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

package/documentation/rpc.md

@@ -0,0 +1,140 @@
+# JSON-RPC
+
+An application annotates it, and every resource it exposes answers as a procedure as well.
+
+```yaml
+exposition:
+  rpc:
+    batch: 32
+```
+
+Without it `/.rpc` is a path like any other, and nothing answers there. The path is fixed:
+one an application could choose is one it could collide with a route of its own.
+
+## The name
+
+A procedure is an RTD method — a node and a verb — and its name is written the way the node is
+declared: the route template, with a variable marked by a leading `_`, and the verb as the last
+segment.
+
+| route | verb | method |
+| --- | --- | --- |
+| `/pots` | `GET` | `pots/GET` |
+| `/pots` | `POST` | `pots/POST` |
+| `/pots/:id` | `GET` | `pots/_id/GET` |
+| `/identity/tokens/:identity` | `POST` | `identity/tokens/_identity/POST` |
+| `/files/**` | `GET` | `files/__/GET` |
+| `/` | `GET` | `GET` |
+
+The verb is always the last segment, so `/pots/GET` answering `POST` is `pots/GET/POST` and
+`/pots` answering `GET` is `pots/GET`. Nothing is declared to make a name: a re-mounted route is
+a renamed procedure, because the name is the address.
+
+## What has a name
+
+A segment is addressed where it holds only `A-Z`, `a-z`, `0-9` and `-`. `_` is the name's own,
+marking a variable, and `__` the rest of a path.
+
+A route with a segment holding anything else — a `.`, a `_`, a `*`, a variable that is not one
+word — has no name. It is served over HTTP as it always was; what it loses is the address, so
+`/.rpc` cannot call it. Each is said once at startup, naming the route and the segment.
+
+```
+Route cannot be addressed as a procedure  route=/pots/v1.0 segment=v1.0
+```
+
+## The parameters
+
+`params` is by name, and carries what a request carries.
+
+A key the template names is a route variable, and is taken by the path. `query` is the
+querystring. Whatever is left is the body.
+
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "pots/_id/GET", "params": {"id": "a1b2"}}
+```
+
+```json
+{"jsonrpc": "2.0", "id": 2, "method": "pots/POST",
+ "params": {"title": "Kettle", "volume": 1.7}}
+```
+
+```json
+{"jsonrpc": "2.0", "id": 3, "method": "pots/GET",
+ "params": {"query": {"criteria": "volume=gt=1", "limit": 10}}}
+```
+
+The querystring has a name of its own because an operation's input is free to have an `id` or
+a `limit`, and the two would otherwise be one object. An operation whose input has a property
+named `query` cannot be called with one.
+
+A variable stands for a single segment, so its value may not contain `/`, `?` or `#`. `__`
+stands for the rest of the path and may contain `/`; its value is read under the name `**`,
+which is what the RTD calls it wherever else it is read.
+
+## What answers
+
+The reply is the operation's, restricted by the same [`io:output`](io.md) as the resource's,
+and encoded as the request's `accept` asks. A call that returned nothing answers `result: null`
+— JSON-RPC has no 404, and nothing went wrong.
+
+A call with no `id` is a notification: it runs and answers nothing, and a request carrying only
+notifications answers `204`.
+
+## Several at once
+
+A request may carry an array of calls instead of one, and answers an array of what they
+answered — shorter than what it was given, where some were notifications.
+
+```json
+[{"jsonrpc": "2.0", "id": 1, "method": "pots/_id/GET", "params": {"id": "a1b2"}},
+ {"jsonrpc": "2.0", "method": "pots/_id/DELETE", "params": {"id": "c3d4"}}]
+```
+
+They run one after another, in the order given. `batch` is how many one request may carry, 32
+where the annotation does not say: a request is one authentication and one reply however many
+calls it makes, so what a caller may ask for at once is bounded.
+
+## What refuses
+
+The whole request is refused, with a status, when it is not a request this endpoint serves: a
+verb other than `POST` is `405`, an unreadable body is `400`, and an array that is empty or
+longer than `batch` is `400`.
+
+A call that is not one — a version it does not state, a method it does not name — is answered
+to nobody: `id` is `null`, because nothing about it is trustworthy enough to answer to.
+
+A credential is the request's, so a call cannot be refused for one: a request that presents
+none where the procedure requires one is `401`, and carries the challenge that says where to
+authenticate.
+
+Everything else a call runs into is a value, at `200`, because the request itself succeeded.
+
+| | |
+| --- | --- |
+| `-32601` | no route of that name, or no such verb on it |
+| `-32602` | a variable is missing, or a query is not one |
+| `-32000` | the identity is not authorized to make this call |
+| `-32001` | the operation refused, its own code in `data.code` |
+| `-32603` | anything the gateway did not mean to answer |
+| `-32002` | the request carries more calls than `batch` |
+
+The first five codes JSON-RPC states mean the same to every client. `-32000` and `-32001` are
+this gateway's, from the block the specification reserves and leaves empty, so
+`-32001` says only that an operation refused — `data.code` is the code that operation declares
+in its manifest, and is what a caller reads.
+
+## Authorization
+
+A procedure is authorized as the resource is, against the path and the verb its name states.
+A token restricted to `/pots/:id/` for `GET` authorizes `pots/_id/GET` and nothing else,
+whichever way the call arrives.
+
+[`anonymous`](access.md#anonymous) is the one directive that reads a call differently from a
+request: it admits one whatever the request presented, because what refuses a credentialed request
+is that the reply would not be cacheable, and what a call answers is not a reply.
+
+## What has no procedure
+
+`map:buffer` reads the request, and a call is not the request. A resource that declares it
+answers over HTTP alone.

package/documentation/tree.md

@@ -71,6 +71,9 @@ Forwarding Route variables are mapped to the forwarded Route variables if they h
 
 ## Methods
 
+Every Method is also addressable as a procedure, where the context annotates
+[JSON-RPC](rpc.md).
+
 Methods are mappings of the HTTP methods to the corresponding operations.
 
 A Method is a key named after the corresponding HTTP method, with a value following the schema

package/features/auth.bearer.feature

@@ -0,0 +1,120 @@
+@security
+Feature: More than one provider claims Bearer
+
+  An OpenID `id_token` and a token this gateway issued are both presented as `Bearer`,
+  and only their own provider can verify either. The gateway asks each in turn.
+
+  Background:
+    Given local IDP is running
+    And the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the annotation:
+      """yaml
+      /:
+        io:output: true
+        /hello/:id:
+          auth:id: id
+          GET:
+            dev:stub: Hello
+      """
+
+  Scenario: A token this gateway issued is presented as Bearer
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ token }}
+      content-type: text/plain
+
+      Hello
+      """
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ token }}
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+
+      Hello
+      """
+    # the token was answered by its own provider, so nothing rotates it
+    And the reply does not contain:
+      """
+      authorization: Token
+      """
+
+  Scenario: A Bearer this gateway did not issue is answered by federation
+    Given the IDP token for Stranger is issued
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Stranger.id_token }}
+      accept: text/plain
+      """
+    # `identity.tokens` declines it, and federation rejects an issuer it does not trust
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: A malformed Bearer is rejected, not an error
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer not.a.token
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: Both kinds of Bearer against one authority
+    Given the `identity.federation` configuration:
+      """yaml
+      trust:
+        - iss: http://localhost:44444
+          aud: test
+      """
+    And the IDP token for User is issued
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ User.id_token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ federated }}
+
+      id: ${{ User.id }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ federated }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ User.id }}
+      """

