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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.251",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -21,13 +21,11 @@
   },
   "dependencies": {
     "@rsql/parser": "1.2.4",
-    "@toa.io/console": "1.0.0-alpha.25",
-    "@toa.io/generic": "1.0.0-alpha.25",
-    "@toa.io/yaml": "1.0.0-alpha.25",
-    "error-value": "0.3.0"
+    "@toa.io/generic": "1.0.0-alpha.225",
+    "@toa.io/yaml": "1.0.0-alpha.246",
+    "error-value": "0.3.0",
+    "openspan": "1.0.0-alpha.251",
+    "uuid": "11.1.1"
   },
-  "devDependencies": {
-    "clone-deep": "4.0.1"
-  },
-  "gitHead": "756ea259f35dda03d45047f8153d441191026877"
+  "gitHead": "c3857e14dde3a910fe28d41a5a97a960c15beba3"
 }

package/src/call.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { Readable } = require('node:stream')
+const { current, encode } = require('openspan')
 const { Connector } = require('./connector')
 const { Err } = require('error-value')
 
@@ -18,11 +19,18 @@ class Call extends Connector {
   }
 
   async invoke (request = {}) {
+    request.input ??= null
+
     this.#contract.fit(request)
 
     // avoid validation on the recipient's side
     request.authentic = true
 
+    const context = current()
+
+    if (context !== undefined)
+      request.telemetry = encode(context)
+
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null
@@ -37,6 +45,10 @@ class Call extends Connector {
         return reply.output
     }
   }
+
+  explain () {
+    return this.#contract.discovery
+  }
 }
 
 exports.Call = Call

package/src/cascade.js

@@ -1,19 +1,21 @@
 'use strict'
 
