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, generators, handlers, and commands. 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.

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.

Processing Components

Generators: The Producers

Generators 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 generator 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

Handlers: The Reactors

Handlers 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.

A handler might:

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

Commands: The On-demand Processors

Commands are reusable operations that can be called on-demand with input data. Unlike generators which run continuously, or handlers which maintain state, commands are stateless and execute independently each time they are called.

A command might:

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

Component Comparison

Aspect	Generators	Handlers	Commands
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	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 Generators

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

3. Introduce Handlers

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

4. Define Commands

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

Working Together

These components create a flexible architecture where:

1. Generators feed events into the system from external sources
2. Handlers process those events, maintaining state if needed
3. Commands 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 generator watching system metrics
• A handler that processes those metrics and detects anomalies
• A command that can be called to fetch additional data when an anomaly is detected
• The event store maintaining the complete history of metrics and analysis