@toa.io/extensions.cadence 1.0.0-alpha.284

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.284](https://github.com/toa-io/toa/compare/v1.0.0-alpha.283...v1.0.0-alpha.284) (2026-09-05)
+
+### Features
+
+* **cadence:** calls a component makes to itself, and calls it puts off ([8bbde5f](https://github.com/toa-io/toa/commit/8bbde5fc89e8e5549d5aa2bfcddb1beec0871565))

package/components/cadence.metronome/manifest.toa.yaml

@@ -0,0 +1,72 @@
+namespace: cadence
+name: metronome
+
+# The extension puts its dispatcher on this component, and nothing else here declares a cadence.
+cadence: ~
+
+entity:
+  schema:
+    type: object
+    properties:
+      lane:
+        description: Which dispatcher takes this row, as the outbox partitions its lanes
+        type: integer
+      due:
+        description: When the call is to be made, in milliseconds since the epoch
+        type: integer
+      expires:
+        description: >
+          After this the call is not made at all. A scan bounds on it, so a call nothing was
+          running to make in time is a row nobody reads, rather than an event anything sees.
+        type: integer
+      endpoint:
+        description: What to call, as `namespace.component.operation`
+        type: string
+      request:
+        description: The request to make, as it was handed over
+        type: object
+    required:
+      - lane
+      - due
+      - expires
+      - endpoint
+  index:
+    due:
+      lane: asc
+      due: asc
+
+# `enumerate` reads what is due and `terminate` cancels one; both come from the prototype.
+operations:
+  delay:
+    query: false
+    input:
+      type: object
+      properties:
+        endpoint:
+          type: string
+          pattern: ^[a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]*\.[a-zA-Z][_a-zA-Z0-9]*$
+        request:
+          type: object
+        interval:
+          description: Milliseconds from now
+          type: integer
+          minimum: 0
+        overdue:
+          description: >
+            Milliseconds the call may be late and still be made, or null for no bound. Stated
+            rather than defaulted: only the caller knows whether a late call is still the right
+            call.
+          type: integer
+          nullable: true
+          minimum: 0
+      required:
+        - endpoint
+        - interval
+        - overdue
+    output:
+      type: string
+
+  settle:
+    query: true
+    # a row may be cancelled while a page of them is being settled
+    concurrency: retry

package/components/cadence.metronome/operations/delay.js

@@ -0,0 +1,28 @@
+import { LANES } from '@toa.io/extensions.cadence'
+
+/**
+ * A call to make later. The request carries no query, so the transition is handed a new object.
+ *
+ * The lane is random, not one this replica owns. An outbox row is written into an owned lane so
+ * that in steady state a replica settles its own rows before it ever reads them — but a delayed
+ * row has no immediate path to settle, so nothing is gained, and an even spread is what the
+ * dispatchers want.
+ */
+export function transition (input, object) {
+  const due = Date.now() + input.interval
+
+  object.lane = Math.floor(Math.random() * LANES)
+  object.due = due
+  object.endpoint = input.endpoint
+
+  // absolute, because the bound is the caller's and a scan reads rows of many callers at once.
+  // No bound is the end of representable time rather than an absent field, so that one
+  // comparison answers for every row
+  object.expires = input.overdue === null ? Number.MAX_SAFE_INTEGER : due + input.overdue
+
+  // a call that takes no request has none: the entity's `request` is an object where it is
+  // there at all, and a null would not fit it
+  if (input.request !== undefined) object.request = input.request
+
+  return object.id
+}

package/components/cadence.metronome/operations/settle.js

@@ -0,0 +1,9 @@
+/**
+ * The rows whose calls have been made. They are tombstoned rather than removed: the record of
+ * what was asked for outlives the call, and a query answers only what is still owed.
+ */
+export function transition (_, objects) {
+  const now = Date.now()
+
+  for (const object of objects) object._deleted = now
+}

package/components/cadence.metronome/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/cadence.metronome/types/toa.d.ts

@@ -0,0 +1,45 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { Query } from '@toa.io/core'
+import type { Readable } from 'node:stream'
+
+export interface Entity {
+  /** Which dispatcher takes this row, as the outbox partitions its lanes */
+  lane: number
+  /** When the call is to be made, in milliseconds since the epoch */
+  due: number
+  /** After this the call is not made at all. A scan bounds on it, so a call nothing was running to make in time is a row nobody reads, rather than an event anything sees. */
+  expires: number
+  /** What to call, as `namespace.component.operation` */
+  endpoint: string
+  /** The request to make, as it was handed over */
+  request?: Record<string, unknown>
+  id: string
+  _version?: number
+  _created?: number
+  _updated?: number
+  _deleted?: number | null
+}
+
+export type DelayInput = {
+  endpoint: string
+  request?: Record<string, unknown>
+  /** Milliseconds from now */
+  interval: number
+  /** Milliseconds the call may be late and still be made, or null for no bound. Stated rather than defaulted: only the caller knows whether a late call is still the right call. */
+  overdue: number | null
+}
+
+export type DelayOutput = string
+
+export interface Component {
+  delay: (request: { input: DelayInput, task?: boolean }) => Promise<DelayOutput>
+  settle: (request: { input?: null, query: Query<Entity>, task?: boolean }) => Promise<unknown>
+  assign: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  ensure: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  enumerate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity[]>
+  observe: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity | null>
+  stream: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Readable>
+  terminate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@toa.io/extensions.cadence",
+  "version": "1.0.0-alpha.284",
+  "type": "module",
+  "description": "Toa Schedule",
+  "author": "temich <tema.gurtovoy@gmail.com>",
+  "homepage": "https://github.com/toa-io/toa#readme",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@toa.io/core": "1.0.0-alpha.284",
+    "@toa.io/schemas": "1.0.0-alpha.283",
+    "openspan": "1.0.0-alpha.277"
+  },
+  "scripts": {
+    "transpile": "tsc"
+  }
+}

package/readme.md

@@ -0,0 +1,188 @@
+# Toa Cadence
+
+Calls a component makes to itself, and calls it puts off.
+
+A **pulse** calls an operation of its own component on a cadence its manifest states. A **delay**
+hands one call over to be made later.
+
+Both rest on [`atomicity`](/connectors/atomicity), which is what keeps two replicas from making
+one call and where that promise is written down. Where it is not configured, nothing is called
+at all.
+
+## Pulse
+
+```yaml
+# manifest.toa.yaml
+cadence:
+  sweep:                # an operation of this component
+    cycle: 86400        # seconds one whole cycle takes
+    intervals: 24       # what it is split into, so one call an hour
+```
+
+The gap between calls is `cycle / intervals`, derived rather than declared, so the two cannot
+disagree. `intervals` defaults to `1`, one call per cycle, which is also what the shorthand
+declares:
+
+```yaml
+# manifest.toa.yaml
+cadence:
+  sweep: 3600           # once an hour
+```
+
+The operation is called with the cycle and the interval as its input:
+
+```javascript
+async function sweep ({ n, i }, context) { }
+```
+
+`n` is `intervals` and `i` is which of them this call is for, from `0` to `n - 1`. They are there
+so that one sweep can be spread across its cycle rather than run whole every time: an operation
+that takes `i` as its share of the work does a twenty-fourth of it every hour instead of all of
+it at midnight.
+
+A pulse may name any operation a receiver may — `transition`, `assignment`, `effect` or
+`unmanaged`. An operation that produces no side effects has nothing to be called periodically
+for.
+
+A cycle is measured from the Unix epoch rather than from a calendar, so `86400` means UTC
+midnight and `3600` the top of the hour. A cycle that is not a divisor of a day lands on a
+boundary that is not any particular time of day. Time zones and calendar months are not
+supported.
+
+### What to expect
+
+**An interval may not be called.** A rollout, a crash, or an operation that raised or ran past
+its own interval each cost that interval, and nothing makes it up afterwards.
+
+**So select by state, not by position.** With `intervals` above `1` the shares are a partition —
+`i = 5` missed is not covered by `i = 6`, and waits a whole cycle. Write the operation to take
+what in its share is still due, rather than everything in its share, and a missed interval costs
+a delay instead of a day. An operation written the other way loses a day's work to a
+thirty-second rollout.
+
+Where a call has to happen even if nothing was running when it came due, it needs a stored
+schedule: [`delay`](#delay) is one.
+
+**An interval is called once.** Two calls for one interval need the clocks of two machines to
+disagree and the work to change hands in the same moment, which is a window the width of that
+disagreement.
+
+**A call is never made while the one before it is still running.** If the work does not fit the
+gap the interval is skipped and says so; where that is logged, the cycle is too short or has too
+few intervals.
+
+**An operation that raises loses its interval, and nothing is retried.** Skipping is a choice
+rather than a conclusion, and there is no setting for it — retrying would be as defensible, and
+either answer put to everyone who wanted an operation called every hour is a worse cost than
+picking one.
+
+`intervals` is not a replica count. With `intervals: 24` and three replicas each makes eight of
+the day's calls: the cycle is spread over *time*, not over the fleet. Replicas beyond `intervals`
+make none.
+
+## Delay
+
+```javascript
+const id = await context.delay('mail.sender.remind', { input: { user } },
+  { interval: 7 * 24 * 3600 * 1000, overdue: null })
+
+await context.delay.cancel(id)
+```
+
+| | |
+|---|---|
+| `interval` | milliseconds from now |
+| `overdue` | milliseconds the call may be late and still be made, or `null` for no bound |
+
+The call is made once the delay has passed, and waits for the target where it is not there to
+take it. The id it answers cancels it, and `cancel` raises where the id was never issued.
+
+Nothing is declared for it beyond naming the extension. A component that only delays calls says
+so with an empty declaration:
+
+```yaml
+# manifest.toa.yaml
+cadence: ~
+```
+
+### How late is too late
+
+`overdue` bounds lateness, and lateness is mostly what a failure causes rather than what the
+ordinary path has: a call is made at the moment it is due. How much is left of that in practice
+depends on how coarsely the calls are looked over — see [Discreteness](#discreteness).
+
+| | |
+|---|---|
+| `null` | no bound: made whenever it can be, however late that is |
+| `0` | on time or never |
+| a number | made if no more than that many milliseconds late |
+
+**There is no default, and it is stated on every call.** Only the caller knows whether a late
+call is still the right call — an unpaid order expires on time or not at all, a report is wanted
+whenever it can be had — and nothing else in the system can tell those apart. A default would
+answer for it, and either answer is wrong for somebody: the wrong `null` makes a stale call, and
+the wrong number drops a call and says nothing.
+
+### Discreteness
+
+Calls waiting to be made are looked over on a period — `discreteness`, a minute by default — and
+everything here is measured against it.
+
+**A delay shorter than `discreteness` is served late.** It is made at the next pass rather than
+at the moment it was due, so a five second delay under a one minute `discreteness` lands up to a
+minute after it was asked for. A delay longer than `discreteness` is made on time, because the
+pass before it has already set it going.
+
+**An `overdue` shorter than `discreteness` can be missed where nothing is wrong**, and combined
+with a delay shorter than it will almost always be: the pass that would have made the call finds
+it already past its bound and leaves it. State an `overdue` several times `discreteness`, or
+`null`.
+
+**A cancellation is reliable while the call is further out than `discreteness`**, and is a race
+closer than that, where the call may already be on its way.
+
+So `discreteness` and `overdue` are chosen together against what the application needs. A call
+that must be made within seconds of its time, or cancellable within seconds of it, needs a
+`discreteness` of seconds — at the cost of looking the calls over that much more often.
+
+### What to expect
+
+**A call may be made more than once**, so where a second one would cost something, the target
+has to be the one that refuses it.
+
+**A call may not be made at all**, in four ways:
+
+- **the caller crashed** between committing its own change and handing the call over. This is
+  not transactional with your state, and nothing can tell — where the semantics allow it, hand
+  the call over first;
+- **it expired**, having been given an `overdue` and nothing having been able to make it in
+  time;
+- **it was cancelled** — which is reliable while the call is further out than `discreteness`,
+  and a race closer than that;
+- **it could not be made.** One attempt is given, so a call that could not go out is reported
+  and dropped rather than tried again — the same choice a pulse makes, for the same reason.
+
+What is reported here is a call that could not be made at all. An exception the operation itself
+raises belongs to the component that raised it and is reported there.
+
+A pulse trades the other way: its receiver selects by state, so a skipped interval heals itself
+and a second call is the expensive failure.
+
+### The horizon
+
+A horizon of years costs nothing, and a call put off that long is worth no more than the target
+that will be there to take it: the target may be gone by the time it comes due, and its input
+may no longer be one it accepts. Either way the attempt is spent.
+
+## Configuration
+
+```yaml
+# context.toa.yaml
+cadence:
+  discreteness: 60    # seconds between passes over the calls waiting to be made
+```
+
+`discreteness` is how often the calls waiting to be made are looked over. It defaults to 60,
+which is what an application that states nothing gets. It is the floor under how closely a
+delayed call can be cancelled and how small an `overdue` is worth stating — see
+[Discreteness](#discreteness) — and lowering it costs a pass that runs more often.

package/schemas/annotation.cos.yaml

@@ -0,0 +1,9 @@
+# context.toa.yaml cadence annotation
+type: object
+nullable: true
+properties:
+  discreteness:
+    description: Seconds between passes over the calls waiting to be made
+    type: integer
+    minimum: 1
+additionalProperties: false

package/schemas/declaration.cos.yaml

@@ -0,0 +1,21 @@
+# manifest.toa.yaml cadence declaration: the operations called on a cadence
+type: object
+propertyNames:
+  pattern: ^[a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?$
+patternProperties:
+  ".*":
+    type: object
+    properties:
+      cycle:
+        description: Seconds one whole cycle takes
+        type: integer
+        minimum: 1
+      intervals:
+        description: >
+          Intervals the cycle is split into. The gap between calls is `cycle / intervals`,
+          and the operation is told which interval it is running for.
+        type: integer
+        minimum: 1
+        default: 1
+    required: [cycle]
+    additionalProperties: false

package/source/Aspect.ts

@@ -0,0 +1,64 @@
+import { Connector } from '@toa.io/core'
+import type { Local } from './Local.js'
+import type { Options } from './types.js'
+
+interface Input {
+  endpoint: string
+  interval: number
+  overdue: number | null
+  request?: object
+}
+
+/**
+ * `context.delay(endpoint, request, delay)` — a call to be made later, handed to the component
+ * that keeps them.
+ *
+ * It is not transactional with the caller's state. A crash between committing a change and
+ * handing over the call it should have scheduled loses the call, and there is no way for this
+ * to know. Where the semantics allow it, hand the call over first.
+ *
+ * @implements {toa.core.extensions.Aspect}
+ */
+export class Aspect extends Connector {
+  public readonly name = 'delay'
+
+  private readonly metronome: Local
+
+  public constructor (metronome: Local) {
+    super()
+
+    this.metronome = metronome
+
+    this.depends(metronome)
+  }
+
+  // named rather than forwarded, so that the connector's lifecycle is not reachable from an
+  // algorithm — the same reason the atom aspect names its own
+  public async invoke (method: string, ...args: any[]): Promise<unknown> {
+    switch (method) {
+      case 'delay': return await this.delay(args[0], args[1], args[2])
+      case 'cancel': return await this.cancel(args[0])
+      default: throw new Error(`Delay aspect has no '${method}' method`)
+    }
+  }
+
+  /** Answers the id the call was given, which is what cancels it. */
+  private async delay (endpoint: string, request: object | null,
+    options: Options): Promise<unknown> {
+    const input: Input = { endpoint, interval: options.interval, overdue: options.overdue }
+
+    // a call that takes no request carries none, rather than a null one
+    if (request !== null && request !== undefined) input.request = request
+
+    return await this.metronome.invoke('delay', { input })
+  }
+
+  /**
+   * Tombstones the row, which is the prototype's `terminate`. An id that was never issued has
+   * nothing to terminate and raises; one whose call has already been made has a row still, and
+   * terminating it again is not an error.
+   */
+  private async cancel (id: string): Promise<unknown> {
+    return await this.metronome.invoke('terminate', { query: { id }, input: null })
+  }
+}

package/source/Composition.ts

@@ -0,0 +1,47 @@
+import { readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Connector } from '@toa.io/core'
+import type { Dirent } from 'node:fs'
+import type { Host } from './Factory.js'
+
+/** The components this extension ships, which run inside its own service. */
+export function components (): Components {
+  const labels: string[] = []
+  const paths: string[] = []
+
+  for (const entry of entries()) {
+    labels.push(entry.name.replace('.', '-'))
+    paths.push(resolve(ROOT, entry.name))
+  }
+
+  return { labels, paths }
+}
+
+export class Composition extends Connector {
+  private readonly host: Host
+
+  public constructor (host: Host) {
+    super()
+
+    this.host = host
+  }
+
+  protected override async open (): Promise<void> {
+    const composition = await this.host.composition(components().paths)
+
+    await composition.connect()
+
+    this.depends(composition)
+  }
+}
+
+function entries (): Dirent[] {
+  return readdirSync(ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+}
+
+interface Components {
+  labels: string[]
+  paths: string[]
+}
+
+const ROOT = resolve(import.meta.dirname, '../components/')