Rails Event Store (RES)

Rails Event Store (RES) is a library designed for publishing, consuming, storing, and retrieving events. It is intended to support event-driven architectures within Rails applications.

Key use cases include:

• Publish-Subscribe bus: Using RES as a central bus for event distribution.
• Decoupling: Separating core business logic from external concerns (e.g., in Hexagonal architectures).
• Alternative to ActiveRecord Callbacks: Moving away from side-effects in models toward explicit domain events.
• Communication Layer: Facilitating interaction between loosely coupled components.
• Synchronous/Asynchronous Reaction: Reacting to events either immediately or via background processing.
• Side-effect Extraction: Moving logic like notifications or metrics out of controllers/services and into dedicated event handlers.
• Audit Logs: Building a reliable history of system changes.
• Read Models: Creating specialized views of data for optimized querying.
• Event Sourcing: Implementing full event-sourcing patterns.

The RailsEventStore project consists of several core gems and various contributed gems that extend its functionality.

Core Gems

• rails_event_store: The primary gem for Rails integration.
• ruby_event_store: The core Ruby implementation.
• ruby_event_store-active_record: ActiveRecord adapter for ruby_event_store.
• ruby_event_store-browser: Browser-based support for ruby_event_store.
• ruby_event_store-rspec: RSpec testing support.
• aggregate_root: Provides aggregate root functionality.

Contributed Gems

There are many community-contributed gems for specific use cases, including:

• ruby_event_store-outbox: Outbox pattern support.
• ruby_event_store-cli: Command line interface.
• ruby_event_store-process_manager: Process management.
• ruby_event_store-sequel: Sequel adapter.
• ruby_event_store-sidekiq_scheduler: Sidekiq integration.
• ruby_event_store-profiler: Profiling tools.

Extensions allow you to plug new pages and links into the Browser UI. An extension is an object passed to extensions: [...] in the configuration. There is no base class; the Browser discovers functionality using respond_to? on several optional hooks.

Available Hooks

• register_routes(router, context): Add custom routes. The router allows adding routes, and the context provides rendering and event store access.
• stream_links(stream_name, urls): Add links displayed under the header of a stream page.
• event_links(event, urls): Add links displayed on an event page.
• nav_links(urls): Add links to the top navigation bar.
• views_root: Specify the directory for extension templates.
• assets_root: Specify the directory for extension assets (CSS/JS). Files in this directory are automatically served and linked.

The Context Object

In register_routes, the context provides:

• context.render(template, urls:, title: nil, **locals): Renders a template wrapped in the browser layout.
• context.not_found(urls, message: "Page not found"): Renders a styled 404 page.
• context.event_store: The event store client.

Building URLs

Always use urls.app_url_for to build paths to ensure compatibility with different mount points:

urls.app_url_for("my_extension", "param_value")

run RubyEventStore::Browser::App.for(
  event_store_locator: -> { event_store },
  extensions: [DeploymentsExtension.new],
)

Upcasting is a non-destructive strategy for evolving events where transformations occur at read time without modifying the underlying storage. When an event is loaded from the event store, a mapper applies a chain of upcast functions to convert older event representations into the current shape on the fly.

Use upcasting when:

• You are renaming an event class and want old records to be read as the new class.
• You are evolving the data schema of an event and want to express the evolution as a versioned chain.

Important Constraint: Each upcast function must change the event_type. If an upcast returns a record with the same event_type as the input, the system will raise a RubyEventStore::InvalidUpcast error.

upcast_map = {
  "OrderPlaced" => lambda do |record|
    RubyEventStore::Record.new(
      event_id:   record.event_id,
      metadata:   record.metadata,
      timestamp:  record.timestamp,
      valid_at:   record.valid_at,
      event_type: record.event_type,
      data:       record.data.merge(currency: "USD"),
    )
  end
}