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

package/source/Pulse.test.ts

@@ -0,0 +1,274 @@
+import { it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pulse } from './Pulse.js'
+import type { Local } from './Local.js'
+import type { Locator, Request, atomicity } from '@toa.io/core'
+
+type Invoke = (endpoint: string, request: Request) => Promise<unknown>
+type Slots = (total: number) => number[] | null
+
+let local: Local & { invoke: ReturnType<typeof mock.fn<Invoke>> }
+let atom: atomicity.Atom & { slots: ReturnType<typeof mock.fn<Slots>> }
+
+const SECOND = 1000
+const HOUR = 3600
+const DAY = 24 * HOUR
+
+const locator = { id: 'tea.pots' } as Locator
+
+const range = (total: number): number[] => Array.from({ length: total }, (_, index) => index)
+
+/** what a Pulse reaches for, with a lifecycle it can connect through */
+const connector = (properties: object): any =>
+  ({ ...properties, link: mock.fn(), connect: async () => {}, disconnect: async () => {} })
+
+const create = (cycle: number, intervals: number): Pulse =>
+  new Pulse({ locator, endpoint: 'sweep', cycle, intervals }, local, atom)
+
+/** the timers the tick arms are the only ones, so a tick is a jump and its microtasks */
+const advance = async (ms: number): Promise<void> => {
+  mock.timers.tick(ms)
+
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
+/** which interval each call was told it was for */
+const intervals = (): number[] =>
+  local.invoke.mock.calls.map((call) => (call.arguments[1].input as { i: number }).i)
+
+
+beforeEach(() => {
+  mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 0 })
+
+  local = connector({ invoke: mock.fn<Invoke>(async () => undefined) })
+
+  // one replica of one: every slot of the cycle is its own
+  atom = connector({ slots: mock.fn<Slots>((total) => range(total)) })
+})
+
+afterEach(() => {
+  mock.timers.reset()
+})
+
+it('should split a cycle into intervals', () => {
+  const pulse = create(DAY, 24)
+
+  assert.strictEqual(pulse.index(0), 0)
+  assert.strictEqual(pulse.index(HOUR * SECOND - 1), 0)
+  assert.strictEqual(pulse.index(HOUR * SECOND), 1)
+  assert.strictEqual(pulse.index(23 * HOUR * SECOND), 23)
+  assert.strictEqual(pulse.index(DAY * SECOND), 0)
+})
+
+it('should give every interval of a cycle that does not divide evenly', () => {
+  const pulse = create(DAY, 7)
+  const seen = new Set<number>()
+
+  let now = 0
+
+  for (let step = 0; step < 7; step++) {
+    seen.add(pulse.index(now))
+    now = pulse.boundary(now)
+  }
+
+  assert.deepStrictEqual([...seen].sort((a, b) => a - b), [0, 1, 2, 3, 4, 5, 6])
+  assert.strictEqual(now, DAY * SECOND, 'seven boundaries land exactly on the next cycle')
+})
+
+it('should not drift across cycles', () => {
+  const pulse = create(DAY, 7)
+
+  let now = 0
+
+  for (let step = 0; step < 7 * 100; step++) now = pulse.boundary(now)
+
+  assert.strictEqual(now, 100 * DAY * SECOND)
+})
+
+it('should treat the interval it starts in as already handled', async () => {
+  const pulse = create(DAY, 24)
+
+  mock.timers.setTime(30 * 60 * SECOND) // half past the first hour
+
+  await pulse.connect()
+  await advance(0)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 0)
+})
+
+it('should call at the boundary', async () => {
+  const pulse = create(DAY, 24)
+
+  mock.timers.setTime(30 * 60 * SECOND)
+
+  await pulse.connect()
+
+  await advance(30 * 60 * SECOND - 1)
+  assert.strictEqual(local.invoke.mock.callCount(), 0, 'not a millisecond early')
+
+  await advance(1)
+  assert.strictEqual(local.invoke.mock.callCount(), 1)
+})
+
+it('should tell the operation which interval it is', async () => {
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+  await advance(HOUR * SECOND)
+
+  const [endpoint, request] = local.invoke.mock.calls[0].arguments
+
+  assert.strictEqual(endpoint, 'sweep')
+  assert.deepStrictEqual(request, { input: { n: 24, i: 1 } })
+})
+
+it('should call once per interval, and every interval of a cycle', async () => {
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+
+  for (let hour = 0; hour < 24; hour++) await advance(HOUR * SECOND)
+
+  assert.deepStrictEqual(intervals(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+    17, 18, 19, 20, 21, 22, 23, 0])
+})
+
+it('should keep calling a cycle it is not splitting', async () => {
+  const pulse = create(HOUR, 1)
+
+  await pulse.connect()
+
+  for (let cycle = 0; cycle < 3; cycle++) await advance(HOUR * SECOND)
+
+  assert.deepStrictEqual(intervals(), [0, 0, 0])
+})
+
+it('should not call while this replica owns nothing', async () => {
+  atom.slots.mock.mockImplementation(() => null)
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+  await advance(HOUR * SECOND)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 0)
+})
+
+it('should not call an interval it acquired after the boundary', async () => {
+  atom.slots.mock.mockImplementation(() => [])
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+  await advance(HOUR * SECOND) // the boundary passes, and the interval is not this one's
+
+  atom.slots.mock.mockImplementation((total) => range(total))
+
+  await advance(30 * 60 * SECOND) // and half an hour later it is
+
+  assert.strictEqual(local.invoke.mock.callCount(), 0,
+    'the replica that held it at the boundary is the only one that could have called')
+})
+
+it('should not call an interval another replica owns', async () => {
+  atom.slots.mock.mockImplementation((total) =>
+    range(total).filter((slot) => slot % 2 === 0))
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+
+  for (let hour = 0; hour < 24; hour++) await advance(HOUR * SECOND)
+
+  const called = intervals()
+
+  assert.strictEqual(called.length, 12)
+  assert.ok(called.every((i) => i % 2 === 0))
+})
+
+it('should not start a call while the one before has not returned', async () => {
+  let release: () => void = () => {}
+
+  local.invoke.mock.mockImplementation(async () =>
+    await new Promise<void>((resolve) => { release = resolve }))
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+
+  await advance(HOUR * SECOND)
+  await advance(HOUR * SECOND)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 1)
+
+  release()
+  await advance(0) // the call settles, and only then is the pulse free again
+
+  await advance(HOUR * SECOND)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 2)
+})
+
+it('should keep its cadence when a call raises', async () => {
+  local.invoke.mock.mockImplementationOnce(async () => { throw new Error('nope') })
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+
+  await advance(HOUR * SECOND)
+  await advance(HOUR * SECOND)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 2,
+    'the interval that raised is skipped, and the next one is called')
+})
+
+it('should wait out a cycle longer than one timer in instalments', async () => {
+  const YEAR = 365 * DAY
+
+  const pulse = create(YEAR, 1)
+
+  await pulse.connect()
+
+  // more than `setTimeout` takes at once, and nothing is due yet
+  await advance(2 ** 31)
+  assert.strictEqual(local.invoke.mock.callCount(), 0)
+
+  await advance(YEAR * SECOND)
+  assert.strictEqual(local.invoke.mock.callCount(), 1)
+})
+
+it('should wait for a call in flight before closing', async () => {
+  let release: () => void = () => {}
+  let closed = false
+
+  local.invoke.mock.mockImplementation(async () =>
+    await new Promise<void>((resolve) => { release = resolve }))
+
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+  await advance(HOUR * SECOND)
+
+  const closing = pulse.disconnect().then(() => { closed = true })
+
+  await advance(0)
+  assert.strictEqual(closed, false, 'the call is still running')
+
+  release()
+  await advance(0)
+  await closing
+
+  assert.strictEqual(closed, true)
+})
+
+it('should stop calling once closed', async () => {
+  const pulse = create(DAY, 24)
+
+  await pulse.connect()
+  await pulse.disconnect()
+  await advance(HOUR * SECOND)
+
+  assert.strictEqual(local.invoke.mock.callCount(), 0)
+})

