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

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,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,24 +1,36 @@
 'use strict'
 
-const {
-  difference,
-  newid
-} = require('@toa.io/generic')
-
-const { EntityContractException } = require('../exceptions')
+const { EntityContractException, EntityGuardException } = require('../exceptions')
+const { newid } = require('./newid')
 
 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 +41,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)
 
-    if (error !== null) throw new EntityContractException(error)
+    const error = optional ? this.#schema.fitOptional(value) : this.#schema.fit(value)
 
+    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()

package/src/entities/factory.js

@@ -1,26 +1,37 @@
 '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)
+  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)
   }

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,11 +5,13 @@ 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')
 const { Locator } = require('./locator')
 const { Observation } = require('./observation')
+const { Outbox } = require('./outbox')
 const { Operation } = require('./operation')
 const { Query } = require('./query')
 const { Receiver } = require('./receiver')
@@ -19,6 +21,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,11 +36,13 @@ exports.Composition = Composition
 exports.Connector = Connector
 exports.Context = Context
 exports.Discovery = Discovery
+exports.Effect = Effect
 exports.Emission = Emission
 exports.Event = Event
 exports.Exposition = Exposition
 exports.Locator = Locator
 exports.Observation = Observation
+exports.Outbox = Outbox
 exports.Operation = Operation
 exports.Query = Query
 exports.Receiver = Receiver
@@ -45,3 +51,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,11 +1,21 @@
 '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
 
+  /**
+   * Whether what this operation acquires may be modified and committed. Only a
+   * transition commits, and only a commit needs the pre-image an entity keeps
+   * to diff the new state against.
+   *
+   * @protected
+   */
+  mutable = false
+
   #cascade
   #contracts
   #query
@@ -26,8 +36,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 +64,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,7 +89,10 @@ class Operation extends Connector {
   async commit () {}
 
   async query (query) {
-    return this.scope[this.#scope](query)
+    if (query === undefined)
+      throw new RequestContractException('Request query is required')
+
+    return this.scope[this.#scope](query, this.mutable)
   }
 }
 

package/src/outbox/index.js

@@ -0,0 +1,6 @@
+'use strict'
+
+const { Outbox, LANES } = require('./outbox')
+
+exports.Outbox = Outbox
+exports.LANES = LANES