Skip to content

HOG v2.0.0

HOG v2 is a ground-up rewrite on Go 1.26 and the standard library. It is a single, composable application gateway that serves your frontend and acts as its backend-for-frontend (BFF) and API gateway. It is no longer a fork of KrakenD — v2 drops that lineage for a lean, idiomatic, standard-library-first design with its own architecture, configuration model, and extension system.

Highlights

  • One binary, two jobs. A traversal-safe static web server (a drop-in in front of a single-page app) and a full BFF/API gateway, in one static Go binary.
  • Kubernetes-style configuration. Declarative YAML resources (Gateway, Route, RouteGroup, Policy) with ${ENV} interpolation and label selectors — GitOps friendly.
  • BFF authentication. OpenID Connect login with PKCE; the session lives in an encrypted cookie that never reaches your backends. API clients authenticate with a bearer token.
  • Backend mapping and aggregation. Reverse-proxy a route to one upstream, or fan out an api route to several backends and merge their responses.
  • Authorization. Built-in group and claim rules plus embedded OPA/Rego policies, applied per route or route group. Additive, deny-overrides, fail-closed.
  • Observability. Opt-in OpenTelemetry traces and metrics over OTLP, W3C context propagation, and a trace-correlated access log.
  • Compile-time extensibility. Extend HOG with Go plugins compiled in at build time — no fragile .so loading. Ship with hog-build or the batteries-included images.
  • Secure by default. Non-root, read-only-friendly container images; fail-closed authorization; strict credential hygiene.

What's new

Core spine

  • Two gateway-wide edge layers — forwarded (trusted-proxy header normalization) and security (CSRF + response headers) — wrap the entire handler outermost, covering every route and the raw /auth/* endpoints alike.
  • A fixed per-route middleware chain — recover → request-id → access-log → session → auth-gate → authz → projection → terminal — with guarded slots that activate only when configured.
  • A compile-time module registry: every feature (built-in or plugin) registers under a kind + name and is built by name from config. HOG's own features use the same contract third-party plugins use.
  • A Kubernetes-style resource model (kind/metadata/spec), ${ENV} expansion, and multi-document YAML files and directories.

Static web server

  • A traversal-safe static file server built on os.Root, with single-page-app fallback, dotfile protection, and configurable cache-control.

BFF authentication and sessions

  • OpenID Connect connector (PKCE, UserInfo) over coreos/go-oidc.
  • Encrypted, fingerprinted session cookie with SameSite=Lax (chosen so the OAuth redirect completes) and domain-separated sealing.
  • Browser login, callback, and logout endpoints with open-redirect-safe return_to.
  • Bearer-token authentication for non-browser API clients.
  • Enforcement gates: session resolution, an auth gate (302 for browsers, 401 for APIs), and identity projection that injects X-User-* headers into backend requests and strips inbound spoofs.
  • A pluggable session state provider for deployments that need shared state.

Backend mapping

  • A reverse-proxy terminal built on httputil.ReverseProxy: path rewriting, host control, per-route timeouts (502 on failure, 504 on timeout), and connection pooling.
  • An api terminal that fans out to multiple backends concurrently and merges their JSON under group keys, with partial-response handling (X-Hog-Partial).
  • Identity forwarding to backends, optional Authorization: Bearer injection in BFF mode, and HOG session cookies stripped before every backend call.

Authorization

  • A kind: Policy resource with two tiers: built-in require (groups any-of, claims all-of) and embedded OPA/Rego (data.hog.authz.deny).
  • Route/RouteGroup expose a single access block — auth, authorize (policy names), and projection — replacing the earlier separate policy/policies fields. Routes and route groups reference policies by name via access.authorize; the effective set is the union.
  • Additive default-allow, deny-overrides, fail-closed on missing identity or policy errors. Generic 403 responses; deny reasons are logged, never leaked.

Security hardening

  • Trusted-proxy enforcement. A gateway-wide forwarded layer strips X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Real-Ip, and Forwarded from any request whose immediate peer isn't listed in Gateway.spec.trustedProxies. CIDRs and bare IPs are accepted, "*" trusts every peer, and the default (empty) trusts none — the secure default.
  • CSRF protection and security headers. Gateway.spec.security wraps the entire handler — every route and the raw /auth/* endpoints alike — with net/http.CrossOriginProtection-based CSRF defense (on by default, with trustedOrigins and per-pattern bypassPatterns) and static response headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security, opt-in Content-Security-Policy).

Observability

  • Opt-in OpenTelemetry traces and metrics exported over OTLP, W3C trace-context propagation, a trace-correlated structured access log, and a session_id correlation hash. Credentials are never recorded; query strings are redacted.

Delivery

  • hog-build: composes a custom binary from the Gateway.plugins manifest (generate + go build), so the configuration is the build manifest.
  • A secure-by-design Alpine image family: hog-builder (build), hog-runtime (a non-root, debuggable runtime base), and hog-static (a SPA server out of the box).
  • Framework mode: import HOG as a Go package and call hog.Main().

Security posture

  • Container images run as a non-root user and support a read-only root filesystem.
  • Authorization is fail-closed and deny-overrides.
  • HOG session cookies are never forwarded to backends; access tokens are forwarded only when explicitly enabled.
  • No credentials appear in logs, traces, or error responses.
  • HOG runs behind a TLS-terminating load balancer and derives the external scheme, host, and client IP from X-Forwarded-*. Gateway.spec.trustedProxies is enforced: a gateway-wide forwarded layer strips X-Forwarded-*/X-Real-Ip/Forwarded from any peer not listed there (empty, the default, trusts none; "*" trusts every peer) — deploy it so only your proxy's CIDR is trusted.
  • CSRF protection (net/http.CrossOriginProtection, defense-in-depth on top of SameSite=Lax session cookies) and security response headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security) are on by default, applied gateway-wide via Gateway.spec.security to every route and the raw /auth/* endpoints alike. A same-site-but-cross-origin frontend (e.g. an SPA on a different subdomain from HOG) needs its origin added to security.csrf.trustedOrigins for state-changing requests to succeed.

Breaking changes

HOG v2 is a clean-room rewrite and is not backward compatible with v1:

  • Configuration format. v1's KrakenD-style JSON is replaced by Kubernetes-style YAML resources. There is no automatic config migration.
  • Extension model. v1's runtime .so plugins are replaced by compile-time Go plugins composed with hog-build or imported as a framework.
  • Runtime. v2 is a native net/http gateway; the Lura/KrakenD core is gone.

See migrating from v1 for the mapping and the v1 deprecation timeline.

Deferred

The following are intentionally out of scope for this release: event publishing, a generic HTTP response cache, TLS termination inside HOG (always terminate at the LB), runtime .so plugin loading, and single-artifact embed.FS baking of content/config.