@toa.io/extensions.exposition 0.8.3-dev.9 → 0.20.0-alpha.0

package/features/queries.feature

@@ -0,0 +1,214 @@
+Feature: Queries
+
+  Background:
+    Given the `pots` database contains:
+      | _id                              | title      | volume | temperature |
+      | 4c4759e6f9c74da989d64511df42d6f4 | First pot  | 100    | 80          |
+      | 99988d785d7d445cad45dbf8531f560b | Second pot | 200    | 30          |
+      | a7edded6b2ab47a0aca9508cc4da4138 | Third pot  | 300    | 50          |
+      | bc6913d317334d76acd07d9f25f73535 | Fourth pot | 400    | 90          |
+
+  Scenario: Request with `id` query parameter
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /pot:
+          GET: observe
+      """
+    When the following request is received:
+      """
+      GET /pots/pot/?id=99988d785d7d445cad45dbf8531f560b HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      id: 99988d785d7d445cad45dbf8531f560b
+      title: Second pot
+      volume: 200
+      """
+
+  Scenario: Request with query criteria
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      GET /pots/?criteria=volume<300&limit=10 HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: 4c4759e6f9c74da989d64511df42d6f4
+        title: First pot
+        volume: 100
+      - id: 99988d785d7d445cad45dbf8531f560b
+        title: Second pot
+        volume: 200
+      """
+
+  Scenario: Request with `omit` and `limit`
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      GET /pots/?omit=1&limit=2 HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: 99988d785d7d445cad45dbf8531f560b
+        title: Second pot
+        volume: 200
+      - id: a7edded6b2ab47a0aca9508cc4da4138
+        title: Third pot
+        volume: 300
+      """
+
+  Scenario: Request with sorting
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      GET /pots/?sort=volume:desc&limit=2 HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: bc6913d317334d76acd07d9f25f73535
+        title: Fourth pot
+        volume: 400
+      - id: a7edded6b2ab47a0aca9508cc4da4138
+        title: Third pot
+        volume: 300
+      """
+
+  Scenario: Request to a route with a path variable
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:id:
+          GET: observe
+      """
+    When the following request is received:
+      """
+      GET /pots/99988d785d7d445cad45dbf8531f560b/ HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      id: 99988d785d7d445cad45dbf8531f560b
+      title: Second pot
+      volume: 200
+      """
+
+  Scenario: Request to a route with predefined criretia
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /big:
+          GET:
+            endpoint: enumerate
+            query:
+              criteria: volume>200
+      """
+    When the following request is received:
+      """
+      GET /pots/big/ HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: a7edded6b2ab47a0aca9508cc4da4138
+        title: Third pot
+        volume: 300
+      - id: bc6913d317334d76acd07d9f25f73535
+        title: Fourth pot
+        volume: 400
+      """
+
+  Scenario: Request to a route with combined criteria
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /big:
+          GET:
+            endpoint: enumerate
+            query:
+              criteria: volume>200; # open criteria
+      """
+    When the following request is received:
+      """
+      GET /pots/big/?criteria=temperature>50 HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: bc6913d317334d76acd07d9f25f73535
+        title: Fourth pot
+        volume: 400
+        temperature: 90
+      """
+
+  Scenario: Request to a route with predefined query
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /hottest2:
+          GET:
+            endpoint: enumerate
+            query:
+              criteria: temperature>60
+              sort: temperature:desc
+              limit: 2
+      """
+    When the following request is received:
+      """
+      GET /pots/hottest2/ HTTP/1.1
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      - id: bc6913d317334d76acd07d9f25f73535
+        title: Fourth pot
+        volume: 400
+        temperature: 90
+      - id: 4c4759e6f9c74da989d64511df42d6f4
+        title: First pot
+        volume: 100
+        temperature: 80
+      """

package/features/routes.feature

