Skip to content

Audience routing

A Chronicle event store’s outbox is a broadcast: every store that subscribes to it receives every event of the types it asks for. When one operator runs several products on one store, each product would otherwise receive the decisions meant for the others. An audience is a tag on an outbox event, named audience, that a subscription can filter on. The mechanism is Chronicle’s: EventTags.Audience(...) addresses an append, and ForAudience(...) on a subscription filters on it.

Audience routing is opt-in everywhere. Every option below defaults to unset, which means nothing is addressed and every subscription is unfiltered: a deployment that does not set them behaves exactly as before. Both sides have to agree: a subscription that filters on an audience receives nothing that was published without one, so set the publisher’s option before, or together with, the subscriber’s.

Channel Direction Addressing
Operator decisions (TrialOpened, SeatCapacitySet, ModuleGranted, TenantSuspended, OfferPublished, …) operator to every product Product subscribes for its own audience: BoxOfficeOptions.ProductAudience. The operator addresses what it publishes.
Offering, default offering, started tenants (OfferingDeclared, DefaultOfferingDeclared, TenantStartedOnOffer) product to operator Addressed to the operator: OperatorAudience.
Seat reports (SeatTaken, SeatReleased) and compute reports (AllowanceExhausted, ComputeDayClosed, ComputeDayCorrected) product to operator Addressed to the operator: OperatorAudience.
Support desk traffic (Usher) both UsherOptions.Audience filters; UsherOptions.DeskAudience addresses.
Notes published to a collector application to collector NotesOptions.CollectorAudience addresses; NotesOptions.Audience filters what comes back and names the sender.
Collector replies to a note collector to application Addressed automatically to the application that named itself with NotesOptions.Audience.
Marquee announcements authoring to a product MarqueeAuthoringOptions.AddressToProducts addresses by product; MarqueeOptions.SubscribeForProduct filters.
GuestList audience grants operator to a product GuestListAuthoringOptions.AddressToProducts addresses by product; GuestListOptions.SubscribeForProduct filters. The routing audience is separate from the Audience field of the events.

Two kinds of traffic are left alone on purpose. TenantRegistered and TenantProvisioned are one-to-one between an operator and the product that owns the tenant, and the event source (the organization) already identifies the pair. The Notes HTTP relay moves one application’s outbox to one collector and has no other recipient to tell apart. Note replies from the collector to an application are not addressed yet; see the limits below.

builder.AddBoxOffice(boxOffice =>
{
boxOffice.OperatorStores = ["Direct"];
boxOffice.ProductAudience = "studio"; // receive only what the operator addresses to "studio"
boxOffice.OperatorAudience = "direct"; // address every report to the operator "direct"
});
Option Default Meaning
ProductAudience unset The audience that identifies this product. When set, the subscription to each operator store carries audience=<value>, so the operator’s events for other products never reach this product’s inbox.
OperatorAudience unset The audience of the operator the product reports to. When set, everything the product appends to its outbox for the operator is tagged with it. It also sets OfferingOptions.OperatorAudience, which is what the offering declaration, the default offering, the started tenants and the metering use.

A blank value is refused when the host starts. With several OperatorStores, one OperatorAudience addresses everything the product reports, whichever operator reads it.

A product that uses only AddBoxOfficeOffering or AddBoxOfficeMetering, without AddBoxOffice, sets the operator audience on OfferingOptions:

builder.Services.Configure<OfferingOptions>(options => options.OperatorAudience = "direct");

The operator subscribes to the product’s outbox for itself, with the Chronicle subscription builder:

await eventStore.Subscriptions.Subscribe(
new EventStoreSubscriptionId("studio"),
"Studio",
subscription => subscription.ForAudience("direct"));

The same two ideas apply: the receiving side filters with an option, the publishing side addresses with another.

builder.Services.AddUsher(usher =>
{
usher.Audience = "studio"; // receive what the desk addresses to this application
usher.DeskAudience = "direct"; // address what Usher publishes to the desk
});
builder.Services.AddNotes(notes =>
{
notes.Audience = "studio";
notes.CollectorAudience = "direct";
});
builder.Services.AddMarquee(marquee => marquee.SubscribeForProduct = true); // filters on the value of Product
services.Configure<MarqueeAuthoringOptions>(options => options.AddressToProducts = true);

Marquee’s own Audiences (a module or plan audience that decides who sees an announcement) are a different thing: they are a property of the announcement, not a tag on the outbox event.

Chronicle’s [Audience] on an event type makes an audience mandatory: appending the event without one fails. No contract event is marked, because every option above is opt-in and a product that has not set one would start failing to publish. A host that wants the guarantee marks its own events, or adds its own IEventTagEnricher.

  • A subscription that changes its filter applies the new filter to events from then on; events already forwarded stay in the inbox.
  • Chronicle filters in the kernel, so the kernel has to be a version that supports filtered subscriptions.
  • A note carries the sending application’s NotesOptions.Audience as a from tag. The collector keeps it on the private fact it records and addresses OperatorAcknowledgedNote, OperatorAddressedNote and OperatorDeclinedNote to it, so an application that sets NotesOptions.Audience receives the answers to its own notes. A note from an application that set no Audience is answered unaddressed, so an application that wants its subscription filtered must set Audience; a collector that serves several applications needs every one of them to set it.
  • Notes over the HTTP transport relays event content, not tags, so from does not reach the collector and its answers come back unaddressed. Audience routing for notes applies to the Chronicle transport.