@toa.io/extensions.exposition 1.0.0-alpha.283 → 1.0.0-alpha.285

package/features/oauth.discovery.feature

@@ -11,14 +11,10 @@ Feature: Authorization server discovery
         nex: nex.toa.io
       oauth:
         authorize: https://app.nex.toa.io/oauth/authorize
-        resources: ['/mcp/']
+        resources: ['/.mcp']
         scopes: [app:notes]
-      /:
-        io:output: true
-        /mcp/**:
-          anyone: true
-          GET:
-            dev:stub: Tools
+      mcp:
+        name: Teapots
       """
 
   Scenario: The authorization server names its endpoints
@@ -64,7 +60,7 @@ Feature: Authorization server discovery
   Scenario: The protected resource is named by the path it is reached at
     When the following request is received:
       """
-      GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
+      GET /.well-known/oauth-protected-resource/.mcp HTTP/1.1
       host: nex.toa.io
       accept: application/yaml
       """
@@ -72,7 +68,7 @@ Feature: Authorization server discovery
       """
       200 OK
 
-      resource: https://nex.toa.io/mcp
+      resource: https://nex.toa.io/.mcp
       authorization_servers:
         - https://nex.toa.io
       bearer_methods_supported:
@@ -119,14 +115,17 @@ Feature: Authorization server discovery
   Scenario: The challenge names the resource the request was refused at
     When the following request is received:
       """
-      GET /mcp/tools/ HTTP/1.1
+      POST /.mcp HTTP/1.1
       host: nex.toa.io
       accept: text/plain
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
       """
     Then the following reply is sent:
       """
       401 Unauthorized
-      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/mcp", scope="app:notes"
+      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/.mcp", scope="app:notes"
       """
 
   Scenario: A host named after a property a plain object answers on its own

package/features/oauth.grants.feature

@@ -17,14 +17,17 @@ Feature: Authorization code flow
         nex: nex.toa.io
       oauth:
         authorize: https://app.nex.toa.io/oauth/authorize
-        resources: ['/mcp/']
+        resources: ['/.mcp']
         registration: open
+      mcp:
+        name: Teapots
       /:
         io:output: true
-        /mcp/**:
+        /pots:
           anyone: true
           GET:
-            dev:stub: Tools
+            mcp:tool: Every pot there is.
+            dev:stub: Kettles and teapots.
       """
     When the following request is received:
       """
@@ -69,14 +72,17 @@ Feature: Authorization code flow
     # nothing yet, and the client is told where to get one
     When the following request is received:
       """
-      GET /mcp/tools/ HTTP/1.1
+      POST /.mcp HTTP/1.1
       host: nex.toa.io
-      accept: text/plain
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
       """
     Then the following reply is sent:
       """
       401 Unauthorized
-      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/mcp"
+      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/.mcp"
       """
     When the following request is received:
       """
@@ -97,16 +103,23 @@ Feature: Authorization code flow
       """
     When the following request is received:
       """
-      GET /mcp/tools/ HTTP/1.1
+      POST /.mcp HTTP/1.1
       host: nex.toa.io
       authorization: Bearer ${{ access_token }}
-      accept: text/plain
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
       """
     Then the following reply is sent:
       """
       200 OK
 
-      Tools
+      jsonrpc: '2.0'
+      id: 1
+      result:
+        tools:
+          - name: pots.GET
       """
 
   Scenario: A code is spent once

package/features/octets.cloudinary.feature

@@ -1,3 +1,4 @@
+@cloudinary
 Feature: Octets with Cloudinary storage
 
   Background:

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, oauth } = annotation
+    const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
     const properties = Object.assign({}, DEFAULT_PROPERTIES)
 
     if (debug !== undefined)
@@ -47,6 +47,12 @@ export class Gateway {
     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()
@@ -148,7 +154,15 @@ 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, then a hundred; a scenario that asks too early
+     * reads the 404 that precedes the route, which `realtime` was failing on in two runs
+     * of three. It is a sleep and not a poll, so it is raised rather than fixed.
+     */
+    await timeout(DISCOVERY)
   }
 
   @after()
@@ -203,6 +217,9 @@ const DEFAULT_TREE = JSON.stringify({
   ]
 } satisfies syntax.Node)
 
+/** Milliseconds a composition is given to finish connecting what it needs. */
+const DISCOVERY = 500
+
 const DEFAULT_PROPERTIES: Partial<http.Options> = {
   authorities: {
     nex: 'nex.toa.io'

package/features/steps/Parameters.ts

@@ -33,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: [
@@ -87,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: [
@@ -117,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)
 })