@source-repo/rpc-cli 3.0.0

package/dist/bus.js

@@ -0,0 +1,272 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { EventEmitter } from 'events';
+import { rpc, rpcNamespace, RpcMessageType } from '@source-repo/rpc';
+/** Exported so the console can give its own record of a tap the same life as the tap itself. */
+export const DEFAULT_TAP_TTL = 300;
+const DEFAULT_TTL = DEFAULT_TAP_TTL;
+const MAX_TTL = 3600;
+/**
+ * How many calls are remembered while waiting for their replies. A call whose reply never comes
+ * would otherwise be held forever, and this runs on a bus with no upper bound on traffic.
+ */
+const MAX_PENDING = 5000;
+/** The kinds, as the wire writes them, so a filter can name them without importing the enum. */
+const KINDS = new Set([RpcMessageType.CallInstanceMethod, RpcMessageType.success, RpcMessageType.error, RpcMessageType.event]);
+let BusService = (() => {
+    let _classDecorators = [rpcNamespace('bus', { version: '1' })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _classSuper = EventEmitter;
+    let _instanceExtraInitializers = [];
+    let _tap_decorators;
+    let _untap_decorators;
+    let _taps_decorators;
+    var BusService = class extends _classSuper {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _tap_decorators = [rpc];
+            _untap_decorators = [rpc];
+            _taps_decorators = [rpc];
+            __esDecorate(this, null, _tap_decorators, { kind: "method", name: "tap", static: false, private: false, access: { has: obj => "tap" in obj, get: obj => obj.tap }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _untap_decorators, { kind: "method", name: "untap", static: false, private: false, access: { has: obj => "untap" in obj, get: obj => obj.untap }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _taps_decorators, { kind: "method", name: "taps", static: false, private: false, access: { has: obj => "taps" in obj, get: obj => obj.taps }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            BusService = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        busName = __runInitializers(this, _instanceExtraInitializers);
+        active = new Map();
+        /** Calls seen and not yet answered, so a reply can be given the time it took and the method. */
+        pending = new Map();
+        counter = 0;
+        constructor(
+        /** Named in what `taps()` reports, so a reader knows which broker they are looking at. */
+        busName) {
+            super();
+            this.busName = busName;
+        }
+        /**
+         * Opened when the first tap starts and closed after the last one ends, for a source that costs
+         * something to hold open - an MQTT subscription to every peer's traffic, in particular. A broker
+         * needs none of this: it is already forwarding the frames, and `observe` returns on its first
+         * line when nothing is watching.
+         */
+        onDemand;
+        /**
+         * Starts or stops the source to match whether anything is watching.
+         *
+         * Failures on the way down are swallowed and failures on the way up are not: a tap that could
+         * not subscribe has to say so, or it reports an empty network and looks like a quiet one.
+         */
+        async settleSource(wasActive) {
+            const active = this.active.size > 0;
+            if (active === wasActive || !this.onDemand)
+                return;
+            if (active)
+                await this.onDemand.start();
+            else
+                await this.onDemand.stop().catch(() => undefined);
+        }
+        /**
+         * Start watching. Returns a token: several people can tap at once with different filters, and
+         * untapping has to remove yours rather than everyone's.
+         */
+        async tap(filter) {
+            const requested = filter ?? {};
+            for (const kind of requested.kinds ?? [])
+                if (!KINDS.has(kind))
+                    throw Object.assign(new Error(`unknown kind '${kind}'`), { code: 'InvalidParams' });
+            // Bounded rather than taken as given: a ttl of a year is a leak with a number on it.
+            const ttl = Math.min(Math.max(requested.ttl ?? DEFAULT_TTL, 1), MAX_TTL);
+            const token = `tap-${++this.counter}`;
+            const wasActive = this.active.size > 0;
+            this.active.set(token, { token, filter: { ...requested, ttl }, expires: Date.now() + ttl * 1000, frames: 0 });
+            try {
+                await this.settleSource(wasActive);
+            }
+            catch (e) {
+                // Rolled back rather than left as a tap watching nothing, which would report a quiet
+                // network instead of a source that could not be opened.
+                this.active.delete(token);
+                throw e;
+            }
+            return { token, expires: Date.now() + ttl * 1000, filter: { ...requested, ttl } };
+        }
+        async untap(token) {
+            const wasActive = this.active.size > 0;
+            const had = this.active.delete(token);
+            if (!this.active.size)
+                this.pending.clear();
+            await this.settleSource(wasActive);
+            return { tapping: false, already: !had };
+        }
+        /** Who is watching what, including how much each tap has seen. */
+        async taps() {
+            this.expire();
+            return { bus: this.busName, taps: [...this.active.values()], pending: this.pending.size };
+        }
+        /** Whether anything is listening, so the broker can leave the transport hook unattached. */
+        get tapping() {
+            this.expire();
+            return this.active.size > 0;
+        }
+        expire() {
+            const now = Date.now();
+            const wasActive = this.active.size > 0;
+            for (const [token, record] of this.active)
+                if (record.expires <= now)
+                    this.active.delete(token);
+            if (!this.active.size)
+                this.pending.clear();
+            // Not awaited: expiry is noticed from the frame path and from taps(), neither of which can
+            // wait on a broker connection closing. Failures on the way down are swallowed anyway.
+            if (wasActive && !this.active.size)
+                void this.settleSource(wasActive);
+        }
+        /**
+         * One relayed frame, from the transport that forwarded it.
+         *
+         * Everything here is best-effort reading of someone else's message: a frame whose payload is
+         * not the shape we expect is reported with what could be read rather than dropped, since a
+         * malformed frame on the bus is exactly the sort of thing a tap exists to show.
+         */
+        observe(relayed) {
+            this.expire();
+            if (!this.active.size)
+                return;
+            const frame = this.readFrame(relayed);
+            if (!frame)
+                return;
+            const matched = [...this.active.values()].filter((record) => this.matches(record.filter, frame));
+            if (!matched.length)
+                return;
+            // Payloads are carried only if at least one of the taps that matched asked for them.
+            if (!matched.some((record) => record.filter.payloads)) {
+                delete frame.params;
+                delete frame.result;
+            }
+            frame.taps = matched.map((record) => record.token);
+            for (const record of matched)
+                record.frames++;
+            this.emit('frame', frame);
+        }
+        matches(filter, frame) {
+            if (filter.peer && frame.source !== filter.peer && frame.target !== filter.peer)
+                return false;
+            if (filter.namespace && frame.namespace !== filter.namespace)
+                return false;
+            if (filter.kinds?.length && !filter.kinds.includes(frame.kind))
+                return false;
+            return true;
+        }
+        readFrame({ source, target, message }) {
+            const payload = message.payload;
+            if (!payload || typeof payload !== 'object' || typeof payload.type !== 'string')
+                return undefined;
+            const at = Date.now();
+            const frame = { at, source, target, kind: payload.type, taps: [] };
+            switch (payload.type) {
+                case RpcMessageType.CallInstanceMethod: {
+                    const call = payload;
+                    frame.namespace = call.path;
+                    frame.method = call.method;
+                    frame.id = call.id;
+                    frame.params = call.params;
+                    // Remembered so the reply can be given a duration and the method it answers.
+                    if (this.pending.size >= MAX_PENDING) {
+                        const oldest = this.pending.keys().next();
+                        if (!oldest.done)
+                            this.pending.delete(oldest.value);
+                    }
+                    if (call.id)
+                        this.pending.set(call.id, { at, namespace: call.path, method: call.method, source });
+                    break;
+                }
+                case RpcMessageType.success: {
+                    const success = payload;
+                    frame.id = success.id;
+                    frame.result = success.result;
+                    this.pair(frame);
+                    break;
+                }
+                case RpcMessageType.error: {
+                    const failure = payload;
+                    frame.id = failure.id;
+                    frame.code = failure.code;
+                    frame.error = failure.error?.message;
+                    this.pair(frame);
+                    break;
+                }
+                case RpcMessageType.event: {
+                    const event = payload;
+                    frame.event = event.event;
+                    frame.namespace = event.path;
+                    frame.params = event.params;
+                    break;
+                }
+                default:
+                    // An unrecognised kind is still traffic, and still worth showing.
+                    break;
+            }
+            return frame;
+        }
+        /** Fills in what a reply does not carry: the method it answers, and how long it took. */
+        pair(frame) {
+            if (!frame.id)
+                return;
+            const call = this.pending.get(frame.id);
+            if (!call)
+                return;
+            this.pending.delete(frame.id);
+            frame.ms = frame.at - call.at;
+            frame.namespace = call.namespace;
+            frame.method = call.method;
+        }
+        /** Drops every tap, so a broker shutting down stops building frames for nobody. */
+        async releaseAll() {
+            const wasActive = this.active.size > 0;
+            this.active.clear();
+            this.pending.clear();
+            await this.settleSource(wasActive);
+        }
+    };
+    return BusService = _classThis;
+})();
+export { BusService };
+//# sourceMappingURL=bus.js.map

package/dist/bus.js.map

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

package/dist/bus.types.json

@@ -0,0 +1,269 @@
+{
+    "schema": 1,
+    "types": {
+        "TapFilter": {
+            "kind": "object",
+            "fields": {
+                "peer": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "namespace": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "kinds": {
+                    "type": {
+                        "kind": "array",
+                        "items": {
+                            "kind": "string"
+                        }
+                    },
+                    "optional": true
+                },
+                "payloads": {
+                    "type": {
+                        "kind": "boolean"
+                    },
+                    "optional": true
+                },
+                "ttl": {
+                    "type": {
+                        "kind": "number"
+                    },
+                    "optional": true
+                }
+            }
+        },
+        "TapRecord": {
+            "kind": "object",
+            "fields": {
+                "token": {
+                    "type": {
+                        "kind": "string"
+                    }
+                },
+                "filter": {
+                    "type": {
+                        "kind": "ref",
+                        "name": "TapFilter"
+                    }
+                },
+                "expires": {
+                    "type": {
+                        "kind": "number"
+                    }
+                },
+                "frames": {
+                    "type": {
+                        "kind": "number"
+                    }
+                }
+            }
+        },
+        "TappedFrame": {
+            "kind": "object",
+            "fields": {
+                "at": {
+                    "type": {
+                        "kind": "number"
+                    }
+                },
+                "source": {
+                    "type": {
+                        "kind": "string"
+                    }
+                },
+                "target": {
+                    "type": {
+                        "kind": "string"
+                    }
+                },
+                "kind": {
+                    "type": {
+                        "kind": "string"
+                    }
+                },
+                "namespace": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "method": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "event": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "id": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "ms": {
+                    "type": {
+                        "kind": "number"
+                    },
+                    "optional": true
+                },
+                "code": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "error": {
+                    "type": {
+                        "kind": "string"
+                    },
+                    "optional": true
+                },
+                "params": {
+                    "type": {
+                        "kind": "array",
+                        "items": {
+                            "kind": "any"
+                        }
+                    },
+                    "optional": true
+                },
+                "result": {
+                    "type": {
+                        "kind": "any"
+                    },
+                    "optional": true
+                },
+                "taps": {
+                    "type": {
+                        "kind": "array",
+                        "items": {
+                            "kind": "string"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "namespaces": {
+        "bus": {
+            "version": "1",
+            "methods": {
+                "tap": {
+                    "params": [
+                        {
+                            "kind": "union",
+                            "options": [
+                                {
+                                    "kind": "ref",
+                                    "name": "TapFilter"
+                                },
+                                {
+                                    "kind": "literal",
+                                    "value": null
+                                }
+                            ]
+                        }
+                    ],
+                    "paramNames": [
+                        "filter"
+                    ],
+                    "returns": {
+                        "kind": "object",
+                        "fields": {
+                            "token": {
+                                "type": {
+                                    "kind": "string"
+                                }
+                            },
+                            "expires": {
+                                "type": {
+                                    "kind": "number"
+                                }
+                            },
+                            "filter": {
+                                "type": {
+                                    "kind": "ref",
+                                    "name": "TapFilter"
+                                }
+                            }
+                        }
+                    }
+                },
+                "untap": {
+                    "params": [
+                        {
+                            "kind": "string"
+                        }
+                    ],
+                    "paramNames": [
+                        "token"
+                    ],
+                    "returns": {
+                        "kind": "object",
+                        "fields": {
+                            "tapping": {
+                                "type": {
+                                    "kind": "boolean"
+                                }
+                            },
+                            "already": {
+                                "type": {
+                                    "kind": "boolean"
+                                }
+                            }
+                        }
+                    }
+                },
+                "taps": {
+                    "params": [],
+                    "returns": {
+                        "kind": "object",
+                        "fields": {
+                            "bus": {
+                                "type": {
+                                    "kind": "string"
+                                }
+                            },
+                            "taps": {
+                                "type": {
+                                    "kind": "array",
+                                    "items": {
+                                        "kind": "ref",
+                                        "name": "TapRecord"
+                                    }
+                                }
+                            },
+                            "pending": {
+                                "type": {
+                                    "kind": "number"
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "events": {
+                "frame": {
+                    "params": [
+                        {
+                            "kind": "ref",
+                            "name": "TappedFrame"
+                        }
+                    ]
+                }
+            }
+        }
+    }
+}

package/dist/conform.d.ts

@@ -0,0 +1,75 @@
+import { type Incompatibility, type RpcSchema, type ServerDescription } from '@source-repo/rpc';
+import { type ConnectedNetwork, type NetworkOptions } from './network.js';
+/**
+ * A live peer's self-description as a schema the compatibility check can read.
+ *
+ * The two are nearly the same information in different shapes - describe() returns lists because a
+ * console renders them in order, a schema uses dictionaries because dispatch looks methods up by
+ * name.
+ */
+export declare const schemaFromDescription: (description: ServerDescription) => RpcSchema;
+export interface ConformanceProblem extends Incompatibility {
+    namespace: string;
+}
+export interface ConformanceReport {
+    peer: string;
+    /** True when the peer serves its methods without a published contract, so nothing was compared. */
+    undescribed: string[];
+    problems: ConformanceProblem[];
+    /** Namespaces the stored contract has and the peer does not serve at all. */
+    missing: string[];
+    checked: string[];
+}
+/**
+ * Compares what a peer says it serves with the contract callers were built against.
+ *
+ * The stored contract is the caller's side and the device is the current side, which is the same
+ * orientation `check` uses against source - so "argument 0 narrowed" means the same thing here as
+ * it does in CI, and means it about the box rather than the branch.
+ */
+export declare const checkPeerOn: (connected: ConnectedNetwork, options: {
+    peer: string;
+    stored: RpcSchema;
+    wait?: number;
+}) => Promise<ConformanceReport>;
+/** The same, opening a connection of its own - what the command line wants. */
+export declare const checkPeer: (options: NetworkOptions & {
+    peer: string;
+    stored: RpcSchema;
+    wait?: number;
+}) => Promise<ConformanceReport>;
+export interface PeerDifference {
+    namespace: string;
+    /** The method or event, or undefined when a whole namespace is on one side only. */
+    member?: string;
+    /** How it reads on each side; absent means it is not there at all. */
+    left?: string;
+    right?: string;
+}
+/**
+ * What two live peers offer differently - the "why does cell 3 behave differently from cell 2"
+ * question, which is usually answered by one of them running last season's firmware.
+ *
+ * Signatures are compared as they read rather than structurally, because the answer is going to be
+ * read by a person standing in front of two cabinets.
+ */
+export declare const diffPeersOn: (connected: ConnectedNetwork, options: {
+    left: string;
+    right: string;
+    wait?: number;
+}) => Promise<{
+    left: string;
+    right: string;
+    differences: PeerDifference[];
+}>;
+/** The same, opening a connection of its own - what the command line wants. */
+export declare const diffPeers: (options: NetworkOptions & {
+    left: string;
+    right: string;
+    wait?: number;
+}) => Promise<{
+    left: string;
+    right: string;
+    differences: PeerDifference[];
+}>;
+//# sourceMappingURL=conform.d.ts.map

package/dist/conform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conform.d.ts","sourceRoot":"","sources":["../src/conform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,eAAe,EAAwB,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACxI,OAAO,EAA6B,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAiBpG;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,gBAAiB,iBAAiB,KAAG,SAwBrE,CAAA;AAMF,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACvD,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,mGAAmG;IACnG,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,EAAE,MAAM,EAAE,CAAA;CACpB;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,cAAqB,gBAAgB,WAAW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,iBAAiB,CA4BrJ,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,YAAmB,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,iBAAiB,CAOvI,CAAA;AAED,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,cAAqB,gBAAgB,WAAW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;;;;EAwCrH,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,YAAmB,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;;;;EAOvG,CAAA"}