@toa.io/userland 0.2.1-dev.3

package/samples/test/stage.mock.js

@@ -0,0 +1,34 @@
+// noinspection JSCheckFunctionSignatures
+
+'use strict'
+
+const { generate } = require('randomstring')
+const { Locator } = require('@toa.io/core')
+
+const locator = () => {
+  const name = generate()
+  const namespace = generate()
+
+  return new Locator(name, namespace)
+}
+
+// stage
+const manifest = jest.fn(async (path) => ({ path, locator: locator() }))
+const composition = jest.fn()
+const shutdown = jest.fn()
+
+const remote = jest.fn(async (id) => {
+  const [namespace, name] = id.split('.')
+  const locator = new Locator(name, namespace)
+  const invoke = jest.fn(async (operation, request) => request.reply)
+  const disconnect = jest.fn(async () => undefined)
+
+  return { locator, invoke, disconnect }
+})
+
+const emit = jest.fn()
+const binding = { binding: { emit } }
+
+const stage = { manifest, composition, remote, shutdown, binding }
+
+exports.stage = stage

package/samples/test/suite.components.test.js

@@ -0,0 +1,85 @@
+'use strict'
+
+const { resolve } = require('node:path')
+const yaml = require('@toa.io/yaml')
+
+const { components } = require('../src/suite')
+
+it('should be', () => {
+  expect(components).toBeDefined()
+})
+
+const root = resolve(__dirname, 'context/components/ok')
+const paths = [root]
+const component = 'dummies.dummy'
+
+/** @type {toa.samples.Suite} */
+let suite
+
+beforeAll(async () => {
+  suite = await components(paths)
+})
+
+it('should return object', () => {
+  expect(typeof suite).toStrictEqual('object')
+})
+
+it('should set title', async () => {
+  expect(suite.title).toStrictEqual('Component samples')
+})
+
+it('should define suite as autonomous', async () => {
+  expect(suite.autonomous).toStrictEqual(true)
+})
+
+it('should load component samples', async () => {
+  const expected = await operations()
+
+  expect(Object.keys(suite.operations)).toStrictEqual([component])
+
+  const set = suite.operations[component]
+
+  expect(Object.keys(set)).toStrictEqual(['do', 'undo'])
+
+  expect(set.do).toStrictEqual(expected.do)
+  expect(set.undo).toStrictEqual(expected.undo)
+})
+
+it('should load message samples', async () => {
+  const expected = await messages()
+
+  expect(suite.messages).toStrictEqual(expected)
+})
+
+/**
+ * @returns {Promise<toa.samples.operations.Set>}
+ */
+const operations = async () => {
+  const path = resolve(root, 'samples')
+
+  /** @type {toa.samples.Operation[]} */
+  const do1 = (await yaml.load.all(resolve(path, 'do.yaml')))
+
+  /** @type {toa.samples.Operation[]} */
+  const do2 = (await yaml.load.all(resolve(path, 'dummies.dummy.do.yaml')))
+
+  /** @type {toa.samples.Operation[]} */
+  const undo = (await yaml.load.all(resolve(path, 'dummies.dummy.undo.yaml')))
+
+  return {
+    do: [...do1, ...do2], undo
+  }
+}
+
+/**
+ *
+ * @returns {Promise<toa.samples.messages.Set>}
+ */
+const messages = async () => {
+  const label = 'somewhere.something.happened'
+  const file = resolve(root, 'samples/messages', label + '.yaml')
+  const declarations = await yaml.load.all(file)
+  const messages = declarations.map((sample) => ({ component, ...sample }))
+
+  return { [label]: messages }
+}

package/samples/test/suite.context.test.js

