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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +3 -3
  2. package/LICENSE +22 -0
  3. package/components/cadence.metronome/manifest.toa.yaml +22 -28
  4. package/components/cadence.metronome/migrations/0001-system-properties.yaml +14 -0
  5. package/components/cadence.metronome/migrations/0002-indexes.yaml +5 -0
  6. package/components/cadence.metronome/migrations/0003-pending-index.yaml +16 -0
  7. package/components/cadence.metronome/migrations/0004-retention.yaml +15 -0
  8. package/components/cadence.metronome/operations/delay.js +1 -1
  9. package/components/cadence.metronome/operations/settle.js +8 -4
  10. package/components/cadence.metronome/types/toa.d.ts +5 -5
  11. package/package.json +6 -5
  12. package/readme.md +35 -21
  13. package/schemas/declaration.cos.yaml +0 -1
  14. package/source/Aspect.ts +19 -10
  15. package/source/Composition.ts +4 -4
  16. package/source/Dispatcher.test.ts +240 -32
  17. package/source/Dispatcher.ts +145 -32
  18. package/source/Factory.ts +13 -10
  19. package/source/Local.ts +5 -4
  20. package/source/Pulse.test.ts +48 -19
  21. package/source/Pulse.ts +30 -21
  22. package/source/const.ts +7 -1
  23. package/source/context.ts +2 -2
  24. package/source/deployment.ts +10 -5
  25. package/source/manifest.test.ts +9 -6
  26. package/source/manifest.ts +24 -11
  27. package/transpiled/Aspect.d.ts +0 -1
  28. package/transpiled/Aspect.js +11 -5
  29. package/transpiled/Aspect.js.map +1 -1
  30. package/transpiled/Composition.js.map +1 -1
  31. package/transpiled/Dispatcher.d.ts +22 -4
  32. package/transpiled/Dispatcher.js +111 -18
  33. package/transpiled/Dispatcher.js.map +1 -1
  34. package/transpiled/Factory.d.ts +1 -1
  35. package/transpiled/Factory.js.map +1 -1
  36. package/transpiled/Local.d.ts +2 -1
  37. package/transpiled/Local.js.map +1 -1
  38. package/transpiled/Pulse.d.ts +2 -1
  39. package/transpiled/Pulse.js +14 -5
  40. package/transpiled/Pulse.js.map +1 -1
  41. package/transpiled/const.d.ts +6 -0
  42. package/transpiled/const.js +6 -0
  43. package/transpiled/const.js.map +1 -1
  44. package/transpiled/context.d.ts +1 -1
  45. package/transpiled/deployment.js +5 -2
  46. package/transpiled/deployment.js.map +1 -1
  47. package/transpiled/manifest.js +6 -3
  48. package/transpiled/manifest.js.map +1 -1
  49. package/tsconfig.tsbuildinfo +1 -0
package/source/Factory.ts CHANGED
@@ -6,7 +6,7 @@ import { Dispatcher } from './Dispatcher.js'
6
6
  import { Local } from './Local.js'
7
7
  import { Pulse } from './Pulse.js'
8
8
  import type { Declaration } from './types.js'
9
- import type { extensions } from '@toa.io/core'
9
+ import type { extensions } from '@toa.io/core/types'
10
10
 
