Configuration¶
siphon-http reads its own YAML file, referenced from siphon's main config under
extensions.http:
# siphon.yaml (the binary's main config)
extensions:
http: /etc/siphon/http.yaml # → this addon's own config
script:
path: /etc/siphon/script.py # your @http.route handlers
The addon config has two top-level sections: servers (inbound listeners) and
clients (named outbound HTTP clients). Everything is optional except that you
need at least one server for anything to listen.
All values support siphon's ${VAR} / ${VAR:-default} environment expansion.
Full example¶
# http.yaml — siphon-http addon config.
servers:
# Public HTTPS listener.
- listen: "0.0.0.0:8443"
tls:
cert_path: "/etc/siphon/tls/server.crt"
key_path: "/etc/siphon/tls/server.key"
client_ca: "/etc/siphon/tls/client-ca.crt" # optional mTLS
max_body_bytes: 65536
request_timeout_ms: 5000
# Localhost-only plain-HTTP listener (e.g. health / metrics).
- listen: "127.0.0.1:9090"
clients:
api:
base_url: "https://api.example.com"
timeout_ms: 5000
verify: "/etc/siphon/tls/ca.crt" # optional custom CA
pool_size: 16
limits and error_retry_after_seconds¶
A server above its capacity should refuse early and say when to come back (RFC 9110 clause 10.2.3), not queue until the client's timer fires.
limits:
- path: /nsmf-pdusession/v1/sm-contexts # the pattern @http.route registered
methods: [POST] # optional; none is every method
listeners: [sbi] # optional; unset is every listener
max_inflight: 64
retry_after_seconds: 1 # default 1
error_retry_after_seconds: 1 # unset leaves 5xx answers as they are
A route over its max_inflight answers 503 with Retry-After and an
application/problem+json document with cause: NF_CONGESTION
(TS 29.500 clause 6.4.2.2), before the body is read and before any
middleware or handler. error_retry_after_seconds gives Retry-After to a
5xx (other than 501) that has none: a handler that raised, a request that
timed out. A Retry-After a handler set itself stays.
A Rust guard (task_with_admission) sees these answers too: its
Admitted::decorate(status, headers) runs on every response of a route,
those of the limits and a handler's error included, and may add or change
header fields (load and overload information, say). Inbound::route is the
pattern that matched.
servers¶
A list of listeners. Each entry is one socket; list several to serve, for example, a public HTTPS endpoint and a localhost-only plain-HTTP endpoint at once.
| Key | Type | Description |
|---|---|---|
listen |
string | Bind address as an IP literal and port (e.g. 0.0.0.0:8443, 127.0.0.1:9090, [::]:8443). Hostnames are not resolved. |
name |
string | Optional. A name for the listener: what a route names to be served on it alone, and what a handler reads as req.listener.name. Without one the listener is known by its listen value. Two listeners of one name are a load error. See Routes on one listener. |
tls |
map | Optional. Present → the listener terminates TLS. Absent → plain HTTP. See TLS. |
max_body_bytes |
int | Optional. Cap on the buffered request body. A larger body is rejected with 413 Payload Too Large. |
request_timeout_ms |
int | Optional. Per-request time budget in milliseconds. |
dscp |
int or string | Optional. The DSCP (RFC 2474) the listener marks with: 0 to 63, or ef, af11…af43, cs0…cs7, va, le, df. Set on the listening socket, which accepted connections inherit. IPv4 listeners only; an IPv6 one with it does not bind. |
HTTP/1.1 and HTTP/2 are both served on every listener automatically — there is no per-listener switch. See HTTP/2.
A listen value that is not an IP address and port is rejected when the file
is loaded. Every listener is then bound at startup, before @http.on_startup
runs, and only starts accepting once those hooks finish. If any listener cannot
bind (port in use, missing or unreadable TLS file) and the script registered at
least one @http.route, siphon exits with an error instead of running with
routes nobody can reach.
TLS termination¶
Add a tls block to a server to terminate TLS on that socket:
servers:
- listen: "0.0.0.0:8443"
tls:
cert_path: "/etc/siphon/tls/server.crt"
key_path: "/etc/siphon/tls/server.key"
| Key | Type | Description |
|---|---|---|
cert_path |
string | Server certificate chain (PEM). |
key_path |
string | Server private key (PEM). |
client_ca |
string | Optional. A CA bundle (PEM); its presence turns on mutual TLS — clients must present a certificate that chains to it. |
reload_seconds |
int | Optional. Check cert_path, key_path and client_ca this often; when one changed, new connections get the files as they are now and open ones keep theirs. Files that do not load are logged and the previous ones stay. Without it the files are read once, at bind. |
Mutual TLS (mTLS)¶
Set tls.client_ca to require and verify a client certificate:
servers:
- listen: "0.0.0.0:8443"
tls:
cert_path: "/etc/siphon/tls/server.crt"
key_path: "/etc/siphon/tls/server.key"
client_ca: "/etc/siphon/tls/client-ca.crt" # require + verify client certs
A handler reads the certificate the client presented from req.tls: its
subject, its subject alternative names and its SHA-256 fingerprint. That is
what to tie a peer's identity to, not its source address. With client_ca
set the handshake of a client without a certificate of that CA fails, so no
request of such a client reaches a handler.
Routes on one listener¶
By default every route is served on every listener. A route that belongs on one of them, such as an internal interface that must not answer on the public port, names its listeners:
servers:
- listen: "0.0.0.0:8080"
name: public
- listen: "192.0.2.10:8443"
name: internal
tls:
cert_path: "/etc/siphon/tls/server.crt"
key_path: "/etc/siphon/tls/server.key"
client_ca: "/etc/siphon/tls/client-ca.crt"
On public the path answers 404, as a path no route has. A route that
names a listener the file does not have stops siphon at startup. Middleware
runs on every listener; it can branch on req.listener.name.
clients¶
A map of named, pooled outbound HTTP clients. A handler picks one up by name
with http.Client("api"), which resolves to clients.api here. Each named
client wraps a pooled reqwest::Client, so connections are reused across
requests.
clients:
api:
base_url: "https://api.example.com"
timeout_ms: 5000
verify: "/etc/siphon/tls/ca.crt"
pool_size: 16
http2_prior_knowledge: false
follow_redirects: true
redirects: 3
resolve:
hooks.example.com: ["192.0.2.10:443"]
| Key | Type | Description |
|---|---|---|
base_url |
string | Base URL; relative paths passed to the client are joined onto it. |
timeout_ms |
int | Optional. Per-request timeout in milliseconds. |
verify |
string | Optional. Path to a CA bundle (PEM, every certificate in it) trusted to verify the server certificate, beside the built-in roots. |
verify_only |
bool | Optional. Trust the verify bundle only, not the built-in roots (an operator PKI, where a public CA must not vouch for a peer). Needs verify. |
cert |
string / pair | Optional. Client-certificate identity for mutual TLS — a combined PEM, or a (cert, key) pair. |
pool_size |
int | Optional. Max pooled connections. |
http2_prior_knowledge |
bool | Optional. Start cleartext connections directly in HTTP/2 (h2c) instead of HTTP/1.1. TLS uses ALPN regardless. |
follow_redirects |
bool | Optional, default true: a 3xx is followed to its Location (up to 10 hops) inside the request. false returns the 3xx to the script as received, Location and the other headers included, to relay or follow itself. |
redirects |
bool / int | Optional. false or 0 returns every 3xx as received; a number follows at most that many hops (more is an error); true follows up to 10. Takes precedence over follow_redirects when set. |
resolve |
map | Optional. Host name to a list of IP:port socket addresses. A request to such a host connects to exactly those addresses (in order) and never asks DNS; the SNI, the certificate check and the Host header keep the host name. The port of the URL is used, not the one in the address. A bad address fails when the client is built. |
reload_seconds |
int | Optional. On a request at most this often, check verify, cert and key; when one changed the pool is built again from them. Files that do not load are logged and the previous pool stays. Without it they are read once. |
Rust code that links siphon-http reaches the same pool with
HttpClient::named(&config, "api"), before or without the server task, and
sends with request(method, target, headers, body):
let client = siphon_http::HttpClient::named(&config, "api")?;
let reply = client.request(http::Method::GET, "/v1/things", &[], None).await?;
A name is one pool per process, whoever asks first. A second configuration
that gives the name other settings gets ClientError::Conflict.
Handlers can also build inline clients that don't need a config entry —
http.Client(base_url=…, verify=…, cert=…). Named clients are preferable for
anything hot, because they share a pool. See the
Script API for the client object itself.
HTTP/2¶
Every listener auto-negotiates the protocol:
- On TLS — h2 or HTTP/1.1 via ALPN.
- On cleartext — h2c (HTTP/2 over cleartext, using the connection preface for prior-knowledge) or HTTP/1.1, on the same socket.
There is no per-listener HTTP/2 switch; you don't configure it. Outbound clients
use ALPN on TLS the same way; for cleartext h2c set
clients.<name>.http2_prior_knowledge: true (or pass http2_prior_knowledge=True
to an inline http.Client).
Environment expansion¶
Every string value goes through siphon's environment expansion, so you can keep secrets and per-environment paths out of the file: