@source-repo/rpc-cli 3.0.0

package/dist/conform.js

@@ -0,0 +1,152 @@
+import { namespaceProblems } from '@source-repo/rpc';
+import { awaitPeer, connectNetwork } from './network.js';
+import { signatureOf } from './verbs.js';
+/**
+ * Checking a device rather than a build.
+ *
+ * `check` compares source against a stored contract, which catches a change before it ships. What it
+ * cannot answer is the question asked on site: the contract says this device offers
+ * `writeSetpoint(value, mode?)` - is that what the box on the wall is actually running? A peer that
+ * describes itself can be asked, and the answer runs through the same comparison the server applies
+ * to a caller declaring an older version, so a device behind its own contract is reported in exactly
+ * the words a stale caller would have been.
+ */
+/** The one namespace nobody's own contract covers; every server that describes itself has it. */
+const INTROSPECTION = 'msgrpc';
+/**
+ * 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 const schemaFromDescription = (description) => ({
+    schema: 1,
+    ...(description.version ? { version: description.version } : {}),
+    types: description.types ?? {},
+    namespaces: Object.fromEntries(description.namespaces.map((namespace) => [
+        namespace.name,
+        {
+            ...(namespace.version ? { version: namespace.version } : {}),
+            methods: Object.fromEntries(namespace.methods.map((method) => [
+                method.name,
+                {
+                    params: method.params ?? [],
+                    ...(method.paramNames ? { paramNames: method.paramNames } : {}),
+                    ...(method.rest ? { rest: method.rest } : {}),
+                    ...(method.returns ? { returns: method.returns } : {})
+                }
+            ])),
+            events: Object.fromEntries(namespace.events.map((event) => [event.name, { params: event.params ?? [] }]))
+        }
+    ]))
+});
+/** Whether a peer publishes enough of a contract for a comparison to mean anything. */
+const describesItsMethods = (namespace) => namespace.methods.length === 0 || namespace.methods.some((method) => !!method.params);
+const describe = async (connected, peer) => {
+    const proxy = await connected.network.proxy(INTROSPECTION, peer);
+    return await proxy.remote.describe();
+};
+/**
+ * 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 const checkPeerOn = async (connected, options) => {
+    {
+        if (!(await awaitPeer(connected, options.peer, options.wait ?? 5000)))
+            throw Object.assign(new Error(`${options.peer} did not appear within ${options.wait ?? 5000} ms`), { code: 'ClassNotFound' });
+        const description = await describe(connected, options.peer);
+        const live = schemaFromDescription(description);
+        const types = { ...options.stored.types, ...live.types };
+        const report = { peer: options.peer, undescribed: [], problems: [], missing: [], checked: [] };
+        for (const [name, stored] of Object.entries(options.stored.namespaces)) {
+            if (name === INTROSPECTION)
+                continue;
+            const served = description.namespaces.find((namespace) => namespace.name === name);
+            if (!served) {
+                report.missing.push(name);
+                continue;
+            }
+            // A peer running without a schema describes its method names and nothing else. Comparing
+            // that would report every argument as removed, which is a statement about the peer's
+            // configuration rather than about its contract - so it is said plainly instead.
+            if (!describesItsMethods(served)) {
+                report.undescribed.push(name);
+                continue;
+            }
+            report.checked.push(name);
+            report.problems.push(...namespaceProblems(stored, live.namespaces[name], types).map((problem) => ({ ...problem, namespace: name })));
+        }
+        return report;
+    }
+};
+/** The same, opening a connection of its own - what the command line wants. */
+export const checkPeer = async (options) => {
+    const connected = await connectNetwork(options);
+    try {
+        return await checkPeerOn(connected, options);
+    }
+    finally {
+        await connected.close();
+    }
+};
+/**
+ * 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 const diffPeersOn = async (connected, options) => {
+    {
+        for (const peer of [options.left, options.right])
+            if (!(await awaitPeer(connected, peer, options.wait ?? 5000)))
+                throw Object.assign(new Error(`${peer} did not appear within ${options.wait ?? 5000} ms`), { code: 'ClassNotFound' });
+        const [left, right] = await Promise.all([describe(connected, options.left), describe(connected, options.right)]);
+        const differences = [];
+        const namespaces = [...new Set([...left.namespaces.map((n) => n.name), ...right.namespaces.map((n) => n.name)])].sort();
+        for (const name of namespaces) {
+            if (name === INTROSPECTION)
+                continue;
+            const here = left.namespaces.find((namespace) => namespace.name === name);
+            const there = right.namespaces.find((namespace) => namespace.name === name);
+            if (!here || !there) {
+                differences.push({ namespace: name, ...(here ? { left: 'served' } : {}), ...(there ? { right: 'served' } : {}) });
+                continue;
+            }
+            if (here.version !== there.version)
+                differences.push({ namespace: name, member: 'contract version', left: here.version ?? 'none', right: there.version ?? 'none' });
+            const members = [...new Set([...here.methods.map((m) => m.name), ...there.methods.map((m) => m.name)])].sort();
+            for (const member of members) {
+                const a = here.methods.find((method) => method.name === member);
+                const b = there.methods.find((method) => method.name === member);
+                const one = a ? signatureOf(a) : undefined;
+                const other = b ? signatureOf(b) : undefined;
+                if (one !== other)
+                    differences.push({ namespace: name, member, ...(one ? { left: one } : {}), ...(other ? { right: other } : {}) });
+            }
+            const events = [...new Set([...here.events.map((e) => e.name), ...there.events.map((e) => e.name)])].sort();
+            for (const event of events) {
+                const a = here.events.some((entry) => entry.name === event);
+                const b = there.events.some((entry) => entry.name === event);
+                if (a !== b)
+                    differences.push({ namespace: name, member: `event ${event}`, ...(a ? { left: 'emitted' } : {}), ...(b ? { right: 'emitted' } : {}) });
+            }
+        }
+        return { left: options.left, right: options.right, differences };
+    }
+};
+/** The same, opening a connection of its own - what the command line wants. */
+export const diffPeers = async (options) => {
+    const connected = await connectNetwork(options);
+    try {
+        return await diffPeersOn(connected, options);
+    }
+    finally {
+        await connected.close();
+    }
+};
+//# sourceMappingURL=conform.js.map

