@toa.io/extensions.cadence 1.0.0-alpha.291 → 1.0.0-alpha.293

package/source/Pulse.test.ts

@@ -1,303 +0,0 @@
-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 } from '@toa.io/core'
-import type { Request, atomicity } from '@toa.io/core/types'
-
-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

@@ -1,211 +0,0 @@
-import { console } from 'openspan'
-import { Connector } from '@toa.io/core'
-import type { Local } from './Local.js'
-import type { SpanOptions } from 'openspan'
-import type { Locator } from '@toa.io/core'
-import type { atomicity } from '@toa.io/core/types'
-
-/**
- * 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

@@ -1,31 +0,0 @@
-import { environment } from '@toa.io/generic'
-
-/** 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.
- *
- * A scan asks for its lanes as a set and sorts on `due`, which is the index's second key, so
- * the plan that serves it explodes the set into one scan per lane and merges them in order.
- * MongoDB stops exploding past `internalQueryMaxScansToExplode`, 200 by default, and falls
- * back to sorting the whole result in memory — so this staying well under that is not
- * incidental.
- */
-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(environment.get(variable))
-
-  return Number.isNaN(value) || value <= 0 ? fallback : value
-}

package/source/context.ts

@@ -1,10 +0,0 @@
-import type { Contribution } from '@toa.io/core/types'
-
-/** 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

@@ -1,38 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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))
-})