Reference

Config Reference

Complete JSON configuration reference with all options and defaults.

Full Configuration Template

Below is the complete config.json structure with all default values. Only include the sections you need to override.

config/config.json

{
  "debug": false,
  "host": "0.0.0.0",
  "port": 6001,
  "mode": "production",
  "path_prefix": "/",
  "activity_timeout": 120,
  "shutdown_grace_period": 10,
  "user_authentication_timeout": 3600,
  "websocket_max_payload_kb": 64,

  "instance": {
    "process_id": "<auto-generated-uuid>"
  },

  "adapter": {
    "driver": "local",
    "buffer_multiplier_per_cpu": 64,
    "enable_socket_counting": true,
    "redis": {
      "requests_timeout": 5000,
      "prefix": "sockudo_adapter:",
      "redis_pub_options": {},
      "redis_sub_options": {},
      "cluster_mode": false
    },
    "cluster": {
      "nodes": [],
      "prefix": "sockudo_adapter:",
      "request_timeout_ms": 1000,
      "use_connection_manager": true,
      "use_sharded_pubsub": false
    },
    "nats": {
      "servers": ["nats://localhost:4222"],
      "prefix": "sockudo_adapter:",
      "request_timeout_ms": 5000,
      "username": null,
      "password": null,
      "token": null,
      "connection_timeout_ms": 5000,
      "nodes_number": null
    },
    "cluster_health": {
      "enabled": true,
      "heartbeat_interval_ms": 10000,
      "node_timeout_ms": 30000,
      "cleanup_interval_ms": 10000
    }
  },

  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "app-id",
          "key": "app-key",
          "secret": "app-secret",
          "enabled": true,
          "enable_client_messages": false,
          "max_connections": 100,
          "max_client_events_per_second": 100,
          "max_read_requests_per_second": 100,
          "max_backend_events_per_second": 100,
          "max_presence_members_per_channel": 100,
          "max_presence_member_size_in_kb": 100,
          "max_channel_name_length": 100,
          "max_event_channels_at_once": 100,
          "max_event_name_length": 100,
          "max_event_payload_in_kb": 100,
          "max_event_batch_size": 100,
          "enable_user_authentication": false,
          "enable_watchlist_events": false,
          "allowed_origins": null,
          "webhooks": null,
          "channel_delta_compression": null
        }
      ]
    },
    "cache": {
      "enabled": true,
      "ttl": 300
    },
    "scylladb": {
      "nodes": ["127.0.0.1:9042"],
      "keyspace": "sockudo",
      "table_name": "applications",
      "username": null,
      "password": null,
      "replication_class": "SimpleStrategy",
      "replication_factor": 3
    }
  },

  "cache": {
    "driver": "memory",
    "redis": {
      "prefix": "sockudo_cache:",
      "url_override": null,
      "cluster_mode": false
    },
    "memory": {
      "ttl": 300,
      "cleanup_interval": 60,
      "max_capacity": 10000
    }
  },

  "channel_limits": {
    "max_name_length": 200,
    "cache_ttl": 3600
  },

  "cors": {
    "credentials": true,
    "origin": ["*"],
    "methods": ["GET", "POST", "OPTIONS"],
    "allowed_headers": ["Authorization", "Content-Type", "X-Requested-With", "Accept"]
  },

  "database": {
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "username": "root",
      "password": "",
      "database": "sockudo",
      "table_name": "applications",
      "connection_pool_size": 10,
      "pool_min": null,
      "pool_max": null,
      "cache_ttl": 300,
      "cache_cleanup_interval": 60,
      "cache_max_capacity": 100
    },
    "postgres": {
      "host": "localhost",
      "port": 3306,
      "username": "root",
      "password": "",
      "database": "sockudo",
      "table_name": "applications",
      "connection_pool_size": 10,
      "pool_min": null,
      "pool_max": null,
      "cache_ttl": 300,
      "cache_cleanup_interval": 60,
      "cache_max_capacity": 100
    },
    "redis": {
      "host": "127.0.0.1",
      "port": 6379,
      "db": 0,
      "username": null,
      "password": null,
      "key_prefix": "sockudo:",
      "sentinels": [],
      "sentinel_password": null,
      "name": "mymaster",
      "cluster": {
        "nodes": [],
        "username": null,
        "password": null,
        "use_tls": false
      },
      "cluster_nodes": []
    },
    "dynamodb": {
      "region": "us-east-1",
      "table_name": "sockudo-applications",
      "endpoint_url": null,
      "aws_access_key_id": null,
      "aws_secret_access_key": null,
      "aws_profile_name": null
    },
    "scylladb": {
      "nodes": ["127.0.0.1:9042"],
      "keyspace": "sockudo",
      "table_name": "applications",
      "username": null,
      "password": null,
      "replication_class": "SimpleStrategy",
      "replication_factor": 3
    }
  },

  "database_pooling": {
    "enabled": true,
    "min": 2,
    "max": 10
  },

  "event_limits": {
    "max_channels_at_once": 100,
    "max_name_length": 200,
    "max_payload_in_kb": 100,
    "max_batch_size": 10
  },

  "http_api": {
    "request_limit_in_mb": 10,
    "accept_traffic": {
      "memory_threshold": 0.90
    }
  },

  "logging": {
    "colors_enabled": true,
    "include_target": true
  },

  "metrics": {
    "enabled": true,
    "driver": "prometheus",
    "host": "0.0.0.0",
    "port": 9601,
    "prometheus": {
      "prefix": "sockudo_"
    }
  },

  "presence": {
    "max_members_per_channel": 100,
    "max_member_size_in_kb": 2
  },

  "queue": {
    "driver": "redis",
    "redis": {
      "concurrency": 5,
      "prefix": "sockudo_queue:",
      "url_override": null,
      "cluster_mode": false
    },
    "redis_cluster": {
      "concurrency": 5,
      "prefix": "sockudo_queue:",
      "nodes": ["redis://127.0.0.1:6379"],
      "request_timeout_ms": 5000
    },
    "sqs": {
      "region": "us-east-1",
      "queue_url_prefix": null,
      "visibility_timeout": 30,
      "endpoint_url": null,
      "max_messages": 10,
      "wait_time_seconds": 5,
      "concurrency": 5,
      "fifo": false,
      "message_group_id": "default"
    }
  },

  "rate_limiter": {
    "enabled": true,
    "driver": "memory",
    "api_rate_limit": {
      "max_requests": 100,
      "window_seconds": 60,
      "identifier": "api",
      "trust_hops": 0
    },
    "websocket_rate_limit": {
      "max_requests": 20,
      "window_seconds": 60,
      "identifier": "websocket_connect",
      "trust_hops": 0
    },
    "redis": {
      "prefix": "sockudo_rl:",
      "url_override": null,
      "cluster_mode": false
    }
  },

  "ssl": {
    "enabled": false,
    "cert_path": "",
    "key_path": "",
    "passphrase": null,
    "ca_path": null,
    "redirect_http": false,
    "http_port": 80
  },

  "unix_socket": {
    "enabled": false,
    "path": "/var/run/sockudo/sockudo.sock",
    "permission_mode": "660"
  },

  "webhooks": {
    "batching": {
      "enabled": true,
      "duration": 50
    }
  },

  "cleanup": {
    "async_enabled": true,
    "fallback_to_sync": true,
    "queue_buffer_size": 50000,
    "batch_size": 25,
    "batch_timeout_ms": 50,
    "worker_threads": "auto",
    "max_retry_attempts": 2
  },

  "cluster_health": {
    "enabled": true,
    "heartbeat_interval_ms": 10000,
    "node_timeout_ms": 30000,
    "cleanup_interval_ms": 10000
  },

  "delta_compression": {
    "enabled": true,
    "algorithm": "fossil",
    "full_message_interval": 10,
    "min_message_size": 100,
    "max_state_age_secs": 300,
    "max_channel_states_per_socket": 100,
    "max_conflation_states_per_channel": 100,
    "conflation_key_path": null,
    "cluster_coordination": false,
    "omit_delta_algorithm": false
  },

  "tag_filtering": {
    "enabled": false,
    "enable_tags": true
  },

  "websocket": {
    "max_messages": 1000,
    "max_bytes": null,
    "disconnect_on_buffer_full": true,
    "max_message_size": 67108864,
    "max_frame_size": 16777216,
    "write_buffer_size": 16384,
    "max_backpressure": 1048576,
    "auto_ping": true,
    "ping_interval": 30,
    "idle_timeout": 120,
    "compression": "disabled"
  }
}

