mqtt-plus 1.4.15 → 1.4.17

package/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+    "context": {
+        "fileName": "AGENTS.md"
+    }
+}

package/AGENTS.md

@@ -1,47 +1,41 @@
 
-AGENTS
-======
+# Overview for AI Agents
 
-This file provides guidance to Agentic AI Coding Tools when working with code in this repository.
+## Project Abstract
 
-Project Overview
-----------------
+MQTT+ (`mqtt-plus`) is a TypeScript library implementing four MQTT
+communication patterns with full type safety: Event Emission, Service
+Call (RPC), Source Fetch, and Sink Push. It uses `mqtt` as a peer
+dependency and builds to ESM, CJS, and UMD formats.
 
-MQTT+ (`mqtt-plus`) is a TypeScript library implementing four MQTT communication patterns
-with full type safety: Event Emission, Service Call (RPC), Source Fetch, and Sink Push.
-It uses `mqtt` as a peer dependency and builds to ESM, CJS, and UMD formats.
+## Technology Stack
 
-Commands
---------
+Build-Tools: npm, @rse/stx, vite, eslint, typescript
+Language:    TypeScript
+Libraries:   nanoid, cbor2, p-lazy, valibot, jose, @stablelib/pbkdf2, @stablelib/sha256
+Runtime:     Browser, Node.js
 
-MQTT+ plus uses NPM:
+## Build Commands
 
-```bash
-npm install             # install dependencies
-```
-
-Build and development commands use STX (`@rse/stx`) as the task runner:
+Build and development commands use NPM and STX (`@rse/stx`) as the task runner:
 
 ```bash
-npm start lint          # standard: perform static code analysis
-npm start build         # standard: build everything
-npm start test          # standard: run unit test suite
+npm install          # install dependencies
 
-npm start build-doc     # generate SVG diagrams from D2 sources only
-npm start dev           # development watch mode (rebuild on change)
-npm start sample        # run sample/sample.ts via `tsx`
+npm start lint       # standard: perform static code analysis
+npm start build      # standard: build everything
+npm start test       # standard: run unit test suite
 
-npm start clean         # remove dst-stage1/ and dst-stage2/
-npm start distclean     # remove node_modules/ and package-lock.json
-npm start publish       # publish to npm (restricted to maintainer host)
-```
+npm start build-doc  # generate SVG diagrams from D2 sources only
+npm start dev        # development watch mode (rebuild on change)
+npm start sample     # run sample/sample.ts via `tsx`
 
-Tests require an MQTT broker under run-time; the test suite starts/stops
-one automatically. If Docker is available, a Mosquitto broker is used;
-otherwise, the Aedes in-process broker serves as the fallback.
+npm start clean      # remove dst-stage1/ and dst-stage2/
+npm start distclean  # remove node_modules/ and package-lock.json
+npm start publish    # publish to npm (restricted to maintainer host)
+```
 
-Build Pipeline
---------------
+## Build Pipeline
 
 Two-stage build:
 
@@ -52,16 +46,22 @@ Two-stage build:
    `mqtt-plus.esm.js`, `mqtt-plus.cjs.js`, `mqtt-plus.umd.js`.
    UMD build includes Node polyfills (events, stream, buffer).
 
-Configuration lives in `etc/`: `tsc.json`, `vite.mts`, `eslint.mts`, `knip.jsonc`, `stx.conf`, `d2.mts`, `d2.theme.d2`, `logo.ai`, `logo.svg`.
+Configuration lives in `etc/`: `tsc.json`, `vite.mts`, `eslint.mts`,
+`knip.jsonc`, `stx.conf`, `d2.mts`, `d2.theme.d2`, `logo.ai`,
+`logo.svg`.
+
+Tests require an MQTT broker under run-time; the test suite starts/stops
+one automatically. If Docker is available, a Mosquitto broker is used;
+otherwise, the Aedes in-process broker serves as the fallback.
+For regression testing always use the all-in-one command `npm start build test`.
 
-Architecture
-------------
+## Architecture
 
 ### Trait-Based Mixin Tower
 
 The library is composed as a vertical chain of trait classes (mixins),
-each extending the previous. The final exported class `MQTTp` sits at
-the bottom of this chain:
+each extending the previous one. The final exported class `MQTTp` sits
+at the bottom of this chain:
 
 ```
     OptionsTrait        — configuration (id, codec, timeout, share, chunkSize, chunkCredit, topicMake/topicMatch)
