HTTP Server

HTTP Server

The HTTP server (http.service) listens on a port and hosts routers, endpoints, and static file handlers.

Configuration

- name: gateway
  kind: http.service
  addr: ":8080"
  timeouts:
    read: "5s"
    write: "30s"
    idle: "60s"
  host:
    buffer_size: 1024
    worker_count: 4
  lifecycle:
    auto_start: true
    security:
      actor:
        id: "http-gateway"
      policies:
        - app:http_policy

Field	Type	Default	Description
addr	string	required	Listen address (:8080, 0.0.0.0:443)
timeouts.read	duration	-	Request read timeout
timeouts.write	duration	-	Response write timeout
timeouts.idle	duration	-	Keep-alive connection timeout
host.buffer_size	int	1024	Message relay buffer size
host.worker_count	int	NumCPU	Message relay workers
network	Registry ID	-	Bind listener through a network overlay (e.g. Tailscale, I2P)
tls	object	-	TLS termination (see TLS)

Timeouts

Configure timeouts to prevent resource exhaustion:

timeouts:
  read: "10s"    # Max time to read the entire request (headers + body)
  write: "60s"   # Max time to write response
  idle: "120s"   # Keep-alive timeout

• read - Short (5-10s) for APIs, longer for uploads
• write - Match expected response generation time
• idle - Balance connection reuse vs resource usage

Duration format: 30s, 1m, 2h15m. Use 0 to disable.

Host Configuration

The host section configures the server’s internal message relay used by components like WebSocket relay:

host:
  buffer_size: 2048
  worker_count: 8

Field	Default	Description
buffer_size	1024	Message queue capacity per worker
worker_count	NumCPU	Parallel message processing goroutines

Increase these values for high-throughput WebSocket applications. The message relay handles async delivery between HTTP components and processes.

Security

HTTP servers can have a default security context applied through the lifecycle configuration:

lifecycle:
  auto_start: true
  security:
    actor:
      id: "gateway-service"
    policies:
      - app:http_access_policy

This sets a baseline actor and policies for all requests. For authenticated requests, the token_auth middleware overrides the actor based on the validated token, allowing per-user security policies.

Lifecycle

Servers are managed by the supervisor:

lifecycle:
  auto_start: true
  start_timeout: 30s
  stop_timeout: 60s
  depends_on:
    - app:database

Field	Description
auto_start	Start when application starts
start_timeout	Max time to wait for server to start
stop_timeout	Max time for graceful shutdown
depends_on	Start after these entries are ready

Connecting Components

Routers and static handlers reference the server via metadata:

entries:
  - name: gateway
    kind: http.service
    addr: ":8080"

  - name: api
    kind: http.router
    meta:
      server: gateway
    prefix: /api

  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app:public

Multiple Servers

Run separate servers for different purposes:

entries:
  # Public API
  - name: public
    kind: http.service
    addr: ":8080"
    lifecycle:
      auto_start: true

  # Admin (localhost only)
  - name: admin
    kind: http.service
    addr: "127.0.0.1:9090"
    lifecycle:
      auto_start: true

TLS

The server can terminate TLS directly. Set tls.mode to manual (supply your own certificate) or auto (certificate provided by an overlay network driver, e.g. network.tailscale). Plain clearnet listeners do not support auto. Omit tls or leave the mode empty to run plain HTTP.

In auto mode the server must not specify cert/key/cert_env/key_env — the network driver provides them.

Manual certificate

Provide cert and key either inline/file-loaded or via environment variables (never both):

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: file://./certs/server.pem
    key:  file://./certs/server.key

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert_env: TLS_SERVER_CERT
    key_env:  TLS_SERVER_KEY

Field	Description
mode	"" (off), auto, or manual
cert / key	PEM content (typically loaded via file://)
cert_env / key_env	Env variable names resolved via the env registry

Mutual TLS (mTLS)

Under mode: manual the server can additionally verify client certificates:

tls:
  mode: manual
  cert_env: TLS_SERVER_CERT
  key_env:  TLS_SERVER_KEY
  client_ca: file://./certs/clients-ca.pem
  client_auth: require_and_verify

Field	Description
client_auth	request, require_any, verify_if_given, require_and_verify
client_ca	PEM bundle of trusted client CAs
client_ca_env	Env variable holding the CA bundle (mutually exclusive with client_ca)

verify_if_given and require_and_verify require a CA. request and require_any accept any client cert without CA verification.

See Also

• Routing - Routers and endpoints
• Static Files - Static file serving
• Middleware - Available middleware
• Security - Security policies
• WebSocket Relay - WebSocket messaging