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

package/src/receiver.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { console, decode, run } = require('openspan')
 const { add } = require('@toa.io/generic')
 const { Connector } = require('./connector')
 
@@ -16,18 +17,28 @@ class Receiver extends Connector {
   /** @type {string} */
   #endpoint
 
-  /** @type {toa.core.Component} */
+  /** @type {string} */
+  #label
+
+  /** @type {string} */
+  #destination
+
+  /** @type {unknown[]} */
+  #arguments
+
+  /** @type {toa.core.Source} */
+  #origin
+
   #local
 
-  /** @type {toa.core.bridges.Receiver} */
   #bridge
 
-  /**
-   *
-   * @param {toa.norm.component.Receiver} definition
-   * @param {toa.core.Component} local
-   * @param {toa.core.bridges.Receiver} bridge
-   */
+  /** @type {object} */
+  #delivery
+
+  /** @type {object} */
+  #processing
+
   constructor (definition, local, bridge) {
     super()
 
@@ -36,17 +47,42 @@ class Receiver extends Connector {
     this.#conditioned = conditioned
     this.#adaptive = adaptive
     this.#endpoint = operation
+    this.#label = definition.label ?? operation
+    this.#destination = definition.destination ?? this.#label
+    this.#arguments = definition.arguments
+    this.#origin = definition.origin
 
     this.#local = local
     this.#bridge = bridge
 
     this.depends(local)
     if (bridge !== undefined) this.depends(bridge)
+
+    /*
+     * The delivery span is created on behalf of the messaging destination, so that
+     * each consumer forms its own complete producer/consumer pair, and service graphs
+     * display fan-out correctly: producer -> destination -> each consumer
+     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
+     * with a single producer span, see grafana/tempo#5408)
+     */
+    this.#delivery = {
+      name: `${this.#label} deliver`,
+      kind: 'producer',
+      service: this.#destination,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    this.#processing = {
+      name: `${this.#label} process`,
+      kind: 'consumer',
+      service: local.locator.id,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
   }
 
   /** @hot */
   async receive (message) {
-    const { payload, ...extensions } = message
+    const { payload, telemetry, ...extensions } = message
 
     if (this.#conditioned && await this.#bridge.condition(payload) === false) return
 
@@ -54,11 +90,37 @@ class Receiver extends Connector {
 
     add(request, extensions)
 
-    await this.#local.invoke(this.#endpoint, request)
+    // set after `add`, so that a message field can not spoof the origin
+    if (this.#origin !== undefined) request.source = this.#origin
+
+    // continue the trace from the producer span
+    const remote = telemetry === undefined ? null : decode(telemetry)
+    const task = () => this.#process(request)
+
+    if (remote === null)
+      await task()
+    else
+      await run(remote, task)
+  }
+
+  async #process (request) {
+    return console.span(this.#delivery, async () => console.span(this.#processing, async () => {
+      try {
+        await this.#local.invoke(this.#endpoint, request)
+      } catch (error) {
+        console.error('Receiver error', {
+          component: this.#local.locator.id,
+          endpoint: this.#endpoint,
+          error
+        })
+
+        throw error
+      }
+    }))
   }
 
   async #request (payload) {
-    return this.#adaptive ? await this.#bridge.request(payload) : { input: payload }
+    return this.#adaptive ? await this.#bridge.request(payload, ...(this.#arguments ?? [])) : { input: payload }
   }
 }
 

package/src/remote.js