@@ -0,0 +1,79 @@
+'use strict'
+
+const { join } = require('node:path')
+const yaml = require('@toa.io/yaml')
+
+const { context } = require('../src/suite')
+
+it('should be', async () => {
+  expect(context).toBeDefined()
+})
+
+const root = join(__dirname, 'context')
+
+/** @type {toa.samples.Suite} */
+let suite
+
+beforeAll(async () => {
+  suite = await context(root)
+})
+
+it('should return object', async () => {
+  expect(typeof suite).toStrictEqual('object')
+})
+
+it('should set title', async () => {
+  expect(suite.title).toStrictEqual('Integration samples')
+})
+
+it('should define suite as non-autonomous', async () => {
+  expect(suite.autonomous).toStrictEqual(false)
+})
+
+it('should load operation samples', async () => {
+  const expected = await operations()
+
+  expect(suite.operations).toStrictEqual(expected)
+})
+
+it('should load message samples', async () => {
+  const expected = await messages()
+
+  expect(suite.messages).toStrictEqual(expected)
+})
+
+/**
+ * @returns {Promise<toa.samples.suite.Operations>}
+ */
+const operations = async () => {
+  const path = join(root, 'samples')
+  const component = 'dummies.dummy'
+  const endpoints = ['transit', 'observe']
+
+  /** @type {toa.samples.suite.Operations} */
+  const operations = {}
+
+  /** @type {toa.samples.operations.Set} */
+  const set = operations[component] = {}
+
+  for (const endpoint of endpoints) {
+    const filename = component + '.' + endpoint + '.yaml'
+    const filepath = join(path, filename)
+
+    set[endpoint] = /** @type {toa.samples.Operation[]} */ await yaml.load.all(filepath)
+  }
+
+  return operations
+}
+
+/**
+ * @returns {Promise<toa.samples.messages.Set>}
+ */
+const messages = async () => {
+  const label = 'somewhere.something.happened'
+  const file = label + '.yaml'
+  const path = join(root, 'samples/messages', file)
+  const samples = /** @type {toa.samples.Message[]} */ await yaml.load.all(path)
+
+  return { [label]: samples }
+}

package/samples/test/suite.mock.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const { generate } = require('randomstring')
+
+const suite = {
+  components: jest.fn(async () => generate()),
+  context: jest.fn(async () => generate())
+}
+
+exports.suite = suite

package/samples/types/index.d.ts

@@ -0,0 +1,8 @@
+import * as _replay from './replay'
+
+export { Operation } from './operation'
+export { Message } from './message'
+
+export const context: _replay.context
+export const components: _replay.components
+export const replay: _replay.replay

package/samples/types/message.d.ts

@@ -0,0 +1,24 @@
+import type * as _core from '@toa.io/core/types'
+import type * as _operation from './operation'
+
+declare namespace toa.samples {
+
+  namespace messages {
+
+    type Set = Record<string, Message[]>
+
+  }
+
+  type Message = {
+    title?: string
+    component: string
+    payload: Object
+    input?: any
+    query?: _core.Query
+    request?: _operation.Operation | null
+  }
+
+}
+
+export type Message = toa.samples.Message
+export type Set = toa.samples.messages.Set

package/samples/types/operation.d.ts

@@ -0,0 +1,36 @@
+import * as _core from '@toa.io/core/types'
+import * as _sampling from '@toa.io/extensions.sampling'
+
+declare namespace toa.samples {
+
+  namespace operations {
+
+    type Call = {
+      input?: any
+      output?: any
+    }
+
+    type Calls = Record<string, Call[]>
+
+    type Events = Record<string, Object>
+
+    type Set = Record<string, Operation[]>
+
+  }
+
+  type Operation = {
+    title?: string
+    input?: any
+    output?: any
+    current?: _core.storages.Record
+    next?: _core.storages.Record
+    remote?: operations.Calls
+    local?: operations.Calls
+    events?: operations.Events
+    extensions?: _sampling.request.Extensions
+  }
+
+}
+
+export type Operation = toa.samples.Operation
+export type Set = toa.samples.operations.Set

package/samples/types/replay.d.ts

@@ -0,0 +1,13 @@
+import * as _suite from "./suite";
+
+declare namespace toa.samples.replay {
+
+  type components = (paths: string[]) => Promise<boolean>
+  type context = (path: string) => Promise<boolean>
+  type replay = (suite: _suite.Suite, paths: string[]) => Promise<boolean>
+
+}
+
+export type context = toa.samples.replay.context
+export type components = toa.samples.replay.components
+export type replay = toa.samples.replay.replay

package/samples/types/suite.d.ts