package/source/Pulse.ts

@@ -0,0 +1,202 @@
+import { console } from 'openspan'
+import { Connector } from '@toa.io/core'
+import type { Local } from './Local.js'
+import type { SpanOptions } from 'openspan'
+import type { Locator, atomicity } from '@toa.io/core'
+
+/**
+ * A recurring call to an operation of its own component, on the cadence its manifest states.
+ *
+ * Nothing is stored. The cycle is split into `n` intervals and the current one is a function of
+ * the clock, so every replica computes the same `i` without talking to any other; the one that
+ * owns `i` is the one that calls. An interval no replica was alive for is not made up
+ * afterwards — the operation is expected to select by what is still due rather than by where
+ * the cycle has reached.
+ */
+export class Pulse extends Connector {
+  private readonly endpoint: string
+  private readonly label: string
+
+  /** milliseconds one whole cycle takes */
+  private readonly cycle: number
+
+  /** intervals the cycle is split into */
+  private readonly n: number
+
+  private readonly local: Local
+  private readonly atom: atomicity.Atom
+
+  /** span options, built once */
+  private readonly options: SpanOptions
+
+  /**
+   * The ordinal of the interval this process has already handled, so an early wake-up is not a
+   * second call. An ordinal and not an index: with one interval per cycle the index never
+   * changes, and comparing it would suppress every call after the first.
+   */
+  private fired = 0
+
+  private timer?: NodeJS.Timeout
+
+  /** the call in flight, awaited on close */
+  private firing?: Promise<unknown>
+
+  private closing = false
+
+  public constructor (definition: Definition, local: Local, atom: atomicity.Atom) {
+    super()
+
+    const { locator, endpoint, cycle, intervals } = definition
+
+    this.endpoint = endpoint
+    this.label = `${locator.id}.${endpoint}`
+    this.cycle = cycle * 1000
+    this.n = intervals
+
+    this.local = local
+    this.atom = atom
+
+    this.depends(local)
+    this.depends(atom)
+
+    this.options = {
+      name: `${this.label} pulse`,
+      kind: 'producer',
+      service: locator.id
+    }
+  }
+
+  /**
+   * How many intervals have passed since the epoch, `now` included. Against the cycle rather
+   * than by adding up gaps, so a cycle that does not divide evenly into its intervals neither
+   * drifts nor accumulates error.
+   *
+   * The arithmetic is exact rather than double: `now` is milliseconds since 1970 and `n` may be
+   * as large as the cycle has seconds, so their product leaves the range a double is exact in
+   * for a long cycle cut finely. It is evaluated once per interval, where this costs nothing.
+   */
+  public ordinal (now: number): number {
+    return Number(BigInt(now) * BigInt(this.n) / BigInt(this.cycle))
+  }
+
+  /** Which of the cycle's intervals `now` falls in. */
+  public index (now: number): number {
+    return this.ordinal(now) % this.n
+  }
+
+  /** When the interval `now` falls in gives way to the next one. */
+  public boundary (now: number): number {
+    const cycle = BigInt(this.cycle)
+    const n = BigInt(this.n)
+    const next = BigInt(this.ordinal(now) + 1)
+
+    // the earliest millisecond whose ordinal is the next one
+    return Number((next * cycle + n - 1n) / n)
+  }
+
+  protected override async open (): Promise<void> {
+    // whatever interval it is now, this replica was not there when it began, so it is not
+    // this one's to call — the first call is at the next boundary
+    this.fired = this.ordinal(Date.now())
+
+    this.arm()
+  }
+
+  protected override async close (): Promise<void> {
+    this.closing = true
+
+    clearTimeout(this.timer)
+
+    // a call still running holds the remote it was made through, which is torn down after
+    // this returns. Bounded, because an operation that never returns would outlive any
+    // grace period and the interval is over either way
+    if (this.firing !== undefined)
+      await Promise.race([this.firing, delay(DRAIN)])
+  }
+
+  private arm (): void {
+    const now = Date.now()
+
+    // a delay past this fires at once rather than late, so a long cycle is waited out in
+    // instalments; the wake-up finds the same interval and simply arms again
+    const wait = Math.min(this.boundary(now) - now, MAX_DELAY)
+
+    this.timer = setTimeout(() => this.tick(), wait)
+    this.timer.unref()
+  }
+
+  private tick (): void {
+    if (this.closing) return
+
+    const ordinal = this.ordinal(Date.now())
+
+    // a timer may wake a millisecond before the boundary it was set for, and a cycle longer
+    // than one timer wakes several times on the way — both are the interval already handled
+    if (ordinal !== this.fired) {
+      this.fired = ordinal
+
+      void this.fire(ordinal % this.n)
+    }
+
+    this.arm()
+  }
+
+  /**
+   * Nothing queues here. A call still running when the next boundary arrives means the work
+   * does not fit the gap, and starting a second one would only make that worse.
+   */
+  private async fire (i: number): Promise<void> {
+    if (this.firing !== undefined) {
+      console.warn('Pulse skipped: the previous call has not returned',
+        { pulse: this.label, interval: i })
+
+      return
+    }
+
+    const owned = this.atom.slots(this.n)
+
+    if (owned === null) {
+      console.warn('Pulse skipped: this replica owns nothing',
+        { pulse: this.label, interval: i })
+
+      return
+    }
+
+    if (!owned.includes(i)) return
+
+    /*
+     * A pulse calls and waits, so an operation that raised comes back as an exception here —
+     * the runtime carries it across and rethrows it in this process. What to do about one is a
+     * choice with no right answer, and asking would put the whole of it in front of anyone who
+     * only wanted an operation called every hour. So the interval is skipped: it is reported,
+     * and the next one is called as though it had not happened.
+     */
+    const firing = console.span(this.options,
+      async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } }))
+      .catch((error: unknown) => {
+        console.error('Pulse failed', { pulse: this.label, interval: i, error })
+      })
+      .finally(() => { this.firing = undefined })
+
+    this.firing = firing
+
+    await firing
+  }
+}
+
+export interface Definition {
+  locator: Locator
+  endpoint: string
+  cycle: number
+  intervals: number
+}
+
+async function delay (ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms).unref())
+}
+
+/** `setTimeout` fires immediately past this, so a longer wait is taken in instalments */
+const MAX_DELAY = 2 ** 31 - 1
+
+/** how long a call in flight is waited for on close */
+const DRAIN = 10_000