@@ -85,63 +85,55 @@ Each trait lives in its own file: `src/mqtt-plus-<trait>.ts`.
 
 ### Key Source Files
 
-| File                            | Role |
-|---------------------------------|------|
-| `src/mqtt-plus.ts`              | Main entry point, re-exports public API types and the final MQTTp class |
-| `src/mqtt-plus-api.ts`          | Branded endpoint type definitions (Event, Service, Source, Sink) and APISchema generic |
-| `src/mqtt-plus-info.ts`         | Info/context object types passed to pattern callbacks (sender metadata, etc.) |
-| `src/mqtt-plus-error.ts`        | Spool (resource cleanup) and run (error handling) utilities |
-| `src/mqtt-plus-util.ts`         | PLazy, CreditGate flow control, and stream/buffer collection utilities |
-| `src/mqtt-plus-version.ts`      | Version utility for converting version strings to numeric format |
-| `src/mqtt-plus-options.ts`      | OptionsTrait — configuration (id, codec, timeout, share, chunkSize, chunkCredit, topicMake/topicMatch) |
-| `src/mqtt-plus-codec.ts`        | CodecTrait — CBOR and JSON codec encoding/decoding |
-| `src/mqtt-plus-encode.ts`       | EncodeTrait — string/buffer conversion utilities (str2buf, buf2str) |
-| `src/mqtt-plus-msg.ts`          | MsgTrait — message class definitions, valibot schemas, and parsing logic |
-| `src/mqtt-plus-trace.ts`        | TraceTrait — EventEmitter and structured logging |
-| `src/mqtt-plus-base.ts`         | BaseTrait — MQTT client connection, subscription management, message routing |
-| `src/mqtt-plus-subscription.ts` | SubscriptionTrait — RefCountedSubscription class and ref-counted MQTT topic subscription management |
-| `src/mqtt-plus-timer.ts`        | TimerTrait — named timer management (refresh/clear) |
-| `src/mqtt-plus-meta.ts`         | MetaTrait — instance and per-request metadata management |
-| `src/mqtt-plus-auth.ts`         | AuthTrait — JWT authentication (jose) and role-based access control |
-| `src/mqtt-plus-event.ts`        | EventTrait — Event Emission communication pattern (event/emit) |
-| `src/mqtt-plus-service.ts`      | ServiceTrait — Service Call / RPC communication pattern (service/call) |
-| `src/mqtt-plus-source.ts`       | SourceTrait — Source Fetch communication pattern (source/fetch) |
-| `src/mqtt-plus-sink.ts`         | SinkTrait — Sink Push communication pattern (sink/push) |
-
-### Documentation
-
-The `doc/` directory contains Markdown documentation, D2 diagram sources,
-and generated SVG files:
-
-- `doc/mqtt-plus-api.md` — public API reference
-- `doc/mqtt-plus-architecture.{d2,svg,md}` — architecture overview (diagram + docs)
-- `doc/mqtt-plus-broker-setup.md` — MQTT broker setup guide
-- `doc/mqtt-plus-comm.md` — communication patterns overview
-- `doc/mqtt-plus-comm-event-emission.{d2,svg}` — Event Emission pattern diagram
-- `doc/mqtt-plus-comm-service-call.{d2,svg}` — Service Call pattern diagram
-- `doc/mqtt-plus-comm-sink-push.{d2,svg}` — Sink Push pattern diagram
-- `doc/mqtt-plus-comm-source-fetch.{d2,svg}` — Source Fetch pattern diagram
-- `doc/mqtt-plus-internals.md` — internal implementation details
-
-Regenerate diagrams with `npm start build-doc` (requires the `etc/d2.mts` helper script).
-
-### Tests
-
-Test files live in `tst/`:
-
-| File                              | Role |
-|-----------------------------------|------|
-| `tst/mqtt-plus-0-fixture.ts`      | Shared test fixture setup (broker, MQTTp instances, etc.) |
-| `tst/mqtt-plus-0-broker.ts`       | Broker dispatch: creates Aedes or Mosquitto broker based on env |
-| `tst/mqtt-plus-0-broker-aedes.ts` | Helper for starting/stopping the Aedes MQTT broker |
-| `tst/mqtt-plus-0-broker-mosquitto.ts` | Helper for starting/stopping the Mosquitto MQTT broker |
-| `tst/mqtt-plus-1-api.spec.ts`     | API type and endpoint definition tests |
-| `tst/mqtt-plus-2-event.spec.ts`   | Event Emission pattern tests |
-| `tst/mqtt-plus-3-service.spec.ts` | Service Call / RPC pattern tests |
-| `tst/mqtt-plus-4-sink.spec.ts`    | Sink Push pattern tests |
-| `tst/mqtt-plus-5-source.spec.ts`  | Source Fetch pattern tests |
-| `tst/mqtt-plus-6-misc.spec.ts`    | Miscellaneous / edge-case tests |
-| `tst/tsc.json`                    | TypeScript configuration for the test directory |
+- `src/mqtt-plus.ts`: Main entry point, re-exports public API types and the final MQTTp class
+- `src/mqtt-plus-api.ts`: Branded endpoint type definitions (Event, Service, Source, Sink) and APISchema generic
+- `src/mqtt-plus-info.ts`: Info/context object types passed to pattern callbacks (sender metadata, etc.)
+- `src/mqtt-plus-error.ts`: Spool (resource cleanup) and run (error handling) utilities
+- `src/mqtt-plus-util.ts`: PLazy, CreditGate flow control, and stream/buffer collection utilities
+- `src/mqtt-plus-version.ts`: Version utility for converting version strings to numeric format
+- `src/mqtt-plus-options.ts`: OptionsTrait — configuration (id, codec, timeout, share, chunkSize, chunkCredit, topicMake/topicMatch)
+- `src/mqtt-plus-codec.ts`: CodecTrait — CBOR and JSON codec encoding/decoding
+- `src/mqtt-plus-encode.ts`: EncodeTrait — string/buffer conversion utilities (str2buf, buf2str)
+- `src/mqtt-plus-msg.ts`: MsgTrait — message class definitions, valibot schemas, and parsing logic
+- `src/mqtt-plus-trace.ts`: TraceTrait — EventEmitter and structured logging
+- `src/mqtt-plus-base.ts`: BaseTrait — MQTT client connection, subscription management, message routing
+- `src/mqtt-plus-subscription.ts`: SubscriptionTrait — RefCountedSubscription class and ref-counted MQTT topic subscription management
+- `src/mqtt-plus-timer.ts`: TimerTrait — named timer management (refresh/clear)
+- `src/mqtt-plus-meta.ts`: MetaTrait — instance and per-request metadata management
+- `src/mqtt-plus-auth.ts`: AuthTrait — JWT authentication (jose) and role-based access control
+- `src/mqtt-plus-event.ts`: EventTrait — Event Emission communication pattern (event/emit)
+- `src/mqtt-plus-service.ts`: ServiceTrait — Service Call / RPC communication pattern (service/call)
+- `src/mqtt-plus-source.ts`: SourceTrait — Source Fetch communication pattern (source/fetch)
+- `src/mqtt-plus-sink.ts`: SinkTrait — Sink Push communication pattern (sink/push)
+
+### Key Test Files
+
+- `tst/mqtt-plus-0-fixture.ts`: Shared test fixture setup (broker, MQTTp instances, etc.)
+- `tst/mqtt-plus-0-broker.ts`: Broker dispatch: creates Aedes or Mosquitto broker based on env
+- `tst/mqtt-plus-0-broker-aedes.ts`: Helper for starting/stopping the Aedes MQTT broker
+- `tst/mqtt-plus-0-broker-mosquitto.ts`: Helper for starting/stopping the Mosquitto MQTT broker
+- `tst/mqtt-plus-1-api.spec.ts`: API type and endpoint definition tests
+- `tst/mqtt-plus-2-event.spec.ts`: Event Emission pattern tests
+- `tst/mqtt-plus-3-service.spec.ts`: Service Call / RPC pattern tests
+- `tst/mqtt-plus-4-sink.spec.ts`: Sink Push pattern tests
+- `tst/mqtt-plus-5-source.spec.ts`: Source Fetch pattern tests
+- `tst/mqtt-plus-6-misc.spec.ts`: Miscellaneous / edge-case tests
+- `tst/mqtt-plus-7-spool.spec.ts`: Spool (resource cleanup) utility tests
+- `tst/mqtt-plus-8-run.spec.ts`: Run (error handling) utility tests
+- `tst/tsc.std.json`: TypeScript configuration for the test directory (standard)
+- `tst/tsc.cov.json`: TypeScript configuration for the test directory (coverage)
+
+### Key Documentation Files
+
+- `doc/mqtt-plus-api.md`: public API reference
+- `doc/mqtt-plus-architecture.{d2,svg,md}`: architecture overview (diagram + docs)
+- `doc/mqtt-plus-broker-setup.md`: MQTT broker setup guide
+- `doc/mqtt-plus-comm.md`: communication patterns overview
+- `doc/mqtt-plus-comm-event-emission.{d2,svg}`: Event Emission pattern diagram
+- `doc/mqtt-plus-comm-service-call.{d2,svg}`: Service Call pattern diagram
+- `doc/mqtt-plus-comm-sink-push.{d2,svg}`: Sink Push pattern diagram
+- `doc/mqtt-plus-comm-source-fetch.{d2,svg}`: Source Fetch pattern diagram
+- `doc/mqtt-plus-internals.md`: internal implementation details
 
 ### Type System
 