@@ -0,0 +1,19 @@
+import * as _operations from './operation'
+import * as _messages from './message'
+
+declare namespace toa.samples {
+
+  namespace suite {
+    type Operations = Record<string, _operations.Set>
+  }
+
+  type Suite = {
+    title: string
+    autonomous: boolean
+    operations?: suite.Operations
+    messages?: _messages.Set
+  }
+
+}
+
+export type Suite = toa.samples.Suite

package/stage/package.json

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

package/stage/readme.md

@@ -0,0 +1,41 @@
+# Toa integration tests framework
+
+## TL;DR
+
+```javascript
+const stage = require('@toa.io/userland/stage')
+
+const component = await stage.component('dummies.dummy')
+const reply = await component.invoke('do', { input: 'foo' })
+
+await stage.shutdown()
+```
+
+See [examples](../example/stage).
+
+## Component
+
+`async component(path: string): toa.core.Component`
+
+Boot the component.
+
+> Components consuming events must be able to discover event sources, that is, either they must be
+> booted after event sources are composed or within the same composition.
+
+## Composition
+
+`async composition(paths: string[]): void`
+
+Boot the composition.
+
+## Remote
+
+`async remote(paths: string[]): toa.core.Component`
+
+Connect the remote.
+
+## Shutdown
+
+`async sutdown(): void`
+
+Shutdown all components, compositions and services.

package/stage/src/binding/binding.js

@@ -0,0 +1,49 @@
+'use strict'
+
+/**
+ * @implements {toa.stage.binding.Binding}
+ */
+class Binding {
+  /** @type {Record<string, function[]>} */
+  #subs = {}
+
+  /** @type {Record<string, function>} */
+  #calls = {}
+
+  async subscribe (label, callback) {
+    if (this.#subs[label] === undefined) this.#subs[label] = []
+
+    this.#subs[label].push(callback)
+  }
+
+  async emit (label, message) {
+    const callbacks = this.#subs[label]
+
+    if (callbacks === undefined) return undefined
+
+    const promises = callbacks.map((callback) => callback(message))
+
+    await Promise.all(promises)
+  }
+
+  async reply (label, produce) {
+    if (this.#calls[label] !== undefined) throw new Error(`Label '${label}' is already bound`)
+
+    this.#calls[label] = produce
+  }
+
+  async request (label, request) {
+    if (this.#calls[label] === undefined) throw new Error(`Label '${label}' is not bound`)
+
+    return this.#calls[label](request)
+  }
+
+  reset () {
+    this.#subs = {}
+    this.#calls = {}
+  }
+}
+
+const binding = new Binding()
+
+exports.binding = binding

package/stage/src/binding/consumer.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { binding } = require('./binding')
+const { label } = require('./label')
+
+/**
+ * @implements {toa.core.bindings.Consumer}
+ */
+class Consumer extends Connector {
+  /** @type {string} */
+  #label
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string} endpoint
+   */
+  constructor (locator, endpoint) {
+    super()
+
+    this.#label = label(locator, endpoint)
+  }
+
+  async request (request) {
+    return binding.request(this.#label, request)
+  }
+}
+
+exports.Consumer = Consumer

package/stage/src/binding/emitter.js

@@ -0,0 +1,26 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { binding } = require('./binding')
+const { label } = require('./label')
+
+/**
+ * @implements {toa.core.bindings.Emitter}
+ */
+class Emitter extends Connector {
+  /** @type {string} */
+  #label
+
+  constructor (locator, endpoint) {
+    super()
+
+    this.#label = label(locator, endpoint)
+  }
+
+  async emit (message) {
+    return binding.emit(this.#label, message)
+  }
+}
+
+exports.Emitter = Emitter

package/stage/src/binding/factory.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { Emitter } = require('./emitter')
+const { Receiver } = require('./receiver')
+const { Consumer } = require('./consumer')
+const { Producer } = require('./producer')
+
+class Factory {
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string} label
+   * @param {string} id
+   * @param {toa.core.Receiver} receiver
+   * @returns {toa.core.Connector}
+   */
+  receiver (locator, label, id, receiver) {
+    return new Receiver(locator, label, receiver)
+  }
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string} label
+   * @returns {toa.core.bindings.Emitter}
+   */
+  emitter (locator, label) {
+    return new Emitter(locator, label)
+  }
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string} endpoint
+   * @returns {toa.core.bindings.Consumer}
+   */
+  consumer (locator, endpoint) {
+    return new Consumer(locator, endpoint)
+  }
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string[]} endpoints
+   * @param {toa.core.Component} component
+   * @returns {toa.core.Connector}
+   */
+  producer (locator, endpoints, component) {
+    return new Producer(locator, endpoints, component)
+  }
+}
+
+exports.Factory = Factory