package/source/const.ts

@@ -0,0 +1,23 @@
+/** The component the extension ships to hold delayed calls. */
+export const NAMESPACE = 'cadence'
+export const COMPONENT = 'metronome'
+
+/**
+ * Constant, never configuration: a row carries its lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas dispatching, and a power of
+ * two so that the common replica counts divide evenly. The outbox says the same of its own.
+ */
+export const LANES = 128
+
+/** seconds between passes over the calls waiting to be made, and how far ahead each reaches */
+export const DISCRETENESS = 60
+
+/** rows one scan brings back */
+export const BATCH = 200
+
+/** A number from the environment, where a deployment or a test suite states one. */
+export function number (variable: string, fallback: number): number {
+  const value = Number(process.env[variable])
+
+  return Number.isNaN(value) || value <= 0 ? fallback : value
+}

package/source/context.ts

@@ -0,0 +1,10 @@
+import type { Contribution } from '@toa.io/core'
+
+/** What this extension puts on the context of a component that declares it. */
+export function context (): Contribution {
+  return {
+    name: 'delay',
+    type: 'Delay',
+    imports: { '@toa.io/extensions.cadence': ['Delay'] }
+  }
+}

package/source/deployment.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs'
+import { components } from './Composition.js'
+import { DISCRETENESS, NAMESPACE } from './const.js'
+import * as schemas from './schemas.js'
+import type { Annotation } from './types.js'
+import type { Dependency, Service, Variable } from '@toa.io/operations'
+
+/**
+ * The component that keeps delayed calls runs in a service of its own, the way the identity
+ * components run in the gateway. A composition may claim it and run it in its own pods instead.
+ */
+export function deployment (_: unknown, annotation?: Annotation | null): Dependency {
+  schemas.annotation.validate<Annotation | null>(annotation ?? null, 'Invalid cadence annotation')
+
+  // stated in seconds and carried in milliseconds, so that what an application writes is what
+  // the rest of a manifest is written in
+  const discreteness = (annotation?.discreteness ?? DISCRETENESS) * 1000
+  const variables: Variable[] =
+    [{ name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }]
+
+  const service: Service = {
+    group: NAMESPACE,
+    name: 'metronome',
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    components: components().labels,
+    variables
+  }
+
+  return { services: [service] }
+}
+
+/** The extension is deployed for the sake of `delay`, which nothing has to declare to use. */
+export const standalone = true