@@ -150,8 +142,7 @@ The API uses branded types (`Event<...>`, `Service<...>`, `Source<...>`,
 type parameter threads through the trait tower, enabling full type
 inference for pattern names and parameter types.
 
-Coding Style
-------------
+## Coding Style
 
 - 4-space indentation, double quotes, no semicolons
 - Stroustrup brace style (`else`/`catch`/`finally` on new line after closing brace)

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 ChangeLog
 =========
 
+1.4.17 (2026-04-11)
+-------------------
+
+- IMPROVEMENT: add "signal" field to info of service and event callbacks for signalling abortion
+- IMPROVEMENT: add more utility functions related to timers
+- IMPROVEMENT: support cancelling push operations with a credit of zero
+- IMPROVEMENT: let Spool.unroll() always execute the cleanup callback
+- IMPROVEMENT: perform a minimum version check in the protocol
+- IMPROVEMENT: log invalid requests with missing senders
+- IMPROVEMENT: add upper bound for the nanoid iteration
+- IMPROVEMENT: perform topic receiver matching and validate service response names
+- IMPROVEMENT: move the destroyed flag to the base class and protect other methods
+- IMPROVEMENT: send errors to peer and provide AggregateError to not lose errors
+- IMPROVEMENT: bump minimum Node version to 20 for ES2022
+- BUGFIX: Spool.unroll() silently skipped remaining cleanups on first async failure
+- BUGFIX: improve semantics of info.authenticated field for event/service/sink/source in case of optional authentication
+- BUGFIX: in the ReadableTee class, do not run read() twice: once ourself and once via the base class
+- BUGFIX: correctly propagate description in run() also to finally callback
+- BUGFIX: fix resource handling in source trait
+- BUGFIX: avoid race conditions and unhandled promise rejections in async processing
+- BUGFIX: fix cleanup and error handling across sink/source traits
+- BUGFIX: fix Mosqitto ACL
+- UPDATE: upgrade NPM dependencies
+- CLEANUP: various code cleanups (callback handling, settle code, destroy handling, termination, subscriptions)
+- CLEANUP: align with ensureError code and fix typos
+
+1.4.16 (2026-03-27)
+-------------------
+
+- IMPROVEMENT: allow source/sink operations to be aborted via a signal
+- IMPROVEMENT: support `info.buffer` to be a plain `Uint8Array` for sources
+- IMPROVEMENT: provide callback indicating which field is consumed
+- IMPROVEMENT: improve credit-based flow control enforcement
+- IMPROVEMENT: validate and deduplicate request IDs
+- IMPROVEMENT: lock responder for communication
+- IMPROVEMENT: improve backpressure and stream handling
+- IMPROVEMENT: improve meta handling
+- IMPROVEMENT: improve typing
+- IMPROVEMENT: use cross-env for better script portability
+- IMPROVEMENT: switch "npm start test" procedure to individual tasks for portability
+- BUGFIX: in sink and source traits: do not miss stream data in case the stream is consumed as a buffer
+- BUGFIX: fix error handling and prevent unhandled exceptions in sink and source traits
+- BUGFIX: fix message name mismatch and cancellation handling
+- BUGFIX: guard for already destroyed streams
+- BUGFIX: use .cjs for file extension of CJS variant
+- CLEANUP: align and track spool handling in source trait
+- CLEANUP: align and guard timer handling
+- CLEANUP: merge handlers into one
+
 1.4.15 (2026-03-14)
 -------------------
 

package/README.md

@@ -165,7 +165,7 @@ Main documentation:
 - [**Communication Patterns**](doc/mqtt-plus-comm.md)
 - [**Application Programming Interface (API)**](doc/mqtt-plus-api.md)
 
-Additional auxilliary documentation:
+Additional auxiliary documentation:
 
 - [Extra: Architecture Overview](doc/mqtt-plus-architecture.md)
 - [Extra: Internal Protocol](doc/mqtt-plus-internals.md)

package/doc/mqtt-plus-api.md

@@ -250,9 +250,10 @@ Register for an event.
 - The optional `auth` enables authentication validation on incoming events.
   When set to a role name string (e.g., `"admin"`), authentication is required
   and the token must include that role. When set to an object `{ mode, roles }`,
-  the mode can be `"require"` (reject unauthenticated) or `"optional"` (accept all
-  but reflect validation result in `info.authenticated`), and roles specifies
-  the required role names.
+  the mode can be `"require"` (reject unauthenticated, so `info.authenticated`
+  is always `true` in the callback) or `"optional"` (accept all, but set
+  `info.authenticated` to `true` or `false` to reflect the validation result),
+  and roles specifies the required role names.
 
 - Internally, on the MQTT broker, the topics generated by
   `topicMake(name, "event-emission")` (default: `${name}/event-emission/any` and
@@ -380,9 +381,10 @@ Register a service.
 - The optional `auth` enables authentication validation on incoming service calls.
   When set to a role name string (e.g., `"admin"`), authentication is required
   and the token must include that role. When set to an object `{ mode, roles }`,
-  the mode can be `"require"` (reject unauthenticated with error response) or
-  `"optional"` (accept all but reflect validation result in `info.authenticated`),
-  and roles specifies the required role names.
+  the mode can be `"require"` (reject unauthenticated with error response, so
+  `info.authenticated` is always `true` in the callback) or `"optional"` (accept
+  all, but set `info.authenticated` to `true` or `false` to reflect the validation
+  result), and roles specifies the required role names.
 
 - Internally, on the MQTT broker, the topics generated by
   `topicMake(name, "service-call-request")` (default: `${name}/service-call-request/any` and
@@ -437,6 +439,7 @@ Sink Registration
                 receiver?:      string,
                 authenticated?: boolean,
                 meta?:          Record<string, any>,
+                signal:         AbortSignal,
                 stream:         Readable,
                 buffer:         Promise<Uint8Array>
             }
@@ -451,6 +454,7 @@ Sink Registration
                 receiver?:      string,
                 authenticated?: boolean,
                 meta?:          Record<string, any>,
+                signal:         AbortSignal,
                 stream:         Readable,
                 buffer:         Promise<Uint8Array>
             }
@@ -467,6 +471,11 @@ Register a sink for receiving data.
 - The `callback` is called with the `params` passed to a remote `push()`.
   The `info.stream` provides a Node.js `Readable` stream for consuming the pushed data.
   The `info.buffer` provides a lazy `Promise<Uint8Array>` that resolves to the complete data once the stream ends.
+  The `info.signal` is aborted when the push request is cancelled, times out, or is otherwise torn down,
+  allowing the sink handler to stop any related side work cooperatively.
+  When the sink handler's stream closes abnormally (before normal completion),
+  a cancel signal (`credit=0`) is automatically sent to the pusher to abort
+  the data transfer on the sender side.
   The `info.meta` contains optional metadata sent by the pusher via `push()`.
 
 - The optional `options` allows setting MQTT.js `subscribe()` options like `qos`.
@@ -482,9 +491,10 @@ Register a sink for receiving data.
   When set to a role name string (e.g., `"admin"`), authentication
   is required and the token must include that role. When set to an
   object `{ mode, roles }`, the mode can be `"require"` (reject
-  unauthenticated) or `"optional"` (accept all but reflect validation
-  result in `info.authenticated`), and roles specifies the required
-  role names.
+  unauthenticated, so `info.authenticated` is always `true` in the
+  callback) or `"optional"` (accept all, but set `info.authenticated`
+  to `true` or `false` to reflect the validation result), and roles
+  specifies the required role names.
 
 - Internally, on the MQTT broker, the topics generated by
   `topicMake(name, "sink-push-request")`
