@toa.io/userland 1.0.0-alpha.33 → 1.0.0-alpha.331

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)
 })

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.331",
+  "type": "module",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
   "author": {
@@ -16,23 +17,28 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./stage": {
+      "types": "./stage/types/index.d.ts",
+      "default": "./stage/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
-    "@toa.io/boot": "1.0.0-alpha.33",
-    "@toa.io/core": "1.0.0-alpha.33",
-    "@toa.io/filesystem": "1.0.0-alpha.33",
-    "@toa.io/generic": "1.0.0-alpha.33",
-    "@toa.io/norm": "1.0.0-alpha.33",
-    "@toa.io/schemas": "1.0.0-alpha.33",
-    "@toa.io/storages.null": "0.22.0",
-    "@toa.io/yaml": "1.0.0-alpha.33",
-    "tap": "16.3.4"
+    "@toa.io/agent": "1.0.0-alpha.330",
+    "@toa.io/boot": "1.0.0-alpha.331",
+    "@toa.io/core": "1.0.0-alpha.330",
+    "@toa.io/generic": "1.0.0-alpha.330",
+    "@toa.io/norm": "1.0.0-alpha.331",
+    "@toa.io/schemas": "1.0.0-alpha.330",
+    "@toa.io/storages.null": "1.0.0-alpha.330"
   },
-  "gitHead": "ef81cea49d8f8b3b248adaba62d4548bbeb39f80"
+  "gitHead": "e7020d160910ca4f0c2ff9040b3cbb4fca8ea41f"
 }

package/readme.md

@@ -1,7 +1,64 @@
 # Toa development kit
 
 - [Stage](./stage): integration tests framework (Node.js)
