proxy/docs

layout, title, description, toc

layout	title	description	toc
default	Sunbeam Proxy Documentation	Configuration reference and feature documentation for Sunbeam Proxy	true

Sunbeam Proxy Documentation

Complete reference for configuring and operating Sunbeam Proxy — a TLS-terminating reverse proxy built on Pingora 0.8.

Quick Start

# Local development
SUNBEAM_CONFIG=dev.toml RUST_LOG=info cargo run

# Run tests
cargo nextest run

# Build release (linux-musl for containers)
cargo build --release --target x86_64-unknown-linux-musl

---

Configuration Reference

Configuration is TOML, loaded from $SUNBEAM_CONFIG or /etc/pingora/config.toml.

Listeners & TLS

[listen]
http  = "0.0.0.0:80"
https = "0.0.0.0:443"

[tls]
cert_path = "/etc/ssl/tls.crt"
key_path  = "/etc/ssl/tls.key"

Telemetry

[telemetry]
otlp_endpoint = ""         # OpenTelemetry OTLP endpoint (empty = disabled)
metrics_port  = 9090        # Prometheus scrape port (0 = disabled)

Routes

Each route maps a host prefix to a backend. host_prefix = "docs" matches requests to docs.<your-domain>.

[[routes]]
host_prefix = "docs"
backend     = "http://docs-backend.default.svc.cluster.local:8080"
websocket   = false                    # forward WebSocket upgrade headers
disable_secure_redirection = false     # true = allow plain HTTP

Path Sub-Routes

Longest-prefix match within a host. Mix static serving with API proxying.

[[routes.paths]]
prefix       = "/api"
backend      = "http://api-backend:8000"
strip_prefix = true                    # /api/users → /users
websocket    = false

Static File Serving

Serve frontends directly from the proxy. The try_files chain checks candidates in order:

1. $static_root/$uri — exact file
2. $static_root/$uri.html — with .html extension
3. $static_root/$uri/index.html — directory index
4. $static_root/$fallback — SPA fallback

If nothing matches, the request falls through to the upstream backend.

[[routes]]
host_prefix = "meet"
backend     = "http://meet-backend:8080"
static_root = "/srv/meet"
fallback    = "index.html"

Content-type detection is based on file extension:

