Events API (/events)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/routes/events.ts
• apps/api/examples/nodejs-usage.ts
• apps/runtime/crates/ts-addon/src/lib.rs
• apps/api/examples/express-app.js
• README.md
• apps/dashboard/src/pages/Dashboard.tsx
• examples/authenticated-usage.js

The Events API provides a set of authenticated REST endpoints for persisting, retrieving, and monitoring events within the Kodus Runtime. It is built using the Elysia.js framework and serves as the primary HTTP interface for interacting with the underlying Rust-based event store. All operations are routed through a Node.js native addon, which ensures high performance for event processing and persistence.

The API is responsible for receiving event data, passing it to the core KodusRuntime for durable storage, and exposing methods to query the stored events and their statistics. All endpoints under the /api/events prefix are protected and require a valid JWT for access.

Sources: apps/api/src/routes/events.ts, README.md:23-31, README.md:47-50

Architecture

The Events API acts as a bridge between an HTTP client and the core Rust runtime. The API logic itself is lightweight; its main responsibility is to handle HTTP requests, perform authentication, and delegate the core operations to the KodusRuntime class, which is a native addon written in Rust.

This diagram illustrates the request flow from a client to the durable store.

API Endpoints

The API exposes endpoints for creating events, querying them by source, and retrieving store statistics.

Sources: apps/api/src/routes/events.ts:7-106

POST /events

This endpoint is used to create and persist a new event in the durable store. It accepts a JSON payload containing the event data and its associated metadata. The request must be authenticated.

Sources: apps/api/src/routes/events.ts:10-53, README.md:47-50

Request Body

Parameter	Type	Default	Description
payload	object		The main JSON data of the event.
source	string		A string identifying the origin of the event (e.g., 'payment-service').
priority	number	1	The event priority (0: Low, 1: Normal, 2: High, 3: Critical).
userId	string	null	An optional ID of the user associated with the event.
correlationId	string	null	An optional ID to correlate multiple events in a single flow.
tags	Array<[string, string]>	[]	An array of key-value pairs for custom metadata.

Sources: apps/api/src/routes/events.ts:18-25, apps/runtime/crates/ts-addon/src/lib.rs:43-73

Responses

• 201 Created: Returned on successful event persistence.

  {
    "success": true,
    "eventId": "uuid-string-of-the-event",
    "message": "Evento persistido com sucesso"
  }
  

• 401 Unauthorized: Returned if the JWT is missing or invalid.
• 500 Internal Server Error: Returned if the runtime fails to persist the event.

Sources: apps/api/src/routes/events.ts:41-46, apps/api/src/routes/events.ts:47-52

Sequence Diagram

This diagram shows the sequence of calls for creating an event.

GET /events/:source

Retrieves a list of all events that match the given source parameter. The request must be authenticated.

Sources: apps/api/src/routes/events.ts:56-81

URL Parameters

Parameter	Type	Description
source	string	The source identifier to filter events by.

Sources: apps/api/src/routes/events.ts:56

Response

• 200 OK: Returns an array of event objects.

  {
    "success": true,
    "events": [
      {
        "id": "...",
        "source": "demo-script",
        "priority": 1,
        "userId": "user-id",
        "correlationId": "session-id",
        "tags": [["demo", "true"]],
        "timestamp": "iso-string",
        "retryCount": 0,
        "payload": { "action": "demo_authenticated_usage" }
      }
    ]
  }
  

• 500 Internal Server Error: Returned if the query fails.

Sources: apps/api/src/routes/events.ts:60-75, examples/authenticated-usage.js:56-59

GET /events/stats

Fetches statistics from the event store, such as the total number of events. This endpoint is used by the dashboard to display monitoring information. The request must be authenticated.

Sources: apps/api/src/routes/events.ts:84-106, apps/dashboard/src/pages/Dashboard.tsx:7-14

Response

• 200 OK: Returns an object with event store statistics.

  {
    "success": true,
    "stats": {
      "totalEvents": 12345,
      "treeStats": "sled tree statistics string"
    }
  }
  

• 500 Internal Server Error: Returned if fetching stats fails.

Sources: apps/api/src/routes/events.ts:88-96, apps/runtime/crates/ts-addon/src/lib.rs:134-138

Core Component: KodusRuntime

The API routes are thin wrappers around the KodusRuntime class, which is exposed from a Rust native addon. This class provides the JavaScript/TypeScript interface to the core functionality.

Sources: apps/runtime/crates/ts-addon/src/lib.rs:5-12

This class diagram shows the public methods of the KodusRuntime bridge available to the Node.js application. The Events API primarily uses persistEventWithMetadata, findEventsBySource, and getStats.

Sources: apps/runtime/crates/ts-addon/src/lib.rs:15-127

Data Structures

EventData

This object represents a single event and is used when retrieving events from the runtime.

Field	Type	Description
id	string	Unique identifier (UUID) of the event.
payload	Buffer	The event data as a byte buffer.
source	string	The source of the event.
priority	number	Priority level (0-3).
userId	string | null	Associated user ID.
correlationId	string | null	Associated correlation ID (UUID).
tags	Array<[string, string]>	Key-value metadata tags.
timestamp	string	ISO 8601 timestamp of event creation.
retryCount	number	Number of processing retries.

Sources: apps/runtime/crates/ts-addon/src/lib.rs:129-139, apps/api/examples/nodejs-usage.ts:3-5

Stats

This object contains statistics about the event store.

Field	Type	Description
totalEvents	number	The total number of events persisted in the store.
treeStats	string | null	Detailed internal statistics from the Sled database tree.

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

Usage Example

The following curl command demonstrates how to create a new event by sending a POST request to the API with a valid authentication token.

curl -X POST http://localhost:3201/api/events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {"test": "data"},
    "source": "demo"
  }'

Sources: README.md:29-32