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

package/stage/test/composition.test.js

@@ -1,27 +1,29 @@
-'use strict'
+import { it, mock as mocking } from 'node:test'
+import assert from 'node:assert/strict'
 
-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')
 
 const paths = [generate(), generate()]
 
 it('should be', () => {
-  expect(stage.composition).toBeDefined()
+  assert.notStrictEqual(stage.composition, undefined)
 })
 
 it('should boot composition', async () => {
   await stage.composition(paths)
 
-  expect(mock.boot.composition.mock.calls[0][0]).toStrictEqual(paths)
+  assert.deepStrictEqual(mock.boot.composition.mock.calls[0].arguments[0], paths)
 
-  const composition = await mock.boot.composition.mock.results[0].value
+  const composition = await mock.boot.composition.mock.calls[0].result
 
-  expect(composition.connect).toHaveBeenCalled()
+  assert.ok(composition.connect.mock.callCount() > 0)
 })

package/stage/test/manifest.test.js

@@ -1,17 +1,20 @@
-'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.manifest).toBeDefined()
+  assert.notStrictEqual(stage.manifest, undefined)
 })
 
 it('should boot manifest', async () => {
@@ -19,6 +22,10 @@ it('should boot manifest', async () => {
 
   const manifest = await stage.manifest(path)
 
-  expect(mock.boot.manifest).toHaveBeenCalledWith(path)
-  expect(manifest).toStrictEqual(await mock.boot.manifest.mock.results[0].value)
+  assert.ok(
+    mock.boot.manifest.mock.calls.some(
+      (call) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], path)
+    )
+  )
+  assert.deepStrictEqual(manifest, await mock.boot.manifest.mock.calls[0].result)
 })

package/stage/test/remote.test.js

@@ -1,17 +1,19 @@
-'use strict'
+import { it, mock as mocking } from 'node:test'
+import assert from 'node:assert/strict'
 
