Skip to content

Getting started

This tutorial stands up a hardened HTTP server with health endpoints, then adds a gRPC server alongside it — enough to see what the stack wires for you.

Install

go get gitlab.com/phpboyscout/go/transport

A health-checked HTTP server

transport/http builds a hardened *http.Server from typed ServerSettings, and gives you ready-made health/liveness/readiness handlers that report from a go/controls health source:

package main

import (
    "context"
    "net/http"

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", transporthttp.HealthHandler(reporter))    // controls.HealthReporter
    mux.HandleFunc("/livez", transporthttp.LivenessHandler(reporter))
    mux.HandleFunc("/readyz", transporthttp.ReadinessHandler(reporter))

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

    _ = srv // hand to go/controls, or srv.ListenAndServe()
}

NewServer sets bounded read/write/idle timeouts and a hardened TLS config; health endpoints are plain handlers you mount outside any auth middleware, so probes are never gated by authentication.

Run it under the lifecycle

The server is designed to be driven by go/controls. Register wires construction, health, and graceful shutdown into a supervised service in one call:

import (
    gtls "gitlab.com/phpboyscout/go/tls"
    transporthttp "gitlab.com/phpboyscout/go/transport/http"
)

srv, err := transporthttp.Register(
    ctx, "api", controller, logger,      // controls.Controllable + *slog.Logger
    transporthttp.ServerSettings{Port: 8080},
    gtls.Pair{},                          // disabled ⇒ plain HTTP; enabled ⇒ TLS
    handler,
    transporthttp.WithMiddleware(chain),  // a go/transit server Chain (optional)
)

Add a gRPC server

transport/grpc mirrors the shape for gRPC — a secure *grpc.Server, a built-in health service, and the same lifecycle glue:

import transportgrpc "gitlab.com/phpboyscout/go/transport/grpc"

srv, err := transportgrpc.NewServer(transportgrpc.ServerSettings{Port: 9090, Reflection: true})
if err != nil {
    panic(err)
}

transportgrpc.RegisterHealthService(srv, reporter)
// pb.RegisterYourServiceServer(srv, impl)

start := transportgrpc.Start(logger, srv, transportgrpc.ServerSettings{Port: 9090}, gtls.Pair{})
_ = start // a controls.StartFunc

Where next