Configuration

Trestle validates configuration before listening. Command-line flags override environment variables, which override conservative defaults.

Process and HTTP

Listener

The bind host and port follow the shared precedence CLI flag > environment variable > default, with 127.0.0.1:7333 as the default. The port must be an integer from 1 through 65535; malformed, empty, zero, negative or oversized values fail rather than falling back. Surrounding whitespace is trimmed, and IPv6 hosts are bracketed (--host ::1 binds [::1]:7333).

./trestle                            # 127.0.0.1:7333
TRESTLE_PORT=7403 ./trestle          # 127.0.0.1:7403 (host defaulted)
./trestle --host 0.0.0.0 --port 7403 # CLI wins over environment and defaults

The legacy single-address --listen (and TRESTLE_LISTEN) is retained for compatibility and is mutually exclusive with --host/--port; an explicit host/port selection overrides TRESTLE_LISTEN, while a conflict between TRESTLE_LISTEN and TRESTLE_HOST/TRESTLE_PORT environment variables fails clearly. Explicit --host/--port (CLI or environment) overrides an existing durable config listener in memory, so the advertised override controls the runtime listener; a bare invocation or legacy --listen keeps the durable config.

Bind Trestle to loopback by default and terminate TLS with a reverse proxy on the same host; keep the public Host and configure only the exact proxy addresses you administer. Binding 0.0.0.0 exposes Trestle on all IPv4 interfaces with no authentication bypass.

Trusted proxies

Provide comma-separated CIDRs only for reverse proxies you administer. Forwarded scheme and client data are ignored from every other immediate peer. Trestle walks a trusted chain from right to left and stops at the first untrusted address.

TRESTLE_TRUSTED_PROXIES=127.0.0.1/32,10.20.0.0/24

Timeout boundaries

The header timeout limits slow header delivery. The read timeout covers request bodies, including uploads, while the idle timeout bounds unused keep-alive connections. Trestle deliberately has no global response write timeout because realtime SSE connections are long lived.

Secret handling

Keep S3 and AWS credentials in an owner-readable environment file or secret manager. Do not put them in service definitions, command lines, support bundles or source control. The data directory is normalized to mode 0700 on Unix.

Shutdown

SIGINT and SIGTERM remove readiness, stop background work and allow in-flight requests to finish within the configured timeout.