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

package/documentation/discovery.md

@@ -0,0 +1,81 @@
+# Resource discovery
+
+Everything an application serves, at one path, and a page to read it with.
+
+```http
+OPTIONS /.discovery HTTP/1.1
+accept: application/yaml
+```
+
+```http
+200 OK
+Allow: GET, HEAD, OPTIONS
+cache-control: private, max-age=1800
+
+routes:
+  /pots:
+    title: Pots
+    GET:
+      title: Every pot
+      description: Every pot there is, newest first.
+      output:
+        type: array
+        items:
+          type: object
+          properties:
+            title: { type: string, maxLength: 64 }
+    POST:
+      input:
+        type: object
+        properties:
+          title: { type: string, maxLength: 64 }
+        required: [title]
+      errors:
+        - NO_WAY
+  /pots/:id:
+    protected: true
+    GET:
+      protected: true
+      route:
+        id: { title: Which pot }
+```
+
+`routes` is keyed by route template, and an object so that what is said of the whole tree has
+somewhere to go. What a key maps to is what [`OPTIONS`](introspection.md) on that path
+answers — what the resource is, from [`help:node`](help.md), beside every method of it — so a key
+can be read from here and sent straight back as a request. A method this identity may not reach is
+not in either, and a resource they may reach no method of is not here at all — so what a reader
+sees is what they may call, and signing in is what adds to it.
+
+A key carries no trailing slash, and a request needs one: `OPTIONS /pots/:id` and
+`OPTIONS /pots/:id/` both answer, but `GET /pots/:id` is `404` and `GET /pots/:id/` is the call.
+Append it.
+
+Held for half an hour, and `private`: what is in it is what the identity that asked may reach.
+
+## The page
+
+`GET /.discovery/` is a page that reads the tree, served from the same origin the API is. It
+answers before a credential is read, so it opens for a client whose token has expired — which is
+the client most likely to be looking.
+
+A method is called from it: the verb is a button, what the method takes is a form, and what came
+back is shown where the form was. The call is made as whoever is reading — the same request they
+would send themselves, and with the same effect.
+
+A `GET /` whose `accept` prefers a page is sent here, so the address of the application opens it
+in a browser. A route declared at `/` answers `/` as it always did; this is only what stands where
+an application serves nothing there.
+
+## What it is not
+
+Neither is annotated, and both answer wherever a gateway does. What each entry says is what
+`OPTIONS` on that path already says to the same caller, but the enumeration is not otherwise
+available: an application that does not publish its routes to everyone refuses `/.discovery` at
+the ingress.
+
+## References
+
+- [Introspection](introspection.md), which is what an entry is
+- [Help](help.md), which is what names one
+- [Features](../features/discovery.feature)

package/documentation/help.md

