mqtt-plus 0.9.6 → 0.9.7

package/README.md

@@ -42,22 +42,6 @@ communication patterns with type safety:
 
   ![Event Emission](doc/mqtt-plus-1-event-emission.svg)
 
-- **Stream Transfer**:
-
-  Stream Transfer is a *uni-directional* communication pattern.
-  A stream is the combination of a stream name, a `Readable` stream object and optionally zero or more arguments.
-  You *attach* to a stream.
-  When a stream is *transferred*, either a single particular attacher (in case of
-  a directed stream transfer) or all attachers are called and receive the
-  arguments as extra information. The `Readable` stream is available via
-  `info.stream` in the attacher callback.
-
-  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.
-
-  ![Stream Transfer](doc/mqtt-plus-2-stream-transfer.svg)
-
 - **Service Call**:
 
   Service Call is a *bi-directional* communication pattern.
@@ -73,18 +57,24 @@ communication patterns with type safety:
   Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call)
   (RPC) style communication.
 
-  ![Service Call](doc/mqtt-plus-3-service-call.svg)
+  ![Service Call](doc/mqtt-plus-2-service-call.svg)
 
 - **Resource Transfer**:
 
   Resource Transfer is a *bi-directional* communication pattern.
   A Resource is the combination of a resource name and optionally zero or more arguments.
   You *provision* for a resource transfer.
