Configuration reference

Reference major Sockudo configuration sections and the deployment decisions they control.

Sockudo's TOML configuration is organized by runtime responsibility.

For deployment overrides and secrets, use the complete environment variable reference. It lists every runtime variable parsed by the server and push subsystem.

Top-level

Key	Purpose
`host`	Bind host for WebSocket and HTTP API.
`port`	Bind port for WebSocket and HTTP API.
`debug`	Enables verbose diagnostics for local development.

App manager

Section	Purpose
`[app_manager]`	Select app storage driver.
`[app_manager.array]`	Static in-config app definitions.
`[[app_manager.array.apps]]`	App ID, key, secret, enabled flag, limits, and policy.

Runtime backends

Section	Purpose
`[adapter]`	Cross-node fanout.
`[cache]`	Shared cache and coordination.
`[queue]`	Webhook and push background work.
`[rate_limiter]`	Request, connection, event, and push limits.

[database.redis] configures the Redis connection used by the Redis adapter, cache, queue, and rate limiter. When sentinels is non-empty, Sockudo connects through Redis Sentinel using a native Sentinel client (rather than a direct URL) and can secure both connection hops independently.

Key	Purpose
`sentinels`	List of `{ host, port }` Sentinel nodes. A non-empty list enables Sentinel mode.
`name`	Monitored master (Sentinel service) name.
`username` / `password`	Auth for the master/replica data connection.
`sentinel_username` / `sentinel_password`	Auth for the Sentinel control connection.
`[database.redis.sentinel_tls]`	TLS for the client→Sentinel control connection.
`[database.redis.master_tls]`	TLS for the client→master/replica data connection.

Each TLS block accepts enabled, accept_invalid_certs (skips verification; dangerous), ca_path (PEM CA for private CAs), and client_cert_path + client_key_path (PEM pair for mutual TLS / client-certificate auth).

[database.redis]
name = "mymaster"
db = 0
username = "appuser"
password = "app-secret"
sentinel_username = "sentineluser"
sentinel_password = "sentinel-secret"

[[database.redis.sentinels]]
host = "sentinel-1.internal"
port = 26379

[[database.redis.sentinels]]
host = "sentinel-2.internal"
port = 26379

[database.redis.sentinel_tls]
enabled = true
ca_path = "/etc/sockudo/tls/ca.pem"
client_cert_path = "/etc/sockudo/tls/client.pem"
client_key_path = "/etc/sockudo/tls/client.key"

[database.redis.master_tls]
enabled = true
ca_path = "/etc/sockudo/tls/ca.pem"
client_cert_path = "/etc/sockudo/tls/client.pem"
client_key_path = "/etc/sockudo/tls/client.key"

Note: Sentinel TLS currently secures the horizontal Redis adapter (pub/sub) path. A redis_pub_options.url override, if set, takes precedence and uses the standalone connection path instead.

Protocol features

Section	Purpose
`[recovery]`	V2 replay buffers and resume behavior.
`[history]`	Durable channel history.
`[versioned_messages]`	V2 mutable-message storage, version paging, and retention.
`[presence_history]`	Historical presence transitions and snapshots.
`[annotations]`	V2 annotation publish/delete/summary surfaces.
`[delta]`	Delta algorithms, cache size, and conflation behavior.
`[tag_filtering]`	V2 filter parsing and match controls.
`[webhooks]`	Webhook delivery, batching, and retry.
`[ai_transport]`	AI Transport validation and session-channel matching.
`[ai_transport.rollup]`	Append rollup egress coalescing and orphan tracking.
`[[ai_transport.channels]]`	Channel prefixes where AI Transport validation applies.

Push

Section	Purpose
`[push]`	Enables push, async behavior, limits, status retention.
`[push.providers.fcm]`	Firebase Cloud Messaging credentials.
`[push.providers.apns]`	Apple Push Notification service credentials.
`[push.providers.webpush]`	Web Push VAPID configuration.
`[push.providers.hms]`	Huawei Mobile Services credentials.
`[push.providers.wns]`	Windows Notification Service credentials.
`[[push_rules]]`	Optional channel-publish to push-notification rules.

Capability tokens

