Explicit Event Store Subscriptions

Chronicle supports explicit subscriptions — manual registration of subscriptions between event stores using the Subscriptions API. When you configure a subscription explicitly, you control:

• Which event types are forwarded
• Subscription lifecycle and management
• The subscription identifier for reference and cleanup

Explicit subscriptions are ideal when:

• You need fine-grained control over which event types are forwarded
• The source service’s event types are not in a shared NuGet package
• You want to dynamically create or remove subscriptions
• Events come from a legacy or external system

Client coverage

Explicit subscriptions are real in Elixir (Chronicle.subscribe_to_event_store/3,4, Chronicle.unsubscribe_from_event_store/1,2) and TypeScript (store.subscriptions.subscribe/.unsubscribe) too — both map closely onto C#‘s Subscriptions API. Kotlin and Java have no event-store-subscription support at all yet — nothing in the Kotlin SDK source corresponds to this API. The host-builder-specific registration patterns further down this page (ASP.NET Core startup) aren’t ported — see each client’s own startup/registration conventions for the equivalent.

Setting Up an Explicit Subscription

Use the Subscriptions property on IEventStore to subscribe:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;

[EventType]
public record SubscriptionsExplicitShipmentDispatched(string OrderId);

public static class SubscriptionsExplicitBasic
{
    public static Task Run(IEventStore eventStore) =>
        eventStore.Subscriptions.Subscribe(
            "orders-from-fulfillment",
            "fulfillment-service",
            builder => builder.WithEventType<SubscriptionsExplicitShipmentDispatched>());
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.Events.SubscriptionsExplicitShipmentDispatched do
  use Chronicle.Events.EventType, id: "subscriptions-explicit-shipment-dispatched"

  defstruct [:order_id]
end

defmodule MyApp.SubscriptionsExplicitBasic do
  alias Chronicle.EventStoreSubscriptions.DefinitionBuilder
  alias MyApp.Events.SubscriptionsExplicitShipmentDispatched

  def run do
    Chronicle.subscribe_to_event_store(
      "orders-from-fulfillment",
      "fulfillment-service",
      fn builder -> DefinitionBuilder.with_event_type(builder, SubscriptionsExplicitShipmentDispatched) end,
      []
    )
  end
end

TypeScript

import { eventType, IEventStore } from '@cratis/chronicle';

@eventType()
class SubscriptionsExplicitShipmentDispatched {
    constructor(readonly orderId: string) {}
}

class SubscriptionsExplicitBasic {
    static async run(store: IEventStore): Promise<void> {
        await store.subscriptions.subscribe(
            'orders-from-fulfillment',
            'fulfillment-service',
            builder => builder.withEventType(SubscriptionsExplicitShipmentDispatched)
        );
    }
}

The three arguments are:

Argument	Description
Subscription ID	A stable, unique string that identifies this subscription within the target event store
Source event store	The name of the event store whose outbox to subscribe to
Configuration callback	Optional — filters which event types to forward

Subscription ID

The subscription ID must be unique within the target event store. It serves as the persistent identifier for the subscription on the kernel side. If you call Subscribe with the same ID, the kernel treats it as idempotent — no duplicate subscription is created.

A typical naming convention:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;

[EventType]
public record SubscriptionsExplicitStockAdjusted(string ItemId, int Delta);

public static class SubscriptionsExplicitNamingConvention
{
    public static async Task Run(IEventStore eventStore)
    {
        // subscription-id format: {target}-from-{source}
        await eventStore.Subscriptions.Subscribe(
            "orders-from-fulfillment",
            "fulfillment-service",
            builder => builder.WithEventType<SubscriptionsExplicitShipmentDispatched>());

        await eventStore.Subscriptions.Subscribe(
            "inventory-from-warehouse",
            "warehouse-service",
            builder => builder.WithEventType<SubscriptionsExplicitStockAdjusted>());
    }
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.Events.SubscriptionsExplicitStockAdjusted do
  use Chronicle.Events.EventType, id: "subscriptions-explicit-stock-adjusted"