@@ -528,9 +538,12 @@ Pushes data to all established sinks or a specific sink handler.
   configurable via `chunkSize` option) and sent over MQTT until the
   stream is closed or the buffer is fully transferred.
   The returned `Promise` resolves when the entire data has been pushed.
+  If the receiver cancels the push (via a cancel signal with `credit=0`),
+  the returned `Promise` rejects with a cancellation error.
 
 - The remote `sink()` `callback` is called with `params` and an `info` object
-  containing `stream` (`Readable`) for consuming the pushed data,
+  containing `signal` (`AbortSignal`) for cooperative cancellation,
+  `stream` (`Readable`) for consuming the pushed data,
   `buffer` (lazy `Promise<Uint8Array>`) that resolves to the complete
   data once the stream ends, and `meta` (`Record<string, any> |
   undefined`) containing the metadata sent by the pusher.
@@ -559,8 +572,9 @@ Source Registration
                 receiver?:      string,
                 authenticated?: boolean,
                 meta?:          Record<string, any>,
+                signal:         AbortSignal,
                 stream?:        Readable,
-                buffer?:        Promise<Uint8Array>
+                buffer?:        Promise<Uint8Array> | Uint8Array
             }
         ) => void | Promise<void>
     ): Promise<Registration>
@@ -573,8 +587,9 @@ Source Registration
                 receiver?:      string,
                 authenticated?: boolean,
                 meta?:          Record<string, any>,
