weaseldb/config.md

WeaselDB Configuration

WeaselDB uses a TOML configuration file to control server behavior and API limits. The configuration is organized into three main sections that correspond to different aspects of the system.

Configuration File Location

By default, WeaselDB looks for config.toml in the current directory. You can specify an alternative path:

./weaseldb /path/to/custom/config.toml

Configuration Sections

Server Configuration ([server])

Controls basic server binding and request limits.

Parameter	Type	Default	Description
bind_address	string	"127.0.0.1"	IP address to bind the server to
port	integer	8080	Port number to listen on
max_request_size_bytes	integer	1048576 (1MB)	Maximum size for incoming requests. Requests exceeding this limit receive a 413 Content Too Large response

Commit Configuration ([commit])

Controls behavior of the /v1/commit endpoint and request ID management.

Parameter	Type	Default	Description
min_request_id_length	integer	20	Minimum length required for client-provided request_id fields to ensure sufficient entropy for collision avoidance
request_id_retention_hours	integer	24	How long to retain request IDs in memory for /v1/status queries. Longer retention reduces the chance of log_truncated responses
request_id_retention_versions	integer	100000000	Minimum number of versions to retain request IDs for, regardless of time. Provides additional protection against log_truncated responses

Subscription Configuration ([subscription])

Controls behavior of the /v1/subscribe endpoint and SSE streaming.

Parameter	Type	Default	Description
max_buffer_size_bytes	integer	10485760 (10MB)	Maximum amount of unconsumed data to buffer for slow subscribers. Connections are closed if this limit is exceeded
keepalive_interval_seconds	integer	30	Interval between keepalive comments in the Server-Sent Events stream to prevent idle timeouts on network proxies

Example Configuration

# WeaselDB Configuration File

[server]
bind_address = "0.0.0.0"
port = 8080
max_request_size_bytes = 2097152  # 2MB

[commit]
min_request_id_length = 32
request_id_retention_hours = 48
request_id_retention_versions = 50000

[subscription]
max_buffer_size_bytes = 52428800  # 50MB
keepalive_interval_seconds = 15

Configuration Loading

• If the specified config file doesn't exist or contains errors, WeaselDB will use default values and log a warning
• All configuration parameters are optional - any missing values will use the defaults shown above

API Relationship

These configuration parameters directly affect API behavior:

• max_request_size_bytes: Determines when /v1/commit returns 413 Content Too Large
• min_request_id_length: Validates request_id fields in /v1/commit requests
• request_id_retention_*: Affects availability of data for /v1/status queries and likelihood of log_truncated responses
• max_buffer_size_bytes: Controls when /v1/subscribe connections are terminated due to slow consumption
• keepalive_interval_seconds: Frequency of keepalive comments in /v1/subscribe streams