@toa.io/core 1.0.0-alpha.27 → 1.0.0-alpha.272

package/test/entities/entity.test.js

@@ -7,76 +7,86 @@ beforeEach(() => {
   jest.clearAllMocks()
 })
 
-describe('new', () => {
-  it('should throw on schema error', () => {
-    const entity = new Entity(fixtures.schema)
+describe('argument', () => {
+  it('should set state', () => {
+    const state = fixtures.state()
+    const entity = new Entity(fixtures.schema, state)
 
-    expect(() => entity.set(fixtures.failed())).toThrow()
+    expect(entity.get()).toEqual(state)
   })
 
-  it('should provide state', () => {
-    const entity = new Entity(fixtures.schema)
-    const state = fixtures.state()
-
-    entity.set(state)
+  it('should snapshot the record it may commit', () => {
+    const record = fixtures.state()
+    const entity = new Entity(fixtures.schema, record)
 
-    expect(entity.get()).toEqual(state)
+    expect(entity.get()).not.toBe(record)
+    expect(entity.event().origin).toBe(record)
   })
 })
 
-describe('argument', () => {
-  it('should provide initial state if no argument passed', () => {
-    const entity = new Entity(fixtures.schema)
-    const defaults = fixtures.schema.defaults.mock.results[0].value
-    const expected = {
-      ...defaults,
-      _version: 0
-    }
-
-    expect(entity.get()).toStrictEqual(expect.objectContaining(expected))
+describe('read-only', () => {
+  it('should take the record as it came', () => {
+    const record = fixtures.state()
+    const entity = new Entity(fixtures.schema, record, undefined, false)
+
+    // no pre-image to diff against, hence no copy of it
+    expect(entity.get()).toBe(record)
   })
 
-  it('should set state', () => {
-    const state = fixtures.state()
-    const entity = new Entity(fixtures.schema, state)
+  it('should still report a tombstone', () => {
+    const record = { ...fixtures.state(), _deleted: Date.now() }
+    const entity = new Entity(fixtures.schema, record, undefined, false)
 
-    expect(entity.get()).toEqual(state)
+    expect(entity.deleted).toBe(true)
+  })
+
+  it('should refuse to be modified', () => {
+    const entity = new Entity(fixtures.schema, fixtures.state(), undefined, false)
+
+    expect(() => entity.set(entity.get())).toThrow('read-only')
   })
 })
 
-it('should provide event', () => {
-  const origin = fixtures.state()
-  const entity = new Entity(fixtures.schema, origin)
-  const state = entity.get()
+describe('tombstone', () => {
+  it('should lift tombstone when transition leaves _deleted untouched', () => {
+    const origin = fixtures.state()
+    const entity = new Entity(fixtures.schema, origin)
+    const state = entity.get()
 
-  state.foo = 'new value'
-  entity.set(state)
+    state.foo = 'revived'
+    entity.set(state)
 
-  const event = entity.event()
+    expect(entity.get()._deleted).toBeNull()
+    expect(entity.deleted).toBe(false)
+    expect(entity.event().state._deleted).toBeNull()
+  })
 
-  expect(event).toEqual(expect.objectContaining({
-    state,
-    origin,
-    changeset: expect.objectContaining({
-      foo: 'new value',
-      _version: 1
-    })
-  }))
-})
+  it('should keep tombstone written by transition', () => {
+    const origin = { ...fixtures.state(), _deleted: null }
+    const entity = new Entity(fixtures.schema, origin)
+    const state = entity.get()
+    const timestamp = Date.now()
 
-it('should define `id` as readonly', async () => {
-  const origin = fixtures.state()
-  const entity = new Entity(fixtures.schema, origin)
-  const state = entity.get()
+    state._deleted = timestamp
+    entity.set(state)
 
-  expect(() => (state.id = 1)).toThrow('assign to read only property')
+    expect(entity.get()._deleted).toBe(timestamp)
+    expect(entity.deleted).toBe(true)
+  })
 })
 
-it('should seal id', async () => {
+it('should provide event', () => {
   const origin = fixtures.state()
   const entity = new Entity(fixtures.schema, origin)
   const state = entity.get()
-  const redefine = () => Object.defineProperty(state, 'id', { writable: true })
 
-  expect(redefine).toThrow('redefine property')
+  state.foo = 'new value'
+  entity.set(state)
+
+  const event = entity.event()
+
+  expect(event).toEqual(expect.objectContaining({ state, origin }))
+  expect(event.state.foo).toBe('new value')
+  expect(event.state._version).toBe(1)
+  expect(event.origin.foo).not.toBe('new value')
 })

package/test/entities/factory.test.js

@@ -23,14 +23,15 @@ it('should create initial', () => {
   const initial = factory.init(id)
 
   expect(initial).toBeInstanceOf(mock.Entity)
-  expect(initial.constructor).toHaveBeenCalledWith(fixtures.schema, id)
+  expect(initial.constructor).toHaveBeenCalledWith(fixtures.schema, id, expect.any(Function))
 })
 
 it('should create instance', () => {
   const object = factory.object(fixtures.entity)
 
   expect(object).toBeInstanceOf(mock.Entity)
-  expect(object.constructor).toHaveBeenCalledWith(fixtures.schema, fixtures.entity)
+  expect(object.constructor)
+    .toHaveBeenCalledWith(fixtures.schema, fixtures.entity, expect.any(Function), true)
 })
 
 it('should create set', () => {
@@ -39,7 +40,8 @@ it('should create set', () => {
   expect(objects).toBeInstanceOf(mock.EntitySet)
 
   const instances = fixtures.set.map((entity, index) => {
-    expect(mock.Entity).toHaveBeenNthCalledWith(index + 1, fixtures.schema, entity)
+    expect(mock.Entity)
+      .toHaveBeenNthCalledWith(index + 1, fixtures.schema, entity, expect.any(Function), true)
 
     return mock.Entity.mock.instances[index]
   })

package/test/event.test.js

@@ -41,7 +41,7 @@ describe('condition', () => {
       await emit()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
 
@@ -71,7 +71,7 @@ describe('condition', () => {
       expect(fixtures.bridge.condition).not.toHaveBeenCalledWith()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
@@ -84,7 +84,7 @@ describe('payload', () => {
       await emit()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
@@ -110,7 +110,7 @@ describe('payload', () => {
       await emit()
 
       const payload = fixtures.event.state
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })

package/test/outbox.test.js

@@ -0,0 +1,114 @@
+'use strict'
+
+const { Outbox } = require('../src/outbox')
+
+let emission, storage, atom, outbox
+
+const BATCH = 4
+
+/** rows as the storage hands them back, ids ascending like the uuid v7 they are */
+const page = (from, count) =>
+  Array.from({ length: count }, (_, i) => ({
+    id: String(from + i).padStart(4, '0'),
+    event: { state: {} }
+  }))
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  jest.useFakeTimers()
+
+  emission = { emit: jest.fn(async () => undefined), link: jest.fn() }
+
+  storage = {
+    link: jest.fn(),
+    outbox: {
+      pending: jest.fn(async () => []),
+      settle: jest.fn(async () => undefined)
+    }
+  }
+
+  atom = { slots: jest.fn(() => [0]), link: jest.fn() }
+  outbox = new Outbox(emission, storage, atom, { interval: 1000, batch: BATCH })
+})
+
+afterEach(() => {
+  jest.useRealTimers()
+})
+
+/** one cycle, and everything it awaited */
+const cycle = async () => {
+  jest.advanceTimersByTime(1000)
+
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
+it('should read nothing more when the first page is short', async () => {
+  storage.outbox.pending.mockResolvedValueOnce(page(0, 3))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).toHaveBeenCalledTimes(1)
+  expect(emission.emit).toHaveBeenCalledTimes(3)
+})
+
+it('should keep reading while a page comes back full', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, BATCH))
+    .mockResolvedValueOnce(page(2 * BATCH, 5))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).toHaveBeenCalledTimes(3)
+  expect(emission.emit).toHaveBeenCalledTimes(2 * BATCH + 5)
+})
+
+it('should continue each page from the id the one before ended on', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, 1))
+
+  await outbox.open()
+  await cycle()
+
+  const [, second] = storage.outbox.pending.mock.calls
+
+  expect(storage.outbox.pending.mock.calls[0][3]).toBeUndefined()
+  expect(second[3]).toStrictEqual(String(BATCH - 1).padStart(4, '0'))
+})
+
+it('should mark what it published, once, after the last page', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, 2))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.settle).toHaveBeenCalledTimes(1)
+  expect(storage.outbox.settle.mock.calls[0][0]).toHaveLength(BATCH + 2)
+})
+
+it('should not publish a row it has published and not yet marked', async () => {
+  storage.outbox.settle.mockRejectedValueOnce(new Error('mongo is out'))
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, 2))
+    .mockResolvedValueOnce(page(0, 2))
+
+  await outbox.open()
+  await cycle()
+  await cycle()
+
+  expect(emission.emit).toHaveBeenCalledTimes(2)
+})
+
+it('should read nothing while it owns no slots', async () => {
+  atom.slots.mockReturnValue(null)
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).not.toHaveBeenCalled()
+})

package/test/query.test.js

@@ -22,6 +22,23 @@ describe('criteria', () => {
     expect(query.criteria).toEqual(fixtures.samples.simple.parsed.criteria)
   })
 
+  it('should keep a parsed criteria', () => {
+    const instance = new Query(fixtures.samples.simple.properties)
+
+    const first = instance.parse(fixtures.samples.simple.query).criteria
+    const second = instance.parse(fixtures.samples.simple.query).criteria
+
+    expect(second).toBe(first)
+  })
+
+  it('should not keep an invalid criteria', () => {
+    const instance = new Query(fixtures.samples.simple.properties)
+    const query = { criteria: 'nonexistent==1' }
+
+    expect(() => instance.parse(query)).toThrow()
+    expect(() => instance.parse(query)).toThrow()
+  })
+
   it('should parse criteria with type coercion', () => {
     const instance = new Query(fixtures.samples.extended.properties)
     const query = instance.parse(fixtures.samples.extended.query)

package/test/receiver.fixtures.js

@@ -9,6 +9,7 @@ const definition = /** @type {toa.norm.component.Receiver} */ {
 }
 
 const local = /** @type {toa.core.Component} */ {
+  locator: { id: 'default.dummy' },
   invoke: jest.fn()
 }
 

package/test/state.fixtures.js

@@ -8,7 +8,10 @@ const storage = {
   find: jest.fn(() => ([{ id: generate() }])),
   add: jest.fn(() => true),
   set: jest.fn(() => true),
-  store: jest.fn(() => true)
+  store: jest.fn(() => true),
+  massStore: jest.fn(() => true),
+  upsert: jest.fn(() => ({ id: generate() })),
+  ensure: jest.fn((query, properties, state) => state)
 }
 
 const factory = {
@@ -20,9 +23,7 @@ const query = generate()
 
 const entity = {
   get: jest.fn(() => ({ [generate()]: generate() })),
-  event: jest.fn(() => ({
-    state: { [generate()]: generate() }, changeset: { [generate()]: generate() }
-  }))
+  event: jest.fn(() => ({ state: { [generate()]: generate() } }))
 }
 
 const initial = {
@@ -31,16 +32,18 @@ const initial = {
 
 const unchanged = {
   ...entity,
-  event: jest.fn(() => ({ state: { [generate()]: generate() }, changeset: {} }))
+  event: jest.fn(() => ({ state: { [generate()]: generate() } }))
 }
 
-const emitter = {
-  emit: jest.fn()
+// a legacy outbox: no storage capability, so `publish` emits inline
+const outbox = {
+  row: jest.fn((event) => ({ id: generate(), lane: 0, published: false, pending: 0, event })),
+  publish: jest.fn()
 }
 
 exports.storage = storage
 exports.factory = factory
-exports.emitter = emitter
+exports.outbox = outbox
 exports.query = query
 exports.entity = entity
 exports.initial = initial

package/test/state.test.js

@@ -8,7 +8,7 @@ let state
 beforeEach(() => {
   jest.clearAllMocks()
 
-  state = new State(fixtures.storage, fixtures.factory, fixtures.emitter)
+  state = new State(fixtures.storage, fixtures.factory, fixtures.outbox)
 })
 
 it('should provide object', async () => {
@@ -16,31 +16,79 @@ it('should provide object', async () => {
 
   expect(fixtures.storage.get).toHaveBeenCalledWith(fixtures.query)
   expect(entity).toStrictEqual(fixtures.factory.object.mock.results[0].value)
-  expect(fixtures.factory.object).toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value)
+  expect(fixtures.factory.object)
+    .toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value, true)
 })
 
-it('should provide objects', async () => {
-  const set = await state.objects(fixtures.query)
+it('should provide read-only object', async () => {
+  await state.object(fixtures.query, false)
 
-  expect(fixtures.storage.find).toHaveBeenCalledWith(fixtures.query)
-  expect(set).toStrictEqual(fixtures.factory.objects.mock.results[0].value)
-  expect(fixtures.factory.objects).toHaveBeenCalledWith(fixtures.storage.find.mock.results[0].value)
+  expect(fixtures.factory.object)
+    .toHaveBeenCalledWith(fixtures.storage.get.mock.results[0].value, false)
+})
+
+it('should provide read-only objects', async () => {
+  await state.objects(fixtures.query, false)
+
+  expect(fixtures.factory.objects)
+    .toHaveBeenCalledWith(fixtures.storage.find.mock.results[0].value, undefined, false)
 })
 
 it('should store entity', async () => {
   await state.commit(fixtures.initial)
 
-  expect(fixtures.storage.store).toHaveBeenCalledWith(fixtures.initial.get.mock.results[0].value)
+  expect(fixtures.storage.store).toHaveBeenCalledWith(
+    fixtures.initial.get.mock.results[0].value,
+    fixtures.outbox.row.mock.results[0].value)
+})
+
+it('should publish the row', async () => {
+  await state.commit(fixtures.entity)
+
+  expect(fixtures.outbox.row).toHaveBeenCalledWith(fixtures.entity.event.mock.results[0].value)
+  expect(fixtures.outbox.publish).toHaveBeenCalledWith(fixtures.outbox.row.mock.results[0].value)
 })
 
-it('should emit', async () => {
+it('should not publish if the write did not happen', async () => {
+  fixtures.storage.store.mockImplementationOnce(() => false)
+
   await state.commit(fixtures.entity)
 
-  expect(fixtures.emitter.emit).toHaveBeenCalledWith(fixtures.entity.event.mock.results[0].value)
+  expect(fixtures.outbox.publish).not.toHaveBeenCalled()
 })
 
-it('should not emit if state has not been changed', async () => {
-  await state.commit(fixtures.unchanged)
+it('should build the row before the write', async () => {
+  // the storage commits the row in the same transaction, so it must already exist
+  fixtures.storage.store.mockImplementationOnce((_, row) => {
+    expect(row).toBeDefined()
+
+    return true
+  })
+
+  expect.assertions(1)
+
+  await state.commit(fixtures.entity)
+})
+
+describe('assignment', () => {
+  const changeset = { query: 'q', export: () => ({ foo: 1 }) }
+
+  it('should pass the row to upsert and publish it', async () => {
+    const result = await state.apply(changeset, { foo: 1 })
+
+    expect(fixtures.storage.upsert).toHaveBeenCalledWith(
+      changeset.query, { foo: 1 }, fixtures.outbox.row.mock.results[0].value)
+
+    expect(fixtures.outbox.publish).toHaveBeenCalledWith(fixtures.outbox.row.mock.results[0].value)
+    expect(result).toStrictEqual(fixtures.storage.upsert.mock.results[0].value)
+  })
+
+  it('should fill the state a storage without the outbox left alone', async () => {
+    await state.apply(changeset, { foo: 1 })
+
+    const row = fixtures.outbox.row.mock.results[0].value
 
-  expect(fixtures.emitter.emit).not.toHaveBeenCalled()
+    expect(row.event.state).toStrictEqual(fixtures.storage.upsert.mock.results[0].value)
+    expect(row.event.input).toStrictEqual({ foo: 1 })
+  })
 })

package/types/atomicity.d.ts

@@ -0,0 +1,58 @@
+// noinspection ES6UnusedImports
+
+import { Connector } from './connector'
+
+declare namespace toa.core {
+
+  namespace atomicity {
+
+    /**
+     * What one group of replicas decides together, in one place. The decisions here are the
+     * ones processes cannot arrange by talking to each other: they need a single arbiter and a
+     * step indivisible from its point of view.
+     */
+    interface Atom extends Connector {
+      /**
+       * An exclusive claim on slots of `0..total`: while this replica holds one, no other
+       * replica of the group does. Answered from memory, so it costs nothing to ask.
+       *
+       * `null` while this replica owns nothing — after a restart, during a rollout, or while
+       * coordination is unreachable. Whoever asks must be able to stand down: acting on a
+       * claim that cannot be supported is a different guarantee, not a degraded one.
+       */
+      slots (total: number): number[] | null
+
+      /**
+       * Debt the group has run up under each key, in milliseconds. Every call adds its own
+       * deltas and reads back where the group stands, so a replica reports what it alone has
+       * spent and still decides on what all of them have.
+       *
+       * Rejects where there is nothing to arbitrate through.
+       */
+      meter (keys: string[], deltas: number[]): Promise<number[]>
+
+      /**
+       * Runs `routine` holding `keys`, and while it holds them no other replica of the group
+       * does. Waits for as long as it takes to acquire them.
+       *
+       * The lease is extended for as long as the routine runs. An extension that fails aborts
+       * the signal the routine is given, which is the only way it learns it no longer holds
+       * what it is working under.
+       *
+       * Rejects where there is nothing to arbitrate through.
+       */
+      lock<T> (keys: string | string[],
+        routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>
+    }
+
+    interface Factory {
+      /** @param group what the replicas deciding together have in common */
+      atom (group: string, options?: object): Atom
+    }
+
+  }
+
+}
+
+export type Atom = toa.core.atomicity.Atom
+export type Factory = toa.core.atomicity.Factory

package/types/bindings.d.ts

@@ -1,26 +1,28 @@
 import * as _core from './index'
 
-declare namespace toa.core.bindings{
+declare namespace toa.core.bindings {
 
   type Properties = {
     async?: boolean
   }
 
-  interface Consumer extends _core.Connector{
+  interface Consumer extends _core.Connector {
     request (request: Request): Promise<_core.Reply>
+
+    task (request: Request): Promise<void>
   }
 
-  interface Emitter extends _core.Connector{
+  interface Emitter extends _core.Connector {
     emit (message: _core.Message): Promise<void>
   }
 
-  interface Broadcast<L> extends _core.Connector{
+  interface Broadcast<L> extends _core.Connector {
     transmit<T> (label: L, payload: T): Promise<void>
 
     receive<T> (label: L, callback: (payload: T) => void | Promise<void>): Promise<void>
   }
 
-  interface Factory{
+  interface Factory {
     producer? (locator: _core.Locator, endpoints: Array<string>, producer: _core.Component): _core.Connector
 
     consumer? (locator: _core.Locator, endpoint: string): Consumer

package/types/bridges.ts

@@ -1,5 +1,6 @@
 import type { Request, Reply } from './request'
 import type { Context } from './context'
+import type { Connector } from './connector'
 
 export interface Algorithm {
   mount: (context?: Context) => Promise<void>
@@ -27,4 +28,6 @@ export interface Factory {
   event?: (path: string, label: string) => Event
 
   receiver?: (path: string, label: string) => Receiver
+
+  rc?: (path: string, context: Context) => Promise<{ preflight?: Connector, settle?: Connector, dispose?: Connector } | undefined>
 }

package/types/component.d.ts

@@ -1,9 +1,12 @@
 import { Connector } from './connector'
 import { Locator } from './locator'
 import { Request } from './request'
+import { Operation } from './operations'
 
-export interface Component extends Connector{
+export class Component extends Connector {
   locator: Locator
 
+  constructor (locator: Locator, operations: Record<string, Operation>)
+
   invoke<T = any> (endpoint: string, request: Request): Promise<T>
 }

package/types/context.d.ts

@@ -1,4 +1,5 @@
 import * as _request from './request'
+import { Locator } from './locator'
 import * as _reply from './reply'
 import * as _extensions from './extensions'
 import * as _connector from './connector'
@@ -6,6 +7,8 @@ import * as _connector from './connector'
 export interface Context extends _connector.Connector{
   aspects: _extensions.Aspect[]
 
+  locator: Locator
+
   /**
    * Calls local endpoint
    */

package/types/entity.d.ts

@@ -8,9 +8,9 @@ declare namespace toa.core {
     interface Factory {
       init(id: string): Entity
 
-      object(record: Object): Entity
+      object(record: Object, mutable?: boolean): Entity
 
-      objects(recordset: Object[]): Entity[]
+      objects(recordset: Object[], init?: string[], mutable?: boolean): Entity[]
 
       changeset(query: _storages.Query): Changeset
     }

package/types/extensions.d.ts

@@ -3,9 +3,10 @@ import * as _component from './component'
 import * as _context from './context'
 import * as _storages from './storages'
 import * as _bindings from './bindings'
+import { Manifest } from '@toa.io/norm'
 
-export interface Factory{
-  tenant? (locator: _core.Locator, manifest: object): _core.Connector
+export interface Factory {
+  tenant? (locator: _core.Locator, manifest: object, component: Manifest): _core.Connector
 
   aspect? (locator: _core.Locator, manifest: object | null): Aspect | Aspect[]
 
@@ -15,14 +16,16 @@ export interface Factory{
 
   context? (context: _context.Context): _context.Context
 
+  manage? (composition: _core.Connector): _core.Connector
+
   storage? (storage: _storages.Storage): _storages.Storage
 
-  emitter? (emitter: _bindings.Emitter, label: string): _bindings.Emitter
+  emitter? (emitter: _bindings.Emitter, label: string, locator: _core.Locator): _bindings.Emitter
 
   receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
 }
 
-export interface Aspect extends _core.Connector{
+export interface Aspect extends _core.Connector {
   name: string
 
   invoke (...args: any[]): any