@toa.io/extensions.exposition 1.0.0-alpha.27 → 1.0.0-alpha.271

package/documentation/tracing.md

@@ -0,0 +1,70 @@
+# Tracing
+
+Each incoming request is processed within a [trace](../../telemetry/readme.md#tracing) —
+a server span is created, and its trace context is propagated to component invocations and
+emitted events, so all log entries and spans across the application caused by the request
+share the same `trace_id`.
+
+## The `ray` response header
+
+Each response contains a `ray` header with the trace ID of the request.
+It can be used to find related log entries, or be attached to a support ticket.
+
+Log entries are stamped with the trace ID regardless of the sampling decision,
+while the trace itself is only recorded if the trace is sampled (see [Sampling](#sampling)).
+
+```
+HTTP/1.1 201 Created
+ray: 0af7651916cd43dd8448eb211c80319c
+```
+
+## Continuing a trace
+
+By default, the trace starts at the gateway. If the request carries a trace context in one of the
+following headers, the trace is continued, that is, the incoming trace ID is used.
+
+### `traceparent`
+
+The [W3C Trace Context](https://www.w3.org/TR/trace-context/#traceparent-header) header, sent by
+clients instrumented with OpenTelemetry-compatible tooling, or by upstream proxies.
+
+```
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+```
+
+In addition to the trace ID, it carries the ID of the client span, which becomes the *parent* of
+the gateway's server span, linking client-side and server-side spans into a single trace tree.
+
+### `ray`
+
+A bare trace ID (32 lowercase hex digits), for clients without tracing instrumentation willing to
+correlate their requests with server-side traces.
+
+```
+ray: 4bf92f3577b34da6a3ce929d0e0e4736
+```
+
+Unlike `traceparent`, it carries no parent span, so the gateway's server span becomes the root of
+the trace.
+
+If both headers are present, `traceparent` takes precedence as it carries more information.
+Headers with invalid values are ignored, and a new trace is started.
+
+## Sampling
+
+The trace *context* (trace ID) is always created and propagated, so the `ray` header and
+`trace_id` in log entries are always present. The sampling decision only determines whether
+the *spans* of the trace are recorded.
+
+The decision is made once, by the process that starts the trace, and is propagated along with
+the trace context (the flags byte of `traceparent`), so a trace is either recorded as a whole
+or not at all. Sampling is configured with the
+[`telemetry.traces` annotation](../../telemetry/readme.md#sampling).
+
+Sending a trace context does not bypass sampling: an incoming `ray` header adopts the trace ID,
+while the recording decision is still made by the gateway. The `sampled` flag of an incoming
+`traceparent` is respected, as the decision belongs to the trace root.
+
+## See also
+
+- [Telemetry extension](../../telemetry/readme.md) — spans, structured logs, `context.span`

package/documentation/tree.md

@@ -56,6 +56,19 @@ 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.
 
+## Route forwarding
+
+A Route can be forwarded to another Route by specifying the destination Route as the value of the
+Route.
+
+```yaml
+/destination/:var: ...
+/static: /destination/hello
+/variables/:bar: /destination/:bar
+```
+
+Forwarding Route variables are mapped to the forwarded Route variables if they have the same name.
+
 ## Methods
 
 Methods are mappings of the HTTP methods to the corresponding operations.

package/features/access.feature

@@ -52,6 +52,56 @@ Feature: Access authorization
       access: granted!
       """
 
+  Scenario: Allow access to anyone
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        auth:anyone: true
+        GET:
+          dev:stub:
+            access: granted!
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      access: granted!
+      """
+
+    # request without credentials
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+    # request with invalid credentials
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic bm9uOmV4aXN0ZW50
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
   Scenario: Deny access with credentials to a resource with anonymous access
     Given the annotation:
       """yaml
@@ -364,8 +414,8 @@ Feature: Access authorization
     Then the following reply is sent:
       """
       200 OK
-      content-type: application/yaml
       authorization: Token ${{ token }}
+      content-type: application/yaml
 
       access: granted!
       """
@@ -421,12 +471,12 @@ Feature: Access authorization
       """
       403 Forbidden
 
-      Basic authentication scheme is required to access this resource.
+      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.
+  Trunk directives should not be applied to the Identity management resources
 
     Given the annotation:
       """yaml
@@ -468,9 +518,79 @@ Feature: Access authorization
     Then the following reply is sent:
       """
       200 OK
+      authorization: Token ${{ token }}
 
       identity:
         id: efe3a65ebbee47ed95a73edd911ea328
         roles:
           - developer
       """
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    And the reply does not contain:
+      """
+      authorization: Token
+      """
+
+  Scenario: Delegation does not violate input restrictions
+    Given the `identity.roles` database contains:
+      | _id                              | identity                         | role      |
+      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
+    # `auth:` is declared before `io:`, and the identity it embeds is the server's
+    # own addition — what `io:input` restricts is the body the client sent
+    And the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          POST:
+            auth:rule:
+              role: developer
+              delegate: identity
+            io:input: [foo]
+            io:output: true
+            endpoint: echo
+      """
+    When the following request is received:
+      """
+      POST /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      content-type: application/yaml
+
+      foo: bar
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      foo: bar
+      identity:
+        id: efe3a65ebbee47ed95a73edd911ea328
+      """
+    # and a property the client is not allowed to send is still refused
+    When the following request is received:
+      """
+      POST /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      content-type: application/yaml
+
+      foo: bar
+      baz: qux
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      'Unexpected input: baz'
+      """

package/features/auth.assert.feature

@@ -0,0 +1,57 @@
+Feature: Identity assertion
+
+  Scenario: Assert Identity
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     | _version |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+    And the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET:
+            auth:assert: true
+            anyone: true
+            io:output: true
+            endpoint: ping
+      """
+
+    # existent identity
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ developer.token }}
+      """
+
+    # new identity
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYSQkdzByZCE=
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ user.token }}
+      """
+
+    # invalid credentials
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNz
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      422 Unprocessable Entity
+
+      code: INVALID_PASSWORD
+      """

package/features/auth.claims.feature

@@ -0,0 +1,170 @@
+@security
+Feature: Federated identity authentication
+
+  Background:
+    Given the `identity.federation` database is empty
+    And local IDP is running
+    And the IDP token for Bob is issued
+    And the `identity.federation` configuration:
+      """yaml
+      trust:
+        - iss: http://localhost:44444
+      """
+
+  Scenario: Full claim
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: test
+            sub: Bob
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: Only `sub`
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            sub: Bob
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: No `sub`
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: test
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: `sub` mismatch
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            sub: Alice
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
+  Scenario: `aud` mismatch
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: goalkeepers
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
+  Scenario: Matching authority and Route parameter
+    Given the annotation:
+      """yaml
+      authorities:
+        test: the.test.local
+      /:
+        /:id:
+          GET:
+            auth:claims:
+              aud: :authority
+              sub: /:id
+            dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET /Bob/ HTTP/1.1
+      host: the.test.local
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: `iss` matching authority common domain
+    Given the annotation:
+      """yaml
+      /:
+        /:id:
+          GET:
+            auth:claims:
+              iss: :domain
+              sub: /:id
+            dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET /Bob/ HTTP/1.1
+      host: localhost
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """

package/features/auth.incept.feature

@@ -0,0 +1,120 @@
+Feature: Identity inception
+
+  Scenario: Non-associated Identity inception
+    Given the `identity.basic` database is empty
+    When the following request is received:
+      """
+      POST /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+
+      id: ${{ id }}
+      roles: []
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ id }}
+      roles: []
+      """
+
+  Scenario: Creating new Identity using inception with Basic scheme
+    Given the `users` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          POST:
+            io:input: [name]
+            io:output: true
+            incept: id
+            query: ~
+            endpoint: transit
+      """
+    When the following request is received:
+      """
+      POST /users/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic #{{ basic }}
+      accept: application/yaml
+      content-type: application/yaml
+
+      name: Bill Smith
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+
+      id: ${{ id }}
+      """
+
+  Scenario: Inception with operation error
+    Given the `users` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          POST:
+            io:input: [name]
+            io:output: true
+            incept: id
+            endpoint: create
+      """
+    When the following request is received:
+      """
+      POST /users/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic #{{ basic }}
+      accept: application/yaml
+      content-type: application/yaml
+
+      name: return_error
+      """
+    Then the following reply is sent:
+      """
+      422 Unprocessable Entity
+      """
+
+  Scenario: Incept without credentials
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          POST:
+            auth:incept: id
+            io:output: true
+            query: ~
+            endpoint: echo
+      """
+    And transient identity
+    When the following request is received:
+      """
+      POST /echo/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/yaml
+
+      id: ${{ identity.id }}
+      foo: bar
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+
+      id: ${{ identity.id }}
+      foo: bar
+      """

package/features/auth.input.feature

@@ -0,0 +1,59 @@
+Feature: Input properties authorization
+
+  Background:
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username | password                                                     |
+      | 72cf9b0ab0ac4ab2b8036e4e940ddcae | nex       | root     | $2b$10$Qq/qnyyU5wjrbDXyWok14OnqAZv/z.pLhz.UddatjI6eHU/rFof4i |
+    And the `identity.roles` database contains:
+      | _id                              | identity                         | role  |
+      | 9c4702490ff84f2a9e1b1da2ab64bdd4 | 72cf9b0ab0ac4ab2b8036e4e940ddcae | app:b |
+
+  Scenario: Input properties authorization
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          io:input: [a, b]
+          io:output: [a, b]
+          anonymous: true
+          auth:role: app:b
+          auth:input:
+            - prop: b
+              role: app:b
+          PUT: parameters
+      """
+
+    When the following request is received:
+      """
+      PUT /echo/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/yaml
+
+      a: foo
+      b: bar
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+
+      Input property is not authorized
+      """
+    When the following request is received:
+      """
+      PUT /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic cm9vdDpzZWNyZXQ=
+      accept: application/yaml
+      content-type: application/yaml
+
+      a: foo
+      b: bar
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      a: foo
+      b: bar
+      """

package/features/authorities.feature

@@ -19,6 +19,8 @@ Feature: Authorities
       """
       200 OK
       """
+
+    # arbitrary authorities are also allowed
     When the following request is received:
       """
       GET / HTTP/1.1
@@ -26,7 +28,5 @@ Feature: Authorities
       """
     Then the following reply is sent:
       """
-      404 Not Found
-
-      Unknown authority
+      200 OK
       """