@toa.io/userland 1.0.0-alpha.31 → 1.0.0-alpha.310

package/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.310](https://github.com/toa-io/toa/compare/v1.0.0-alpha.309...v1.0.0-alpha.310) (2026-09-16)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.309](https://github.com/toa-io/toa/compare/v1.0.0-alpha.308...v1.0.0-alpha.309) (2026-09-16)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.308](https://github.com/toa-io/toa/compare/v1.0.0-alpha.307...v1.0.0-alpha.308) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.307](https://github.com/toa-io/toa/compare/v1.0.0-alpha.306...v1.0.0-alpha.307) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.306](https://github.com/toa-io/toa/compare/v1.0.0-alpha.305...v1.0.0-alpha.306) (2026-09-14)
+
+* feat(boot)!: a process can be halted and come back ([7196fa5](https://github.com/toa-io/toa/commit/7196fa51a9c882e84c3767a4fdd329fd2df319f5))
+
+### BREAKING CHANGES
+
+* `Host` gains `gate` and `halt`, and `Factory.service` may answer a gate. An
+  extension that gates nothing keeps its connections through a halt.
+
+
+# [1.0.0-alpha.305](https://github.com/toa-io/toa/compare/v1.0.0-alpha.304...v1.0.0-alpha.305) (2026-09-13)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.304](https://github.com/toa-io/toa/compare/v1.0.0-alpha.303...v1.0.0-alpha.304) (2026-09-13)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.303](https://github.com/toa-io/toa/compare/v1.0.0-alpha.302...v1.0.0-alpha.303) (2026-09-12)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.302](https://github.com/toa-io/toa/compare/v1.0.0-alpha.301...v1.0.0-alpha.302) (2026-09-11)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.301](https://github.com/toa-io/toa/compare/v1.0.0-alpha.300...v1.0.0-alpha.301) (2026-09-11)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.300](https://github.com/toa-io/toa/compare/v1.0.0-alpha.299...v1.0.0-alpha.300) (2026-09-11)
+
+* feat(boot)!: a process is a thing, and an extension may keep something in one ([528d6cd](https://github.com/toa-io/toa/commit/528d6cdd307b45a6c30b6a184d7e06b3328cecf8))
+
+### BREAKING CHANGES
+
+* a composition booted directly has no readiness probe. Readiness is
+  the process's, and a composition is not a process. `stage.workload` boots one where a
+  suite needs it.
+
+
+# [1.0.0-alpha.299](https://github.com/toa-io/toa/compare/v1.0.0-alpha.298...v1.0.0-alpha.299) (2026-09-10)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.298](https://github.com/toa-io/toa/compare/v1.0.0-alpha.297...v1.0.0-alpha.298) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.297](https://github.com/toa-io/toa/compare/v1.0.0-alpha.296...v1.0.0-alpha.297) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.296](https://github.com/toa-io/toa/compare/v1.0.0-alpha.295...v1.0.0-alpha.296) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.295](https://github.com/toa-io/toa/compare/v1.0.0-alpha.294...v1.0.0-alpha.295) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.294](https://github.com/toa-io/toa/compare/v1.0.0-alpha.293...v1.0.0-alpha.294) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.293](https://github.com/toa-io/toa/compare/v1.0.0-alpha.292...v1.0.0-alpha.293) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/userland
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/userland

package/example/components/echo/manifest.toa.yaml

@@ -2,14 +2,24 @@ name: echo
 
 operations:
   signal:
-    output: string
+    output:
+      type: string
   get:
-    output: string
+    output:
+      type: string
   resolve:
-    input: string
-    output: string
+    input:
+      type: string
+    output:
+      type: string
 
 configuration:
-  signal: quack
+  schema:
+    type: object
+    properties:
+      signal:
+        type: string
+  defaults:
+    signal: quack
 
 state: ~

package/example/components/echo/operations/get.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (_, context) {
+export async function computation(_, context) {
   return context.state.value
 }
-
-exports.computation = computation

package/example/components/echo/operations/resolve.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (key, context) {
+export async function computation(key, context) {
   return context.state.values.get(key)
 }
-
-exports.computation = computation

package/example/components/echo/operations/signal.js

@@ -1,15 +1,11 @@
-'use strict'
-
-class Computation {
+export class Computation {
   #context
 
-  async mount (context) {
+  async mount(context) {
     this.#context = context
   }
 
-  async execute () {
+  async execute() {
     return this.#context.configuration.signal
   }
 }
-
-exports.Computation = Computation

package/example/components/math.calculations/manifest.toa.yaml

@@ -4,11 +4,24 @@ namespace: math
 operations:
   add:
     input:
-      a: number
-      b: number
-    output: number
+      properties:
+        a:
+          type: number
+        b:
+          type: number
+      type: object
+    output:
+      type: number
   increment:
     input:
-      value: number
-      times: 1
-    output: number
+      properties:
+        value:
+          type: number
+        times:
+          type: number
+      type: object
+      required:
+        - value
+        - times
+    output:
+      type: number

package/example/components/math.calculations/operations/add.js

@@ -1,7 +1,3 @@
-'use strict'
-
-async function computation (input) {
+export async function computation(input) {
   return input.a + input.b
 }
-
-exports.computation = computation

package/example/components/math.calculations/operations/increment.js

@@ -1,6 +1,4 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   let value = input.value
 
   for (let i = 0; i < input.times; i++) {
@@ -9,5 +7,3 @@ async function computation (input, context) {
 
   return value
 }
-
-exports.computation = computation

package/example/components/math.proxy/manifest.toa.yaml

@@ -4,6 +4,11 @@ namespace: math
 operations:
   add:
     input:
-      a: number
-      b: number
-    output: number
+      properties:
+        a:
+          type: number
+        b:
+          type: number
+      type: object
+    output:
+      type: number

package/example/components/math.proxy/operations/add.js

@@ -1,10 +1,6 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   const request = { input }
 
   // noinspection JSUnresolvedVariable
   return context.remote.math.calculations.add(request)
 }
-
-exports.computation = computation

package/example/components/tea.pots/manifest.toa.yaml

@@ -3,21 +3,35 @@ namespace: tea
 
 entity:
   storage: mongodb
-  schema:
-    material*: [ glass, ceramic, steel ]
-    volume: number
+  properties:
+    volume: &volume
+      type: number
+    booked: &booked
+      type: boolean
+    material: &material
+      type: string
+      enum:
+        - glass
+        - ceramic
+        - steel
+  required:
+    - material
+  blank:
     booked: false
 
 operations:
   transit:
     concurrency: none
     input:
-      material: .
-      volume: .
-      booked: .
+      properties:
+        material: *material
+        volume: *volume
+        booked: *booked
+      type: object
   same:
-    input: .material
-    output: array
+    input: *material
+    output:
+      type: array
 
 receivers:
   store.orders.created:
@@ -25,4 +39,10 @@ receivers:
     binding: amqp # avoid discovery
 
 configuration:
-  step: 0.5
+  schema:
+    type: object
+    properties:
+      step:
+        type: number
+  defaults:
+    step: 0.5

package/example/components/tea.pots/operations/same.js

@@ -1,6 +1,4 @@
-'use strict'
-
-async function computation (input, context) {
+export async function computation(input, context) {
   const criteria = `material==${input}`
   const query = { criteria, limit }
 
@@ -9,5 +7,3 @@ async function computation (input, context) {
 }
 
 const limit = 10
-
-exports.computation = computation

package/example/components/tea.pots/receivers/store.orders.created.js

@@ -1,8 +1,4 @@
-'use strict'
-
-const request = async (payload) => ({
+export const request = async (payload) => ({
   input: { booked: true },
   query: { id: payload.pot }
 })
-
-exports.request = request

package/example/components/web/manifest.toa.yaml

@@ -2,7 +2,5 @@ name: web
 
 operations:
   get:
-    output: object
-
-origins:
-  dev: http://api.example.com
+    output:
+      type: object

package/example/components/web/operations/get.js

@@ -1,15 +1,10 @@
-'use strict'
-
-async function computation (_, context) {
-  const response = await context.http.dev.path.to.resource.get()
+export async function computation(_, context) {
+  const response = await context.fetch('http://api.example.com/path/to/resource')
   const type = response.headers.get('content-type')
 
-  if (type !== 'application/json')
-    return ERR_UNSUPPORTED_MEDIA_TYPE
+  if (type !== 'application/json') return ERR_UNSUPPORTED_MEDIA_TYPE
 
   return await response.json()
 }
 
 const ERR_UNSUPPORTED_MEDIA_TYPE = new Error('UNSUPPORTED_MEDIA_TYPE')
-
-exports.computation = computation

package/example/context.toa.yaml

@@ -1,10 +1,5 @@
 name: examples
-packages: components/*
 registry: example
 
-amqp: amqp://localhost
-mongodb: mongodb://localhost
-
-origins:
-  default.web:
-    dev: http://localhost
+amqp: amqp://localhost:31010
+mongodb: mongodb://localhost:31020

package/example/stage/call.test.js

@@ -1,16 +1,21 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const { exceptions: { RequestContractException } } = require('@toa.io/core')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import { exceptions } from '@toa.io/core'
+import * as stage from '@toa.io/userland/stage'
 
-const root = resolve(__dirname, '../components')
+const { RequestContractException } = exceptions
+
+const root = resolve(import.meta.dirname, '../components')
 
 let echo
 let math
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_DEFAULT_ECHO = '{}'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
 
   const paths = ['echo', 'math.calculations'].map((rel) => resolve(root, rel))
 
@@ -20,7 +25,7 @@ beforeAll(async () => {
   math = await stage.remote('math.calculations')
 })
 
-afterAll(async () => {
+after(async () => {
   await stage.shutdown()
 
   delete process.env.TOA_DEV
@@ -29,13 +34,15 @@ afterAll(async () => {
 it('should call endpoint', async () => {
   const reply = await echo.invoke('signal', {})
 
-  expect(reply).toStrictEqual('quack')
+  assert.deepStrictEqual(reply, 'quack')
 })
 
 it('should throw on invalid input', async () => {
   const a = 'not a number'
   const b = 'neither'
 
-  await expect(math.invoke('add', { input: { a, b } }))
-    .rejects.toBeInstanceOf(RequestContractException)
+  await assert.rejects(math.invoke('add', { input: { a, b } }), (error) => {
+    assert.ok(error instanceof RequestContractException)
+    return true
+  })
 })

package/example/stage/events.test.js

@@ -1,51 +1,98 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import * as boot from '@toa.io/boot'
+import { Connector, Locator } from '@toa.io/core'
+import { timeout } from '@toa.io/generic'
+import * as stage from '@toa.io/userland/stage'
 
-const binding = stage.binding.binding
-const root = resolve(__dirname, '../components')
+const root = resolve(import.meta.dirname, '../components')
 
 let remote
+let emitter
+let consumer
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
+
+  // the outbox pumps on a tick; at the default five seconds a test would end before it ran
+  process.env.TOA_OUTBOX_INTERVAL = '100'
 
   const path = resolve(root, 'tea.pots')
 
   await stage.composition([path])
 
   remote = await stage.remote('tea.pots')
+
+  // what `store.orders` would emit, sent the way it would send it
+  emitter = await boot.bindings.emit(AMQP, new Locator('orders', 'store'), 'created')
+
+  await emitter.connect()
 })
 
-afterAll(async () => {
+after(async () => {
+  await consumer?.disconnect()
+  await emitter.disconnect()
   await stage.shutdown()
 
   delete process.env.TOA_DEV
+  delete process.env.TOA_CONFIGURATION_TEA_POTS
+  delete process.env.TOA_OUTBOX_INTERVAL
 })
 
 it('should receive event', async () => {
   const created = await remote.invoke('transit', { input: { material: 'glass' } })
   const id = created.id
-  const payload = { pot: id }
-  const message = { payload }
   const request = { query: { id } }
 
-  await binding.emit('store.orders.created', message)
+  await emitter.emit({ payload: { pot: id } })
+
+  // the receiver books the pot on delivery, which is asynchronous
+  const deadline = Date.now() + 5000
 
-  const reply = await remote.invoke('observe', request)
+  let reply
 
-  expect(reply.booked).toStrictEqual(true)
+  do {
+    await timeout(50)
+
+    reply = await remote.invoke('observe', request)
+  } while (reply.booked !== true && Date.now() < deadline)
+
+  assert.deepStrictEqual(reply.booked, true)
 })
 
 it('should emit event', async () => {
-  expect.assertions(1)
-
   const material = 'steel'
 
-  await binding.subscribe('tea.pots.created', (pot) => {
-    expect(pot.payload.material).toStrictEqual(material)
+  const received = new Promise((resolve) => {
+    consumer = boot.receive('tea.pots.created', new Subscriber(resolve))
   })
 
+  consumer = await consumer
+
+  await consumer.connect()
   await remote.invoke('transit', { input: { material } })
+
+  const payload = await received
+
+  assert.deepStrictEqual(payload.material, material)
 })
+
+/** What the event consumer hands deliveries to. */
+class Subscriber extends Connector {
+  #handler
+
+  constructor(handler) {
+    super()
+
+    this.#handler = handler
+  }
+
+  async receive(message) {
+    this.#handler(message.payload)
+  }
+}
+
+const AMQP = '@toa.io/bindings.amqp'

package/example/stage/invoke.test.js

@@ -1,22 +1,25 @@
-'use strict'
+import { it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { resolve } = require('node:path')
-const stage = require('@toa.io/userland/stage')
+import { resolve } from 'node:path'
+import * as stage from '@toa.io/userland/stage'
 
-const root = resolve(__dirname, '../components')
+const root = resolve(import.meta.dirname, '../components')
 
-/** @type {toa.core.Component} */
+/** @type {import('@toa.io/core').Component} */
 let component
 
-beforeAll(async () => {
+before(async () => {
   process.env.TOA_DEV = '1'
+  process.env.TOA_CONFIGURATION_DEFAULT_ECHO = '{}'
+  process.env.TOA_CONFIGURATION_TEA_POTS = '{}'
 
   const path = resolve(root, 'math.calculations')
 
   component = await stage.component(path)
 })
 
-afterAll(async () => {
+after(async () => {
   await stage.shutdown()
 
   delete process.env.TOA_DEV
@@ -28,6 +31,6 @@ it('should invoke', async () => {
 
   const reply = await component.invoke('add', { input: { a, b } })
 
-  expect(reply.exception).toBeUndefined()
-  expect(reply.output).toStrictEqual(a + b)
+  assert.strictEqual(reply.exception, undefined)
+  assert.deepStrictEqual(reply.output, a + b)
 })