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

package/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
+
+
+* feat(exposition)!: throttle by a distributed GCRA ([287eb25](https://github.com/toa-io/toa/commit/287eb254b11339b20ef011deb659eb11f225defe))
+
+
+### Performance Improvements
+
+* **exposition:** project io restrictions through a set ([d70b364](https://github.com/toa-io/toa/commit/d70b36478626dd29958a55ebf72f0373e07e34f5))
+* **exposition:** stop recomputing per-request what a route fixes ([b52f335](https://github.com/toa-io/toa/commit/b52f335023e58db42a21f1ee6bd99470e8547a2c))
+* **exposition:** tag a reply from the body already encoded ([e6ea7d7](https://github.com/toa-io/toa/commit/e6ea7d7b169783becddb2854ae6fb24caf611398))
+* **openspan:** create a span only when something records it ([a6efb0e](https://github.com/toa-io/toa/commit/a6efb0eed38393f4c169b067f23d7447f0169bca))
+
+
+### BREAKING CHANGES
+
+* `io:throttle` no longer takes `cooldown`, and its schema now
+rejects unknown properties, so a declaration carrying one fails at boot instead of
+being ignored quietly. Metering earns the budget back rather than locking a key
+out, so the lockout is expressed as a rate: `requests: 20, interval: 600` admits a
+burst of twenty and then one every thirty seconds, where `requests: 20, interval:
+60, cooldown: 600` used to refuse everything for ten minutes. The stash aspect's
+`count` is replaced by `meter`, which takes a batch of keys and debts and answers
+what the group has reached.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.269](https://github.com/toa-io/toa/compare/v1.0.0-alpha.268...v1.0.0-alpha.269) (2026-08-30)
+
+
+### Bug Fixes
+
+* **exposition:** check input restrictions before directives add to the body ([b37961a](https://github.com/toa-io/toa/commit/b37961aa43b8ea52fbbbfd8d447fd20a71fbbef6))
+
+
+
+
+
+# [1.0.0-alpha.268](https://github.com/toa-io/toa/compare/v1.0.0-alpha.267...v1.0.0-alpha.268) (2026-08-30)
+
+
+### Bug Fixes
+
+* **agent:** do not append a content-length a request already declares ([17893e9](https://github.com/toa-io/toa/commit/17893e9bc8c64c744dac2ad7cf057267a0932afb))
+* **exposition:** make the allowed CORS headers stable and per-gateway ([2ea3554](https://github.com/toa-io/toa/commit/2ea3554ad61bd4dc9246cebc30cad6cf553dcce5))
+* **exposition:** report the entity length on HEAD ([bf20086](https://github.com/toa-io/toa/commit/bf2008672d5f192bdeffa5d7c1d46fef7e06ea7b))
+* **exposition:** serialize the error a failed workflow step reports ([c11a3a6](https://github.com/toa-io/toa/commit/c11a3a6ecdf177227679bad590a886753cbdf2a5))
+* **exposition:** type the throttle key declaration precisely ([ac7d486](https://github.com/toa-io/toa/commit/ac7d4865f689f1a77f65ed3262da47fd49b62e81))
+
+
+
+
+
+# [1.0.0-alpha.267](https://github.com/toa-io/toa/compare/v1.0.0-alpha.266...v1.0.0-alpha.267) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.exposition
+
+
+
+
+
+# [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.exposition
+
+
+
+
+
+# [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.exposition
+
+
+
+
+
+# [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.exposition
+
+
+
+
+
+# [1.0.0-alpha.263](https://github.com/toa-io/toa/compare/v1.0.0-alpha.262...v1.0.0-alpha.263) (2026-08-29)
+
+
+### Bug Fixes
+
+* **exposition:** cancel the discovery settle timeout ([0124c9f](https://github.com/toa-io/toa/commit/0124c9f8956722b967681ac7bd49a26556761e66))
+
+
+### Performance Improvements
+
+* **exposition:** let the probe own the startup delay ([1cb8e04](https://github.com/toa-io/toa/commit/1cb8e0459981d0a47c68dce48e17fa1fceb79a61))
+* **exposition:** settle discovery as soon as the branches go quiet ([d40bafd](https://github.com/toa-io/toa/commit/d40bafd5b6c71f34a2fcac201697823870460fa5))
+
+
+
+
+
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Bug Fixes
+
+* **exposition:** serve endpoints declared in the context annotation ([49da8a4](https://github.com/toa-io/toa/commit/49da8a4234ee987b25023952d0622ce575dfb60c))
+* **introspection:** return the whole map over HTTP ([053c0cd](https://github.com/toa-io/toa/commit/053c0cd5c22b1a80bceb23d2cda68ede33a0d1c0))
+
+
+### Features
+
+* **core:** identify the origin of a call with `request.source` ([9da6b66](https://github.com/toa-io/toa/commit/9da6b66df852690351a1e82c7b8cc176fd89774a))
+* **operations:** let a service claim a path prefix on the host ([02677d1](https://github.com/toa-io/toa/commit/02677d17fcd4222b07c3be458d93bcc496a016a8))
+
+
+
+
+
+# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/extensions.exposition
+
+
+
+
+
+# [1.0.0-alpha.258](https://github.com/toa-io/toa/compare/v1.0.0-alpha.257...v1.0.0-alpha.258) (2026-08-24)
+
+
+### Bug Fixes
+
+* **exposition:** accept federation signature key as PEM ([121fb00](https://github.com/toa-io/toa/commit/121fb00a4e84ec31d65aa1f747f2a22770db9ba1))
+
+
+
+
+
+# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
+
+
+### Bug Fixes
+
+* **exposition:** allow null output of basic credentials info ([2a98d0c](https://github.com/toa-io/toa/commit/2a98d0c4c7dd510d57f23485fd516990c79e6759))
+* **exposition:** re-add deleted basic credentials ([93abdb7](https://github.com/toa-io/toa/commit/93abdb7c97f807d400a236c417af716dbd367189))
+* **exposition:** return identity id from federation inception ([4ddcb7e](https://github.com/toa-io/toa/commit/4ddcb7ee7e574d79f783816190381b5bd6eb2dce))
+* **exposition:** revive deleted federation credential on create ([89e6363](https://github.com/toa-io/toa/commit/89e6363778a5e503957c339d1626cda0827fbed8))
+* **storages.mongodb:** lift tombstone on set ([b33d227](https://github.com/toa-io/toa/commit/b33d227dbe1d6c95957d67d31bbe2543e1def8c1))
+
+
+### Features
+
+* **exposition:** add federation create operation ([0262d7d](https://github.com/toa-io/toa/commit/0262d7d18362d580fc1dd923225c9acba01e751a))
+* **exposition:** detach federation credential id from identity ([63a54e4](https://github.com/toa-io/toa/commit/63a54e44a63c846886d7ed55b29de3e85b4725ff))
+* **exposition:** return the credential from federation inception ([fced302](https://github.com/toa-io/toa/commit/fced302d16979d234f5a3dbf0ed3897362e95b90))
+* **exposition:** unique federation credential per identity and issuer ([0c3e11b](https://github.com/toa-io/toa/commit/0c3e11b2e2497319dc66d566330f8e03c4e35f8d))
+
+
+
+
+
+# [1.0.0-alpha.256](https://github.com/toa-io/toa/compare/v1.0.0-alpha.255...v1.0.0-alpha.256) (2026-08-23)
+
+
+### Features
+
+* add toa mono and discover components at components/* ([787a111](https://github.com/toa-io/toa/commit/787a111c8f83e56ebc734801c97106c585d034ea))

package/components/exposition.octets/manifest.toa.yaml

@@ -0,0 +1,29 @@
+namespace: exposition
+name: octets
+
+storages: ~
+
+operations:
+  put:
+    bindings: ~
+    input:
+      storage*: string
+      request*: ~
+      location: string
+      accept: string
+      limit: number
+      trust: ~ # array of strings or regular expressions
+    errors:
+      - LOCATION_UNTRUSTED
+      - LOCATION_LENGTH
+      - LOCATION_UNAVAILABLE
+      - INVALID_ID
+  get: &simple
+    bindings: ~
+    input:
+      storage*: string
+      path*: string
+      range: string
+      agent: string
+  head: *simple
+  delete: *simple

package/components/exposition.octets/operations/get.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function get (input, context) {
+  return await context.storages[input.storage].get(input.path, { range: input.range, agent: input.agent })
+}
+
+exports.effect = get

package/components/exposition.octets/operations/head.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function head (input, context) {
+  return await context.storages[input.storage].head(input.path)
+}
+
+exports.computation = head

package/components/exposition.octets/operations/put.js

@@ -0,0 +1,135 @@
+'use strict'
+
+const { Readable } = require('node:stream')
+const { posix } = require('node:path')
+const { Err } = require('error-value')
+const { match } = require('matchacho')
+
+async function put (input, context) {
+  const { storage, request, location, accept, limit, trust } = input
+  const url = request.url
+  const id = request.headers['content-id']
+  const claim = request.headers['content-type']
+  const attributes = parseAttributes(request.headers['content-attributes'])
+  const reference = request.headers['content-location']
+
+  /** @type {Readable} */
+  let body = request
+
+  const options = { claim, accept, attributes }
+
+  if (id !== undefined) {
+    if (!ID_RX.test(id))
+      return ERR_INVALID_ID
+
+    options.id = id
+  }
+
+  if (reference !== undefined) {
+    const length = Number.parseInt(request.headers['content-length'])
+
+    if (length !== 0)
+      return ERR_LENGTH
+
+    if (!trusted(reference, trust))
+      return ERR_UNTRUSTED
+
+    body = await download(reference)
+
+    if (body instanceof Error)
+      return body
+
+    options.origin = reference
+  }
+
+  if (limit !== undefined)
+    options.limit = limit
+
+  const path = posix.resolve(url, location ?? '.')
+
+  return context.storages[storage].put(path, body, options)
+}
+
+/**
+ * @param {string | string[] | undefined} values
+ * @returns {Record<string, string>}
+ */
+function parseAttributes (values) {
+  const attributes = {}
+
+  if (values === undefined)
+    return attributes
+
+  if (typeof values === 'string')
+    values = values.split(',')
+
+  for (const pair of values) {
+    const eq = pair.indexOf('=')
+    const key = (eq === -1 ? pair : pair.slice(0, eq)).trim()
+
+    attributes[key] = eq === -1 ? 'true' : pair.slice(eq + 1).trim()
+  }
+
+  return attributes
+}
+
+/**
+ * @param {string} location
+ * @return {Readable | Error}
+ */
+async function download (location) {
+  const response = await fetch(location)
+
+  if (!response.ok)
+    return ERR_UNAVAILABLE
+
+  return response.body === null ? ERR_UNAVAILABLE : Readable.fromWeb(
+    /** @type {import('node:stream/web').ReadableStream} **/ response.body)
+
+}
+
+/**
+ * @param {string} location
+ * @param {Trust | undefined} trust
+ * @return {boolean}
+ */
+function trusted (location, trust) {
+  if (trust === undefined)
+    return false
+
+  const url = toURL(location)
+
+  if (url === null)
+    return false
+
+  for (const permission of trust) {
+    const ok = match(permission,
+      String, (origin) => url.origin === origin,
+      RegExp, (pattern) => pattern.test(url.origin))
+
+    if (ok)
+      return true
+  }
+
+  return false
+}
+
+function toURL (location) {
+  try {
+    return new URL(location)
+  } catch (error) {
+    return null
+  }
+}
+
+const ERR_UNTRUSTED = new Err('LOCATION_UNTRUSTED', 'Location is not trusted')
+const ERR_LENGTH = new Err('LOCATION_LENGTH', 'Content-Length must be 0 when Content-Location is used')
+const ERR_UNAVAILABLE = new Err('LOCATION_UNAVAILABLE', 'Location is not available')
+const ERR_INVALID_ID = new Err('INVALID_ID', 'Invalid Content-ID')
+
+const ID_RX = /^[a-zA-Z0-9-_]{1,32}$/
+
+exports.effect = put
+
+/** @typedef {Array<string | RegExp>} Trust */
+/** @typedef {import('node:stream').Readable} Readable */

package/components/exposition.stash/manifest.toa.yaml

@@ -0,0 +1,21 @@
+namespace: exposition
+name: stash
+
+stash: ~
+
+operations:
+  meter:
+    bindings: ~ # the gateway calls this in its own process, over the loop
+    input:
+      type: object
+      properties:
+        keys:
+          type: array
+          items:
+            type: string
+        deltas:
+          type: array
+          items:
+            type: number
+      required: [keys, deltas]
+      additionalProperties: false