@toa.io/core 1.0.0-alpha.28 → 1.0.0-alpha.282

package/src/contract/reply.js

@@ -1,25 +1,46 @@
-'use strict'
+import * as schemas from './schemas/index.js'
+import { Contract } from './contract.js'
+import { ResponseContractException } from '../exceptions.js'
 
-const schemas = require('./schemas')
-const { Conditions } = require('./conditions')
-const { ResponseContractException } = require('../exceptions')
-
-class Reply extends Conditions {
+export 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) {
+      /*
+       * A reply carries more than the operation declares — `_version` and the rest of the
+       * record's own fields — so what it is validated against is the declaration relaxed.
+       * On a copy: the declaration itself is what a component publishes when asked to
+       * explain, and relaxing that would publish a contract nobody wrote.
+       */
+      output = structuredClone(output)
+
+      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
   }
 }
-
-exports.Reply = Reply

package/src/contract/request.js

@@ -1,10 +1,19 @@
-'use strict'
+import * as schemas from './schemas/index.js'
+import { RequestContractException } from '../exceptions.js'
+import { Contract } from './contract.js'
 
-const schemas = require('./schemas')
-const { RequestContractException } = require('../exceptions')
-const { Conditions } = require('./conditions')
+export 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 +22,11 @@ class Request extends Conditions {
   static schema (definition, entity) {
     const schema = {
       type: 'object',
-      properties: { authentic: { type: 'boolean' } },
+      properties: {
+        authentic: { type: 'boolean' },
+        task: { type: 'boolean' },
+        source: structuredClone(schemas.source)
+      },
       additionalProperties: true
     }
 
@@ -22,9 +35,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
@@ -63,5 +75,3 @@ class Request extends Conditions {
     return schema
   }
 }
-
-exports.Request = Request

package/src/contract/schemas/index.js

@@ -1,7 +1,11 @@
-'use strict'
+import { resolve } from 'path'
+import { readFileSync } from 'node:fs'
+import { yaml } from '@toa.io/generic'
 
-const { resolve } = require('path')
-const { load } = require('@toa.io/yaml')
+export const query = read(resolve(import.meta.dirname, './query.yaml'))
+export const error = read(resolve(import.meta.dirname, './error.yaml'))
+export const source = read(resolve(import.meta.dirname, './source.yaml'))
 
-exports.query = load.sync(resolve(__dirname, './query.yaml'))
-exports.error = load.sync(resolve(__dirname, './error.yaml'))
+function read (path) {
+  return yaml.load(readFileSync(path, 'utf8'))
+}

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/contract/schemas/source.yaml

@@ -0,0 +1,23 @@
+# Origin of a call, see toa.core.Source.
+# Deliberately permissive on required properties: the contract throws on a mismatch,
+# and a strict union would turn a partially stamped source into a failed business call.
+# `additionalProperties: false` combined with `removeAdditional` is what matters here —
+# it strips whatever a peer puts in, bounding the cardinality of the resulting map.
+type: object
+properties:
+  namespace:
+    type: string
+    maxLength: 64
+  component:
+    type: string
+    maxLength: 64
+  operation:
+    type: string
+    maxLength: 64
+  event:
+    type: string
+    maxLength: 64
+  service:
+    type: string
+    maxLength: 64
+additionalProperties: false

package/src/discovery.js

@@ -1,9 +1,7 @@
-'use strict'
+import { console } from 'openspan'
+import { Connector } from './connector.js'
 
-const { console } = require('@toa.io/console')
-const { Connector } = require('./connector')
-
-class Discovery extends Connector {
+export class Discovery extends Connector {
   #lookup
   #lookups
 
@@ -25,20 +23,24 @@ class Discovery extends Connector {
       this.depends(this.#lookups[id])
     }
 
-    console.debug(`Sending lookup request to '${id}'`)
+    const since = Date.now()
+
+    // 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)
 
-    const warning = () => console.warn(`Waiting for lookup response from '${id}'...`)
-    const timeout = setTimeout(warning, TIMEOUT)
+      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
-
-exports.Discovery = Discovery
+const INTERVAL = 5000

package/src/effect.js

@@ -0,0 +1,15 @@
+import { Observation } from './observation.js'
+
+export 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()
+  }
+
+}

package/src/emission.js

@@ -1,8 +1,6 @@
-'use strict'
+import { Connector } from './connector.js'
 
-const { Connector } = require('./connector')
-
-class Emission extends Connector {
+export class Emission extends Connector {
   #events
 
   constructor (events) {
@@ -19,5 +17,3 @@ class Emission extends Connector {
     await Promise.all(emission)
   }
 }
-
-exports.Emission = Emission

package/src/entities/changeset.js

@@ -1,13 +1,6 @@
-'use strict'
+import { EntityContractException } from '../exceptions.js'
 
-const {
-  merge,
-  overwrite,
-  newid
-} = require('@toa.io/generic')
-const { EntityContractException } = require('../exceptions')
-
-class Changeset {
+export class Changeset {
   /** @type {toa.core.Query} */
   query
 
@@ -18,7 +11,7 @@ class Changeset {
     this.query = query
 
     this.#schema = schema
-    this.#state = schema.system()
+    this.#state = {}
   }
 
   get () {
@@ -26,10 +19,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
@@ -39,5 +34,3 @@ class Changeset {
     return this.#state
   }
 }
-
-exports.Changeset = Changeset

package/src/entities/entity.js

@@ -1,24 +1,34 @@
-'use strict'
+import { EntityContractException, EntityGuardException } from '../exceptions.js'
+import { newid } from './newid.js'
 
-const {
-  difference,
-  newid
-} = require('@toa.io/generic')
-
-const { EntityContractException } = require('../exceptions')
-
-class Entity {
+export class Entity {
+  deleted = false
   #schema
+  #guards
   #origin = null
   #state
+  #mutable = true
 
-  constructor (schema, argument) {
+  /**
+   * @param {boolean} [mutable] whether the entity may be modified and committed
+   */
+  constructor (schema, argument, guards, mutable = true) {
     this.#schema = schema
+    this.#guards = guards
 
     if (typeof argument === 'object') {
-      const object = structuredClone(argument)
-      this.set(object)
-      this.#origin = argument
+      /*
+       * The origin is the pre-image a commit diffs the new state against. An operation
+       * that cannot commit has nothing to diff, so it takes the record as it came from
+       * the storage instead of paying for a deep copy of every record it read.
+       */
+      this.#mutable = mutable
+
+      if (mutable) {
+        this.#set(structuredClone(argument))
+        this.#origin = argument
+      } else
+        this.#set(argument)
     } else {
       const id = argument === undefined ? newid() : argument
       this.#init(id)
@@ -29,37 +39,75 @@ class Entity {
     return this.#state
   }
 
-  set (value) {
-    const error = this.#schema.fit(value)
+  set (value, optional = false) {
+    if (!this.#mutable)
+      throw new Error('Entity acquired by a read-only operation cannot be modified')
+
+    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.#revive(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)
+      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, 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)
     }
+  }
 
-    this.#set(value)
+  // deletion is only expressed as a new _deleted timestamp,
+  // so committing over a tombstone without touching it means revival
+  #revive (value) {
+    if (this.#origin?._deleted == null || value._deleted !== this.#origin._deleted)
+      return
+
+    value._deleted = null
+    this.deleted = false
   }
 
   #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()
@@ -69,5 +117,3 @@ class Entity {
     this.#state = value
   }
 }
-
-exports.Entity = Entity

package/src/entities/factory.js

@@ -1,26 +1,35 @@
-'use strict'
+import { newid } from './newid.js'
+import { Entity } from './entity.js'
+import { EntitySet } from './set.js'
+import { Changeset } from './changeset.js'
 
-const { Entity } = require('./entity')
-const { EntitySet } = require('./set')
-const { Changeset } = require('./changeset')
-
-class Factory {
+export 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)
+  object (record, mutable = true) {
+    return new Entity(this.#schema, record, this.#guards, mutable)
   }
 
-  objects (recordset) {
-    const set = recordset.map((record) => this.object(record))
+  objects (recordset, init, mutable = true) {
+    const set = recordset.map((record) => this.object(record, mutable))
+
+    if (init !== undefined) 
+      for (const id of init)
+        set.unshift(this.init(id))
 
     return new EntitySet(set)
   }
@@ -29,5 +38,3 @@ class Factory {
     return new Changeset(this.#schema, query)
   }
 }
-
-exports.Factory = Factory

package/src/entities/index.js

@@ -1,5 +1 @@
-'use strict'
-
-const { Factory } = require('./factory')
-
-exports.Factory = Factory
+export { Factory } from './factory.js'

package/src/entities/newid.js

@@ -0,0 +1,9 @@
+import * as uuid from 'uuid'
+
+export function newid () {
+  const buf = Buffer.alloc(16)
+
+  uuid.v7(undefined, buf)
+
+  return buf.toString('hex')
+}

package/src/entities/set.js

@@ -1,6 +1,6 @@
-'use strict'
+import { SystemException } from '../exceptions.js'
 
-class EntitySet {
+export class EntitySet {
   #set
 
   constructor (set) {
@@ -10,6 +10,15 @@ class EntitySet {
   get () {
     return this.#set.map((entity) => entity.get())
   }
-}
 
-exports.EntitySet = EntitySet
+  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))
+  }
+}

package/src/event.js

@@ -1,22 +1,25 @@
-'use strict'
-
-const { Connector } = require('./connector')
+import { console, current, encode } from 'openspan'
+import { Connector } from './connector.js'
 
 /**
  * @implements {toa.core.Event}
  */
-class Event extends Connector {
+export class Event extends Connector {
   /** @type {toa.core.bindings.Emitter} */
   #emitter
   #bridge
   #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,9 +35,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)
+      })
     }
   }
 }
-
-exports.Event = Event