package/dist/conform.js.map

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

package/dist/console.d.ts

@@ -0,0 +1,285 @@
+import { type ServerOptions as TlsServerOptions } from 'node:https';
+import { EventEmitter } from 'events';
+import { RpcServer, type ServerDescription } from '@source-repo/rpc';
+import { type NetworkOptions } from './network.js';
+import { BusService, type TapFilter, type TappedFrame } from './bus.js';
+/**
+ * A browser console for a live msgrpc network: which peers are up, what each one exposes, and a
+ * form to call it and watch its events.
+ *
+ * Peer discovery is nearly free. Every peer publishes retained presence, so subscribing to
+ * <prefix>/presence/+ hands over everyone already online immediately - no scanning, no probing.
+ *
+ * The browser reaches this over msgrpc itself. The CLI runs an RpcServer on the same HTTP server
+ * that serves the page, so calls and the event stream both ride the library rather than a REST and
+ * SSE pair written for the occasion - and the console becomes the library's own first client.
+ */
+/**
+ * Where the page learns which peer to address. Everything else the console offers is RPC, but a
+ * client has to know the name before it can call anything, and the console's name is now its name
+ * on the network rather than a constant - two consoles on one bus cannot both be 'msgrpc-console'.
+ */
+export declare const consoleIdentityPath = "/console.json";
+/**
+ * The network flags every command shares, plus where the console listens.
+ *
+ * A hub is how a network with no broker - and a server hosted in a browser page, which cannot
+ * listen at all - becomes visible: peers there announce themselves on connect. Without `sign` the
+ * console cannot talk to a server configured with `verify`; it still discovers peers, because
+ * presence is unsigned retained state, and then every call times out with nothing to say why.
+ */
+export interface ConsoleOptions extends NetworkOptions {
+    port: number;
+    host: string;
+    /**
+     * Certificate and key, which is what makes this console HTTPS - and its socket.io link WSS,
+     * since both ride the same listener. Absent means plain HTTP, which is right behind a proxy
+     * that has already terminated TLS.
+     */
+    tls?: TlsServerOptions;
+    /**
+     * The path this console is published under, when a reverse proxy forwards the prefix instead of
+     * stripping it. `/tools/console` makes the page, its assets and socket.io all answer there.
+     *
+     * Not needed for the ordinary `proxy_pass http://console:7844/` rule, whose trailing slash
+     * strips the prefix before the console sees it - the page already resolves everything relative
+     * to where it was served, so that case needs no configuration at either end. This is for the
+     * proxy that passes `/tools/console/socket.io` through unchanged.
+     */
+    basePath?: string;
+}
+/**
+ * A mount point as `/tools/console/`, or `/` for none: one leading slash, one trailing slash.
+ *
+ * The trailing slash is the load-bearing part. Everything the page asks for is relative to its
+ * mount, so the app has to be reached at a path ending in one or its requests resolve a level up.
+ */
+export declare const normaliseBasePath: (basePath?: string) => string;
+/** An event the console forwarded from a peer it was asked to watch. */
+export interface StreamedEvent {
+    peer: string;
+    namespace: string;
+    event: string;
+    args: unknown[];
+    at: number;
+}
+/** A peer arriving or leaving, on any of the console's links. */
+export interface PeerChange {
+    peer: string;
+    state: string;
+    at: number;
+    /** The link it arrived on or left from, when the console knows it. */
+    link?: string;
+}
+/**
+ * What a peer turned out to be, learned from a description the console had already made.
+ *
+ * Deliberately not discovered by describing every peer on sight: that is a round trip each on a
+ * network where the peer list is the cheap part. The console describes a peer when someone selects
+ * it, and when it goes looking for a bus to tap - so the labels fill in as the network is used, and
+ * cost nothing that was not already being spent.
+ */
+export type PeerRole = 'broker' | 'console' | 'page' | 'device' | 'undescribed';
+/** A tap the console holds, and where it holds it. */
+export interface ConsoleTap {
+    token: string;
+    /** The peers doing the watching: a broker's `bus`, this console's own MQTT tap, or both. */
+    sources: string[];
+}
+/**
+ * A frame a transport refused or could not deliver, a name two peers claimed, or a link that
+ * failed - the four things that otherwise reach a caller only as an unexplained timeout.
+ *
+ * The transports have always emitted these. Nothing listened, so the console showed a call that
+ * never came back and no reason anywhere, which is the hardest kind of problem to diagnose and the
+ * one this tooling exists to make visible.
+ */
+export interface NetworkProblem {
+    at: number;
+    /** `rejected`, `unroutable`, `peerDisplaced` or `transportError`. */
+    kind: string;
+    /** The link it happened on: the page's own, the broker, or the hub. */
+    link: string;
+    /** Who the frame claimed to come from, or the name that was taken over. */
+    peer?: string;
+    /** Who an undeliverable frame was addressed to. */
+    target?: string;
+    reason?: string;
+}
+/** What a browser may ask this console to do. Everything else on the class stays local. */
+export declare class ConsoleService extends EventEmitter {
+    /** Every peer the console can see, on any of its links. */
+    private readonly online;
+    /** How long this console waits on the network, reported so the browser can wait longer. */
+    private readonly callTimeout;
+    /**
+     * Declared rather than inferred from emit() calls, which cannot be read statically. Without
+     * this the console's own contract described its methods and none of its events, so a console
+     * pointed at another one saw an empty events list on a service that has three.
+     */
+    rpcEvents: {
+        event: [event: StreamedEvent];
+        peer: [change: PeerChange];
+        frame: [frame: TappedFrame];
+        problem: [problem: NetworkProblem];
+    };
+    /**
+     * Subscriptions this console holds on the network, keyed by peer/namespace/event. The handler
+     * is kept because removing a listener needs the same function reference that was registered.
+     */
+    readonly watching: Map<string, (...args: unknown[]) => void>;
+    /**
+     * The console's own place on the network, set once it exists. Every call the browser asks for
+     * goes out through this: one server holding the browser link, the broker and the hub, so a
+     * peer's name is enough - the registry knows which link reaches it.
+     */
+    private network?;
+    useNetwork(network: RpcServer): void;
+    /**
+     * This console's own tap, when it has an MQTT link. There is no broker of ours on an MQTT
+     * network to ask, so the console does the watching itself - see `startConsole`.
+     */
+    private localBus?;
+    useLocalTap(bus: BusService): void;
+    /** Which link each peer was last seen on, written by startConsole as they arrive. */
+    readonly links: Map<string, string>;
+    /**
+     * The flags this console was started with, so the page can render a command line that actually
+     * runs. A call worth making in the browser is usually one worth putting in a script, and
+     * retyping `--hub http://…` from memory is where that stops happening.
+     */
+    startedWith: {
+        broker?: string;
+        hub?: string;
+        prefix?: string;
+    };
+    /** What has gone wrong on the links, newest first and bounded. */
+    private readonly seen;
+    /**
+     * Peers arriving and leaving, newest first and bounded.
+     *
+     * Kept because a peer that comes and goes is one of the commonest faults on a plant and the
+     * hardest to catch in the act: the console showed it as a dot that changed colour and forgot,
+     * so a device flapping every thirty seconds looked exactly like one that was simply up.
+     */
+    private readonly comings;
+    /** What each peer turned out to be, from descriptions already made. */
+    private readonly roles;
+    notePresence(change: PeerChange): void;
+    /** Records a problem and passes it on, so a page open now sees it and one opened later still can. */
+    noteProblem(problem: NetworkProblem): void;
+    /** Console-side token -> the taps it opened, here and on other peers, and when they lapse. */
+    private readonly held;
+    /** Peers whose `frame` event this console has already subscribed to, so it subscribes once. */
+    private readonly forwarding;
+    private tapCounter;
+    constructor(
+    /** Every peer the console can see, on any of its links. */
+    online: Set<string>, 
+    /** How long this console waits on the network, reported so the browser can wait longer. */
+    callTimeout: number);
+    /** Refuses early for a peer nothing has announced, rather than waiting out a call timeout. */
+    private reach;
+    peers(): Promise<{
+        peers: string[];
+        watching: string[];
+        callTimeout: number;
+        network: {
+            broker?: string;
+            hub?: string;
+            prefix?: string;
+        };
+        roles: {
+            [k: string]: PeerRole;
+        };
+        links: {
+            [k: string]: string;
+        };
+    }>;
+    /**
+     * What has gone wrong on the links, newest first.
+     *
+     * Fetched as well as streamed, because these arrive whether or not anyone is watching and the
+     * interesting ones are usually the ones from before you went looking.
+     */
+    problems(): Promise<{
+        problems: NetworkProblem[];
+    }>;
+    /**
+     * Peers arriving and leaving, newest first - including before this page was opened, which is
+     * the half that matters when the question is whether something has been flapping.
+     */
+    presence(): Promise<{
+        changes: PeerChange[];
+    }>;
+    describe(peer: string): Promise<ServerDescription | {
+        error: string;
+        code?: string;
+    }>;
+    call(peer: string, namespace: string, method: string, args?: unknown[]): Promise<{
+        result?: unknown;
+        error?: string;
+        code?: string;
+        ms: number;
+    }>;
+    watch(peer: string, namespace: string, event: string): Promise<{
+        watching: boolean;
+        already: boolean;
+    }>;
+    unwatch(peer: string, namespace: string, event: string): Promise<{
+        watching: boolean;
+        already: boolean;
+    }>;
+    /**
+     * Peers that can watch traffic: any exposing a `bus`, which in practice is the broker.
+     *
+     * Found by describing rather than configured, because the broker is a peer like any other and
+     * the console has no idea which of them it is. Cached: the answer changes only when a broker
+     * joins or leaves, and describing every peer on each tap would be a round trip per peer.
+     */
+    private busPeers;
+    private readonly knownBuses;
+    /** A peer that has gone is worth asking about again if it comes back under new software. */
+    forgetBus(peer: string): void;
+    /**
+     * Start watching traffic, wherever this console can watch it.
+     *
+     * A socket.io network is watched at the broker, which is the only thing that sees frames it is
+     * not party to; an MQTT network is watched by this console's own subscription, since there is
+     * no broker of ours there to ask. A console holding both links turns on both, and the frames
+     * arrive on one event either way - which is what keeps the page from having to know any of this.
+     */
+    tap(filter?: TapFilter): Promise<ConsoleTap>;
+    untap(token: string): Promise<{
+        tapping: boolean;
+        already: boolean;
+    }>;
+    /** Everything this console is watching, and where. */
+    taps(): Promise<{
+        taps: ConsoleTap[];
+        sources: string[];
+    }>;
+    /**
+     * Drops taps whose life has run out, and the subscriptions they were holding.
+     *
+     * The taps themselves have already lapsed at the far end by now; this is what stops the console
+     * forwarding frames for them, and what keeps `held` from growing by one on every page reload.
+     */
+    private expireTaps;
+    /**
+     * Drops the subscriptions on the peers doing the watching once nothing here wants them.
+     *
+     * Kept until then rather than per tap, since several taps share one subscription - and dropped
+     * when the last goes, so a broker is not left emitting frames into a console that stopped
+     * reading them.
+     */
+    private stopForwardingIfIdle;
+    /** Drops every subscription this console holds, so servers that outlive it keep no listeners. */
+    releaseAll(): Promise<void>;
+}
+export declare const startConsole: (options: ConsoleOptions) => Promise<{
+    url: string;
+    service: ConsoleService;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=console.d.ts.map

package/dist/console.d.ts.map

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