Rust-Node.js Bridge (ts-addon)
Relevant source files
The following files were used as context for generating this wiki page:
The ts-addon module serves as a high-performance bridge between the Rust-based Kodus core runtime and a Node.js environment. It leverages the napi-rs framework to compile core Rust functionality into a native Node.js addon (.node file), allowing JavaScript and TypeScript applications to directly interface with the durable event store and workflow engine.
This bridge exposes the KodusRuntime class, which provides an asynchronous API for persisting events, managing workflows, and retrieving statistics. This enables Node.js applications, such as the project's Express API, to utilize the performance and safety of the Rust backend for critical operations.
Sources: apps/runtime/crates/ts-addon/src/lib.rs, README.md:12
Architecture and Build Process
The ts-addon is a Rust library configured to be compiled as a dynamic system library (cdylib), which is the format required for a native Node.js addon. The build process is managed by napi-build, which is specified in the build dependencies.
The core dependencies for this bridge are napi-rs (for Node.js interop) and kodus-core (for access to the main runtime logic).
Sources: apps/runtime/crates/ts-addon/Cargo.toml:9-14
The following diagram illustrates the build and usage flow of the addon.
This diagram shows how Rust source files are compiled into a .node addon, which is then loaded into a Node.js application.
Sources: apps/runtime/crates/ts-addon/Cargo.toml, apps/api/examples/nodejs-usage.js:1
Core API: The KodusRuntime Class
The primary export of the addon is the KodusRuntime class. It encapsulates the connection to the DurableStore and the WorkflowEngine.
Initialization
An instance of the class is created by passing a file path for the data directory, which initializes the underlying Sled-based durable store.
// Initialize the runtime, specifying the data storage directory
const runtime = new KodusRuntime('./data');
Sources: apps/api/examples/nodejs-usage.js:5, apps/runtime/crates/ts-addon/src/lib.rs:16-25
Class Diagram
The diagram below shows the structure of the KodusRuntime class and its exposed methods.
Exposed Functionality
The KodusRuntime class exposes several asynchronous methods to interact with the core Rust engine.
Event Management
Methods for creating and retrieving events from the DurableStore.
| Method | Description |
|---|---|
persistEvent | Persists a simple event with only a payload and source. |
persistEventWithMetadata | Persists an event with full metadata, including priority, user ID, correlation ID, and tags. |
findEventsBySource | Retrieves a list of all events associated with a specific source string. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:27-106
The sequence diagram below shows a Node.js application persisting an event with metadata.
Workflow Management
Methods for creating and executing workflows defined in kodus-core.
| Method | Description |
|---|---|
createWorkflow | Registers a new workflow definition with a given name and description. The current implementation creates a simple workflow with a single default transform step. |
executeWorkflow | Executes a registered workflow by its ID, passing an EventData object as input. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:121-180, apps/runtime/crates/core/src/workflow.rs:259-277
The following example demonstrates creating and executing a workflow.
// Create a workflow
const workflowId = await runtime.createWorkflow(
'payment-processing',
'Process payment events with validation'
);
// Execute the workflow with an input event
const processedEvent = await runtime.executeWorkflow(workflowId, inputEvent);
Sources: apps/api/examples/nodejs-usage.js:63-79
Statistics and Utilities
Helper methods for monitoring and configuration.
| Method / Function | Description |
|---|---|
getStats | Retrieves statistics from the DurableStore, including total event count. |
createRetryPolicy | A standalone function to create a RetryPolicyData object in JavaScript. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:108-120, 198-207
Data Structures
Data is transferred between Node.js and Rust using #[napi(object)] structs that are automatically converted to/from JavaScript objects.
EventData
Represents an event when transferring data across the bridge.
| Field | Type | Description |
|---|---|---|
id | string | The unique identifier of the event (UUID). |
payload | Buffer | The binary payload of the event. |
source | string | The source identifier for the event. |
priority | number | Numeric priority: 0=Low, 1=Normal, 2=High, 3=Critical. |
userId | string | undefined | Optional ID of the user associated with the event. |
correlationId | string | undefined | Optional ID for correlating related events. |
tags | [string, string][] | A list of key-value pairs for metadata. |
timestamp | string | The event creation timestamp in ISO 8601 format. |
retryCount | number | The number of times this event has been retried. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:183-195, apps/api/examples/README.md:111-122
Stats
Contains statistics about the DurableStore.
| Field | Type | Description |
|---|---|---|
totalEvents | number | The total number of events in the store. |
treeStats | string | undefined | Optional detailed statistics from the underlying Sled database tree. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:197-201
Usage in an Express API
The addon is used in the example express-app.js to expose the Kodus Runtime functionality via a REST API. This demonstrates a practical application of the bridge.
The following endpoints are created:
POST /events: Persists a new event usingruntime.persistEventWithMetadata.GET /events/:source: Finds events usingruntime.findEventsBySource.GET /stats: Gets store statistics usingruntime.getStats.POST /workflows: Creates a workflow usingruntime.createWorkflow.
This integration allows any HTTP client to interact with the Rust core via a standard Node.js web server.