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:

Registering readiness checks

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

The ctx passed to the check carries the deadline of the incoming probe request, so the check respects any timeout set by the Kubernetes kubelet.

Example 503 response body:

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

Configuration

srv := httpserver.NewWithConfig(&httpserver.Config{
    Name:            "api",           // component name in logs (default: "httpserver")
    Addr:            ":8080",         // default: ":8080"
    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")