-const { merge } = require('@toa.io/generic')
 const { Connector } = require('./connector')
 
 class Cascade extends Connector {
-  #bridges
+  // #bridges
   #last
 
-  constructor (bridges) {
+  constructor (bridges, rc) {
     super()
 
-    this.#bridges = bridges
+    // this.#bridges = bridges
     this.#last = bridges[bridges.length - 1]
 
-    this.depends(bridges)
+    if (rc === undefined)
+      this.depends(bridges)
+    else
+      this.depends(bridges).depends(rc)
   }
 
   async run (...args) {

package/src/component.js

@@ -1,40 +1,64 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const assert = require('node:assert')
+const { console, current, decode, run } = require('openspan')
 const { Connector } = require('./connector')
-const { NotImplementedException } = require('./exceptions')
 
-/**
- * @implements {toa.core.Component}
- */
 class Component extends Connector {
   locator
 
-  #operations
+  /** @protected */
+  operations
+
+  /** @protected */
+  kind = 'server'
 
   constructor (locator, operations) {
     super()
 
     this.locator = locator
-    this.#operations = operations
+    this.operations = operations
 
     Object.values(operations).forEach((operation) => this.depends(operation))
   }
 
-  async open () {
-    console.info(`Runtime '${this.locator.id}' connected`)
-  }
+  async invoke (endpoint, request) {
+    assert.ok(endpoint in this.operations,
+      `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-  async dispose () {
-    console.info(`Runtime '${this.locator.id}' disconnected`)
+    // if the request carries no telemetry, the trace starts here
+    const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
+    const task = () => this.process(endpoint, request)
+
+    if (remote === null)
+      return task()
+    else
+      return run(remote, task)
   }
 
-  async invoke (endpoint, request) {
-    if (!(endpoint in this.#operations)) {
-      throw new NotImplementedException(`Endpoint '${endpoint}' not found in '${this.locator.id}'`)
-    }
+  /** @private */
+  async process (endpoint, request) {
+    const options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+    // the server span is emitted by the component itself,
+    // while the client span belongs to the calling service and inherits it from the context
+    if (this.kind === 'server')
+      options.service = this.locator.id
+
+    return console.span(options, async () => {
+      const reply = await this.operations[endpoint].invoke(request)
+
+      if (reply?.exception !== undefined) {
+        current().status = 'error'
+
+        console.error('Failed to execute operation', {
+          endpoint: `${this.locator.id}.${endpoint}`,
+          exception: reply.exception
+        })
+      }
 
-    return this.#operations[endpoint].invoke(request)
+      return reply
+    })
   }
 }
 

package/src/composition.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const { console } = require('openspan')
 const { Connector } = require('./connector')
 
 class Composition extends Connector {

package/src/connector.js

@@ -1,7 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
-const { newid } = require('@toa.io/generic')
+const { console } = require('openspan')
 
 /**
  * Abstract connections hierarchy
@@ -26,7 +25,7 @@ class Connector {
   connected = false
 
   constructor () {
-    this.id = this.constructor.name + '#' + newid().substring(0, 8)
+    this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
   }
 
   /**
@@ -86,12 +85,18 @@ class Connector {
 
     this.#disconnecting = undefined
 
-    console.debug(`Connecting '${this.id}' with ${this.#dependencies.length} dependencies...`)
-
-    this.#connecting = (async () => {
+    const work = async () => {
       await Promise.all(this.#dependencies.map((connector) => connector.connect()))
       await this.open()
-    })()
+    }
+
+    // anonymous grouping nodes are not worth a span
+    this.#connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
+      ? console.span({
+        name: `connect ${this.constructor.name}`,
+        attributes: { id: this.locator?.id ?? this.id }
+      }, work)
+      : work()
 
     try {
       await this.#connecting
@@ -100,8 +105,6 @@ class Connector {
       await this.disconnect(true)
       throw e
     }
-
-    console.debug(`Connector '${this.id}' connected`)
   }
 
   /**
@@ -115,7 +118,11 @@ class Connector {
    * @returns {Promise<void>}
    */
   async disconnect (interrupt) {
-    if (interrupt !== true) await this.#connecting
+    // a connector that has not finished connecting has nothing to close, and
+    // awaiting a connection that may never settle outlives any grace period
+    const pending = interrupt === true || this.connected === false
+
+    if (!pending) await this.#connecting
 
     if (this.#disconnecting) return this.#disconnecting
 
@@ -132,10 +139,11 @@ class Connector {
       const interval = setInterval(() => {
         const delay = +new Date() - start
 
-        if (delay > DELAY) console.warn(`Connector ${this.id} still disconnecting (${delay})`)
+        if (delay > DELAY)
+          console.warn(`Connector ${this.id} still disconnecting (${delay})`)
       }, DELAY)
 
-      if (interrupt !== true) await this.close()
+      if (!pending) await this.close()
 
       clearInterval(interval)
 
@@ -145,8 +153,6 @@ class Connector {
     })()
 
     await this.#disconnecting
-
-    console.debug(`Connector '${this.id}' disconnected`)
   }
 
   async reconnect () {
@@ -179,5 +185,6 @@ class Connector {
 }
 
 const DELAY = 5000
+const TRACE_BOOT = process.env.TOA_BOOT_TRACE === '1'
 
 exports.Connector = Connector

package/src/context.js

@@ -6,6 +6,8 @@ const { Connector } = require('./connector')
  * @implements {toa.core.Context}
  */
 class Context extends Connector {
+  env
+  name
   aspects
 
   #local
@@ -15,6 +17,8 @@ class Context extends Connector {
   constructor (local, discover, aspects = []) {
     super()
 
+    this.env = process.env.TOA_ENV
+    this.name = process.env.TOA_CONTEXT
     this.aspects = aspects
 
     this.#local = local

package/src/contract/contract.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const { SystemException } = require('../exceptions')
+
+class Contract {
+  schema
+
+  constructor (schema) {
+    this.schema = schema
+  }
+
+  fit (value) {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new this.constructor.Exception(error, value)
+  }
+
+  static Exception = SystemException
+}
+
+exports.Contract = Contract

package/src/contract/reply.js

@@ -1,22 +1,39 @@
 'use strict'
 
 const schemas = require('./schemas')
-const { Conditions } = require('./conditions')
+const { Contract } = require('./contract')
 const { ResponseContractException } = require('../exceptions')
 
-class Reply extends Conditions {
+class Reply extends Contract {
   static Exception = ResponseContractException
 
-  /**
-   * @returns {toa.schema.JSON}
-   */
-  static schema (output, error) {
+  static schema (output, errors) {
     const schema = { type: 'object', properties: {}, additionalProperties: false }
 
-    if (output !== undefined) schema.properties.output = output
+    if (output !== undefined) {
+      if (output.type === 'object')
+        output.additionalProperties = true
+      else if (output.type === 'array' && output.items?.type === 'object')
+        output.items.additionalProperties = true
 
-    if (error !== undefined) schema.properties.error = error
-    else schema.properties.error = schemas.error
+      schema.properties.output = output
+    }
+
+    if (errors !== undefined)
+      schema.properties.error = {
+        type: 'object',
+        properties: {
+          code: {
+            enum: errors
+          },
+          message: {
+            type: 'string'
+          }
+        },
+        required: ['code']
+      }
+    else
+      schema.properties.error = schemas.error
 
     return schema
   }

package/src/contract/request.js

@@ -2,9 +2,20 @@
 
 const schemas = require('./schemas')
 const { RequestContractException } = require('../exceptions')
-const { Conditions } = require('./conditions')
+const { Contract } = require('./contract')
+
+class Request extends Contract {
+  /** @readonly */
+  discovery = {}
+
+  constructor (schema, definition) {
+    super(schema)
+
+    for (const key of ['input', 'output', 'errors'])
+      if (definition[key] !== undefined)
+        this.discovery[key] = definition[key]
+  }
 
-class Request extends Conditions {
   static Exception = RequestContractException
 
   /**
@@ -13,7 +24,7 @@ class Request extends Conditions {
   static schema (definition, entity) {
     const schema = {
       type: 'object',
-      properties: { authentic: { type: 'boolean' } },
+      properties: { authentic: { type: 'boolean' }, task: { type: 'boolean' } },
       additionalProperties: true
     }
 
@@ -22,9 +33,8 @@ class Request extends Conditions {
     if (definition.input !== undefined) {
       schema.properties.input = definition.input
       required.push('input')
-    } else {
+    } else
       schema.properties.input = { type: 'null' }
-    }
 
     if (entity === undefined)
       definition.query = false

package/src/contract/schemas/query.yaml

@@ -1,11 +1,22 @@
 type: object
 properties:
-  id: { }
+  id:
+    type: string
+  ids:
+    type: array
+    uniqueItems: true
+    minItems: 1
+    items:
+      type: string
   version:
     type: integer
     minimum: 0
   criteria:
     type: string
+  search:
+    type: string
+  sample:
+    type: number
   omit:
     type: integer
     minimum: 0
@@ -27,4 +38,6 @@ properties:
       type: string
       not:
         const: id
+  deleted:
+    type: boolean
 additionalProperties: false

package/src/discovery.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const { console } = require('openspan')
 const { Connector } = require('./connector')
 
 class Discovery extends Connector {
@@ -25,20 +25,26 @@ class Discovery extends Connector {
       this.depends(this.#lookups[id])
     }
 
-    console.debug(`Sending lookup request to '${id}'`)
+    const since = Date.now()
 
-    const warning = () => console.warn(`Waiting for lookup response from '${id}'...`)
-    const timeout = setTimeout(warning, TIMEOUT)
+    // the wait is unbounded by design, as a dependency may still be starting,
+    // so repeating is the only way a component stuck on one stays visible
+    const warning = setInterval(() => {
+      const waiting = Math.round((Date.now() - since) / 1000)
+
+      console.warn('Waiting for lookup response', { component: id, waiting })
+    }, INTERVAL)
+
+    warning.unref()
 
     const output = await this.#lookups[id].invoke()
 
-    console.debug(`Lookup response from '${id}' received`)
-    clearTimeout(timeout)
+    clearInterval(warning)
 
     return output
   }
 }
 
-const TIMEOUT = 5000
+const INTERVAL = 5000
 
 exports.Discovery = Discovery

package/src/effect.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { Observation } = require('./observation')
+
+class Effect extends Observation {
+
+  async acquire (store) {
+    const { query, entity, input } = store.request
+
+    if (entity === undefined)
+      return super.acquire(store)
+
+    store.scope = await this.scope.ensure(query, entity, input)
+    store.state = store.scope.get()
+  }
+
+}
+
+exports.Effect = Effect

package/src/entities/changeset.js

@@ -1,10 +1,5 @@
 'use strict'
 
-const {
-  merge,
-  overwrite,
-  newid
-} = require('@toa.io/generic')
 const { EntityContractException } = require('../exceptions')
 
 class Changeset {
@@ -18,7 +13,7 @@ class Changeset {
     this.query = query
 
     this.#schema = schema
-    this.#state = schema.system()
+    this.#state = {}
   }
 
   get () {
@@ -26,10 +21,12 @@ class Changeset {
   }
 
   set (value) {
-    const error = this.#schema.adapt(value)
+    const error = this.#schema.match(value)
 
-    if (error !== null) throw new EntityContractException(error)
+    if (error !== null)
+      throw new EntityContractException(error, value)
 
+    delete value._version
     value._updated = Date.now()
 
     this.#state = value

package/src/entities/entity.js

@@ -1,23 +1,23 @@
 'use strict'
 
-const {
-  difference,
-  newid
-} = require('@toa.io/generic')
-
-const { EntityContractException } = require('../exceptions')
+const { difference } = require('@toa.io/generic')
+const { EntityContractException, EntityGuardException } = require('../exceptions')
+const { newid } = require('./newid')
 
 class Entity {
+  deleted = false
   #schema
+  #guards
   #origin = null
   #state
 
-  constructor (schema, argument) {
+  constructor (schema, argument, guards) {
     this.#schema = schema
+    this.#guards = guards
 
     if (typeof argument === 'object') {
       const object = structuredClone(argument)
-      this.set(object)
+      this.#set(object)
       this.#origin = argument
     } else {
       const id = argument === undefined ? newid() : argument
@@ -29,37 +29,62 @@ class Entity {
     return this.#state
   }
 
-  set (value) {
-    const error = this.#schema.fit(value)
+  set (value, optional = false) {
+    if (!optional)
+      this.#guard(value)
+
+    const error = optional ? this.#schema.fitOptional(value) : this.#schema.fit(value)
 
-    if (error !== null) throw new EntityContractException(error)
+    if (error !== null)
+      throw new EntityContractException(error, value)
 
     this.#set(value)
   }
 
-  event () {
+  event (input = undefined) {
     return {
       origin: this.#origin,
       state: this.#state,
-      changeset: this.#origin === null ? this.#state : difference(this.#origin, this.#state)
+      changeset: this.#origin === null ? this.#state : difference(this.#origin, this.#state),
+      trailers: this.#state._trailers,
+      input
     }
   }
 
   #init (id) {
-    const value = {
-      ...this.#schema.defaults({ id }),
-      _version: 0,
-      _created: Date.now()
-    }
+    const value = { id, _version: 0 }
 
-    this.#set(value)
+    this.set(value, true)
+  }
+
+  #guard (value) {
+    if (this.#guards === undefined)
+      return
+
+    for (const guard of this.#guards) {
+      const ok = guard.fit(value, this.#origin)
+
+      if (ok === false)
+        throw new EntityGuardException(guard.name, value)
+    }
   }
 
   #set (value) {
-    Object.defineProperty(value, 'id', {
-      writable: false,
-      configurable: false
-    })
+    if (!('_trailers' in value))
+      Object.defineProperty(value, '_trailers', {
+        writable: false,
+        configurable: false,
+        enumerable: false,
+        value: {}
+      })
+
+    if (!('_created' in value)) {
+      value._created = Date.now()
+      value._updated ??= value._created
+    }
+
+    if ('_deleted' in value && value._deleted !== null)
+      this.deleted = true
 
     if (this.#state !== undefined) {
       value._updated = Date.now()

package/src/entities/factory.js

@@ -1,27 +1,38 @@
 'use strict'
 
+const { newid } = require('./newid')
 const { Entity } = require('./entity')
 const { EntitySet } = require('./set')
 const { Changeset } = require('./changeset')
 
 class Factory {
   #schema
+  #guards
 
-  constructor (schema) {
+  constructor (schema, guards) {
     this.#schema = schema
+    this.#guards = guards
+  }
+
+  fit (values) {
+    this.#schema.validate({ id: newid(), ...values }, 'Entity')
   }
 
   init (id) {
-    return new Entity(this.#schema, id)
+    return new Entity(this.#schema, id, this.#guards)
   }
 
   object (record) {
-    return new Entity(this.#schema, record)
+    return new Entity(this.#schema, record, this.#guards)
   }
 
-  objects (recordset) {
+  objects (recordset, init) {
     const set = recordset.map((record) => this.object(record))
 
+    if (init !== undefined) 
+      for (const id of init)
+        set.unshift(this.init(id))
+
     return new EntitySet(set)
   }