-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.remote).toBeDefined()
+  assert.notStrictEqual(stage.remote, undefined)
 })
 
 it('should connect remote', async () => {
@@ -21,12 +23,12 @@ it('should connect remote', async () => {
 
   const remote = await stage.remote(id)
 
-  expect(mock.boot.remote).toHaveBeenCalled()
-  expect(remote).toStrictEqual(await mock.boot.remote.mock.results[0].value)
-  expect(remote.connect).toHaveBeenCalled()
+  assert.ok(mock.boot.remote.mock.callCount() > 0)
+  assert.deepStrictEqual(remote, await mock.boot.remote.mock.calls[0].result)
+  assert.ok(remote.connect.mock.callCount() > 0)
 
-  const locator = mock.boot.remote.mock.calls[0][0]
+  const locator = mock.boot.remote.mock.calls[0].arguments[0]
 
-  expect(locator).toBeDefined()
-  expect(locator).toMatchObject({ name, namespace })
+  assert.notStrictEqual(locator, undefined)
+  assert.partialDeepStrictEqual(locator, { name, namespace })
 })

package/stage/test/shutdown.test.js

@@ -1,24 +1,27 @@
-'use strict'
+import { it, beforeEach, mock as mocking } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
+import * as _boot from './boot.mock.js'
+import * as _state from './state.mock.js'
 
 const mock = {
-  boot: require('./boot.mock'),
-  state: require('./state.mock')
+  boot: _boot,
+  state: _state
 }
 
-jest.mock('@toa.io/boot', () => mock.boot)
-jest.mock('../src/state', () => mock.state)
+mocking.module('@toa.io/boot', { namedExports: mock.boot })
+mocking.module('../src/state', { namedExports: mock.state })
 
-const { state } = require('../src/state')
-const stage = require('../')
+const { state } = await import('../src/state.js')
+const stage = await import('../src/index.js')
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
 })
 
 it('should be', () => {
-  expect(stage.shutdown).toBeDefined()
+  assert.notStrictEqual(stage.shutdown, undefined)
 })
 
 it('should disconnect components', async () => {
@@ -27,7 +30,7 @@ it('should disconnect components', async () => {
 
   await stage.shutdown()
 
-  expect(component.disconnect).toHaveBeenCalled()
+  assert.ok(component.disconnect.mock.callCount() > 0)
 })
 
 it('should disconnect compositions', async () => {
@@ -36,9 +39,9 @@ it('should disconnect compositions', async () => {
   await stage.composition(paths)
   await stage.shutdown()
 
-  const composition = await mock.boot.composition.mock.results[0].value
+  const composition = await mock.boot.composition.mock.calls[0].result
 
-  expect(composition.disconnect).toHaveBeenCalled()
+  assert.ok(composition.disconnect.mock.callCount() > 0)
 })
 
 it('should disconnect remotes', async () => {
@@ -47,11 +50,21 @@ it('should disconnect remotes', async () => {
   const remote = await stage.remote(id)
   await stage.shutdown()
 
-  expect(remote.disconnect).toHaveBeenCalled()
+  assert.ok(remote.disconnect.mock.callCount() > 0)
 })
 
 it('should reset state', async () => {
   await stage.shutdown()
 
-  expect(state.reset).toHaveBeenCalled()
+  assert.ok(state.reset.mock.callCount() > 0)
 })
+
+function resetCalls(target = [assert, mock, stage], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
+}

package/stage/test/state.mock.js

@@ -1,8 +1,7 @@
-'use strict'
+import { mock } from 'node:test'
 
-const original = jest.requireActual('../src/state')
+// this module defines the replacement, so it still sees the real one
+import * as original from '../src/state.js'
 
-const reset = jest.fn(() => original.state.reset())
-const state = { ...original.state, reset }
-
-module.exports = { state }
+const reset = mock.fn(() => original.state.reset())
+export const state = { ...original.state, reset }

package/stage/test/state.test.js

@@ -1,19 +1,20 @@
-'use strict'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { state } = require('../src/state')
+import { state } from '../src/state.js'
 
 it('should be', () => {
-  expect(state).toBeDefined()
+  assert.notStrictEqual(state, undefined)
 })
 
 it('should reset', () => {
-  const component = /** @type {toa.core.Component} */ 1
-  const composition = /** @type {toa.core.Connector} */ 2
-  const remote = /** @type {toa.core.Component} */ 3
+  const component = /** @type {import('@toa.io/core').Component} */ 1
+  const composition = /** @type {import('@toa.io/core').Connector} */ 2
+  const remote = /** @type {import('@toa.io/core').Component} */ 3
 
-  expect(state.components.length).toStrictEqual(0)
-  expect(state.compositions.length).toStrictEqual(0)
-  expect(state.remotes.length).toStrictEqual(0)
+  assert.deepStrictEqual(state.components.length, 0)
+  assert.deepStrictEqual(state.compositions.length, 0)
+  assert.deepStrictEqual(state.remotes.length, 0)
 
   state.components.push(component)
   state.compositions.push(composition)
@@ -21,7 +22,7 @@ it('should reset', () => {
 
   state.reset()
 
-  expect(state.components.length).toStrictEqual(0)
-  expect(state.compositions.length).toStrictEqual(0)
-  expect(state.remotes.length).toStrictEqual(0)
+  assert.deepStrictEqual(state.components.length, 0)
+  assert.deepStrictEqual(state.compositions.length, 0)
+  assert.deepStrictEqual(state.remotes.length, 0)
 })

package/stage/types/index.d.ts

@@ -1,17 +1,30 @@
-import * as _core from '@toa.io/core'
+import type * as _core from '@toa.io/core'
 import * as _norm from '@toa.io/norm/types'
 import * as _composition from '@toa.io/boot/types/composition'
+import type * as _boot from '@toa.io/boot'
 
-export function manifest (path: string): Promise<_norm.Component>
+export function manifest(path: string): Promise<_norm.Component>
 
-export function component (path: string): Promise<_core.Component>
+/** what this process is given about the components it calls */
+export function map(contracts: Record<string, _norm.Contract> | undefined): void
 
-export function composition (paths: string[], options?: _composition.Options): Promise<void>
+export function component(path: string): Promise<_core.Component>
 
-export function compose (paths: string[]): Promise<void>
+export function composition(
+  paths: string[],
+  options?: _composition.Options
+): Promise<void>
 
-export function serve (ref: string): Promise<_core.Component>
+export function compose(paths: string[]): Promise<void>
 
-export function remote (id: string): Promise<_core.Component>
+/** the same components as a process runs them: behind a gate, with the residents beside */
+export function workload(
+  paths: string[],
+  options?: _composition.Options
+): Promise<_boot.Workload>
 
-export function shutdown (): Promise<void>
+export function serve(ref: string): Promise<_core.Component>
+
+export function remote(id: string): Promise<_core.Component>
+
+export function shutdown(): Promise<void>

package/stage/types/state.d.ts

@@ -1,15 +1,14 @@
-import * as _core from '@toa.io/core'
-
-declare namespace toa.stage{
+import type * as _core from '@toa.io/core'
 
+declare namespace toa.stage {
   type State = {
     reset: () => void
     components: _core.Component[]
     compositions: _core.Connector[]
+    workloads: _core.Connector[]
     services: _core.Connector[]
     remotes: _core.Component[]
   }
-
 }
 
 export type State = toa.stage.State

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.env*
+.map.json

package/template/components/hello/manifest.toa.yaml

@@ -0,0 +1,22 @@
+name: hello
+
+operations:
+  greet:
+    input:
+      type: object
+      properties:
+        name: { type: string, maxLength: 64 }
+    output:
+      type: object
+      properties:
+        greeting: { type: string }
+      required: [greeting]
+
+exposition:
+  /:
+    anonymous: true
+    io:output: true
+    GET:
+      endpoint: greet
+      query:
+        parameters: [name]

package/template/components/hello/operations/greet.ts

@@ -0,0 +1,5 @@
+import type { GreetInput } from '../types/index.d.ts'
+
+export async function computation(input: GreetInput) {
+  return { greeting: `Hello, ${input.name ?? 'world'}!` }
+}

package/template/components/notes/manifest.toa.yaml

@@ -0,0 +1,25 @@
+name: notes
+
+entity:
+  properties:
+    text: { type: string, maxLength: 1024 }
+  required: [text]
+
+operations:
+  create:
+    forward: transit
+    query: false
+    input:
+      type: object
+      properties:
+        text: { type: string, maxLength: 1024 }
+      required: [text]
+
+exposition:
+  /:
+    anonymous: true
+    io:output: [id, text]
+    GET: enumerate
+    POST: create
+    /:id:
+      GET: observe

package/template/context.toa.yaml

@@ -0,0 +1,29 @@
+name: {{name}}
+registry: registry.example.com/{{name}}
+
+amqp: amqp://localhost
+mongodb: mongodb://localhost
+stash: redis://localhost
+
+atomicity:
+  redis: redis://localhost
+
+storages:
+  tmp:
+    provider: tmp
+    directory: {{name}}
+
+exposition:
+  authorities:
+    local: localhost:8000
+
+configuration:
+  identity.tokens:
+    keys:
+      - id: key0
+        key: $IDENTITY_TOKENS_ENCRYPTION_KEY0
+
+ingress:
+  hosts: [localhost]
+
+resources: ~

package/template/cucumber.js

@@ -0,0 +1,4 @@
+export default {
+  import: ['features/steps/*.ts'],
+  failFast: true
+}

package/template/docker-compose.yaml

@@ -0,0 +1,62 @@
+# What a local run connects to. `developer` and `secret` are what `toa env --dev` writes.
+name: {{name}}
+volumes:
+  mongo-data:
+  mongo-key:
+services:
+  rabbitmq:
+    image: rabbitmq:4.2.4-management
+    ports:
+      - "5672:5672"
+      - "15672:15672"
+    environment:
+      RABBITMQ_DEFAULT_USER: developer
+      RABBITMQ_DEFAULT_PASS: secret
+    healthcheck:
+      test: rabbitmq-diagnostics -q ping
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  # a replica set of one member: transactions and change streams need one
+  mongodb:
+    image: mongo:8.0.16
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: developer
+      MONGO_INITDB_ROOT_PASSWORD: secret
+    volumes:
+      - mongo-data:/data/db
+      - mongo-key:/etc/mongo-keyfile
+    entrypoint: >
+      bash -c '
+        set -e
+
+        if [ ! -f /etc/mongo-keyfile/keyfile ]; then
+          umask 077
+          openssl rand -base64 756 > /etc/mongo-keyfile/keyfile
+          chown mongodb:mongodb /etc/mongo-keyfile/keyfile
+        fi
+
+        exec docker-entrypoint.sh mongod --replSet rs0 --bind_ip_all --keyFile /etc/mongo-keyfile/keyfile
+      '
+    healthcheck:
+      test: >
+        mongosh "mongodb://developer:secret@localhost:27017/admin?directConnection=true" --quiet --eval '
+          try { rs.status() } catch (e) { rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] }) }
+          if (!db.hello().isWritablePrimary) quit(1)
+        '
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: redis:8.6.1
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: redis-cli ping
+      interval: 5s
+      timeout: 5s
+      retries: 30

package/template/ecosystem.config.js

@@ -0,0 +1,29 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+// the binary of this project's Toa, by its path: pm2 resolves a script through the PATH of the
+// shell that starts it, which has `node_modules/.bin` only under `npm run`
+const toa = join(import.meta.dirname, 'node_modules/.bin/toa')
+
+const components = readdirSync(join(import.meta.dirname, 'components'), {
+  withFileTypes: true
+})
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => join('components', entry.name))
+
+const common = {
+  script: toa,
+  cwd: import.meta.dirname,
+  autorestart: false,
+  watch: false,
+  merge_logs: true,
+  wait_ready: true,
+  listen_timeout: 60_000
+}
+
+export const apps = [
+  // what Toa serves beside an application: its gateway, configuration and introspection
+  { ...common, name: 'sys', args: 'serve configuration exposition introspection' },
+  // the application's components
+  { ...common, name: 'app', args: `compose ${components.join(' ')}` }
+]

package/template/features/hello.feature

@@ -0,0 +1,14 @@
+Feature: Hello
+
+  Scenario: Greeting by name
+    When the request is sent:
+      """
+      GET /hello/?name=Toa HTTP/1.1
+      accept: application/yaml
+      """
+    Then the response is received:
+      """
+      200 OK
+
+      greeting: Hello, Toa!
+      """

package/template/features/notes.feature

@@ -0,0 +1,29 @@
+Feature: Notes
+
+  Scenario: Keeping a note
+    When the request is sent:
+      """
+      POST /notes/ HTTP/1.1
+      content-type: application/yaml
+      accept: application/yaml
+
+      text: Buy milk
+      """
+    Then the response is received:
+      """
+      201 Created
+
+      id: ${{ id }}
+      text: Buy milk
+      """
+    When the request is sent:
+      """
+      GET /notes/${{ id }}/ HTTP/1.1
+      accept: application/yaml
+      """
+    Then the response is received:
+      """
+      200 OK
+
+      text: Buy milk
+      """

package/template/features/steps/application.ts

@@ -0,0 +1,22 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { BeforeAll, AfterAll } from '@cucumber/cucumber'
+import * as stage from '@toa.io/userland/stage'
+
+const root = resolve(import.meta.dirname, '../..')
+const components = resolve(root, 'components')
+
+BeforeAll({ timeout: 60_000 }, async function () {
+  const map = await readFile(resolve(root, '.map.json'), 'utf8')
+  const entries = await readdir(components)
+  const paths = entries.map((entry) => resolve(components, entry))
+
+  stage.map(JSON.parse(map))
+
+  // the components run in this process; what serves them is started with `npm run sys`
+  await stage.compose(paths)
+})
+
+AfterAll(async function () {
+  await stage.shutdown()
+})

package/template/features/steps/http.ts

@@ -0,0 +1,19 @@
+import { Before, When, Then } from '@cucumber/cucumber'
+import { Agent } from '@toa.io/agent'
+
+// what the steps of one scenario share
+export interface World {
+  agent: Agent
+}
+
+Before(function (this: World) {
+  this.agent = new Agent('http://localhost:8000')
+})
+
+When('the request is sent:', async function (this: World, text: string) {
+  await this.agent.request(text)
+})
+
+Then('the response is received:', function (this: World, text: string) {
+  this.agent.responseIncludes(text)
+})

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "postinstall": "toa npm",
+    "dock": "docker compose up -d --wait",
+    "env": "toa types --quiet && toa env --dev && toa map",
+    "start": "pm2 start ecosystem.config.js",
+    "restart": "npm run env && pm2 restart ecosystem.config.js",
+    "stop": "pm2 delete ecosystem.config.js",
+    "sys": "pm2 start ecosystem.config.js --only sys",
+    "features": "cucumber-js",
+    "typecheck": "tsc"
+  },
+  "workspaces": [
+    "components/*"
+  ],
+  "devDependencies": {
+    "@cucumber/cucumber": "13.2.1",
+    "@toa.io/agent": "{{agent}}",
+    "@toa.io/operations": "{{version}}",
+    "@toa.io/runtime": "{{version}}",
+    "@toa.io/userland": "{{version}}",
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "esnext",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true
+  },
+  "include": ["components", "features"]
+}