@toa.io/extensions.exposition 1.0.0-alpha.274 → 1.0.0-alpha.277

package/features/steps/components/pricing/operations/quote.js

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

package/features/steps/components/sequences/operations/numbers.js

@@ -1,7 +1,5 @@
-'use strict'
-
 function * effect (amount) {
   for (let i = 0; i < amount; i++) yield i
 }
 
-exports.effect = effect
+export { effect }

package/features/steps/components/sequences/operations/tokens.js

@@ -1,6 +1,4 @@
-'use strict'
-
-const { randomBytes } = require('node:crypto')
+import { randomBytes } from 'node:crypto'
 
 async function * computation () {
   while (true) {
@@ -13,4 +11,4 @@ function timeout (ms) {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
-exports.computation = computation
+export { computation }

package/features/steps/components/users/operations/create.js

@@ -1,6 +1,4 @@
-'use strict'
-
-function transition (input, object) {
+export function transition (input, object) {
   if (input.name === 'return_error') {
     const e = new Error()
 
@@ -11,5 +9,3 @@ function transition (input, object) {
 
   return Object.assign(object, input)
 }
-
-exports.transition = transition

package/features/steps/map.ts

@@ -1,6 +1,10 @@
+import { createRequire } from 'node:module'
+import * as norm from '@toa.io/norm'
 import { dirname, join } from 'node:path'
 import type { Manifest } from '@toa.io/norm'
 
+const require = createRequire(import.meta.url)
+
 const PACKAGE = '@toa.io/extensions.introspection'
 const COMPONENTS = ['introspection.nodes', 'introspection.edges']
 
@@ -16,7 +20,7 @@ export function components (): string[] {
 
 /** `norm` declares `component` as a namespace of types; the runtime export is a function. */
 export async function manifests (): Promise<Manifest[]> {
-  const { component } = require('@toa.io/norm') as Norm
+  const { component } = norm as unknown as Norm
 
   return await Promise.all(components().map(async (path) => await component(path)))
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.274",
+  "version": "1.0.0-alpha.277",
+  "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -17,12 +18,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@simplewebauthn/server": "13.3.3",
-    "@toa.io/core": "1.0.0-alpha.273",
-    "@toa.io/generic": "1.0.0-alpha.273",
-    "@toa.io/schemas": "1.0.0-alpha.274",
+    "@simplewebauthn/server": "14.0.0",
+    "@toa.io/core": "1.0.0-alpha.277",
+    "@toa.io/generic": "1.0.0-alpha.277",
+    "@toa.io/schemas": "1.0.0-alpha.277",
     "bcryptjs": "3.0.3",
-    "content-type": "2.1.0",
+    "content-type": "3.0.0",
     "jose": "6.2.10",
     "js-yaml": "5.4.1",
     "lru-cache": "11.5.2",
@@ -30,11 +31,11 @@
     "minimatch": "10.2.6",
     "msgpackr": "2.1.0",
     "negotiator": "1.1.0",
-    "openspan": "1.0.0-alpha.272",
-    "paseto": "3.1.4"
+    "openspan": "1.0.0-alpha.277",
+    "paseto": "4.0.0"
   },
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test": "echo \"Error: run tests from root\" && exit 1",
     "transpile": "tsc && npm run transpile:bans && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles && npm run transpile:federation && npm run transpile:credentials && npm run transpile:keys && npm run transpile:passkeys && npm run transpile:otp",
     "transpile:bans": "tsc -p ./components/identity.bans",
     "transpile:basic": "tsc -p ./components/identity.basic",
@@ -45,21 +46,15 @@
     "transpile:keys": "tsc -p ./components/identity.keys",
     "transpile:passkeys": "tsc -p ./components/identity.passkeys",
     "transpile:otp": "tsc -p ./components/identity.otp",
-    "features": "cucumber-js",
-    "features:security": "cucumber-js --tags @security",
-    "features:octets": "cucumber-js features/octets.*"
+    "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
+    "features:h2c": "TOA_EXPOSITION_PROTOCOL=h2c TOA_AGENT_PROTOCOL=h2c TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
+    "features:security": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags @security",
+    "features:octets": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js features/octets.*"
   },
   "devDependencies": {
     "@toa.io/extensions.storages": "*",
     "@types/cors": "2.8.19",
-    "@types/negotiator": "0.6.5",
-    "jest-esbuild": "0.4.0"
+    "@types/negotiator": "0.6.5"
   },
-  "jest": {
-    "transform": {
-      "^.+\\.ts$": "jest-esbuild"
-    },
-    "testEnvironment": "node"
-  },
-  "gitHead": "7df32eb2872155c45681c299036b1efbeefd6518"
+  "gitHead": "0c0071418c2c56a44e621ba5ced5cdd23dff1738"
 }

package/readme.md

@@ -188,21 +188,15 @@ exposition:
 
 ## Ready probe
 
-The gateway serves `GET /.ready` on port `8000` for Kubernetes startup/readiness probes.
+The gateway serves `GET /.ready` on port `8004`, not on the port it serves traffic on, and
+telemetry's probe is disabled in its process.
 
-It returns `200` only after:
+It answers `200` only after the in-process identity composition has connected, initial route
+discovery has settled, and the HTTP server is listening. Before that it answers `503` with a
+`retry-after`. When ready, the process also sends `process.send('ready')` for PM2 `wait_ready`.
 
-1. The in-process identity composition has connected
-2. Initial route discovery has settled
-3. The HTTP server is listening
-
-Before listen, probes get connection refused; after listen but before ready, `503`.
-When ready, the process also sends `process.send('ready')` (for PM2 `wait_ready`).
-
-The nested identity composition shares this process. Deployment disables telemetry's port-`8001`
-probe (`TOA_TELEMETRY_READY=false`) so only the gateway `/.ready` is used.
-
-See also [telemetry ready probe](../telemetry/readme.md#ready-probe).
+See also [telemetry ready probe](../telemetry/readme.md#ready-probe) and
+[reserved ports](../../documentation/ports.md).
 
 ## See Also
 

package/schemas/annotation.cos.yaml

@@ -24,8 +24,19 @@ properties:
     patternProperties:
       ^.+$:
         type: string
+  service:
+    type: object
+    properties:
+      annotations:
+        type: object
+        patternProperties:
+          ^.+$:
+            type: string
   debug:
     type: boolean
+  protocol:
+    type: string
+    enum: [h1, h2c]
   /: {}
   authorities:
     type: object

package/source/Annotation.ts

@@ -1,10 +1,21 @@
 import type { Resources } from '@toa.io/operations'
+import type { Protocol } from './HTTP/index.js'
 
 export interface Annotation {
   authorities: Record<string, string>
+
+  /**
+   * `h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream.
+   * See `documentation/protocol.md`.
+   */
+  protocol?: Protocol
   class?: string
   resources?: Resources
   annotations?: Record<string, string>
+
+  /** The Service, as opposed to the Ingress that `annotations` above describes. */
+  service?: { annotations?: Record<string, string> }
+
   debug?: boolean
   '/'?: object // parsed and validated by RTD.syntax.parse
 }

package/source/Branch.test.ts

@@ -1,5 +1,8 @@
-import { decide } from './Branch'
-import type { Branch, Exposed } from './Branch'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { decide } from './Branch.js'
+import type { Branch, Exposed } from './Branch.js'
 
 function branch (version: string, timestamp: number): Branch {
   return {
@@ -17,21 +20,21 @@ function exposed (version: string, timestamp: number): Exposed {
 }
 
 it('should refresh the same version', () => {
-  expect(decide(exposed('a', 1), branch('a', 2))).toStrictEqual('refresh')
+  assert.deepStrictEqual(decide(exposed('a', 1), branch('a', 2)), 'refresh')
 })
 
 it('should refresh the same version announced by an older tenant', () => {
-  expect(decide(exposed('a', 2), branch('a', 1))).toStrictEqual('refresh')
+  assert.deepStrictEqual(decide(exposed('a', 2), branch('a', 1)), 'refresh')
 })
 
 it('should merge a newer tenant', () => {
-  expect(decide(exposed('a', 1), branch('b', 2))).toStrictEqual('merge')
+  assert.deepStrictEqual(decide(exposed('a', 1), branch('b', 2)), 'merge')
 })
 
 it('should not merge a tenant that started earlier', () => {
-  expect(decide(exposed('b', 2), branch('a', 1))).toStrictEqual('superseded')
+  assert.deepStrictEqual(decide(exposed('b', 2), branch('a', 1)), 'superseded')
 })
 
 it('should merge when tenants started at the same time', () => {
-  expect(decide(exposed('a', 1), branch('b', 1))).toStrictEqual('merge')
+  assert.deepStrictEqual(decide(exposed('a', 1), branch('b', 1)), 'merge')
 })

package/source/Branch.ts

@@ -1,5 +1,5 @@
-import type * as RTD from './RTD/syntax'
-import type { Node } from './RTD'
+import type * as RTD from './RTD/syntax/index.js'
+import type { Node } from './RTD/index.js'
 
 export interface Branch {
   namespace: string

package/source/Composition.ts

@@ -1,7 +1,7 @@
 import { readdirSync, type Dirent } from 'node:fs'
 import { resolve } from 'node:path'
 import { Connector } from '@toa.io/core'
-import { type Bootloader } from './Factory'
+import { type Bootloader } from './Factory.js'
 
 export class Composition extends Connector {
   private readonly boot: Bootloader
@@ -48,4 +48,4 @@ interface Components {
   paths: string[]
 }
 
-const ROOT = resolve(__dirname, '../components/')
+const ROOT = resolve(import.meta.dirname, '../components/')

package/source/Context.ts

@@ -1,4 +1,4 @@
-import type * as RTD from './RTD'
+import type * as RTD from './RTD/index.js'
 
 // the trunk is built from the context annotation and belongs to no branch,
 // thus its endpoints must be fully qualified and are not versioned

package/source/Directive.test.ts

@@ -1,49 +1,54 @@
-import assert from 'node:assert'
+import { describe, it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { generate } from 'randomstring'
-import { DirectivesFactory } from './Directive'
-import type { syntax, DirectiveFamily } from './RTD'
-import type { Remotes } from './Remotes'
-import type { Context } from './HTTP'
+import { DirectivesFactory } from './Directive.js'
+import type { syntax, DirectiveFamily } from './RTD/index.js'
+import type { Remotes } from './Remotes.js'
+import type { Context } from './HTTP/index.js'
+
+const sequence: string[] = []
 
-const families: Array<jest.MockedObjectDeep<DirectiveFamily>> = [
+const families: Array<DirectiveFamily> = [
   {
     name: 'foo',
     mandatory: true,
-    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
-    arrange: jest.fn(),
-    preflight: jest.fn(),
-    settle: jest.fn(),
-    dispose: jest.fn()
+    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('foo'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
   },
   {
     name: 'qux',
     mandatory: true,
-    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
-    arrange: jest.fn(),
-    preflight: jest.fn(),
-    settle: jest.fn(),
-    dispose: jest.fn()
+    create: mock.fn((_0: any, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('qux'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
   },
   {
     name: 'bar',
     mandatory: false,
-    create: jest.fn((_0: string, _1: any, _2: any) => generate() as any),
-    arrange: jest.fn(),
-    preflight: jest.fn(),
-    settle: jest.fn(),
-    dispose: jest.fn()
+    create: mock.fn((_0: string, _1: any, _2: any) => generate() as any),
+    arrange: mock.fn(),
+    preflight: mock.fn(() => { sequence.push('bar'); return null }),
+    settle: mock.fn(),
+    dispose: mock.fn()
   }
 ]
 
 let factory: DirectivesFactory
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
+  sequence.length = 0
 
   for (const family of families) {
     assert.ok(family.preflight !== undefined)
 
-    family.preflight.mockImplementation(() => null)
+    family.preflight.mock.mockImplementation(() => { sequence.push(family.name); return null })
   }
 
   factory = new DirectivesFactory(families, {} as unknown as Remotes)
@@ -68,8 +73,8 @@ it('should create directive', async () => {
   for (const declaration of declarations) {
     const family = families.find(({ name }) => name === declaration.family)!
 
-    expect(family.create.mock.calls[0][0]).toBe(declaration.name)
-    expect(family.create.mock.calls[0][1]).toBe(declaration.value)
+    assert.strictEqual(family.create.mock.calls[0].arguments[0], declaration.name)
+    assert.strictEqual(family.create.mock.calls[0].arguments[1], declaration.value)
   }
 })
 
@@ -78,7 +83,7 @@ it('should pass the route to the families', async () => {
 
   factory.create([{ family: 'foo', name: generate(), value: generate() }], route)
 
-  expect(families[0].create.mock.calls[0][3]).toBe(route)
+  assert.strictEqual(families[0].create.mock.calls[0].arguments[3], route)
 })
 
 it('should throw error if directive family is not found', async () => {
@@ -88,8 +93,8 @@ it('should throw error if directive family is not found', async () => {
     value: generate()
   }
 
-  expect(() => factory.create([declaration]))
-    .toThrow(`Directive family '${declaration.family}' is not found`)
+  assert.throws(() => factory.create([declaration]),
+    (error: Error) => error.message.includes(`Directive family '${declaration.family}' is not found`))
 })
 
 it('should apply directive', async () => {
@@ -101,14 +106,14 @@ it('should apply directive', async () => {
 
   const directives = factory.create([declaration])
   const request = generate() as unknown as Context
-  const directive = families[0].create.mock.results[0].value
+  const directive = families[0].create.mock.calls[0].result
 
   await directives.preflight(request, [])
 
   assert.ok(families[0].preflight !== undefined)
 
-  expect(families[0].preflight.mock.calls[0][0]).toStrictEqual([directive])
-  expect(families[0].preflight.mock.calls[0][1]).toEqual(request)
+  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[0], [directive])
+  assert.deepStrictEqual(families[0].preflight.mock.calls[0].arguments[1], request)
 })
 
 it('should apply mandatory families', async () => {
@@ -117,16 +122,13 @@ it('should apply mandatory families', async () => {
 
   await directives.preflight(request, [])
 
-  expect(families[0].preflight).toHaveBeenCalled()
+  assert.ok(families[0].preflight.mock.callCount() > 0)
 })
 
 describe('order', () => {
+  // the order the families actually ran, as each preflight recorded it
   function order (): string[] {
-    return families
-      .filter(({ preflight }) => preflight!.mock.calls.length > 0)
-      .sort((a, b) => a.preflight!.mock.invocationCallOrder[0] -
-        b.preflight!.mock.invocationCallOrder[0])
-      .map(({ name }) => name)
+    return sequence
   }
 
   it('should run mandatory families in their own order, whatever a manifest says', async () => {
@@ -138,7 +140,7 @@ describe('order', () => {
 
     await directives.preflight(generate() as unknown as Context, [])
 
-    expect(order()).toStrictEqual(['foo', 'qux'])
+    assert.deepStrictEqual(order(), ['foo', 'qux'])
   })
 
   it('should run a mandatory family before a declared one it is not declared with',
@@ -151,7 +153,7 @@ describe('order', () => {
 
       await directives.preflight(generate() as unknown as Context, [])
 
-      expect(order()).toStrictEqual(['foo', 'qux'])
+      assert.deepStrictEqual(order(), ['foo', 'qux'])
     })
 
   it('should run mandatory families before the rest', async () => {
@@ -162,6 +164,16 @@ describe('order', () => {
 
     await directives.preflight(generate() as unknown as Context, [])
 
-    expect(order()).toStrictEqual(['foo', 'qux', 'bar'])
+    assert.deepStrictEqual(order(), ['foo', 'qux', 'bar'])
   })
 })
+
+function resetCalls (target = [families], 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/source/Directive.ts

@@ -1,8 +1,8 @@
 import { console, type SpanOptions } from 'openspan'
-import type { Context, OutgoingMessage } from './HTTP'
-import type { Remotes } from './Remotes'
-import type { Output } from './io'
-import type * as RTD from './RTD'
+import type { Context, OutgoingMessage } from './HTTP/index.js'
+import type { Remotes } from './Remotes.js'
+import type { Output } from './io.js'
+import type * as RTD from './RTD/index.js'
 
 export class Directives implements RTD.Directives {
   private readonly sets: RTD.DirectiveSet[]

package/source/Endpoint.ts

@@ -1,12 +1,12 @@
 import { Readable } from 'node:stream'
 import { console } from 'openspan'
-import { Mapping } from './Mapping'
-import * as http from './HTTP'
-import type { Introspection, Schema } from './Introspection'
+import { Mapping } from './Mapping.js'
+import * as http from './HTTP/index.js'
+import type { Introspection, Schema } from './Introspection.js'
 import type { Remote } from '@toa.io/core'
-import type { Remotes } from './Remotes'
-import type { Context } from './Context'
-import type * as RTD from './RTD'
+import type { Remotes } from './Remotes.js'
+import type { Context } from './Context.js'
+import type * as RTD from './RTD/index.js'
 
 export class Endpoint implements RTD.Endpoint {
   private readonly endpoint: string

package/source/Factory.ts

@@ -1,20 +1,20 @@
 import assert from 'node:assert'
 import { createHash } from 'node:crypto'
 import { console, traces, type LevelName, type TracesOptions } from 'openspan'
-import { Tenant } from './Tenant'
-import { Gateway } from './Gateway'
-import { Remotes } from './Remotes'
-import { Tree } from './RTD'
-import { EndpointsFactory } from './Endpoint'
-import { families, interceptors } from './directives'
-import { DirectivesFactory } from './Directive'
-import { Composition } from './Composition'
-import * as root from './root'
-import { Interception } from './Interception'
-import * as http from './HTTP'
-import type { Branch } from './Branch'
-import type { syntax } from './RTD'
-import type { Broadcast } from './Gateway'
+import { Tenant } from './Tenant.js'
+import { Gateway } from './Gateway.js'
+import { Remotes } from './Remotes.js'
+import { Tree } from './RTD/index.js'
+import { EndpointsFactory } from './Endpoint.js'
+import { families, interceptors } from './directives/index.js'
+import { DirectivesFactory } from './Directive.js'
+import { Composition } from './Composition.js'
+import * as root from './root.js'
+import { Interception } from './Interception.js'
+import * as http from './HTTP/index.js'
+import type { Branch } from './Branch.js'
+import type { syntax } from './RTD/index.js'
+import type { Broadcast } from './Gateway.js'
 import type { Connector, Locator, extensions } from '@toa.io/core'
 
 export class Factory implements extensions.Factory {
@@ -24,8 +24,8 @@ export class Factory implements extensions.Factory {
     this.boot = boot
   }
 
-  public tenant (locator: Locator, node: syntax.Node): Connector {
-    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL, locator.id)
+  public async tenant (locator: Locator, node: syntax.Node): Promise<Connector> {
+    const broadcast: Broadcast = await this.boot.bindings.broadcast(CHANNEL, locator.id)
     const hash = createHash('sha256').update(JSON.stringify(node)).digest('hex')
 
     // no timestamp: the tenant stamps each announcement with its own start time
@@ -40,14 +40,14 @@ export class Factory implements extensions.Factory {
     return new Tenant(broadcast, branch)
   }
 
-  public service (): Connector | null {
+  public async service (): Promise<Connector | null> {
     assert.ok(process.env.TOA_EXPOSITION_PROPERTIES,
       'TOA_EXPOSITION_PROPERTIES is undefined')
 
     configureLogs()
 
     const options = JSON.parse(process.env.TOA_EXPOSITION_PROPERTIES) as http.Options
-    const broadcast: Broadcast = this.boot.bindings.broadcast(CHANNEL)
+    const broadcast: Broadcast = await this.boot.bindings.broadcast(CHANNEL)
     const server = http.Server.create({ ...options })
     const remotes = new Remotes(this.boot)
     const node = root.resolve()

package/source/Gateway.ts

@@ -2,13 +2,13 @@ import assert from 'node:assert'
 import { setTimeout } from 'node:timers/promises'
 import { console } from 'openspan'
 import { type bindings, Connector } from '@toa.io/core'
-import * as http from './HTTP'
-import { rethrow } from './exceptions'
-import { decide } from './Branch'
-import type { Interception } from './Interception'
-import type { Method, Node, Parameter, Tree, Match } from './RTD'
-import type { Label } from './discovery'
-import type { Branch, Exposed } from './Branch'
+import * as http from './HTTP/index.js'
+import { rethrow } from './exceptions.js'
+import { decide } from './Branch.js'
+import type { Interception } from './Interception.js'
+import type { Method, Node, Parameter, Tree, Match } from './RTD/index.js'
+import type { Label } from './discovery.js'
+import type { Branch, Exposed } from './Branch.js'
 
 export class Gateway extends Connector {
   private readonly broadcast: Broadcast

package/source/HTTP/Context.ts

@@ -2,11 +2,11 @@ import crypto from 'node:crypto'
 import { buffer } from 'node:stream/consumers'
 import Negotiator from 'negotiator'
 import { console } from 'openspan'
-import { Timing } from './Timing'
-import { type Format, formats, types } from './formats'
-import { read } from './messages'
-import type { OutgoingMessage } from './messages'
-import type * as http from 'node:http'
+import { Timing } from './Timing.js'
+import { type Format, formats, types } from './formats/index.js'
+import { read } from './messages.js'
+import type { OutgoingMessage } from './messages.js'
+import type { IncomingMessage } from './types.js'
 
 export class Context {
   public readonly id: string
@@ -87,11 +87,6 @@ export class Context {
   }
 }
 
-export interface IncomingMessage extends http.IncomingMessage {
-  url: string
-  method: string
-}
-
 interface Pipelines {
   body: Array<(input: unknown) => unknown>
   response: Array<(output: OutgoingMessage) => void | Promise<void>>