server.toml

# KalamDB Server Configuration
# This is an example configuration file with all available settings.
# Copy this file to config.toml and adjust values for your environment.
#
# NOTE: Runtime configuration only!
# - Namespace and storage location configuration is stored in system tables (via kalamdb-sql)
# - This file contains only server runtime settings (ports, paths, limits, etc.)

[server]
# Server bind address (default: 127.0.0.1)
host = "127.0.0.1"

# Server port (default: 8080)
port = 8080

# Number of worker threads (0 = number of CPU cores)
workers = 0

# Enable HTTP/2 protocol support (default: true)
# When true, server uses automatic HTTP/1.1 and HTTP/2 cleartext (h2c) negotiation
# When false, server only supports HTTP/1.1
# HTTP/2 offers:
# - Multiplexed requests (multiple requests on single connection)
# - Header compression (HPACK)
# - Binary protocol (more efficient parsing)
# - Server push support (for future features)
enable_http2 = true

# API version (default: "v1")
# Controls the versioned endpoint prefix (e.g., /v1/api/sql)
api_version = "v1"

[storage]
# Base data directory for all KalamDB storage
# Subdirectories are automatically created:
#   ./data/rocksdb  - RocksDB hot storage (write buffer)
#   ./data/storage  - Parquet cold storage (flushed segments)
#   ./data/snapshots - Raft snapshots (consensus state)
data_path = "./data"

# Templates for table storage paths (used by 'local' storage)
# Available placeholders: {namespace}, {tableName}, {userId}
# Final paths: {data_path}/storage/{template}
# Examples:
#   Shared table: ./data/storage/myapp/products
#   User table: ./data/storage/myapp/preferences/user123
shared_tables_template = "{namespace}/{tableName}"
user_tables_template = "{namespace}/{tableName}/{userId}"

[storage.rocksdb]
# Block cache size for reads in bytes (default: 2MB)
block_cache_size = 2097152

max_background_jobs = 4

[storage.rocksdb.cf_profiles.system_meta]
write_buffer_size = 32768
max_write_buffers = 2

[storage.rocksdb.cf_profiles.system_index]
write_buffer_size = 32768
max_write_buffers = 2

[storage.rocksdb.cf_profiles.hot_data]
write_buffer_size = 131072
max_write_buffers = 2

[storage.rocksdb.cf_profiles.hot_index]
write_buffer_size = 65536
max_write_buffers = 2

[storage.rocksdb.cf_profiles.raft]
write_buffer_size = 262144
max_write_buffers = 2

[datafusion]
# Memory limit for query execution in bytes (default: 64MB)
# KalamDB is optimised for mobile/OLTP workloads, not heavy analytics.
# 64 MB is sufficient for key-based lookups and small aggregates.
memory_limit = 67108864

# Number of parallel threads for query execution (default: 2)
query_parallelism = 2

# Maximum number of partitions per query (default: 4)
max_partitions = 4

# Batch size for record processing (default: 1024 rows)
batch_size = 1024

[manifest_cache]
# Eviction job interval in seconds (default: 300s = 5 minutes)
eviction_interval_seconds = 300

# Maximum number of cached manifest entries (default: 500)
max_entries = 500

# TTL in days for manifest eviction (default: 7 days)
eviction_ttl_days = 7

# Weight factor for user table manifests (default: 10)
# User tables are evicted N times faster than shared tables.
user_table_weight_factor = 10

[flush]
# Default row limit for flush policies (default: 10000 rows)
# Tables without explicit flush policy will use this value
default_row_limit = 10000

# Default time interval for flush in seconds (default: 300s = 5 minutes)
# Tables will flush to Parquet after this duration
default_time_interval = 300

# Batch size for flush operations (default: 10000 rows)
# Controls how many rows are loaded into memory at once during flush
# Lower values reduce memory usage but may increase flush duration
# Set to 0 to load all rows at once (not recommended for large tables)
flush_batch_size = 10000

