@toa.io/core 1.0.0-alpha.25 → 1.0.0-alpha.251

package/src/entities/newid.js

@@ -0,0 +1,11 @@
+const uuid = require('uuid')
+
+function newid () {
+  const buf = Buffer.alloc(16)
+
+  uuid.v7(undefined, buf)
+
+  return buf.toString('hex')
+}
+
+module.exports = { newid }

package/src/entities/set.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { SystemException } = require("../exceptions")
+
 class EntitySet {
   #set
 
@@ -10,6 +12,17 @@ class EntitySet {
   get () {
     return this.#set.map((entity) => entity.get())
   }
+
+  set (values) {
+    if (values.length !== this.#set.length)
+      throw new SystemException('Objects array must not be modified')
+
+    values.forEach((value, index) => this.#set[index].set(value))
+  }
+
+  events (input = undefined) {
+    return this.#set.map((entity) => entity.event(input))
+  }
 }
 
 exports.EntitySet = EntitySet

package/src/event.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { console, current, encode } = require('openspan')
 const { Connector } = require('./connector')
 
 /**
@@ -12,11 +13,15 @@ class Event extends Connector {
   #conditioned
   #subjective
 
+  /** @type {string} */
+  #label
+
   constructor (definition, emitter, bridge = undefined) {
     super()
 
     this.#conditioned = definition.conditioned
     this.#subjective = definition.subjective
+    this.#label = definition.label ?? 'event'
     this.#emitter = emitter
     this.#bridge = bridge
 
@@ -32,7 +37,20 @@ class Event extends Connector {
       /** @type {toa.core.Message} */
       const message = { payload }
 
-      await this.#emitter.emit(message)
+      const options = {
+        name: `${this.#label} publish`,
+        kind: 'producer',
+        attributes: { 'messaging.destination.name': this.#label }
+      }
+
+      await console.span(options, async () => {
+        const context = current()
+
+        if (context !== undefined)
+          message.telemetry = encode(context)
+
+        await this.#emitter.emit(message)
+      })
     }
   }
 }

package/src/exceptions.js

@@ -4,7 +4,6 @@ const { swap } = require('@toa.io/generic')
 
 const codes = {
   System: 0,
-  NotImplemented: 10,
 
   Contract: 200,
   RequestSyntax: 201,
@@ -12,6 +11,7 @@ const codes = {
   RequestConflict: 203,
   ResponseContract: 211,
   EntityContract: 212,
+  EntityGuard: 213,
   QuerySyntax: 221,
 
   State: 300,
@@ -32,9 +32,12 @@ class Exception {
   code
   message
 
-  constructor (code, message) {
+  constructor (code, message, cause) {
     this.code = code
     this.message = message
+
+    if (cause !== undefined)
+      this.cause = cause
   }
 }
 
@@ -49,31 +52,30 @@ class SystemException extends Exception {
 }
 
 class ContractException extends Exception {
-  keyword
-  property
-  schema
-  path
-
-  constructor (code, error) {
-    super(code || codes.Contract, error.message)
-
-    this.keyword = error.keyword
-    this.property = error.property
-    this.schema = error.schema
-    this.path = error.path
+  constructor (code, error, cause) {
+    super(code || codes.Contract, typeof error === 'string' ? error : error?.message, cause)
+
+    if (typeof error === 'object' && error !== null)
+      for (const k of ['keyword', 'property', 'schema', 'path', 'params'])
+        if (k in error)
+          this[k] = error[k]
   }
 }
 
 class RequestContractException extends ContractException {
-  constructor (error) { super(codes.RequestContract, error) }
+  constructor (error, cause) { super(codes.RequestContract, error, cause) }
 }
 
 class ResponseContractException extends ContractException {
-  constructor (error) { super(codes.ResponseContract, error) }
+  constructor (error, cause) { super(codes.ResponseContract, error, cause) }
 }
 
 class EntityContractException extends ContractException {
-  constructor (error) { super(codes.EntityContract, error) }
+  constructor (error, cause) { super(codes.EntityContract, error, cause) }
+}
+
+class EntityGuardException extends ContractException {
+  constructor (name, cause) { super(codes.EntityGuard, name, cause) }
 }
 
 // #region exports
@@ -82,14 +84,19 @@ exports.SystemException = SystemException
 exports.RequestContractException = RequestContractException
 exports.ResponseContractException = ResponseContractException
 exports.EntityContractException = EntityContractException
+exports.EntityGuardException = EntityGuardException
 
 for (const [name, code] of Object.entries(codes)) {
   const classname = name + 'Exception'
 
   if (exports[classname] === undefined) {
     exports[classname] = class extends Exception {
-      constructor (message) {
-        super(code, message ?? classname)
+      constructor (message, cause) {
+        message = message
+          ? `${classname}: ${message}`
+          : classname
+
+        super(code, message ?? classname, cause)
       }
     }
   }

package/src/exposition.js

@@ -20,8 +20,9 @@ class Exposition extends Connector {
 }
 
 const expose = (manifest) => {
-  const { namespace, name, operations, events, entity } = manifest
-  return { namespace, name, operations, events, entity }
+  const { namespace, name, entity, operations, events } = manifest
+
+  return { namespace, name, entity, operations, events }
 }
 
 exports.Exposition = Exposition

package/src/guard.js

@@ -0,0 +1,17 @@
+'use strict'
+
+class Guard {
+  name
+  #bridge
+
+  constructor (name, bridge) {
+    this.name = name
+    this.#bridge = bridge
+  }
+
+  fit (state, origin) {
+    return this.#bridge.fit(state, origin)
+  }
+}
+
+exports.Guard = Guard

package/src/index.js

@@ -5,6 +5,7 @@ const { Composition } = require('./composition')
 const { Connector } = require('./connector')
 const { Context } = require('./context')
 const { Discovery } = require('./discovery')
+const { Effect } = require('./effect')
 const { Emission } = require('./emission')
 const { Event } = require('./event')
 const { Exposition } = require('./exposition')
@@ -19,6 +20,8 @@ const { Component } = require('./component')
 const { State } = require('./state')
 const { Transition } = require('./transition')
 const { Transmission } = require('./transmission')
+const { Unmanaged } = require('./unmanaged')
+const { Guard } = require('./guard')
 
 exports.entities = require('./entities')
 exports.exceptions = require('./exceptions')
@@ -32,6 +35,7 @@ exports.Composition = Composition
 exports.Connector = Connector
 exports.Context = Context
 exports.Discovery = Discovery
+exports.Effect = Effect
 exports.Emission = Emission
 exports.Event = Event
 exports.Exposition = Exposition
@@ -45,3 +49,5 @@ exports.Remote = Remote
 exports.State = State
 exports.Transition = Transition
 exports.Transmission = Transmission
+exports.Unmanaged = Unmanaged
+exports.Guard = Guard

package/src/observation.js

@@ -3,16 +3,8 @@
 const { Operation } = require('./operation')
 
 class Observation extends Operation {
-  async acquire (store) {
-    const scope = await this.query(store.request.query)
-    const state = scope === null ? null : scope.get()
-
-    store.scope = scope
-    store.state = state
-  }
-
   async run (store) {
-    if (store.scope === null) store.reply = null
+    if (store.scope === null || (store.scope?.deleted === true && store.request.query?.options?.deleted !== true)) store.reply = null
     else await super.run(store)
   }
 }

package/src/operation.js

@@ -1,7 +1,8 @@
 'use strict'
 
 const { Connector } = require('./connector')
-const { SystemException } = require('./exceptions')
+const { SystemException, RequestContractException } = require('./exceptions')
+const { Readable } = require('node:stream')
 
 class Operation extends Connector {
   scope
@@ -26,8 +27,15 @@ class Operation extends Connector {
 
   async invoke (request) {
     try {
-      if (request.authentic !== true) this.#contracts.request.fit(request)
-      if ('query' in request) request.query = this.#query.parse(request.query)
+      if (request.authentic !== true)
+        this.#contracts.request.fit(request)
+
+      if ('query' in request)
+        request.query = this.#query.parse(request.query)
+
+      // validate entity
+      if ('entity' in request)
+        this.scope.fit(request.entity)
 
       const store = { request }
 
@@ -47,14 +55,24 @@ class Operation extends Connector {
     return store.reply
   }
 
-  async acquire () {}
+  async acquire (store) {
+    if (this.#scope === 'none')
+      return
+
+    const scope = await this.query(store.request.query)
+    const raw = scope === null || scope instanceof Readable
+
+    store.scope = scope
+    store.state = raw ? scope : scope.get()
+  }
 
   async run (store) {
     const { request, state } = store
-    // noinspection UnnecessaryLocalVariableJS
-    const reply = await this.#cascade.run(request.input, state) || {}
+    const reply = await this.#cascade.run(request.input, state)
 
-    // this.#contracts.reply.fit(reply)
+    // validate reply only on local environments
+    if (process.env.TOA_ENV === 'local' && !(reply instanceof Readable))
+      this.#contracts.reply.fit(reply)
 
     store.reply = reply
   }
@@ -62,6 +80,9 @@ class Operation extends Connector {
   async commit () {}
 
   async query (query) {
+    if (query === undefined)
+      throw new RequestContractException('Request query is required')
+
     return this.scope[this.#scope](query)
   }
 }

package/src/query/options.js

@@ -33,8 +33,9 @@ const projection = (projection, properties) => {
     }
   }
 
-  if (projection.includes('_version') === false)
-    projection.push('_version')
+  for (const property of ['_version', '_created', '_updated', '_deleted'])
+    if (!projection.includes(property))
+      projection.push(property)
 }
 
 exports.options = options

package/src/query.js

@@ -19,13 +19,15 @@ class Query {
   parse (query) {
     /** @type {toa.core.storages.Query} */
     const result = {}
-    const { id, version, criteria, ...rest } = query
+    const { id, ids, version, criteria, search, ...rest } = query
 
     const options = this.#options(rest)
 
     if (id !== undefined) result.id = id
+    if (ids !== undefined) result.ids = ids
     if (version !== undefined) result.version = version
     if (criteria !== undefined) result.criteria = parse.criteria(criteria, this.#properties)
+    if (search !== undefined) result.search = search
     if (options !== undefined) result.options = options
 
     return result

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,19 @@ class Receiver extends Connector {
   /** @type {string} */
   #endpoint
 
-  /** @type {toa.core.Component} */
+  /** @type {string} */
+  #label
+
+  /** @type {string} */
+  #destination
+
+  /** @type {unknown[]} */
+  #arguments
+
   #local
 
-  /** @type {toa.core.bridges.Receiver} */
   #bridge
 
-  /**
-   *
-   * @param {toa.norm.component.Receiver} definition
-   * @param {toa.core.Component} local
-   * @param {toa.core.bridges.Receiver} bridge
-   */
   constructor (definition, local, bridge) {
     super()
 
@@ -36,6 +38,9 @@ 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.#local = local
     this.#bridge = bridge
@@ -46,7 +51,7 @@ class Receiver extends Connector {
 
   /** @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 +59,55 @@ class Receiver extends Connector {
 
     add(request, extensions)
 
-    await this.#local.invoke(this.#endpoint, request)
+    // 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) {
+    /*
+     * 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)
+     */
+    const delivery = {
+      name: `${this.#label} deliver`,
+      kind: 'producer',
+      service: this.#destination,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    const options = {
+      name: `${this.#label} process`,
+      kind: 'consumer',
+      service: this.#local.locator.id,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    return console.span(delivery, async () => console.span(options, 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,16 @@
 '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) {
+    assert.ok(endpoint in this.operations,
+      `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)
+    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)
   }
 
   async objects (query) {
-    const recordset = await this.#storage.find(query)
+    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)
+  }
 
-    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)
+
+    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) {