+                signal:         AbortSignal,
                 stream?:        Readable,
-                buffer?:        Promise<Uint8Array>
+                buffer?:        Promise<Uint8Array> | Uint8Array
             }
         ) => void | Promise<void>,
         options?: MQTT::IClientSubscribeOptions,
@@ -588,7 +603,9 @@ Register a source for sending data.
 
 - The `callback` is called with the `params` passed to a remote `fetch()`.
   The `callback` should set `info.stream` to a `Readable` or
-  `info.buffer` to a `Promise<Uint8Array>` containing the data.
+  `info.buffer` to a `Promise<Uint8Array>` or `Uint8Array` containing the data.
+  The `info.signal` is aborted when the fetch request is cancelled, times out,
+  or is otherwise torn down, allowing the source handler to stop producing data.
   Optionally, the `callback` can set `info.meta` to a `Record<string,
   any>` to send metadata back with the response.
 
@@ -605,9 +622,10 @@ Register a source for sending data.
   When set to a role name string (e.g., `"admin"`), authentication
   is required and the token must include that role. When set to an
   object `{ mode, roles }`, the mode can be `"require"` (reject
-  unauthenticated) or `"optional"` (accept all but reflect validation
-  result in `info.authenticated`), and roles specifies the required
-  role names.
+  unauthenticated, so `info.authenticated` is always `true` in the
+  callback) or `"optional"` (accept all, but set `info.authenticated`
+  to `true` or `false` to reflect the validation result), and roles
+  specifies the required role names.
 
 - Internally, on the MQTT broker, the topics generated by
   `topicMake(name, "source-fetch-request")`
