Skip to content

Migration: transport server stack → go/transport

The server side of GTB's transport layer — the HTTP server, the gRPC server and the grpc-gateway — has been extracted into the standalone module gitlab.com/phpboyscout/go/transport (v0.1.1), with http, grpc and gateway sub-packages. It consumes go/controls, go/authn, go/transit, go/tls and go/grpcclient, and never imports go-tool-base or the CLI/config/TUI stack.

This is a clean break, not a facade. Unlike the client extractions (go/httpclient, go/grpcclient) which GTB re-exports, the pure server API is not re-exported from pkg/http/pkg/grpc/pkg/gateway. GTB keeps only the config.Containable adapters — the framework glue that reads a service's config and calls the transport constructors. Code that used the pure server symbols must update its imports.

What stayed in GTB (no change for you)

The config-driven adapters keep their names and behaviour, so a tool that builds its servers from GTB config is unaffected:

  • pkg/http: NewServerFromContainable, StartFromContainable, RegisterFromContainable, ServerSettingsFromConfig, ObserveServerSettingsFromConfig, RateLimitConfigFromConfig, CircuitBreakerConfigFromConfig, and the config-selection options WithConfigPrefix / WithPort. Also still here: the re-exported HTTP client (NewClient, from go/httpclient) and the go/transit HTTP middleware re-exports (NewChain, RateLimitMiddleware, …).
  • pkg/grpc: the same *FromContainable set plus DialLocalFromContainable, WithConfigPrefix/WithPort, and the go/transit gRPC interceptor re-exports (NewInterceptorChain, LoggingInterceptor, …).
  • pkg/gateway: SettingsFromConfig, ObserveSettingsFromConfig, NewFromContainable, NewFromConfig, RegisterFromContainable, RegisterFromConfig, and the adapter's own WithDialOptions / WithMuxOptions / WithMiddleware.

Note: the *FromContainable accessors now return the transport module's ServerSettings type (transporthttp.ServerSettings etc.), not a GTB-local one. If you named that type explicitly, import it from go/transport/http (or /grpc, /gateway).

What moved — repoint these imports

The pure server API moved. Map pkg/http → go/transport/http, pkg/grpc → go/transport/grpc, pkg/gateway → go/transport/gateway:

Was (gitlab.com/phpboyscout/go-tool-base/pkg/…) Now (gitlab.com/phpboyscout/go/transport/…)
http.NewServer, http.Register, http.StartWithTLSPair, http.Stop, http.Status http.NewServer, http.Register, http.StartWithTLSPair, http.Stop, http.Status
http.ServerSettings, http.ServerOption (timeouts/TLS), http.RegisterOption same names under transport/http
http.WithReadTimeout / WithWriteTimeout / WithIdleTimeout / WithMaxHeaderBytes / WithServerTLSConfig / WithMiddleware / WithMaxRequestBodyBytes / MaxBytesMiddleware transport/http
http.HealthHandler / LivenessHandler / ReadinessHandler transport/http
http.AuthMiddleware (+ WithBearerVerifier, …), http.IdentityFromContext transport/http
http.SecurityHeadersMiddleware (+ WithHSTS, WithReferrerPolicy, …) transport/http
grpc.NewServer, grpc.Register, grpc.Start, grpc.Stop, grpc.Status, grpc.RegisterHealthService transport/grpc
grpc.ServerSettings, grpc.WithInterceptors, grpc.TLSServerCredentials, grpc.TLSClientCredentials, grpc.DialLocal transport/grpc
grpc.AuthInterceptor (+ WithGRPCBearerVerifier, …), grpc.IdentityFromContext transport/grpc
gateway.New, gateway.Register, gateway.Settings, gateway.RegisterFunc transport/gateway

The go/transit middleware (Chain, Middleware, NewChain, RateLimitConfig, Interceptor, InterceptorChain, …) is unchanged: GTB still re-exports it from pkg/http/pkg/grpc, and it also lives directly in go/transit.

Notable API change: the config prefix

WithConfigPrefix/WithPort are now GTB options (config selection) and no longer exist in go/transport — the pure server reads no config, so a "config prefix" was meaningless there. Pass gtbhttp.WithConfigPrefix(...) to the *FromContainable adapters as before; when constructing a server from go/transport directly, put the port in ServerSettings{Port: …} (or transport/http.WithPort).

How to migrate

  • Build servers from GTB config? Do nothing — the *FromContainable adapters are unchanged (only the returned ServerSettings type is now the transport module's).
  • Called the pure server API directly? Repoint the import per the table and depend on the module:
go get gitlab.com/phpboyscout/go/[email protected]

import transporthttp "gitlab.com/phpboyscout/go/transport/http"

srv, err := transporthttp.NewServer(ctx, transporthttp.ServerSettings{Port: 8080}, handler)

Notes

  • Full documentation and the server/client split live at transport.go.phpboyscout.uk; the API reference is on pkg.go.dev.
  • This completes the transport-stack extraction programme: go/tls, go/authn, go/observability, go/transit, go/httpclient, go/grpcclient and now go/transport.