httpserver

httpserver

Package httpserver provides an HTTP server that implements app.Component, plugging into the app.App lifecycle for managed startup and graceful shutdown.

Quick start

mux := http.NewServeMux()
mux.HandleFunc("GET /api/projects", listProjects)
mux.HandleFunc("GET /api/projects/{id}", getProject)

srv := httpserver.NewWithConfig(&httpserver.Config{
    Addr:    ":8080",
    Logger:  a.Logger(),
    Tracer:  a.Tracer(),
    Handler: mux,
})

a.Register(srv)

Pass the server to app.App.Register and it will start when app.Start is called and drain in-flight requests when app.Shutdown is called.

Routing

LabKit does not own the routing layer. Consumers bring their own router and pass it as Config.Handler. Any http.Handler works:

• Standard library http.ServeMux (Go 1.22+): supports method-based routing (GET /path) and path parameters (/items/{id}). Sufficient for most services.
• chi: recommended when you need route grouping, scoped middleware, or sub-router mounting. Zero external dependencies, http.Handler throughout.
• Any other http.Handler: the Server wraps whatever you provide with built-in middleware.

Standard library example

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", getUser)
mux.HandleFunc("POST /users", createUser)

srv := httpserver.NewWithConfig(&httpserver.Config{
    Handler: mux,
})

chi example

r := chi.NewRouter()
r.Use(requireAuth)
r.Get("/users/{id}", getUser)
r.Route("/api/v2", func(r chi.Router) {
    r.Get("/projects", listProjects)
})

srv := httpserver.NewWithConfig(&httpserver.Config{
    Handler: r,
})

Path parameters

mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := httpserver.URLParam(r, "id")
    // ...
})

URLParam uses r.PathValue() (Go 1.22+), which works with both the standard library and chi v5.1+.

Built-in middleware

When Logger and Tracer are set, two middleware layers wrap the handler automatically:

Middleware is applied in the order listed above (tracing outermost, logging innermost). The trace span covers the full request including the log write.

Low-cardinality span names

By default, span names use the concrete URL path (e.g. GET /users/42). For low-cardinality names, set the route pattern via SetRoutePattern in a router-specific middleware:

// Example for chi:
func chiRoutePattern(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        next.ServeHTTP(w, r)
        rctx := chi.RouteContext(r.Context())
        if rctx != nil {
            r = r.WithContext(httpserver.SetRoutePattern(r.Context(), rctx.RoutePattern()))
        }
    })
}

Health endpoints

Two endpoints are available on every server without any registration:

Liveness

/-/liveness always returns 200 OK. It confirms the process is running and has not deadlocked. It does not test any dependencies and never should — a liveness failure causes Kubernetes to restart the container, which cannot fix an unavailable database.

Startup

Kubernetes disables liveness and readiness probes until the startup probe succeeds. This makes startup probes the right solution for services with slow or unpredictable startup times — loading large config, warming a connection pool, waiting for an init container. Without a startup probe, you must set initialDelaySeconds as a rough guess; too low causes false restarts, too high slows rollouts.

Use /-/readiness as the startup probe endpoint. It returns 503 until the process is up and checks pass, then 200, unlocking liveness and readiness probing. /-/liveness is not suitable here because it always returns 200, so it provides no startup gate.

Set failureThreshold generously so that failureThreshold × periodSeconds covers your worst-case startup time:

startupProbe:
  httpGet:
    path: /-/readiness
    port: 9090             # dedicated probe port
  periodSeconds: 5
  failureThreshold: 24   # 24 × 5s = 2 minutes of startup grace

Once a startup probe is configured, remove initialDelaySeconds from liveness and readiness probes as it becomes redundant.

If your startup checks genuinely differ from ongoing readiness checks (for example, verifying a database migration ran once at boot but not on every poll), register a custom endpoint on your http.ServeMux and point the startup probe at that instead.

Readiness

/-/readiness runs every registered check concurrently and returns 200 when all pass or 503 when one or more fail.

Registering checks

srv.AddReadinessCheck("database", func(ctx context.Context) error {
    return db.PingContext(ctx)
})

The ctx passed to each check carries the deadline of the incoming probe request, so checks respect any timeout configured in the Kubernetes probe spec.

Example 503 response body:

{
  "status": "error",
  "checks": {
    "database": "dial tcp: connection refused",
    "redis": "ok"
  }
}

Writing safe readiness checks

Readiness means "this pod can serve traffic right now" — not "all my dependencies are healthy".

Kubernetes uses the readiness state to decide whether to route requests to a pod. A failing readiness check removes the pod from the load balancer; it does not restart the container.