-  When a resource is *fetched* or *pushed*, a single particular provisioner (in case
+  When a resource is *fetched*, a single particular provisioner (in case
   of a directed resource transfer) or one arbitrary provisioner is called and
-  sends or receives the resource and its arguments.
+  sends the resource and its arguments.
+  When a resource is *pushed*, the provisioner receives the resource data
+  as a stream with arguments.
 
-  ![Resource Transfer](doc/mqtt-plus-4-resource-transfer.svg)
+  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.
+
+  ![Resource Transfer](doc/mqtt-plus-3-resource-transfer.svg)
 
 Usage
 -----
@@ -92,7 +82,7 @@ Usage
 ### API:
 
 The API type defines the available endpoints. Use the marker types
-`Event<T>`, `Stream<T>`, and `Service<T>` to declare the communication
+`Event<T>`, `Service<T>`, and `Resource<T>` to declare the communication
 pattern of each endpoint:
 
 ```ts
@@ -100,16 +90,15 @@ import type * as MQTTpt from "mqtt-plus"
 
 export type API = {
     "example/sample":   MQTTpt.Event<(a1: string, a2: number) => void>
-    "example/upload":   MQTTpt.Stream<(name: string) => void>
     "example/hello":    MQTTpt.Service<(a1: string, a2: number) => string>
     "example/resource": MQTTpt.Resource<(filename: string) => void>
 }
 ```
 
 The marker types ensure that `subscribe()` and `emit()` only accept
-`Event<T>` endpoints, `attach()` and `transfer()` only accept
-`Stream<T>` endpoints, and `register()` and `call()` only accept
-`Service<T>` endpoints.
+`Event<T>` endpoints, `register()` and `call()` only accept
+`Service<T>` endpoints, and `provision()`, `fetch()` and `push()` only
+accept `Resource<T>` endpoints.
 
 ### Server:
 
@@ -178,18 +167,27 @@ The **MQTT+** API provides the following methods:
   The `mqtt` is the [MQTT.js](https://www.npmjs.com/package/mqtt) instance,
   which has to be established separately.
 
+  Use `destroy()` to clean up when the instance is no longer needed.
+
   The optional `options` object supports the following fields:
   - `id`: Custom MQTT peer identifier (default: auto-generated NanoID).
   - `codec`: Encoding format (default: `cbor`).
   - `timeout`: Communication timeout in milliseconds (default: `10000`).
-  - `chunkSize`: Chunk size in bytes for stream transfers (default: `16384`).
+  - `chunkSize`: Chunk size in bytes for resource transfers (default: `16384`).
   - `topicMake`: Custom topic generation function.
-    The `operation` parameter is one of: `event-emission`, `stream-transfer`, `service-call-request`, `service-call-response`, `resource-transfer-request`, `resource-transfer-response`.
+    The `operation` parameter is one of: `event-emission`, `service-call-request`, `service-call-response`, `resource-transfer-request`, `resource-transfer-response`.
     (default: `` (name, operation, peerId) => `${name}/${operation}` + (peerId ? `/${peerId}` : "/any") ``)
   - `topicMatch`: Custom topic matching function.
     Returns `{ name, operation, peerId? }` or `null` if no match. The `peerId` is `undefined` for broadcast topics (ending with `/any`).
     (default: `` (topic) => { const m = topic.match(/^(.+)\/([^/]+)\/([^/]+)$/); return m ? { name: m[1], operation: m[2], peerId: m[3] === "any" ? undefined : m[3] } : null } ``)
 
+- **Destruction**:<br/>
+
+      destroy(): void
+
+  Clean up the MQTT+ instance by removing all event listeners.
+  Call this method when the instance is no longer needed.
+
 - **Event Subscription**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
@@ -213,30 +211,6 @@ The **MQTT+** API provides the following methods:
   `${event}/event-emission/${peerId}`) are subscribed. Returns a
   `Subscription` object with an `unsubscribe()` method.
 
-- **Stream Attachment**:<br/>
-
-      /*  (simplified TypeScript API method signature)  */
-      attach(
-          stream:   string,
-          options?: MQTT::IClientSubscribeOptions
-          callback: (
-              ...params: any[],
-              info: { sender: string, receiver?: string, stream: stream.Readable }
-          ) => void
-      ): Promise<Attachment>
-
-  Attach to (observe) a stream.
-  The `stream` has to be a valid MQTT topic name.
-  The optional `options` allows setting MQTT.js `subscribe()` options like `qos`.
-  The `callback` is called with the `params` passed to a remote `transfer()`.
-  The `info.stream` provides a Node.js `Readable` stream for consuming the transferred data.
-  There is no return value of `callback`.
-
-  Internally, on the MQTT broker, the topics generated by
-  `topicMake(stream, "stream-transfer")` (default: `${stream}/stream-transfer/any` and
-  `${stream}/stream-transfer/${peerId}`) are subscribed. Returns an
-  `Attachment` object with an `unattach()` method.
-
 - **Service Registration**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
@@ -268,20 +242,32 @@ The **MQTT+** API provides the following methods:
           options?: MQTT::IClientSubscribeOptions
           callback: (
               ...params: any[],
-              info: { sender: string, receiver?: string, resource: Buffer | null }
+              info: {
+                  sender: string,
+                  receiver?: string,
+                  resource: Buffer | Readable | null,
+                  stream?: Readable,
+                  buffer?: Promise<Buffer>
+              }
           ) => void
       ): Promise<Provisioning>
 
-  Provision a resource.
+  Provision a resource for both fetch requests and pushed data.
   The `resource` has to be a valid MQTT topic name.
   The optional `options` allows setting MQTT.js `subscribe()` options like `qos`.