# How often the background scheduler checks for tables with pending writes
# and creates flush jobs (default: 60 seconds). Set to 0 to disable.
check_interval_seconds = 60

[retention]
# Default retention hours for soft-deleted rows (default: 168 hours = 7 days)
# Rows with _deleted=true will be kept in Parquet files for this duration
default_deleted_retention_hours = 168

[stream]
# Default TTL for stream table rows in seconds (default: 10 seconds)
# Stream tables are ephemeral - rows expire after this duration
default_ttl_seconds = 10

# Default maximum buffer size for stream tables (default: 10000 rows)
# Oldest rows are evicted when buffer exceeds this limit
default_max_buffer = 10000

# Stream eviction interval in seconds (default: 60 seconds = 1 minute)
# How often the background task checks and evicts expired events
eviction_interval_seconds = 60

[limits]
# Maximum message size for REST API requests in bytes (default: 1MB)
max_message_size = 1048576

# Maximum rows that can be returned in a single query (default: 1000)
max_query_limit = 1000

# Default LIMIT for queries without explicit LIMIT clause (default: 50)
default_query_limit = 50

[logging]
# Log level: error, warn, info, debug, trace (default: info)
level = "debug"

# Directory for all log files (default: "./logs")
# Server will create app.log, slow.log, and other log files in this directory
logs_path = "./logs"

# Also log to console/stdout (default: true)
log_to_console = true

# Log format: compact, pretty, json (default: compact)
format = "json"

# Slow query logging threshold in milliseconds (default: 1000ms = 1 second)
# Queries taking longer than this threshold will be logged to slow.log
# AND displayed as WARN in the console
# Set to a high value (e.g., 999999) to disable slow query logging
slow_query_threshold_ms = 1000

[logging.otlp]
enabled = true
endpoint = "http://127.0.0.1:4317"
protocol = "grpc"
service_name = "kalamdb-server"
timeout_ms = 3000

[performance]
# Request timeout in seconds (default: 30s)
# Requests exceeding this duration will be terminated
request_timeout = 30

# Keep-alive timeout in seconds (default: 75s)
keepalive_timeout = 75

# Maximum concurrent connections (default: 25000)
# Includes both REST API and WebSocket connections
max_connections = 25000

[rate_limit]
# Maximum SQL queries per second per user (default: 100)
# Prevents query flooding from a single user
# NOTE: Set higher for development/testing environments
max_queries_per_sec = 100000

# Maximum WebSocket messages per second per connection (default: 50)
# Prevents message flooding on WebSocket connections
max_messages_per_sec = 10000

# Maximum concurrent live query subscriptions per user (default: 10)
# Limits total active subscriptions to prevent resource exhaustion
max_subscriptions_per_user = 100

# Maximum auth requests per second per IP (default: 20)
# Applies to login/refresh/setup endpoints to slow brute-force attacks
max_auth_requests_per_ip_per_sec = 50

# ==========================================================================
# Security Settings
# ==========================================================================
# CORS, WebSocket, and request limit configuration

[security]
# Maximum request body size in bytes (default: 10MB)
# Prevents memory exhaustion from large payloads
max_request_body_size = 10485760

# Maximum WebSocket message size in bytes (default: 1MB)
# Prevents memory exhaustion from large WebSocket messages
max_ws_message_size = 1048576

# Allowed WebSocket origins (if different from CORS origins)
# Leave empty to use CORS allowed_origins for WebSocket validation
allowed_ws_origins = []

# Strict WebSocket origin checking (default: false)
# If true, rejects WebSocket connections without Origin header
strict_ws_origin_check = false

# CORS Configuration (uses actix-cors)
# See: https://docs.rs/actix-cors
[security.cors]
# Allowed origins for CORS requests
# Use ["*"] or empty [] for any origin (development mode)
# For production, specify exact origins: ["https://app.example.com", "https://admin.example.com"]
allowed_origins = []