11
11
  export class Factory implements extensions.Factory {
12
12
  private readonly host: Host
@@ -14,7 +14,7 @@ export class Factory implements extensions.Factory {
14
14
  /** one per component, however much of this extension calls through it */
15
15
  private readonly locals: Record<string, Local> = {}
16
16
 
17
- public constructor (host: Host) {
17
+ public constructor(host: Host) {
18
18
  this.host = host
19
19
  }
20
20
 
@@ -25,10 +25,13 @@ export class Factory implements extensions.Factory {
25
25
  * A tenant is created before the components of its composition are, which is why nothing here
26
26
  * reaches for one.
27
27
  */
28
- public tenant (locator: Locator, declaration: object): Connector {
28
+ public tenant(locator: Locator, declaration: object): Connector {
29
29
  if (mine(locator))
30
- return new Dispatcher(this.metronome(), (target) => this.local(target),
31
- this.host.atom(locator.id))
30
+ return new Dispatcher(
31
+ this.metronome(),
32
+ (target) => this.local(target),
33
+ this.host.atom(locator.id)
34
+ )
32
35
 
33
36
  const tenant = new Connector()
34
37
  const pulses = declaration as Declaration | null
@@ -46,27 +49,27 @@ export class Factory implements extensions.Factory {
46
49
  }
47
50
 
48
51
  /** `context.delay` — for every component but the one that keeps the calls. */
49
- public aspect (locator: Locator): extensions.Aspect | extensions.Aspect[] {
52
+ public aspect(locator: Locator): extensions.Aspect | extensions.Aspect[] {
50
53
  if (mine(locator)) return []
51
54
 
52
55
  return new Aspect(this.metronome())
53
56
  }
54
57
 
55
- public service (): Connector {
58
+ public service(): Connector {
56
59
  return new Composition(this.host)
57
60
  }
58
61
 
59
- private metronome (): Local {
62
+ private metronome(): Local {
60
63
  return this.local(new Locator(COMPONENT, NAMESPACE))
61
64
  }
62
65
 
63
- private local (locator: Locator): Local {
66
+ private local(locator: Locator): Local {
64
67
  return (this.locals[locator.id] ??= new Local(this.host, locator))
65
68
  }
66
69
  }
67
70
 
68
71
  /** Whether this is a component the extension ships rather than one of the application's. */
69
- function mine (locator: Locator): boolean {
72
+ function mine(locator: Locator): boolean {
70
73
  return locator.namespace === NAMESPACE
71
74
  }
72
75
 
package/source/Local.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { Connector } from '@toa.io/core'
2
2
  import type { Host } from './Factory.js'
3
- import type { Locator, Remote, Reply, Request } from '@toa.io/core'
3
+ import type { Locator, Remote } from '@toa.io/core'
4
+ import type { Reply, Request } from '@toa.io/core/types'
4
5
 
5
6
  /**
6
7
  * The component a tenant belongs to, as something to call.
@@ -14,20 +15,20 @@ export class Local extends Connector {
14
15
  private readonly locator: Locator
15
16
  private remote?: Promise<Remote>
16
17
 
17
- public constructor (host: Host, locator: Locator) {
18
+ public constructor(host: Host, locator: Locator) {
18
19
  super()
19
20
 
20
21
  this.host = host
21
22
  this.locator = locator
22
23
  }
23
24
 
24
- public async invoke (endpoint: string, request: Request): Promise<Reply> {
25
+ public async invoke(endpoint: string, request: Request): Promise<Reply> {
25
26
  this.remote ??= this.locate()
26
27
 
27
28
  return await (await this.remote).invoke(endpoint, request)
28
29
  }
29
30
 
30
- private async locate (): Promise<Remote> {
31
+ private async locate(): Promise<Remote> {
31
32
  const remote = await this.host.remote(this.locator)
32
33
 
33
34
  this.depends(remote)
@@ -3,7 +3,8 @@ import assert from 'node:assert/strict'
3
3
 
4
4
  import { Pulse } from './Pulse.js'
5
5
  import type { Local } from './Local.js'
6
- import type { Locator, Request, atomicity } from '@toa.io/core'
6
+ import type { Locator } from '@toa.io/core'
7
+ import type { Request, atomicity } from '@toa.io/core/types'
7
8
 
8
9
  type Invoke = (endpoint: string, request: Request) => Promise<unknown>
9
10
  type Slots = (total: number) => number[] | null
@@ -17,11 +18,16 @@ const DAY = 24 * HOUR
17
18
 
18
19
  const locator = { id: 'tea.pots' } as Locator
19
20
 
20
- const range = (total: number): number[] => Array.from({ length: total }, (_, index) => index)
21
+ const range = (total: number): number[] =>
22
+ Array.from({ length: total }, (_, index) => index)
21
23
 
22
24
  /** what a Pulse reaches for, with a lifecycle it can connect through */
23
- const connector = (properties: object): any =>
24
- ({ ...properties, link: mock.fn(), connect: async () => {}, disconnect: async () => {} })
25
+ const connector = (properties: object): any => ({
26
+ ...properties,
27
+ link: mock.fn(),
28
+ connect: async () => {},
29
+ disconnect: async () => {}
30
+ })
25
31
 
26
32
  const create = (cycle: number, intervals: number): Pulse =>
27
33
  new Pulse({ locator, endpoint: 'sweep', cycle, intervals }, local, atom)
@@ -37,7 +43,6 @@ const advance = async (ms: number): Promise<void> => {
37
43
  const intervals = (): number[] =>
38
44
  local.invoke.mock.calls.map((call) => (call.arguments[1].input as { i: number }).i)
39
45
 
40
-
41
46
  beforeEach(() => {
42
47
  mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 0 })
43
48
 
@@ -72,7 +77,10 @@ it('should give every interval of a cycle that does not divide evenly', () => {
72
77
  now = pulse.boundary(now)
73
78
  }
74
79
 
75
- assert.deepStrictEqual([...seen].sort((a, b) => a - b), [0, 1, 2, 3, 4, 5, 6])
80
+ assert.deepStrictEqual(
81
+ [...seen].sort((a, b) => a - b),
82
+ [0, 1, 2, 3, 4, 5, 6]
83
+ )
76
84
  assert.strictEqual(now, DAY * SECOND, 'seven boundaries land exactly on the next cycle')
77
85
  })
78
86
 
@@ -130,8 +138,10 @@ it('should call once per interval, and every interval of a cycle', async () => {
130
138
 
131
139
  for (let hour = 0; hour < 24; hour++) await advance(HOUR * SECOND)
132
140
 
133
- assert.deepStrictEqual(intervals(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
134
- 17, 18, 19, 20, 21, 22, 23, 0])
141
+ assert.deepStrictEqual(
142
+ intervals(),
143
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 0]
144
+ )
135
145
  })
136
146
 
137
147
  it('should keep calling a cycle it is not splitting', async () => {
@@ -167,13 +177,17 @@ it('should not call an interval it acquired after the boundary', async () => {
167
177
 
168
178
  await advance(30 * 60 * SECOND) // and half an hour later it is
169
179
 
170
- assert.strictEqual(local.invoke.mock.callCount(), 0,
171
- 'the replica that held it at the boundary is the only one that could have called')
180
+ assert.strictEqual(
181
+ local.invoke.mock.callCount(),
182
+ 0,
183
+ 'the replica that held it at the boundary is the only one that could have called'
184
+ )
172
185
  })
173
186
 
174
187
  it('should not call an interval another replica owns', async () => {
175
188
  atom.slots.mock.mockImplementation((total) =>
176
- range(total).filter((slot) => slot % 2 === 0))
189
+ range(total).filter((slot) => slot % 2 === 0)
190
+ )
177
191
 
178
192
  const pulse = create(DAY, 24)
179
193
 
@@ -190,8 +204,12 @@ it('should not call an interval another replica owns', async () => {
190
204
  it('should not start a call while the one before has not returned', async () => {
191
205
  let release: () => void = () => {}
192
206
 
193
- local.invoke.mock.mockImplementation(async () =>
194
- await new Promise<void>((resolve) => { release = resolve }))
207
+ local.invoke.mock.mockImplementation(
208
+ async () =>
209
+ await new Promise<void>((resolve) => {
210
+ release = resolve
211
+ })
212
+ )
195
213
 
196
214
  const pulse = create(DAY, 24)
197
215
 
@@ -211,7 +229,9 @@ it('should not start a call while the one before has not returned', async () =>
211
229
  })
212
230
 
213
231
  it('should keep its cadence when a call raises', async () => {
214
- local.invoke.mock.mockImplementationOnce(async () => { throw new Error('nope') })
232
+ local.invoke.mock.mockImplementationOnce(async () => {
233
+ throw new Error('nope')
234
+ })
215
235
 
216
236
  const pulse = create(DAY, 24)
217
237
 
@@ -220,8 +240,11 @@ it('should keep its cadence when a call raises', async () => {
220
240
  await advance(HOUR * SECOND)
221
241
  await advance(HOUR * SECOND)
222
242
 
223
- assert.strictEqual(local.invoke.mock.callCount(), 2,
224
- 'the interval that raised is skipped, and the next one is called')
243
+ assert.strictEqual(
244
+ local.invoke.mock.callCount(),
245
+ 2,
246
+ 'the interval that raised is skipped, and the next one is called'
247
+ )
225
248
  })
226
249
 
227
250
  it('should wait out a cycle longer than one timer in instalments', async () => {
@@ -243,15 +266,21 @@ it('should wait for a call in flight before closing', async () => {
243
266
  let release: () => void = () => {}
244
267
  let closed = false
245
268
 
246
- local.invoke.mock.mockImplementation(async () =>
247
- await new Promise<void>((resolve) => { release = resolve }))
269
+ local.invoke.mock.mockImplementation(
270
+ async () =>
271
+ await new Promise<void>((resolve) => {
272
+ release = resolve
273
+ })
274
+ )
248
275
 
249
276
  const pulse = create(DAY, 24)
250
277
 
251
278
  await pulse.connect()
252
279
  await advance(HOUR * SECOND)
253
280
 
254
- const closing = pulse.disconnect().then(() => { closed = true })
281
+ const closing = pulse.disconnect().then(() => {
282
+ closed = true
283
+ })
255
284
 
256
285
  await advance(0)
257
286
  assert.strictEqual(closed, false, 'the call is still running')
package/source/Pulse.ts CHANGED
@@ -2,7 +2,8 @@ import { console } from 'openspan'
2
2
  import { Connector } from '@toa.io/core'
3
3
  import type { Local } from './Local.js'
4
4
  import type { SpanOptions } from 'openspan'
5
- import type { Locator, atomicity } from '@toa.io/core'
5
+ import type { Locator } from '@toa.io/core'
6
+ import type { atomicity } from '@toa.io/core/types'
6
7
 
7
8
  /**
8
9
  * A recurring call to an operation of its own component, on the cadence its manifest states.
@@ -43,7 +44,7 @@ export class Pulse extends Connector {
43
44
 
44
45
  private closing = false
45
46
 
46
- public constructor (definition: Definition, local: Local, atom: atomicity.Atom) {
47
+ public constructor(definition: Definition, local: Local, atom: atomicity.Atom) {
47
48
  super()
48
49
 
49
50
  const { locator, endpoint, cycle, intervals } = definition
@@ -75,17 +76,17 @@ export class Pulse extends Connector {
75
76
  * as large as the cycle has seconds, so their product leaves the range a double is exact in
76
77
  * for a long cycle cut finely. It is evaluated once per interval, where this costs nothing.
77
78
  */
78
- public ordinal (now: number): number {
79
- return Number(BigInt(now) * BigInt(this.n) / BigInt(this.cycle))
79
+ public ordinal(now: number): number {
80
+ return Number((BigInt(now) * BigInt(this.n)) / BigInt(this.cycle))
80
81
  }
81
82
 
82
83
  /** Which of the cycle's intervals `now` falls in. */
83
- public index (now: number): number {
84
+ public index(now: number): number {
84
85
  return this.ordinal(now) % this.n
85
86
  }
86
87
 
87
88
  /** When the interval `now` falls in gives way to the next one. */
88
- public boundary (now: number): number {
89
+ public boundary(now: number): number {
89
90
  const cycle = BigInt(this.cycle)
90
91
  const n = BigInt(this.n)
91
92
  const next = BigInt(this.ordinal(now) + 1)
@@ -94,7 +95,7 @@ export class Pulse extends Connector {
94
95
  return Number((next * cycle + n - 1n) / n)
95
96
  }
96
97
 
97
- protected override async open (): Promise<void> {
98
+ protected override async open(): Promise<void> {
98
99
  // whatever interval it is now, this replica was not there when it began, so it is not
99
100
  // this one's to call — the first call is at the next boundary
100
101
  this.fired = this.ordinal(Date.now())
@@ -102,7 +103,7 @@ export class Pulse extends Connector {
102
103
  this.arm()
103
104
  }
104
105
 
105
- protected override async close (): Promise<void> {
106
+ protected override async close(): Promise<void> {
106
107
  this.closing = true
107
108
 
108
109
  clearTimeout(this.timer)
@@ -110,11 +111,10 @@ export class Pulse extends Connector {
110
111
  // a call still running holds the remote it was made through, which is torn down after
111
112
  // this returns. Bounded, because an operation that never returns would outlive any
112
113
  // grace period and the interval is over either way
113
- if (this.firing !== undefined)
114
- await Promise.race([this.firing, delay(DRAIN)])
114
+ if (this.firing !== undefined) await Promise.race([this.firing, delay(DRAIN)])
115
115
  }
116
116
 
117
- private arm (): void {
117
+ private arm(): void {
118
118
  const now = Date.now()
119
119
 
120
120
  // a delay past this fires at once rather than late, so a long cycle is waited out in
@@ -125,7 +125,7 @@ export class Pulse extends Connector {
125
125
  this.timer.unref()
126
126
  }
127
127
 
128
- private tick (): void {
128
+ private tick(): void {
129
129
  if (this.closing) return
130
130
 
131
131
  const ordinal = this.ordinal(Date.now())
@@ -145,10 +145,12 @@ export class Pulse extends Connector {
145
145
  * Nothing queues here. A call still running when the next boundary arrives means the work
146
146
  * does not fit the gap, and starting a second one would only make that worse.
147
147
  */
148
- private async fire (i: number): Promise<void> {
148
+ private async fire(i: number): Promise<void> {
149
149
  if (this.firing !== undefined) {
150
- console.warn('Pulse skipped: the previous call has not returned',
151
- { pulse: this.label, interval: i })
150
+ console.warn('Pulse skipped: the previous call has not returned', {
151
+ pulse: this.label,
152
+ interval: i
153
+ })
152
154
 
153
155
  return
154
156
  }
@@ -156,8 +158,10 @@ export class Pulse extends Connector {
156
158
  const owned = this.atom.slots(this.n)
157
159
 
158
160
  if (owned === null) {
159
- console.warn('Pulse skipped: this replica owns nothing',
160
- { pulse: this.label, interval: i })
161
+ console.warn('Pulse skipped: this replica owns nothing', {
162
+ pulse: this.label,
163
+ interval: i
164
+ })
161
165
 
162
166
  return
163
167
  }
@@ -171,12 +175,17 @@ export class Pulse extends Connector {
171
175
  * only wanted an operation called every hour. So the interval is skipped: it is reported,
172
176
  * and the next one is called as though it had not happened.
173
177
  */
174
- const firing = console.span(this.options,
175
- async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } }))
178
+ const firing = console
179
+ .span(
180
+ this.options,
181
+ async () => await this.local.invoke(this.endpoint, { input: { n: this.n, i } })
182
+ )
176
183
  .catch((error: unknown) => {
177
184
  console.error('Pulse failed', { pulse: this.label, interval: i, error })
178
185
  })
179
- .finally(() => { this.firing = undefined })
186
+ .finally(() => {
187
+ this.firing = undefined
188
+ })
180
189
 
181
190
  this.firing = firing
182
191
 
@@ -191,7 +200,7 @@ export interface Definition {
191
200
  intervals: number
192
201
  }
193
202
 
194
- async function delay (ms: number): Promise<void> {
203
+ async function delay(ms: number): Promise<void> {
195
204
  await new Promise((resolve) => setTimeout(resolve, ms).unref())
196
205
  }
197
206
 
package/source/const.ts CHANGED
@@ -6,6 +6,12 @@ export const COMPONENT = 'metronome'
6
6
  * Constant, never configuration: a row carries its lane, so lowering this would leave rows in
7
7
  * lanes nobody reads any more. It is also the ceiling on replicas dispatching, and a power of
8
8
  * two so that the common replica counts divide evenly. The outbox says the same of its own.
9
+ *
10
+ * A scan asks for its lanes as a set and sorts on `due`, which is the index's second key, so
11
+ * the plan that serves it explodes the set into one scan per lane and merges them in order.
12
+ * MongoDB stops exploding past `internalQueryMaxScansToExplode`, 200 by default, and falls
13
+ * back to sorting the whole result in memory — so this staying well under that is not
14
+ * incidental.
9
15
  */
10
16
  export const LANES = 128
11
17
 
@@ -16,7 +22,7 @@ export const DISCRETENESS = 60
16
22
  export const BATCH = 200
17
23
 
18
24
  /** A number from the environment, where a deployment or a test suite states one. */
19
- export function number (variable: string, fallback: number): number {
25
+ export function number(variable: string, fallback: number): number {
20
26
  const value = Number(process.env[variable])
21
27
 
22
28
  return Number.isNaN(value) || value <= 0 ? fallback : value
package/source/context.ts CHANGED
@@ -1,7 +1,7 @@
1
- import type { Contribution } from '@toa.io/core'
1
+ import type { Contribution } from '@toa.io/core/types'
2
2
 
3
3
  /** What this extension puts on the context of a component that declares it. */
4
- export function context (): Contribution {
4
+ export function context(): Contribution {
5
5
  return {
6
6
  name: 'delay',
7
7
  type: 'Delay',
@@ -9,19 +9,24 @@ import type { Dependency, Service, Variable } from '@toa.io/operations'
9
9
  * The component that keeps delayed calls runs in a service of its own, the way the identity
10
10
  * components run in the gateway. A composition may claim it and run it in its own pods instead.
11
11
  */
12
- export function deployment (_: unknown, annotation?: Annotation | null): Dependency {
13
- schemas.annotation.validate<Annotation | null>(annotation ?? null, 'Invalid cadence annotation')
12
+ export function deployment(_: unknown, annotation?: Annotation | null): Dependency {
13
+ schemas.annotation.validate<Annotation | null>(
14
+ annotation ?? null,
15
+ 'Invalid cadence annotation'
16
+ )
14
17
 
15
18
  // stated in seconds and carried in milliseconds, so that what an application writes is what
16
19
  // the rest of a manifest is written in
17
20
  const discreteness = (annotation?.discreteness ?? DISCRETENESS) * 1000
18
- const variables: Variable[] =
19
- [{ name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }]
21
+ const variables: Variable[] = [
22
+ { name: 'TOA_CADENCE_DISCRETENESS', value: String(discreteness) }
23
+ ]
20
24
 
21
25
  const service: Service = {
22
26
  group: NAMESPACE,
23
27
  name: 'metronome',
24
- version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
28
+ version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
29
+ .version,
25
30
  components: components().labels,
26
31
  variables
27
32
  }
@@ -35,18 +35,21 @@ it('should answer a component that only delays calls', () => {
35
35
  })
36
36
 
37
37
  it('should refuse an undefined operation', () => {
38
- assert.throws(() => manifest({ nothing: 3600 } as any, component),
39
- /refers to undefined operation 'nothing'/)
38
+ assert.throws(
39
+ () => manifest({ nothing: 3600 } as any, component),
40
+ /refers to undefined operation 'nothing'/
41
+ )
40
42
  })
41
43
 
42
44
  it('should refuse an operation that produces no side effects', () => {
43
- assert.throws(() => manifest({ peek: 3600 } as any, component),
44
- /of the allowed types/)
45
+ assert.throws(() => manifest({ peek: 3600 } as any, component), /of the allowed types/)
45
46
  })
46
47
 
47
48
  it('should refuse an interval shorter than a second', () => {
48
- assert.throws(() => manifest({ sweep: { cycle: 60, intervals: 61 } }, component),
49
- /less than a second/)
49
+ assert.throws(
50
+ () => manifest({ sweep: { cycle: 60, intervals: 61 } }, component),
51
+ /less than a second/
52
+ )
50
53
  })
51
54
 
52
55
  it('should refuse a cycle of no time at all', () => {
@@ -10,11 +10,12 @@ import type { Manifest } from '@toa.io/norm'
10
10
  * A component that declares nothing still has a declaration. `cadence: ~` is how one that only
11
11
  * delays calls says so, and it has to produce a value or norm rejects the extension.
12
12
  */
13
- export function manifest (declaration: Declaration | null | undefined,
14
- component: Manifest): Declaration {
13
+ export function manifest(
14
+ declaration: Declaration | null | undefined,
15
+ component: Manifest
16
+ ): Declaration {
15
17
  const normalized: Record<string, unknown> = expand(declaration)
16
18
 
17
- // `intervals` is defaulted by the schema, so the declaration is only whole after this
18
19
  schemas.declaration.validate<Declaration>(normalized, 'Invalid cadence declaration')
19
20
 
20
21
  for (const [endpoint, pulse] of Object.entries(normalized)) {
@@ -24,24 +25,36 @@ export function manifest (declaration: Declaration | null | undefined,
24
25
  throw new Error(`Pulse refers to undefined operation '${endpoint}'`)
25
26
 
26
27
  if (!TYPES.has(operation.type))
27
- throw new Error(`Pulse '${endpoint}' must refer to an operation of the allowed types: ` +
28
- [...TYPES].join(', '))
28
+ throw new Error(
29
+ `Pulse '${endpoint}' must refer to an operation of the allowed types: ` +
30
+ [...TYPES].join(', ')
31
+ )
29
32
 
30
33
  if (pulse.intervals > pulse.cycle)
31
- throw new Error(`Pulse '${endpoint}' splits a cycle of ${pulse.cycle} seconds into ` +
32
- `${pulse.intervals} intervals, which is less than a second each`)
34
+ throw new Error(
35
+ `Pulse '${endpoint}' splits a cycle of ${pulse.cycle} seconds into ` +
36
+ `${pulse.intervals} intervals, which is less than a second each`
37
+ )
33
38
  }
34
39
 
35
40
  return normalized
36
41
  }
37
42
 
38
43
  /** A pulse whose cycle is not split has nothing to state but the cycle. */
39
- function expand (declaration: Declaration | null | undefined): Record<string, unknown> {
44
+ function expand(declaration: Declaration | null | undefined): Record<string, unknown> {
40
45
  if (declaration === null || declaration === undefined) return {}
41
46
 
42
- return Object.fromEntries(Object.entries(declaration)
43
- .map(([endpoint, pulse]) =>
44
- [endpoint, typeof pulse === 'number' ? { cycle: pulse } : pulse]))
47
+ // a cycle nothing splits is one interval, which is what the shorthand declares
48
+ return Object.fromEntries(
49
+ Object.entries(declaration).map(([endpoint, pulse]) => {
50
+ const declared: Record<string, unknown> =
51
+ typeof pulse === 'number' ? { cycle: pulse } : { ...pulse }
52
+
53
+ declared.intervals ??= 1
54
+
55
+ return [endpoint, declared]
56
+ })
57
+ )
45
58
  }
46
59
 
47
60
  /**
@@ -8,7 +8,6 @@ import type { Local } from './Local.js';
8
8
  * handing over the call it should have scheduled loses the call, and there is no way for this
9
9
  * to know. Where the semantics allow it, hand the call over first.
10
10
  *
11
- * @implements {toa.core.extensions.Aspect}
12
11
  */
13
12
  export declare class Aspect extends Connector {
14
13
  readonly name = "delay";
@@ -7,7 +7,6 @@ import { Connector } from '@toa.io/core';
7
7
  * handing over the call it should have scheduled loses the call, and there is no way for this
8
8
  * to know. Where the semantics allow it, hand the call over first.
9
9
  *
10
- * @implements {toa.core.extensions.Aspect}
11
10
  */
12
11
  export class Aspect extends Connector {
13
12
  name = 'delay';
@@ -21,14 +20,21 @@ export class Aspect extends Connector {
21
20
  // algorithm — the same reason the atom aspect names its own
22
21
  async invoke(method, ...args) {
23
22
  switch (method) {
24
- case 'delay': return await this.delay(args[0], args[1], args[2]);
25
- case 'cancel': return await this.cancel(args[0]);
26
- default: throw new Error(`Delay aspect has no '${method}' method`);
23
+ case 'delay':
24
+ return await this.delay(args[0], args[1], args[2]);
25
+ case 'cancel':
26
+ return await this.cancel(args[0]);
27
+ default:
28
+ throw new Error(`Delay aspect has no '${method}' method`);
27
29
  }
28
30
  }
29
31
  /** Answers the id the call was given, which is what cancels it. */
30
32
  async delay(endpoint, request, options) {
31
- const input = { endpoint, interval: options.interval, overdue: options.overdue };
33
+ const input = {
34
+ endpoint,
35
+ interval: options.interval,
36
+ overdue: options.overdue
37
+ };
32
38
  // a call that takes no request carries none, rather than a null one
33
39
  if (request !== null && request !== undefined)
34
40
  input.request = request;
@@ -1 +1 @@
1
- {"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAWxC;;;;;;;;;GASG;AACH,MAAM,OAAO,MAAO,SAAQ,SAAS;IACnB,IAAI,GAAG,OAAO,CAAA;IAEb,SAAS,CAAO;IAEjC,YAAoB,SAAgB;QAClC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAE1B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACzB,CAAC;IAED,0FAA0F;IAC1F,4DAA4D;IACrD,KAAK,CAAC,MAAM,CAAE,MAAc,EAAE,GAAG,IAAW;QACjD,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,OAAO,EAAE,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YAChE,KAAK,QAAQ,EAAE,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YAChD,SAAS,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAA;QACpE,CAAC;IACH,CAAC;IAED,mEAAmE;IAC3D,KAAK,CAAC,KAAK,CAAE,QAAgB,EAAE,OAAsB,EAC3D,OAAgB;QAChB,MAAM,KAAK,GAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAA;QAEvF,oEAAoE;QACpE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtE,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACxD,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM,CAAE,EAAU;QAC9B,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACjF,CAAC;CACF"}
1
+ {"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAWxC;;;;;;;;GAQG;AACH,MAAM,OAAO,MAAO,SAAQ,SAAS;IACnB,IAAI,GAAG,OAAO,CAAA;IAEb,SAAS,CAAO;IAEjC,YAAmB,SAAgB;QACjC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAE1B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACzB,CAAC;IAED,0FAA0F;IAC1F,4DAA4D;IACrD,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,GAAG,IAAW;QAChD,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,OAAO;gBACV,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YACpD,KAAK,QAAQ;gBACX,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YACnC;gBACE,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAA;QAC7D,CAAC;IACH,CAAC;IAED,mEAAmE;IAC3D,KAAK,CAAC,KAAK,CACjB,QAAgB,EAChB,OAAsB,EACtB,OAAgB;QAEhB,MAAM,KAAK,GAAU;YACnB,QAAQ;YACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAA;QAED,oEAAoE;QACpE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtE,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACxD,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM,CAAC,EAAU;QAC7B,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACjF,CAAC;CACF"}
@@ -1 +1 @@
1
- {"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,6EAA6E;AAC7E,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,SAAS;IACvB,IAAI,CAAM;IAE3B,YAAoB,IAAU;QAC5B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;QAEnE,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,SAAS,OAAO;IACd,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AAC1F,CAAC;AAOD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA"}
1
+ {"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,6EAA6E;AAC7E,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,SAAS;IACvB,IAAI,CAAM;IAE3B,YAAmB,IAAU;QAC3B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;QAEnE,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,SAAS,OAAO;IACd,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AAC1F,CAAC;AAOD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA"}
@@ -1,13 +1,14 @@
1
1
  import { Connector, Locator } from '@toa.io/core';
2
2
  import type { Local } from './Local.js';
3
- import type { atomicity } from '@toa.io/core';
3
+ import type { atomicity } from '@toa.io/core/types';
4
4
  /**
5
5
  * Makes the calls that were put off.
6
6
  *
7
7
  * Two tiers, which is what a store polled rarely and a call due to the second need between
8
- * them: the rows are the record, and one scan primes the next interval of them into timers.
9
- * A crash loses the timers and nothing else — the next scan reads what is overdue along with
10
- * what is upcoming, so a dispatcher that died mid-interval costs a delay and not a call.
8
+ * them: the rows are the record, and one scan primes the next two intervals of them into
9
+ * timers. A crash loses the timers and nothing else — the next scan reads what is overdue
10
+ * along with what is upcoming, so a dispatcher that died mid-interval costs a delay and not a
11
+ * call.
11
12
  *
12
13
  * Partitioned by lane exactly as the outbox is, so every replica scans and dispatches its own
13
14
  * share of every interval rather than taking turns at whole ones.
@@ -28,6 +29,8 @@ export declare class Dispatcher extends Connector {
28
29
  private off?;
29
30
  private scanning;
30
31
  private closing;
32
+ /** when the scan that is running started, so a tick that finds it can say how long */
33
+ private started;
31
34
  constructor(metronome: Local, resolve: (locator: Locator) => Local, atom: atomicity.Atom);
32
35
  protected open(): Promise<void>;
33
36
  protected close(): Promise<void>;
@@ -42,6 +45,21 @@ export declare class Dispatcher extends Connector {
42
45
  /** What is armed for a lane this replica no longer holds: whoever holds it now will arm it. */
43
46
  private disarm;
44
47
  private scan;
48
+ /**
49
+ * Gives up what the store no longer answers with. A scan reads everything still owed in the
50
+ * lanes this replica holds, so a row it armed before and does not read now is one nothing
51
+ * owes any more — cancelled, most of the time — and a timer left for it makes the call
52
+ * regardless.
53
+ *
54
+ * This is what lets a scan reach further ahead than the next one without a cancellation
55
+ * becoming any less reliable: a row is held only for as long as the store keeps saying it is
56
+ * owed, so what bounds cancelling is the period between passes and not how far one reaches.
57
+ *
58
+ * Two things are not evidence of a cancellation. A batch filled to its limit is a read that
59
+ * was cut short, and says nothing about what it did not reach. And a call already on its way
60
+ * is settled by its own path rather than by what a scan reads.
61
+ */
62
+ private forget;
45
63
  /**
46
64
  * A row already armed is left alone: a scan reads what it read before, because a row stays
47
65
  * until its call has been made.