Configuration

Service Framework uses a configuration object to control the runtime. You can build it programmatically or load from a JSON file.

The Configuration Object

The framework::configuration class holds settings for ports, TLS, JWT, logging, gossip, quotas, and more.

Minimal Configuration

cpp

#include <framework.hpp>

using namespace framework;

int main() {
    configuration config;
    config.ports_.node_port_.store(10000);
    config.ports_.client_port_.store(8080);

    framework::app app(config);
    app.run_http_service(8080);
    app.run();
    return 0;
}

Loading from a JSON File

cpp

configuration config;
config.load_from_json("config.json");

framework::app app(config);

After loading from JSON, you can synchronize the scopes array to the bitset:

cpp

config.sync_log_bitset();  // syncs logging_.scopes_ → logging_.scope_bitset_

JSON Config Reference

The JSON configuration structure maps to the configuration class fields. Strings use std::shared_ptr<const std::string> internally:

cpp

config.seed_.host_.store(std::make_shared<const std::string>("10.0.0.1"));

Ports & Seed

JSON key	C++ field	Type	Default	Description
`ports.node`	`ports_.node_port_`	integer	10000	Inter-node mesh port
`ports.client`	`ports_.client_port_`	integer	0	Default client listener port. Overridden by the port argument passed to `run_http_service(port)`. With default 0, no listener starts automatically — you must call `run_http_service()` explicitly.
`seed.enabled`	`seed_.enabled_`	boolean	false	Enable seed-based discovery
`seed.host`	`seed_.host_`	string	"127.0.0.1"	Seed node hostname
`seed.node_port`	`seed_.node_port_`	integer	0	Seed node mesh port
`seed.client_port`	`seed_.client_port_`	integer	0	Seed client port
`seed.retry_interval_ms`	`seed_.retry_interval_ms_`	integer	2000	Seed reconnect interval

Node

JSON key	C++ field	Type	Default	Description
`node.host`	`node_.host_`	string	"127.0.0.1"	Advertised hostname
`node.max_connections`	`node_.max_connections_`	integer	5	Max connections per peer
`node.max_peers`	`node_.max_peers_`	integer	8	Max total peers
`node.load_balance_strategy`	`node_.load_balance_strategy_`	string	"roundrobin"	"random", "roundrobin", "least_loaded"
`node.max_send_receivers`	`node_.max_send_receivers_`	integer	100	Max recipients per send
`node.metrics_interval_ms`	`node_.metrics_interval_ms_`	integer	60000	Metrics report interval
`node.app_key`	`node_.app_key_`	string	"default_app_key"	Application identifier
`node.max_frame_size`	`node_.max_frame_size_`	integer	65536	Max frame size (bytes)
`node.max_payload_size`	`node_.max_payload_size_`	integer	10MB	Max payload size (bytes)
`node.max_hops`	`node_.max_hops_`	integer	10	Max message propagation hops
`node.max_queue_size`	`node_.max_queue_size_`	integer	5000	Outbound message queue
`node.read_timeout_seconds`	`node_.read_timeout_seconds_`	integer	10	Read timeout

Gossip

JSON key	C++ field	Type	Default	Description
`gossip.hybrid_threshold`	`gossip_.hybrid_threshold_`	integer	10	Max peers for direct ping
`gossip.rumor_limit_per_frame`	`gossip_.rumor_limit_per_frame_`	integer	5	Max rumors per gossip cycle
`gossip.cycle_interval_ms`	`gossip_.cycle_interval_ms_`	integer	1000	Gossip cycle interval
`gossip.suspect_timeout_s`	`gossip_.suspect_timeout_s_`	integer	10	Time before marking suspect
`gossip.dead_timeout_s`	`gossip_.dead_timeout_s_`	integer	30	Time before marking dead
`gossip.prune_timeout_s`	`gossip_.prune_timeout_s_`	integer	300	Time before removing dead nodes

TLS

JSON key	C++ field	Type	Default	Description
`tls.cert_chain_file`	`tls_.cert_chain_file_`	string	—	PEM certificate chain
`tls.private_key_file`	`tls_.private_key_file_`	string	—	PEM private key
`tls.ca_file`	`tls_.ca_file_`	string	—	CA bundle for peer verification