Section Reference

`adapter`

Controls the pub/sub transport used for horizontal scaling.

Field	Type	Default	Description
`driver`	`string`	`local`	`local`, `redis`, `redis-cluster`, `nats`
`buffer_multiplier_per_cpu`	`number`	`64`	Concurrent operations per CPU core
`enable_socket_counting`	`bool`	`true`	Track socket counts across cluster nodes

`adapter.redis`

Field	Type	Default	Description
`requests_timeout`	`number`	`5000`	Request timeout in ms
`prefix`	`string`	`sockudo_adapter:`	Redis key prefix
`redis_pub_options`	`object`	`{}`	Extra options for pub connection
`redis_sub_options`	`object`	`{}`	Extra options for sub connection
`cluster_mode`	`bool`	`false`	Use cluster-aware connections

`adapter.cluster` (Redis Cluster)

Field	Type	Default	Description
`nodes`	`string[]`	`[]`	Cluster seed node URLs
`prefix`	`string`	`sockudo_adapter:`	Key prefix
`request_timeout_ms`	`number`	`1000`	Request timeout in ms
`use_connection_manager`	`bool`	`true`	Use connection manager
`use_sharded_pubsub`	`bool`	`false`	Use `SSUBSCRIBE`/`SPUBLISH` (Redis 7.0+)

