web/CHANGELOG.md

# Changelog — einherjar/web

All notable changes to this module are documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
This module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [1.0.1] — 2026-05-28

### Changed

- Bumped `code.nochebuena.dev/einherjar/contracts` dependency from v1.0.0 to v1.1.0.
  No code changes — MVS selects v1.1.0 automatically when a consumer (e.g. `auth`)
  requires the new `SecurityBag` API. This pin makes the minimum explicit.

---

## [1.0.0] — 2026-05-28

### Added

#### `server`

- `Server` interface — embeds `lifecycle.Component` (from `contracts/lifecycle`) and
  `chi.Router` (from `go-chi/chi/v5`); any type that satisfies both is directly
  compatible
- `Config` struct — `Host`, `Port`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout`,
  `ShutdownTimeout`; all fields carry `env:"EINHERJAR_SERVER_*"` and `envDefault`
  tags (`caarlos0/env` syntax)
- `New(logger logging.Logger, cfg Config, opts ...Option) Server` — constructs the
  unexported `impl` struct; embeds `chi.NewRouter()`
- `Option` type + `WithMiddleware(mw ...func(http.Handler) http.Handler) Option` —
  variadic option for middleware composition
- `impl.OnInit()` — applies registered middleware via `chi.Use`
- `impl.OnStart()` — binds TCP listener synchronously (`net.Listen`), starts
  `http.Server.Serve` in a goroutine; port binding failure returns immediately
- `impl.OnStop(ctx)` — graceful `http.Server.Shutdown(ctx)` with `ShutdownTimeout`
  (fallback: `defaultShutdownTimeout = 10s`)
- `var _ Server = (*impl)(nil)` — compile-time assertion

#### `mw`

- `StatusRecorder` struct — wraps `http.ResponseWriter`, captures written status code
- `Recover() func(http.Handler) http.Handler` — catches panics, writes 500, logs
  stack trace via `runtime/debug.Stack()`
- `RequestID(generator func() string) func(http.Handler) http.Handler` — injects a
  request ID via `logz.WithRequestID`; reads existing `X-Request-ID` header if present
- `RequestLogger(logger logging.Logger) func(http.Handler) http.Handler` — structured
  request logging: method, path, status, latency; uses `StatusRecorder` to capture code
- `CORS(origins []string) func(http.Handler) http.Handler` — sets
  `Access-Control-Allow-Origin` for listed origins; supports preflight (`OPTIONS`)
- `CORSAllowAll() func(http.Handler) http.Handler` — shorthand for `CORS([]string{"*"})`
- `RateLimiterStore` interface — `Allow(ctx context.Context, key string) (bool, error)`;
  pluggable backend; `error` return allows infrastructure failures to surface; fail-open
  contract: non-nil error allows the request
- `InMemoryRateLimiterStore` struct — per-key token bucket via `golang.org/x/time/rate`;
  `sync.Map` for concurrent access; background goroutine evicts idle entries after 5
  minutes via `time.Ticker`; `Allow` always returns `(bool, nil)`
- `NewInMemoryRateLimiterStore(rps float64, burst int) *InMemoryRateLimiterStore`
- `IPRateLimit(store RateLimiterStore, logger logging.Logger) func(http.Handler) http.Handler`
  — limits by client IP (`X-Forwarded-For` → `RemoteAddr` fallback); returns 429 JSON
  on exceeded limit; fails open on store error
- `UserRateLimit(store RateLimiterStore, logger logging.Logger) func(http.Handler) http.Handler`
  — limits by authenticated user ID from `security.FromContext`; falls back to client IP
  when no identity present; same 429 + fail-open behaviour

#### `httputil`

- `HandlerFunc` type — `func(w http.ResponseWriter, r *http.Request) error`; implements
  `http.Handler` via `ServeHTTP`
- `Handle[Req, Res any](v valid.Validator, fn func(ctx context.Context, req Req) (Res, error)) http.HandlerFunc`
  — decodes JSON body, validates struct, calls `fn`, encodes response; 400 on validation
  failure, mapped status on `*xerrors.Err`
- `HandleNoBody[Res any](fn func(ctx context.Context) (Res, error)) http.HandlerFunc`
  — no body decoding/validation; encodes response directly
- `HandleEmpty[Req any](v valid.Validator, fn func(ctx context.Context, req Req) error) http.HandlerFunc`
  — decodes and validates body, calls `fn`, returns 204 on success
- `JSON(w http.ResponseWriter, status int, v any)` — writes JSON response
- `NoContent(w http.ResponseWriter)` — writes 204 with no body
- `Error(w http.ResponseWriter, err error)` — maps `*xerrors.Err` to HTTP status and
  writes `{"code":"<wire_value>","message":"<msg>"}` JSON body; complete 16-code mapping

#### `health`

- `Config` struct — `CheckTimeout time.Duration` with
  `env:"EINHERJAR_HEALTH_CHECK_TIMEOUT" envDefault:"5s"` (`caarlos0/env` syntax)
- `Response` struct — `Status string`, `Components map[string]ComponentStatus`
- `ComponentStatus` struct — `Status`, `Latency` (omitempty), `Error` (omitempty)
- `NewHandler(logger logging.Logger, checks ...observability.Checkable) http.Handler`
  — shorthand with default 5s timeout
- `NewHandlerWithConfig(logger logging.Logger, cfg Config, checks ...observability.Checkable) http.Handler`
  — all checks run concurrently in goroutines with a shared context timeout; results
  collected via buffered channel; `DOWN` (critical priority) → 503; `DEGRADED`
  (degraded priority) → 200; `UP` → 200
- Accepts `observability.Checkable` from `contracts` directly — no local redefinition

#### Root package (`web`)

- `Config` struct — `Server server.Config`, `AllowedOrigins []string` with
  `env:"EINHERJAR_SERVER_CORS_ORIGINS" envSeparator:","`
- `New(logger logging.Logger, cfg ...Config) server.Server` — pre-wires recommended
  middleware stack: Recover → RequestID (UUID v7 with v4 fallback) → RequestLogger →
  CORS (only when `AllowedOrigins` non-empty)
- Unexported `newRequestID()` — uses `uuid.NewV7()` (time-ordered), falls back to
  `uuid.NewString()` (v4) on generation error

### Design Notes

1. **Progressive disclosure.** `web.New` is the happy path — one call, all middleware
   pre-wired, env vars respected. `server.New` is the escape hatch — every choice
   explicit. Both tiers share the same config structs, env variables, and lifecycle
   contract.

2. **`RateLimiterStore` interface.** The pluggable backend design lets developers start
   with `InMemoryRateLimiterStore` (zero extra dependencies) and swap to a distributed
   store (e.g., `cache-valkey`) at scale without touching middleware wiring. The store
   satisfies the interface via Go duck typing — `cache-valkey` never imports `web/mw`.

3. **Fail-open rate limiting.** When the store returns an error (e.g., Valkey
   unavailable), the request is allowed. Availability is preferred over hard
   enforcement during infrastructure degradation.

4. **`observability.Checkable` from contracts.** `health.NewHandler` accepts
   `observability.Checkable` directly from `contracts/observability`. Any starter
   (`db-*`, `cache-*`, `storage-*`) that implements the contracts interface plugs in
   without an adapter — no `web` import required by those starters.

5. **`last_seen` excluded.** Session tracking is an application-domain concern, not
   transport-level middleware. It requires knowing which entity to track and where to
   persist it. Developers who need it can write it in ~15 lines in their own wiring
   package. Will be revisited if `einherjar/worker` provides a fire-and-forget
   primitive.

6. **UUID v7 for request IDs.** Time-ordered UUIDs embed a millisecond-precision
   timestamp, enabling request IDs to sort chronologically in log aggregation systems.
   UUID v4 fallback ensures ID generation never fails.

---

[1.0.0]: https://code.nochebuena.dev/einherjar/web/releases/tag/v1.0.0