@toa.io/extensions.exposition 0.20.0-alpha.0 → 0.20.0-alpha.2

package/components/context.toa.yaml

@@ -11,5 +11,5 @@ configuration:
   identity.tokens:
     key0: k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA
 
-realtime:
-  messages.created: [senderId, recipientId]
+exposition:
+  debug: true

package/documentation/notes/sse.md

@@ -0,0 +1,71 @@
+# Note: Server Sent Events
+
+## TL;DR
+
+1. Doesn't exist.
+2. Ridiculous.
+3. Redundant.
+
+## There is no SSE
+
+The initial premise of SSE is to deliver real-time events specifically targeted at a particular user. It's evident that
+to access these events, user authentication is essential, typically implemented through
+an [HTTP Authentication framework](https://datatracker.ietf.org/doc/html/rfc2617).
+
+However, despite this being the most straightforward
+scenario, [it does not work this way](https://github.com/whatwg/html/issues/2177). The only viable way to use SSE is
+to avoid the standard `EventSource` implementation.
+
+## Peculiar event format
+
+### SLAP
+
+[Event stream format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format)
+defines four fields: `event`, `data`, `id`, `retry`.
+
+In practice, code capable of producing such an object is forced to break the Single Level of Abstraction Principle. This
+requires knowledge of both event structures and connection properties. In real-world systems, these may be handled by
+different processes, such as an Events microservice and an API Gateway.
+
+### Content negotiation
+
+The `data` property is expected to be an arbitrary string, although real-world event data is often structured as an
+object.
+
+Furthermore, since the Event stream format defines its own content type, there is no built-in way to negotiate the
+format of the events.
+
+Additionally, the `data` value is limited to a single line, which hinders the use of
+more [human-friendly formats](https://yaml.org) in a straightforward manner.
+
+## HTTP is enough
+
+Rather than resorting to a non-standard client and a predefined content format, a basic HTTP request can provide a
+solution:
+
+```http
+GET /events/ HTTP/1.1
+accept: application/yaml
+```
+
+```
+200 OK
+content-type: application/yaml
+transfer-encoding: chunked
+
+id: 1
+event: created
+data:
+  foo: bar
+
+id: 2
+event: deleted
+data:
+  bar: baz
+```
+
+Server-side implementation with flow control and stream termination handling is trivial:
+
+```javascript
+eventStream.pipe(response)
+```

package/documentation/protocol.md

@@ -12,4 +12,7 @@ The following media types are supported for both requests and responses:
 The response format is determined by content negotiation
 using [negotiator](https://github.com/jshttp/negotiator).
 
-> Errors are always sent as `text/plain`. See [debug mode](../readme.md#context-annotation).
+## Streams
+
+Reply streams are transmitted
+using [chunked transfer encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#directives).

package/features/access.feature

@@ -69,11 +69,12 @@ Feature: Access authorization
   Scenario: Using `auth:id` directive
     Given the annotation:
       """yaml
-      /:id:
-        auth:id: id
-        GET:
-          dev:stub:
-            access: granted!
+      /:
+        /:id:
+          auth:id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     When the following request is received:
       """
@@ -144,14 +145,15 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
-        auth:role: developer:rust:junior  # role scope matches
-        /nested:
+        /:
+          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: good!
-      /javascript:
-        auth:role: developer:javascript   # role scope does not match
-        GET:
-          dev:stub: no good!
+            dev:stub: no good!
       """
     When the following request is received:
       """
@@ -211,20 +213,21 @@ Feature: Access authorization
       | 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!
+      /:
+        /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:
       """
@@ -252,11 +255,12 @@ Feature: Access authorization
   Scenario: Token authentication scheme
     Given the annotation:
       """yaml
-      /:id:
-        auth:id: id
-        GET:
-          dev:stub:
-            access: granted!
+      /:
+        /:id:
+          auth:id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     When the following request is received:
       """
@@ -329,12 +333,13 @@ Feature: Access authorization
   Scenario: Using `auth:scheme` directive
     Given the annotation:
       """yaml
-      /:id:
-        auth:scheme: basic
-        auth:id: id
-        GET:
-          dev:stub:
-            access: granted!
+      /:
+        /:id:
+          auth:scheme: basic
+          auth:id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     When the following request is received:
       """
@@ -388,11 +393,12 @@ Feature: Access authorization
       | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | system |
     And the annotation:
       """yaml
-      /:id:
-        auth:id: id
-        GET:
-          dev:stub:
-            access: granted!
+      /:
+        /:id:
+          auth:id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     And the `identity.tokens` configuration:
       """yaml

package/features/annotation.feature

@@ -3,10 +3,12 @@ Feature: Annotation
   Scenario: Simple annotation
     Given the annotation:
       """yaml
-      anonymous: true
-      /foo:
-        GET:
-          endpoint: pots.enumerate
+      /:
+        anonymous: true
+        /foo:
+          GET:
+            query: {}
+            endpoint: pots.enumerate
       """
     And the `pots` is running
     And the `pots` database contains:

package/features/body.feature

@@ -19,3 +19,27 @@ Feature: Request body
       """
       201 Created
       """
+
+  Scenario Outline: Path segment as input for <operation>
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:name:
+          GET: <operation>
+      """
+    When the following request is received:
+      """
+      GET /echo/world/ HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+
+      Hello world
+      """
+    Examples:
+      | operation |
+      | compute   |
+      | affect    |

package/features/directives.feature

@@ -3,8 +3,8 @@ Feature: Directives
   Scenario: Basic directive
     Given the annotation:
       """yaml
-      anonymous: true
       /:
+        anonymous: true
         GET:
           dev:stub:
             hello: world
@@ -25,8 +25,8 @@ Feature: Directives
   Scenario: Nested routes
     Given the annotation:
       """yaml
-      anonymous: true
       /:
+        anonymous: true
         dev:stub:
           hello: again
         GET: {}

package/features/dynamic.feature

@@ -6,11 +6,21 @@ Feature: Dynamic tree updates
       | 4c4759e6f9c74da989d64511df42d6f4 | First pot | 100    | 80          |
 
   Scenario: Updating routes
+    Given the Gateway is running
     And the `pots` is running with the following manifest:
       """yaml
       exposition:
         /:
-          POST: transit
+          isolated: true
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      GET /pots/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
       """
     Then the `pots` is stopped
     Then the `pots` is running with the following manifest:

package/features/errors.feature

@@ -168,41 +168,26 @@ Feature: Errors
       Malformed authorization header.
       """
 
-  Scenario: Creating an Identity using inception with existing credentials
-    Given the `identity.basic` database is empty
-    And the `users` is running with the following manifest:
+  Scenario Outline: Exception is thrown (debug: <debug>)
+    Given the annotation:
       """yaml
-      exposition:
-        /:
+      debug: <debug>
+      /:
+        GET:
           anonymous: true
-          POST:
-            incept: id
-            endpoint: transit
+          dev:throw: Broken!
       """
     When the following request is received:
-      # identity inception
       """
-      POST /users/ HTTP/1.1
-      authorization: Basic dXNlcjpwYXNzMTIzNA==
-      accept: application/yaml
-      content-type: application/yaml
-
-      name: Bill Smith
-      """
-    Then the following reply is sent:
-      """
-      201 Created
-      """
-    And the following request is received:
-      # same credentials
-      """
-      POST /users/ HTTP/1.1
-      authorization: Basic dXNlcjpwYXNzMTIzNA==
-      content-type: text/plain
-
-      name: Mary Louis
+      GET / HTTP/1.1
+      accept: text/plain
       """
     Then the following reply is sent:
       """
-      403 Forbidden
+      500 Internal Server Error
+      <response>
       """
+    Examples:
+      | debug | response          |
+      | false | content-length: 0 |
+      | true  | Error: Broken!    |

package/features/identity.basic.feature

@@ -26,6 +26,7 @@ Feature: Basic authentication
           POST:
             incept: id
             endpoint: transit
+            query: ~
         /:id:                 # credential testing route
           id: id
           GET: observe
@@ -69,12 +70,13 @@ Feature: Basic authentication
 
   Scenario: Changing the password
     Given the annotation:
-      """
-      /:id:
-        id: id
-        GET:
-          dev:stub:
-            access: granted!
+      """yaml
+      /:
+        /:id:
+          id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     And the `identity.basic` database contains:
       | _id                              | _version | username  | password                                                     |
@@ -233,3 +235,42 @@ Feature: Basic authentication
       code: PRINCIPAL_LOCKED
       message: Principal username cannot be changed.
       """
+
+  Scenario: Creating an Identity using inception with existing credentials
+    Given the `identity.basic` database is empty
+    And the `users` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          anonymous: true
+          POST:
+            incept: id
+            endpoint: transit
+      """
+    When the following request is received:
+      # identity inception
+      """
+      POST /users/ HTTP/1.1
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      accept: application/yaml
+      content-type: application/yaml
+
+      name: Bill Smith
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      """
+    And the following request is received:
+      # same credentials
+      """
+      POST /users/ HTTP/1.1
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      content-type: text/plain
+
+      name: Mary Louis
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """

package/features/identity.tokens.feature

@@ -4,16 +4,17 @@ Feature: Tokens lifecycle
     Given the `identity.basic` database contains:
       | _id                              | username  | password                                                     |
       | efe3a65ebbee47ed95a73edd911ea328 | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-    And the `greeter` is running with the following manifest:
+    Given the annotation:
       """yaml
-      exposition:
-        /:id:
+      /:
+        /hello/:id:
           auth:id: id
-          GET: greet
+          GET:
+            dev:stub: Hello
       """
     When the following request is received:
       """
-      GET /greeter/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: text/plain
       """
@@ -31,16 +32,17 @@ Feature: Tokens lifecycle
       """yaml
       refresh: 1
       """
-    And the `greeter` is running with the following manifest:
+    And the annotation:
       """yaml
-      exposition:
-        /:id:
+      /:
+        /hello/:id:
           auth:id: id
-          GET: greet
+          GET:
+            dev:stub: Hello
       """
     When the following request is received:
       """
-      GET /greeter/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: text/plain
       """
@@ -54,7 +56,7 @@ Feature: Tokens lifecycle
     Then after 1 second
     When the following request is received:
       """
-      GET /greeter/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
       authorization: Token ${{ token }}
       accept: text/plain
       """
@@ -69,11 +71,12 @@ Feature: Tokens lifecycle
   Scenario: Token revocation on password change
     Given the annotation:
       """yaml
-      /:id:
-        id: id
-        GET:
-          dev:stub:
-            access: granted!
+      /:
+        /:id:
+          id: id
+          GET:
+            dev:stub:
+              access: granted!
       """
     And the `identity.tokens` configuration:
       """yaml

package/features/steps/Gateway.ts

@@ -16,9 +16,16 @@ export class Gateway {
   @given('the annotation:')
   public async annotate (yaml: string): Promise<void> {
     const annotation = parse(yaml)
-    const node = syntax.parse(annotation, shortcuts)
 
-    process.env.TOA_EXPOSITION = encode(node)
+    if ('/' in annotation) {
+      const node = { '/': annotation['/'] }
+      const tree = syntax.parse(node, shortcuts)
+
+      process.env.TOA_EXPOSITION = encode(tree)
+    }
+
+    if (annotation.debug === true)
+      process.env.TOA_EXPOSITION_DEBUG = '1'
 
     await Gateway.stop()
 
@@ -40,22 +47,7 @@ export class Gateway {
     this.default = false
   }
 
-  @after()
-  public async cleanup (): Promise<void> {
-    if (this.default)
-      return
-
-    delete process.env.TOA_EXPOSITION
-
-    await Gateway.stop()
-  }
-
-  @afterAll()
-  public static async stop (): Promise<void> {
-    await instance?.disconnect()
-    instance = null
-  }
-
+  @given('the Gateway is running')
   public async start (): Promise<void> {
     if (instance !== null)
       return
@@ -76,6 +68,22 @@ export class Gateway {
     await timeout(50) // resource discovery
   }
 
+  @after()
+  public async cleanup (): Promise<void> {
+    if (this.default)
+      return
+
+    delete process.env.TOA_EXPOSITION
+
+    await Gateway.stop()
+  }
+
+  @afterAll()
+  public static async stop (): Promise<void> {
+    await instance?.disconnect()
+    instance = null
+  }
+
   private writeConfiguration (): void {
     for (const [id, configuration] of Object.entries(DEFAULT_CONFIGURATION)) {
       const [name, namespace = 'default'] = id.split('.').reverse()

package/features/steps/components/echo/manifest.toa.yaml

@@ -0,0 +1,9 @@
+name: echo
+
+operations:
+  compute:
+    input:
+      name*: string
+  affect:
+    input:
+      name*: string

package/features/steps/components/echo/operations/affect.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function effect (input) {
+  return `Hello ${input.name}`
+}
+
+exports.effect = effect

package/features/steps/components/echo/operations/compute.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function computation (input) {
+  return `Hello ${input.name}`
+}
+
+exports.computation = computation

package/features/steps/components/greeter/manifest.toa.yaml

@@ -1,9 +1,5 @@
 name: greeter
 
-operations:
-  greet:
-    output: string
-
 exposition:
   /:
     GET: greet

package/features/steps/components/greeter/operations/greet.js

@@ -1,6 +1,6 @@
 'use strict'
 
-async function computation () {
+function computation () {
   return 'Hello'
 }
 

package/features/steps/components/sequences/manifest.toa.yaml

@@ -0,0 +1,10 @@
+name: sequences
+
+operations:
+  numbers:
+    input: 5
+
+exposition:
+  /tokens:
+    anonymous: true
+    GET: tokens

package/features/steps/components/sequences/operations/numbers.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function * effect (amount) {
+  for (let i = 0; i < amount; i++) yield i
+}
+
+exports.effect = effect

package/features/steps/components/sequences/operations/tokens.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const { randomBytes } = require('node:crypto')
+
+async function * computation () {
+  while (true) {
+    await timeout(Math.floor(Math.random() * 100) + 10)
+    yield randomBytes(4).toString('hex')
+  }
+}
+
+function timeout (ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+exports.computation = computation