feat(web): initial implementation — server, mw, httputil, health (v1.0.0)

Introduces code.nochebuena.dev/einherjar/web — the HTTP transport layer of the
Einherjar framework. Absorbs httpserver, httpmw, and httputil from micro-lib,
replacing gorilla/mux with chi, adopting SecurityBag-native middleware, and
centralizing error handling through a single httputil.Error function.

server:
- Server interface — embeds lifecycle.Component and chi.Router
- Config struct (EINHERJAR_SERVER_* env vars); DefaultConfig
- New(logger, cfg, opts...) Server; WithMiddleware option
- Binds TCP synchronously in OnStart; logs "server: listening" on success
- Graceful shutdown within ShutdownTimeout on OnStop

mw:
- Recover — catches panics, returns 500, logs at Error
- RequestID — injects UUID v7 (UUID v4 fallback) into context and X-Request-ID header
- RequestLogger — structured access log per request
- CORS / CORSAllowAll — chi-based, applied only when origins non-empty
- IPRateLimit / UserRateLimit — pluggable RateLimiterStore interface
- InMemoryRateLimiterStore — token-bucket backed by golang.org/x/time/rate;
  background goroutine evicts stale entries every 5 minutes
- StatusRecorder — wraps ResponseWriter to capture HTTP status code

httputil:
- Handle[Req, Res] / HandleNoBody[Res] / HandleEmpty[Req] — generic handler adapters
- Error(logger, w, r, err) — derives log level from status (≥500→Error, 4xx→Warn,
  499→Info); writes standardized JSON body; logz enriches *xerrors.Err automatically
- JSON(w, status, v) / NoContent(w) — response helpers
- HandlerFunc adapter type

health:
- NewHandler / NewHandlerWithConfig — runs all Checkable checks concurrently;
  returns JSON {status, components} with per-component latency and error
- Config struct (EINHERJAR_HEALTH_CHECK_TIMEOUT, default 5s)

Root factory:
- web.New(logger, cfg...) Server — composes Recover+RequestID+RequestLogger+CORS
  in outermost-first order; CORS applied only when AllowedOrigins non-empty

- server.Server interface and web/server/identifiable.go: embeds observability.Identifiable;
  ModulePath and ModuleVersion read via runtime/debug.ReadBuildInfo() — prints in launcher banner
This commit is contained in:
2026-05-29 15:48:11 +00:00
commit c4ef1948f6
38 changed files with 3095 additions and 0 deletions

51
server/doc.go Normal file
View File

@@ -0,0 +1,51 @@
// Package server provides a lifecycle-aware HTTP server for Einherjar services.
//
// [Server] embeds both [lifecycle.Component] and [chi.Router], so it plugs
// directly into [launcher.New] and exposes the full chi routing API.
//
// For the happy path use [web.New], which pre-wires the recommended middleware
// stack. Use this package directly when you need explicit control over
// middleware order, a custom request-ID generator, or any other deviation from
// the defaults.
//
// # Basic usage
//
// srv := server.New(logger, server.Config{Port: 8080},
// server.WithMiddleware(
// mw.Recover(),
// mw.RequestID(myIDGenerator),
// mw.RequestLogger(logger),
// mw.CORS([]string{"https://example.com"}),
// ),
// )
//
// srv.Get("/health", health.NewHandler(logger, db))
//
// lc := launcher.New(logger)
// lc.Append(srv)
// lc.BeforeStart(func() error {
// srv.Mount("/v1", apiRouter)
// return nil
// })
// if err := lc.Run(); err != nil {
// logger.Error("launcher failed", err)
// os.Exit(1)
// }
//
// # Lifecycle
//
// [Server.OnInit] applies registered middleware to the router.
// [Server.OnStart] binds the TCP listener synchronously — a port conflict
// surfaces immediately rather than silently dropping the server. Requests
// are served in a background goroutine.
// [Server.OnStop] performs a graceful shutdown within [Config.ShutdownTimeout].
//
// # Environment variables
//
// EINHERJAR_SERVER_HOST=0.0.0.0 bind address (default 0.0.0.0)
// EINHERJAR_SERVER_PORT=8080 listen port (default 8080)
// EINHERJAR_SERVER_READ_TIMEOUT=5s HTTP read timeout (default 5s)
// EINHERJAR_SERVER_WRITE_TIMEOUT=10s HTTP write timeout (default 10s)
// EINHERJAR_SERVER_IDLE_TIMEOUT=120s keep-alive idle timeout (default 120s)
// EINHERJAR_SERVER_SHUTDOWN_TIMEOUT=10s graceful shutdown budget (default 10s)
package server