hog

README

🐗 HOG - Highly Over-engineered Gateway

A KrakenD-CE fork with built-in OAuth 2.0 / OIDC authentication, static content proxying, and enhanced observability for modern SPA architectures.

What is HOG?

HOG extends the ultra-high performance KrakenD API Gateway with production-ready authentication and observability features:

• 🔐 BFF Authentication - OAuth 2.0 / OIDC plugin acting as a Backend-for-Frontend (PKCE, encrypted cookies, stateless sessions)
• 📦 Static Content Proxy - Serve SPAs with optional per-route authentication and auto-redirect after login
• 📊 Enhanced Observability - Structured JSON logging with OTEL/Datadog trace correlation
• 🚀 Zero-Trust by Default - Secure cookie handling, XSS protection, and automatic JWT injection

Quick Start

# docker-compose.yaml
services:
  gateway:
    image: ghcr.io/paulopiriquito/hog:latest
    environment:
      - IDP_ISSUER=http://your-idp:5556
      - IDP_CLIENT_ID=your-client
      - IDP_CLIENT_SECRET=your-secret
      - AUTH_COOKIE_KEY=abcdefghijklmnopqrstuvwxyz123456 # must be exactly 32 bytes
    volumes:
      - ./krakend.json:/etc/krakend/krakend.json
    ports:
      - "8080:8080"

{
  "version": 3,
  "extra_config": {
    "plugin/http-server": {
      "name": ["hog-authenticator", "hog-static-content"],
      "hog-authenticator": {
        "idp": { "type": "oidc" }
      },
      "hog-static-content": {
        "static": [
          { "path-prefix": "/*", "service-host": "http://spa:3000", "auth": true }
        ],
        "service-gateway": { "path-prefix": ["/api/*"] }
      }
    }
  },
  "endpoints": []
}

HOG Plugins

hog-authenticator

OAuth 2.0 / OIDC authentication plugin that acts as a Backend-for-Frontend (BFF):

• OIDC Discovery - Automatic endpoint configuration via .well-known/openid-configuration
• PKCE Support - Proof Key for Code Exchange for enhanced security
• Encrypted Cookies - AES-256-GCM encrypted HttpOnly cookies (XSS protection)
• Stateless Sessions - Horizontal scaling with signed state tokens
• User Headers - Automatic injection of X-User-Id, X-User-Email, X-User-Name

hog-static-content

Static content proxy with optional authentication:

