@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.300

package/documentation/tree.md

@@ -1,165 +0,0 @@
-# Resource Tree Declaration
-
-The foundation of a Resource Tree Declaration (RTD) is an RTD node.
-An RTD node is an object that consists of _Routes_, _Methods_ and _Directives_.
-
-## Routes
-
-A Route is a key starting with `/` and it has a value as a nested RTD node.
-
-```yaml
-/:
-  /users:
-    /:user-id: ...
-  /posts:
-    /:post-id: ...
-```
-
-Route declarations can also be flat, meaning that the RTD can have adjacent branches.
-The following will represent the same resources as the above:
-
-```yaml
-/users/:user-id: ...
-/posts/:post-id: ...
-```
-
-> Refer to the [Directives](#directives) section for an explanation of the differences between
-> nested and adjacent RTD branches.
-
-An RTD node that does not contain any Routes is called an _RTD leaf_.
-
-> Route declarations must not have a trailing slash.
-
-### Route variables
-
-Route segments prefixed with a colon (`:`) are Route variables.
-
-> A segment may include a reference to a single variable.
-> For instance, in the route `/messages/:sender-:recipient`,
-> a single variable is declared with the name `sender-:recipient`.
-
-Refer to [Query mapping](query.md) for the details.
-
-### Route conflicts
-
-Routes with specific, non-variable segments are given precedence in routing decisions.
-
-Consider the following route declarations:
-
-```yaml
-/users/:id: ...
-/users/hot: ...
-```
-
-Request made to `/users/hot/`, will be routed to the second `/users/hot` Route,
-as it provides a more specific match compared to the generic `/users/:id` route.
-
-The priority of Routes with the same specificity is determined by the order of declaration.
-
-## Methods
-
-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
-below:
-
-```yaml
-endpoint: string
-query?: Query
-```
-
-> Refer to [Query mapping](query.md) for the details.
-
-Methods can be present in any RTD node.
-However, it is required that an RTD leaf must have at least one Method.
-
-If a Method only has an `operation` key, it can be declared directly as the value of the `operation`
-key.
-
-```yaml
-/teapots:
-  GET:
-    endpoint: select
-  /hot:
-    GET:
-      endpoint: select
-      query:
-        criteria: state==hot
-/posts:
-  GET: select
-  POST: transit
-  /:post-id:
-    GET: observe
-    PUT: transit
-```
-
-HTTP methods can only be mapped to operations of the corresponding types.
-
-| HTTP method | Operation type                                |
-|-------------|-----------------------------------------------|
-| `POST`      | **Transition** (without Query)<br/>**Effect** |
-| `PUT`       | **Transition** (with Query)<br/>**Effect**    |
-| `GET`       | **Observation**<br/>**Computation**           |
-| `PATCH`     | **Assignment**<br/>**Effect**                 |
-
-As method mapping is unambiguous for Observation, Assignent, and Computation, a consice syntax is
-available:
-
-```yaml
-/items: compute
-/items/:id: [observe, assign]
-```
-
-### Intermediate Nodes
-
-An RTD Node that has a Route with a key `/` is an _intermediate_ Node.
-Intermediate Nodes must not have Methods as they are unreachable.
-
-```yaml
-/posts: # Node is intermediate
-  GET: select # INVALID: Method is unreachable
-  /:
-    PUT: transit
-```
-
-## Directives
-
-RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}` pattern and can be used
-to add or modify the behavior of request processing. Directive declarations are applied to the RTD node where they are
-declared and to all nested nodes.
-
-```yaml
-/posts/:user-id:
-  authorization:id: user-id
-  /:post-id:
-    authorization:role: editor
-```
-
-In the above example, the Route `/posts/:user-id/:post-id/` has both `authorization:id`
-and `authorization:role` directives applied.
-
-When it is necessary to avoid directive nesting, a Route can be declared adjacent.
-
-```yaml
-/posts:
-  /:user-id:
-    id: user-id
-  /:user-id/:post-id:
-    role: editor
-```
-
-In this example, the Route `/posts/:user-id/:post-id/` has only the `authorization:role` directive
-applied.
-
-Another way to avoid nesting is to declare an _isolated_ Node as follows:
-
-```yaml
-/posts:
-  /:user-id:
-    id: user-id
-    /:post-id:
-      isolated: true
-      role: editor
-```
-
-See [Access Authorization](./access.md) as an example of directive provider.

package/documentation/vary.md

@@ -1,69 +0,0 @@
-# HTTP request details
-
-The `vary` directives family provides the capability to include HTTP request details as input for an
-operation call.
-
-## TL;DR
-
-```yaml
-exposition:
-  realms:
-    toa: the.toa.io
-  /:
-    vary:languages: [en, fr]
-    GET:
-      vary:embed:
-        lang: language # predefined embeddings
-        realm: realm
-        token: :x-access-token # raw header value
-      endpoint: dummies.get
-```
-
-## Embeddings
-
-Request parts are embedded into the operation call according to the mapping
-defined by the `vary:embed` directive.
-The keys in the embedding map are the names of the input properties details to be embedded to,
-and the values are the names of the embedding functions.
-If the value is an array, the first non-empty embedding function's result is used.
-
-> If a property is already present in the input, the embedded value will overwrite its current
-> value.
-
-### Realm
-
-Realm is an identifier of a domain used to access the Exposition.
-The list of domains is defined by the `vary:realms` directive,
-which is a map of realm names to their domain names.
-
-The `realm` embedding substitutes the realm identified based on the `host` request header.
-
-### Language
-
-The `language` embedding substitutes the most matching language code based on the `accept-language`
-request header and a list of supported languages defined by the `vary:languages` directive, and also
-adds `accept-language` to the `vary` HTTP response header value.
-If neither of the supported languages matches, the first supported language is used.
-
-### Raw header values
-
-Keys in the embedding map starting with a semicolon (:) are the names of HTTP request headers whose
-values to be embedded into an operation call.
-The names of these headers are then included in the `vary` HTTP response header
-and [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
-of the [CORS](protocol.md#cors).
-
-[Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are embedded
-as a comma-separated list.
-
-### Fallbacks
-
-If the embedding function is an array, the first non-empty resolved value is used.
-
-```yaml
-vary:embed:
-  ip: # fallbacks
-    - :CloudFront-Viewer-Address
-    - :CF-Connecting-IP
-    - :X-Appengine-User-IP
-```

package/features/access.feature

@@ -1,449 +0,0 @@
-Feature: Access authorization
-
-  Background:
-    Given the `identity.basic` database contains:
-      # developer:secret
-      # user:12345
-      | _id                              | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-      | e8e4f9c2a68d419b861403d71fabc915 | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
-    And the `identity.bans` database is empty
-
-  Scenario: Deny by default
-    Given the annotation:
-      """yaml
-      /:
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      """
-
-  Scenario: Allow anonymous access
-    Given the annotation:
-      """yaml
-      /:
-        auth:anonymous: true
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-
-  Scenario: Deny access with credentials to a resource with anonymous access
-    Given the annotation:
-      """yaml
-      /:
-        auth:anonymous: true
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Using `auth:id` directive
-    Given the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Using `auth:role` directive
-    Given the `identity.roles` database contains:
-      | _id                              | identity                         | role      |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
-      | 1d95bd2c764142818f6ece5e084015b5 | efe3a65ebbee47ed95a73edd911ea328 | user      |
-    And the annotation:
-      """yaml
-      /:
-        auth:role: developer
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    When the following request is received:
-      # identity with `developer` and `user` roles
-      """
-      GET / HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-    When the following request is received:
-      # identity with no roles
-      """
-      GET / HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Using `auth:role` directive with scope matching
-    Given the `identity.roles` database contains:
-      | _id                              | identity                         | role           |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer:rust |
-    And the annotation:
-      """yaml
-      /:
-        /:
-          auth:role: developer:rust:junior  # role scope matches
-          /nested:
-            GET:
-              dev:stub: good!
-        /javascript:
-          auth:role: developer:javascript   # role scope does not match
-          GET:
-            dev:stub: no good!
-      """
-    When the following request is received:
-      """
-      GET /nested/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: text/plain
-
-      good!
-      """
-    When the following request is received:
-      """
-      GET /javascript/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Allow by `auth:role` matching one of the roles
-    Given the `identity.roles` database contains:
-      | _id                              | identity                         | role      |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
-    And the annotation:
-      """yaml
-      /:
-        role:
-          - developer
-          - admin
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    When the following request is received:
-      # identity with `developer` and `user` roles
-      """
-      GET / HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-
-  Scenario: Using `auth:rule` directive
-    Given the `identity.roles` database contains:
-      | _id                              | identity                         | role           |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer:rust |
-    And the annotation:
-      """yaml
-      /:
-        /rust/:id:
-          auth:rule:
-            id: id
-            role: developer:rust
-          GET:
-            dev:stub:
-              access: granted!
-        /javascript/:id:
-          rule:
-            id: id
-            role: developer:javascript
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    When the following request is received:
-      """
-      GET /rust/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-    When the following request is received:
-      """
-      GET /javascript/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Token authentication scheme
-    Given the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-    And the reply does not contain:
-      """
-      authorization: Token
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.cjlxn4IJ9hI92KuksguzDx7_kYxgDFFGFnfNchf0cWnmos34dqX2XpTAUBd-LqgqfuH-lVGfNvjBUkw5JtHRBiIAVaPHF3Ncc0eafwgH2DPme9pndZL92fWryGnJ-sMHA28Q6UcXsIfhgd2JZ0n-585SBhwlosC3gKTcVHK7XNljeaTen4jZPw8uY-pdbsm6dDq3aKMzl8K78_BTTfiNPG2cI_aNuHw
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Using token with roles
-    Given the annotation:
-      """yaml
-      /:
-        auth:role: developer
-        GET:
-          dev:stub:
-            access: granted!
-      """
-    And the `identity.roles` database contains:
-      | _id                              | identity                         | role      |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-      authorization: Token ${{ token }}
-
-      access: granted!
-      """
-    When the following request is received:
-      """
-      GET / HTTP/1.1
-      authorization: Token ${{ token }}
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-
-  Scenario: Using `auth:scheme` directive
-    Given the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:scheme: basic
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      access: granted!
-      """
-    When the following request is received:
-      """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
-      accept: text/plain
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-
-      Basic authentication scheme is required to access this resource.
-      """
-
-  Scenario: Adding a role without required permissions
-
-  Trunk directives should not be applied to the Identity management resources.
-
-    Given the annotation:
-      """yaml
-      anonymous: true
-      """
-    When the following request is received:
-      """
-      POST /identity/roles/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      content-type: application/yaml
-
-      role: developer
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      """
-
-  Scenario: Banning an Identity
-    Given the `identity.roles` database contains:
-      | _id                              | identity                         | role   |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | system |
-    And the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    And the `identity.tokens` configuration:
-      """yaml
-      refresh: 1
-      """
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      authorization: Token ${{ token }}
-      """
-    When the following request is received:
-      """
-      PUT /identity/bans/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      content-type: application/yaml
-
-      banned: true
-      """
-    Then the following reply is sent:
-      """
-      204 No Content
-      """
-    # accessing a resource with a banned Identity
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      """
-    Then after 1 second
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Token ${{ token }}
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      """

package/features/annotation.feature

@@ -1,30 +0,0 @@
-Feature: Annotation
-
-  Scenario: Simple annotation
-    Given the annotation:
-      """yaml
-      /:
-        anonymous: true
-        /foo:
-          GET:
-            query: {}
-            endpoint: pots.enumerate
-      """
-    And the `pots` is running
-    And the `pots` database contains:
-      | _id                              | title     | volume |
-      | 4c4759e6f9c74da989d64511df42d6f4 | First pot | 100    |
-    When the following request is received:
-      """
-      GET /foo/ HTTP/1.1
-      accept: application/yaml
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      content-type: application/yaml
-
-      - id: 4c4759e6f9c74da989d64511df42d6f4
-        title: First pot
-        volume: 100
-      """