Protocol V2 capability tokens do not currently have a TOML [auth.capability_tokens] switch. They are accepted through the WebSocket token query parameter and refreshed with sockudo:auth. Limits are compiled constants in sockudo-core/src/capability_token.rs: HS256 only, max token size 8 KiB, max client_id 128 bytes, max jti 128 bytes, max lifetime 24 hours, and 30 seconds clock skew. Revocation uses signed HTTP POST /apps/{appId}/revocations and shared cache keys.

AI Transport and Mutable Defaults

Runtime config uses [versioned_messages]; VersionStore is the Rust trait/storage abstraction. There is no separate [version_store] TOML section in the current code.

The following block is machine checked by sockudo-core tests. Update it whenever code defaults change.

[versioned_messages]
enabled = false
driver = "memory"
max_page_size = 100
retention_window_seconds = 0
purge_interval_seconds = 300
purge_batch_size = 1000
max_purge_per_tick = 100000

[history]
enabled = false
rewind_enabled = true
backend = "postgres"
retention_window_seconds = 86400
max_page_size = 100
writer_shards = 16
writer_queue_capacity = 4096
purge_interval_seconds = 300
purge_batch_size = 1000
max_purge_per_tick = 100000

[history.postgres]
table_prefix = "sockudo_history"
write_timeout_ms = 5000

[presence_history]
enabled = false
retention_window_seconds = 86400
max_page_size = 100

[annotations]
enabled = false

[ai_transport]
enabled = false
max_accumulated_message_bytes = 1048576
max_appends_per_message = 4096
max_open_streaming_messages_per_channel = 1024

[ai_transport.rollup]
enabled = true
default_window_ms = 40
min_window_ms = 0
max_window_ms = 500
orphan_ttl_ms = 60000
wheel_tick_ms = 5
shards = 64

[push]
storage_driver = "memory"
queue_driver = "memory"
fcm_enabled = false
apns_enabled = false
webpush_enabled = false
hms_enabled = false
wns_enabled = false
accept_worker_count = 1
planner_worker_count = 1
shard_worker_count = 1
dispatch_worker_count = 1
feedback_worker_count = 1
queue_partition_count = 1
channel_shard_count = 1
fanout_fast_threshold = 10000
fanout_shard_size = 100000
fanout_sync_threshold = 0
backpressure_lag_threshold_secs = 60
publish_status_ttl_days = 30
stale_device_max_age_days = 90
dry_run = false
analytics_enabled = false
analytics_retention_days = 30
scheduler_interval_secs = 5

[push.retry]
max_attempts = 5
initial_backoff_ms = 1000
max_backoff_ms = 60000
max_elapsed_secs = 86400
jitter = true
respect_retry_after = true

[push.circuit_breaker]
failure_threshold = 5
cooldown_secs = 60
half_open_max_inflight = 10

[push.default_quotas]
acceptance_rps = 100
delivery_quota_daily = 0
fanout_max = 0
inflight_max = 1000

[push.payload_redaction]
redact_payload = true
redact_template_data = true
redact_provider_overrides = true
allow_debug_payload_logging = false

[[push_rules]]
enabled = true
channel_pattern = ""
event_filter = []
rate_limit_per_second = 100

[push_rules.payload_mapping]
title_field = "title"
body_field = "body"
template_data_field = "data"
include_remaining_fields = true

max_messages_per_channel, max_bytes_per_channel, max_events_per_channel, credential refs, and external key refs default to unset and are omitted from the checked block.

Observability

Section	Purpose
`[metrics]`	Enables metrics and configures the Prometheus scrape endpoint.
`[metrics.prometheus]`	Prometheus metric naming options.
`[metrics.tcp_exporter]`	Optional metrics-rs TCP event exporter for live clients and sidecars.
logging environment	Runtime log level and structured output.

Example production skeleton

host = "0.0.0.0"
port = 6001
debug = false

[adapter]
driver = "redis"

[cache]
driver = "redis"

[queue]
driver = "redis"

[metrics]
enabled = true
port = 9601

[metrics.tcp_exporter]
enabled = false
host = "127.0.0.1"
port = 5000
buffer_size = 1024

[push]
enabled = true
async_only = true
publish_status_ttl_seconds = 86400