@@ -1,16 +1,17 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
-
+const assert = require('node:assert')
 const { Component } = require('./component')
 
 class Remote extends Component {
-  async open () {
-    console.info(`Remote '${this.locator.id}' connected`)
-  }
+  kind = 'client'
+
+  explain (endpoint) {
+    if (!(endpoint in this.operations))
+      // `assert.fail`, not `assert.ok`: the message is built only when it is needed
+      assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-  async dispose () {
-    console.info(`Remote '${this.locator.id}' disconnected`)
+    return this.operations[endpoint].explain()
   }
 }
 

package/src/state.js

@@ -1,73 +1,109 @@
 'use strict'
 
-const { empty } = require('@toa.io/generic')
-
-const {
-  StatePreconditionException,
-  StateNotFoundException
-} = require('./exceptions')
+const { StatePreconditionException, StateNotFoundException } = require('./exceptions')
 
 class State {
+  storage
+
   #associated
-  #storage
-  #entity
+  #entities
   #emission
 
   constructor (storage, entity, emission, associated) {
-    this.#storage = storage
-    this.#entity = entity
+    this.storage = storage
+    this.#entities = entity
     this.#emission = emission
     this.#associated = associated === true
   }
 
   init (id) {
-    return this.#entity.init(id)
+    return this.#entities.init(id)
+  }
+
+  fit (values) {
+    return this.#entities.fit(values)
   }
 
-  async object (query) {
-    const record = await this.#storage.get(query)
+  async object (query, mutable = true) {
+    const record = await this.storage.get(query)
 
     if (record === null) {
-      if (this.#associated && query.id !== undefined && query.version === undefined) {
+      if (this.#associated && query.id !== undefined && query.criteria === undefined && query.version === undefined)
         return this.init(query.id)
-      } else if (query.version !== undefined) throw new StatePreconditionException()
-    }
+      else if (query.version !== undefined)
+        throw new StatePreconditionException()
 
-    if (record === null) {
       return null
-    } else {
-      return this.#entity.object(record)
-    }
+    } else
+      return this.#entities.object(record, mutable)
   }
 
-  async objects (query) {
-    const recordset = await this.#storage.find(query)
+  async objects (query, mutable = true) {
+    const recordset = await this.storage.find(query)
+    const missing = this.#associated && query.ids !== undefined && recordset.length < query.ids.length
+    const init = missing ? query.ids.filter((id) => !recordset.some((record) => record.id === id)) : undefined
+    
+    return this.#entities.objects(recordset, init, mutable)
+  }
 
-    return this.#entity.objects(recordset)
+  async stream (query) {
+    return this.storage.stream(query)
   }
 
   changeset (query) {
-    return this.#entity.changeset(query)
+    return this.#entities.changeset(query)
   }
 
   none () {
     return null
   }
 
-  async commit (state) {
-    const event = state.event()
+  async ensure (query, properties, input) {
+    const object = this.#entities.init()
+    const blank = object.get()
 
-    let ok = true
+    Object.assign(blank, properties)
 
-    if (!empty(event.changeset)) {
-      const object = state.get()
+    object.set(blank)
 
-      ok = await this.#storage.store(object)
+    const record = await this.storage.ensure(query, properties, object.get())
 
-      // #20
-      if (ok === true) {
-        await this.#emission.emit(event)
-      }
+    if (record.id !== blank.id) // exists
+      return this.#entities.object(record, NOT_MUTABLE)
+
+    const event = object.event(input)
+
+    await this.#emission.emit(event)
+
+    return object
+  }
+
+  async commit (state, input) {
+    if (state.constructor.name === 'EntitySet') 
+      return this.massCommit(state, input)
+
+    const data = state.get()
+    const ok = await this.storage.store(data)
+
+    // #20
+    if (ok === true) {
+      const event = state.event(input)
+
+      await this.#emission.emit(event)
+    }
+
+    return ok
+  }
+
+  async massCommit (state, input) {
+    const data = state.get()
+    const ok = await this.storage.massStore(data)
+
+    // #20
+    if (ok === true) {
+      const events = state.events(input)
+
+      await Promise.all(events.map((event) => this.#emission.emit(event)))
     }
 
     return ok
@@ -76,7 +112,7 @@ class State {
   async apply (state) {
     const changeset = state.export()
 
-    const result = await this.#storage.upsert(state.query, changeset)
+    const result = await this.storage.upsert(state.query, changeset)
 
     if (result === null) {
       if (state.query.version !== undefined) {
@@ -96,4 +132,7 @@ class State {
   }
 }
 
+/** an effect never commits what `ensure` hands it, see `Effect` */
+const NOT_MUTABLE = false
+
 exports.State = State

package/src/transition.js

@@ -1,14 +1,13 @@
 'use strict'
 
 const { retry } = require('@toa.io/generic')
-
 const { Operation } = require('./operation')
-const {
-  StateConcurrencyException,
-  StateNotFoundException
-} = require('./exceptions')
+const { StateConcurrencyException, StateNotFoundException } = require('./exceptions')
 
 class Transition extends Operation {
+  /** a transition is the only operation that commits */
+  mutable = true
+
   #concurrency
 
   constructor (cascade, scope, contract, query, definition) {
@@ -26,33 +25,26 @@ class Transition extends Operation {
 
     store.scope = request.query ? await this.query(request.query) : this.scope.init()
 
-    if (store.scope === null) {
+    if (store.scope === null || (store.scope.deleted === true && request.query?.options?.deleted !== true))
       throw new StateNotFoundException()
-    }
-
+  
     store.state = store.scope.get()
   }
 
   async commit (store) {
-    const {
-      scope,
-      state,
-      reply,
-      retry
-    } = store
+    const { scope, state, reply, retry } = store
 
     if (reply.error !== undefined) return
 
     scope.set(state)
 
-    const result = await this.scope.commit(scope)
+    const result = await this.scope.commit(scope, store.request.input)
 
     if (result === false) {
-      if (this.#concurrency === 'retry') {
+      if (this.#concurrency === 'retry')
         return retry()
-      } else {
+      else
         throw new StateConcurrencyException()
-      }
     }
   }
 
@@ -67,7 +59,7 @@ const RETRY = {
   base: 10,
   max: 5000,
   dispersion: 1,
-  retries: Infinity
+  retries: 32
 }
 
 exports.Transition = Transition

package/src/transmission.js

@@ -18,13 +18,22 @@ class Transmission extends Connector {
     let i = 0
 
     while (reply === false && i < this.#bindings.length) {
-      reply = await this.#bindings[i].request(request)
+      const binding = this.#bindings[i]
+
       i++
+
+      if (request?.task === true) {
+        if (binding.task === undefined)
+          continue
+
+        await binding.task(request)
+        reply = null
+      } else
+        reply = await binding.request(request)
     }
 
-    if (reply === false) {
+    if (reply === false)
       throw new TransmissionException(`All (${this.#bindings.length}) bindings rejected.`)
-    }
 
     return reply
   }

package/src/unmanaged.js

@@ -0,0 +1,11 @@
+'use strict'
+
+const { Operation } = require('./operation')
+
+class Unmanaged extends Operation {
+  acquire (context) {
+    context.state = this.scope.storage.raw
+  }
+}
+
+exports.Unmanaged = Unmanaged

package/test/component.test.js

@@ -3,6 +3,7 @@
 const { Component } = require('../src/component')
 const { codes } = require('../src/exceptions')
 const fixtures = require('./component.fixtures')
+const { AssertionError } = require('node:assert')
 
 describe('Invocations', () => {
   const name = ['foo', 'bar'][Math.floor(2 * Math.random())]
@@ -16,12 +17,12 @@ describe('Invocations', () => {
   it('should invoke', async () => {
     await component.invoke(name)
 
-    expect(invocation.invoke).toBeCalled()
+    expect(invocation.invoke).toHaveBeenCalled()
   })
 
   it('should throw on unknown invocation name', async () => {
     await expect(() => component.invoke('baz'))
-      .rejects.toMatchObject({ code: codes.NotImplemented })
+      .rejects.toThrow(AssertionError)
   })
 
   it('should invoke input and query', async () => {
@@ -29,7 +30,7 @@ describe('Invocations', () => {
     const query = { test: Math.random() }
     await component.invoke(name, { input, query })
 
-    expect(invocation.invoke).toBeCalledWith({ input, query })
+    expect(invocation.invoke).toHaveBeenCalledWith({ input, query })
   })
 
   it('should return io', async () => {

package/test/connector.fixtures.js

@@ -36,5 +36,13 @@ class FailingConnector extends Connector {
   }
 }
 
+/** Stands for a connector waiting for something that never arrives. */
+class StuckConnector extends Connector {
+  async open () {
+    return new Promise(() => undefined)
+  }
+}
+
 exports.TestConnector = TestConnector
 exports.FailingConnector = FailingConnector
+exports.StuckConnector = StuckConnector

package/test/connector.test.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { timeout } = require('@toa.io/generic')
+
 const fixtures = require('./connector.fixtures')
 
 let sequence
@@ -105,6 +107,7 @@ describe('dependencies', () => {
     a.depends(b).depends(c)
     b.depends(d)
 
+    await a.connect()
     await a.disconnect()
 
     expect(sequence.indexOf('-a')).toBeLessThan(sequence.indexOf('-b'))
@@ -146,6 +149,23 @@ describe('dependencies', () => {
     expect(() => a.depends({})).toThrow()
   })
 
+  it('should disconnect while still connecting', async () => {
+    const stuck = new fixtures.StuckConnector()
+
+    a.depends(stuck).depends(b)
+
+    void a.connect()
+
+    while (b.connected !== true) await timeout(1)
+
+    // `a` never connects, and disconnecting must not wait for it to
+    expect(a.connected).toStrictEqual(false)
+
+    await a.disconnect()
+
+    expect(sequence).toEqual(['+b', '-b', '*b', '*a'])
+  })
+
   describe('errors', () => {
     let f
 

package/test/contract/conditions.test.js

@@ -2,19 +2,19 @@
 
 const { generate } = require('randomstring')
 
-const { Conditions } = require('../../src/contract/conditions')
+const { Contract } = require('../../src/contract/contract')
 const fixtures = require('./contract.fixtures')
 
-let conditions
+let contract
 
 beforeEach(() => {
-  conditions = new Conditions(fixtures.schema)
+  contract = new Contract(fixtures.schema)
 })
 
 it('should fit value', () => {
   const value = { foo: generate() }
 
-  conditions.fit(value)
+  contract.fit(value)
 
   expect(fixtures.schema.fit).toHaveBeenCalledWith(value)
 })
@@ -22,5 +22,5 @@ it('should fit value', () => {
 it('should throw on invalid value', () => {
   const value = { invalid: true }
 
-  expect(() => conditions.fit(value)).toThrow()
+  expect(() => contract.fit(value)).toThrow()
 })

package/test/contract/request.test.js

@@ -3,10 +3,10 @@
 const clone = require('clone-deep')
 const { generate } = require('randomstring')
 
-jest.mock('../../src/contract/conditions')
+jest.mock('../../src/contract/contract')
 
 const { Request } = require('../../src/contract/request')
-const { Conditions } = require('../../src/contract/conditions')
+const { Contract } = require('../../src/contract/contract')
 const fixtures = require('./contract.fixtures')
 
 let contract
@@ -14,14 +14,14 @@ let contract
 beforeEach(() => {
   jest.clearAllMocks()
 
-  contract = new Request(fixtures.schema)
+  contract = new Request(fixtures.schema, {})
 })
 
 const dummy = { schema: { properties: {} } }
 
 it('should extend Conditions', () => {
-  expect(contract).toBeInstanceOf(Conditions)
-  expect(Conditions).toHaveBeenCalledWith(fixtures.schema)
+  expect(contract).toBeInstanceOf(Contract)
+  expect(Contract).toHaveBeenCalledWith(fixtures.schema)
 })
 
 it('should fit request', () => {
@@ -29,7 +29,7 @@ it('should fit request', () => {
 
   contract.fit(request)
 
-  expect(Conditions.mock.instances[0].fit).toHaveBeenCalledWith(request)
+  expect(Contract.mock.instances[0].fit).toHaveBeenCalledWith(request)
 })
 
 describe('schema', () => {
@@ -59,7 +59,7 @@ describe('schema', () => {
 
   it('should not contain query if declaration.query is false', () => {
     schema.properties.query = { type: 'null' }
-    expect(Request.schema({ query: false }, dummy)).toStrictEqual(schema)
+    expect(Request.schema({ query: false }, dummy)).toMatchObject(schema)
   })
 
   it('should require query if declaration.query is true', () => {
@@ -110,3 +110,42 @@ describe('schema', () => {
     expect(objects.limit).toBeDefined()
   })
 })
+
+describe('source', () => {
+  const schemas = require('@toa.io/schemas')
+
+  const compile = (definition, entity) =>
+    schemas.schema(Request.schema(definition, entity), { removeAdditional: true })
+
+  it('should declare source', () => {
+    const schema = Request.schema({}, dummy)
+
+    expect(schema.properties.source).toBeDefined()
+    expect(schema.properties.source.additionalProperties).toStrictEqual(false)
+  })
+
+  it('should pass known source variants', () => {
+    const schema = compile({}, undefined)
+
+    for (const source of [
+      { namespace: 'a', component: 'b', operation: 'c' },
+      { namespace: 'a', component: 'b', event: 'c' },
+      { service: 'exposition' }
+    ]) {
+      const request = { input: null, query: null, source }
+
+      expect(schema.fit(request)).toStrictEqual(null)
+      expect(request.source).toStrictEqual(source)
+    }
+  })
+
+  // `source` crosses the wire and keys the introspection map, so whatever
+  // a peer adds to it must not survive
+  it('should strip unknown source properties', () => {
+    const schema = compile({}, undefined)
+    const request = { input: null, query: null, source: { service: 'exposition', evil: 'x' } }
+
+    expect(schema.fit(request)).toStrictEqual(null)
+    expect(request.source).toStrictEqual({ service: 'exposition' })
+  })
+})

package/test/discovery.test.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const { console } = require('openspan')
+const { Connector } = require('../src/connector')
+const { Discovery } = require('../src/discovery')
+
+class Lookup extends Connector {
+  invoke = jest.fn(async () => ({ operations: {} }))
+}
+
+/** @type {Lookup} */
+let lookup
+
+/** @type {Discovery} */
+let discovery
+
+/** @type {jest.SpyInstance} */
+let warn
+
+const locator = { id: 'dummies.one' }
+
+beforeEach(async () => {
+  jest.useFakeTimers()
+
+  warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+  lookup = new Lookup()
+  discovery = new Discovery(async () => lookup)
+
+  await discovery.connect()
+})
+
+afterEach(() => {
+  warn.mockRestore()
+  jest.useRealTimers()
+})
+
+it('should not warn if a lookup is answered', async () => {
+  await discovery.lookup(locator)
+
+  jest.advanceTimersByTime(60_000)
+
+  expect(warn).not.toHaveBeenCalled()
+})
+
+it('should keep warning while a lookup is unanswered', async () => {
+  lookup.invoke.mockImplementation(() => new Promise(() => undefined))
+
+  void discovery.lookup(locator)
+
+  await jest.advanceTimersByTimeAsync(12_000)
+
+  expect(warn).toHaveBeenCalledTimes(2)
+
+  expect(warn).toHaveBeenLastCalledWith('Waiting for lookup response',
+    { component: locator.id, waiting: 10 })
+})