package/source/index.ts

@@ -0,0 +1,8 @@
+export { Factory } from './Factory.js'
+export { manifest } from './manifest.js'
+export { components } from './Composition.js'
+export { deployment, standalone } from './deployment.js'
+export { context } from './context.js'
+export { LANES } from './const.js'
+
+export type { Declaration, Delay, Pulse } from './types.js'

package/source/manifest.test.ts

@@ -0,0 +1,58 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { manifest } from './manifest.js'
+import type { Manifest } from '@toa.io/norm'
+
+const component = {
+  operations: {
+    sweep: { type: 'effect' },
+    gather: { type: 'transition' },
+    peek: { type: 'observation' }
+  }
+} as unknown as Manifest
+
+it('should normalize a declaration', () => {
+  const declaration = manifest({ sweep: { cycle: 86400, intervals: 24 } }, component)
+
+  assert.deepStrictEqual(declaration, { sweep: { cycle: 86400, intervals: 24 } })
+})
+
+it('should split a cycle into one interval by default', () => {
+  const declaration = manifest({ sweep: { cycle: 3600 } } as any, component)
+
+  assert.deepStrictEqual(declaration, { sweep: { cycle: 3600, intervals: 1 } })
+})
+
+it('should expand the shorthand', () => {
+  const declaration = manifest({ sweep: 3600 } as any, component)
+
+  assert.deepStrictEqual(declaration, { sweep: { cycle: 3600, intervals: 1 } })
+})
+
+it('should answer a component that only delays calls', () => {
+  assert.deepStrictEqual(manifest(null, component), {})
+})
+
+it('should refuse an undefined operation', () => {
+  assert.throws(() => manifest({ nothing: 3600 } as any, component),
+    /refers to undefined operation 'nothing'/)
+})
+
+it('should refuse an operation that produces no side effects', () => {
+  assert.throws(() => manifest({ peek: 3600 } as any, component),
+    /of the allowed types/)
+})
+
+it('should refuse an interval shorter than a second', () => {
+  assert.throws(() => manifest({ sweep: { cycle: 60, intervals: 61 } }, component),
+    /less than a second/)
+})
+
+it('should refuse a cycle of no time at all', () => {
+  assert.throws(() => manifest({ sweep: { cycle: 0, intervals: 1 } }, component))
+})
+
+it('should refuse what the declaration does not describe', () => {
+  assert.throws(() => manifest({ sweep: { cycle: 60, every: 3 } } as any, component))
+})