@@ -658,7 +676,8 @@ Fetches data from any source or from a specific source.
   optional metadata sent by the source when the first chunk arrives.
 
 - The remote `source()` `callback` is called with `params` and
-  should set `info.stream` to a `Readable` or `info.buffer` to
+  receives `info.signal` (`AbortSignal`) for cooperative cancellation
+  and should set `info.stream` to a `Readable` or `info.buffer` to
   a `Promise<Uint8Array>` containing the data. Optionally, the
   `callback` can set `info.meta` to send metadata back with the
   response. If the remote `callback` throws an exception, this
@@ -703,4 +722,3 @@ Example:
     const ui8a   = mqttp.arr2buf(buffer)
     const buffer = mqttp.buf2arr(ui8a, Buffer)
     const i8a    = mqttp.buf2arr(ui8a, Int8Array)
-

package/doc/mqtt-plus-architecture.md

@@ -2,7 +2,7 @@
 MQTT+ Architecture
 ==================
 
-**MQTT+** is composed as a vertical chain of API and infratructure trait
+**MQTT+** is composed as a vertical chain of API and infrastructure trait
 classes (mixins), each extending the previous. Additionally, some base
 modules complement the functionality.
 

package/doc/mqtt-plus-broker-setup.md

@@ -69,7 +69,7 @@ pattern read      example/server/+/service-call-response/%c
 
 topic   read      example/client/+/service-call-request/any
 pattern read      example/client/+/service-call-request/%c