+- [Template](#template): the application `toa create` writes
 
 See [example](./example).
 
-[^1]: not yet implemented
+## Template
+
+[`toa create <name>`](/runtime/cli/readme.md#create) writes an application into an empty
+directory. Running it takes [Docker](https://docs.docker.com/get-docker/), for the services it
+connects to, and [PM2](https://pm2.keymetrics.io), which keeps its processes:
+
+```shell
+$ npm install -g pm2
+```
+
+```text
+package.json
+tsconfig.json
+docker-compose.yaml
+ecosystem.config.js
+context.toa.yaml
+cucumber.js
+components/
+  hello/
+    manifest.toa.yaml
+    operations/greet.ts
+  notes/
+    manifest.toa.yaml
+features/
+  hello.feature
+  notes.feature
+  steps/
+    application.ts
+    http.ts
+```
+
+| File                  | Is                                                                                                                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context.toa.yaml`    | The Context: the application's name and where its infrastructure is. It is the least a Context holds.                                                          |
+| `docker-compose.yaml` | RabbitMQ, MongoDB as a replica set of one, and Redis, on their conventional ports, with the credentials `toa env --dev` writes.                                |
+| `ecosystem.config.js` | The two processes PM2 keeps: `sys`, what Toa serves beside an application — its gateway, configuration and introspection — and `app`, the components.          |
+| `components/hello`    | A component with code and no state: `greet`, a computation, served at `GET /hello/`.                                                                           |
+| `components/notes`    | A component with state and no code: an entity, `create` forwarded to the operation every component inherits, served at `/notes/`.                              |
+| `features`            | A scenario for each component, sent over HTTP. The steps start the components with the [stage](./stage), in the process of the test; `sys` is running already. |
+| `package.json`        | The packages of Toa at the version that created the application, and the scripts below.                                                                        |
+| `tsconfig.json`       | What `tsc` checks the components and the steps with.                                                                                                           |
+
+| Script              | Runs                                                                                                      |
+| ------------------- | --------------------------------------------------------------------------------------------------------- |
+| `npm install`       | Installs the packages, then `toa npm`, which adds what the declarations require beyond them.              |
+| `npm run dock`      | The services, and waits until they are ready.                                                             |
+| `npm run env`       | `toa types`, `toa env --dev` and `toa map`. Run it again when a manifest or a component's source changes. |
+| `npm run sys`       | `sys` alone: what the scenarios need, since they start the components themselves.                         |
+| `npm run features`  | The scenarios.                                                                                            |
+| `npm start`         | `sys` and `app`: the application, with its gateway on `http://localhost:8000`.                            |
+| `npm run restart`   | `npm run env`, and both processes again.                                                                  |
+| `npm stop`          | Stops and forgets both.                                                                                   |
+| `npm run typecheck` | `tsc`.                                                                                                    |
+
+`pm2 logs` shows what the processes write, and `pm2 ls` whether they run.
+
+The routes are open to anyone, which is right for a first run and for nothing else.

package/stage/package.json

@@ -1,4 +1,5 @@
 {
+  "type": "module",
   "private": true,
   "main": "src/index.js",
   "types": "types/index.d.ts"

package/stage/src/component.js

@@ -1,10 +1,8 @@
-'use strict'
-
-const boot = require('@toa.io/boot')
-const { state } = require('./state')
+import * as boot from '@toa.io/boot'
+import { state } from './state.js'
 
 /** @type {toa.stage.Component} */
-const component = async (path, options) => {
+export const component = async (path, options) => {
   const manifest = await boot.manifest(path, options)
   const component = await boot.component(manifest)
 
@@ -14,5 +12,3 @@ const component = async (path, options) => {
 
   return component
 }
-
-exports.component = component

package/stage/src/composition.js

@@ -1,15 +1,11 @@
-'use strict'
-
-const boot = require('@toa.io/boot')
-const { state } = require('./state')
+import * as boot from '@toa.io/boot'
+import { state } from './state.js'
 
 /** @type {toa.stage.Composition} */
-const composition = async (paths, options) => {
+export const composition = async (paths, options) => {
   const composition = await boot.composition(paths, options)
 
   await composition.connect()
 
   state.compositions.push(composition)
 }
-
-exports.composition = composition

package/stage/src/index.js

@@ -1,16 +1,9 @@
-'use strict'
-
-const { manifest } = require('./manifest')
-const { component } = require('./component')
-const { composition } = require('./composition')
-const { service } = require('./service')
-const { remote } = require('./remote')
-const { shutdown } = require('./shutdown')
-
-exports.manifest = manifest
-exports.component = component
-exports.composition = composition
-exports.compose = composition
-exports.serve = service
-exports.remote = remote
-exports.shutdown = shutdown
+export { manifest } from './manifest.js'
+export { map } from './map.js'
+export { component } from './component.js'
+export { composition, composition as compose } from './composition.js'
+export { workload } from './workload.js'
+export { service as serve } from './service.js'
+export { remote } from './remote.js'
+export { halt, restore } from './quiescence.js'
+export { shutdown } from './shutdown.js'

package/stage/src/manifest.js

@@ -1,12 +1,8 @@
-'use strict'
-
-const boot = require('@toa.io/boot')
+import * as boot from '@toa.io/boot'
 
 /**
  * @type {toa.stage.Manifest}
  */
-const manifest = async (path) => {
+export const manifest = async (path) => {
   return boot.manifest(path)
 }
-
-exports.manifest = manifest

package/stage/src/map.js

@@ -0,0 +1,15 @@
+import * as boot from '@toa.io/boot'
+
+/**
+ * What this process is given about the components it calls: the contract of the version each of
+ * them runs.
+ *
+ * A composition staged here is given none unless a test states one, and a component the map
+ * states nothing of is asked what it provides — which is what a run outside a deployment gets.
+ *
+ * @param {Record<string, import('@toa.io/core').Contract> | undefined} contracts
+ * @returns {void}
+ */
+export const map = (contracts) => {
+  boot.map.use(contracts)
+}

package/stage/src/quiescence.js

@@ -0,0 +1,16 @@
+import { state } from './state.js'
+
+/**
+ * Stops what everything staged does of its own accord, holding every connection open — what a
+ * process does when it is told to go quiet. A component's `stop` run command runs here.
+ */
+export const halt = async () => {
+  for (const composition of state.compositions) await composition.halt()
+  for (const workload of state.workloads) await workload.halt()
+}
+
+/** Starts it again, running the `resume` command. */
+export const restore = async () => {
+  for (const composition of state.compositions) await composition.restore()
+  for (const workload of state.workloads) await workload.restore()
+}

package/stage/src/remote.js

@@ -1,19 +1,17 @@
-'use strict'
+import * as boot from '@toa.io/boot'
+import { Locator } from '@toa.io/core'
 
-const boot = require('@toa.io/boot')
-const { Locator } = require('@toa.io/core')
-
-const { state } = require('./state')
+import { state } from './state.js'
 
 /** @type {toa.stage.Remote} */
-const remote = async (id) => {
+export const remote = async (id) => {
   const segments = id.split('.')
 
   if (segments.length === 1) segments.unshift('default')
 
   const [namespace, name] = segments
   const locator = new Locator(name, namespace)
-  const remote = await boot.remote(locator)
+  const remote = await boot.remote(locator, SOURCE)
 
   await remote.connect()
 
@@ -22,4 +20,9 @@ const remote = async (id) => {
   return remote
 }
 
-exports.remote = remote
+/**
+ * A feature suite calls components the way a service does, so it says so: without this
+ * every call it makes is attributed to an unidentified origin, and a test run leaves
+ * `unknown` on the application's map.
+ */
+const SOURCE = { service: 'features' }

package/stage/src/service.js

@@ -1,14 +1,17 @@
-'use strict'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import * as boot from '@toa.io/boot'
+import { state } from './state.js'
+import { shortcuts } from '@toa.io/norm'
 
-const boot = require('@toa.io/boot')
-const { state } = require('./state')
-const { shortcuts } = require('@toa.io/norm')
+// a shortcut resolves to a package name, which is not a path
+const require = createRequire(import.meta.url)
 
-const service = async (ref) => {
+export const service = async (ref) => {
   const path = shortcuts.resolve(ref)
-  const { Factory } = require(path)
-  const factory = new Factory(boot)
-  const service = factory.service()
+  const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
+  const factory = new Factory(boot.host())
+  const service = await factory.service()
 
   await service.connect()
 
@@ -16,5 +19,3 @@ const service = async (ref) => {
 
   return service
 }
-
-exports.service = service

package/stage/src/shutdown.js

@@ -1,18 +1,28 @@
-'use strict'
+import * as boot from '@toa.io/boot'
 
-const { state } = require('./state')
+import { state } from './state.js'
+import { map } from './map.js'
 
 /** @type {toa.stage.Shutdown} */
-const shutdown = async () => {
+export const shutdown = async () => {
   const components = state.components.map((component) => component.disconnect())
   const compositions = state.compositions.map((composition) => composition.disconnect())
+  const workloads = state.workloads.map((workload) => workload.disconnect())
   const services = state.services.map((service) => service.disconnect())
   const remotes = state.remotes.map((remote) => remote.disconnect())
-  const disconnections = [...components, ...compositions, ...services, ...remotes]
+  const disconnections = [
+    ...components,
+    ...compositions,
+    ...workloads,
+    ...services,
+    ...remotes
+  ]
 
   await Promise.all(disconnections)
 
+  // whatever a test stated is not carried into the next one, and what it composed is gone
+  map(undefined)
+  boot.map.forget()
+
   state.reset()
 }
-
-exports.shutdown = shutdown

package/stage/src/state.js

@@ -1,12 +1,11 @@
-'use strict'
-
-const state = {}
+export const state = {}
 
 const reset = () => {
   Object.assign(state, {
     reset,
     components: [],
     compositions: [],
+    workloads: [],
     remotes: [],
     services: []
   })
@@ -15,4 +14,3 @@ const reset = () => {
 reset()
 
 /** @type {toa.stage.State} */
-exports.state = state

package/stage/src/workload.js

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import * as boot from '@toa.io/boot'
+import { Connector } from '@toa.io/core'
+import { shortcuts } from '@toa.io/norm'
+import { state } from './state.js'
+
+// a shortcut resolves to a package name, which is not a path
+const require = createRequire(import.meta.url)
+
+/** The services, made against this process rather than against no process. */
+const create = async (references, workload) => {
+  const services = []
+
+  for (const reference of references) {
+    const path = shortcuts.resolve(reference)
+    const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
+    const service = await new Factory(boot.host(workload)).service()
+
+    if (service !== null) services.push(service)
+  }
+
+  return services
+}
+
+/**
+ * A process, as `toa compose` runs one: the composition behind a gate, whatever services it
+ * was told to run beside it, and whatever the extensions keep in a process — the readiness
+ * probe, the ear a halt arrives at.
+ *
+ * `composition` is the other way to boot the same components, and the difference is the point
+ * of this one: what belongs to a process is here and not there. So is what a halt takes,
+ * which is why a service that has to be halted is run from here rather than staged apart.
+ */
+export const workload = async (paths, options, services = []) => {
+  const workload = new boot.Workload(async (workload) => {
+    const composition = workload.gate(async () => await boot.composition(paths, options))
+
+    if (services.length === 0) return composition
+
+    const root = new Connector()
+
+    root.depends([composition, ...(await create(services, workload))])
+
+    return root
+  })
+
+  await workload.connect()
+
+  state.workloads.push(workload)
+
+  return workload
+}

package/stage/test/boot.mock.js

@@ -1,16 +1,15 @@
-'use strict'
+import { mock } from 'node:test'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
 
 const connector = () => ({
-  connect: jest.fn(),
-  disconnect: jest.fn(),
-  link: jest.fn()
+  connect: mock.fn(),
+  disconnect: mock.fn(),
+  link: mock.fn()
 })
 
-const manifest = jest.fn(async () => generate())
-const component = jest.fn(async () => connector())
-const composition = jest.fn(async () => connector())
-const remote = jest.fn(async () => connector())
-
-module.exports = { manifest, component, composition, remote }
+export const map = { use: mock.fn(), forget: mock.fn() }
+export const manifest = mock.fn(async () => generate())
+export const component = mock.fn(async () => connector())
+export const composition = mock.fn(async () => connector())
+export const remote = mock.fn(async () => connector())

package/stage/test/component.test.js

@@ -1,25 +1,35 @@
-'use strict'
+import { it, mock as mocking } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
+import * as _boot from './boot.mock.js'
 
 const mock = {
-  boot: require('./boot.mock')
+  boot: _boot
 }
 
-jest.mock('@toa.io/boot', () => mock.boot)
+mocking.module('@toa.io/boot', { namedExports: mock.boot })
 
-const stage = require('../')
+const stage = await import('../src/index.js')
 
 it('should be', () => {
-  expect(stage.component).toBeDefined()
+  assert.notStrictEqual(stage.component, undefined)
 })
 
 it('should boot component', async () => {
   const path = generate()
   const component = await stage.component(path)
 
-  expect(mock.boot.manifest.mock.calls[0][0]).toStrictEqual(path)
-  expect(mock.boot.component).toHaveBeenCalledWith(await mock.boot.manifest.mock.results[0].value)
-  expect(component).toStrictEqual(await mock.boot.component.mock.results[0].value)
-  expect(component.connect).toHaveBeenCalled()
+  assert.deepStrictEqual(mock.boot.manifest.mock.calls[0].arguments[0], path)
+  const manifest = await mock.boot.manifest.mock.calls[0].result
+
+  assert.ok(
+    mock.boot.component.mock.calls.some(
+      (call) =>
+        call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], manifest)
+    )
+  )
+  assert.deepStrictEqual(component, await mock.boot.component.mock.calls[0].result)
+  assert.ok(component.connect.mock.callCount() > 0)
 })