@source-repo/rpc 3.0.0

package/dist/RpcServer.d.ts

@@ -0,0 +1,191 @@
+import { GenericModule, PeerRegistry, Transport } from './RPC/Core.js';
+import { RpcAuthenticator, RpcAuthorizer, type TrustedCertificateAuthority } from './RPC/Auth.js';
+import { RpcSchema } from './RPC/Schema.js';
+import { ExposeOptions, RpcServerHandler } from './RPC/RpcServerHandler.js';
+import type { RpcIdempotencyStore } from './RPC/Idempotency.js';
+import { RpcClientHandler } from './RPC/RpcClientHandler.js';
+import { RpcProxy } from './RpcClient.js';
+import { RelayRule } from './Transports/Presence.js';
+import { Switch } from './Utilities/Switch.js';
+import { IManageRpc } from './RPC/Rpc.js';
+export interface ServerOptions {
+    description?: string;
+}
+/**
+ * Serve over a connection this server opens, rather than one it accepts. A browser page cannot
+ * listen, so this is the only way it can host an RpcServer: it dials a hub, announces its name, and
+ * the hub relays calls to it.
+ */
+export interface ConnectServerOptions extends ServerOptions {
+    connect: string;
+    path?: string;
+    /** Presented to a hub that authenticates. */
+    credentials?: unknown;
+    /**
+     * Dial an `https://` or `wss://` hub without checking its certificate. Deliberately unsafe:
+     * anything able to answer on that address can then read and rewrite this link. For a
+     * development hub with a self-signed certificate.
+     */
+    allowInsecureTls?: boolean;
+    /**
+     * A certificate authority to trust when dialling the hub, on top of the system ones. What a
+     * plant issuing its own certificates wants, and what to reach for before `allowInsecureTls`:
+     * verification stays on, so anything this does not vouch for is still refused.
+     */
+    ca?: TrustedCertificateAuthority;
+}
+export interface RpcServerOptions {
+    name: string;
+    /**
+     * What this server serves over. Only the two a browser can use are here; NodeRpcServer widens
+     * it with a socket.io listener, an existing http.Server and a broker connection, which is what
+     * makes `{ port: 8080 }` in browser code a compile error rather than a surprise at runtime.
+     */
+    transports: (ConnectServerOptions | Transport)[];
+    useMsgPack: boolean;
+    /**
+     * Verify credentials when a peer connects. Applied to socket.io transports this server builds.
+     * MQTT has no server-side handshake, so MQTT peers are authenticated by the broker instead.
+     */
+    authenticate?: RpcAuthenticator;
+    /** Called for every call and every event subscription. Return false to reject it. */
+    authorize?: RpcAuthorizer;
+    /**
+     * Reject calls from peers no transport can vouch for. Defaults to true when `authenticate` is
+     * set. Note that MQTT peers can never be vouched for at this layer, so a server that mixes an
+     * authenticating socket.io transport with MQTT will reject its MQTT peers unless this is
+     * explicitly false.
+     */
+    requireAuthenticatedPeers?: boolean;
+    /**
+     * Forward frames addressed to another peer connected to this server's socket.io transports,
+     * instead of running them here. On by default, because a peer that can only dial out has no
+     * other way to be reached. A predicate decides per connection; `false` forwards nothing.
+     */
+    relay?: RelayRule;
+    /**
+     * Publish manageRpc.createRpcInstance so peers can instantiate exposed classes remotely.
+     * Off by default: it is remote object construction, and it is rarely needed.
+     */
+    exposeManagement?: boolean;
+    /** How long ready() waits for every transport to connect before throwing. 0 waits forever. */
+    readyTimeout: number;
+    /** How long this server's own outgoing calls wait. See proxy(). */
+    callTimeout?: number;
+    /** Describes what exposed methods accept, so arguments off the wire can be checked. */
+    schema?: RpcSchema;
+    /**
+     * 'described' (the default when a schema is given) checks the namespaces the schema covers.
+     * 'required' refuses anything undescribed. 'off' disables checking without removing the schema.
+     */
+    validation?: 'off' | 'described' | 'required';
+    /** Check what handlers return against the schema too. Off by default: it is a self-check. */
+    validateResults?: boolean;
+    /** Refuse to expose a class that marks no @rpc methods, rather than publishing all of them. */
+    requireExplicitExposure?: boolean;
+    /** Refuse a caller declaring a contract version the schema has no history for. Default 'allow'. */
+    unknownVersion?: 'allow' | 'reject';
+    /**
+     * Where to record what a non-repeatable command did, so a request redelivered after this
+     * process died is answered from the record instead of run a second time.
+     *
+     * Without one, delivery and execution are at least once - which is the honest description of
+     * every RPC system that has no such store. See RPC/Idempotency.ts for what exactly it closes.
+     */
+    idempotency?: RpcIdempotencyStore;
+    /**
+     * Publish msgrpc.describe(), which reports the exposed namespaces, their methods and events,
+     * and which instances are live. Off by default: listing all of that is reconnaissance, and it
+     * is subject to authorize() like any other call.
+     */
+    exposeIntrospection?: boolean;
+}
+/**
+ * Everything that works anywhere: a peer serves over connections it opens, or over transports it
+ * was handed. Listening for connections and speaking MQTT need Node, and live in NodeRpcServer,
+ * which is what `RpcServer` means when imported outside a browser.
+ */
+export declare class RpcServerBase implements IManageRpc {
+    rpc: RpcServerHandler;
+    /**
+     * This server as a caller. A server on a bus is rarely only a server: it answers its peers and
+     * calls them back. Sharing the transports means it does so under its own name, over the
+     * connection it already has, rather than needing a second RpcClient with a second name - which
+     * over MQTT means a second broker session, and over socket.io a second announced peer.
+     */
+    caller: RpcClientHandler;
+    readyFlag: boolean;
+    switch?: Switch;
+    transports: Transport[];
+    /** Peer name -> transport, shared by this server's modules and nothing outside them. */
+    readonly peers: PeerRegistry;
+    options: RpcServerOptions;
+    constructor(options?: Partial<RpcServerOptions>);
+    /** Why init() failed, rethrown by ready() so the caller sees the cause and not a timeout. */
+    private initError?;
+    /** Resolves when every transport has been built and wired. ready() waits on it. */
+    private starting;
+    /**
+     * Build each configured transport and wire it in. The socket.io listener and the MQTT client
+     * are imported here rather than at the top of the file: a page hosting an RpcServer over a
+     * connection it dials has no use for either, and a static import would put both in its bundle.
+     */
+    /** What to build when nothing was configured. A peer that cannot listen has no useful default. */
+    protected configuredTransports(): unknown[];
+    /**
+     * Turn one configuration entry into a transport, or undefined if this class does not know that
+     * shape. NodeRpcServer overrides it for the shapes that need Node and defers here for the rest.
+     */
+    protected buildTransport(serveroption: unknown): Promise<Transport | undefined>;
+    private buildTransports;
+    /** Put one transport into the graph: piped into both handlers, routable from the switch. */
+    private attach;
+    /**
+     * Pass a presence change from the transport that saw it to the other links: told directly to
+     * the peers connected here, and advertised to the hubs this server has dialled into. The
+     * advertisement is what makes a network deeper than a star work - and it never includes a peer
+     * back on the link it was learned from, or two hubs each end up believing the other is the way
+     * to it.
+     */
+    private relayPresence;
+    private advertiseReachability;
+    /** Not 'error': an EventEmitter throws on an unhandled 'error' event. */
+    private emitSafely;
+    /**
+     * Run a presence reaction without letting it escape into the transport that emitted the event.
+     * Bookkeeping here failing is worth reporting; it is not worth ending the process over.
+     */
+    private safely;
+    /**
+     * A typed proxy for calling another peer, over this server's own transports and under its own
+     * name. The mirror of RpcClient.proxy, so a peer that both serves and calls needs one object.
+     */
+    proxy<T>(name: string, target?: string): Promise<RpcProxy<T>>;
+    close(): Promise<void>;
+    exposeClassInstance(instance: object, name?: string, options?: number | ExposeOptions): void;
+    exposeClass<T>(constructor: new (...args: unknown[]) => T, aliasName?: string): void;
+    exposeObject(obj: object, name: string): void;
+    expose(methodName: string, method: () => void): void;
+    createRpcInstance(className: string, instanceName?: string, ...args: unknown[]): Promise<string | undefined>;
+    addTarget(target: string, transport: GenericModule): void;
+    init(): Promise<void>;
+    ready(): Promise<void>;
+    /**
+     * Wait until a peer is addressable from here, rather than calling it and hoping.
+     *
+     * `ready()` says this peer's own links are up. It says nothing about anyone else, and it cannot:
+     * presence arrives over those links a moment after they open, and over MQTT a retained
+     * announcement lands a moment after the subscription does. Calling in that moment reaches a
+     * switch with no route and fails.
+     *
+     * This is the wait that closes it, and the reason it is here rather than in each application is
+     * that everything built on this library has needed it - the CLI's verbs, its recorder, its
+     * replayer and its console each grew their own copy before this existed.
+     *
+     * Returns true when the peer is addressable, false if it never appeared. A `false` is worth
+     * reporting as "nobody is answering to that name" rather than retrying: the usual cause is a
+     * peer that is not running or is running under a different name.
+     */
+    awaitPeer(peer: string, timeout?: number): Promise<boolean>;
+}
+//# sourceMappingURL=RpcServer.d.ts.map