-pattern write     example/client/+/service-call-response/%c
+pattern write     example/client/+/service-call-response/+
 
 #   ---- source fetch ----
 
@@ -87,7 +87,7 @@ pattern read      example/server/+/sink-push-response/%c
 
 topic   read      example/client/+/sink-push-request/any
 pattern read      example/client/+/sink-push-request/%c
-pattern write     example/client/+/sink-push-response/%c
+pattern write     example/client/+/sink-push-response/+
 
 #   ==== server/authenticated ACL ====
 

package/doc/mqtt-plus-comm.md

@@ -50,7 +50,9 @@ chunks as a stream with arguments.
 > In contrast to the regular MQTT message publish/subscribe, this
 > pattern allows to transfer arbitrary amounts of arbitrary data by
 > chunking the data via a stream. Additionally, it supports authentication
-> and meta-data, etc.
+> and meta-data, provides an `AbortSignal` to the sink handler for
+> cooperative cancellation, and allows the receiver to cancel an
+> in-progress push via a cancel signal (`credit=0`), etc.
 
 ![Sink Push](mqtt-plus-comm-sink-push.svg)
 
@@ -67,7 +69,7 @@ data chunks as a stream with arguments.
 > In contrast to the regular MQTT message publish/subscribe, this
 > pattern allows to transfer arbitrary amounts of arbitrary data by
 > chunking the data via a stream. Additionally, it supports
