@toa.io/extensions.exposition 0.9.0-canary.2 → 0.20.0-alpha.1

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "0.9.0-canary.2",
-  "description": "Toa Resources Exposition",
+  "version": "0.20.0-alpha.1",
+  "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
-  "main": "src/index.js",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/toa-io/toa.git"
@@ -15,22 +16,35 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "test": "echo \"Error: run tests from root\" && exit 1"
-  },
-  "devDependencies": {
-    "@types/express": "4.17.13"
+  "peerDependencies": {
+    "nopeable": "*"
   },
   "dependencies": {
-    "@toa.io/bindings.amqp": "0.8.0-canary.2",
-    "@toa.io/console": "0.6.0",
-    "@toa.io/core": "1.1.0-canary.2",
-    "@toa.io/generic": "0.11.0-canary.2",
-    "@toa.io/schema": "0.8.0-canary.2",
-    "@toa.io/yaml": "0.8.0-canary.2",
+    "@toa.io/core": "0.20.0-alpha.1",
+    "@toa.io/generic": "0.20.0-alpha.1",
+    "@toa.io/http": "0.20.0-alpha.1",
+    "@toa.io/schemas": "0.20.0-alpha.1",
+    "bcryptjs": "2.4.3",
     "cors": "2.8.5",
-    "express": "4.18.1",
-    "path-to-regexp": "6.2.0"
+    "express": "4.18.2",
+    "js-yaml": "4.1.0",
+    "msgpackr": "1.9.5",
+    "negotiator": "0.6.3",
+    "paseto": "3.1.4"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node"
+  },
+  "scripts": {
+    "transpile": "npx tsc && npx tsc -p ./components/identity.basic && npx tsc -p ./components/identity.tokens",
+    "features": "npx cucumber-js"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "2.4.3",
+    "@types/cors": "2.8.13",
+    "@types/express": "4.17.17",
+    "@types/negotiator": "0.6.1"
   },
-  "gitHead": "a80d81d4d9da9fec07606154c959dd6512de4c76"
+  "gitHead": "d1a5369c0ee4ee423f792b83e9753fd2fd943cce"
 }

package/readme.md