  defstruct [:item_id, :delta]
end

defmodule MyApp.SubscriptionsExplicitNamingConvention do
  alias Chronicle.EventStoreSubscriptions.DefinitionBuilder
  alias MyApp.Events.{SubscriptionsExplicitShipmentDispatched, SubscriptionsExplicitStockAdjusted}

  def run do
    # subscription-id format: {target}-from-{source}
    :ok =
      Chronicle.subscribe_to_event_store(
        "orders-from-fulfillment",
        "fulfillment-service",
        fn builder -> DefinitionBuilder.with_event_type(builder, SubscriptionsExplicitShipmentDispatched) end,
        []
      )

    Chronicle.subscribe_to_event_store(
      "inventory-from-warehouse",
      "warehouse-service",
      fn builder -> DefinitionBuilder.with_event_type(builder, SubscriptionsExplicitStockAdjusted) end,
      []
    )
  end
end

TypeScript

import { eventType, IEventStore } from '@cratis/chronicle';

@eventType()
class SubscriptionsExplicitStockAdjusted {
    constructor(
        readonly itemId: string,
        readonly delta: number
    ) {}
}

class SubscriptionsExplicitNamingConvention {
    static async run(store: IEventStore): Promise<void> {
        // subscription-id format: {target}-from-{source}
        await store.subscriptions.subscribe(
            'orders-from-fulfillment',
            'fulfillment-service',
            builder => builder.withEventType(SubscriptionsExplicitShipmentDispatched)
        );

        await store.subscriptions.subscribe(
            'inventory-from-warehouse',
            'warehouse-service',
            builder => builder.withEventType(SubscriptionsExplicitStockAdjusted)
        );
    }
}

Filtering Event Types

Without a configuration callback, all events from the source outbox are forwarded. Use WithEventType<T>() to limit the subscription to specific types:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;

[EventType]
public record SubscriptionsExplicitStockReserved(string ItemId, int Quantity);

public static class SubscriptionsExplicitFiltering
{
    public static Task Run(IEventStore eventStore) =>
        eventStore.Subscriptions.Subscribe(
            "inventory-updates",
            "warehouse-service",
            builder => builder
                .WithEventType<SubscriptionsExplicitStockAdjusted>()
                .WithEventType<SubscriptionsExplicitStockReserved>());
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.Events.SubscriptionsExplicitStockReserved do
  use Chronicle.Events.EventType, id: "subscriptions-explicit-stock-reserved"

  defstruct [:item_id, :quantity]
end

defmodule MyApp.SubscriptionsExplicitFiltering do
  alias Chronicle.EventStoreSubscriptions.DefinitionBuilder
  alias MyApp.Events.{SubscriptionsExplicitStockAdjusted, SubscriptionsExplicitStockReserved}

