@toa.io/extensions.exposition 1.0.0-alpha.288 → 1.0.0-alpha.289

package/documentation/introspection.md

@@ -1,7 +1,8 @@
 # Resource introspection
 
 Any resource can be introspected by sending an `OPTIONS` request to the resource's path.
-[Discovery](discovery.md) answers the same of every resource at once.
+[Resource discovery](discovery.md) answers every resource at once, at `OPTIONS /.discovery`, and
+serves a page that reads it.
 
 What it answers is what the route's directives leave of what the operation declared, for each
 method this identity may reach. A method they may not is not there, nor in `Allow`; a resource
@@ -13,13 +14,17 @@ described to whoever asks, as it is at `/.rpc` and `/.mcp`.
 
 What the resource itself is, from [`help:node`](help.md), is answered beside the methods rather
 than inside one. A verb is upper case, so neither key can be mistaken for the other. A resource
-carries `private`, `protected` and `system` where any of its methods does.
+carries `private`, `protected` and `system` where any of its methods does. A method
+[`help:method: null`](help.md) hides is in none of this, and is reached as it always was.
 
 Introspection properties:
 
 - `title` and `description` what the route states this method is, from
   [`help:method`](help.md). The operation states what it is too, and that is not this: it is
   written without knowledge of any route, and the same operation mounted twice is two methods