Extensions	Content-Type
html, htm	text/html; charset=utf-8
css	text/css; charset=utf-8
js, mjs	application/javascript; charset=utf-8
json	application/json; charset=utf-8
svg	image/svg+xml
png, jpg, gif, webp, avif	image/*
woff, woff2, ttf, otf	font/*
wasm	application/wasm

Cache-control headers are set per extension type:

Extensions	Cache-Control
js, css, woff2, wasm	public, max-age=31536000, immutable
png, jpg, svg, ico	public, max-age=86400
Everything else	no-cache

Path sub-routes take priority over static serving — if /api matches a path route, it goes to that backend even if a static file exists.

Path traversal (..) is rejected and falls through to the upstream.

URL Rewrites

Regex patterns compiled at startup, applied before static file lookup. First match wins.

[[routes.rewrites]]
pattern = "^/docs/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/?$"
target  = "/docs/[id]/index.html"

Response Body Rewriting

Find/replace in response bodies, like nginx sub_filter. Only applies to text/html, application/javascript, and text/javascript responses. Binary responses pass through untouched.

The entire response is buffered in memory before substitution (fine for HTML/JS — typically <1MB). Content-Length is removed since the body size may change.

[[routes.body_rewrites]]
find    = "old-domain.example.com"
replace = "new-domain.sunbeam.pt"

Custom Response Headers

[[routes.response_headers]]
name  = "X-Frame-Options"
value = "DENY"

Auth Subrequests

Gate path routes with an HTTP auth check before forwarding upstream. Similar to nginx auth_request.

[[routes.paths]]
prefix               = "/media"
backend              = "http://seaweedfs-filer:8333"
strip_prefix         = true
auth_request         = "http://drive-backend/api/v1.0/items/media-auth/"
auth_capture_headers = ["Authorization", "X-Amz-Date", "X-Amz-Content-Sha256"]
upstream_path_prefix = "/sunbeam-drive/"

The auth subrequest sends a GET to auth_request with the original Cookie, Authorization, and X-Original-URI headers.

Auth response	Proxy behavior
2xx	Capture specified headers, forward to backend
Non-2xx	Return 403 to client
Network error	Return 502 to client

HTTP Response Cache

Per-route in-memory cache backed by pingora-cache.

[routes.cache]
enabled                     = true
default_ttl_secs            = 60      # TTL when upstream has no Cache-Control
stale_while_revalidate_secs = 0       # serve stale while revalidating
max_file_size               = 0       # max cacheable body size (0 = unlimited)

Pipeline position: Cache runs after the security pipeline and before upstream modifications.

Request → DDoS → Scanner → Rate Limit → Cache → Upstream

Cache behavior:

• Only caches GET and HEAD requests
• Respects Cache-Control: no-store and Cache-Control: private
• TTL priority: s-maxage > max-age > default_ttl_secs
• Skips routes with body rewrites (content varies)
• Skips requests with auth subrequest headers (per-user content)
• Cache key: {host}{path}?{query}

SSH Passthrough

Raw TCP proxy for SSH traffic.

[ssh]
listen  = "0.0.0.0:22"
backend = "gitea-ssh.devtools.svc.cluster.local:2222"

DDoS Detection

KNN-based per-IP behavioral classification over sliding windows.

[ddos]
enabled         = true
model_path      = "ddos_model.bin"
k               = 5
threshold       = 0.6
window_secs     = 60
window_capacity = 1000
min_events      = 10

Scanner Detection

Logistic regression per-request classification with verified bot allowlist.

[scanner]
enabled            = true
model_path         = "scanner_model.bin"
threshold          = 0.5
poll_interval_secs = 30        # hot-reload check interval (0 = disabled)
bot_cache_ttl_secs = 86400     # verified bot IP cache TTL

[[scanner.allowlist]]
ua_prefix    = "Googlebot"
reason       = "Google crawler"
dns_suffixes = ["googlebot.com", "google.com"]
cidrs        = ["66.249.64.0/19"]

Rate Limiting

Leaky bucket per-identity throttling. Identity resolution: ory_kratos_session cookie > Bearer token > client IP.

[rate_limit]
enabled                = true
eviction_interval_secs = 300
stale_after_secs       = 600
bypass_cidrs           = ["10.42.0.0/16"]

[rate_limit.authenticated]
burst = 200
rate  = 50.0

[rate_limit.unauthenticated]
burst = 50
rate  = 10.0

---

Observability

Request IDs

Every request gets a UUID v4 request ID. It's:

• Attached to a tracing::info_span! so all log lines within the request inherit it
• Forwarded upstream via X-Request-Id
• Returned to clients via X-Request-Id
• Included in audit log lines

Prometheus Metrics

Served at GET /metrics on metrics_port (default 9090).

Metric	Type	Labels
sunbeam_requests_total	Counter	method, host, status, backend
sunbeam_request_duration_seconds	Histogram	—
sunbeam_ddos_decisions_total	Counter	decision
sunbeam_scanner_decisions_total	Counter	decision, reason
sunbeam_rate_limit_decisions_total	Counter	decision
sunbeam_cache_status_total	Counter	status
sunbeam_active_connections	Gauge	—

GET /health returns 200 for k8s probes.

# Prometheus scrape config
- job_name: sunbeam-proxy
  static_configs:
    - targets: ['sunbeam-proxy.ingress.svc.cluster.local:9090']

Audit Logs

Every request produces a structured JSON log line (target = "audit"):

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "GET",
  "host": "docs.sunbeam.pt",
  "path": "/api/v1/pages",
  "query": "limit=10",
  "client_ip": "203.0.113.42",
  "status": 200,
  "duration_ms": 23,
  "content_length": 0,
  "user_agent": "Mozilla/5.0 ...",
  "referer": "https://docs.sunbeam.pt/",
  "accept_language": "en-US",
  "accept": "text/html",
  "has_cookies": true,
  "cf_country": "FR",
  "backend": "http://docs-backend:8080",
  "error": null
}

Detection Pipeline Logs

Each security layer emits a target = "pipeline" log line before acting:

layer=ddos       → all HTTPS traffic (scanner training data)
layer=scanner    → traffic that passed DDoS (rate-limit training data)
layer=rate_limit → traffic that passed scanner

This guarantees training pipelines always see the full traffic picture.

---

CLI Commands

# Start the proxy server
sunbeam-proxy serve [--upgrade]

# Train DDoS model from audit logs
sunbeam-proxy train --input logs.jsonl --output ddos_model.bin \
    [--attack-ips ips.txt] [--normal-ips ips.txt] \
    [--heuristics heuristics.toml] [--k 5] [--threshold 0.6]

# Replay logs through detection pipeline
sunbeam-proxy replay --input logs.jsonl --model ddos_model.bin \
    [--config config.toml] [--rate-limit]

# Train scanner model
sunbeam-proxy train-scanner --input logs.jsonl --output scanner_model.bin \
    [--wordlists path/to/wordlists] [--threshold 0.5]

---

Architecture

Source Files

src/main.rs          — server bootstrap, watcher spawn, SSH spawn
src/lib.rs           — library crate root
src/config.rs        — TOML config deserialization
src/proxy.rs         — ProxyHttp impl: routing, filtering, caching, logging
src/acme.rs          — Ingress watcher for ACME HTTP-01 challenges
src/watcher.rs       — Secret/ConfigMap watcher for cert + config hot-reload
src/cert.rs          — K8s Secret → cert files on disk
src/telemetry.rs     — JSON logging + OTEL tracing init
src/ssh.rs           — TCP proxy for SSH passthrough
src/metrics.rs       — Prometheus metrics and scrape endpoint
src/static_files.rs  — Static file serving with try_files chain
src/cache.rs         — pingora-cache MemCache backend
src/ddos/            — KNN-based DDoS detection
src/scanner/         — Logistic regression scanner detection
src/rate_limit/      — Leaky bucket rate limiter
src/dual_stack.rs    — Dual-stack (IPv4+IPv6) TCP listener

Runtime Model

Pingora manages its own async runtime. K8s watchers (cert/config, Ingress) each run on separate OS threads with their own tokio runtimes. This isolation is deliberate — Pingora's internal runtime has specific constraints that don't mix with general-purpose async work.

Security Pipeline

Request
  │
  ├── DDoS detection (KNN per-IP)
  │     └── blocked → 429
  │
  ├── Scanner detection (logistic regression per-request)
  │     └── blocked → 403
  │
  ├── Rate limiting (leaky bucket per-identity)
  │     └── blocked → 429
  │
  ├── Cache lookup
  │     └── hit → serve cached response
  │
  └── Upstream request
        ├── Auth subrequest (if configured)
        ├── Response body rewriting (if configured)
        └── Response to client