`adapter.nats`

Field	Type	Default	Description
`servers`	`string[]`	`["nats://localhost:4222"]`	NATS server URLs
`prefix`	`string`	`sockudo_adapter:`	Subject prefix
`request_timeout_ms`	`number`	`5000`	Request timeout in ms
`username`	`string?`	`null`	NATS username
`password`	`string?`	`null`	NATS password
`token`	`string?`	`null`	NATS auth token
`connection_timeout_ms`	`number`	`5000`	Connection timeout in ms
`nodes_number`	`number?`	`null`	Expected cluster size

`app_manager`

Field	Type	Default	Description
`driver`	`string`	`memory`	`memory`, `mysql`, `postgres`, `dynamodb`, `scylladb`
`array.apps`	`App[]`	`[]`	In-memory app definitions
`cache.enabled`	`bool`	`true`	Cache app lookups
`cache.ttl`	`number`	`300`	Cache TTL in seconds

`app_manager.scylladb`

Field	Type	Default	Description
`nodes`	`string[]`	`["127.0.0.1:9042"]`	ScyllaDB contact points
`keyspace`	`string`	`sockudo`	Keyspace name
`table_name`	`string`	`applications`	Table name
`username`	`string?`	`null`	Auth username
`password`	`string?`	`null`	Auth password
`replication_class`	`string`	`SimpleStrategy`	Replication strategy
`replication_factor`	`number`	`3`	Replication factor

`cache`

Field	Type	Default	Description
`driver`	`string`	`memory`	`memory`, `redis`, `redis-cluster`, `none`

`cache.redis`

Field	Type	Default	Description
`prefix`	`string?`	`sockudo_cache:`	Redis key prefix
`url_override`	`string?`	`null`	Override Redis URL
`cluster_mode`	`bool`	`false`	Use cluster mode

`cache.memory`

Field	Type	Default	Description
`ttl`	`number`	`300`	TTL in seconds
`cleanup_interval`	`number`	`60`	Cleanup interval in seconds
`max_capacity`	`number`	`10000`	Max cache entries

`channel_limits`

Field	Type	Default	Description
`max_name_length`	`number`	`200`	Max channel name length
`cache_ttl`	`number`	`3600`	Channel cache TTL in seconds

`cors`

Field	Type	Default	Description
`credentials`	`bool`	`true`	Allow credentials
`origin`	`string[]`	`["*"]`	Allowed origins
`methods`	`string[]`	`["GET","POST","OPTIONS"]`	Allowed methods
`allowed_headers`	`string[]`	`["Authorization","Content-Type","X-Requested-With","Accept"]`	Allowed headers

`database`

`database.mysql` / `database.postgres`

Field	Type	Default	Description
`host`	`string`	`localhost`	Database host
`port`	`number`	`3306`	Database port
`username`	`string`	`root`	Username
`password`	`string`	`""`	Password
`database`	`string`	`sockudo`	Database name
`table_name`	`string`	`applications`	Table name
`connection_pool_size`	`number`	`10`	Connection pool size
`pool_min`	`number?`	`null`	Min pool connections
`pool_max`	`number?`	`null`	Max pool connections
`cache_ttl`	`number`	`300`	Query cache TTL in seconds
`cache_cleanup_interval`	`number`	`60`	Cache cleanup interval
`cache_max_capacity`	`number`	`100`	Max cached entries

`database.redis`

Field	Type	Default	Description
`host`	`string`	`127.0.0.1`	Redis host
`port`	`number`	`6379`	Redis port
`db`	`number`	`0`	Database index
`username`	`string?`	`null`	ACL username
`password`	`string?`	`null`	Password
`key_prefix`	`string`	`sockudo:`	Key prefix
`sentinels`	`Sentinel[]`	`[]`	Sentinel nodes
`sentinel_password`	`string?`	`null`	Sentinel auth password
`name`	`string`	`mymaster`	Sentinel master name