@@ -0,0 +1,181 @@
+# Toa Exposition
+
+## TL;DR
+
+Exposition is a converter from [ROA](https://en.wikipedia.org/wiki/Resource-oriented_architecture)
+to [SOA](https://en.wikipedia.org/wiki/Service-oriented_architecture).
+
+```yaml
+# manifest.toa.yaml
+
+name: dummy
+namespace: dummies
+
+exposition:
+  /:
+    GET: observe
+```
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  host: api.example.com
+```
+
+```http
+GET /dummies/dummy/
+Host: api.example.com
+```
+
+See [features](features) for more examples.
+
+## Overview
+
+<a href="https://miro.com/app/board/uXjVOoy0ImU=/?moveToWidget=3458764555658883997&cot=14">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="./documentation/.assets/overview-dark.jpg">
+        <img alt="Exposition" width="800" height="427" src="./documentation/.assets/overview-light.jpg">
+    </picture>
+</a>
+
+The Exposition extension includes a Service which is an HTTP server with ingress and a Tenant. The
+Service communicates
+with Tenants to discover their resource declarations and exposes them as HTTP resources. An instance
+of the Tenant is
+running within each Composition that has at least one Component with a resource declaration.
+
+## Resource tree discovery
+
+During the startup of the Tenant instance, it broadcasts an `expose` message
+containing [Resource branches](#resource-branch)
+of the Components within the Composition. Upon receiving the `expose` message, instances of the
+Service (re-)configures
+corresponding routes for its HTTP server.
+
+During the startup of the Service instance, it broadcasts a `ping` message. Once an instance of the
+Tenant receives
+a `ping` message, it broadcasts an `expose` message.
+
+## Resource branch
+
+<a href="">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="documentation/.assets/rtd-dark.jpg">
+    <img alt="IA3" width="600" height="293" src="documentation/.assets/rtd-light.jpg">
+  </picture>
+</a>
+
+A Component can specify how to expose its Operations as HTTP resources by declaring a Resource
+branch using the manifest extension.
+
+```yaml
+# manifest.toa.yaml
+
+extensions:
+  '@toa.io/extensions.exposition': ...
+```
+
+Alternatively, a shortcut `exposition` is available:
+
+```yaml
+# manifest.toa.yaml
+
+exposition: ...
+```
+
+Resource branches are attached to a Tree with a prefix `/{namespace}/{name}` or `/{name}` for
+components within the default namespace.
+
+```yaml
+# manifest.toa.yaml
+
+name: rooms
+namespace: messaging
+
+exposition:
+  /: ...
+  /:user-id: ...
+  /:user-id/:room-id: ...
+```
+
+The declaration above will result in exposing the following resources:
+
+```
+/messaging/rooms/
+/messaging/rooms/:user-id/
+/messaging/rooms/:user-id/:room-id/
+```
+
+> Trailing slash is required.
+
+## Context annotation
+
+The Exposition annotation declares options for its deployment.
+
+```yaml
+annotations:
+  '@toa.io/extensions.exposition':
+    host: the.exmaple.com
+```
+
+A shortcut is also available.
+
+```yaml
+exposition:
+  host: the.example.com
+```
+
+| Option        | Type      | Description                                                      |
+|---------------|-----------|------------------------------------------------------------------|
+| `host`        | `string`  | Domain name to be used for the corresponding Kubernetes Ingress. |
+| `class`       | `string`  | Ingress class                                                    |
+| `annotations` | `object`  | Ingress annotations                                              |
+| `debug`       | `boolean` | Output server errors. Default `false`.                           |
+
+### Context resources
+
+Exposition annotaion can contain [resource declaration](documentation/tree.md) under the `/` key.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  host: the.example.com
+  /:
+    /code:
+      GET:
+        endpoint: development.code.checkout
+        type: observation
+```
+
+In the example above, a request `GET /code` will be mapped to the `development.code.checkout`
+operation call.
+Unlike a component resource branch declaration, properties `namespace`, `component`, and `type` are
+required.
+
+If component resource branch conflicts with an annotation, the annotation takes precedence.
+
+### Example
+
+```yaml
+exposition:
+  host: the.example.com
+  host@staging: the.example.dev
+  class: alb
+  annotations:
+    alb.ingress.kubernetes.io/scheme: internet-facing
+    alb.ingress.kubernetes.io/target-type: ip
+    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 443}]'
+  /:
+    /foo:
+      GET: foo.bar.observe
+```
+
+## See Also
+
+- [Protocol support](documentation/protocol.md)
+- [Resource Tree Definition](documentation/tree.md)
+- [Identity authentication](documentation/identity.md)
+- [Access authorization](documentation/access.md)
+- [Features](features)

package/schemas/annotation.cos.yaml

@@ -0,0 +1,4 @@
+host?: string
+class?: string
+annotations?: <string>
+/?: ref:node

package/schemas/directive.cos.yaml

@@ -0,0 +1,3 @@
+family: string
+name: string
+value: ~

package/schemas/method.cos.yaml

@@ -0,0 +1,9 @@
+verb: /^(GET|POST|PUT|PATCH|DELETE)$/
+mapping:
+  namespace: string
+  component: string
+  endpoint: string
+  query:
+    $ref: query
+    default: { }
+directives: [ref:directive]

package/schemas/node.cos.yaml

@@ -0,0 +1,5 @@
+protected: boolean
+isolated: boolean
+routes: [ref:route]
+methods: [ref:method]
+directives: [ref:directive]

package/schemas/query.cos.yaml

@@ -0,0 +1,16 @@
+id?: string
+criteria?: string
+sort?: string
+omit:
+  $ref: range
+  default:
+    value: 0
+    range: [0, 1000]
+limit:
+  $ref: range
+  default:
+    value: 10
+    range: [1, 1000]
+  required: [value]
+selectors?: [string]
+projection?: [string]

package/schemas/querystring.cos.yaml

@@ -0,0 +1,5 @@
+id: string
+criteria: string
+sort: string
+omit: number
+limit: number

package/schemas/range.cos.yaml

@@ -0,0 +1,2 @@
+value?: number
+range: [number]

package/schemas/route.cos.yaml

@@ -0,0 +1,2 @@
+path: string
+node: ref:node

package/source/Annotation.ts

@@ -0,0 +1,6 @@
+export interface Annotation {
+  host?: string
+  class?: string
+  annotations?: Record<string, string>
+  '/'?: object // parsed and validated by RTD.syntax.parse
+}

package/source/Branch.ts

@@ -0,0 +1,8 @@
+import type * as RTD from './RTD/syntax'
+
+export interface Branch {
+  namespace: string
+  component: string
+  isolated: boolean
+  node: RTD.Node
+}

package/source/Composition.ts

@@ -0,0 +1,58 @@
+import { readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { type Dirent } from 'fs'
+import { Connector } from '@toa.io/core'
+import { type Bootloader } from './Factory'
+
+export class Composition extends Connector {
+  private readonly boot: Bootloader
+
+  public constructor (boot: Bootloader) {
+    super()
+    this.boot = boot
+  }
+
+  protected override async open (): Promise<void> {
+    const paths = find()
+    const composition = await this.boot.composition(paths)
+
+    await composition.connect()
+
+    this.depends(composition)
+
+    console.info('Composition complete.')
+  }
+
+  protected override dispose (): void {
+    console.info('Composition shutdown complete.')
+  }
+}
+
+function find (): string[] {
+  return entries().map((entry) => resolve(ROOT, entry.name))
+}
+
+function entries (): Dirent[] {
+  const entries = readdirSync(ROOT, { withFileTypes: true })
+
+  return entries.filter((entry) => entry.isDirectory())
+}
+
+export function components (): Components {
+  const labels: string[] = []
+  const paths: string[] = []
+
+  for (const entry of entries()) {
+    labels.push(entry.name.replace('.', '-'))
+    paths.push(resolve(ROOT, entry.name))
+  }
+
+  return { labels, paths }
+}
+
+interface Components {
+  labels: string[]
+  paths: string[]
+}
+
+const ROOT = resolve(__dirname, '../components/')

package/source/Context.ts

@@ -0,0 +1,6 @@
+import { type Endpoint } from './Endpoint'
+import { type Directives } from './Directive'
+import { type Branch } from './Branch'
+import type * as RTD from './RTD'
+
+export type Context = RTD.Context<Endpoint, Directives, Branch>

package/source/Directive.test.ts

@@ -0,0 +1,91 @@
+import { generate } from 'randomstring'
+import { DirectivesFactory, type Family } from './Directive'
+import { type syntax } from './RTD'
+import { type IncomingMessage } from './HTTP'
+import { type Remotes } from './Remotes'
+
+const families: Array<jest.MockedObject<Family>> = [
+  {
+    name: 'foo',
+    mandatory: true,
+    create: jest.fn((_0: any, _1: any, _2: any) => generate() as any),
+    preflight: jest.fn(),
+    settle: jest.fn()
+  },
+  {
+    name: 'bar',
+    mandatory: false,
+    create: jest.fn((_0: string, _1: any, _2: any) => generate() as any),
+    preflight: jest.fn(),
+    settle: jest.fn()
+  }
+]
+
+let factory: DirectivesFactory
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  families[0].preflight.mockImplementation(() => null)
+  families[1].preflight.mockImplementation(() => null)
+  factory = new DirectivesFactory(families, {} as unknown as Remotes)
+})
+
+it('should create directive', async () => {
+  const declarations: syntax.Directive[] = [
+    {
+      family: 'foo',
+      name: generate(),
+      value: generate()
+    },
+    {
+      family: 'bar',
+      name: generate(),
+      value: generate()
+    }
+  ]
+
+  factory.create(declarations)
+
+  for (let i = 0; i < declarations.length; i++) {
+    expect(families[i].create.mock.calls[0][0]).toBe(declarations[i].name)
+    expect(families[i].create.mock.calls[0][1]).toBe(declarations[i].value)
+  }
+})
+
+it('should throw error if directive family is not found', async () => {
+  const declaration: syntax.Directive = {
+    family: generate(),
+    name: generate(),
+    value: generate()
+  }
+
+  expect(() => factory.create([declaration]))
+    .toThrowError(`Directive family '${declaration.family}' not found.`)
+})
+
+it('should apply directive', async () => {
+  const declaration: syntax.Directive = {
+    family: 'foo',
+    name: generate(),
+    value: generate()
+  }
+
+  const directives = factory.create([declaration])
+  const request = generate() as unknown as IncomingMessage
+  const directive = families[0].create.mock.results[0].value
+
+  await directives.preflight(request, [])
+
+  expect(families[0].preflight.mock.calls[0][0]).toStrictEqual([directive])
+  expect(families[0].preflight.mock.calls[0][1]).toEqual(request)
+})
+
+it('should apply mandatory families', async () => {
+  const directives = factory.create([])
+  const request = generate() as unknown as IncomingMessage
+
+  await directives.preflight(request, [])
+
+  expect(families[0].preflight).toHaveBeenCalled()
+})

package/source/Directive.ts

@@ -0,0 +1,120 @@
+import { type IncomingMessage, type OutgoingMessage } from './HTTP'
+import { type Remotes } from './Remotes'
+import type * as RTD from './RTD'
+
+export class Directives implements RTD.Directives<Directives> {
+  private readonly directives: DirectiveSet[]
+
+  public constructor (directives: DirectiveSet[]) {
+    this.directives = directives
+  }
+
+  public async preflight (request: IncomingMessage, parameters: RTD.Parameter[]): Promise<Output> {
+    for (const directive of this.directives) {
+      const output = await directive.family.preflight(directive.directives, request, parameters)
+
+      if (output !== null) {
+        await this.settle(request, output)
+
+        return output
+      }
+    }
+
+    return null
+  }
+
+  public async settle (request: IncomingMessage, response: OutgoingMessage): Promise<void> {
+    for (const directive of this.directives)
+      if (directive.family.settle !== undefined)
+        await directive.family.settle(directive.directives, request, response)
+  }
+
+  public merge (directives: Directives): void {
+    this.directives.push(...directives.directives)
+  }
+}
+
+export class DirectivesFactory implements RTD.DirectivesFactory<Directives> {
+  private readonly remtoes: Remotes
+  private readonly families: Record<string, Family> = {}
+  private readonly mandatory: string[] = []
+
+  public constructor (families: Family[], remotes: Remotes) {
+    for (const family of families) {
+      this.families[family.name] = family
+
+      if (family.mandatory)
+        this.mandatory.push(family.name)
+    }
+
+    this.remtoes = remotes
+  }
+
+  public create (declarations: RTD.syntax.Directive[]): Directives {
+    const groups: Record<string, any> = {}
+    const mandatory = new Set(this.mandatory)
+
+    declarations.sort((a, b) =>
+      (mandatory.has(b.family) ? 1 : 0) - (mandatory.has(a.family) ? 1 : 0))
+
+    for (const declaration of declarations) {
+      const family = this.families[declaration.family]
+
+      if (family === undefined)
+        throw new Error(`Directive family '${declaration.family}' not found.`)
+
+      const directive = family.create(declaration.name, declaration.value, this.remtoes)
+
+      groups[family.name] ??= []
+      groups[family.name].push(directive)
+      mandatory.delete(family.name)
+    }
+
+    const sets: DirectiveSet[] = []
+
+    for (const family of mandatory)
+      sets.push({
+        family: this.families[family],
+        directives: []
+      })
+
+    for (const [family, directives] of Object.entries(groups))
+      sets.push({
+        family: this.families[family],
+        directives
+      })
+
+    return new Directives(sets)
+  }
+}
+
+export const shortcuts: RTD.syntax.Shortcuts = new Map([
+  ['anonymous', 'auth:anonymous'],
+  ['id', 'auth:id'],
+  ['role', 'auth:role'],
+  ['rule', 'auth:rule'],
+  ['incept', 'auth:incept']
+])
+
+export interface Family<TDirective = any, TExtension = any> {
+  readonly name: string
+  readonly mandatory: boolean
+
+  create: (name: string, value: any, remotes: Remotes) => TDirective
+
+  preflight: (directives: TDirective[],
+    request: IncomingMessage & TExtension,
+    parameters: RTD.Parameter[]) => Output | Promise<Output>
+
+  settle?: (directives: TDirective[],
+    request: IncomingMessage & TExtension,
+    response: OutgoingMessage) => void | Promise<void>
+}
+
+interface DirectiveSet {
+  family: Family
+  directives: any[]
+}
+
+export type Input = IncomingMessage
+export type Output = OutgoingMessage | null

package/source/Endpoint.ts

@@ -0,0 +1,57 @@
+import { type Component, type Reply } from '@toa.io/core'
+import { type Remotes } from './Remotes'
+import { Mapping } from './Mapping'
+import { type Context } from './Context'
+import type * as RTD from './RTD'
+import type * as http from './HTTP'
+
+export class Endpoint implements RTD.Endpoint<Endpoint> {
+  private readonly endpoint: string
+  private readonly mapping: Mapping
+  private readonly discovery: Promise<Component>
+  private remote: Component | null = null
+
+  public constructor (endpoint: string, mapping: Mapping, discovery: Promise<Component>) {
+    this.endpoint = endpoint
+    this.mapping = mapping
+    this.discovery = discovery
+  }
+
+  public async call (body: any, query: http.Query, parameters: RTD.Parameter[]): Promise<Reply> {
+    const request = this.mapping.fit(body, query, parameters)
+
+    this.remote ??= await this.discovery
+
+    return await this.remote.invoke(this.endpoint, request)
+  }
+
+  public async close (): Promise<void> {
+    this.remote ??= await this.discovery
+
+    await this.remote.disconnect()
+  }
+}
+
+export class EndpointFactory implements RTD.EndpointsFactory<Endpoint> {
+  private readonly remotes: Remotes
+
+  public constructor (remotes: Remotes) {
+    this.remotes = remotes
+  }
+
+  public create (method: RTD.syntax.Method, context: Context): Endpoint {
+    if (method.mapping === undefined)
+      throw new Error('Cannot create Endpoint without mapping.')
+
+    const mapping = Mapping.create(method.verb, method.mapping.query)
+    const namespace = method.mapping.namespace ?? context.extension?.namespace
+    const component = method.mapping.component ?? context.extension?.component
+
+    if (namespace === undefined || component === undefined)
+      throw new Error('Annotation endpoints must be fully qualified.')
+
+    const discovery = this.remotes.discover(namespace, component)
+
+    return new Endpoint(method.mapping.endpoint, mapping, discovery)
+  }
+}