Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Configuration in the Kodus Runtime project is managed through a hybrid approach. The core Rust-based runtime is configured via a central config.json file, providing detailed control over its components like the event store, task execution, and telemetry. In contrast, the surrounding Node.js services, such as the API, are configured primarily through environment variables, which is a common practice for containerized applications.
This separation allows for a robust, static configuration for the high-performance core, while offering flexibility for the service layer, especially in different deployment environments (development, production). The project also includes a shared @kodus/config package, which primarily provides a standardized logger for TypeScript applications within the monorepo.
Sources: README.md:41-43, 203-228, apps/runtime/crates/core/src/config.rs, tools/docker/docker-compose.yml:10-15
Core Runtime Configuration (config.json)
The heart of the Rust runtime's configuration is a JSON file, typically named config.json. This file is loaded at startup and validated to ensure the runtime operates correctly. The configuration is modular, with distinct sections for runtime, store, queue, and telemetry.
Sources: README.md:203-206, apps/runtime/crates/core/src/config.rs:10-21
Configuration Loading and Validation
The Rust application loads the configuration from a file and validates its contents. The Config::from_file() function reads and deserializes the JSON, while config.validate() checks for logical consistency.
The diagram below illustrates the configuration loading flow in the Rust core.
Configuration Structure
The main Config struct in Rust is composed of several sub-structures, each corresponding to a top-level key in the config.json file.
This diagram shows the relationship between the main Config struct and its components.
runtime Section
This section configures the task execution engine.
| Parameter | Type | Description | Default |
|---|---|---|---|
executor_type | String | The async runtime to use. "Tokio" is an example. | "Tokio" |
max_concurrent_tasks | number | Maximum number of tasks to run concurrently. | 1000 |
shutdown_timeout_secs | number | Graceful shutdown period in seconds. | 30 |
health_check_interval_secs | number | Interval for health checks in seconds. | 5 |
Sources: config/config.example.json:2-7, apps/runtime/crates/core/src/config.rs:24-33, 83-88
store Section
This section configures the durable event store (Sled).
| Parameter | Type | Description | Default |
|---|---|---|---|
data_dir | String | Directory for storing persistent data. | "data" |
batch_size | number | Number of events to batch for persistence operations. | 1000 |
compression_enabled | boolean | Enables or disables data compression. | false |
cache_enabled | boolean | Enables or disables the cache layer. | true |
max_cache_size | number | Maximum number of items in the cache. | 10000 |
Sources: config/config.example.json:8-15, apps/runtime/crates/core/src/config.rs:35-45, 90-96
queue Section
This section configures the in-memory event queueing system.
| Parameter | Type | Description | Default |
|---|---|---|---|
capacity | number | Maximum number of events the queue can hold. | 10000 |
priority_enabled | boolean | Enables or disables priority-based queueing. | true |
dead_letter_queue_enabled | boolean | Enables or disables the dead-letter queue. | true |
retry_policy | object | Configuration for event processing retries. | See below |
Sources: config/config.example.json:16-26, apps/runtime/crates/core/src/config.rs:47-55, 98-103
retry_policy Sub-section
| Parameter | Type | Description | Default |
|---|---|---|---|
max_retries | number | Maximum number of retries for a failed event. | 3 |
initial_delay_ms | number | Initial delay before the first retry in milliseconds. | 1000 |
max_delay_ms | number | Maximum delay between retries in milliseconds. | 30000 |
backoff_multiplier | number | Multiplier for exponential backoff. | 2.0 |
Sources: config/config.example.json:20-25, apps/runtime/crates/core/src/config.rs:65-73, 108-113
telemetry Section
This section configures OpenTelemetry integration for tracing and metrics.
| Parameter | Type | Description | Default |
|---|---|---|---|
enabled | boolean | Enables or disables telemetry. | true |
endpoint | String | The OTLP exporter endpoint. | "http://localhost:4318" |
service_name | String | The name of the service reported to the collector. | "kodus-runtime" |
metrics_enabled | boolean | Enables or disables metrics exporting. | true |
tracing_enabled | boolean | Enables or disables trace exporting. | true |
Sources: config/config.example.json:27-34, apps/runtime/crates/core/src/config.rs:57-63, 105-106
Example config.json
{
"runtime": {
"executor_type": "Tokio",
"max_concurrent_tasks": 1000,
"shutdown_timeout_secs": 30,
"health_check_interval_secs": 5
},
"store": {
"data_dir": "data",
"batch_size": 1000,
"compression_enabled": false,
"cache_enabled": true,
"max_cache_size": 10000
},
"queue": {
"capacity": 10000,
"priority_enabled": true,
"dead_letter_queue_enabled": true,
"retry_policy": {
"max_retries": 3,
"initial_delay_ms": 1000,
"max_delay_ms": 30000,
"backoff_multiplier": 2.0
}
},
"telemetry": {
"enabled": true,
"endpoint": "http://localhost:4318",
"service_name": "kodus-runtime",
"metrics_enabled": true,
"tracing_enabled": true
}
}
Source: README.md:208-242
Service Layer Configuration (Environment Variables)
The Node.js API and other services are configured using environment variables, following 12-factor app principles. These are typically loaded from a .env file during local development and supplied directly in containerized environments.
The docker-compose.yml file defines the environment variables passed to the api service container.
| Variable | Description | Example Value |
|---|---|---|
NODE_ENV | Sets the application environment. | production |
PORT | The port the API server will listen on. | 3201 |
CORS_ORIGIN | The allowed origin for Cross-Origin Resource Sharing. | http://localhost:80 |
JWT_ACCESS_SECRET | Secret key for signing JWT access tokens. | dev-access-secret |
JWT_REFRESH_SECRET | Secret key for signing JWT refresh tokens. | dev-refresh-secret |
DATABASE_URL | Path to the Sled database directory. | /app/data |
Sources: tools/docker/docker-compose.yml:10-16, README.md:104-108
Shared @kodus/config Package
The monorepo includes a shared package named @kodus/config. Contrary to what its name might suggest, its primary role is not to distribute configuration values but to provide a shared, structured logger for use across TypeScript-based applications like the API and Dashboard. This ensures consistent logging behavior.
The logger has info, warn, error, and debug levels. In production, debug logs are suppressed.
Sources: packages/config/README.md:3-17, packages/config/package.json:2-3, 12-14
Conclusion
The configuration system of Kodus Runtime is thoughtfully designed to match the needs of its different architectural layers. The Rust core benefits from a detailed, validated JSON configuration that ensures stability and performance. The surrounding Node.js services leverage the flexibility of environment variables, which is ideal for modern, container-based deployments. This dual strategy provides a clear separation of concerns and robust control over the entire platform.
Sources: README.md:41-43, 99-108, 203-206