transport

README

transport

A framework-free HTTP + gRPC + gateway server stack for Go — hardened server constructors, health endpoints, authentication and security headers

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Docs: transport.go.phpboyscout.uk

---

gitlab.com/phpboyscout/go/transport is the server half of the transport stack extracted from go-tool-base: a secure, lifecycle-managed HTTP and/or gRPC server — health probes, TLS, authentication and security headers wired in — without a CLI framework in tow. Three composable sub-packages:

• transport/http — hardened *http.Server, health/liveness/readiness handlers, AuthMiddleware, SecurityHeadersMiddleware, controls lifecycle glue.
• transport/grpc — hardened *grpc.Server, health service, AuthInterceptor, TLS credentials, DialLocal, lifecycle glue.
• transport/gateway — a grpc-gateway exposing a gRPC service over REST/JSON.

Install

go get gitlab.com/phpboyscout/go/transport

Quick start

import (
	"context"
	"net/http"

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

mux := http.NewServeMux()
mux.HandleFunc("/healthz", transporthttp.HealthHandler(reporter))

srv, err := transporthttp.NewServer(
	context.Background(),
	transporthttp.ServerSettings{Port: 8080},
	mux,
)

Design

• Framework-free. Depends on go/controls, go/authn, go/transit, go/tls, go/grpcclient, the gRPC SDK and the grpc-gateway runtime — but not go-tool-base or the CLI/config/TUI stack. A depfootprint_test.go guard forbids go-tool-base, Viper/Cobra/Charm and the cloud SDKs.
• Secure by default. Hardened TLS and timeouts, health endpoints outside the auth chain, security headers, credential-redacting auth.
• Middleware is transit's. Logging, OpenTelemetry, circuit breaking and rate limiting are the go/transit server middleware; this stack composes them via a Chain / InterceptorChain.
• Clean framework seam. The pure server API lives here; the *FromContainable config adapters stay in go-tool-base and call into this module.

Compatibility

go/controls, go/authn, go/transit, go/tls and go/grpcclient versions are pinned and kept in lockstep with go-tool-base. Grouped Renovate updates keep them aligned.

Documentation

Guides and the design model: transport.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.

Documentation

Overview

Package transport is the umbrella for go-tool-base's extracted server-side transport stack. It has no exported symbols of its own; the functionality lives in the sub-packages:

• gitlab.com/phpboyscout/go/transport/http — the hardened HTTP server: health/liveness/readiness handlers, the secure server constructor, request authentication, security headers, and lifecycle glue.
• gitlab.com/phpboyscout/go/transport/grpc — the gRPC server: the secure server constructor, health service, RPC authentication, TLS credentials, local dialling, and lifecycle glue.
• gitlab.com/phpboyscout/go/transport/gateway — the grpc-gateway that exposes a gRPC service over REST/JSON.

The middleware these servers compose (logging, OpenTelemetry, circuit breaking, rate limiting) lives in gitlab.com/phpboyscout/go/transit and is consumed, not re-exported. TLS material comes from gitlab.com/phpboyscout/go/tls, authentication from gitlab.com/phpboyscout/go/authn, and service lifecycle from gitlab.com/phpboyscout/go/controls. The module is framework-free: it never imports go-tool-base or the CLI/config/TUI stack, a boundary enforced by a dependency-footprint test.