-  The `callback` is called with the `params` passed to a remote `fetch()`.
-  The `callback` should set `info.resource` to a `Buffer` containing the resource data.
+
+  For **fetch requests**: The `callback` is called with the `params` passed to a remote `fetch()`.
+  The `callback` should set `info.resource` to a `Buffer` or `Readable` containing the resource data.
+
+  For **pushed 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<Buffer>` that resolves to the complete data once the stream ends.
 
   Internally, on the MQTT broker, the topics by
-  `topicMake(resource, "resource-transfer-request")` (default: `${resource}/resource-transfer-request/any` and
-  `${resource}/resource-transfer-request/${peerId}`) are subscribed. Returns a
-  `Provisioning` object with an `unprovision()` method.
+  `topicMake(resource, "resource-transfer-request")` and `topicMake(resource, "resource-transfer-response")`
+  (default: `${resource}/resource-transfer-request/any`, `${resource}/resource-transfer-request/${peerId}`,
+  `${resource}/resource-transfer-response/any`, and `${resource}/resource-transfer-response/${peerId}`)
+  are subscribed. Returns a `Provisioning` object with an `unprovision()` method.
 
 - **Event Emission**:<br/>
 
@@ -303,33 +289,6 @@ The **MQTT+** API provides the following methods:
   Internally, publishes to the MQTT topic by `topicMake(event, "event-emission", peerId)`
   (default: `${event}/event-emission/any` or `${event}/event-emission/${peerId}`).
 
-- **Stream Transfer**:<br/>
-
-      /*  (simplified TypeScript API method signature)  */
-      transfer(
-          stream:    string,
-          readable:  stream.Readable,
-          receiver?: Receiver,
-          options?:  MQTT::IClientPublishOptions,
-          ...params: any[]
-      ): Promise<void>
-
-  Transfer a stream to all attachers or a specific attacher.
-  The `readable` is a Node.js `Readable` stream providing the data to transfer.
-  The optional `receiver` directs the transfer to a specific attacher only.
-  The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
-
-  The data is read from `readable` in chunks (default: 16KB,
-  configurable via `chunkSize` option) and sent over MQTT until the
-  stream is closed. The returned `Promise` resolves when the entire
-  stream has been transferred.
-
-  The remote `attach()` `callback` is called with `params` and an `info` object
-  containing a `stream.Readable` for consuming the transferred data.
-
-  Internally, publishes to the MQTT topic by `topicMake(stream, "stream-transfer", peerId)`
-  (default: `${stream}/stream-transfer/any` or `${stream}/stream-transfer/${peerId}`).
-
 - **Service Call**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
@@ -352,36 +311,67 @@ The **MQTT+** API provides the following methods:
   (default: `${service}/service-call-response/${peerId}`) is temporarily subscribed
   for receiving the response.
 
-- **Resource Transfer**:<br/>
+- **Resource Fetch**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
       fetch(
-          blob:      string,
+          resource:  string,
           receiver?: Receiver,
           options?:  MQTT::IClientSubscribeOptions,
           ...params: any[]
-      ): Promise<Buffer>
+      ): Promise<{ stream: Readable, buffer: Promise<Buffer> }>
 
   Fetches a resource from any resource provisioner or from a specific provisioner.
   The optional `receiver` directs the call to a specific provisioner only.
   The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
 
-  The remote `provision()` `callback` is called with `params` and its
-  return value resolves the returned `Promise`. If the remote `callback`
-  throws an exception, this rejects the returned `Promise`.
+  Returns an object with a `stream` (`Readable`) for consuming the transferred data
+  and a lazy `buffer` (`Promise<Buffer>`) that resolves to the complete data once the stream ends.
+
+  The remote `provision()` `callback` is called with `params` and
+  should set `info.resource` to a `Buffer` or `Readable` containing the resource data.
+  If the remote `callback` throws an exception, this destroys the stream with the error.
 
   Internally, on the MQTT broker, the topic by
   `topicMake(resource, "resource-transfer-response", peerId)` (default:
   `${resource}/resource-transfer-response/${peerId}`) is temporarily subscribed
   for receiving the response.
 
+- **Resource Push**:<br/>
+
+      /*  (simplified TypeScript API method signature)  */
+      push(
+          resource:       string,
+          streamOrBuffer: Readable | Buffer,
+          receiver?:      Receiver,
+          options?:       MQTT::IClientPublishOptions,
+          ...params:      any[]
+      ): Promise<void>
+
+  Pushes a resource to all provisioners or a specific provisioner.
+  The `streamOrBuffer` is either a Node.js `Readable` stream or a `Buffer` providing the data to push.
+  The optional `receiver` directs the push to a specific provisioner only.
+  The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
+
+  The data is read from `streamOrBuffer` in chunks (default: 16KB,
+  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.
+
+  The remote `provision()` `callback` is called with `params` and an `info` object
+  containing `stream` (`Readable`) for consuming the pushed data and
+  `buffer` (lazy `Promise<Buffer>`) that resolves to the complete data once the stream ends.
+
+  Internally, publishes to the MQTT topic by `topicMake(resource, "resource-transfer-response", peerId)`
+  (default: `${resource}/resource-transfer-response/any` or `${resource}/resource-transfer-response/${peerId}`).
+
 - **Receiver Wrapping**:<br/>
 
       receiver(
           id: string
       ): Receiver
 
-  Wrap a receiver ID string for use with `emit()` or `call()` to direct the
+  Wrap a receiver ID string for use with `emit()`, `call()`, `fetch()` or `push()` to direct the
   message to a specific receiver. Returns a `Receiver` object.
 
 Internals
@@ -583,7 +573,7 @@ Notice
 > or CBOR (default), uses an own packet format (allowing sender and
 > receiver information), uses shorter NanoIDs instead of longer UUIDs
 > for identification of sender, receiver and requests, and additionally
-> provides stream transfer and resource transfer support.
+> provides resource transfer support (with fetch and push capabilities).
 
 License
 -------

package/doc/mqtt-plus-3-resource-transfer.d2

@@ -0,0 +1,32 @@
+
+shape: sequence_diagram
+
+client: "Client"
+broker: "Broker"
+server: "Server"
+
+broker.class: brown
+
+provision("foo/bar") {
+    server -> broker: "op: subscribe\ntopic: foo/bar/resource-transfer-request/any"
+    server -> broker: "op: subscribe\ntopic: foo/bar/resource-transfer-response/any"
+}
+
+push("foo/bar") {
+    client -> broker: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response #1"
+    broker -> server: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response #1"
+    client -> broker: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response #N"
+    broker -> server: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response #N"
+    client -> broker: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response EoS"
+    broker -> server: "op: publish\ntopic: foo/bar/resource-transfer-response/any\ndata: Resource-Transfer-Response EoS"
+}
+
+fetch("foo/bar") {
+    client -> broker: "op: subscribe\ntopic: foo/bar/resource-transfer-response/XXX"
+    client -> broker: "op: publish\ntopic: foo/bar/resource-transfer-request/any\ndata: Resource-Transfer-Request"
+    broker -> server: "op: publish\ntopic: foo/bar/resource-transfer-request/any\ndata: Resource-Transfer-Request"
+    broker <- server: "op: publish\ntopic: foo/bar/resource-transfer-response/XXX\ndata: Resource-Transfer-Response #1"
+    client <- broker: "op: publish\ntopic: foo/bar/resource-transfer-response/XXX\ndata: Resource-Transfer-Response #1"
+    broker <- server: "op: publish\ntopic: foo/bar/resource-transfer-response/XXX\ndata: Resource-Transfer-Response #N"
+    client <- broker: "op: publish\ntopic: foo/bar/resource-transfer-response/XXX\ndata: Resource-Transfer-Response #N"
+}

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

@@ -1,22 +1,17 @@
 type Brand<T> = T & {
     readonly __brand: unique symbol;
 };
-export type APIEndpoint = APIEndpointEvent | APIEndpointStream | APIEndpointService | APIEndpointResource;
+export type APIEndpoint = APIEndpointEvent | APIEndpointService | APIEndpointResource;
 export type APIEndpointEvent = (...args: any[]) => void;
-export type APIEndpointStream = (...args: any[]) => void;
 export type APIEndpointService = (...args: any[]) => any;
 export type APIEndpointResource = (...args: any[]) => void;
 export type Event<T extends APIEndpointEvent> = Brand<T>;
-export type Stream<T extends APIEndpointStream> = Brand<T>;
 export type Service<T extends APIEndpointService> = Brand<T>;
 export type Resource<T extends APIEndpointResource> = Brand<T>;
 export type APISchema = Record<string, APIEndpoint>;
 export type EventKeys<T> = string extends keyof T ? string : {
     [K in keyof T]: T[K] extends Event<infer _F> ? K : never;
 }[keyof T];
-export type StreamKeys<T> = string extends keyof T ? string : {
-    [K in keyof T]: T[K] extends Stream<infer _F> ? K : never;
-}[keyof T];
 export type ServiceKeys<T> = string extends keyof T ? string : {
     [K in keyof T]: T[K] extends Service<infer _F> ? K : never;
 }[keyof T];

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

@@ -109,6 +109,6 @@ export class BaseTrait extends ReceiverTrait {
         this._dispatchMessage(topic, parsed);
     }
     /*  dispatch parsed message to appropriate handler
-        (base implementation, to be overridden in super-traits)  */
+        (base implementation, to be overridden in sub-traits)  */
     _dispatchMessage(_topic, _parsed) { }
 }

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

@@ -1,16 +1,15 @@
-import stream from "stream";
+import { Readable } from "stream";
 export interface InfoBase {
     sender: string;
     receiver?: string;
 }
 export interface InfoEvent extends InfoBase {
 }
-export interface InfoStream extends InfoBase {
-    stream: stream.Readable;
-}
 export interface InfoService extends InfoBase {
 }
 export interface InfoResource extends InfoBase {
-    resource: Buffer | null;
+    resource: Buffer | Readable | null;
+    stream?: Readable;
+    buffer?: Promise<Buffer>;
 }
 export type WithInfo<F, I extends InfoBase> = F extends (...args: infer P) => infer R ? (...args: [...P, info: I]) => R : never;

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

@@ -12,12 +12,6 @@ export declare class EventEmission extends Base {
     params?: any[] | undefined;
     constructor(id: string, event: string, params?: any[] | undefined, sender?: string, receiver?: string);
 }
-export declare class StreamTransfer extends Base {
-    stream: string;
-    chunk: Buffer | null;
-    params?: any[] | undefined;
-    constructor(id: string, stream: string, chunk: Buffer | null, params?: any[] | undefined, sender?: string, receiver?: string);
-}
 export declare class ServiceCallRequest extends Base {
     service: string;
     params?: any[] | undefined;
@@ -34,19 +28,20 @@ export declare class ResourceTransferRequest extends Base {
     constructor(id: string, resource: string, params?: any[] | undefined, sender?: string, receiver?: string);
 }
 export declare class ResourceTransferResponse extends Base {
-    chunk: Buffer | undefined;
-    error: string | undefined;
-    final: boolean | undefined;
-    constructor(id: string, chunk: Buffer | undefined, error: string | undefined, final: boolean | undefined, sender?: string, receiver?: string);
+    resource?: string | undefined;
+    params?: any[] | undefined;
+    chunk?: Buffer | undefined;
+    error?: string | undefined;
+    final?: boolean | undefined;
+    constructor(id: string, resource?: string | undefined, params?: any[] | undefined, chunk?: Buffer | undefined, error?: string | undefined, final?: boolean | undefined, sender?: string, receiver?: string);
 }
 export default class Msg {
     makeEventEmission(id: string, event: string, params?: any[], sender?: string, receiver?: string): EventEmission;
-    makeStreamTransfer(id: string, stream: string, chunk: Buffer | null, params?: any[], sender?: string, receiver?: string): StreamTransfer;
     makeServiceCallRequest(id: string, service: string, params?: any[], sender?: string, receiver?: string): ServiceCallRequest;
     makeServiceCallResponse(id: string, result?: any, error?: string, sender?: string, receiver?: string): ServiceCallResponse;
     makeResourceTransferRequest(id: string, resource: string, params?: any[], sender?: string, receiver?: string): ResourceTransferRequest;
-    makeResourceTransferResponse(id: string, chunk?: Buffer, error?: string, final?: boolean, sender?: string, receiver?: string): ResourceTransferResponse;
-    parse(obj: any): EventEmission | StreamTransfer | ServiceCallRequest | ServiceCallResponse | ResourceTransferRequest | ResourceTransferResponse;
+    makeResourceTransferResponse(id: string, resource?: string, params?: any[], chunk?: Buffer, error?: string, final?: boolean, sender?: string, receiver?: string): ResourceTransferResponse;
+    parse(obj: any): EventEmission | ServiceCallRequest | ServiceCallResponse | ResourceTransferRequest | ResourceTransferResponse;
 }
 export declare class MsgTrait<T extends APISchema = APISchema> extends CodecTrait<T> {
     protected msg: Msg;

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

@@ -39,15 +39,6 @@ export class EventEmission extends Base {
         this.params = params;
     }
 }
-/*  stream chunk  */
-export class StreamTransfer extends Base {
-    constructor(id, stream, chunk, params, sender, receiver) {
-        super("stream-transfer", id, sender, receiver);
-        this.stream = stream;
-        this.chunk = chunk;
-        this.params = params;
-    }
-}
 /*  service request  */
 export class ServiceCallRequest extends Base {
     constructor(id, service, params, sender, receiver) {
@@ -74,8 +65,10 @@ export class ResourceTransferRequest extends Base {
 }
 /*  resource response  */
 export class ResourceTransferResponse extends Base {
-    constructor(id, chunk, error, final, sender, receiver) {
+    constructor(id, resource, params, chunk, error, final, sender, receiver) {
         super("resource-transfer-response", id, sender, receiver);
+        this.resource = resource;
+        this.params = params;
         this.chunk = chunk;
         this.error = error;
         this.final = final;
@@ -87,10 +80,6 @@ export default class Msg {
     makeEventEmission(id, event, params, sender, receiver) {
         return new EventEmission(id, event, params, sender, receiver);
     }
-    /*  factory for stream chunk  */
-    makeStreamTransfer(id, stream, chunk, params, sender, receiver) {
-        return new StreamTransfer(id, stream, chunk, params, sender, receiver);
-    }
     /*  factory for service request  */
     makeServiceCallRequest(id, service, params, sender, receiver) {
         return new ServiceCallRequest(id, service, params, sender, receiver);
@@ -104,8 +93,8 @@ export default class Msg {
         return new ResourceTransferRequest(id, resource, params, sender, receiver);
     }
     /*  factory for resource response  */
-    makeResourceTransferResponse(id, chunk, error, final, sender, receiver) {
-        return new ResourceTransferResponse(id, chunk, error, final, sender, receiver);
+    makeResourceTransferResponse(id, resource, params, chunk, error, final, sender, receiver) {
+        return new ResourceTransferResponse(id, resource, params, chunk, error, final, sender, receiver);
     }
     /*  parse any object into typed object  */
     parse(obj) {
@@ -133,18 +122,6 @@ export default class Msg {
                 throw new Error("invalid EventEmission object: \"params\" field must be an array");
             return this.makeEventEmission(obj.id, obj.event, obj.params, obj.sender, obj.receiver);
         }
-        else if (obj.type === "stream-transfer") {
-            /*  detect and parse stream chunk  */
-            if (typeof obj.stream !== "string")
-                throw new Error("invalid StreamTransfer object: \"stream\" field must be a string");
-            if (anyFieldsExcept(obj, ["type", "id", "stream", "chunk", "params", "sender", "receiver"]))
-                throw new Error("invalid StreamTransfer object: contains unknown fields");
-            if (obj.chunk !== undefined && typeof obj.chunk !== "object")
-                throw new Error("invalid StreamTransfer object: \"chunk\" field must be an object or null");
-            if (!validParams(obj))
-                throw new Error("invalid StreamTransfer object: \"params\" field must be an array");
-            return this.makeStreamTransfer(obj.id, obj.stream, obj.chunk, obj.params, obj.sender, obj.receiver);
-        }
         else if (obj.type === "service-call-request") {
             /*  detect and parse service request  */
             if (typeof obj.service !== "string")
@@ -172,15 +149,19 @@ export default class Msg {
             return this.makeResourceTransferRequest(obj.id, obj.resource, obj.params, obj.sender, obj.receiver);
         }
         else if (obj.type === "resource-transfer-response") {
+            if (obj.resource !== undefined && typeof obj.resource !== "string")
+                throw new Error("invalid ResourceTransferResponse object: \"resource\" field must be a string");
             if (obj.chunk !== undefined && typeof obj.chunk !== "object")
                 throw new Error("invalid ResourceTransferResponse object: \"chunk\" field must be an object");
             if (obj.error !== undefined && typeof obj.error !== "string")
                 throw new Error("invalid ResourceTransferResponse object: \"error\" field must be a string");
             if (obj.final !== undefined && typeof obj.final !== "boolean")
                 throw new Error("invalid ResourceTransferResponse object: \"final\" field must be a boolean");
-            if (anyFieldsExcept(obj, ["type", "id", "chunk", "error", "final", "sender", "receiver"]))
+            if (!validParams(obj))
+                throw new Error("invalid ResourceTransferResponse object: \"params\" field must be an array");
+            if (anyFieldsExcept(obj, ["type", "id", "resource", "params", "chunk", "error", "final", "sender", "receiver"]))
                 throw new Error("invalid ResourceTransferResponse object: contains unknown fields");
-            return this.makeResourceTransferResponse(obj.id, obj.chunk, obj.error, obj.final, obj.sender, obj.receiver);
+            return this.makeResourceTransferResponse(obj.id, obj.resource, obj.params, obj.chunk, obj.error, obj.final, obj.sender, obj.receiver);
         }
         else
             throw new Error("invalid object: not of any known type");

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

@@ -1,3 +1,4 @@
+import { Readable } from "stream";
 import { IClientPublishOptions, IClientSubscribeOptions } from "mqtt";
 import { APISchema, ResourceKeys } from "./mqtt-plus-api";
 import type { WithInfo, InfoResource } from "./mqtt-plus-info";
@@ -8,12 +9,35 @@ export interface Provisioning {
 }
 export declare class ResourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T> {
     private provisionings;
-    private fetchCallback;
+    private callbacks;
+    private pushStreams;
     provision<K extends ResourceKeys<T> & string>(resource: K, callback: WithInfo<T[K], InfoResource>): Promise<Provisioning>;
     provision<K extends ResourceKeys<T> & string>(resource: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K], InfoResource>): Promise<Provisioning>;
-    fetch<K extends ResourceKeys<T> & string>(resource: K, ...params: Parameters<T[K]>): Promise<Buffer>;
-    fetch<K extends ResourceKeys<T> & string>(resource: K, receiver: Receiver, ...params: Parameters<T[K]>): Promise<Buffer>;
-    fetch<K extends ResourceKeys<T> & string>(resource: K, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<Buffer>;
-    fetch<K extends ResourceKeys<T> & string>(resource: K, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<Buffer>;
+    private _collectStreamToBuffer;
+    private _chunkToBuffer;
+    push<K extends ResourceKeys<T> & string>(resource: K, stream: Readable, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, stream: Readable, receiver: Receiver, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, stream: Readable, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, stream: Readable, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, buffer: Buffer, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, buffer: Buffer, receiver: Receiver, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, buffer: Buffer, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
+    push<K extends ResourceKeys<T> & string>(resource: K, buffer: Buffer, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
+    fetch<K extends ResourceKeys<T> & string>(resource: K, ...params: Parameters<T[K]>): Promise<{
+        stream: Readable;
+        buffer: Promise<Buffer>;
+    }>;
+    fetch<K extends ResourceKeys<T> & string>(resource: K, receiver: Receiver, ...params: Parameters<T[K]>): Promise<{
+        stream: Readable;
+        buffer: Promise<Buffer>;
+    }>;
+    fetch<K extends ResourceKeys<T> & string>(resource: K, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<{
+        stream: Readable;
+        buffer: Promise<Buffer>;
+    }>;
+    fetch<K extends ResourceKeys<T> & string>(resource: K, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<{
+        stream: Readable;
+        buffer: Promise<Buffer>;
+    }>;
     protected _dispatchMessage(topic: string, parsed: any): void;
 }