• Wildcard Routing - Flexible path patterns (/app/*, /assets/*)
• Multiple Upstreams - Different static servers per path
• Optional Auth - Per-route authentication via hog-authenticator
• Auto-Redirect - Unauthenticated users redirected to login, then back to original path

HOG Packages

Reusable Go packages for extending KrakenD:

Package	Description
pkg/logging	Structured logging with trace context and access logs
pkg/headers	Header manipulation and trace propagation utilities
pkg/forward	Project IdP claims into forwarded headers (filter, rename, map)
pkg/session	Cookie and JWT session management
pkg/paths	URL pattern matching for routing
pkg/pluginlogger	Logger wrapper for KrakenD plugins

Documentation

HOG Features

• Observability & Trace Correlation - Configure JSON logging with OTEL/Datadog trace IDs
• Authenticator Plugin - Full BFF authentication configuration
• Static Content Plugin - Static serving with auth options
• Local Stack - Docker-based testing with Dex IdP and Grafana observability
• End-to-End Tests - Headless-browser tests covering simple-auth, client PKCE, and protected static/API flows

This project is not supported by the KrakenD team.

---

Recognition

This project is a fork of KrakenD Community Edition Thank you to the KrakenD and Lura team for creating such a great piece of software.

KrakenD Community Edition

KrakenD is an extensible, ultra-high performance API Gateway that helps you effortlessly adopt microservices and secure communications. KrakenD is easy to operate and run and scales out without a single point of failure.

KrakenD Community Edition (or KrakenD-CE) is the open-source distribution of KrakenD.

KrakenD Site | Documentation | Blog | Twitter | Downloads

Benefits

• Easy integration of an ultra-high performance gateway.
• Effortlessly transition to microservices and Backend For Frontend implementations.
• True linear scalability: Thanks to its stateless design, every KrakenD node can operate independently in the cluster without any coordination or centralized persistence.
• Low operational cost: +70K reqs/s on a single instance of regular size. Super low memory consumption with high traffic (usually under 50MB w/ +1000 concurrent). Fewer machines. Smaller machines. Lower budget.
• Platform-agnostic. Whether you work in a Cloud-native environment (e.g., Kubernetes) or self-hosted on-premises.
• No vendor lock-in: Reuse the best existing open-source and proprietary tools rather than having everything in the gateway (telemetry, identity providers, etc.)
• API Lifecycle: Using GitOps and declarative configuration.
• Decouple clients from existing services. Create new APIs without changing your existing API contracts.

Technical features

• Content aggregation, composition, and filtering: Create views and mashups of aggregated content from your APIs.
• Content Manipulation and format transformation: Change responses, convert transparently from XML to JSON, and vice-versa.
• Security: Zero-trust policy, CORS, OAuth, JWT, HSTS, clickjacking protection, HPKP, MIME-Sniffing prevention, XSS protection...
• Concurrent calls: Serve content faster than consuming backends directly.
• SSL and HTTP2 ready
• Throttling: Limits of usage in the router and proxy layers
• Multi-layer rate-limiting for the end-user and between KrakenD and your services, including bursting, load balancing, and circuit breaker.
• Telemetry and dashboards of all sorts: Datadog, Zipkin, Jaeger, Prometheus, Grafana...
• Extensible with Go plugins, Lua scripts, Martian, or Google CEL spec.

See the website for more information.

Download

KrakenD is packaged and distributed in several formats. You don't need to clone this repo to use KrakenD unless you want to tweak and build the binary yourself.

Run

In its simplest form with the offical Docker image:

docker run -it -p "8080:8080" krakend

Now see http://localhost:8080/__health. The gateway is listening. Now CTRL-C and replace /etc/krakend/krakend.json with your first configuration.

Build

See the required Go version in the Makefile, and then:

make build

Or, if you don't have or don't want to install go, you can build it using the golang docker container:

make build_on_docker

License

Apache Version 2.0 - ./LICENSE

Documentation

Index

• func AddCheck(f func(context.Context, *cobra.Command, string, string) bool)
• func LoadPlugins(folder, pattern string, logger logging.Logger)
• func LoadPluginsWithContext(ctx context.Context, folder, pattern string, logger logging.Logger)
• func NewBackendFactory(logger logging.Logger, metricCollector *metrics.Metrics) proxy.BackendFactory
• func NewBackendFactoryWithContext(ctx context.Context, logger logging.Logger, metricCollector *metrics.Metrics) proxy.BackendFactory
• func NewEngine(cfg config.ServiceConfig, opt luragin.EngineOptions) *gin.Engine
• func NewExecutor(ctx context.Context) cmd.Executor
• func NewHandlerFactory(logger logging.Logger, metricCollector *metrics.Metrics, ...) router.HandlerFactory
• func NewProxyFactory(logger logging.Logger, backendFactory proxy.BackendFactory, ...) proxy.Factory
• func NewTestPluginCmd() cmd.Command
• func NewTestPluginCmdWithArgs(flags ...cmd.FlagBuilder) cmd.Command
• func RegisterEncoders()
• func RegisterSubscriberFactories(_ context.Context, _ config.ServiceConfig, _ logging.Logger) func(n string, p int)
• type AgentStarter
• type BackendFactory
• type BloomFilterJWT
  • func (BloomFilterJWT) NewTokenRejecter(ctx context.Context, cfg config.ServiceConfig, l logging.Logger, ...) (jose.ChainedRejecterFactory, error)
• type DefaultRunServerFactory
  • func (*DefaultRunServerFactory) NewRunServer(l logging.Logger, next router.RunServerFunc) RunServer
• type EngineFactory
• type ExecutorBuilder
  • func (e *ExecutorBuilder) NewCmdExecutor(ctx context.Context) cmd.Executor
• type HandlerFactory
• type LoggerBuilder
  • func (LoggerBuilder) NewLogger(cfg config.ServiceConfig) (logging.Logger, io.Writer, error)
• type LoggerFactory
• type MetricsAndTraces
  • func (m *MetricsAndTraces) Close()
  • func (m *MetricsAndTraces) Register(ctx context.Context, cfg config.ServiceConfig, l logging.Logger) *metrics.Metrics
• type MetricsAndTracesRegister
• type PluginLoader
• type PluginLoaderWithContext
• type ProxyFactory
• type RunServer
• type RunServerFactory
• type SubscriberFactoriesRegister
• type TokenRejecterFactory

Functions

func AddCheck

func AddCheck(f func(context.Context, *cobra.Command, string, string) bool)

func LoadPlugins

func LoadPlugins(folder, pattern string, logger logging.Logger)

LoadPlugins loads and registers the plugins so they can be used if enabled at the configuration

func LoadPluginsWithContext

func LoadPluginsWithContext(ctx context.Context, folder, pattern string, logger logging.Logger)

func NewBackendFactory

func NewBackendFactory(logger logging.Logger, metricCollector *metrics.Metrics) proxy.BackendFactory

NewBackendFactory creates a BackendFactory by stacking all the available middlewares: - oauth2 client credentials - http cache - martian - pubsub - amqp - cel - lua - rate-limit - circuit breaker - metrics collector - opencensus collector

func NewBackendFactoryWithContext

func NewBackendFactoryWithContext(ctx context.Context, logger logging.Logger, metricCollector *metrics.Metrics) proxy.BackendFactory

NewBackendFactoryWithContext creates a BackendFactory by stacking all the available middlewares and injecting the received context

func NewEngine

func NewEngine(cfg config.ServiceConfig, opt luragin.EngineOptions) *gin.Engine

NewEngine creates a new gin engine with some default values and a secure middleware

func NewExecutor

func NewExecutor(ctx context.Context) cmd.Executor

NewExecutor returns an executor for the cmd package. The executor initalizes the entire gateway by registering the components and composing a RouterFactory wrapping all the middlewares.

func NewHandlerFactory

func NewHandlerFactory(logger logging.Logger, metricCollector *metrics.Metrics, rejecter jose.RejecterFactory) router.HandlerFactory

NewHandlerFactory returns a HandlerFactory with a rate-limit and a metrics collector middleware injected

func NewProxyFactory

func NewProxyFactory(logger logging.Logger, backendFactory proxy.BackendFactory, metricCollector *metrics.Metrics) proxy.Factory

NewProxyFactory returns a new ProxyFactory wrapping the injected BackendFactory with the default proxy stack and a metrics collector

func NewTestPluginCmd

func NewTestPluginCmd() cmd.Command

func NewTestPluginCmdWithArgs

func NewTestPluginCmdWithArgs(flags ...cmd.FlagBuilder) cmd.Command

func RegisterEncoders

func RegisterEncoders()

RegisterEncoders registers all the available encoders

func RegisterSubscriberFactories

func RegisterSubscriberFactories(_ context.Context, _ config.ServiceConfig, _ logging.Logger) func(n string, p int)

RegisterSubscriberFactories registers all the available sd adaptors

Types

type AgentStarter

type AgentStarter interface {
	Start(
		context.Context,
		[]*config.AsyncAgent,
		logging.Logger,
		chan<- string,
		proxy.Factory,
	) func() error
}

AgentStarter defines a type that starts a set of agents

type BackendFactory

type BackendFactory interface {
	NewBackendFactory(context.Context, logging.Logger, *metrics.Metrics) proxy.BackendFactory
}

BackendFactory returns a KrakenD backend factory, ready to be passed to the KrakenD proxy factory

type BloomFilterJWT

type BloomFilterJWT struct{}

BloomFilterJWT is the default TokenRejecterFactory implementation.

func (BloomFilterJWT) NewTokenRejecter

func (BloomFilterJWT) NewTokenRejecter(ctx context.Context, cfg config.ServiceConfig, l logging.Logger, reg func(n string, p int)) (jose.ChainedRejecterFactory, error)

NewTokenRejecter registers the bloomfilter component and links it to a token rejecter. Then it returns a chained rejecter factory with the created token rejecter and other based on the CEL component.

type DefaultRunServerFactory

type DefaultRunServerFactory struct{}

DefaultRunServerFactory creates the default RunServer by wrapping the injected RunServer with the plugin loader and the CORS module

func (*DefaultRunServerFactory) NewRunServer

func (*DefaultRunServerFactory) NewRunServer(l logging.Logger, next router.RunServerFunc) RunServer

type EngineFactory

type EngineFactory interface {
	NewEngine(config.ServiceConfig, router.EngineOptions) *gin.Engine
}

EngineFactory returns a gin engine, ready to be passed to the KrakenD RouterFactory

type ExecutorBuilder

type ExecutorBuilder struct {
	PluginLoaderWithContext     PluginLoaderWithContext
	LoggerFactory               LoggerFactory
	SubscriberFactoriesRegister SubscriberFactoriesRegister
	TokenRejecterFactory        TokenRejecterFactory
	MetricsAndTracesRegister    MetricsAndTracesRegister
	EngineFactory               EngineFactory

	ProxyFactory        ProxyFactory
	BackendFactory      BackendFactory
	HandlerFactory      HandlerFactory
	RunServerFactory    RunServerFactory
	AgentStarterFactory AgentStarter

	Middlewares []gin.HandlerFunc
}

ExecutorBuilder is a composable builder. Every injected property is used by the NewCmdExecutor method.

func (*ExecutorBuilder) NewCmdExecutor

func (e *ExecutorBuilder) NewCmdExecutor(ctx context.Context) cmd.Executor

NewCmdExecutor returns an executor for the cmd package. The executor initializes the entire gateway by delegating most of the tasks to the injected collaborators. They register the components and compose a RouterFactory wrapping all the middlewares. Every nil collaborator is replaced by the default one offered by this package.

type HandlerFactory

type HandlerFactory interface {
	NewHandlerFactory(logging.Logger, *metrics.Metrics, jose.RejecterFactory) router.HandlerFactory
}

HandlerFactory returns a KrakenD router handler factory, ready to be passed to the KrakenD RouterFactory

type LoggerBuilder

type LoggerBuilder struct{}

LoggerBuilder is the default BuilderFactory implementation.

func (LoggerBuilder) NewLogger

func (LoggerBuilder) NewLogger(cfg config.ServiceConfig) (logging.Logger, io.Writer, error)

NewLogger sets up the logging components as defined at the configuration.

type LoggerFactory

type LoggerFactory interface {
	NewLogger(config.ServiceConfig) (logging.Logger, io.Writer, error)
}

LoggerFactory returns a KrakenD Logger factory, ready to be passed to the KrakenD RouterFactory

type MetricsAndTraces

type MetricsAndTraces struct {
	// contains filtered or unexported fields
}

MetricsAndTraces is the default implementation of the MetricsAndTracesRegister interface.

func (*MetricsAndTraces) Close

func (m *MetricsAndTraces) Close()

func (*MetricsAndTraces) Register

func (m *MetricsAndTraces) Register(ctx context.Context, cfg config.ServiceConfig, l logging.Logger) *metrics.Metrics

Register registers the metrics, influx and opencensus packages as required by the given configuration.

type MetricsAndTracesRegister

type MetricsAndTracesRegister interface {
	Register(context.Context, config.ServiceConfig, logging.Logger) *metrics.Metrics
}

MetricsAndTracesRegister registers the defined observability components and returns a metrics collector, if required.

type PluginLoader

type PluginLoader interface {
	Load(folder, pattern string, logger logging.Logger)
}

PluginLoader defines the interface for the collaborator responsible of starting the plugin loaders Deprecated: Use PluginLoaderWithContext

type PluginLoaderWithContext

type PluginLoaderWithContext interface {
	LoadWithContext(ctx context.Context, folder, pattern string, logger logging.Logger)
}

PluginLoaderWithContext defines the interface for the collaborator responsible of starting the plugin loaders

type ProxyFactory

type ProxyFactory interface {
	NewProxyFactory(logging.Logger, proxy.BackendFactory, *metrics.Metrics) proxy.Factory
}

ProxyFactory returns a KrakenD proxy factory, ready to be passed to the KrakenD RouterFactory

type RunServer

type RunServer func(context.Context, config.ServiceConfig, http.Handler) error

RunServer defines the interface of a function used by the KrakenD router to start the service

type RunServerFactory

type RunServerFactory interface {
	NewRunServer(logging.Logger, router.RunServerFunc) RunServer
}

RunServerFactory returns a RunServer with several wraps around the injected one

type SubscriberFactoriesRegister

type SubscriberFactoriesRegister interface {
	Register(context.Context, config.ServiceConfig, logging.Logger) func(string, int)
}

SubscriberFactoriesRegister registers all the required subscriber factories from the available service discover components and adapters and returns a service register function. The service register function will register the service by the given name and port to all the available service discover clients

type TokenRejecterFactory

type TokenRejecterFactory interface {
	NewTokenRejecter(context.Context, config.ServiceConfig, logging.Logger, func(string, int)) (jose.ChainedRejecterFactory, error)
}

TokenRejecterFactory returns a jose.ChainedRejecterFactory containing all the required jose.RejecterFactory. It also should setup and manage any service related to the management of the revocation process, if required.