@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/features/rpc.feature

@@ -0,0 +1,429 @@
+Feature: JSON-RPC
+
+  A procedure is an RTD method addressed by name: the route template with its variables
+  marked, and the verb as the last segment. Nothing is declared for it — what is exposed as
+  a resource is exposed as a procedure, under the same directives.
+
+  Background:
+    Given the annotation:
+      """yaml
+      rpc: {}
+      """
+    And the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          io:output: true
+          anonymous: true
+          GET: enumerate
+          POST: create
+          /:id:
+            GET: observe
+          /guarded:
+            isolated: true
+            GET:
+              auth:role: admin
+              dev:stub: never
+          /faulty:
+            GET:
+              dev:throw: nope
+          /v1.0:
+            GET:
+              dev:stub: never
+      """
+    And the `pots` database contains:
+      | _id                              | title     | volume |
+      | 4c4759e6f9c74da989d64511df42d6f4 | First pot | 100    |
+
+  Scenario: A variable is taken from the parameters
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "pots._id.GET",
+       "params": {"id": "4c4759e6f9c74da989d64511df42d6f4"}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      cache-control: no-store
+
+      jsonrpc: '2.0'
+      id: 1
+      result:
+        id: 4c4759e6f9c74da989d64511df42d6f4
+        title: First pot
+        volume: 100
+      """
+
+  Scenario: What is left of the parameters is the input
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 2, "method": "pots.POST",
+       "params": {"title": "Kettle", "volume": 1.7}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 2
+      result:
+        id:
+      """
+
+  Scenario: A query travels under a name of its own
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 3, "method": "pots.GET",
+       "params": {"query": {"limit": 1}}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 3
+      result:
+        - id: 4c4759e6f9c74da989d64511df42d6f4
+      """
+
+  Scenario: A call without an id answers nothing
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Pot", "volume": 1}}
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """
+
+  Scenario: A name nothing answers to
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 4, "method": "kettles.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 4
+      error:
+        code: -32601
+      """
+
+  Scenario: A credential does not refuse an anonymous procedure
+    What refuses a credentialed request at an `anonymous` route is that the reply would not
+    be cacheable, and what a procedure answers is not a reply.
+
+    # developer:secret
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the `identity.bans` database is empty
+    When the following request is received:
+      """
+      GET /pots/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 17, "method": "pots.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 17
+      result:
+        - id: 4c4759e6f9c74da989d64511df42d6f4
+      """
+
+  Scenario: A route no name can spell
+    A segment holding a `.` or a `_` has no name, so nothing addresses it — the resource
+    itself is served over HTTP as it always was.
+
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 16, "method": "pots/v1.0/GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 16
+      error:
+        code: -32601
+      """
+    When the following request is received:
+      """
+      GET /pots/v1.0/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: A variable the parameters do not carry
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 5, "method": "pots._id.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 5
+      error:
+        code: -32602
+      """
+
+  Scenario: A call that fails is a value, not a status
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 6, "method": "pots.faulty.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 6
+      error:
+        code: -32603
+      """
+
+  Scenario: A credential is the request's, so a call cannot be refused for one
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 7, "method": "pots.guarded.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: A request may carry several calls
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      [{"jsonrpc": "2.0", "id": 8, "method": "pots._id.GET",
+        "params": {"id": "4c4759e6f9c74da989d64511df42d6f4"}},
+       {"jsonrpc": "2.0", "id": 9, "method": "kettles.GET", "params": {}},
+       {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Pot", "volume": 1}}]
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      - jsonrpc: '2.0'
+        id: 8
+        result:
+          id: 4c4759e6f9c74da989d64511df42d6f4
+          title: First pot
+      - jsonrpc: '2.0'
+        id: 9
+        error:
+          code: -32601
+      """
+
+  Scenario: What a request took is said once, whatever it carried
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      [{"jsonrpc": "2.0", "id": 13, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 14, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 15, "method": "pots.GET", "params": {}}]
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    # the stages of a call are measured per call, and a trace is where they are read
+    And the reply does not contain:
+      """
+      precall
+      """
+
+  Scenario: A request of notifications alone answers nothing
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      content-type: application/json
+
+      [{"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "One", "volume": 1}},
+       {"jsonrpc": "2.0", "method": "pots.POST", "params": {"title": "Two", "volume": 2}}]
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """
+
+  Scenario: A request carries at least one call
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      []
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      jsonrpc: '2.0'
+      id:
+      error:
+        code: -32600
+      """
+
+  Scenario: A call that is not one is answered to nobody
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "1.0", "id": 10, "method": "pots.GET"}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id:
+      error:
+        code: -32600
+      """
+
+  Scenario: The endpoint answers POST alone
+    When the following request is received:
+      """
+      GET /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      405 Method Not Allowed
+      allow: POST
+      """
+
+  Scenario: What a request may carry at once is bounded
+    Given the annotation:
+      """yaml
+      rpc:
+        batch: 1
+      """
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      [{"jsonrpc": "2.0", "id": 11, "method": "pots.GET", "params": {}},
+       {"jsonrpc": "2.0", "id": 12, "method": "pots.GET", "params": {}}]
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      jsonrpc: '2.0'
+      id:
+      error:
+        code: -32002
+      """
+
+  Scenario: Nothing is served where it was not asked for
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        anonymous: true
+      """
+    When the following request is received:
+      """
+      POST /.rpc HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 9, "method": "pots.GET", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      404 Not Found
+      """

package/features/server.feature

@@ -0,0 +1,21 @@
+Feature: `Server` response header
+
+  Scenario: `Server` response header
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          anonymous: true
+          dev:stub:
+            access: granted!
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      server: Exposition/
+      """

package/features/site/_app/immutable/asset.js

@@ -0,0 +1 @@
+export const hashed = true

package/features/site/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<!-- stands in for what `ui` builds; the scenarios are about the server, not the page -->
+<html lang="en">
+  <head>
+    <title>fixture</title>
+  </head>
+  <body>
+    the page
+  </body>
+</html>

package/features/steps/.env.example

@@ -0,0 +1,5 @@
+CLOUDINARY_ENVIRONMENT=
+TOA_STORAGES_CLOUDINARY_API_KEY=
+TOA_STORAGES_CLOUDINARY_API_SECRET=
+TOA_STORAGES_CLOUDINARY_VIDEO_API_KEY=
+TOA_STORAGES_CLOUDINARY_VIDEO_API_SECRET=

package/features/steps/Captures.ts

@@ -1,6 +1,20 @@
 import * as http from '@toa.io/agent'
-import { binding } from 'cucumber-tsflow'
+import tsflow from 'cucumber-tsflow'
+
+const { binding } = tsflow
 
 @binding()
 export class Captures extends http.Captures {
+  public constructor() {
+    super(functions)
+  }
+}
+
+const functions: http.Functions = {
+  otp: function (this: Captures, value: string, arg: string): string {
+    const identity = this.get(arg + '.id')
+    const code = this.get(arg + '.code')
+
+    return Buffer.from(`${identity}:${code}`).toString('base64')
+  }
 }

package/features/steps/Cloudinary.ts

@@ -0,0 +1,12 @@
+import { Before } from '@cucumber/cucumber'
+
+/**
+ * The Cloudinary scenarios upload to a real account, named by `features/steps/.env` — the
+ * environment and the keys `.env.example` lists. A checkout carries none, and an account is
+ * not something a run can stand up for itself, the way the compose file stands up a database.
+ * Without one the scenarios are skipped rather than failed, so `npm run features` answers on a
+ * fresh machine; with one they run, no flag to remember.
+ */
+Before({ tags: '@cloudinary' }, function () {
+  if (process.env.CLOUDINARY_ENVIRONMENT === undefined) return 'skipped'
+})

package/features/steps/Common.ts

@@ -1,10 +1,38 @@
-import { binding, given } from 'cucumber-tsflow'
+import * as assert from 'node:assert'
+import tsflow from 'cucumber-tsflow'
 import { timeout } from '@toa.io/generic'
+import { Captures } from './Captures.js'
 
-@binding()
+const { binding, given } = tsflow
+
+@binding([Captures])
 export class Common {
+  private readonly captures: Captures
+
+  public constructor(captures: Captures) {
+    this.captures = captures
+  }
+
   @given('after {float} second(s)')
-  public async timeout (interval: number): Promise<void> {
+  public async timeout(interval: number): Promise<void> {
     await timeout(interval * 1000)
   }
+
+  @given('the process is running')
+  public async noop(): Promise<void> {}
+
+  /**
+   * A remote resource is whatever it is today. A scenario downloading one compares the reply
+   * against what the origin actually serves, not against a literal that goes stale when it changes.
+   */
+  @given('the length of `{}` is captured as `{word}`')
+  public async length(url: string, name: string): Promise<void> {
+    const response = await fetch(url)
+
+    assert.equal(response.status, 200, `${url} answered ${response.status}`)
+
+    const body = await response.arrayBuffer()
+
+    this.captures.set(name, String(body.byteLength))
+  }
 }

package/features/steps/Components.ts

@@ -1,34 +1,80 @@
+import { createRequire } from 'node:module'
 import * as assert from 'node:assert'
-import { after, binding, given } from 'cucumber-tsflow'
+import { dirname, join } from 'node:path'
+import tsflow 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'
+import { environment } from '@toa.io/generic'
+
+import { load as parse } from 'js-yaml'
+import { Gateway } from './Gateway.js'
+import { Workspace } from './Workspace.js'
+import { components as map } from './map.js'
+
+const { after, binding, given } = tsflow
 
-@binding([Workspace])
+const require = createRequire(import.meta.url)
+
+const MAP = 'introspection'
+const VALUES = 'configuration'
+
+@binding([Workspace, Gateway])
 export class Components {
   private readonly workspace: Workspace
+  private readonly gateway: Gateway
   private compositions: Record<string, Connector> = {}
 
-  public constructor (workspace: Workspace) {
+  public constructor(workspace: Workspace, gateway: Gateway) {
     this.workspace = workspace
+    this.gateway = gateway
   }
 
   @given('the `{word}` is running')
-  public async run (name: string): Promise<void> {
+  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)
+  public async patchAndRun(name: string, yaml: string): Promise<void> {
+    const manifest = parse(yaml) as object
 
     await this.runComponent(name, manifest)
   }
 
+  /** One composition, as the explorer hosts them. */
+  @given('the introspection components are running')
+  public async runMap(): Promise<void> {
+    assert.ok(!(MAP in this.compositions), `Composition '${MAP}' is already running`)
+
+    this.compositions[MAP] = await boot.composition(map())
+
+    await this.compositions[MAP].connect()
+  }
+
+  /** The values component, as the configuration extension ships it; the service hosts it alone. */
+  @given('the configuration values are running')
+  public async runValues(): Promise<void> {
+    assert.ok(
+      !(VALUES in this.compositions),
+      `Composition '${VALUES}' is already running`
+    )
+
+    await this.gateway.start()
+
+    this.compositions[VALUES] = await boot.composition([values()])
+
+    await this.compositions[VALUES].connect()
+  }
+
+  /** What the deployment would tell the values service, as the scenario needs it. */
+  @given('the configuration values are deployed:')
+  public deployValues(yaml: string): void {
+    environment.set('TOA_CONFIGURATION_VALUES', JSON.stringify(parse(yaml)))
+  }
+
   @given('the `{word}` is stopped')
-  public async stop (name: string): Promise<void> {
+  public async stop(name: string): Promise<void> {
     assert.ok(name in this.compositions, `Composition '${name}' is not running`)
 
     await this.compositions[name].disconnect()
@@ -36,20 +82,34 @@ export class Components {
   }
 
   @after()
-  public async shutdown (): Promise<void> {
-    const promises = Object.values(this.compositions).map((composition) => composition.disconnect())
+  public async shutdown(): Promise<void> {
+    const promises = Object.values(this.compositions).map((composition) =>
+      composition.disconnect()
+    )
 
     await Promise.all(promises)
+
+    environment.delete('TOA_CONFIGURATION_VALUES')
   }
 
-  private async runComponent (name: string, manifest?: object): Promise<void> {
+  private async runComponent(name: string, manifest?: object): Promise<void> {
     assert.ok(!(name in this.compositions), `Composition '${name}' is already running`)
 
+    // the gateway first: a component announces itself when it opens, and that only
+    // reaches a gateway that is already listening. Started the other way round, the
+    // component waits for a knock, which the request that follows does not.
+    await this.gateway.start()
+
     const path = await this.workspace.addComponent(name, manifest)
 
     this.compositions[name] = await boot.composition([path])
 
     await this.compositions[name].connect()
-    await timeout(50) // discovery
   }
 }
+
+function values(): string {
+  const root = dirname(require.resolve('@toa.io/extensions.configuration/package.json'))
+
+  return join(root, 'components', 'configuration.values')
+}