feat: route dynamic servers through managed Via

Route API-registered Gate servers through managed Via using vialite v0.2.8 dynamic backends. Preserve custom ServerDialer backends such as Connect through a local bridge, clean up dynamic Via resources, and document dynamic Via behavior.

Author: robinbraemer

.web/docs/guide/compatibility.md

@@ -14,6 +14,26 @@ Gate provides excellent support for **modded servers** including Fabric and NeoF
 Gate is compatible with Minecraft 1.8 through the latest version
 and we maintainers update Gate as soon as a new Minecraft version is released.
 
+## Java Version Translation
+
+Gate can run managed Via translation in classic proxy mode. When `config.via.enabled`
+is true, Gate starts vialite, keeps it on the latest stable release by default,
+and routes backend connections through Via-compatible protocol translation.
+This applies to both configured servers and API-registered servers, so dynamic
+Connect/session backends can be joined by Java clients even when the backend
+Minecraft version differs from the client version.
+
+```yaml
+config:
+  via:
+    enabled: true
+```
+
+Lite mode does not run managed Via translation. Dynamic API-registered backend
+translation uses the default subprocess mode; embedded mode is limited to
+configured servers. For controlled deployments, Gate still supports exact
+vialite version pins, offline mode, and local artifact paths.
+
 ## Paper <VPBadge>Recommended</VPBadge>
 
 We highly recommend using [Paper](https://papermc.io/) for running a server in most cases.

README.md

@@ -63,8 +63,8 @@ graph LR
 ## Java Version Compatibility
 
 Gate can start **Via-powered backend protocol translation** through managed
-vialite, so Java clients can join backend servers running different Minecraft
-versions without running a separate Via sidecar.
+vialite, so Java clients can join configured or API-registered backend servers
+running different Minecraft versions without running a separate Via sidecar.
 
 Enable managed Via in classic proxy mode with:
 
@@ -76,9 +76,13 @@ config:
 
 Gate starts the native vialite subprocess, resolves the latest stable vialite
 release automatically, downloads the checksummed artifact into the local cache,
-and routes backend connections through it. Exact release pins, offline mode, and
-local artifact paths remain available for controlled deployments, but no manual
-version setting is required for the default path.
+and routes backend connections through it. Dynamic backends registered through
+Gate's Go API are added to vialite at runtime, which lets Connect-style session
+backends use the same version compatibility path as static config servers. Exact
+release pins, offline mode, and local artifact paths remain available for
+controlled deployments, but no manual version setting is required for the
+default path. Dynamic API-registered backend translation uses the default
+subprocess mode; embedded mode is limited to configured servers.
 
 ## Gate Lite Mode
 

config.yml

@@ -95,12 +95,13 @@ config:
     # Can also be set via environment variable: GATE_BUNGEEGUARD_SECRET
     #bungeeGuardSecret: secret_here
   # Via backend protocol translation for Gate classic mode.
-  # This starts vialite at startup and routes configured classic backend connections
-  # through Via-compatible translation before Gate dials the backend.
+  # This starts vialite at startup and routes configured or API-registered classic
+  # backend connections through Via-compatible translation before Gate dials the backend.
   # Not used in lite mode. Changes require a Gate restart.
   via:
     enabled: false
     # Options: subprocess, embedded. Subprocess uses released vialite artifacts and is the default.
+    # API-registered dynamic backends use subprocess mode; embedded mode only translates configured servers.
     mode: subprocess
     # Optional local bind for the native runtime's internal loopback listener.
     #bind: 127.0.0.1:0

go.mod

@@ -35,7 +35,7 @@ require (
 	go.minekube.com/common v0.3.0
 	go.minekube.com/connect v0.6.2
 	go.minekube.com/geyserlite v0.3.14
-	go.minekube.com/vialite v0.2.7
+	go.minekube.com/vialite v0.2.8
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0
 	go.opentelemetry.io/otel v1.41.0
 	go.opentelemetry.io/otel/metric v1.41.0

go.sum

@@ -254,8 +254,8 @@ go.minekube.com/connect v0.6.2 h1:RajPc7YgqygcOviV2g4xetL3J0Wzi8b/lsYXUzIltxE=
 go.minekube.com/connect v0.6.2/go.mod h1:28k11I4RyzUfAL3AkOXt3atzjeOFAC8eqbCMwsYKAb0=
 go.minekube.com/geyserlite v0.3.14 h1:+cSN9o/b5jEOHeym/uXvt5MEoGnrYloJidrVe9K9pWo=
 go.minekube.com/geyserlite v0.3.14/go.mod h1:yy0/M0zSD6X3FoQMwtmf5Jn+7YFM7AZWamKw0E8fnOE=
-go.minekube.com/vialite v0.2.7 h1:G5OuIt0qN4xfowW2rahZhb8zzMark5nI6AqubVBn6gQ=
-go.minekube.com/vialite v0.2.7/go.mod h1:W9L1l8/b/GsLmkw1BW4wijaaPj/zV3OdrtYJgWdkhxE=
+go.minekube.com/vialite v0.2.8 h1:3xEuciKORVeuDdCOY6w2BSnenVYti0ZS8xlqCUX42nk=
+go.minekube.com/vialite v0.2.8/go.mod h1:W9L1l8/b/GsLmkw1BW4wijaaPj/zV3OdrtYJgWdkhxE=
 go.opencensus.io v0.18.0/go.mod h1:vKdFvxhtzZ9onBp9VKHK8z/sRpBMnKAsufL7wlDrCOA=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=

pkg/configs/config.yml

@@ -95,12 +95,13 @@ config:
     # Can also be set via environment variable: GATE_BUNGEEGUARD_SECRET
     #bungeeGuardSecret: secret_here
   # Via backend protocol translation for Gate classic mode.
-  # This starts vialite at startup and routes configured classic backend connections
-  # through Via-compatible translation before Gate dials the backend.
+  # This starts vialite at startup and routes configured or API-registered classic
+  # backend connections through Via-compatible translation before Gate dials the backend.
   # Not used in lite mode. Changes require a Gate restart.
   via:
     enabled: false
     # Options: subprocess, embedded. Subprocess uses released vialite artifacts and is the default.
+    # API-registered dynamic backends use subprocess mode; embedded mode only translates configured servers.
     mode: subprocess
     # Optional local bind for the native runtime's internal loopback listener.
     #bind: 127.0.0.1:0

pkg/edition/java/proxy/proxy.go

@@ -496,10 +496,39 @@ func (p *Proxy) Register(info ServerInfo) (RegisteredServer, error) {
 	name := strings.ToLower(info.Name())
 
 	p.muS.Lock()
-	defer p.muS.Unlock()
 	if exists, ok := p.servers[name]; ok {
+		p.muS.Unlock()
+		return exists, ErrServerAlreadyExists
+	}
+	p.muS.Unlock()
+
+	var viaAdded bool
+	if _, alreadyVia := info.(*viaServerInfo); !alreadyVia && p.via != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		enabled, err := p.via.AddBackend(ctx, info)
+		if err != nil {
+			return nil, fmt.Errorf("error adding via backend %q: %w", info.Name(), err)
+		}
+		if enabled {
+			viaAdded = true
+			info = newViaServerInfo(info, p.via)
+		}
+	}
+
+	p.muS.Lock()
+	if exists, ok := p.servers[name]; ok {
+		p.muS.Unlock()
+		if viaAdded {
+			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			defer cancel()
+			if err := p.via.RemoveBackend(ctx, info.Name()); err != nil {
+				p.log.Error(err, "could not remove duplicate via backend", "server", info.Name())
+			}
+		}
 		return exists, ErrServerAlreadyExists
 	}
+	defer p.muS.Unlock()
 	rs := newRegisteredServer(info)
 	p.servers[name] = rs
 	// Note: We don't mark API-registered servers as config-managed
@@ -528,6 +557,13 @@ func (p *Proxy) Unregister(info ServerInfo) bool {
 	}
 	delete(p.servers, name)
 	delete(p.configServers, name) // Clean up config tracking
+	if p.via != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		if err := p.via.RemoveBackend(ctx, info.Name()); err != nil {
+			p.log.Error(err, "could not remove via backend", "server", info.Name())
+		}
+	}
 
 	p.log.Info("unregistered backend server",
 		"name", info.Name(), "addr", info.Addr())