+- `anonymous` reaching it takes nothing — [`auth:anonymous`](access.md#anonymous). Said rather
+  than left unsaid, because it is also what refuses a caller presenting a credential: a client
+  holding one has to know which methods not to present it to
 - `authenticated` reaching it takes being someone, whoever — [`auth:anyone`](access.md#anyone),
   `auth:delegate` and `auth:claims`
 - `private` reaching it is being the identity it is about — [`auth:id`](access.md#id)
@@ -33,6 +38,9 @@ Introspection properties:
   `omit`, `search` — is not among them: it is the same of every queryable resource, and so
   not something one says about itself. A [procedure](rpc.md) carries it, because there it is
   something the caller sends
+- `octets` what sending a file takes, from [`octets:put`](octets.md): the media types it
+  `accept`s, the `limit` a larger body is refused by, and `stream` where storing it starts a
+  workflow and the reply arrives in parts rather than as one object
 - `input` input schema, restricted by `io:input`, without what the gateway fills itself
 - `output` output schema, restricted by `io:output`; absent where the reply is not sent at all.
   An operation that declares none is described by what its type answers: a transition, an

package/documentation/octets.md

@@ -190,6 +190,26 @@ status: exception
 --cut--
 ```
 
+### What a client is told
+
+`octets:put` says what sending a file takes, where everything else about a method is said —
+[`OPTIONS`](introspection.md) and the [tree](discovery.md):
+
+```yaml
+POST:
+  octets:
+    accept: image/jpeg,image/png
+    limit: 64MiB
+    stream: true
+```
+
+`accept` is absent where the directive names no type, and anything may be sent. `limit` is
+written as the declaration writes it, and is what a `413` reports. `stream` says a workflow runs
+on what was stored, so the reply arrives as parts rather than as one object — the first part is
+the entry.
+
+Reading a file and deleting one say nothing: those requests are what they look like.
+
 ## `octets:get`
 
 Fetches the content of a stored BLOB corresponding to the request path, and returns it as the

package/features/discovery.feature

@@ -133,7 +133,8 @@ Feature: Resource discovery
 
       routes:
         /open:
-          GET: {}
+          GET:
+            anonymous: true
       """
     And the reply does not contain:
       """
@@ -207,5 +208,6 @@ Feature: Resource discovery
 
       routes:
         /pots:
-          GET: {}
+          GET:
+            anonymous: true
       """

package/features/discovery.ui.feature

@@ -156,9 +156,9 @@ Feature: The discovery page
       location: /.discovery/
       """
 
-  Scenario: A client that takes anything is not
-    `accept` has to prefer a page over what the gateway answers with, which is what a
-    browser sends and an API client does not.
+  Scenario: A client that asks for nothing in particular is sent there too
+    Several unfurlers ask for anything at all, and a link to an application would otherwise
+    show nothing.
 
     When the following request is received:
       """
@@ -166,6 +166,22 @@ Feature: The discovery page
       host: nex.toa.io
       accept: */*
       """
+    Then the following reply is sent:
+      """
+      302 Moved Temporarily
+      location: /.discovery/
+      """
+
+  Scenario: A client that asked for something else gets what it asked for
+    An `accept` naming what the gateway answers with is a client that wants the resource,
+    not the page.
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      accept: application/json
+      """
     Then the following reply is sent:
       """
       405 Method Not Allowed

package/features/help.feature

@@ -464,3 +464,49 @@ Feature: Help
       """
       404 Not Found
       """
+
+  Scenario: A method nobody is meant to find
+    `help:method: null` takes the method out of every answer and leaves it as callable as it
+    was — what a monitor reaches for, and what a person has no business going looking for.
+
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        /hello:
+          GET:
+            dev:stub: hi
+          /agent:
+            GET:
+              help:method: null
+              dev:stub: hi
+      """
+    When the following request is received:
+      """
+      OPTIONS /.discovery HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      routes:
+        /hello:
+          GET:
+            anonymous: true
+      """
+    And the reply does not contain:
+      """
+      /hello/agent
+      """
+    # and it answers as it always did
+    When the following request is received:
+      """
+      GET /hello/agent/ HTTP/1.1
+      host: nex.toa.io
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """

package/features/octets.feature

@@ -245,3 +245,62 @@ Feature: Octets directive family
 
       Trailing slash is redundant
       """
+
+  Scenario: What sending a file takes
+    A file is not a value, so no schema states what may be sent — `octets:put` does, and a
+    client reads it where it reads everything else about the method.
+
+    When the following request is received:
+      """
+      OPTIONS /media/jpeg-or-png/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: POST
+
+      POST:
+        octets:
+          accept: image/jpeg,image/png
+          limit: 64MiB
+      """
+
+  Scenario: A limit is what a refusal reports
+    What a larger body is refused by is said the way the refusal says it.
+
+    When the following request is received:
+      """
+      OPTIONS /limit-1kb/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      POST:
+        octets:
+          limit: 1kb
+      """
+
+  Scenario: Reading a file takes nothing to say
+    Only sending one says anything a schema does not; `octets:get` and `octets:delete` are
+    the request they look like.
+
+    When the following request is received:
+      """
+      OPTIONS /media/images/whatever/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: GET
+      """
+    And the reply does not contain:
+      """
+      octets:
+      """

package/features/steps/Components.ts

@@ -5,6 +5,8 @@ import tsflow from 'cucumber-tsflow'
 
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
+import { environment } from '@toa.io/generic'
+
 import { load as parse } from 'js-yaml'
 import { Gateway } from './Gateway.js'
 import { Workspace } from './Workspace.js'
@@ -68,7 +70,7 @@ export class Components {
   /** What the deployment would tell the values service, as the scenario needs it. */
   @given('the configuration values are deployed:')
   public deployValues(yaml: string): void {
-    process.env.TOA_CONFIGURATION_VALUES = JSON.stringify(parse(yaml))
+    environment.set('TOA_CONFIGURATION_VALUES', JSON.stringify(parse(yaml)))
   }
 
   @given('the `{word}` is stopped')
@@ -87,7 +89,7 @@ export class Components {
 
     await Promise.all(promises)
 
-    delete process.env.TOA_CONFIGURATION_VALUES
+    environment.delete('TOA_CONFIGURATION_VALUES')
   }
 
   private async runComponent(name: string, manifest?: object): Promise<void> {

package/features/steps/Database.ts

@@ -45,6 +45,10 @@ export class Database {
       document.CREATED ??= Date.now()
       document.UPDATED ??= document.CREATED
 
+      // a table states a timestamp as the entity carries it; the storage holds it as a date
+      for (const name of TIMESTAMPS)
+        if (typeof document[name] === 'number') document[name] = new Date(document[name])
+
       documents.push(document)
     }
 
@@ -96,5 +100,7 @@ export class Database {
   }
 }
 
+const TIMESTAMPS = ['CREATED', 'UPDATED', 'DELETED']
+
 /** Every fixture table names an `_id`, which is what a row is replaced by. */
-type Document = Record<string, string | number | boolean | null> & { _id: string }
+type Document = Record<string, string | number | boolean | Date | null> & { _id: string }

package/features/steps/Gateway.ts

@@ -2,10 +2,12 @@ import tsflow from 'cucumber-tsflow'
 
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
+import { environment } from '@toa.io/generic'
+
 import { load as parse } from 'js-yaml'
 import { Factory } from '../../source/index.js'
 import * as syntax from '../../source/RTD/syntax/index.js'
-import { shortcuts } from '../../source/Directive.js'
+import { shortcuts } from '../../source/shortcuts.js'
 import { manifests } from './map.js'
 import { PORT, PROBE } from './Parameters.js'
 import type * as http from '../../source/HTTP/index.js'
@@ -26,7 +28,7 @@ export class Gateway {
     if (annotation['/'] !== undefined) {
       const tree = syntax.parse(annotation['/'], shortcuts)
 
-      process.env.TOA_EXPOSITION = JSON.stringify(tree)
+      environment.set('TOA_EXPOSITION', JSON.stringify(tree))
     }
 
     const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
@@ -46,7 +48,7 @@ export class Gateway {
 
     if (mcp !== undefined) properties.mcp = mcp
 
-    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(properties))
   }
 
   /**
@@ -75,8 +77,8 @@ export class Gateway {
       tree.routes.push(...node.routes)
     }
 
-    process.env.TOA_EXPOSITION = JSON.stringify(tree)
-    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(DEFAULT_PROPERTIES)
+    environment.set('TOA_EXPOSITION', JSON.stringify(tree))
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
   }
 
   @given('the `{word}` configuration:')
@@ -90,7 +92,7 @@ export class Gateway {
     // scenario-scoped, as the secrets it may refer to are: a configuration left behind
     // outlives the secrets it points at, and the next scenario cannot resolve them
     this.written.push(key)
-    process.env[key] = JSON.stringify(configuration)
+    environment.set(key, JSON.stringify(configuration))
   }
 
   /** The secrets a scenario's configuration refers to. */
@@ -100,7 +102,7 @@ export class Gateway {
 
     for (const [name, value] of Object.entries(secrets)) {
       this.written.push(SECRET + name)
-      process.env[SECRET + name] = value
+      environment.set(SECRET + name, value)
     }
   }
 
@@ -111,8 +113,11 @@ export class Gateway {
 
   @given('the Gateway is running')
   public async start(): Promise<void> {
-    process.env.TOA_EXPOSITION ??= DEFAULT_TREE
-    process.env.TOA_EXPOSITION_PROPERTIES ??= JSON.stringify(DEFAULT_PROPERTIES)
+    if (!environment.has('TOA_EXPOSITION'))
+      environment.set('TOA_EXPOSITION', DEFAULT_TREE)
+
+    if (!environment.has('TOA_EXPOSITION_PROPERTIES'))
+      environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
 
     this.writeConfiguration()
 
@@ -141,14 +146,11 @@ export class Gateway {
 
   /** What the running gateway was built from: a different value is a different deployment. */
   private static signature(): string {
-    const configuration = Object.keys(process.env)
-      .filter((key) => key.startsWith('TOA_CONFIGURATION_'))
-      .sort()
-      .map((key) => [key, process.env[key]])
+    const configuration = Object.entries(environment.entries('TOA_CONFIGURATION_')).sort()
 
     return JSON.stringify([
-      process.env.TOA_EXPOSITION,
-      process.env.TOA_EXPOSITION_PROPERTIES,
+      environment.get('TOA_EXPOSITION'),
+      environment.get('TOA_EXPOSITION_PROPERTIES'),
       process.env.__TESTING_EXPOSITION_BRANCH_TTL,
       configuration
     ])
@@ -158,12 +160,12 @@ export class Gateway {
   public async cleanup(): Promise<void> {
     delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 
-    for (const key of this.written) delete process.env[key]
+    for (const key of this.written) environment.delete(key)
 
     this.written = []
 
-    delete process.env.TOA_EXPOSITION
-    delete process.env.TOA_EXPOSITION_PROPERTIES
+    environment.delete('TOA_EXPOSITION')
+    environment.delete('TOA_EXPOSITION_PROPERTIES')
   }
 
   @afterAll()
@@ -178,11 +180,11 @@ export class Gateway {
       const [name, namespace = 'default'] = id.split('.').reverse()
       const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
 
-      process.env[key] ??= JSON.stringify(configuration)
+      if (!environment.has(key)) environment.set(key, JSON.stringify(configuration))
     }
 
     for (const [name, value] of Object.entries(DEFAULT_SECRETS))
-      process.env[SECRET + name] ??= value
+      if (!environment.has(SECRET + name)) environment.set(SECRET + name, value)
   }
 }
 
@@ -208,7 +210,7 @@ const DEFAULT_PROPERTIES: Partial<http.Options> = {
   port: PORT,
   probe: PROBE,
   // `npm run features:h2c` runs the whole suite over cleartext HTTP/2
-  protocol: process.env.TOA_EXPOSITION_PROTOCOL === 'h2c' ? 'h2c' : 'h1'
+  protocol: environment.get('TOA_EXPOSITION_PROTOCOL') === 'h2c' ? 'h2c' : 'h1'
 }
 
 // the identity components boot inside the gateway, and without a variable each would wait

package/features/steps/Parameters.ts

@@ -1,6 +1,7 @@
 import { join } from 'node:path'
 import * as dotenv from 'dotenv'
 import { setDefaultTimeout } from '@cucumber/cucumber'
+import { environment as variables } from '@toa.io/generic'
 
 dotenv.config({ path: join(import.meta.dirname, '.env') })
 
@@ -21,24 +22,29 @@ export class Parameters {
 
 setDefaultTimeout(60 * 1000)
 
-process.env.TOA_DEV = '1'
+variables.set('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'
+if (!variables.has('TOA_ENV')) variables.set('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)
+if (!variables.has('TOA_TELEMETRY_READY'))
+  variables.set('TOA_TELEMETRY_READY', JSON.stringify(false))
 
 // export traces to the local Tempo (`docker compose up tempo grafana`),
 // unavailability of the endpoint is harmless
-process.env.TOA_TELEMETRY_TRACES ??= JSON.stringify({
-  exporters: {
-    console: null,
-    otlp: { endpoint: 'http://localhost:31061' }
-  }
-})
+if (!variables.has('TOA_TELEMETRY_TRACES'))
+  variables.set(
+    'TOA_TELEMETRY_TRACES',
+    JSON.stringify({
+      exporters: {
+        console: null,
+        otlp: { endpoint: 'http://localhost:31061' }
+      }
+    })
+  )
 
 /*
  * The page the gateway serves at `/.discovery/`, pointed at a fixture: the scenarios are
@@ -144,10 +150,13 @@ const CLOUDINARY = {
   }
 }
 
-process.env.TOA_STORAGES = JSON.stringify({
-  octets: {
-    provider: 'tmp',
-    directory: Math.random().toString(36).substring(2)
-  },
-  ...(environment === undefined ? {} : CLOUDINARY)
-})
+variables.set(
+  'TOA_STORAGES',
+  JSON.stringify({
+    octets: {
+      provider: 'tmp',
+      directory: Math.random().toString(36).substring(2)
+    },
+    ...(environment === undefined ? {} : CLOUDINARY)
+  })
+)

package/features/steps/Realtime.ts

@@ -4,7 +4,7 @@ import tsflow from 'cucumber-tsflow'
 
 import { Factory } from '@toa.io/extensions.realtime'
 import * as boot from '@toa.io/boot'
-import { match, timeout } from '@toa.io/generic'
+import { environment, match, timeout } from '@toa.io/generic'
 import { load as parse } from 'js-yaml'
 import { Agent } from '@toa.io/agent'
 import { Parameters } from './Parameters.js'
@@ -38,7 +38,7 @@ export class Realtime {
     for (const [event, property] of Object.entries(annotation))
       routes.push({ event, properties: [property] })
 
-    process.env.TOA_REALTIME = JSON.stringify(routes)
+    environment.set('TOA_REALTIME', JSON.stringify(routes))
 
     const factory = new Factory(boot.host())
 
@@ -93,7 +93,7 @@ export class Realtime {
     await this.instance.disconnect()
 
     this.instance = null
-    process.env.TOA_REALTIME = undefined
+    environment.delete('TOA_REALTIME')
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.288",
+  "version": "1.0.0-alpha.289",
   "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -20,9 +20,9 @@
   "dependencies": {
     "@node-rs/bcrypt": "1.10.8",
     "@simplewebauthn/server": "14.0.0",
-    "@toa.io/core": "1.0.0-alpha.288",
-    "@toa.io/generic": "1.0.0-alpha.286",
-    "@toa.io/schemas": "1.0.0-alpha.287",
+    "@toa.io/core": "1.0.0-alpha.289",
+    "@toa.io/generic": "1.0.0-alpha.289",
+    "@toa.io/schemas": "1.0.0-alpha.289",
     "content-type": "3.0.0",
     "jose": "6.2.10",
     "js-yaml": "5.4.1",
@@ -60,5 +60,5 @@
     "@types/cors": "2.8.19",
     "@types/negotiator": "0.6.5"
   },
-  "gitHead": "d3d696f0a4e287c3c297ac81028d600ad7574112"
+  "gitHead": "4fcb482beac5896305d8084cdbc1d5fcf372d108"
 }

package/source/Directive.ts

@@ -246,14 +246,3 @@ interface Stage {
   depart: SpanOptions
 }
 
-export const shortcuts: RTD.syntax.Shortcuts = new Map([
-  ['anonymous', 'auth:anonymous'],
-  ['anyone', 'auth:anyone'],
-  ['id', 'auth:id'],
-  ['role', 'auth:role'],
-  ['rule', 'auth:rule'],
-  ['incept', 'auth:incept'],
-  ['input', 'io:input'],
-  ['output', 'io:output'],
-  ['languages', 'map:languages']
-])

package/source/Discovery/trunk.ts

@@ -11,13 +11,23 @@ const HTML = 'text/html'
  * and `/` is usually not one of those — a person who typed the address into a browser is
  * looking for something to look at, and the page is the only thing here that is one.
  *
- * A client that takes anything is not one: `accept` has to prefer a page over what the
- * gateway answers with, which is what a browser sends and an API client does not.
+ * A client that asked for something in particular gets what it asked for: only an `accept`
+ * that prefers a page, or one that names no preference at all, is sent here. The second is
+ * what an unfurler sends — several ask for anything, and a link to an application would
+ * otherwise show nothing — and what `curl` sends, which the page serves no worse than the
+ * `405` it used to get.
  */
 export function looking(context: Context): OutgoingMessage | null {
   if (context.request.method !== 'GET' || context.procedural) return null
 
-  if (new Negotiator(context.request).mediaType([...types, HTML]) !== HTML) return null
+  const accept = context.request.headers.accept
+
+  if (accept !== undefined && accept.trim() !== ANYTHING) {
+    if (new Negotiator(context.request).mediaType([...types, HTML]) !== HTML) return null
+  }
 
   return { status: 302, headers: new Headers({ location: DISCOVERY + '/' }) }
 }
+
+/** An `accept` that names nothing, which is the same as naming none. */
+const ANYTHING = '*/*'