-> authentication and meta-data, etc.
+> authentication and meta-data, and provides an `AbortSignal` to the
+> source handler for cooperative cancellation, etc.
 
 ![Source Fetch](mqtt-plus-comm-source-fetch.svg)
-

package/doc/mqtt-plus-internals.md

@@ -138,7 +138,7 @@ Exactly one of `result` or `error` is present.
 | Field    | Type      | Required | Description                         |
 |----------|-----------|----------|-------------------------------------|
 | `name`   | `string`  | yes      | Sink endpoint name                  |
-| `credit` | `integer` | yes      | Number of additional credits (min 1)|
+| `credit` | `integer` | yes      | Number of additional credits (min 0). A value of `0` is a **cancel signal**, indicating that the receiver wants to abort the push stream. |
 
 ### `source-fetch-request`
 
@@ -272,6 +272,16 @@ Setting `chunkCredit` to `0` disables flow control entirely.
 | Sink Push    | Sink          | Pusher          | `sink-push-credit`      |
 | Source Fetch | Fetcher       | Source          | `source-fetch-credit`   |
 
+### Receiver-Initiated Cancellation (Sink Push)
+
+The sink (receiver) can cancel an in-progress push by sending a
+`sink-push-credit` message with `credit` set to `0`. This acts as
+a **cancel signal**: the pusher aborts the data transfer immediately
+and does not send an error chunk back to the receiver (since the
+cancellation originated from the receiver itself). On the receiver
+side, the `AbortSignal` provided to the sink callback is triggered
+when the push stream closes abnormally.
+
 Authentication
 --------------
 

package/dst-stage1/mqtt-plus-auth.js

@@ -86,16 +86,8 @@ export class AuthTrait extends MetaTrait {
     async authenticated(clientId, tokens, option) {
         let authenticated = false;
         /*  determine authentication configuration  */
-        let mode;
-        let roles;
-        if (typeof option === "string") {
-            mode = "require";
-            roles = [option];
-        }
-        else {
-            mode = option.mode;
-            roles = option.roles;
-        }
+        const roles = typeof option === "string"
+            ? [option] : option.roles;
         /*  iterate over all roles and try to authenticate token (first-match, max 8)  */
         if (tokens !== undefined) {
             for (const token of tokens.slice(0, 8)) {
@@ -120,9 +112,6 @@ export class AuthTrait extends MetaTrait {
                     break;
             }
         }
-        /*  handle optional case  */
-        if (!authenticated && mode === "optional")
-            authenticated = true;
         return authenticated;
     }
 }

package/dst-stage1/mqtt-plus-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"mqtt-plus-auth.js","sourceRoot":"","sources":["../src/mqtt-plus-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mqtt-plus-auth.js","sourceRoot":"","sources":["../src/mqtt-plus-auth.ts"],"names":[],"mappings":"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"}

package/dst-stage1/mqtt-plus-base.d.ts

@@ -6,11 +6,12 @@ import { Spool } from "./mqtt-plus-error";
 export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     private mqtt;
     private messageHandler;
+    protected destroyed: boolean;
     protected onRequest: Map<string, (message: any, topicName: string) => void | Promise<void>>;
     protected onResponse: Map<string, (message: any, topicName: string) => void | Promise<void>>;
     constructor(mqtt: MqttClient | null, options?: Partial<APIOptions>);
     destroy(): Promise<void>;
-    protected makeRegistration(spool: Spool, kind: string, name: string, key: string): Registration;
+    protected makeRegistration(spool: Spool, kind: string, name: string): Registration;
     protected subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
     protected unsubscribeTopic(topic: string): Promise<void>;
     protected publishToTopic(topic: string, message: string | Uint8Array, options?: IClientPublishOptions): Promise<void>;