package/stage/src/binding/index.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const { Factory } = require('./factory')
+const { binding } = require('./binding')
+
+const properties = { async: true }
+
+exports.properties = properties
+exports.Factory = Factory
+exports.binding = binding

package/stage/src/binding/label.js

@@ -0,0 +1,12 @@
+'use strict'
+
+/**
+ * @param {toa.core.Locator} locator
+ * @param {string} endpoint
+ * @returns {string}
+ */
+const label = (locator, endpoint) => {
+  return locator.id + '.' + endpoint
+}
+
+exports.label = label

package/stage/src/binding/producer.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { binding } = require('./binding')
+const { label } = require('./label')
+
+/**
+ * @implements {toa.core.Connector}
+ */
+class Producer extends Connector {
+  /** @type {toa.core.Locator} */
+  #locator
+
+  /** @type {string[]} */
+  #endpoints
+
+  /** @type {toa.core.Component} */
+  #component
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string[]} endpoints
+   * @param {toa.core.Component} component
+   */
+  constructor (locator, endpoints, component) {
+    super()
+
+    this.#locator = locator
+    this.#endpoints = endpoints
+    this.#component = component
+  }
+
+  async connection () {
+    for (const endpoint of this.#endpoints) {
+      const command = label(this.#locator, endpoint)
+
+      await binding.reply(command, (request) => this.#component.invoke(endpoint, request))
+    }
+  }
+}
+
+exports.Producer = Producer

package/stage/src/binding/receiver.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { Connector } = require('@toa.io/core')
+
+const { binding } = require('./binding')
+const { label } = require('./label')
+
+/**
+ * @implements {toa.core.Connector}
+ */
+class Receiver extends Connector {
+  /** @type {string} */
+  #label
+
+  /** @type {toa.core.Receiver} */
+  #receiver
+
+  /**
+   * @param {toa.core.Locator} locator
+   * @param {string} endpoint
+   * @param {toa.core.Receiver} receiver
+   */
+  constructor (locator, endpoint, receiver) {
+    super()
+
+    this.#label = label(locator, endpoint)
+    this.#receiver = receiver
+  }
+
+  async connection () {
+    await binding.subscribe(this.#label, (message) => this.#receiver.receive(message))
+  }
+}
+
+exports.Receiver = Receiver

package/stage/src/component.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const boot = require('@toa.io/boot')
+const { state } = require('./state')
+
+/** @type {toa.stage.Component} */
+const component = async (path) => {
+  const manifest = await boot.manifest(path)
+  const component = await boot.component(manifest)
+
+  await component.connect()
+
+  state.components.push(component)
+
+  return component
+}
+
+exports.component = component

package/stage/src/composition.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const boot = require('@toa.io/boot')
+const { state } = require('./state')
+
+const binding = require.resolve('./binding')
+
+/** @type {toa.stage.Composition} */
+const composition = async (paths) => {
+  /** @type {toa.boot.composition.Options} */
+  const options = { bindings: [binding] }
+  const composition = await boot.composition(paths, options)
+
+  await composition.connect()
+
+  state.compositions.push(composition)
+}
+
+exports.composition = composition

package/stage/src/index.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const { manifest } = require('./manifest')
+const { component } = require('./component')
+const { composition } = require('./composition')
+const { remote } = require('./remote')
+const { shutdown } = require('./shutdown')
+const binding = require('./binding')
+
+// staging always runs on local deployment environment
+process.env.TOA_ENV = 'local'
+
+exports.manifest = manifest
+exports.component = component
+exports.composition = composition
+exports.remote = remote
+exports.shutdown = shutdown
+exports.binding = binding