`database.redis.cluster`

Field	Type	Default	Description
`nodes`	`ClusterNode[]`	`[]`	Cluster seed nodes
`username`	`string?`	`null`	Cluster auth username
`password`	`string?`	`null`	Cluster auth password
`use_tls`	`bool`	`false`	Enable TLS for cluster

`database.dynamodb`

Field	Type	Default	Description
`region`	`string`	`us-east-1`	AWS region
`table_name`	`string`	`sockudo-applications`	Table name
`endpoint_url`	`string?`	`null`	Custom endpoint
`aws_access_key_id`	`string?`	`null`	AWS access key
`aws_secret_access_key`	`string?`	`null`	AWS secret key
`aws_profile_name`	`string?`	`null`	AWS profile name

`database_pooling`

Global pool settings (can be overridden per-database).

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable connection pooling
`min`	`number`	`2`	Min connections
`max`	`number`	`10`	Max connections

`event_limits`

Field	Type	Default	Description
`max_channels_at_once`	`number`	`100`	Max channels per event
`max_name_length`	`number`	`200`	Max event name length
`max_payload_in_kb`	`number`	`100`	Max payload size in KB
`max_batch_size`	`number`	`10`	Max events per batch

`http_api`

Field	Type	Default	Description
`request_limit_in_mb`	`number`	`10`	Max request body in MB
`accept_traffic.memory_threshold`	`number`	`0.90`	Reject traffic above this memory usage ratio

`presence`

Field	Type	Default	Description
`max_members_per_channel`	`number`	`100`	Max presence members per channel
`max_member_size_in_kb`	`number`	`2`	Max member info size in KB

`queue`

Field	Type	Default	Description
`driver`	`string`	`redis`	`memory`, `redis`, `redis-cluster`, `sqs`, `none`

`queue.redis`

Field	Type	Default	Description
`concurrency`	`number`	`5`	Concurrent workers
`prefix`	`string?`	`sockudo_queue:`	Key prefix
`url_override`	`string?`	`null`	Override Redis URL
`cluster_mode`	`bool`	`false`	Use cluster mode

`queue.redis_cluster`

Field	Type	Default	Description
`concurrency`	`number`	`5`	Concurrent workers
`prefix`	`string?`	`sockudo_queue:`	Key prefix
`nodes`	`string[]`	`["redis://127.0.0.1:6379"]`	Cluster node URLs
`request_timeout_ms`	`number`	`5000`	Request timeout in ms

`queue.sqs`

Field	Type	Default	Description
`region`	`string`	`us-east-1`	AWS region
`queue_url_prefix`	`string?`	`null`	SQS queue URL prefix
`visibility_timeout`	`number`	`30`	Visibility timeout in seconds
`endpoint_url`	`string?`	`null`	Custom endpoint
`max_messages`	`number`	`10`	Max messages per poll
`wait_time_seconds`	`number`	`5`	Long polling wait
`concurrency`	`number`	`5`	Concurrent workers
`fifo`	`bool`	`false`	Use FIFO queue
`message_group_id`	`string?`	`default`	FIFO message group ID

`rate_limiter`

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable rate limiting
`driver`	`string`	`memory`	Backend: `memory`, `redis`, `redis-cluster`, `none`

`rate_limiter.api_rate_limit` / `rate_limiter.websocket_rate_limit`

Field	Type	Default (API / WS)	Description
`max_requests`	`number`	`100` / `20`	Max requests per window
`window_seconds`	`number`	`60` / `60`	Window duration
`identifier`	`string?`	`api` / `websocket_connect`	Rate limit identifier
`trust_hops`	`number?`	`0` / `0`	Trusted proxy hops

`rate_limiter.redis`

Field	Type	Default	Description
`prefix`	`string?`	`sockudo_rl:`	Redis key prefix
`url_override`	`string?`	`null`	Override Redis URL
`cluster_mode`	`bool`	`false`	Use cluster mode

`ssl`

Field	Type	Default	Description
`enabled`	`bool`	`false`	Enable TLS
`cert_path`	`string`	`""`	Certificate file path
`key_path`	`string`	`""`	Private key file path
`passphrase`	`string?`	`null`	Key passphrase
`ca_path`	`string?`	`null`	CA certificate path
`redirect_http`	`bool`	`false`	Redirect HTTP to HTTPS
`http_port`	`number?`	`80`	HTTP port for redirect

`unix_socket`

Field	Type	Default	Description
`enabled`	`bool`	`false`	Enable Unix socket
`path`	`string`	`/var/run/sockudo/sockudo.sock`	Socket path (must be absolute)
`permission_mode`	`string`	`660`	Octal permissions