JWT

JSON key	C++ field	Type	Default	Description
`jwt.keys.signature`	`jwt_.keys_.signature_`	string	(default)	Base64 JWT signing key
`jwt.keys.encryption`	`jwt_.keys_.encryption_`	string	(default)	Base64 JWT encryption key

CORS

JSON key	C++ field	Type	Default	Description
`cors.enabled`	`cors_.enabled_`	boolean	true	Enable CORS headers
`cors.origin`	`cors_.origin_`	string	"*"	Allowed origin
`cors.headers`	`cors_.headers_`	string	"Content-Type, Authorization"	Allowed headers

Logging

JSON key	C++ field	Type	Default	Description
`logging.scopes`	`logging_.scopes_`	array	["service","operational","verbose"]	Enabled log scopes

Latency

JSON key	C++ field	Type	Default	Description
`latency.enabled`	`latency_.enabled_`	boolean	true	Enable latency tracking
`latency.interval_s`	`latency_.interval_s_`	integer	5	Measurement interval
`latency.timeout_s`	`latency_.timeout_s_`	integer	60	Latency timeout
`latency.history_size`	`latency_.history_size_`	integer	10	Readings to keep

WebSocket

JSON key	C++ field	Type	Default	Description
`websocket.max_queue_size`	`websocket_.max_queue_size_`	integer	1000	Send queue per connection
`websocket.max_subscriptions_per_session`	`websocket_.max_subscriptions_per_session_`	integer	1000	Subscriptions per session
`websocket.max_total_channels`	`websocket_.max_total_channels_`	integer	10000	Total channels limit

HTTP

JSON key	C++ field	Type	Default	Description
`http.pipeline_queue_limit`	`http_.pipeline_queue_limit_`	integer	8	HTTP pipelined requests

Validation

JSON key	C++ field	Type	Default	Description
`validation.regex_timeout_ms`	`validation_.regex_timeout_ms_`	integer	100	Regex match timeout

WAL

JSON key	C++ field	Type	Default	Description
`wal.enabled`	`wal_.enabled_`	boolean	true	Enable write-ahead log
`wal.path`	`wal_.path_`	string	"storage/wal.log"	WAL file path

Quotas

JSON key	C++ field	Type	Default	Description
`quotas.enabled`	`quotas_.enabled_`	boolean	false	Enable rate limiting
`quotas.ingress_bytes_limit`	`quotas_.ingress_bytes_limit_`	integer	-1	Max inbound bytes per window
`quotas.egress_bytes_limit`	`quotas_.egress_bytes_limit_`	integer	-1	Max outbound bytes per window
`quotas.msg_count_limit`	`quotas_.msg_count_limit_`	integer	-1	Max messages per window
`quotas.window_seconds`	`quotas_.window_seconds_`	integer	3600	Sliding window duration
`quotas.permissive`	`quotas_.permissive_`	boolean	false	Log only, no action
`quotas.default_rules`	`quotas_.default_rules_`	array	[]	Default quota limit rules
`quotas.allowlist`	`quotas_.allowlist_`	array	[]	Opcodes exempt from quotas
`quotas.blocklist`	`quotas_.blocklist_`	array	[]	Opcodes always blocked
`quotas.bypass_grants`	`quotas_.bypass_grants_`	array	["system:admin"]	JWT grants that bypass quotas

Quorum

JSON key	C++ field	Type	Default	Description
`quorum.enabled`	`quorum_.enabled_`	boolean	false	Enable quorum checks

Threads

JSON key	C++ field	Type	Default	Description
`threads`	`threads_`	integer	4	I/O thread pool size

Configuration ​

The Configuration Object ​

Minimal Configuration ​

Loading from a JSON File ​

JSON Config Reference ​

Ports & Seed ​

Node ​

Gossip ​

TLS ​

JWT ​

CORS ​

Logging ​

Latency ​

WebSocket ​

HTTP ​

Validation ​

WAL ​

Quotas ​

Quorum ​

Threads ​