Praecise Harness v1.1.0 Get started

Documentation · Building

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):

sh
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:

ts
// workflows/fulfil.ts
export default workflow({
  on: "com.acme.order.placed",
  steps: [{ id: "pack", ask: "Pack order {{event.order}}", agent: "warehouse" }],
});
ts
// 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:

ts
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:

ts
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.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.