@toa.io/extensions.exposition 1.0.0-alpha.267 → 1.0.0-alpha.268

package/documentation/io.md

@@ -57,9 +57,7 @@ Output restrictions are not applied to stream responses and errors.
 
 ## Throttling
 
-The `io:throttle` directive is used to limit the rate of the requests meeting the specified
-criteria.
-See [algorithm description](notes/throttling.md).
+The `io:throttle` directive limits the rate of requests meeting the specified criteria.
 
 ```yaml
 exposition:
@@ -68,29 +66,59 @@ exposition:
       key:
         - route
         - ip
-        - identity
-        - segment: id
-        - header: x-real-ip
-        - status: [4xx, 5xx]
+      condition:
+        status: 404
       requests: 500
       interval: 30
       cooldown: 30
-      status: 429
 ```
 
-Once the rate limit is reached, the server will block the requests with the specified `status`
-code (429 by default) until the `cooldown` period expires.
+Requests are counted per `key`. Once `requests` are counted within `interval` seconds, further
+requests carrying that key are answered `429 Too Many Requests` until `cooldown` seconds pass.
+`interval` and `cooldown` are in seconds.
 
-> Currently, only `header` and `status` key components are supported.
+`requests` is a budget for the **whole group** of gateway instances, not for one of them. Counting
+goes through Redis, so the instances converge on one number rather than each enforcing the limit
+separately. The number they act on is a lower bound: it never claims more requests than were really
+made, and it can lag by up to one interval. Precise per-request enforcement is not what this is for.
 
-### Request key components
+The lag is worth knowing about when `requests` is small. An instance sends what it has counted once
+an interval, and what the group made of it only comes back an interval later — so between its send
+and that reply, an instance is going on what it alone has counted since. A limit of `1` blocks on
+the first request whatever happens; a limit of a handful can be overshot in the first interval of a
+burst, before any instance has a group number to act on. Set `requests` for the rate you want to
+stop, not for an exact ceiling.
 
-Request components used to track quota usage and block requests:
+An instance that cannot reach Redis keeps throttling on what it has seen itself, and keeps serving.
 
-- `header`: name of the header (or a list of header names), which value(s) will be used
+### Key components
 
-### Response key components
+What a request is counted against. Give one, or a list — a list keys on the combination, so
+`[route, ip]` counts each address separately on each route.
 
-Response components used only to track quota usage:
+- `ip` — the client address, read from `X-Forwarded-For` where it is set and not private,
+  and from the connection otherwise.
+- `path` — the path the request came in on, `/users/1`.
+- `route` — the route as declared, `/users/:id`. Every path matching the route shares one budget,
+  which `path` cannot do: keyed on `path`, walking ids is a way around the limit.
+- `identity` — the authenticated identity. Requests carrying none share a single budget between
+  them, so pair it with `ip` if that matters.
+- `segment: <name>` — the value bound to a named route segment, `1` for `:id` in `/users/:id`.
 
-- `status`: response status code (or a list of status codes)
+### Conditions
+
+What is counted, as opposed to what it is counted against. A request that fails a condition is
+served and not counted. Conditions are evaluated against the response, so they cannot decide whether
+to block — only whether to count.
+
+- `status: <code>` — count only responses with this status.
+
+```yaml
+io:throttle:
+  key: ip
+  condition:
+    status: 404
+  requests: 20
+  interval: 60
+  cooldown: 600
+```

package/documentation/notes/throttling.md

@@ -1,5 +1,11 @@
 # Decentralized Request Throttling
 