package/source/manifest.ts

@@ -0,0 +1,51 @@
+import * as schemas from './schemas.js'
+import type { Declaration } from './types.js'
+import type { Manifest } from '@toa.io/norm'
+
+/**
+ * The `cadence:` block of a component manifest: the operations called on a cadence, by the
+ * operation each one calls. Norm hands over the whole manifest, so what the declaration refers
+ * to is checked here rather than left to fail at boot.
+ *
+ * A component that declares nothing still has a declaration. `cadence: ~` is how one that only
+ * delays calls says so, and it has to produce a value or norm rejects the extension.
+ */
+export function manifest (declaration: Declaration | null | undefined,
+  component: Manifest): Declaration {
+  const normalized: Record<string, unknown> = expand(declaration)
+
+  // `intervals` is defaulted by the schema, so the declaration is only whole after this
+  schemas.declaration.validate<Declaration>(normalized, 'Invalid cadence declaration')
+
+  for (const [endpoint, pulse] of Object.entries(normalized)) {
+    const operation = component.operations?.[endpoint]
+
+    if (operation === undefined)
+      throw new Error(`Pulse refers to undefined operation '${endpoint}'`)
+
+    if (!TYPES.has(operation.type))
+      throw new Error(`Pulse '${endpoint}' must refer to an operation of the allowed types: ` +
+        [...TYPES].join(', '))
+
+    if (pulse.intervals > pulse.cycle)
+      throw new Error(`Pulse '${endpoint}' splits a cycle of ${pulse.cycle} seconds into ` +
+        `${pulse.intervals} intervals, which is less than a second each`)
+  }
+
+  return normalized
+}
+
+/** A pulse whose cycle is not split has nothing to state but the cycle. */
+function expand (declaration: Declaration | null | undefined): Record<string, unknown> {
+  if (declaration === null || declaration === undefined) return {}
+
+  return Object.fromEntries(Object.entries(declaration)
+    .map(([endpoint, pulse]) =>
+      [endpoint, typeof pulse === 'number' ? { cycle: pulse } : pulse]))
+}
+
+/**
+ * The types a receiver may refer to. An operation that produces no side effects has nothing to
+ * be called periodically for.
+ */
+const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged'])

package/source/schemas.ts

@@ -0,0 +1,10 @@
+import { resolve } from 'node:path'
+import * as schemas from '@toa.io/schemas'
+import type { Schema } from '@toa.io/schemas'
+import type { Annotation, Declaration } from './types.js'
+
+const path = resolve(import.meta.dirname, '../schemas')
+const namespace = schemas.namespace(path)
+
+export const declaration: Schema<Declaration> = namespace.schema('declaration')
+export const annotation: Schema<Annotation> = namespace.schema('annotation')