@@ -0,0 +1,49 @@
+Feature: Routes
+
+  Scenario Outline: Basic routes
+    Given the `greeter` is running with the following manifest:
+      """yaml
+      namespace: basic
+
+      exposition:
+        /strict:
+          GET:
+            endpoint: greet
+        /shortcuts:
+          /operation:
+            GET: greet
+      """
+    When the following request is received:
+      """
+      GET /basic/greeter<route> HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      Hello
+      """
+    Examples:
+      | route                 |
+      | /strict/              |
+      | /shortcuts/operation/ |
+
+  Scenario: Basic routes within default namespace
+    Given the `greeter` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET: greet
+      """
+    When the following request is received:
+      """
+      GET /greeter/ HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      Hello
+      """

package/features/steps/Common.ts

@@ -0,0 +1,10 @@
+import { binding, given } from 'cucumber-tsflow'
+import { timeout } from '@toa.io/generic'
+
+@binding()
+export class Common {
+  @given('after {float} second(s)')
+  public async timeout (interval: number): Promise<void> {
+    await timeout(interval * 1000)
+  }
+}

package/features/steps/Components.ts

@@ -0,0 +1,43 @@
+import { after, binding, given } from 'cucumber-tsflow'
+import * as boot from '@toa.io/boot'
+import { timeout } from '@toa.io/generic'
+import { type Connector } from '@toa.io/core'
+import { parse } from '@toa.io/yaml'
+import { Workspace } from './Workspace'
+
+@binding([Workspace])
+export class Components {
+  private readonly workspace: Workspace
+  private composition: Connector | null = null
+
+  public constructor (workspace: Workspace) {
+    this.workspace = workspace
+  }
+
+  @given('the `{word}` is running')
+  public async run (name: string): Promise<void> {
+    await this.runComponent(name)
+  }
+
+  @given('the `{word}` is running with the following manifest:')
+  public async patchAndRun (name: string, yaml: string): Promise<void> {
+    const manifest = parse(yaml)
+
+    await this.runComponent(name, manifest)
+  }
+
+  @after()
+  @given('the `{word}` is stopped')
+  public async stop (_?: string): Promise<void> {
+    await this.composition?.disconnect()
+  }
+
+  private async runComponent (name: string, manifest?: object): Promise<void> {
+    const path = await this.workspace.addComponent(name, manifest)
+
+    this.composition = await boot.composition([path])
+
+    await this.composition.connect()
+    await timeout(50) // discovery
+  }
+}

package/features/steps/Database.ts

@@ -0,0 +1,58 @@
+import { afterAll, beforeAll, binding, given } from 'cucumber-tsflow'
+import { type DataTable } from '@cucumber/cucumber'
+import { MongoClient } from 'mongodb'
+
+@binding()
+export class Database {
+  private static client: MongoClient
+
+  @given('the `{word}` database contains:')
+  public async upsert (id: string, table: DataTable): Promise<void> {
+    const [name, namespace = 'default'] = id.split('.').reverse()
+    const collection = Database.client.db(namespace).collection(name)
+
+    const columns = table.raw()[0]
+    const rows = table.rows()
+    const documents: Document[] = []
+
+    for (let r = 0; r < rows.length; r++) {
+      const document: Document = {}
+
+      for (let c = 0; c < columns.length; c++) {
+        const str = rows[r][c]
+        const int = parseInt(str)
+
+        document[columns[c]] = int.toString() === str ? int : str
+      }
+
+      documents.push(document)
+    }
+
+    await collection.deleteMany({})
+
+    if (documents.length > 0)
+      await collection.insertMany(documents)
+  }
+
+  @given('the `{word}` database is empty')
+  public async truncate (id: string): Promise<void> {
+    const [name, namespace = 'default'] = id.split('.').reverse()
+    const collection = Database.client.db(namespace).collection(name)
+
+    await collection.deleteMany({})
+  }
+
+  @beforeAll()
+  public static async connect (): Promise<void> {
+    this.client = new MongoClient('mongodb://developer:secret@localhost:27017')
+
+    await this.client.connect()
+  }
+
+  @afterAll()
+  public static async disconnect (): Promise<void> {
+    await this.client.close()
+  }
+}
+
+type Document = Record<string, string | number>

package/features/steps/Gateway.ts

@@ -0,0 +1,105 @@
+import { after, afterAll, binding, given } from 'cucumber-tsflow'
+import * as boot from '@toa.io/boot'
+import { type Connector } from '@toa.io/core'
+import { parse } from '@toa.io/yaml'
+import { encode, timeout } from '@toa.io/generic'
+import { Factory } from '../../source'
+import * as syntax from '../../source/RTD/syntax'
+import { shortcuts } from '../../source/Directive'
+
+let instance: Connector | null = null
+
+@binding()
+export class Gateway {
+  private default: boolean = true
+
+  @given('the annotation:')
+  public async annotate (yaml: string): Promise<void> {
+    const annotation = parse(yaml)
+    const node = syntax.parse(annotation, shortcuts)
+
+    process.env.TOA_EXPOSITION = encode(node)
+
+    await Gateway.stop()
+
+    this.default = false
+  }
+
+  @given('the `{word}` configuration:')
+  public async configure (id: string, yaml: string): Promise<void> {
+    const [name, namespace = 'default'] = id.split('.').reverse()
+    const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
+    const def = DEFAULT_CONFIGURATION[id] ?? {}
+    const patch: object = parse(yaml)
+    const configuration = Object.assign({}, def, patch)
+
+    process.env[key] = encode(configuration)
+
+    await Gateway.stop()
+
+    this.default = false
+  }
+
+  @after()
+  public async cleanup (): Promise<void> {
+    if (this.default)
+      return
+
+    delete process.env.TOA_EXPOSITION
+
+    await Gateway.stop()
+  }
+
+  @afterAll()
+  public static async stop (): Promise<void> {
+    await instance?.disconnect()
+    instance = null
+  }
+
+  public async start (): Promise<void> {
+    if (instance !== null)
+      return
+
+    process.env.TOA_EXPOSITION ??= DEFAULT_ANNOTATION
+
+    this.writeConfiguration()
+
+    const factory = new Factory(boot)
+    const service = factory.service()
+
+    if (service === null)
+      throw new Error('?')
+
+    instance = service
+
+    await service.connect()
+    await timeout(50) // resource discovery
+  }
+
+  private writeConfiguration (): void {
+    for (const [id, configuration] of Object.entries(DEFAULT_CONFIGURATION)) {
+      const [name, namespace = 'default'] = id.split('.').reverse()
+      const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
+
+      process.env[key] ??= encode(configuration)
+    }
+  }
+}
+
+const DEFAULT_ANNOTATION = encode({
+  routes: [],
+  methods: [],
+  directives: [
+    {
+      family: 'auth',
+      name: 'anonymous',
+      value: true
+    }
+  ]
+} satisfies syntax.Node)
+
+const DEFAULT_CONFIGURATION: Record<string, object> = {
+  'identity.tokens': {
+    key0: 'k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA'
+  }
+}

package/features/steps/HTTP.ts

@@ -0,0 +1,71 @@
+import * as assert from 'assert'
+import { AssertionError } from 'assert'
+import { binding, when, then } from 'cucumber-tsflow'
+import * as http from '@toa.io/http'
+import { trim } from '@toa.io/generic'
+import { Parameters } from './parameters'
+import { Gateway } from './Gateway'
+
+@binding([Gateway, Parameters])
+export class HTTP {
+  private readonly gateway: Gateway
+  private readonly origin: string
+  private response: string = ''
+  private readonly variables: Record<string, string> = {}
+
+  public constructor (gateway: Gateway, parameters: Parameters) {
+    this.gateway = gateway
+    this.origin = parameters.origin
+  }
+
+  @when('the following request is received:')
+  public async request (input: string): Promise<any> {
+    let [headers, body] = trim(input).split('\n\n')
+
+    if (body !== undefined)
+      headers += '\ncontent-length: ' + body?.length
+
+    const text = headers + '\n\n' + (body ?? '')
+    const request = text.replaceAll(SUBSTITUTE, (_, name) => this.variables[name])
+
+    await this.gateway.start()
+
+    this.response = await http.request(request, this.origin)
+  }
+
+  @then('the following reply is sent:')
+  public responseIncludes (expected: string): void {
+    const lines = trim(expected).split('\n')
+
+    for (const line of lines) {
+      const escaped = line.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+      const expression = escaped.replace(CAPTURE,
+        (_, name) => `(?<${name}>\\S{1,2048})`)
+
+      const rx = new RegExp(expression, 'i')
+      const match = this.response.match(rx)
+
+      if (match === null)
+        throw new AssertionError({ message: `Response is missing '${line}'\n${this.response}` })
+
+      Object.assign(this.variables, match.groups)
+    }
+  }
+
+  @then('the reply does not contain:')
+  public responseExcludes (expected: string): void {
+    const lines = trim(expected).split('\n')
+
+    for (const line of lines) {
+      line.replace(SUBSTITUTE, (_, name) => this.variables[name])
+
+      const includes = this.response.includes(line)
+
+      assert.equal(includes, false, `Response contains '${line}'\n${this.response}`)
+    }
+  }
+}
+
+const CAPTURE = /\\\$\\{\\{ (?<name>[A-Za-z_]{0,32}) \\}\\}/g
+const SUBSTITUTE = /\${{ (?<name>[A-Za-z_]{0,32}) }}/g

package/features/steps/Parameters.ts

@@ -0,0 +1,12 @@
+import { setDefaultTimeout } from '@cucumber/cucumber'
+
+export class Parameters {
+  public readonly origin: string
+
+  public constructor () {
+    this.origin = 'http://localhost:8000'
+  }
+}
+
+setDefaultTimeout(10 * 1000)
+process.env.TOA_DEV = '1'

package/features/steps/Workspace.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path'
+import { directory } from '@toa.io/filesystem'
+import * as yaml from '@toa.io/yaml'
+
+export class Workspace {
+  private root: string = devnull
+
+  public static exists
+  (target: Workspace, key: string, descriptor: PropertyDescriptor): PropertyDescriptor {
+    const method = descriptor.value
+
+    descriptor.value = async function (this: Workspace, ...args: any[]): Promise<any> {
+      if (this.root === devnull) this.root = await directory.temp()
+
+      return method.apply(this, args)
+    }
+
+    return descriptor
+  }
+
+  @Workspace.exists
+  public async addComponent (name: string, patch?: object): Promise<string> {
+    const source = join(__dirname, 'components', name)
+    const target = join(this.root, name)
+
+    await directory.copy(source, target)
+
+    if (patch !== undefined) await this.patchManifest(target, patch)
+
+    return target
+  }
+
+  private async patchManifest (target: string, patch: object): Promise<void> {
+    const path = join(target, 'manifest.toa.yaml')
+
+    await yaml.patch(path, patch)
+  }
+}
+
+const devnull = '/dev/null'

package/features/steps/components/greeter/manifest.toa.yaml

@@ -0,0 +1,9 @@
+name: greeter
+
+operations:
+  greet:
+    output: string
+
+exposition:
+  /:
+    GET: greet

package/features/steps/components/greeter/operations/greet.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function computation () {
+  return 'Hello'
+}
+
+exports.computation = computation

package/features/steps/components/pots/manifest.toa.yaml

@@ -0,0 +1,20 @@
+name: pots
+
+entity:
+  schema:
+    title: string
+    volume: number
+    temperature?: number
+
+operations:
+  transit:
+    concurrency: none
+    input:
+      title*: ~
+      volume*: ~
+  observe:
+    output:
+      id: string
+      title: string
+      volume: number
+      temperature: number

package/features/steps/components/users/manifest.toa.yaml

@@ -0,0 +1,11 @@
+name: users
+
+entity:
+  schema:
+    name: string
+
+operations:
+  transit:
+    concurrency: retry
+    input:
+      name*: ~

package/features/steps/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "outDir": "/dev/null",
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}