package/features/cache.feature

@@ -320,3 +320,49 @@ Feature: Caching
       200 OK
       cache-control: private, no-cache
       """
+
+  Scenario: An exact value is set whatever the method
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        /tokens/:
+          anonymous: true
+          cache:exact: no-store
+          POST:
+            dev:stub: issued
+      """
+    When the following request is received:
+      """
+      POST /tokens/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    # whether a reply may be stored is not a question about the method's cacheability
+    Then the following reply is sent:
+      """
+      201 Created
+      cache-control: no-store
+      """
+
+  Scenario: Cacheability is still asked of safe methods only
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        /notes/:
+          anonymous: true
+          cache:control: max-age=60000, public
+          POST:
+            dev:stub: created
+      """
+    When the following request is received:
+      """
+      POST /notes/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the reply does not contain:
+      """
+      cache-control:
+      """

package/features/identity.basic.feature

@@ -323,6 +323,50 @@ Feature: Basic authentication
       message: Principal username cannot be changed
       """
 
+  Scenario: A Principal incepted by its own credentials holds the role at once
+    Given the `identity.basic` database is empty
+    And the `identity.basic` configuration:
+      """yaml
+      principal:
+        authority: nex
+        username: root
+      """
+    And the annotation:
+      """yaml
+      /:
+        io:output: true
+        GET:
+          auth:role: system:stub
+          dev:stub:
+            access: granted!
+      """
+    # the token the inception replies with carries the roles the Identity has by then
+    When the following request is received:
+      """
+      POST /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic cm9vdDpzZWNyZXQjMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      access: granted!
+      """
+
   Scenario: Principal username in another authority is ordinary credentials
     Given the `identity.basic` configuration:
       """yaml

package/features/identity.federation.feature

@@ -197,16 +197,13 @@ Feature: Identity Federation
       id: ${{ root.id }}
       """
 
-    Then after 0.2 seconds
-
-    # the role is checked over the id token: a Token carries the roles held when it
-    # was issued, and this one was issued before the grant
+    # the Role is granted before the reply, so the Token that reply carries holds it
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
       host: nex.toa.io
       accept: application/yaml
-      authorization: Bearer ${{ root.id_token }}
+      authorization: Token ${{ root.token }}
       """
     Then the following reply is sent:
       """