Skip to main content

Eventing & async work

When one service needs to tell another that something happened — a file was uploaded, an invoice was paid, a rule fired — it publishes an event. Other services subscribe.

What you'll learn​

  • Why we use events for cross-service work
  • The delivery guarantee (at-least-once)
  • How to publish and consume events from a service

Why events​

Synchronous service-to-service calls are easy to write but they create coupling:

  • If service B is slow, service A waits.
  • If service B is down, service A errors.
  • Service A has to know about service B at all.

With events, service A publishes "something happened" and walks away. Service B (and C, D, E) read the event when they're ready. A doesn't care who's listening or whether anyone is.

The platform's eventing layer​

Cross-service events use a durable streaming bus with at-least-once delivery and consumer groups.

// Publish (from a service or plugin)
await events.publish('file.uploaded', {fileId, workspaceId, uploadedBy});

// Consume (in another service)
events.consume('file.uploaded', 'thumbnail-worker', async (event) => {
await generateThumbnail(event.fileId);
});
  • publish writes to a named event stream.
  • consume reads via a consumer group — multiple workers share the load.

Delivery guarantees​

GuaranteeYes / No
At-least-once delivery✅ Yes
Exactly-once delivery❌ No — design consumers to be idempotent
Ordering within a key✅ Yes, within a single Stream partition
Cross-stream ordering❌ No

Always make consumers idempotent. A retry of the same event should produce the same result as the first delivery.

Common patterns​

PatternHow
Background work after a sync API callPublish event from the resolver, consume in a worker
Fan-out to many consumersMultiple consumer groups on the same stream
Cross-tenant signalAlways include tenantId in the event payload; consumer filters
Schedule a job for laterUse the scheduler module

Operational notes​

  • Streams are durable but not infinite — set retention per stream
  • Dead-letter queue (DLQ) handling is built into the SDK: events that fail N times move to a :dlq stream
  • Monitor consumer lag via metrics shipped by the SDK

Next steps​