+> **Superseded.** The design below was never implemented. `io:throttle` now counts through
+> [comcount](https://github.com/temich/comcount), by way of the `stash` extension's `count`, which
+> solves the same problem the same way — per-process buffers, periodically reconciled through Redis,
+> never failing the request path — with the interval number derived from Redis' own clock instead of
+> each node's. This note is kept for the problem statement and the forces, which have not changed.
+
 ## Problem
 
 To prevent an unnecessary load, API requests should be throttled when made maliciously or due to an

package/features/io.throttle.feature

@@ -38,3 +38,130 @@ Feature: Request throttling
       """
       200 OK
       """
+
+  Scenario: Throttle requests to a route, whichever path they came in on
+    Given the `echo.beacon` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          /:id:
+            io:throttle:
+              key: [route]
+              requests: 1
+              interval: 5
+              cooldown: 5
+            GET:
+              dev:stub:
+                hello: true
+      """
+    When the following request is received:
+      """
+      GET /echo/beacon/1/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    # a different path of the same route, and the budget is already spent —
+    # keyed on `path` this would be 200
+    When the following request is received:
+      """
+      GET /echo/beacon/2/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      429 Too Many Requests
+      """
+
+  Scenario: Throttle requests per route segment
+    Given the `echo.beacon` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          /:id:
+            io:throttle:
+              key:
+                - segment: id
+              requests: 1
+              interval: 5
+              cooldown: 5
+            GET:
+              dev:stub:
+                hello: true
+      """
+    When the following request is received:
+      """
+      GET /echo/beacon/1/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    When the following request is received:
+      """
+      GET /echo/beacon/1/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      429 Too Many Requests
+      """
+    # another segment value, another budget
+    When the following request is received:
+      """
+      GET /echo/beacon/2/ HTTP/1.1
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: Throttle requests per identity
+    Given the `echo.beacon` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          auth:anyone: true
+          GET:
+            # declared after `auth:` on the node, and mandatory families run in
+            # their own order regardless: `auth` has to resolve the identity
+            # before `io` can key a quota on it
+            io:throttle:
+              key: [identity]
+              requests: 1
+              interval: 5
+              cooldown: 5
+            endpoint: hello
+      """
+    And transient identity alice
+    And transient identity bob
+    When the following request is received:
+      """
+      GET /echo/beacon/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ alice.token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    When the following request is received:
+      """
+      GET /echo/beacon/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ alice.token }}
+      """
+    Then the following reply is sent:
+      """
+      429 Too Many Requests
+      """
+    # bob's own budget, which requires auth to have resolved him before io keyed on him
+    When the following request is received:
+      """
+      GET /echo/beacon/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ bob.token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """

package/features/map.feature

@@ -21,9 +21,9 @@ Feature: HTTP context mapping
     Then the following reply is sent:
       """
       200 OK
-      content-type: application/yaml
       content-language: <result>
-      vary: accept-language, accept
+      vary: origin, accept-language, accept
+      content-type: application/yaml
 
       Hello <result>
       """
@@ -84,7 +84,7 @@ Feature: HTTP context mapping
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, accept-language, foo
+      access-control-allow-headers: accept, accept-language, authorization, content-type, foo, if-match, if-none-match, origin
       """
 
   Scenario: Mapping the value of an arbitrary header
@@ -108,8 +108,8 @@ Feature: HTTP context mapping
     Then the following reply is sent:
       """
       200 OK
+      vary: origin, foo, accept
       content-type: application/yaml
-      vary: foo, accept
 
       Hello bar
       """
@@ -135,8 +135,8 @@ Feature: HTTP context mapping
     Then the following reply is sent:
       """
       200 OK
+      vary: origin, accept
       content-type: application/yaml
-      vary: accept
 
       Hello nex.toa.io
       """

package/features/octets.cloudinary.feature

@@ -37,8 +37,8 @@ Feature: Octets with Cloudinary storage
       content-type: application/yaml
 
       id: ${{ id }}
-      type: image/png
       size: 473831
+      type: image/png
       """
     When the following request is received:
       """
@@ -49,18 +49,20 @@ Feature: Octets with Cloudinary storage
     Then the stream equals to `lenna.png` is sent with the following headers:
       """
       200 OK
-      content-type: image/png
-      content-length: 473831
       access-control-allow-origin: https://toa.io
+      content-length: 473831
+      content-type: image/png
       """
 