package/dist/RpcServer.d.ts.map

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

package/dist/RpcServer.js

@@ -0,0 +1,293 @@
+import { GenericModule, PeerRegistry, TransportEvent } from './RPC/Core.js';
+import { Introspection, withIntrospection } from './RPC/Introspection.js';
+import { RpcServerHandler } from './RPC/RpcServerHandler.js';
+import { defaultCallTimeout, RpcClientHandler } from './RPC/RpcClientHandler.js';
+import { SocketIoClientTransport } from './Transports/SocketIoClientTransport.js';
+import { codecFor } from './RPC/Codec.js';
+import { Switch } from './Utilities/Switch.js';
+/**
+ * Everything that works anywhere: a peer serves over connections it opens, or over transports it
+ * was handed. Listening for connections and speaking MQTT need Node, and live in NodeRpcServer,
+ * which is what `RpcServer` means when imported outside a browser.
+ */
+export class RpcServerBase {
+    rpc;
+    /**
+     * This server as a caller. A server on a bus is rarely only a server: it answers its peers and
+     * calls them back. Sharing the transports means it does so under its own name, over the
+     * connection it already has, rather than needing a second RpcClient with a second name - which
+     * over MQTT means a second broker session, and over socket.io a second announced peer.
+     */
+    caller;
+    readyFlag = false;
+    switch;
+    transports = [];
+    /** Peer name -> transport, shared by this server's modules and nothing outside them. */
+    peers = new PeerRegistry();
+    options = { name: '*', transports: [], useMsgPack: true, readyTimeout: 30000 };
+    constructor(options = {}) {
+        this.options = { ...this.options, ...options };
+        // Handlers first, with no sources. Transports attach to them as they are built, which is
+        // what lets exposeClassInstance() run before any link exists - and lets the two node-only
+        // transports be imported on demand, so a browser bundle carrying RpcServer does not carry
+        // socket.io's server and the MQTT client to reach a hub it dials.
+        this.rpc = new RpcServerHandler(this.options.name);
+        this.caller = new RpcClientHandler(this.options.name, [], this.options.callTimeout ?? defaultCallTimeout);
+        this.switch = new Switch([this.rpc, this.caller]);
+        // One registry for this server's modules only. The transports record which peer they saw a
+        // message from; the switch reads it back to route the reply out of the same transport.
+        for (const module of [this.rpc, this.caller, this.switch])
+            module.usePeerRegistry(this.peers);
+        this.rpc.authorize = this.options.authorize;
+        this.rpc.requireIdentity = this.options.requireAuthenticatedPeers ?? !!this.options.authenticate;
+        // Identity comes from whichever transport the peer is connected to, never from the message
+        // itself. Authenticating transports pin a peer name to one connection, so this lookup
+        // cannot be spoofed by claiming someone else's source.
+        this.rpc.resolveIdentity = (source) => {
+            for (const transport of this.transports) {
+                const identity = transport.getIdentity(source);
+                if (identity)
+                    return identity;
+            }
+            return undefined;
+        };
+        this.rpc.schema = this.options.schema;
+        this.rpc.validation = this.options.validation ?? (this.options.schema ? 'described' : 'off');
+        this.rpc.validateResults = this.options.validateResults ?? false;
+        this.rpc.unknownVersion = this.options.unknownVersion ?? 'allow';
+        this.rpc.idempotency = this.options.idempotency;
+        this.rpc.manageRpc.requireExplicitExposure = this.options.requireExplicitExposure ?? false;
+        if (this.options.exposeManagement)
+            this.rpc.manageRpc.exposeManagement();
+        if (this.options.exposeIntrospection) {
+            this.rpc.manageRpc.exposeClassInstance(new Introspection(this.rpc));
+            // Describing the describer. Without this the one call a peer makes to find out what is
+            // here is the only undescribed thing on the server, and 'required' refuses it outright.
+            this.rpc.schema = withIntrospection(this.rpc.schema);
+        }
+        // Building a listener or a broker connection means loading a module, so this is where the
+        // constructor stops being synchronous. ready() awaits it and reports what went wrong.
+        this.starting = this.buildTransports().then(() => {
+            this.readyFlag = true;
+        }, (e) => {
+            this.initError = e;
+        });
+        // init() is a no-op here but is meant to be overridden, and the constructor cannot await
+        // it. Left unguarded, a subclass whose init() rejected took the process down from a
+        // constructor; kept instead, so ready() can name the cause.
+        void this.init().catch((e) => {
+            this.initError = e;
+            this.emitSafely('initError', e);
+        });
+    }
+    /** Why init() failed, rethrown by ready() so the caller sees the cause and not a timeout. */
+    initError;
+    /** Resolves when every transport has been built and wired. ready() waits on it. */
+    starting = Promise.resolve();
+    /**
+     * Build each configured transport and wire it in. The socket.io listener and the MQTT client
+     * are imported here rather than at the top of the file: a page hosting an RpcServer over a
+     * connection it dials has no use for either, and a static import would put both in its bundle.
+     */
+    /** What to build when nothing was configured. A peer that cannot listen has no useful default. */
+    configuredTransports() {
+        return this.options.transports;
+    }
+    /**
+     * Turn one configuration entry into a transport, or undefined if this class does not know that
+     * shape. NodeRpcServer overrides it for the shapes that need Node and defers here for the rest.
+     */
+    async buildTransport(serveroption) {
+        if (serveroption instanceof GenericModule)
+            return serveroption;
+        if (serveroption.connect) {
+            const connectOptions = serveroption;
+            return new SocketIoClientTransport(this.options.name, connectOptions.connect, [], {
+                ...(connectOptions.path ? { path: connectOptions.path } : {}),
+                ...(connectOptions.credentials ? { auth: connectOptions.credentials } : {}),
+                // The typings narrow `ca` to a string; the runtime takes what Node's tls does.
+                ...(connectOptions.ca ? { ca: connectOptions.ca } : {})
+            }, true, connectOptions.allowInsecureTls);
+        }
+        return undefined;
+    }
+    async buildTransports() {
+        const codec = codecFor(this.options.useMsgPack);
+        for (const serveroption of this.configuredTransports()) {
+            const transport = await this.buildTransport(serveroption);
+            if (!transport)
+                throw new Error(`RpcServer '${this.options.name}': no transport can be built from ${JSON.stringify(serveroption)}`);
+            // The transports encode, so there is no converter between them and the handler. A
+            // structured wire format such as MQTT 5 needs to see the message rather than bytes a
+            // converter already flattened.
+            transport.codec = codec;
+            if (this.options.relay !== undefined && 'relay' in transport)
+                transport.relay = this.options.relay;
+            this.attach(transport);
+        }
+    }
+    /** Put one transport into the graph: piped into both handlers, routable from the switch. */
+    attach(transport) {
+        this.transports.push(transport);
+        transport.usePeerRegistry(this.peers);
+        transport.pipe(this.rpc);
+        transport.pipe(this.caller);
+        this.switch?.setTarget(transport);
+        // Both listeners are guarded: a transport emits these synchronously from its own inbound
+        // path, so anything thrown here unwinds into the transport rather than into something able
+        // to report it.
+        transport.on(TransportEvent.peerGone, (peer) => this.safely('peerGone', peer, () => {
+            // Drop the peer's event subscriptions and forget its route as soon as it goes.
+            this.rpc.removePeer(peer);
+            this.peers.delete(peer);
+            this.relayPresence(transport, peer, 'offline');
+            // A gateway subscription taken out for this peer has nothing left to collect.
+            for (const other of this.transports) {
+                const gateway = other;
+                if (gateway.stopWatchingFor)
+                    void gateway.stopWatchingFor(peer).catch((e) => this.emitSafely('presenceError', { peer, error: e }));
+            }
+        }));
+        // A peer that arrives on one transport is announced on the others, so a browser connected
+        // over socket.io learns about a peer that only exists on the broker.
+        transport.on(TransportEvent.peerOnline, (peer) => this.safely('peerOnline', peer, () => this.relayPresence(transport, peer, 'online')));
+        // Subscriptions this server holds on other peers are replayed when a link returns, the same
+        // way RpcClient does it - otherwise a server that watches its peers goes deaf after a blip
+        // with nothing to say so.
+        transport.on(TransportEvent.connected, () => void this.caller.resubscribe().catch((e) => this.emitSafely('resubscribeError', e)));
+    }
+    /**
+     * Pass a presence change from the transport that saw it to the other links: told directly to
+     * the peers connected here, and advertised to the hubs this server has dialled into. The
+     * advertisement is what makes a network deeper than a star work - and it never includes a peer
+     * back on the link it was learned from, or two hubs each end up believing the other is the way
+     * to it.
+     */
+    relayPresence(from, peer, state) {
+        for (const transport of this.transports) {
+            if (transport === from)
+                continue;
+            const listener = transport;
+            if (listener.announcePeer)
+                listener.announcePeer(peer, state);
+        }
+        this.advertiseReachability();
+    }
+    advertiseReachability() {
+        for (const transport of this.transports) {
+            if (!(transport instanceof SocketIoClientTransport))
+                continue;
+            transport.advertise(this.peers.names().filter((name) => name !== this.options.name && this.peers.get(name) !== transport));
+        }
+    }
+    /** Not 'error': an EventEmitter throws on an unhandled 'error' event. */
+    emitSafely(event, payload) {
+        for (const transport of this.transports)
+            transport.emit(event, payload);
+    }
+    /**
+     * Run a presence reaction without letting it escape into the transport that emitted the event.
+     * Bookkeeping here failing is worth reporting; it is not worth ending the process over.
+     */
+    safely(what, peer, react) {
+        try {
+            react();
+        }
+        catch (e) {
+            this.emitSafely('presenceError', { what, peer, error: e });
+        }
+    }
+    /**
+     * A typed proxy for calling another peer, over this server's own transports and under its own
+     * name. The mirror of RpcClient.proxy, so a peer that both serves and calls needs one object.
+     */
+    async proxy(name, target) {
+        await this.ready();
+        const result = { name };
+        if (target)
+            result.target = target;
+        result.remote = this.caller.proxy(name, target ?? '*');
+        return result;
+    }
+    async close() {
+        this.caller.failPendingCalls('server closed');
+        this.caller.subscriptions.clear();
+        await this.caller.close();
+        // forEach with an async callback did not await anything, so close() returned while the
+        // listeners were still open.
+        await Promise.all(this.transports.map((transport) => transport.close()));
+        this.transports = [];
+        this.peers.clear();
+    }
+    exposeClassInstance(instance, name, options) {
+        this.rpc.manageRpc.exposeClassInstance(instance, name, options);
+    }
+    exposeClass(constructor, aliasName) {
+        this.rpc.manageRpc.exposeClass(constructor, aliasName);
+    }
+    exposeObject(obj, name) {
+        this.rpc.manageRpc.exposeObject(obj, name);
+    }
+    expose(methodName, method) {
+        this.rpc.manageRpc.expose(methodName, method);
+    }
+    createRpcInstance(className, instanceName, ...args) {
+        return this.rpc.manageRpc.createRpcInstance(className, instanceName, ...args);
+    }
+    addTarget(target, transport) {
+        this.switch?.setTarget(transport);
+    }
+    async init() { }
+    async ready() {
+        await this.starting;
+        const allTransportsReady = () => {
+            return this.transports.filter((trp) => !trp.readyFlag).length == 0;
+        };
+        // Previously an unbounded wait, so a server whose broker was unreachable hung at startup
+        // with no diagnostic at all.
+        const deadline = Date.now() + this.options.readyTimeout;
+        while (!allTransportsReady() || !this.readyFlag) {
+            // A transport that can never come up says so, rather than being waited out: a port
+            // already in use is not something more time fixes.
+            const failed = this.transports.find((transport) => transport.startupError !== undefined);
+            if (failed)
+                this.initError = failed.startupError;
+            if (this.initError !== undefined)
+                throw new Error(`RpcServer '${this.options.name}': could not start: ${this.initError instanceof Error ? this.initError.message : String(this.initError)}`, {
+                    cause: this.initError
+                });
+            if (this.options.readyTimeout > 0 && Date.now() > deadline) {
+                const pending = this.transports.filter((trp) => !trp.readyFlag).map((trp) => trp.getName());
+                throw new Error(`RpcServer '${this.options.name}': transports not ready within ${this.options.readyTimeout} ms: ${pending.join(', ')}`);
+            }
+            await new Promise((res) => setTimeout(res, 10));
+        }
+    }
+    /**
+     * Wait until a peer is addressable from here, rather than calling it and hoping.
+     *
+     * `ready()` says this peer's own links are up. It says nothing about anyone else, and it cannot:
+     * presence arrives over those links a moment after they open, and over MQTT a retained
+     * announcement lands a moment after the subscription does. Calling in that moment reaches a
+     * switch with no route and fails.
+     *
+     * This is the wait that closes it, and the reason it is here rather than in each application is
+     * that everything built on this library has needed it - the CLI's verbs, its recorder, its
+     * replayer and its console each grew their own copy before this existed.
+     *
+     * Returns true when the peer is addressable, false if it never appeared. A `false` is worth
+     * reporting as "nobody is answering to that name" rather than retrying: the usual cause is a
+     * peer that is not running or is running under a different name.
+     */
+    async awaitPeer(peer, timeout = 5000) {
+        const deadline = Date.now() + timeout;
+        for (;;) {
+            if (this.peers.get(peer))
+                return true;
+            if (Date.now() >= deadline)
+                return false;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+}
+//# sourceMappingURL=RpcServer.js.map

package/dist/RpcServer.js.map

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

package/dist/Transports/Mqtt5Frame.d.ts

@@ -0,0 +1,107 @@
+import { Message } from '../RPC/Core.js';
+/**
+ * Mapping between msgrpc messages and the MQTT 5 packet layout described in
+ * docs/mqtt5-frame-spec.md.
+ *
+ * The point is that a peer needs no msgrpc code to take part: where to reply and how to correlate
+ * come from the protocol's own Response Topic and Correlation Data, and everything else is a
+ * readable user property. Kept separate from the transport so the mapping can be read, and tested,
+ * without a broker.
+ */
+/** Control properties are prefixed so a broker or gateway injecting its own cannot be mistaken for one. */
+export declare const MR: {
+    readonly version: 'mr-v';
+    readonly source: 'mr-src';
+    readonly kind: 'mr-kind';
+    readonly path: 'mr-path';
+    readonly method: 'mr-method';
+    readonly event: 'mr-event';
+    readonly code: 'mr-code';
+    readonly nonce: 'mr-nonce';
+    readonly timestamp: 'mr-ts';
+    readonly signature: 'mr-sig';
+    readonly contractVersion: 'mr-ver';
+    /**
+     * Milliseconds the caller will still wait, counted from when it sent. Carried alongside MQTT's
+     * own messageExpiryInterval rather than instead of it: expiry is coarse (whole seconds), the
+     * broker decrements it, and it stops at the broker - it says nothing about how long a frame then
+     * sat in the receiving process. This is the caller's own statement, signed, and it survives
+     * relaying through a transport that does not speak MQTT at all.
+     */
+    readonly ttl: 'mr-ttl';
+    /**
+     * Names the command a request is an attempt at, when the caller distinguishes the two. Absent
+     * means the correlation data is the name, so a redelivered packet is the same command and a
+     * fresh attempt is a different one.
+     */
+    readonly idempotencyKey: 'mr-idem';
+};
+/**
+ * Version 2 covers contentType, the error code, the declared contract version, the response topic,
+ * the ttl and the idempotency key in the signature; version 1 covered none of them, and a frame
+ * signed under one cannot verify under the other. Bumped rather than negotiated: a receiver that quietly accepted either
+ * would let an attacker choose the weaker.
+ */
+export declare const FRAME_VERSION = "2";
+/** Frame versions this build will accept. A frame announcing anything else is refused, not guessed at. */
+export declare const SUPPORTED_FRAME_VERSIONS: Set<string>;
+export type FrameKind = 'call' | 'subscribe' | 'unsubscribe' | 'result' | 'error' | 'event';
+/** Which per-peer topic a frame belongs on. */
+export type Channel = 'req' | 'rsp' | 'evt';
+export interface OutboundFrame {
+    kind: FrameKind;
+    channel: Channel;
+    /** The request id, carried as MQTT correlation data. Absent on events. */
+    correlation?: string;
+    path?: string;
+    method?: string;
+    event?: string;
+    code?: string;
+    /** Contract version the caller declares, when it has one. */
+    version?: string;
+    /** Milliseconds the caller will still wait. Drives the MQTT message expiry as well. */
+    ttl?: number;
+    /** Names the command rather than this attempt at it, when the caller says so. */
+    idempotencyKey?: string;
+    /** Encoded as the packet payload: arguments for a request, the value for a result. */
+    body: unknown;
+}
+/** Kinds that expect an answer, and so are the only ones entitled to say where it should go. */
+export declare const isRequestKind: (kind: string | undefined) => kind is "call" | "subscribe" | "unsubscribe";
+/** Undefined for anything this layout has no representation for, which the transport drops. */
+export declare const toOutboundFrame: (message: Message) => OutboundFrame | undefined;
+export interface InboundFrame {
+    kind: string;
+    correlation?: string;
+    path?: string;
+    method?: string;
+    event?: string;
+    code?: string;
+    version?: string;
+    /** What the caller said it would still wait, already narrowed by anything the broker reported. */
+    ttl?: number;
+    idempotencyKey?: string;
+    body: unknown;
+}
+/** Undefined when the frame does not describe anything this RPC layer can dispatch. */
+export declare const fromInboundFrame: (frame: InboundFrame) => Message | undefined;
+export type RawUserProperties = {
+    [key: string]: string | string[];
+} | undefined;
+/**
+ * Read the control properties, refusing any that appear more than once.
+ *
+ * MQTT permits a repeated user property, and mqtt.js surfaces repeats as an array. Taking the
+ * first or the last would let a sender show one value to a check and a different one to the
+ * dispatcher, so a repeat is an ambiguity to refuse rather than resolve.
+ */
+export declare const readControlProperties: (properties: RawUserProperties) => {
+    values: {
+        [key: string]: string;
+    };
+} | {
+    duplicate: string;
+};
+export declare const correlationToString: (correlation: Uint8Array | undefined) => string | undefined;
+export declare const correlationToBytes: (correlation: string | undefined) => Uint8Array<ArrayBuffer> | undefined;
+//# sourceMappingURL=Mqtt5Frame.d.ts.map

package/dist/Transports/Mqtt5Frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mqtt5Frame.d.ts","sourceRoot":"","sources":["../../src/Transports/Mqtt5Frame.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAe,MAAM,gBAAgB,CAAA;AAYrD;;;;;;;;GAQG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,EAAE;aACX,OAAO,EAAE,MAAM;aACf,MAAM,EAAE,QAAQ;aAChB,IAAI,EAAE,SAAS;aACf,IAAI,EAAE,SAAS;aACf,MAAM,EAAE,WAAW;aACnB,KAAK,EAAE,UAAU;aACjB,IAAI,EAAE,SAAS;aACf,KAAK,EAAE,UAAU;aACjB,SAAS,EAAE,OAAO;aAClB,SAAS,EAAE,QAAQ;aACnB,eAAe,EAAE,QAAQ;IACzB;;;;;;OAMG;aACH,GAAG,EAAE,QAAQ;IACb;;;;OAIG;aACH,cAAc,EAAE,SAAS;CACnB,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC,0GAA0G;AAC1G,eAAO,MAAM,wBAAwB,aAA2B,CAAA;AAEhE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAE3F,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;AAE3C,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,IAAI,EAAE,OAAO,CAAA;CAChB;AAKD,gGAAgG;AAChG,eAAO,MAAM,aAAa,SAAU,MAAM,GAAG,SAAS,iDAAsE,CAAA;AAE5H,+FAA+F;AAC/F,eAAO,MAAM,eAAe,YAAa,OAAO,KAAG,aAAa,GAAG,SAiClE,CAAA;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,OAAO,CAAA;CAChB;AAED,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,UAAW,YAAY,KAAG,OAAO,GAAG,SA+ChE,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAAA;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,eAAgB,iBAAiB,KAAG;IAAE,MAAM,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAQhI,CAAA;AAED,eAAO,MAAM,mBAAmB,gBAAiB,UAAU,GAAG,SAAS,uBAAgE,CAAA;AACvI,eAAO,MAAM,kBAAkB,gBAAiB,MAAM,GAAG,SAAS,wCAAgE,CAAA"}