web

einherjar/web

The gate is not a barrier. It is the point where the outside world meets order.

code.nochebuena.dev/einherjar/web is the HTTP layer of the Einherjar framework. It sits above core in the dependency graph and provides everything a service needs to receive, process, and respond to HTTP requests: a lifecycle-aware server, a composable middleware stack, type-safe generic handlers, and a concurrent health endpoint.

Sub-packages

All four are in one module because they compose together and ship in every Einherjar HTTP service.

Usage

Tier 1 — Happy path (web.New)

Zero config, safe defaults, all env vars respected:

import (
    "code.nochebuena.dev/einherjar/core/logz"
    "code.nochebuena.dev/einherjar/web"
    "code.nochebuena.dev/einherjar/web/health"
)

logger := logz.New(logz.Config{JSON: true, StaticArgs: []any{"service", "api"}})

srv := web.New(logger)
// Pre-wired stack: Recover → RequestID (UUID v7/v4) → RequestLogger → [CORS]

srv.Get("/health", health.NewHandler(logger, db, cache))

lc := launcher.New(logger)
lc.Append(srv)
lc.BeforeStart(func() error {
    srv.Mount("/v1", myRouter)
    return nil
})
lc.Run()

With origins (CORS auto-applied):

srv := web.New(logger, web.Config{
    Server:         server.Config{Port: 9090},
    AllowedOrigins: []string{"https://example.com"},
})

Environment variables for web.New:

Tier 2 — Full control (server.New)

Explicit middleware composition:

import (
    "code.nochebuena.dev/einherjar/web/mw"
    "code.nochebuena.dev/einherjar/web/server"
)

srv := server.New(logger, server.Config{Port: 9090},
    server.WithMiddleware(
        mw.Recover(),
        mw.RequestID(myIDGenerator),
        mw.CORS([]string{"*"}),
        mw.RequestLogger(logger),
        myOwnMiddleware,
    ),
)

Both tiers share the same server.Config, env variables, and lifecycle.Component contract. The only difference is how much wiring is automated.

Middleware

import "code.nochebuena.dev/einherjar/web/mw"

// Rate limiting — in-memory token bucket (swap for distributed store at scale)
limiter := mw.NewInMemoryRateLimiterStore(100, 20) // rps=100, burst=20
srv.Use(mw.IPRateLimit(limiter, logger))
srv.Use(mw.UserRateLimit(limiter, logger))

// Scale: swap store without changing middleware
// valkeyLimiter := valkeymw.NewRateLimiterStore(valkey, 100, 20) // implements mw.RateLimiterStore
// srv.Use(mw.IPRateLimit(valkeyLimiter, logger))

IPRateLimit uses X-Forwarded-For → RemoteAddr as the rate-limit key. UserRateLimit uses the authenticated user ID from security.Identity; falls back to client IP when no identity is present in context.

Both middlewares fail open on store error — the request is allowed, the error is logged. This keeps the service available when the rate-limit store is degraded.

Generic handlers

import (
    "code.nochebuena.dev/einherjar/core/valid"
    "code.nochebuena.dev/einherjar/web/httputil"
)

type CreateUserReq struct {
    Email string `json:"email" validate:"required,email"`
    Name  string `json:"name"  validate:"required"`
}
type CreateUserRes struct {
    ID string `json:"id"`
}

v := valid.New()

// POST /users — decode body → validate → call service → encode response
srv.Post("/users", httputil.Handle(v, func(ctx context.Context, req CreateUserReq) (CreateUserRes, error) {
    id, err := userService.Create(ctx, req.Email, req.Name)
    if err != nil {
        return CreateUserRes{}, err
    }
    return CreateUserRes{ID: id}, nil
}))

// GET /users/{id} — no request body
srv.Get("/users/{id}", httputil.HandleNoBody(func(ctx context.Context) (CreateUserRes, error) {
    // ...
}))

// DELETE /users/{id} — no response body
srv.Delete("/users/{id}", httputil.HandleEmpty(v, func(ctx context.Context, req DeleteReq) error {
    return userService.Delete(ctx, req.ID)
}))

Validation failures return 400 with a structured JSON error. All *xerrors.Err values are mapped to their canonical HTTP status codes (full 16-code table below).

Health endpoint

import "code.nochebuena.dev/einherjar/web/health"

// db and cache implement observability.Checkable
srv.Get("/health", health.NewHandler(logger, db, cache))

// Response shape:
// {"status":"UP","components":{"db":{"status":"UP","latency":"1.2ms"}}}
// {"status":"DEGRADED","components":{"cache":{"status":"DEGRADED","latency":"50ms","error":"timeout"}}}
// {"status":"DOWN","components":{"db":{"status":"DOWN","latency":"5s","error":"connection refused"}}}

All checks run concurrently within a configurable timeout (default 5s). DOWN (critical priority failure) → HTTP 503. DEGRADED (degraded priority failure) → HTTP 200.

Environment variables:

HTTP Status Code Mapping

httputil.Error maps *xerrors.Err codes to HTTP status:

Dependency Graph

contracts  (zero dependencies)
    ↑
  core     (contracts)
    ↑
  web      (contracts, core, chi/v5, uuid, x/time)
    ↑
  your app

db-*, cache-*, and storage-* starters never import web — they only need contracts and core. Repositories do not know HTTP exists.

Verification

cd web/
go build ./...     # must compile clean
go vet ./...       # no warnings
go test ./...      # structural + behavioural compliance passes
gofmt -l .         # no output

The gate does not decide who passes. It decides that passing has consequences.