+  # SVG has no binary signature, so the type on upload is whatever the client states;
+  # on the way back it is what Cloudinary serves
   Scenario: Upload an svg
     When the stream of `sample.svg` is received with the following headers:
       """
       POST / HTTP/1.1
       host: nex.toa.io
       accept: application/yaml
-      content-type: application/octet-stream
+      content-type: image/svg+xml
       """
     Then the following reply is sent:
       """
@@ -75,7 +77,8 @@ Feature: Octets with Cloudinary storage
       GET /${{ id }} HTTP/1.1
       host: nex.toa.io
       """
-    Then the stream equals to `lenna.png` is sent with the following headers:
+    # Cloudinary rewrites the SVG it stores, so only the type is asserted
+    Then the following reply is sent:
       """
       200 OK
       content-type: image/svg+xml
@@ -140,8 +143,8 @@ Feature: Octets with Cloudinary storage
     Then the following reply is sent:
       """
       200 OK
-      transfer-encoding: chunked
       content-type: video/mp4
+      transfer-encoding: chunked
       """
 
     # after a while, Cloudinary returns a content-length response
@@ -153,8 +156,8 @@ Feature: Octets with Cloudinary storage
     Then the following reply is sent:
       """
       200 OK
-      content-type: video/mp4
       content-length: 175043
+      content-type: video/mp4
       """
 
     When the following request is received:
@@ -165,8 +168,8 @@ Feature: Octets with Cloudinary storage
     Then the following reply is sent:
       """
       200 OK
-      transfer-encoding: chunked
       content-type: video/mp4
+      transfer-encoding: chunked
       """
 
     When the following request is received:
@@ -206,8 +209,8 @@ Feature: Octets with Cloudinary storage
     Then the following reply is sent:
       """
       206 Partial Content
-      content-type: video/mp4
       content-length: 2
+      content-type: video/mp4
       """
 
     # gif

package/features/octets.download.feature

@@ -32,6 +32,7 @@ Feature: Download external resources
 
       id: ${{ id }}
       type: image/png
+      checksum: ${{ checksum }}
       """
 
     When the following request is received:
@@ -42,9 +43,9 @@ Feature: Download external resources
     Then the following reply is sent:
       """
       200 OK
-      content-type: image/png
       content-length: 1288
-      etag: "${{ id }}"
+      content-type: image/png
+      etag: "${{ checksum }}"
       """
 
     # origin is stored in the entry
@@ -185,5 +186,5 @@ Feature: Download external resources
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-attributes, content-location
+      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match, origin
       """

package/features/octets.entries.feature

@@ -56,6 +56,7 @@ Feature: Accessing metadata
       host: nex.toa.io
       accept: application/yaml
       content-type: application/octet-stream
+      content-id: lenna-ascii
       """
     And the stream of `lenna.png` is received with the following headers:
       """
@@ -63,10 +64,11 @@ Feature: Accessing metadata
       host: nex.toa.io
       accept: application/yaml
       content-type: application/octet-stream
+      content-id: lenna-png
       """
     When the following request is received:
       """
-      GET /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
+      GET /lenna-ascii HTTP/1.1
       host: nex.toa.io
       accept: application/vnd.toa.octets.entry+yaml
       """
@@ -75,7 +77,7 @@ Feature: Accessing metadata
       200 OK
       content-type: application/yaml
 
-      id: 10cf16b458f759e0d617f2f3d83599ff
-      type: application/octet-stream
+      id: lenna-ascii
       size: 8169
+      type: application/octet-stream
       """

package/features/octets.feature

@@ -56,8 +56,8 @@ Feature: Octets directive family
       content-type: application/yaml
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       """
     When the following request is received:
       """
@@ -67,15 +67,15 @@ Feature: Octets directive family
     Then the stream equals to `lenna.ascii` is sent with the following headers:
       """
       200 OK
-      content-type: application/octet-stream
       content-length: 8169
-      etag: ${{ ETAG }}
+      content-type: application/octet-stream
+      etag: "${{ ETAG }}"
       """
     When the following request is received:
       """
       GET /${{ id }} HTTP/1.1
       host: nex.toa.io