  def run do
    Chronicle.subscribe_to_event_store(
      "inventory-updates",
      "warehouse-service",
      fn builder ->
        builder
        |> DefinitionBuilder.with_event_type(SubscriptionsExplicitStockAdjusted)
        |> DefinitionBuilder.with_event_type(SubscriptionsExplicitStockReserved)
      end,
      []
    )
  end
end

TypeScript

import { eventType, IEventStore } from '@cratis/chronicle';

@eventType()
class SubscriptionsExplicitStockReserved {
    constructor(
        readonly itemId: string,
        readonly quantity: number
    ) {}
}

class SubscriptionsExplicitFiltering {
    static async run(store: IEventStore): Promise<void> {
        await store.subscriptions.subscribe(
            'inventory-updates',
            'warehouse-service',
            builder => builder
                .withEventType(SubscriptionsExplicitStockAdjusted)
                .withEventType(SubscriptionsExplicitStockReserved)
        );
    }
}

If you need to subscribe to all events without filtering, omit the configuration callback entirely:

C#

using Cratis.Chronicle;

public static class SubscriptionsExplicitNoFilter
{
    public static Task Run(IEventStore eventStore) =>
        // All events from fulfillment-service outbox will be forwarded
        eventStore.Subscriptions.Subscribe(
            "all-fulfillment-events",
            "fulfillment-service");
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.SubscriptionsExplicitNoFilter do
  def run do
    # All events from fulfillment-service outbox will be forwarded
    Chronicle.subscribe_to_event_store("all-fulfillment-events", "fulfillment-service", [])
  end
end

TypeScript

import { IEventStore } from '@cratis/chronicle';

class SubscriptionsExplicitNoFilter {
    static async run(store: IEventStore): Promise<void> {
        // All events from fulfillment-service outbox will be forwarded
        await store.subscriptions.subscribe('all-fulfillment-events', 'fulfillment-service');
    }
}

Accessing Forwarded Events

Events forwarded via an explicit subscription are placed into the inbox sequence for the source event store. Access inbox events through any observer (reactor, projection, reducer):

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

[EventType]
public record SubscriptionsExplicitOrderPlaced(Guid OrderId, decimal Amount);

public class SubscriptionsExplicitIncomingOrdersReactor : IReactor
{
    public Task OrderPlaced(SubscriptionsExplicitOrderPlaced @event, EventContext context)
        => HandleIncomingOrderAsync(@event.OrderId, @event.Amount);

    Task HandleIncomingOrderAsync(Guid id, decimal amount) => Task.CompletedTask;
}

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.observation.Reactor

@EventType(id = "subscriptions-explicit-order-placed")
data class SubscriptionsExplicitOrderPlaced(val orderId: String, val amount: Double)

@Reactor
class SubscriptionsExplicitIncomingOrdersReactor {
    fun orderPlaced(event: SubscriptionsExplicitOrderPlaced, context: EventContext) {
        handleIncomingOrder(event.orderId, event.amount)
    }

    private fun handleIncomingOrder(id: String, amount: Double) {}
}

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.observation.Reactor;

@EventType(id = "subscriptions-explicit-order-placed")
record SubscriptionsExplicitOrderPlaced(String orderId, double amount) {}

@Reactor
class SubscriptionsExplicitIncomingOrdersReactor {
    void orderPlaced(SubscriptionsExplicitOrderPlaced event, EventContext context) {
        handleIncomingOrder(event.orderId(), event.amount());
    }

    private void handleIncomingOrder(String id, double amount) {}
}

Elixir

defmodule MyApp.Events.SubscriptionsExplicitOrderPlaced do
  use Chronicle.Events.EventType, id: "subscriptions-explicit-order-placed"

  defstruct [:order_id, :amount]
end

defmodule MyApp.Reactors.SubscriptionsExplicitIncomingOrdersReactor do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.SubscriptionsExplicitOrderPlaced

  @handles SubscriptionsExplicitOrderPlaced

  @impl true
  def handle(%SubscriptionsExplicitOrderPlaced{}, _context), do: :ok
end

TypeScript

import { eventType, reactor } from '@cratis/chronicle';

@eventType()
class SubscriptionsExplicitOrderPlaced {
    constructor(
        readonly orderId: string,
        readonly amount: number
    ) {}
}

@reactor()
class SubscriptionsExplicitIncomingOrdersReactor {
    // Method name must be the exact camelCase of the event's class name -
    // Chronicle discovers handlers by name, not by parameter type.
    async subscriptionsExplicitOrderPlaced(event: SubscriptionsExplicitOrderPlaced): Promise<void> {
        await this.handleIncomingOrder(event.orderId, event.amount);
    }

