@source-repo/rpc 3.0.0

package/dist/Transports/Mqtt5Frame.js

@@ -0,0 +1,162 @@
+import { stringToUint8Array, uint8ArrayToString } from 'uint8array-extras';
+import { MessageType } from '../RPC/Core.js';
+import { RpcMessageType } from '../RPC/Messages.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 const MR = {
+    version: 'mr-v',
+    source: 'mr-src',
+    kind: 'mr-kind',
+    path: 'mr-path',
+    method: 'mr-method',
+    event: 'mr-event',
+    code: 'mr-code',
+    nonce: 'mr-nonce',
+    timestamp: 'mr-ts',
+    signature: 'mr-sig',
+    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.
+     */
+    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.
+     */
+    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 const FRAME_VERSION = '2';
+/** Frame versions this build will accept. A frame announcing anything else is refused, not guessed at. */
+export const SUPPORTED_FRAME_VERSIONS = new Set([FRAME_VERSION]);
+const requestKind = (method) => method === 'on' ? 'subscribe' : method === 'off' || method === 'removeListener' ? 'unsubscribe' : 'call';
+/** Kinds that expect an answer, and so are the only ones entitled to say where it should go. */
+export const isRequestKind = (kind) => kind === 'call' || kind === 'subscribe' || kind === 'unsubscribe';
+/** Undefined for anything this layout has no representation for, which the transport drops. */
+export const toOutboundFrame = (message) => {
+    const payload = message.payload;
+    if (!payload)
+        return undefined;
+    switch (payload.type) {
+        case RpcMessageType.CallInstanceMethod: {
+            const call = payload;
+            return {
+                kind: requestKind(call.method),
+                channel: 'req',
+                correlation: call.id,
+                path: call.path,
+                method: call.method,
+                version: call.version,
+                ttl: call.ttl,
+                idempotencyKey: call.idempotencyKey,
+                body: call.params
+            };
+        }
+        case RpcMessageType.success: {
+            const success = payload;
+            return { kind: 'result', channel: 'rsp', correlation: success.id, body: success.result };
+        }
+        case RpcMessageType.error: {
+            const error = payload;
+            return { kind: 'error', channel: 'rsp', correlation: error.id, code: error.code, body: error.error };
+        }
+        case RpcMessageType.event: {
+            const event = payload;
+            return { kind: 'event', channel: 'evt', event: event.event, path: event.path, body: event.params };
+        }
+        default:
+            return undefined;
+    }
+};
+/** Undefined when the frame does not describe anything this RPC layer can dispatch. */
+export const fromInboundFrame = (frame) => {
+    switch (frame.kind) {
+        case 'call':
+        case 'subscribe':
+        case 'unsubscribe': {
+            if (!frame.correlation || !frame.path || !frame.method)
+                return undefined;
+            const payload = {
+                type: RpcMessageType.CallInstanceMethod,
+                id: frame.correlation,
+                path: frame.path,
+                method: frame.method,
+                version: frame.version,
+                ttl: frame.ttl,
+                idempotencyKey: frame.idempotencyKey,
+                // A caller that sends no payload means no arguments.
+                params: Array.isArray(frame.body) ? frame.body : frame.body === undefined || frame.body === null ? [] : [frame.body]
+            };
+            return { type: MessageType.RequestMessage, payload };
+        }
+        case 'result': {
+            if (!frame.correlation)
+                return undefined;
+            const payload = { type: RpcMessageType.success, id: frame.correlation, result: frame.body };
+            return { type: MessageType.ResponseMessage, payload };
+        }
+        case 'error': {
+            if (!frame.correlation)
+                return undefined;
+            const payload = {
+                type: RpcMessageType.error,
+                id: frame.correlation,
+                code: (frame.code ?? 'Exception'),
+                error: frame.body
+            };
+            return { type: MessageType.ErrorMessage, payload };
+        }
+        case 'event': {
+            if (!frame.event)
+                return undefined;
+            const payload = {
+                type: RpcMessageType.event,
+                event: frame.event,
+                path: frame.path,
+                params: Array.isArray(frame.body) ? frame.body : [frame.body]
+            };
+            return { type: MessageType.EventMessage, payload };
+        }
+        default:
+            return 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 const readControlProperties = (properties) => {
+    const values = {};
+    for (const [key, value] of Object.entries(properties ?? {})) {
+        if (!key.startsWith('mr-'))
+            continue;
+        if (Array.isArray(value))
+            return { duplicate: key };
+        values[key] = value;
+    }
+    return { values };
+};
+export const correlationToString = (correlation) => (correlation ? uint8ArrayToString(correlation) : undefined);
+export const correlationToBytes = (correlation) => (correlation ? stringToUint8Array(correlation) : undefined);
+//# sourceMappingURL=Mqtt5Frame.js.map

package/dist/Transports/Mqtt5Frame.js.map

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

package/dist/Transports/MqttTransport.d.ts

@@ -0,0 +1,279 @@
+import * as mqtt from 'mqtt';
+import { GenericModule, IGenericModule, Message } from '../RPC/Core.js';
+import { FrameCodec } from '../RPC/Codec.js';
+import { MessageSigner, MessageVerifier, RpcIdentity } from '../RPC/Auth.js';
+import { ReplayGuard } from '../RPC/Signing.js';
+import { Channel } from './Mqtt5Frame.js';
+/** v1 is the $-header layout; v2 is the MQTT 5 property layout, so the two never share a topic. */
+export declare const defaultTopicPrefix: {
+    readonly 4: 'msgrpc/v1';
+    readonly 5: 'msgrpc/v2';
+};
+/**
+ * A peer name is interpolated into a topic, so it must not be able to change that topic's shape.
+ * A peer named '#' would otherwise subscribe to every other peer's traffic, and one named '+'
+ * would do the same one level down.
+ */
+export declare const isSafeTopicSegment: (value: unknown) => value is string;
+/** A prefix may span levels, so '/' is allowed inside it, but wildcards still are not. */
+export declare const isSafeTopicPrefix: (value: unknown) => value is string;
+/**
+ * A topic something may be published to. Spans levels, but wildcards are only meaningful in a
+ * subscription and `$` opens the broker's own namespace, so neither belongs in a destination that
+ * arrived from somewhere else.
+ */
+export declare const isSafeTopicName: (value: unknown) => value is string;
+export interface MqttTransportOptions {
+    /** Topic namespace. Traffic lives under <prefix>/rpc/<peer> and <prefix>/presence/<peer>. */
+    prefix?: string;
+    /** Peer name to subscribe as. Defaults to the transport's own name. */
+    topic?: string;
+    /**
+     * Watch every peer's traffic instead of this one's, and report it rather than acting on it.
+     *
+     * There is no broker of ours on an MQTT network to hook the way a socket.io one can be, so the
+     * observation happens at the subscription: `<prefix>/rpc/+` under the 3.1.1 layout, and each of
+     * `<prefix>/{req,rsp,evt}/+` under MQTT 5. Everything decoded is emitted as
+     * `TransportEvent.relayed` and nothing is delivered - a tap answers no calls and runs no
+     * methods.
+     *
+     * **Give this its own transport rather than adding it to a working one.** A peer subscribed to
+     * both its own topic and the wildcard covering it has overlapping subscriptions, and a broker
+     * is permitted to deliver a matching message once per subscription - which for a request means
+     * running the method twice. A separate instance is a separate client id and a separate session,
+     * so the two never overlap. It follows that a tap needs a name of its own, and `presence: false`
+     * unless it should appear in everyone's peer list.
+     *
+     * Frames are reported without checking signatures: a tap holds no key for a conversation it is
+     * not part of, and what is on the wire is what it exists to show.
+     */
+    tap?: boolean;
+    /**
+     * Quality of service for RPC traffic. Defaults to 1, at least once: QoS 0 drops messages
+     * silently whenever the broker or link hiccups, which for RPC shows up as a call timeout.
+     * At-least-once permits duplicate delivery, which the RPC server suppresses by request id.
+     */
+    qos?: 0 | 1 | 2;
+    /**
+     * Publish a retained last will, so peers learn when this one disappears instead of holding
+     * its event subscriptions forever. On by default.
+     */
+    presence?: boolean;
+    /**
+     * Ask the broker to keep this client's session, queueing QoS > 0 messages while it is
+     * disconnected. Worth enabling for servers, which should not lose requests across a restart.
+     * Off by default: a persistent session for a short-lived peer lingers on the broker.
+     */
+    persistentSession?: boolean;
+    /** Broker connection options: credentials, TLS client certificates, clientId, keepalive. */
+    mqtt?: mqtt.IClientOptions;
+    /**
+     * Connect to an `mqtts://` or `wss://` broker without checking its certificate. Deliberately
+     * unsafe and named so: it accepts any certificate at all, so anything able to answer on the
+     * broker's address can read and rewrite everything this peer sends. For a development broker
+     * with a self-signed certificate; a plant should carry its own CA in `mqtt.ca` instead.
+     */
+    allowInsecureTls?: boolean;
+    /** Sign every outgoing frame. See RPC/Signing.ts for ready-made HMAC and Ed25519 signers. */
+    sign?: MessageSigner;
+    /**
+     * Require and check a signature on every incoming frame. Unsigned, stale, replayed or
+     * badly-signed frames are dropped before they reach the RPC layer, and a verified peer gains
+     * a real identity that authorize() can act on.
+     */
+    verify?: MessageVerifier;
+    /** How far an incoming frame's timestamp may differ from local time. Default 60000 ms. */
+    maxClockSkew?: number;
+    /** How many recent nonces to remember for replay detection. Default 5000. */
+    maxTrackedNonces?: number;
+    /**
+     * MQTT protocol version. 5 carries the reply address, correlation and method as packet
+     * properties, so a peer with no msgrpc code can take part and standard tooling can read the
+     * traffic. 4 (MQTT 3.1.1) keeps the older $-delimited header for brokers that need it.
+     */
+    protocol?: 4 | 5;
+    /**
+     * MQTT 5 only: how long the broker holds a request that names no deadline of its own.
+     *
+     * A request from an RPC client carries the time its caller will still wait, and the expiry is
+     * taken from that instead - the two used to be independent, so a client that gave up after ten
+     * seconds could have its request delivered and executed twenty seconds later. This remains the
+     * answer for a request that says nothing, which is any third-party caller not sending `mr-ttl`.
+     */
+    requestExpirySeconds?: number;
+    /**
+     * MQTT 5 only: decide whether a request may have its reply published where it asks.
+     *
+     * A request names a Response Topic and that is where the answer goes, which means a caller
+     * chooses a topic this peer then publishes to. Unset, the rule is that the topic must sit under
+     * this transport's own prefix - the boundary broker ACLs are usually drawn on. Supply this to
+     * widen it, or to narrow it to exactly the peer's own reply topic.
+     */
+    allowResponseTopic?: (topic: string, source: string) => boolean;
+    /** MQTT 5 only: which of this peer's channels to subscribe to. Defaults to all three. */
+    channels?: Channel[];
+    /**
+     * MQTT 5 only. Join a shared subscription group so several processes can serve one peer name,
+     * with the broker distributing requests among them.
+     *
+     * Only the request channel is shared. A reply has to reach the requester waiting for it, and an
+     * event its particular subscriber, so sharing those would hand them to an arbitrary replica.
+     */
+    sharedGroup?: string;
+    /**
+     * Distinguishes this replica's broker connection from its siblings'. A broker permits one
+     * connection per client id, and replicas share a peer name, so without this they would
+     * disconnect each other in a loop. Defaults to a random suffix.
+     */
+    replicaId?: string;
+    /**
+     * MQTT 5 only: how long the broker keeps this peer's session after it disconnects. Bounds the
+     * queueing that makes a restart lossless, without leaving session state behind forever.
+     * Defaults to an hour for a persistent session and a minute otherwise.
+     */
+    sessionExpirySeconds?: number;
+}
+export declare class MqttTransport extends GenericModule<Message, unknown, Message, unknown> {
+    url: string;
+    client?: mqtt.MqttClient;
+    connected: boolean;
+    /** Owned here rather than by a converter above, so the transport decides its own wire form. */
+    codec: FrameCodec;
+    readonly prefix: string;
+    readonly topic: string;
+    readonly qos: 0 | 1 | 2;
+    readonly presence: boolean;
+    readonly persistentSession: boolean;
+    readonly mqttOptions: mqtt.IClientOptions;
+    readonly protocol: 4 | 5;
+    readonly requestExpirySeconds: number;
+    readonly channels: Channel[];
+    readonly sharedGroup?: string;
+    readonly allowResponseTopic?: (topic: string, source: string) => boolean;
+    readonly tap: boolean;
+    readonly replicaId: string;
+    readonly sessionExpirySeconds: number;
+    /** A replica must not speak for the whole group; see the constructor. */
+    readonly announcePresence: boolean;
+    readonly sign?: MessageSigner;
+    readonly verify?: MessageVerifier;
+    readonly replayGuard: ReplayGuard;
+    /** Peer name -> identity established by verifying that peer's signature. */
+    peerIdentities: Map<string, RpcIdentity>;
+    /**
+     * Correlation -> where a request asked for its reply and in what encoding it arrived, so the
+     * answer goes back where it was asked for and in a form the caller can read. A third party that
+     * speaks JSON must not be answered in msgpack, and one that subscribed to a topic of its own
+     * choosing must not be answered on a topic we invented for it. Bounded, since the keys come off
+     * the wire.
+     */
+    private pendingReplies;
+    private maxTrackedReplies;
+    constructor(name: string, url: string, options?: MqttTransportOptions, sources?: IGenericModule<unknown, unknown, Message, unknown>[]);
+    /**
+     * The broker connection, or an error saying there is none.
+     *
+     * Publishing used to go through `this.client?.publishAsync(...)`, which resolves to undefined
+     * when the transport is closed or has not opened yet - so an outgoing call was dropped on the
+     * floor and its caller learned nothing until the call timed out. A frame that cannot be sent is
+     * a failure worth reporting at once.
+     */
+    private requireClient;
+    rpcTopic(peer: string): string;
+    channelTopic(channel: Channel, peer: string): string;
+    presenceTopic(peer: string): string;
+    private get presenceRoot();
+    open(): Promise<void>;
+    private connectedSince;
+    /** Consecutive connections that did not survive long enough to be doing anything useful. */
+    private shortConnections;
+    /**
+     * The 3.1.1 half of collision reporting, which has to be inferred rather than read.
+     *
+     * MQTT 5 says why it disconnected you; 3.1.1 has no reason codes, so a session taken over looks
+     * exactly like the link dropping. What it does not look like is a *stable* connection: two
+     * peers sharing a client id evict each other on sight, so both sit in a reconnect loop where no
+     * connection outlives the next one's arrival. A blip reconnects once and stays.
+     *
+     * Reported as a suspicion rather than a fact, because a network flapping this hard would look
+     * the same - and either way it is worth saying out loud.
+     */
+    private noteConnectionLength;
+    private warnedAboutFlapping;
+    private warnAboutFlapping;
+    /** Said once: mqtt.js reconnects on its own, and two peers sharing a name take turns forever. */
+    private warnedAboutDisplacement;
+    private warnAboutDisplacement;
+    private onConnect;
+    private onBrokerMessage;
+    private receiveV5;
+    /**
+     * A frame this transport is only watching, decoded and announced.
+     *
+     * The v1 layout carries no properties, so the payload has to be decoded here before anything can
+     * be said about it - which is also the only work a tap does per frame, and it is skipped
+     * entirely when nothing is listening.
+     */
+    private report;
+    /** The peer a topic addresses: <prefix>/<channel>/<peer>. */
+    private topicAddressee;
+    /**
+     * Hand a decoded frame to this peer's own handler, or on to whichever transport carries its
+     * addressee. The second case is a bridge: this transport is subscribed to a topic belonging to
+     * a peer that lives on another link, and its job is to pass the frame along unchanged - the
+     * source and any signature stay as the original sender wrote them.
+     */
+    private deliver;
+    /** Peers this transport collects answers for, so the subscriptions are made once and dropped once. */
+    private readonly proxied;
+    private watchOnBehalfOf;
+    /** Stop collecting for a peer that has gone, so a departed browser leaves no subscription behind. */
+    stopWatchingFor(peer: string): Promise<void>;
+    /**
+     * A reason to refuse a response topic, or undefined to publish the answer there.
+     *
+     * The topic comes from whoever sent the request, and this peer is the one that will publish to
+     * it, so without a rule a caller could have a server publish anywhere the broker's ACLs let it -
+     * over another peer's presence, into `$SYS`, or onto a retained topic something else reads. The
+     * default rule is the transport's own prefix, since that is the boundary an operator already
+     * draws ACLs on.
+     */
+    private refuseResponseTopic;
+    /**
+     * What is left of the caller's stated budget.
+     *
+     * MQTT 5 requires a server to hand on the Message Expiry Interval it received minus the time
+     * the message spent waiting in it, so for a request that was queued this is the caller's budget
+     * with the queueing already deducted - measured by the broker, with no clock of ours entering
+     * into it. Taken as an upper bound only: expiry is whole seconds and a broker of unknown
+     * quality set it, so it may shorten what the caller signed and never lengthen it.
+     */
+    private remainingTtl;
+    /**
+     * Seconds the broker should hold a request: what its caller said it would wait, rounded up.
+     *
+     * Clamped to the four-byte field MQTT gives it - about 136 years - because the ttl comes from
+     * whatever number a caller set as its timeout, and a value that does not fit would be a packet
+     * the broker refuses rather than a request that waits a long time.
+     */
+    private expiryFor;
+    private rememberReply;
+    /** One request, one answer: taking it also forgets it. */
+    private takeReply;
+    /** A peer may speak JSON while this one defaults to msgpack; contentType says which. */
+    private codecFor;
+    private verifyV5;
+    /**
+     * Returns a reason to reject, or undefined when the frame is authentic. Every check is a
+     * separate failure mode worth naming, because "message dropped" with no reason is the hardest
+     * kind of problem to diagnose on a plant network.
+     */
+    private verifyFrame;
+    receive(message: Message, source: string, target: string): Promise<void>;
+    /** Maps an RPC message onto the MQTT 5 packet layout. See docs/mqtt5-frame-spec.md. */
+    private publishV5;
+    close(): Promise<void>;
+    getIdentity(source: string): RpcIdentity | undefined;
+    isTransport(): boolean;
+}
+//# sourceMappingURL=MqttTransport.d.ts.map

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

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