# Allowed HTTP methods (default: common REST methods)
allowed_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]

# Allowed HTTP headers
# Use ["*"] to allow any header
allowed_headers = ["Authorization", "Content-Type", "Accept", "Origin", "X-Requested-With"]

# Headers to expose to the browser (default: none)
# Example: ["X-Custom-Header", "X-Request-Id"]
expose_headers = []

# Allow credentials (cookies, authorization headers) (default: true)
# Note: If true, allowed_origins cannot be ["*"] in browsers
allow_credentials = true

# Preflight request cache max age in seconds (default: 3600 = 1 hour)
max_age = 3600

# Allow private network requests (default: false)
# Enables Access-Control-Request-Private-Network header support
allow_private_network = false

[authentication]
# Bcrypt cost factor for password hashing (default: 12, range: 10-14)
# Higher values = more secure but slower
# Changing this only affects NEW passwords
bcrypt_cost = 12

# Minimum password length (default: 8)
min_password_length = 8

# Maximum password length (default: 72, bcrypt limit)
# Note: Passwords longer than 72 bytes are truncated by bcrypt
max_password_length = 72

# Disable common password checking (default: false)
# If true, allows passwords like "password", "123456", etc.
# WARNING: Only disable for testing/development environments!
disable_common_password_check = false

# JWT configuration (for JWT Bearer token authentication)
# Secret key for JWT signature validation (minimum 32 characters recommended)
# IMPORTANT: Change this in production! Use a strong, random secret.
jwt_secret = "your-secret-key-at-least-32-chars-change-me-in-production"

# Allow initial server setup from non-localhost clients (default: false)
# Useful for Docker or remote hosts in trusted networks.
# WARNING: Only enable in trusted environments.
allow_remote_setup = false

# List of trusted JWT issuers (leave empty to accept any issuer)
# Add your OAuth provider domains here (e.g., "https://accounts.google.com", "https://github.com")
# Example for Google OAuth: ["https://accounts.google.com"]
# Example for GitHub OAuth: ["https://github.com"]
# Multiple issuers: ["https://accounts.google.com", "https://github.com", "https://kalamdb.io"]
jwt_trusted_issuers = ""

# Auto-create local OAuth users from trusted provider subject/issuer when not found (default: false)
auto_create_users_from_provider = false

[shutdown]
# Timeout settings for graceful shutdown

[shutdown.flush]
# Timeout in seconds to wait for flush jobs to complete during graceful shutdown (default: 300)
timeout = 300

# Maximum number of concurrent jobs (default: 10)
# Controls how many jobs can execute simultaneously
max_concurrent = 10

# Maximum number of retry attempts per job (default: 3)
# Jobs will be retried this many times before being marked as permanently failed
max_retries = 3

# Initial retry backoff delay in milliseconds (default: 100ms)
# Delay increases exponentially with each retry (100ms, 200ms, 400ms, etc.)
retry_backoff_ms = 100

# Phase 11, T026: SQL Handler Execution Configuration
[execution]
# Handler execution timeout in seconds (default: 30)
# Maximum time allowed for a single SQL statement to execute
# Prevents hung requests from blocking resources
handler_timeout_seconds = 30

# Maximum number of parameters per statement (default: 50)
# Prevents memory exhaustion from excessive parameter arrays
max_parameters = 50

# Maximum size per parameter in bytes (default: 524288 = 512KB)
# Prevents memory exhaustion from individual large parameters
max_parameter_size_bytes = 524288

# Maximum number of cached SQL logical plans (default: 200)
# Bound memory used by SQL plan cache
sql_plan_cache_max_entries = 200

# Time-to-idle TTL for SQL cached plans in seconds (default: 900 = 15 minutes)
# Unused plans are evicted automatically after this idle period
sql_plan_cache_ttl_seconds = 900