Serving probes on a dedicated port (:9090 by default, separate from the application port) means your operational endpoints can be restricted to internal cluster traffic in your ingress or network policy without affecting application routing.

What to check

The only things the pod itself controls:

• Process finished initialising (configuration loaded, connection pool warmed up)
• A primary dependency that every handler requires and without which the pod genuinely cannot serve any request (see below)

What not to check

Shared external dependencies whose failure should not pull the pod from rotation:

• Caches (Redis, Memcached)
• Feature flag services
• Optional third-party APIs
• Downstream services

If a non-critical dependency is unavailable, the pod should keep serving traffic and return appropriate errors at the request level.

The cascading failure pattern

Checking a shared dependency creates a correlated failure mode:

1. The dependency experiences a transient blip
2. Every pod's readiness check fails at the same time
3. All pods are removed from the load balancer simultaneously
4. The remaining pods absorb the full traffic load and also start failing
5. The dependency recovers in seconds; the incident runs for minutes

If you must check a critical dependency

Some services cannot serve any request without a specific dependency (for example, a primary database that every handler queries). If you include such a check:

• Keep it lightweight — a connection PING, not a query
• Always honour the context deadline passed to CheckFunc; it carries the probe timeout
• Tune the Kubernetes probe to tolerate transient failures (see below)

Kubernetes probe configuration

readinessProbe:
  httpGet:
    path: /-/readiness
    port: 9090               # dedicated probe port — never exposed externally
  initialDelaySeconds: 10    # allow the process to finish starting
  periodSeconds: 10          # how often to probe
  timeoutSeconds: 5          # count as a failure if no response within 5s
  failureThreshold: 3        # require 3 consecutive failures before removing from load balancer
  successThreshold: 1        # one success restores traffic

• failureThreshold — do not evict on a single failure. Three consecutive failures at periodSeconds: 10 gives 30 seconds of tolerance for transient blips.
• timeoutSeconds — must exceed the maximum expected response time of your check. The Kubernetes default of 1s is too short for any check that touches a real dependency.
• initialDelaySeconds — set based on actual startup time; too low causes false failures during rollout.

Liveness probes

Liveness failures restart the container — the right response to a deadlocked process, but the wrong response to a temporarily unavailable database. Restarting a pod that cannot reach its database changes nothing and adds unnecessary connection churn.

Never check external dependencies in a liveness probe. Liveness should only detect unrecoverable internal failure: a deadlock, a failed background goroutine, or a sentinel condition that only a restart can fix.

Configuration

srv := httpserver.NewWithConfig(&httpserver.Config{
    Name:            "api",           // component name in logs (default: "httpserver")
    Addr:            ":8080",         // default: ":8080"
    ProbeAddr:       ":9090",         // default: ":9090" — serves /-/liveness, /-/readiness, /-/metrics
    ReadTimeout:     5 * time.Second, // default: 5s
    WriteTimeout:   10 * time.Second, // default: 10s
    IdleTimeout:    60 * time.Second, // default: 60s
    ShutdownTimeout: 30 * time.Second, // default: 30s
    Logger:          a.Logger(),
    Tracer:          a.Tracer(),
    Handler:         mux,
})

Use Addr: ":0" to let the OS pick a free port, then read it back with srv.Addr() after Start. This is the recommended pattern in tests.

Multiple servers (e.g. a public API and an internal admin server) can be registered independently by giving each a distinct Name and Addr:

api   := httpserver.NewWithConfig(&httpserver.Config{Name: "api",   Addr: ":8080", Handler: apiMux})
admin := httpserver.NewWithConfig(&httpserver.Config{Name: "admin", Addr: ":9090", Handler: adminMux})
a.Register(api)
a.Register(admin)

Testing

Server implements http.Handler, so tests can call ServeHTTP directly without binding a real port:

func TestListUsers(t *testing.T) {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users", listUsersHandler)

    srv := httpserver.NewWithConfig(&httpserver.Config{Handler: mux})

    req := httptest.NewRequest(http.MethodGet, "/users", nil)
    rec := httptest.NewRecorder()
    srv.ServeHTTP(rec, req)

    assert.Equal(t, http.StatusOK, rec.Code)
}

To test with a live port (e.g. for integration tests), use Addr: ":0" and call Start:

mux := http.NewServeMux()
mux.HandleFunc("GET /ping", pingHandler)

srv := httpserver.NewWithConfig(&httpserver.Config{Addr: ":0", Handler: mux})

require.NoError(t, srv.Start(ctx))
defer srv.Shutdown(ctx)

resp, err := http.Get("http://" + srv.Addr() + "/ping")