@toa.io/extensions.exposition 1.0.0-alpha.282 → 1.0.0-alpha.284

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/steps/Cloudinary.ts

@@ -0,0 +1,13 @@
+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/Components.ts

@@ -4,7 +4,6 @@ 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 { load as parse } from 'js-yaml'
 import { Gateway } from './Gateway.js'
@@ -49,7 +48,6 @@ export class Components {
     this.compositions[MAP] = await boot.composition(map())
 
     await this.compositions[MAP].connect()
-    await timeout(50) // discovery
   }
 
   /** The values component, as the configuration extension ships it; the service hosts it alone. */
@@ -62,7 +60,6 @@ export class Components {
     this.compositions[VALUES] = await boot.composition([values()])
 
     await this.compositions[VALUES].connect()
-    await timeout(50) // discovery
   }
 
   /** What the deployment would tell the values service, as the scenario needs it. */
@@ -101,7 +98,6 @@ export class Components {
     this.compositions[name] = await boot.composition([path])
 
     await this.compositions[name].connect()
-    await timeout(50) // discovery
   }
 }
 

package/features/steps/Gateway.ts

@@ -29,7 +29,7 @@ export class Gateway {
       process.env.TOA_EXPOSITION = JSON.stringify(tree)
     }
 
-    const { debug, authorities, bouncer, ip } = annotation
+    const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
     const properties = Object.assign({}, DEFAULT_PROPERTIES)
 
     if (debug !== undefined)
@@ -44,6 +44,15 @@ export class Gateway {
     if (authorities !== undefined)
       properties.authorities = authorities
 
+    if (oauth !== undefined)
+      properties.oauth = oauth
+
+    if (rpc !== undefined)
+      properties.rpc = rpc
+
+    if (mcp !== undefined)
+      properties.mcp = mcp
+
     process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
 
     await Gateway.stop()
@@ -145,7 +154,14 @@ export class Gateway {
     instance = service
 
     await service.connect()
-    await timeout(50) // resource discovery
+
+    /*
+     * The gateway waits for the branches it discovers, but a component's own resources —
+     * a storage, a queue — are still connecting when it answers. Fifty milliseconds was
+     * enough until the composition grew; a scenario that asks too early reads the 404 that
+     * precedes the route.
+     */
+    await timeout(DISCOVERY)
   }
 
   @after()
@@ -200,6 +216,9 @@ const DEFAULT_TREE = JSON.stringify({
   ]
 } satisfies syntax.Node)
 
+/** Milliseconds a composition is given to finish connecting what it needs. */
+const DISCOVERY = 100
+
 const DEFAULT_PROPERTIES: Partial<http.Options> = {
   authorities: {
     nex: 'nex.toa.io'
@@ -215,6 +234,8 @@ const DEFAULT_CONFIGURATION: Record<string, object> = {
   // features do not run; the variable is the local override that stands in for it
   'realtime.streams': {},
   'identity.basic': {},
+  'identity.clients': {},
+  'identity.grants': {},
   'identity.federation': {},
   'identity.otp': {},
   'identity.passkeys': {},

package/features/steps/Parameters.ts

@@ -16,6 +16,10 @@ setDefaultTimeout(60 * 1000)
 
 process.env.TOA_DEV = '1'
 
+// a reply is checked against what the operation declares, so the suite runs Toa under the
+// contract it asks applications to keep
+process.env.TOA_ENV ??= 'local'
+
 // the gateway answers for itself, as it does in a deployment: telemetry's probe tracks the
 // nested composition, which connects before route discovery settles
 process.env.TOA_TELEMETRY_READY ??= JSON.stringify(false)
@@ -29,14 +33,17 @@ process.env.TOA_TELEMETRY_TRACES ??= JSON.stringify({
   }
 })
 
-process.env.TOA_STORAGES = JSON.stringify({
-  octets: {
-    provider: 'tmp',
-    directory: Math.random().toString(36).substring(2)
-  },
+const environment = process.env.CLOUDINARY_ENVIRONMENT
+
+/**
+ * A storage is built when a component's context is — for every scenario, not only for the ones
+ * that reach for it — and a Cloudinary storage asks for the keys of a real account. A checkout
+ * carries none, so these two are declared only where `features/steps/.env` names an environment.
+ */
+const CLOUDINARY = {
   cloudinary: {
     provider: 'cloudinary',
-    environment: process.env.CLOUDINARY_ENVIRONMENT ?? 'nope',
+    environment,
     type: 'image',
     prefix: 'toa-dev',
     transformations: [
@@ -83,7 +90,7 @@ process.env.TOA_STORAGES = JSON.stringify({
   },
   cloudinary_video: {
     provider: 'cloudinary',
-    environment: process.env.CLOUDINARY_ENVIRONMENT ?? 'nope',
+    environment,
     type: 'video',
     prefix: 'toa-dev',
     eager: [
@@ -113,4 +120,12 @@ process.env.TOA_STORAGES = JSON.stringify({
       }
     ]
   }
+}
+
+process.env.TOA_STORAGES = JSON.stringify({
+  octets: {
+    provider: 'tmp',
+    directory: Math.random().toString(36).substring(2)
+  },
+  ...(environment === undefined ? {} : CLOUDINARY)
 })

package/features/steps/Realtime.ts

@@ -44,6 +44,8 @@ export class Realtime {
 
     Realtime.instance = await factory.service()
 
+    // not awaited: the routes connect to the components that produce the events, and this
+    // scenario starts the producer after the service, so the connection settles later
     void Realtime.instance.connect()
   }
 
@@ -152,3 +154,4 @@ export class Realtime {
     }
   }
 }
+

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

@@ -31,6 +31,7 @@ operations:
           type: object
       type: object
   parameters:
+    description: Answers with what it was given.
     input:
       type: object
       properties:
@@ -54,3 +55,5 @@ operations:
       properties:
         buf:
           type: string
+  error:
+    errors: [CODE]

package/features/steps/components/octets.tester/manifest.toa.yaml

@@ -5,6 +5,7 @@ storages: octets
 
 operations:
   foo: &operation
+    errors: [ERROR, NOT_FOUND]
     input:
       properties:
         identity:
@@ -38,6 +39,7 @@ operations:
   authority: *operation
   identity: *operation
   redirect:
+    errors: [ERROR]
     input:
       properties:
         parameters:

package/features/steps/components/octets.tester/operations/redirect.js

@@ -1,7 +1,12 @@
 function redirect (input) {
-  return input.parameters.type in urls ? { url: urls[input.parameters.type] } : new Error()
+  return input.parameters.type in urls ? { url: urls[input.parameters.type] } : ERR_UNKNOWN
 }
 
+// an error a caller is meant to see carries a code, always
+const ERR_UNKNOWN = new (class UnknownError extends Error {
+  code = 'ERROR'
+})()
+
 const urls = {
   'rfc': 'https://www.rfc-editor.org/rfc/rfc9564.txt',
   'img': 'https://www.w3.org/assets/logos/w3c/w3c-no-bars.svg'

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

@@ -24,6 +24,7 @@ entity:
 
 operations:
   create:
+    description: Put a pot on to brew.
     query: false
     forward: transit
     input:
@@ -71,6 +72,7 @@ operations:
           type: number
       type: object
   enumerate:
+    description: Every pot there is.
     output:
       type: array
       items:

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

@@ -21,6 +21,7 @@ operations:
   create:
     concurrency: retry
     query: false
+    errors: [0]
     input:
       properties:
         name: