Core Concepts

cross.stream is built around four fundamental concepts that work together to create a powerful and flexible event streaming system: the event store, services, actors, and actions. Let’s explore how these components interact and complement each other.

Event Store: The Foundation

At its core, cross.stream is an event store - a specialized database that maintains an append-only log of events. Think of it as a ledger where each entry (called a frame) represents something that happened, complete with metadata about when and how it occurred.

Each frame has a unique SCRU128 ID that increases in value over time, ensuring frames maintain their temporal ordering. You can generate and manipulate these IDs using the xs scru128 CLI command.

The event store provides a few key capabilities:

• Append-only writes: New events can only be added to the end of the stream, preserving the historical record
• Content separation: Event metadata is stored separately from content, optimizing for both quick scanning and efficient content storage
• Real-time subscriptions: Clients can follow the stream live, receiving new events as they occur

This design makes the event store particularly good at maintaining an accurate history of what happened and when, while still being efficient to query and process.

Processors

Services: The Producers

Services are like automated watchers that produce new events into the stream. They run as background processes, monitoring for specific conditions or changes and emitting corresponding events when they occur.

For example, a service might:

• Watch a log file and emit new lines as events
• Monitor a websocket connection and turn incoming messages into events
• Periodically check a system’s status and emit health events

Actors: The Reactors

Actors provide a way to react to and process events in the stream. They are like event-driven functions that wake up when new events arrive, process them according to rules you define, and optionally produce new events in response.

An actor might:

• Transform events into new formats
• Trigger external actions in response to events
• Aggregate or analyze event data
• Create chains of event processing

Actions: The On-demand Processors

Actions are reusable operations that can be called on-demand with input data. Unlike services which run continuously, or actors which maintain state, actions are stateless and execute independently each time they are called.

An action might:

• Make an HTTP request and stream back SSE responses
• Transform input data in a complex way
• Interact with external services

Component Comparison

Aspect	Services	Actors	Actions
Purpose	Produce events from external sources	Process existing events	Perform on-demand operations
Execution	Continuous background process	Event-driven	Called on-demand
State	Stateless	Maintains state between calls	Stateless
Output	Immediate streaming	Buffered until completion	Immediate streaming
Error Handling	Auto-restarts (with a 1-second delay)	Unregisters	Per-invocation
Typical Use Case	Watch external sources	Transform/react to events	Reusable operations

Incremental Adoption

One of the strengths of cross.stream’s design is that you can start simple and gradually add complexity as needed:

1. Start with the Event Store

   • Begin by just using the store to record and query events
   • Get comfortable with the basic append/read operations
   • Use it like a specialized database

2. Add Services

   • When you need to automatically capture events from external sources
   • Start with simple file watchers or API monitors
   • Let services feed your event stream

3. Introduce Actors

   • As you need to process or react to events
   • Start with simple transformations
   • Build up to more complex event processing chains

4. Define Actions

   • When you need reusable, on-demand operations
   • Encapsulate common operations
   • Use for streaming interactions with external services

Working Together

These processors create a flexible architecture where:

1. Services feed events into the system from external sources
2. Actors process those events, maintaining state if needed
3. Actions provide reusable operations that can be called on-demand
4. The event store ensures everything is reliably recorded and retrievable

For example, you might have:

• A service watching system metrics
• An actor that processes those metrics and detects anomalies
• An action that can be called to fetch additional data when an anomaly is detected
• The event store maintaining the complete history of metrics and analysis