`webhooks`

Field	Type	Default	Description
`batching.enabled`	`bool`	`true`	Enable webhook batching
`batching.duration`	`number`	`50`	Batch window in ms

`cleanup`

Field	Type	Default	Description
`async_enabled`	`bool`	`true`	Enable async disconnect processing
`fallback_to_sync`	`bool`	`true`	Fall back to sync if async fails
`queue_buffer_size`	`number`	`50000`	Queue buffer size
`batch_size`	`number`	`25`	Batch size
`batch_timeout_ms`	`number`	`50`	Max batch wait time in ms
`worker_threads`	`string\|number`	`"auto"`	Worker count: `"auto"` or a number
`max_retry_attempts`	`number`	`2`	Max retries for failed cleanups

`cluster_health`

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable health monitoring
`heartbeat_interval_ms`	`number`	`10000`	Heartbeat interval
`node_timeout_ms`	`number`	`30000`	Dead node timeout
`cleanup_interval_ms`	`number`	`10000`	Dead node check interval

heartbeat_interval_ms must be at most node_timeout_ms / 3 to avoid false positive dead node detection.

`delta_compression`

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable delta compression
`algorithm`	`string`	`fossil`	Algorithm: `fossil` or `xdelta3`
`full_message_interval`	`number`	`10`	Full message every N messages
`min_message_size`	`number`	`100`	Min bytes to apply delta
`max_state_age_secs`	`number`	`300`	Max delta state age in seconds
`max_channel_states_per_socket`	`number`	`100`	Max tracked channels per socket
`max_conflation_states_per_channel`	`number?`	`100`	Max conflation groups (entities) per channel
`conflation_key_path`	`string?`	`null`	Global JSON path for conflation key extraction (e.g., `"asset"`, `"data.symbol"`)
`cluster_coordination`	`bool`	`false`	Coordinate deltas across cluster nodes
`omit_delta_algorithm`	`bool`	`false`	Omit algorithm field from delta messages to save bandwidth

Conflation Configuration

Conflation keys group messages by entity for improved compression. Set globally with conflation_key_path or per-channel via channel_delta_compression.

Global default:

{
  "delta_compression": {
    "conflation_key_path": "asset"
  }
}

Per-channel override (in app config):

{
  "channel_delta_compression": {
    "market:*": {
      "enabled": true,
      "conflation_key": "symbol",
      "max_messages_per_key": 100,
      "max_conflation_keys": 1000
    }
  }
}

Per-Channel Field	Type	Description
`conflation_key`	`string?`	JSON path to extract entity identifier (overrides `conflation_key_path`)
`max_messages_per_key`	`number`	Number of messages to cache per entity
`max_conflation_keys`	`number`	Maximum entities to track simultaneously

See Delta Compression for detailed conflation documentation.

`tag_filtering`

Field	Type	Default	Description
`enabled`	`bool`	`false`	Enable tag-based message filtering
`enable_tags`	`bool`	`true`	Include tags in messages

`websocket`

Field	Type	Default	Description
`max_messages`	`number?`	`1000`	Max buffered messages (`null` to disable)
`max_bytes`	`number?`	`null`	Max buffered bytes (`null` to disable)
`disconnect_on_buffer_full`	`bool`	`true`	Disconnect vs drop on buffer full
`max_message_size`	`number`	`67108864`	Max message size (64 MB)
`max_frame_size`	`number`	`16777216`	Max frame size (16 MB)
`write_buffer_size`	`number`	`16384`	Write buffer size (16 KB)
`max_backpressure`	`number`	`1048576`	Max backpressure (1 MB)
`auto_ping`	`bool`	`true`	Enable automatic pings
`ping_interval`	`number`	`30`	Ping interval in seconds
`idle_timeout`	`number`	`120`	Idle timeout in seconds (0 disables)
`compression`	`string`	`disabled`	Compression: `disabled`, `dedicated`, `shared`, `window256b`, `window1kb`, `window2kb`, `window4kb`, `window8kb`, `window16kb`, `window32kb`

`logging`

Optional section. If omitted, defaults apply.

Field	Type	Default	Description
`colors_enabled`	`bool`	`true`	Enable colored log output
`include_target`	`bool`	`true`	Include target module in log lines

Treat the full template as a baseline profile and override per environment with env vars. Only include sections you need to customize.

HTTP Endpoints

Full list of Sockudo operational and API endpoints.

Compatibility Matrix

Client/integration compatibility for Sockudo core and advanced features.