@@ -0,0 +1,109 @@
+# Help
+
+What a resource and its methods are, in the words an application chooses for them. One
+declaration, read by everything that describes a resource: [`OPTIONS`](introspection.md),
+[discovery](discovery.md), and the tools [MCP](mcp.md) publishes.
+
+```yaml
+/pots:
+  help:node: Pots
+  GET:
+    help:method: Every pot
+    help:query:
+      criteria:
+        title: What to match
+        description: An RSQL expression over a pot's fields.
+    endpoint: enumerate
+  /:id:
+    GET:
+      help:method:
+        title: One pot
+        description: The pot by its id, and what is in it.
+      help:route:
+        id: Which pot
+      endpoint: observe
+```
+
+<dl>
+<dt><code>help:node</code></dt>
+<dd>What the resource is.</dd>
+<dt><code>help:method</code></dt>
+<dd>What one of its methods is.</dd>
+<dt><code>help:route</code></dt>
+<dd>What a route variable is, by the name the template gives it.</dd>
+<dt><code>help:query</code></dt>
+<dd>What a querystring parameter is, by name.</dd>
+</dl>
+
+All four take the same value. A bare one is the <code>title</code> — the short thing, and what a
+client has somewhere to put. A sentence is written as a <code>description</code> beside it, and
+either may stand alone. The parameters name each one they describe.
+
+A title is not a name. A name is an address — `apps._identity._id.repos.POST` — and reads as one;
+this is what a person is shown instead.
+
+An operation [states what it is](/documentation/component/declaration.md) as well, and that is not
+this: it is written without knowledge of any route, and a method is an operation and a route
+together. The same operation mounted twice is two methods, and one sentence is not true of both.
+The operation's own is the Introspection's to read, and the gateway does not use it.
+
+## Where it is answered
+
+`help:node` is answered beside the methods, and `help:method` inside the method it is on. A verb
+is upper case, so neither key can be mistaken for the other. A parameter's goes in its schema,
+which is where a schema says these anyway:
+
+```yaml
+title: Pots
+GET:
+  title: Every pot
+  query:
+    criteria:
+      type: string
+      title: What to match
+      description: An RSQL expression over a pot's fields.
+```
+
+Describe a parameter by the name the answer carries it under. `map:segments` answers a variable
+under the property it fills, so that is its name here and the template's is nowhere in the answer.
+
+A route variable the template names is answered whether or not the operation declares it — an `:id`
+an observation takes through the query is otherwise not in the answer at all, and describing it is
+what puts it there. Anything else is described only where it is already answered. A name that is
+nobody's is not answered, and nothing here checks one: the template does not say them all.
+
+`help:query` describes the [parameters a resource declares](query.md#parameters). What selects
+records — `criteria`, `sort` and the rest — is the same of every queryable resource and says so
+itself, so it is neither answered here nor described.
+
+## What it is not inherited by
+
+Every other directive applies to everything below the node it is on. This one does not: carried
+downward, it would say of every resource below that it is the one it was written for.
+
+```yaml
+/pots:
+  help:node: Pots      # `/pots`, and not `/pots/:id`
+  GET: enumerate
+  /:id:
+    GET: observe
+```
+
+A node whose `/` answers in its place is the exception, because the two are one resource:
+
+```yaml
+/pots:
+  help:node: Pots      # `/pots/` is what answers, and it is described
+  /:
+    GET: enumerate
+```
+
+A resource is described beside what it serves, so a node that serves nothing cannot be described.
+Declaring it there is refused where it is written, rather than found missing from the answer.
+
+## References
+
+- [Resource introspection](introspection.md), which is where a method's own is answered
+- [Resource discovery](discovery.md), which answers every resource at once
+- [MCP](mcp.md), where a published method is a tool called this
+- [Features](../features/help.feature)

package/documentation/introspection.md

@@ -1,21 +1,46 @@
 # 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.
 
 What it answers is what the route's directives leave of what the operation declared, for each
-method the request may reach. A method it may not is not there, nor in `Allow`; a resource whose
-every method it may not reach is `403`.
+method this identity may reach. A method they may not is not there, nor in `Allow`; a resource
+whose every method they may not reach is `403`.
+
+A credential does not narrow it. What refuses one at an [`anonymous`](access.md#anonymous) route
+is about a reply a cache would hold, and a description is not one — so a route that is public is
+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.
 
 Introspection properties:
 
-- `description` what the route states this method is, from [`mcp:tool`](mcp.md#what-a-tool-is).
-  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
-- `route` route parameters, including what `map:segments` names differently
-- `query` query parameters
-- `headers` properties `map:headers` reads from a request header, and which header
+- `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
+- `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)
+- `protected` reaching it takes a role — [`auth:role`](access.md#role)
+- `system` and that role is one of the `system` scope, which guards what an application runs
+  on rather than what it serves
+- `route` route parameters, including what `map:segments` names differently, each as
+  [`help:route`](help.md) describes it
+- `query` the [query parameters](query.md#parameters) this resource declares, each as
+  [`help:query`](help.md) describes it. What selects records — `criteria`, `sort`, `limit`,
+  `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
 - `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
+- `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
+  observation and an assignment work on the Entity Object, so that is what they are said to
+  answer — a set of them where the scope is a set. A computation neither uses the scope nor
+  produces one, and an effect answers whatever it computed, so neither is guessed at. It is a
+  description and nothing is held to it — an operation answering a projection says so by
+  declaring its own `output`
 - `errors` error codes
 
 ```http

package/documentation/mcp.md

@@ -32,12 +32,14 @@ A tool is an RTD method that says it is one, named as the [procedure](rpc.md#the
 ```yaml
 /pots:
   GET:
-    mcp:tool: Every pot there is, newest first.
+    mcp:tool: true
+    help:method: Every pot there is, newest first.
     endpoint: enumerate
   /hot:
     GET:
       query: { criteria: temperature=gt=80 }
-      mcp:tool:
+      mcp:tool: true
+      help:method:
         title: Hot pots
         description: The pots that are too hot to pour.
       endpoint: enumerate
@@ -47,21 +49,12 @@ A default denies, and a tree holds everything an application serves — its iden
 uploads, the machinery of the authorization flow the model already came through. Publishing all of
 it would spend a model's context on what it has no business calling.
 
-The value is what the tool is, and stating it is what publishes it — there is no way to publish one
-that says nothing, because a tool a model cannot read the purpose of is one it cannot choose.
+`mcp:tool` says only whether the method is published. What the tool is called and what it is for is
+[`help:method`](help.md), which is what describes the method everywhere else as well — a tool a
+model cannot read the purpose of is one it cannot choose, so declare one beside the other.
 
-A `title` is what a person is shown where a client lists what it may call. Without one a client has
-only the name, which is an address — `apps._identity._id.repos.POST` — and reads as one. A
-description alone is written as the value; a title beside it is written as a mapping.
-
-An operation [states what it is](/documentation/component/declaration.md) as well, and that is not
-this: it is written without knowledge of any route, and a tool is an operation and a route together.
-The two routes above are one operation and two tools, and one sentence is not true of both. The
-operation's own is the Introspection's to read, and the gateway does not use it.
-
-A declaration is inherited by everything below it, as every directive is, and the nearer one wins.
-Since what it carries is what one method is, it belongs on a method: a node stating one would say
-the same thing of everything under it.
+A declaration is inherited by everything below it, as every directive is, and the nearer one wins —
+so a node publishes a subtree, and `mcp:tool: false` withdraws one method of it.
 
 A route whose name a client [cannot spell](rpc.md#what-has-a-name) is refused where the directive
 is built, rather than served as a tool that is quietly never listed.
@@ -81,6 +74,10 @@ application did not publish is not reachable by guessing what it would have been
 querystring under `query`, and what is left is the body. `io:input` restricts it, and a property
 `map` fills is not there — a call carries no headers of its own.
 
+`query` carries what selects records — `criteria`, `sort`, `limit`, `omit`, `search` — beside the
+parameters the resource declares. `OPTIONS` states only the latter, because the former is the same
+of every queryable resource; here it is stated, because here it is something the caller sends.
+
 ```yaml
 type: object
 properties:

package/features/cors.feature

@@ -13,6 +13,7 @@ Feature: CORS Support
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       host: nex.toa.io
       origin: https://hello.world
       """
@@ -21,7 +22,7 @@ Feature: CORS Support
       204 No Content
       access-control-allow-credentials: true
       access-control-allow-headers: accept, authorization, content-type, if-match, if-none-match
-      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK
+      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS
       access-control-allow-origin: https://hello.world
       access-control-max-age: 3600
       cache-control: max-age=3600
@@ -42,6 +43,35 @@ Feature: CORS Support
       vary: origin
       """
 
+  Scenario: An OPTIONS that is not a preflight
+    A preflight is `OPTIONS` carrying `Access-Control-Request-Method`, and only that. A
+    browser puts `Origin` on every request whose method is not `GET` or `HEAD`, its own
+    `OPTIONS` included — so one answered as a preflight is a resource no page can introspect.
+
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        /foo:
+          io:output: true
+          GET:
+            dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      OPTIONS /foo/ HTTP/1.1
+      host: nex.toa.io
+      origin: https://hello.world
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      access-control-allow-origin: https://hello.world
+      Allow: GET
+      vary: origin
+      """
+
   Scenario: Always vary CORS
     Given the annotation:
       """yaml

package/features/dev.feature

@@ -18,6 +18,7 @@ Feature: Dev
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       origin: http://example.com
       """
     Then the following reply is sent:
@@ -70,6 +71,7 @@ Feature: Dev
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       origin: http://example.com
       """
     Then the following reply is sent:

package/features/discovery.feature

@@ -0,0 +1,211 @@
+Feature: Resource discovery
+
+  Every route an application serves, at one path, described as `OPTIONS` on each of them
+  describes it.
+
+  Scenario: What an application serves
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          io:output: [id, title]
+          GET: enumerate
+          POST: create
+          /:id:
+            GET: observe
+      """
+    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
+      Allow: GET, HEAD, OPTIONS
+      cache-control: private, max-age=1800
+
+      routes:
+        /pots:
+          GET:
+            output:
+              type: array
+              items:
+                properties:
+                  id:
+                    type: string
+                  title:
+                    type: string
+          POST:
+            input:
+              properties:
+                title:
+                  type: string
+        /pots/:id:
+          GET:
+            output:
+              properties:
+                id:
+                  type: string
+      """
+
+  Scenario: A key is a request that can be made
+    What each entry says is what `OPTIONS` on that key says, so a client reads the tree
+    once and addresses any of it by the key it was given.
+
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:a:
+          io:output: true
+          PATCH: parameters
+      """
+    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:
+        /echo/:a:
+          PATCH:
+            route:
+              a:
+                type: string
+            input:
+              type: object
+              properties:
+                b:
+                  type: string
+      """
+    When the following request is received:
+      """
+      OPTIONS /echo/:a/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: PATCH
+
+      PATCH:
+        route:
+          a:
+            type: string
+        input:
+          type: object
+          properties:
+            b:
+              type: string
+      """
+
+  Scenario: A resource this caller may reach no method of is not there
+    `OPTIONS` on one answers `403`, and a tree cannot refuse a single entry — so it is
+    omitted, rather than named as something that exists and is not for them.
+
+    Given the annotation:
+      """yaml
+      /:
+        /open:
+          anonymous: true
+          GET:
+            dev:stub: hello
+        /closed:
+          auth:role: admin
+          GET:
+            dev:stub: secret
+      """
+    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:
+        /open:
+          GET: {}
+      """
+    And the reply does not contain:
+      """
+      /closed:
+      """
+
+  Scenario: Only the verbs this caller may reach
+    A resource is described by what is left of it, not dropped for the part that is not
+    theirs.
+
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          isolated: true
+          io:output: [id, title]
+          GET:
+            anonymous: true
+            endpoint: enumerate
+          POST:
+            auth:role: admin
+            endpoint: create
+      """
+    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:
+        /pots:
+          GET:
+      """
+    And the reply does not contain:
+      """
+      temperature
+      """
+
+  Scenario: A credential does not hide what is anonymous
+    A credential refuses an `anonymous` route because it would make the reply uncacheable,
+    and a description is not that reply. Without this an identity would be shown less of
+    the tree than someone presenting nothing at all.
+
+    Given the `identity.basic` database contains:
+      # developer:secret
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the `identity.bans` database is empty
+    And the annotation:
+      """yaml
+      /:
+        /pots:
+          anonymous: true
+          GET:
+            dev:stub: hello
+      """
+    When the following request is received:
+      """
+      OPTIONS /.discovery HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      routes:
+        /pots:
+          GET: {}
+      """