Events
A workflow can be started, or continued, by something that happened elsewhere.
Pushed. POST /api/events/<workflow> takes a
CloudEvent — structured (application/cloudevents+json),
a batch of up to a hundred (application/cloudevents-batch+json), or binary
(ce-id, ce-source, ce-type, ce-specversion headers with the data as the
body):
curl -X POST "$URL/api/events/paid" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/cloudevents+json" \
-d '{"specversion":"1.0","id":"evt-1","source":"/billing","type":"invoice.paid","data":{"invoice":4021}}'The run is named from the event's source and id, so an event delivered twice,
as anything that retries will do, finds the run the first delivery started. The
workflow receives the event's data as event, with type, subject and time
beside it. app.deliver(workflow, event) is the same from code. A run of that
workflow stopped at a wait step the event matches is continued instead, and
only when none is waiting is a run started.
Published. A workflow says which event types start it, and anything in the app can publish one:
// workflows/fulfil.ts
export default workflow({
on: "com.acme.order.placed",
steps: [{ id: "pack", ask: "Pack order {{event.order}}", agent: "warehouse" }],
});// functions/checkout.ts
export default fn({
input: { order: "the order id" },
run: async ({ order }, { publish }) => {
await publish?.("com.acme.order.placed", { order });
},
});app.publish(event) and POST /api/events do the same with a CloudEvent. Every
workflow that declared the type starts a run, and every run waiting for the
event continues. An event published twice with the same source and id starts
nothing new, and a step that is retried publishes the same event. The bus is in
this process: types match exactly, with no patterns; a chain of runs publishing
to each other is refused past sixteen deep; and what a publisher read as
untrusted does not mark the runs it starts.
Pulled. app.follow(source, workflow, { signal }) starts a run for every event
a Source yields and stores the cursor of the last one handled, so it continues
where it stopped after a restart.
On time. A clock is a source:
import { clock } from "@praecise/harness";
await app.follow(clock("nightly", { cron: "0 2 * * *", zone: "Europe/Lisbon" }), "report", { signal });
await app.follow(clock("poll", { every: 300 }), "sync", { signal });cron is five fields, read in zone (UTC unless said); every is in seconds.
The run receives scheduled and missed. catchUp says what happens to ticks
that fell due while nothing was running: "latest" (the default) runs the most
recent and counts the rest in missed, "all" runs each, "none" runs none.
There is no seconds field and no macros such as @daily, and nothing follows a
clock unless the app calls follow. cronNext(expression, after, zone) is the
arithmetic on its own.
Told. A run outlives whoever started it, so an app can say what its runs do to somebody who is not holding a connection open:
const app = await App.load({
root,
notify: { url: "https://ops.example.com/hooks/praecise", secret: process.env.HOOK_SECRET },
});Each run reports com.praecise.run.started, .waiting (stopped at a gate, with
the step and what is being asked), .done, .failed and .cancelled as
CloudEvents, once per change, except that two processes holding the same run may
each report its cancellation. The event names the run and its status and never carries what the run
produced. A { url, secret } target receives a signed webhook in the
Standard Webhooks form (webhook-id,
webhook-timestamp, webhook-signature), retried with backoff;
verifyWebhook(secret, headers, body) checks one on the receiving side. notify
may be a function instead. Delivery happens behind the run and cannot fail it; one
that does not arrive is listed in app.problems. app.onRunChange(listener)
hears the same changes in this process.
Described. GET /asyncapi.json is the events the app receives and sends, as
an AsyncAPI 3.1.0 document: the types its workflows start on and wait for, and
the notifications above. asyncApi(app) builds it.