Lifecycle events: a message when a webhook endpoint (a source) or a route is created, updated, or deleted.

Off by default. config.lifecycle.sinks (YAML: lifecycle.sinks) is a list of Ankusa.Sinks, shaped like a source's; with at least one, every change made through Ankusa.SourceStore.put/5, Ankusa.SourceStore.delete/3, or Ankusa.Routes (the admin API and the route-management API are both thin wrappers over those) becomes one CloudEvents 1.0 event delivered to those sinks.

A durable outbox

The event is not a message handed to a process; it is a row. The change's audit row (Ankusa.Audit) is flagged publish: true and carries, beside it and in the same synced batch, the redacted entity the event reports. So the change and its event are committed or lost together: a kill -9 right after Ankusa.SourceStore.put/5 returns still delivers source.created after the restart.

Ankusa.Lifecycle.Publisher is a cursor reader over those rows. It keeps the last seq it delivered to every sink in m:lifecycle_cursor (synced on every advance), delivers the next flagged row to every sink, and moves on once each sink confirmed or gave up. Rows are read in seq order, which is commit order, so three rapid updates of one source arrive in revision order. Ankusa.Replay with kind: :lifecycle re-emits a window of the trail (since/until/tenant), which is how a sink that was down for longer than dispatch.retry waits is caught up.

Delivery is at least once. A node killed between a sink's confirmation and the cursor write delivers that event again after the restart, and so does a replay; both carry the same event id (see below), so a consumer dedupes on it. A sink that keeps failing holds back the events behind it until it succeeds or dispatch.retry gives up ([:ankusa, :lifecycle, :dropped], reason :gave_up); the event is then lost for that sink and can be replayed.

Turning lifecycle events on starts the outbox at the end of the trail: changes made while they were off are not announced.

The reserved id exists only on the event: the edge never resolves it, so POST /webhooks/ankusa:lifecycle is a 404. The colon keeps it out of reach of every tenant-scoped id, which is [A-Za-z0-9_-] joined by a dot.

The event

A structured-mode CloudEvent, carried as the body of a Ankusa.Sink.Message with content_type: "application/cloudevents+json":

• id — derived from the row, never minted: a keyed hash of the instance, the row's seq and (for a row written after a restore from a backup) the incarnation it belongs to, laid out as a UUID. The same row is the same id whenever and however often it is emitted; a restored store that re-issues a seq the lost one had published gives it a different one.
• type — io.ankusa.source.{created,updated,deleted}, io.ankusa.route.{created,updated,deleted}, io.ankusa.tenant.deleted (a tenant erase, Ankusa.Tenant, after the deleted event of each source and route it removed; its data is {"tenant": <id>} and its subject the tenant id), or io.ankusa.instance.restored (below)
• source — urn:ankusa:instance:<instance>
• subject — the source id (<tenant>.<name>) or the route id
• time — when the change committed (the row's time, not the publisher's)
• data — the entity as the admin API shows it, redacted by Ankusa.Admin.Redact, as the change left it; for a deletion, as it was the moment before
• revision — the subject's change counter (see Ankusa.Audit): a consumer keeps the highest it has seen per subject and ignores a lower one. Absent for a store that keeps none (the Redis source store)
• actor — the principal id that made the change (system for code)
• instance — the instance name
• sequence — the audit seq, a decimal string: events of one instance are totally ordered by it
• replayid — only on an event a replay job re-emitted
• traceparent, tracestate — the CloudEvents distributed-tracing extension, only when an OpenTelemetry SDK runs: the context of the ankusa.lifecycle.event span that built the event (traced_envelope/4). Not part of the event's identity: a re-emitted event keeps its id and gets the trace of the emission

A route event's envelope carries the route's tenant (tenant_id; "default" for a route that belongs to none), so a replay filtered by tenant and a tenant-limited reader of GET /v1/audit see their own routes' changes.

A restore is announced

A store restored from a backup (Ankusa.Store.Backup) resumes the audit trail at the backup's seq, so it re-issues sequence numbers, and per-subject revisions, that the lost node had already published. Before it takes any change it emits io.ankusa.instance.restored (subject = the instance name; data = incarnation, the fresh id the following event ids are keyed with, and restored_sequence, the last seq the restored trail held). A consumer that keeps the highest sequence or revision it has seen must reset that state for this instance when it sees it: ordering restarted at restored_sequence + 1. Events of the restored trail itself keep the ids they were published under.

A change nobody saw finish

A source in the Redis store or a route is a dual write (see Ankusa.Audit), so a node killed in the middle leaves a pending row. reconcile/2 settles it from the subject's present state instead of guessing: the state hashes to the row's after_hash, the change was applied ("ok", announced); to its before_hash, it was not ("failed", not announced); to neither, somebody changed it meanwhile, and the row stays "interrupted" and announces a state-refresh event carrying the current entity and revision.