Octopus API Gateway 🐙

Octopus is an API gateway written in Rust. It routes HTTP traffic to upstream services and can discover and configure those services automatically through FARP — the Forge API Gateway Registration Protocol. Services that speak FARP publish their own schemas (OpenAPI, AsyncAPI, gRPC, GraphQL) and Octopus turns them into routes as services come and go. You can also run it purely statically by listing upstreams and routes in a config file — the two modes work together.

Octopus is maintained by Xraph and is part of the FARP ecosystem.

Why Octopus?01

⚡ Fast by default→

An async core built on Tokio and Hyper, a trie-based router, connection pooling, and Rhai scripts that run in microseconds.

🔄 Schema-driven discovery→

FARP watches services and generates routes from their published schemas — no hand-written route tables required.

☸️ Kubernetes-first→

An in-process operator programs the router from the Gateway API and Octopus CRDs, with probes, graceful drain, EndpointSlice discovery, and cert-manager TLS.

🧩 Extensible→

A middleware chain, an embedded Rhai scripting engine, and a plugin SDK for custom behaviour.

🌐 Multi-protocol→

HTTP/1.1 and HTTP/2 reverse proxying with WebSocket upgrades, plus gRPC and Server-Sent Events.

📊 Observable→

Prometheus metrics, structured logging, and a built-in admin dashboard and REST API.

Capabilities02

Reverse proxy — HTTP/1.1 and HTTP/2 with connection pooling, configurable timeouts, and WebSocket upgrades.
Routing — a trie-based router with wildcard path matching, method filtering, prefix rewriting, and per-route priorities.
Load balancing & resilience — round-robin and weighted load balancing, active health checks, and circuit breaking.
Service discovery — FARP-driven discovery with backends for mDNS, Consul, DNS, and Kubernetes (EndpointSlice).
Middleware — compression and authentication run in the request chain today; the octopus-middleware crate also provides CORS, rate limiting, transformations, caching, a WAF, and more (see Middleware for what's currently wired).
Security — JWT, OIDC, API-key, forward-auth, and mTLS authentication; role/scope and Rhai/OPA authorization; TLS termination with mutual TLS (certificate hot-reload on the Kubernetes path).
Scripting & plugins — an embedded Rhai scripting engine and a plugin SDK (octopus-plugin-api) for custom behaviour.
Kubernetes — an operator for the Gateway API (HTTPRoute/GRPCRoute) and Octopus CRDs, health probes, graceful drain, and a Helm chart.
Observability — Prometheus metrics, structured logging, and a built-in admin dashboard and REST API (distributed tracing is planned).
Configuration — layered YAML, JSON, or TOML with ${VAR} / ${VAR:-default} environment substitution and multi-file merging.

Protocol support03

Protocol	Status	Notes
HTTP/1.1	✅	Reverse proxy with connection pooling
HTTP/2	✅	Multiplexing
gRPC	✅	Transparent HTTP/2 (h2c) proxy; no reflection or transcoding
WebSocket	✅	Bidirectional upgrade proxying
Server-Sent Events	✅	Streaming responses
GraphQL	🚧	Endpoint stub — not yet proxied or federated
HTTP/3 (QUIC)	🚧	Planned

Quick example04

A minimal static configuration — one upstream and one route:

# config.yaml
gateway:
  listen: "0.0.0.0:8080"
  workers: 0                 # 0 = one worker per CPU core

upstreams:
  - name: user-service
    lb_policy: round_robin
    instances:
      - id: user-1
        host: 127.0.0.1
        port: 8081
    health_check:
      type: http
      path: /health
      interval: 10s

routes:
  - path: /api/users/*
    methods: [GET, POST, PUT, DELETE]
    upstream: user-service
    strip_prefix: /api

octopus validate -c config.yaml   # check the config parses
octopus serve -c config.yaml      # start the gateway
curl http://localhost:8080/api/users/123

Note

Health probes (/livez, /readyz, /startupz) and Prometheus metrics (/metrics) are all served on the gateway listen port.

Getting started05

Install

Run the published container image (the listen port 8080 serves traffic, health probes, and /metrics):

docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/etc/octopus/config.yaml" \
  ghcr.io/xraph/octopus:latest

Or build from source (Rust 1.75+) — the binary is written to target/release/octopus:

git clone https://github.com/xraph/octopus.git
cd octopus
make release

See Installation for Helm and Kubernetes options.

Configure

Create a config.yaml. Start from the Quick Start or the per-section Configuration reference.

Validate & run

octopus validate -c config.yaml
octopus serve -c config.yaml

Verify

curl http://localhost:8080/api/users/123   # proxied to your upstream
curl http://localhost:8080/livez            # liveness
curl http://localhost:8080/readyz           # readiness