Skip to content

Migrating from v0.5 to v0.6

v0.6 adds first-class support for building web services: a shared pkg/tls package, grpc.DialLocal for in-process clients, a configurable second HTTP server, a first-class grpc-gateway (pkg/gateway), and an OpenAPI + Stoplight docs server (pkg/openapi).

There is one breaking change: the hardened TLS configuration and its resolution moved out of pkg/http into a dedicated pkg/tls package, so that pkg/grpc no longer depends on pkg/http for TLS. Projects that only use http.Register / grpc.Register (the scaffolded default) are unaffected — the helpers are wired internally. Only code that called the exported TLS functions directly needs to change.

Breaking Changes

Shared TLS moved from pkg/http to pkg/tls

Packages affected: direct callers of pkg/http's DefaultTLSConfig or ResolveTLSConfig.

http.DefaultTLSConfig() and http.ResolveTLSConfig() have been removed. Their replacements live in pkg/tls, and resolution now returns a typed tls.Pair instead of a (bool, string, string) tuple.

Removed (pkg/http) Replacement (pkg/tls)
http.DefaultTLSConfig() tls.DefaultConfig()
http.ResolveTLSConfig(cfg, prefix) (bool, string, string) tls.Resolve(cfg, prefix) tls.Pair

Before:

import gtbhttp "gitlab.com/phpboyscout/go-tool-base/pkg/http"

cfg := gtbhttp.DefaultTLSConfig()

enabled, cert, key := gtbhttp.ResolveTLSConfig(props.Config, "server.http.tls")
if enabled {
    // ... use cert, key
}

After:

import gtbtls "gitlab.com/phpboyscout/go-tool-base/pkg/tls"

cfg := gtbtls.DefaultConfig()

pair := gtbtls.Resolve(props.Config, "server.http.tls")
if pair.Enabled {
    // ... use pair.Cert, pair.Key
}

Migration:

  1. Replace the import pkg/http (for TLS) with pkg/tls.
  2. DefaultTLSConfig() → DefaultConfig().
  3. ResolveTLSConfig(cfg, prefix) → Resolve(cfg, prefix), and read the .Enabled, .Cert and .Key fields of the returned Pair instead of the three return values.

The cipher suites, curve preferences and minimum version are unchanged — only the package and the resolution return type differ.

New Features

pkg/tls — shared, typed TLS

tls.Pair{Enabled, Cert, Key} is the typed config shape used by every transport, with tls.Resolve applying the shared server.tls defaults plus per-transport overrides. tls.CertPool and tls.ClientConfig provide client-side trust for self-signed or private-CA certificates. See TLS.

grpc.DialLocal and grpc.TLSClientCredentials

grpc.DialLocal(cfg) dials the local gRPC server with transport security that matches the server's own config — the connection a grpc-gateway needs in one call. grpc.TLSClientCredentials(caFiles...) is the client-side mirror of TLSServerCredentials. See gRPC.

The gRPC TLS listener now advertises HTTP/2 via ALPN (h2), which grpc-go 1.67+ clients require; this was previously missing and is fixed automatically on the Register / Start path.

http.WithConfigPrefix

http.Register(..., http.WithConfigPrefix("server.gateway")) lets a second HTTP server read its own port and TLS config block, falling back to the shared server.port / server.tls. See HTTP.

pkg/gateway — grpc-gateway as a transport

gateway.New returns a mountable handler; gateway.Register runs the gateway as its own controller-managed HTTP server on server.gateway.*. See Gateway.

pkg/openapi — spec + embedded Stoplight docs

openapi.Register(mux, spec) serves an OpenAPI document and an embedded Stoplight Elements docs site. See OpenAPI.