-      if-none-match: ${{ ETAG }}
+      if-none-match: "${{ ETAG }}"
       """
     Then the following reply is sent:
       """

package/features/octets.head.feature

@@ -35,6 +35,6 @@ Feature: Octets headers
     Then the following reply is sent:
       """
       200 OK
-      content-type: application/octet-stream
       content-length: 8169
+      content-type: application/octet-stream
       """

package/features/octets.location.feature

@@ -71,8 +71,8 @@ Feature: Octets location
       --cut
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       --cut
 
       step: echo

package/features/octets.meta.feature

@@ -85,8 +85,8 @@ Feature: Octets metadata
       200 OK
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       checksum: 10cf16b458f759e0d617f2f3d83599ff
       attributes:
         foo: 'true'
@@ -111,6 +111,6 @@ Feature: Octets metadata
     Then the following reply is sent:
       """
       204 No Content
+      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match, origin
       access-control-allow-origin: https://example.com
-      access-control-allow-headers: accept, authorization, content-type, etag, if-match, if-none-match, content-attributes
       """

package/features/octets.workflows.feature

@@ -39,14 +39,14 @@ Feature: Octets storage workflows
       --cut
 
       step: add-bar
+      status: completed
       output:
         bar: baz
-      status: completed
       --cut
 
       step: add-baz
       status: completed
-      output: 
+      output:
         add-foo:
           foo: bar
         add-bar:
@@ -115,8 +115,8 @@ Feature: Octets storage workflows
 
       --cut
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       --cut
 
       step: add-foo
@@ -124,10 +124,10 @@ Feature: Octets storage workflows
       --cut
 
       step: add-bar
+      status: completed
       error:
         code: ERROR
         message: Something went wrong
-      status: completed
       --cut--
       """
 
@@ -281,8 +281,8 @@ Feature: Octets storage workflows
       --cut
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       --cut
 
       step: concat
@@ -320,8 +320,8 @@ Feature: Octets storage workflows
       --cut
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       --cut
 
       step: authority
@@ -361,8 +361,8 @@ Feature: Octets storage workflows
       --cut
 
       id: ${{ id }}
-      type: application/octet-stream
       size: 8169
+      type: application/octet-stream
       --cut
 
       step: identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.267",
+  "version": "1.0.0-alpha.268",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -17,20 +17,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@simplewebauthn/server": "13.3.2",
+    "@simplewebauthn/server": "13.3.3",
     "@toa.io/core": "1.0.0-alpha.266",
     "@toa.io/generic": "1.0.0-alpha.254",
     "@toa.io/schemas": "1.0.0-alpha.263",
     "bcryptjs": "3.0.3",
-    "content-type": "2.0.0",
+    "content-type": "2.1.0",
     "error-value": "0.4.4",
-    "jose": "6.2.8",
-    "js-yaml": "5.2.3",
+    "jose": "6.2.10",
+    "js-yaml": "5.4.1",
     "lru-cache": "11.5.2",
     "matchacho": "0.6.0",
     "minimatch": "10.2.6",
-    "msgpackr": "2.0.5",
-    "negotiator": "1.0.0",
+    "msgpackr": "2.1.0",
+    "negotiator": "1.1.0",
     "openspan": "1.0.0-alpha.264",
     "paseto": "3.1.4"
   },
@@ -62,5 +62,5 @@
     },
     "testEnvironment": "node"
   },
-  "gitHead": "d2d1a69ee30f426975a835f77ed41bfc1ce4785e"
+  "gitHead": "0c2fe0acb44653a68b12600151d4d25f46a444be"
 }

package/schemas/io/throttle.cos.yaml

@@ -1,7 +1,14 @@
 definitions:
   component: &component
-    type: string
-    enum: [ip, path]
+    anyOf:
+      - type: string
+        enum: [ip, path, route, identity]
+      - type: object
+        properties:
+          segment:
+            type: string
+        required: [segment]
+        additionalProperties: false
   condition: &condition
     type: object
     properties: