Rust Runtime Core

The kodus-core crate is the heart of the Kodus Runtime system, providing a complete, high-performance event processing framework in Rust. It is designed for durable event persistence, asynchronous task execution, and complex event processing through a workflow engine. Its main features include a typed event system, a durable store built on Sled, a multi-runtime executor, and a flexible JSON-based configuration system.

This core library is self-contained but also exposes its functionality to the Node.js ecosystem through a native addon (kodus-addon), enabling seamless integration with TypeScript/JavaScript applications. The core components are designed to be modular, allowing for flexible deployment and usage patterns, from simple event logging to complex, multi-step workflow execution.

Core Architecture

The kodus-core architecture is composed of several key components that work together to process and persist events. The DurableStore handles data persistence, the Event system defines the data structure for all events, the WorkflowEngine processes complex logic, and the Executor manages asynchronous tasks.

This diagram illustrates the high-level interaction between the main components of the Rust Runtime Core.

Event System

The event system is built around the Event struct, which encapsulates the data payload and rich metadata for tracking, routing, and processing.

Sources: apps/runtime/crates/core/src/queue.rs, apps/runtime/crates/core/examples/improved.rs:43-66

Event Structure

The Event struct is the central data model. It includes the payload and extensive metadata.

Key Event Fields

Creating an Event

Events can be created with a simple payload and source, and then enriched with additional metadata using a builder pattern.

// Create a basic event
let event = Event::new(
    b"critical data".to_vec(),
    "payment-service".to_string(),
);

// Add rich metadata
let event_with_metadata = event
    .with_priority(Priority::High)
    .with_correlation_id(Uuid::new_v4())
    .with_user_id("user-123".to_string())
    .with_tag("environment".to_string(), "production".to_string());

Sources: apps/runtime/crates/core/examples/improved.rs:43-56, README.md:200-212

Durable Store

The DurableStore provides persistent, disk-based storage for events using the Sled embedded database. It supports asynchronous operations, batching for high performance, and advanced querying capabilities.

Sources: apps/runtime/crates/core/src/store.rs, README.md:214-227

Core Operations

• open(path): Opens or creates a database at the specified directory.
• persist_event(event): Asynchronously persists a single event.
• persist_batch(events): Asynchronously persists a vector of events in a single batch operation for improved throughput.
• find_by_source(source): Finds all events originating from a specific source.
• find_by_correlation_id(id): Finds all events that share a correlation ID.
• stats(): Returns statistics about the store, such as the total number of events.

Sources: apps/runtime/crates/core/src/store.rs, apps/runtime/crates/core/examples/improved.rs:71-88

Workflow Engine

The WorkflowEngine is responsible for executing complex, multi-step processing logic defined by a WorkflowDefinition. It orchestrates the flow of an event through a series of steps, such as transformations, filters, and external calls.

Sources: apps/runtime/crates/core/src/workflow.rs

Workflow Structure

A workflow is defined by a WorkflowDefinition, which contains a series of WorkflowSteps.

Sources: apps/runtime/crates/core/src/workflow.rs:6-27, 260-388

Workflow Execution Flow

The execute_workflow method processes an event by iterating through the defined steps.

This diagram shows the logic inside WorkflowEngine::execute_workflow.
Sources: apps/runtime/crates/core/src/workflow.rs:72-94

The engine also provides execute_workflow_with_retry, which incorporates the workflow's defined RetryPolicy and can send failed events to a dead-letter queue.
Sources: apps/runtime/crates/core/src/workflow.rs:99-130

Configuration

The runtime is configured via a Config struct, which can be deserialized from a JSON file (e.g., config.json). This provides a flexible way to manage settings for all core components.

Sources: apps/runtime/crates/core/src/config.rs, README.md:243-288

Configuration Sections

Example config.json

{
  "runtime": {
    "executor_type": "Tokio",
    "max_concurrent_tasks": 1000,
    "shutdown_timeout_secs": 30
  },
  "store": {
    "data_dir": "data",
    "batch_size": 1000,
    "compression_enabled": false
  },
  "queue": {
    "capacity": 10000,
    "priority_enabled": true,
    "retry_policy": {
      "max_retries": 3,
      "initial_delay_ms": 1000
    }
  }
}

Sources: README.md:246-272, apps/runtime/crates/core/src/config.rs:10-55

Node.js Integration (ts-addon)

The kodus-core functionality is exposed to Node.js through a native addon built with napi-rs. The KodusRuntime class in the addon wraps the core Rust components, providing an idiomatic JavaScript/TypeScript API.

Sources: apps/runtime/crates/ts-addon/src/lib.rs, apps/api/examples/nodejs-usage.js

Node.js to Rust Flow

This sequence diagram shows how a Node.js application persists an event by calling the native addon, which in turn uses kodus-core.

The addon exposes key functions like persistEvent, findEventsBySource, getStats, and executeWorkflow, mapping them directly to the underlying DurableStore and WorkflowEngine methods.
Sources: apps/runtime/crates/ts-addon/src/lib.rs:27-166