    private async handleIncomingOrder(orderId: string, amount: number): Promise<void> {}
}

The kernel automatically routes incoming events to the appropriate inbox-{sourceEventStore} event sequence. You do not need to reference the subscription ID when observing the events.

Removing a Subscription

C#

using Cratis.Chronicle;

public static class SubscriptionsExplicitUnsubscribe
{
    public static Task Run(IEventStore eventStore) =>
        eventStore.Subscriptions.Unsubscribe("orders-from-fulfillment");
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.SubscriptionsExplicitUnsubscribe do
  def run do
    Chronicle.unsubscribe_from_event_store("orders-from-fulfillment")
  end
end

TypeScript

import { IEventStore } from '@cratis/chronicle';

class SubscriptionsExplicitUnsubscribe {
    static async run(store: IEventStore): Promise<void> {
        await store.subscriptions.unsubscribe('orders-from-fulfillment');
    }
}

Calling Unsubscribe with the subscription ID:

• Stops event forwarding from the source outbox
• Removes the persistent subscription definition from the kernel
• Existing inbox events are not deleted — they remain available for observation

Once removed, no new events are forwarded to the inbox. If you later recreate the subscription with the same ID, forwarding resumes from that point forward.

Idempotent Registration

Subscriptions are identified by their subscription ID. Calling Subscribe with the same ID more than once is safe — if the subscription already exists, no duplicate subscription is created.

This makes it safe to register all subscriptions at application startup without checking if they already exist:

C#

using Cratis.Chronicle;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class SubscriptionsExplicitStartupRegistration
{
    public static async Task Configure(string[] args)
    {
        var builder = Host.CreateApplicationBuilder(args);
        builder.AddCratisChronicle(options => options.EventStore = "Quickstart");

        // Safe to call on every application startup
        var app = builder.Build();

        var eventStore = app.Services.GetRequiredService<IEventStore>();

        await eventStore.Subscriptions.Subscribe(
            "orders-from-fulfillment",
            "fulfillment-service",
            builder => builder.WithEventType<SubscriptionsExplicitShipmentDispatched>());

        await eventStore.Subscriptions.Subscribe(
            "inventory-from-warehouse",
            "warehouse-service",
            builder => builder.WithEventType<SubscriptionsExplicitStockAdjusted>());

        await app.RunAsync();
    }
}

If any of these subscriptions already exist on the kernel, they are left unchanged.

Subscription Lifecycle

Explicit subscriptions are kernel-managed and persistent:

• Created when you call Subscribe, stored on the kernel, and assigned a subscription ID
• Persisted — survive client disconnections and kernel restarts
• Re-established automatically when the kernel starts, even if the client is not connected
• Removed only when you explicitly call Unsubscribe

Typical Setup Pattern

A common pattern is to register all subscriptions once during application startup:

C#

using Cratis.Chronicle;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class SubscriptionsExplicitTypicalPattern
{
    public static async Task RegisterSubscriptions(IEventStore eventStore)
    {
        await eventStore.Subscriptions.Subscribe(
            "orders-from-fulfillment",
            "fulfillment-service",
            builder => builder.WithEventType<SubscriptionsExplicitShipmentDispatched>());

        await eventStore.Subscriptions.Subscribe(
            "inventory-updates",
            "warehouse-service",
            builder => builder
                .WithEventType<SubscriptionsExplicitStockAdjusted>()
                .WithEventType<SubscriptionsExplicitStockReserved>());
    }

    public static async Task Configure(string[] args)
    {
        var hostBuilder = Host.CreateApplicationBuilder(args);
        hostBuilder.AddCratisChronicle(options => options.EventStore = "Quickstart");

        var app = hostBuilder.Build();
        var eventStore = app.Services.GetRequiredService<IEventStore>();
        await RegisterSubscriptions(eventStore);
        await app.RunAsync();
    }
}

When to Use Explicit Subscriptions

Use explicit subscriptions when:

• You need fine-grained control over which event types are forwarded
• Event types are not published in a shared NuGet package
• You need to dynamically create or remove subscriptions at runtime
• The subscription relationship is consuming-service-specific

Use implicit subscriptions when:

• Event types are published in a shared NuGet package with [EventStore] attributes
• All events from a source should be automatically forwarded
• You prefer zero configuration and automatic routing

See Also

• Implicit Event Store Subscriptions — automatic subscription via [EventStore] attributes
• Outbox and Inbox — conceptual explanation of how events flow between stores
• Reactors — processing inbox events with reactors
• Projections — building read models from inbox events