Runtime Adapters
Relevant source files
The following files were used as context for generating this wiki page:Runtime Adapters are a planned feature designed to integrate the Kodus Runtime with various external systems, such as message brokers and third-party APIs. This functionality will enable the runtime to consume and produce events from and to different sources, extending its capabilities beyond the internal event store. According to the project roadmap, this feature is currently in development.
The primary goal of adapters is to bridge the core event processing logic of kodus-core with external services. The initial implementation plan includes adapters for Kafka, NATS, and OpenAI. The existing kodus-adapters crate serves as a placeholder for this future implementation.
Sources: README.md, apps/runtime/crates/adapters/src/lib.rs
Architecture (Planned)
The planned architecture for adapters positions them as intermediaries between the Kodus Runtime's core components (like the event queue and durable store) and external systems. Adapters will be responsible for connecting, authenticating, and translating messages between the external system's format and the internal Event structure of Kodus.
The following diagram illustrates the conceptual data flow involving a runtime adapter.
This diagram shows an adapter receiving data from an external system, converting it into a standard Event for processing by the Kodus Core, and potentially sending data back to the external system, for example, as part of a Workflow step.
Sources: README.md, config/config.example.json, apps/runtime/crates/core/src/workflow.rs:163-172
Configuration
Adapter configuration is managed within the main config.json file, under the adapters key. This allows for a centralized and declarative setup for each adapter. The configuration defines connection details, credentials, and behavior-specific options for each service.
Sources: config/config.example.json:38-56
Example Configuration
The following snippet from config.example.json shows the planned structure for configuring Kafka and NATS adapters.
"adapters": {
"kafka": {
"adapter_type": "kafka",
"connection_string": "localhost:9092",
"credentials": null,
"options": {
"group_id": "kodus-runtime",
"auto_offset_reset": "earliest"
}
},
"nats": {
"adapter_type": "nats",
"connection_string": "nats://localhost:4222",
"credentials": null,
"options": {}
}
}
Sources: config/config.example.json:38-56
Kafka Adapter Configuration
The Kafka adapter is configured with the following parameters.
| Field | Type | Description | Example Value |
|---|---|---|---|
adapter_type | String | Must be "kafka". | "kafka" |
connection_string | String | The address of the Kafka broker(s). | "localhost:9092" |
credentials | Object/null | Placeholder for authentication credentials. | null |
options | Object | Kafka-specific options. | |
options.group_id | String | The consumer group ID for this runtime instance. | "kodus-runtime" |
options.auto_offset_reset | String | The policy for reading from a topic when there is no committed offset. | "earliest" |
Sources: config/config.example.json:40-47
NATS Adapter Configuration
The NATS adapter is configured with the following parameters.
| Field | Type | Description | Example Value |
|---|---|---|---|
adapter_type | String | Must be "nats". | "nats" |
connection_string | String | The URL of the NATS server. | "nats://localhost:4222" |
credentials | Object/null | Placeholder for authentication credentials. | null |
options | Object | Placeholder for NATS-specific options. | {} |
Sources: config/config.example.json:48-53
Crate Structure (kodus-adapters)
The implementation of all runtime adapters is intended to be housed within the kodus-adapters Rust crate.
This diagram shows the dependencies of the kodus-adapters crate.
Sources: apps/runtime/crates/adapters/Cargo.toml:7-8
The Cargo.toml for this crate specifies dependencies on kodus-core and tracing, indicating that adapters will integrate directly with core data structures and will support structured logging.
[dependencies]
kodus-core = { path = "../core", default-features = false }
tracing = { workspace = true }
Sources: apps/runtime/crates/adapters/Cargo.toml:7-9
Currently, the src/lib.rs file for the crate is empty, which confirms that the feature is a work in progress and no adapters have been implemented yet.
Sources: apps/runtime/crates/adapters/src/lib.rs
Planned Adapters
The project roadmap outlines several adapters planned for development.
| Adapter | Description | Status |
|---|---|---|
| Kafka | For integrating with Apache Kafka to consume and produce event streams. Configuration is already defined. | In Development |
| NATS | For integrating with the NATS messaging system. Configuration is already defined. | In Development |
| OpenAI | For connecting to the OpenAI API, likely to be used within a Workflow ExternalCall step for AI-powered event processing. | In Development |
Sources: README.md, config/config.example.json:38-56, apps/runtime/crates/core/src/workflow.rs:27
Summary
The Runtime Adapters feature is a crucial part of the Kodus Runtime's future, aiming to provide robust, configurable integration with external systems like Kafka and NATS. While the feature is still in the development phase, the foundational structure within the kodus-adapters crate and the configuration schema in config.example.json have been established. The implementation will enable the runtime to act as a central hub for event processing in a distributed microservices architecture.
Sources: README.md, apps/runtime/crates/adapters/Cargo.toml, config/config.example.json