# ==========================================================================
# CLUSTER CONFIGURATION (Raft-based Replication)
# ==========================================================================
# ==========================================================================
# Cluster Configuration (v0.2.0)
# ==========================================================================
# Uncomment this section to enable cluster mode with Raft consensus.
# When enabled, all metadata and data operations go through Raft for consistency.
#
# Single-node cluster (for testing):
#   - Set node_id to 1
#   - Leave peers empty
#   - The cluster will auto-initialize as leader
#
# Multi-node cluster:
#   - Set unique node_id for each node (1, 2, 3, ...)
#   - List all OTHER nodes in peers
#   - Node with node_id=1 automatically bootstraps the cluster

[cluster]
# # Unique identifier for this cluster
# cluster_id = "prd-cluster"
# 
# # This node's unique ID (must be >= 1)
# # Node with node_id=1 is the designated bootstrap node
node_id = 1
# 
# # RPC address for Raft inter-node communication
# rpc_addr = "0.0.0.0:9188"
# 
# # API address for client HTTP requests (should match server.host:server.port)
# api_addr = "0.0.0.0:8080"
# 
# # Number of user data shards (default: 32)
user_shards = 32
# 
# # Number of shared data shards (default: 1)
# shared_shards = 1
# 
# # Raft heartbeat interval in milliseconds (default: 250)
# heartbeat_interval_ms = 250
# 
# # Raft election timeout range [min, max] in milliseconds (default: [500, 1000])
# election_timeout_ms = [500, 1000]
# 
# # Snapshot policy (default: "LogsSinceLast(1000)")
# # Applies to both single-node and multi-node clusters.
# # Options:
# #   - "LogsSinceLast(N)" - Create snapshot after N log entries since last snapshot
# #   - "Never" - Disable automatic snapshots (not recommended for production)
# # 
# # Lower values (e.g., 100) create snapshots more frequently:
# #   + Faster follower catchup (smaller log to replay)
# #   + Smaller memory footprint
# #   - More disk I/O for snapshot creation
# # 
# # Higher values (e.g., 10000) reduce snapshot frequency:
# #   + Less disk I/O
# #   - Slower follower catchup
# #   - Larger memory footprint
# snapshot_policy = "LogsSinceLast(1000)"
# 
# # Maximum number of snapshots to keep (default: 3)
# # Older snapshots are automatically deleted. Set to 0 to keep all snapshots.
# # For single-node deployments, you may want to set this to 1 to minimize disk usage.
# # 
# # Examples:
# #   max_snapshots_to_keep = 1   # Keep only the most recent snapshot (minimal disk usage)
# #   max_snapshots_to_keep = 3   # Keep last 3 snapshots (balanced approach)
# #   max_snapshots_to_keep = 0   # Keep all snapshots (useful for backup/recovery)
# max_snapshots_to_keep = 3
# 
# # Timeout in milliseconds to wait for learner catchup during cluster membership changes
# # (default: 5000ms = 5 seconds)
# replication_timeout_ms = 5000
# 
# # Minimum interval in milliseconds between reconnect attempts to an unreachable peer
# # (default: 3000ms = 3 seconds)
# reconnect_interval_ms = 3000
# 
# # NOTE: OpenRaft uses standard Raft quorum: (N/2)+1
# # For 3 nodes: quorum = 2 (majority required for commit)
# # For 5 nodes: quorum = 3
# # This is hardcoded in the Raft protocol and cannot be configured.
# # There is NO min_replication_nodes setting - Raft always uses quorum.
# 
# # Peer nodes (list all OTHER nodes in the cluster)
# # [[cluster.peers]]
# # node_id = 2
# # rpc_addr = "10.0.0.2:9188"
# # api_addr = "http://10.0.0.2:8080"
# #
# # [[cluster.peers]]
# # node_id = 3
# # rpc_addr = "10.0.0.3:9188"
# # api_addr = "http://10.0.0.3:8080"