@source-repo/rpc-cli 3.0.0

package/dist/bench.d.ts

@@ -0,0 +1,66 @@
+import { type NetworkOptions } from './network.js';
+/**
+ * Calling one method over and over, and reporting what it cost.
+ *
+ * `call` already returns the time a single call took, and the console shows it once and forgets it.
+ * The question a plant actually asks is the one a single call cannot answer: this device is fine at
+ * one call a second - what does it do at twenty? Finding the rate at which a device falls over is
+ * ordinarily done by writing a script, and the script is always the same script.
+ *
+ * Percentiles rather than an average, because an average hides exactly the calls worth knowing
+ * about: a device answering in 2 ms with one reply a second taking 4 seconds averages out to
+ * something that looks healthy.
+ */
+export interface BenchOptions extends NetworkOptions {
+    peer: string;
+    namespace: string;
+    method: string;
+    /** Already coerced; `runBench` does that from the contract when given words. */
+    args: unknown[];
+    /** Calls per second to aim for. */
+    rate: number;
+    /** How long to keep going. */
+    forMs: number;
+    /** How many calls may be outstanding at once before the rest are counted as fallen behind. */
+    concurrency: number;
+    wait?: number;
+}
+export interface BenchReport {
+    peer: string;
+    method: string;
+    calls: number;
+    ok: number;
+    failed: number;
+    /**
+     * Calls not sent because too many were already outstanding. A device that cannot keep up shows
+     * here rather than in the latencies, where it would look like the network was fine.
+     */
+    behind: number;
+    /** How the failures broke down, by RPC error code. */
+    codes: {
+        [code: string]: number;
+    };
+    ms: {
+        min: number;
+        p50: number;
+        p90: number;
+        p95: number;
+        p99: number;
+        max: number;
+        mean: number;
+    };
+    rate: {
+        asked: number;
+        achieved: number;
+    };
+    ranForMs: number;
+}
+export declare const bench: (options: BenchOptions) => Promise<BenchReport>;
+/** Coerces the words a shell gives against the peer's own contract, the way `call` does. */
+export declare const benchArguments: (options: NetworkOptions & {
+    peer: string;
+    namespace: string;
+    method: string;
+    texts: string[];
+}) => Promise<unknown[]>;
+//# sourceMappingURL=bench.d.ts.map

package/dist/bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench.d.ts","sourceRoot":"","sources":["../src/bench.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAG7E;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,KAAK,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IACjC,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAClG,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,QAAQ,EAAE,MAAM,CAAA;CACnB;AAYD,eAAO,MAAM,KAAK,YAAmB,YAAY,KAAG,OAAO,CAAC,WAAW,CAgFtE,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,cAAc,YAAmB,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,uBAYlI,CAAA"}

package/dist/bench.js

@@ -0,0 +1,109 @@
+import { awaitPeer, connectNetwork } from './network.js';
+import { coerceArguments } from './verbs.js';
+const percentile = (sorted, fraction) => {
+    if (!sorted.length)
+        return 0;
+    // Nearest-rank: with 20 samples the 95th is the 19th, which is a sample that happened rather
+    // than an interpolation between two that did.
+    const rank = Math.min(sorted.length - 1, Math.ceil(fraction * sorted.length) - 1);
+    return sorted[Math.max(0, rank)];
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const bench = async (options) => {
+    const connected = await connectNetwork(options);
+    try {
+        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 proxy = await connected.network.proxy(options.namespace, options.peer);
+        const remote = proxy.remote;
+        const latencies = [];
+        const codes = {};
+        let ok = 0;
+        let failed = 0;
+        let behind = 0;
+        let inFlight = 0;
+        const outstanding = [];
+        const fire = () => {
+            inFlight++;
+            const started = Date.now();
+            const call = remote[options.method](...options.args)
+                .then(() => {
+                ok++;
+                latencies.push(Date.now() - started);
+            })
+                .catch((e) => {
+                failed++;
+                // Counted by code rather than lumped together: a device refusing arguments and
+                // a device that stopped answering are different findings with the same shape.
+                const code = e.code ?? 'Exception';
+                codes[code] = (codes[code] ?? 0) + 1;
+                latencies.push(Date.now() - started);
+            })
+                .finally(() => {
+                inFlight--;
+            });
+            outstanding.push(call);
+        };
+        const interval = options.rate > 0 ? 1000 / options.rate : 0;
+        const began = Date.now();
+        const deadline = began + options.forMs;
+        let next = began;
+        while (Date.now() < deadline) {
+            const waiting = next - Date.now();
+            if (waiting > 0)
+                await sleep(Math.min(waiting, deadline - Date.now()));
+            if (Date.now() >= deadline)
+                break;
+            // Not sent rather than queued: piling calls onto a device that is already behind
+            // measures the queue rather than the device.
+            if (inFlight >= options.concurrency)
+                behind++;
+            else
+                fire();
+            next = interval > 0 ? next + interval : Date.now();
+        }
+        // The last calls are waited out, so a run does not report latencies it never collected.
+        await Promise.allSettled(outstanding);
+        const ranForMs = Date.now() - began;
+        const sorted = [...latencies].sort((a, b) => a - b);
+        return {
+            peer: options.peer,
+            method: `${options.namespace}.${options.method}`,
+            calls: ok + failed,
+            ok,
+            failed,
+            behind,
+            codes,
+            ms: {
+                min: sorted[0] ?? 0,
+                p50: percentile(sorted, 0.5),
+                p90: percentile(sorted, 0.9),
+                p95: percentile(sorted, 0.95),
+                p99: percentile(sorted, 0.99),
+                max: sorted[sorted.length - 1] ?? 0,
+                mean: sorted.length ? Math.round(sorted.reduce((total, value) => total + value, 0) / sorted.length) : 0
+            },
+            rate: { asked: options.rate, achieved: ranForMs ? Math.round(((ok + failed) / ranForMs) * 1000 * 10) / 10 : 0 },
+            ranForMs
+        };
+    }
+    finally {
+        await connected.close();
+    }
+};
+/** Coerces the words a shell gives against the peer's own contract, the way `call` does. */
+export const benchArguments = async (options) => {
+    const connected = await connectNetwork(options);
+    try {
+        const description = await connected.network
+            .proxy('msgrpc', options.peer)
+            .then((proxy) => proxy.remote.describe())
+            .catch(() => undefined);
+        const method = description?.namespaces.find((namespace) => namespace.name === options.namespace)?.methods.find((entry) => entry.name === options.method);
+        return coerceArguments(options.texts, method, description?.types);
+    }
+    finally {
+        await connected.close();
+    }
+};
+//# sourceMappingURL=bench.js.map

package/dist/bench.js.map

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

package/dist/broker.d.ts

@@ -0,0 +1,61 @@
+import { RpcServer, type RpcAuthenticator } from '@source-repo/rpc';
+import type { ServerOptions as TlsServerOptions } from 'node:https';
+import { BusService } from './bus.js';
+/**
+ * A socket.io broker: an RpcServer that relays, and says what it is relaying when asked.
+ *
+ * There is no separate broker implementation, and there should not be. A server already learns who
+ * is connected, forwards a frame addressed to another peer, and tells every peer who else is there.
+ * Running one that way is what makes it a bus rather than a service - and that is worth a command
+ * of its own only because typing it out is tedious, not because it is a different thing.
+ *
+ * It used to expose nothing at all, so a peer addressing it by name got ClassNotFound - true, and
+ * the plainest possible statement that this is a switchboard. It now exposes exactly one namespace,
+ * `bus`, because the alternative was a --tap flag, and a plant bus that has to be restarted before
+ * it can be watched will not be watched: the run worth looking at is the one already going wrong.
+ * The consequence is stated on startup, since anyone who can reach an unauthenticated broker can
+ * now mirror everything crossing it - which they could always have done by impersonating a peer,
+ * but not this conveniently. `authenticate` and `relay` are what gate it.
+ *
+ * With `authenticate` it gates the whole bus rather than just the tap: a peer that presents no
+ * token this broker knows never reaches the RPC layer, and one that does may only claim the name
+ * its token was issued for. That is the difference between a bus behind a trusted network and a bus
+ * that can be put on one that is not.
+ *
+ * With `upstream` it dials another broker as well, which makes the two one network: each side's
+ * peers are advertised to the other, and a call crosses without either end knowing there was a hop.
+ */
+export interface BrokerOptions {
+    /** Listens on every interface: the library's socket.io transport takes no bind address. */
+    port: number;
+    name: string;
+    /** Brokers to join. Peers here become reachable from there, and the other way round. */
+    upstream?: string[];
+    /**
+     * Certificate and key, which is what makes this bus wss:// rather than ws://. Absent means
+     * plaintext, which is right on a segment that is already isolated or behind a terminating proxy.
+     */
+    tls?: TlsServerOptions;
+    /**
+     * Verify what a peer presents when it dials in. Without it the broker relays for anyone who can
+     * reach the port, and every peer name on it is an unchecked claim.
+     */
+    authenticate?: RpcAuthenticator;
+    /**
+     * Presented to each upstream, for joining a broker that authenticates. One value for all of
+     * them: a token names the peer that holds it, and this broker is one peer however many brokers
+     * it joins, so the same token is the right thing to send to each.
+     */
+    upstreamCredentials?: unknown;
+    /** Called for every arrival and departure, so a command line can show the network filling up. */
+    onPeer?: (peer: string, state: 'online' | 'offline', where: string) => void;
+}
+export declare const startBroker: (options: BrokerOptions) => Promise<{
+    server: RpcServer;
+    /** The tap, so an embedder can watch frames without going through RPC to reach it. */
+    bus: BusService;
+    /** Peers reachable through this broker right now, including any learned from an upstream. */
+    peers: () => string[];
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=broker.d.ts.map

package/dist/broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../src/broker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqC,KAAK,gBAAgB,EAAkC,MAAM,kBAAkB,CAAA;AACtI,OAAO,KAAK,EAAE,aAAa,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAKrC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,aAAa;IAC1B,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAA;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAA;IAC/B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,iGAAiG;IACjG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9E;AAED,eAAO,MAAM,WAAW,YAAmB,aAAa;;IAyChD,sFAAsF;;IAEtF,6FAA6F;;;EAOpG,CAAA"}

package/dist/broker.js

@@ -0,0 +1,56 @@
+import { RpcServer, TransportEvent } from '@source-repo/rpc';
+import { BusService } from './bus.js';
+// Extracted from bus.ts by `npm run contract` and committed, so a console pointed at a broker gets
+// argument fields for tap() rather than `tap(…)`.
+import contract from './bus.types.json' with { type: 'json' };
+export const startBroker = async (options) => {
+    const upstream = options.upstream ?? [];
+    const bus = new BusService(options.name);
+    const server = new RpcServer({
+        name: options.name,
+        transports: [
+            { port: options.port, ...(options.tls ? { tls: options.tls } : {}) },
+            ...upstream.map((url) => ({ connect: url, ...(options.upstreamCredentials ? { credentials: options.upstreamCredentials } : {}) }))
+        ],
+        ...(options.authenticate ? { authenticate: options.authenticate } : {}),
+        // The tap is the only thing here, and it describes itself: a console pointed at a broker
+        // used to be told ClassNotFound, which is indistinguishable from a device whose server was
+        // started without exposeIntrospection.
+        schema: contract,
+        exposeIntrospection: true,
+        readyTimeout: 15000
+    });
+    server.exposeClassInstance(bus);
+    try {
+        // ready() reports a listener that cannot bind rather than waiting it out.
+        await server.ready();
+    }
+    catch (e) {
+        // A broker that could not start still holds a socket.io server and whatever upstream links
+        // it opened. Throwing without closing them leaves them behind for the life of the process.
+        await server.close().catch(() => undefined);
+        throw e;
+    }
+    const where = (transport, index) => (index === 0 ? `:${options.port}` : (upstream[index - 1] ?? transport.getName()));
+    server.transports.forEach((transport, index) => {
+        transport.on(TransportEvent.peerOnline, (peer) => options.onPeer?.(peer, 'online', where(transport, index)));
+        transport.on(TransportEvent.peerGone, (peer) => options.onPeer?.(peer, 'offline', where(transport, index)));
+        // Attached for the life of the broker rather than added and removed with each tap: the
+        // transport only emits this when something is listening, and `observe` returns on the first
+        // line when no tap matches. Attaching on demand would mean a tap started mid-flight seeing
+        // the traffic from whenever the listener happened to land instead.
+        transport.on(TransportEvent.relayed, (relayed) => bus.observe(relayed));
+    });
+    return {
+        server,
+        /** The tap, so an embedder can watch frames without going through RPC to reach it. */
+        bus,
+        /** Peers reachable through this broker right now, including any learned from an upstream. */
+        peers: () => server.peers.names().filter((peer) => peer !== options.name).sort(),
+        close: async () => {
+            await bus.releaseAll();
+            await server.close();
+        }
+    };
+};
+//# sourceMappingURL=broker.js.map

package/dist/broker.js.map

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

package/dist/bus.d.ts

@@ -0,0 +1,142 @@
+import { EventEmitter } from 'events';
+import { type RelayedFrame } from '@source-repo/rpc';
+/**
+ * The traffic tap: what the broker is relaying, turned on while it runs.
+ *
+ * A console can only ever see its own calls and the events it subscribed to, which on a real
+ * network is a small fraction of what is happening. The broker sees everything by definition - it
+ * is the thing forwarding it - so this is where the rest becomes visible.
+ *
+ * **It is turned on by a call, not by a flag.** A plant bus that has to be restarted to be observed
+ * will not be observed: the run you want to look at is the one already going wrong. The cost of
+ * that decision is that the broker now exposes something, where it used to expose nothing at all
+ * and answer ClassNotFound to anyone who addressed it - see the note in broker.ts.
+ *
+ * What this offers over pointing a generic MQTT monitor at the same wire is that it knows what a
+ * frame *is*. A call and its reply share a correlation id, so they can be paired and the reply
+ * reported with the time it took and the method it answers - neither of which is in the reply
+ * itself. A topic browser shows you a MsgPack blob; this shows you
+ * `plantServer.plant.writeSetpoint(1200) -> ok 42ms`.
+ */
+/** What a tap asks to be shown. Everything is optional; a tap with no filter sees all of it. */
+export interface TapFilter {
+    /** Only frames this peer sent or received - "mirror that device", which is the usual request. */
+    peer?: string;
+    /** Only this namespace. Applies to replies too, since a reply is paired with its call first. */
+    namespace?: string;
+    /** Only these kinds: POST, SUCCESS, ERROR, EVENT. */
+    kinds?: string[];
+    /**
+     * Include arguments, results and event payloads.
+     *
+     * Off by default, and deliberately: the metadata is what a debugging session usually needs, and
+     * a plant bus carries values that nobody meant to hand to whoever happened to be tapping.
+     */
+    payloads?: boolean;
+    /**
+     * Seconds before this tap drops itself. A console that closes without untapping would otherwise
+     * leave the broker building and emitting frames for a subscriber that is not there any more.
+     */
+    ttl?: number;
+}
+/** One frame the broker passed between two peers. */
+export interface TappedFrame {
+    at: number;
+    source: string;
+    target: string;
+    /** POST, SUCCESS, ERROR or EVENT. */
+    kind: string;
+    /** The namespace, taken from the call when this is a reply - a reply does not carry one. */
+    namespace?: string;
+    method?: string;
+    event?: string;
+    /** Correlation id, so a call and its reply can be lined up by whoever is reading. */
+    id?: string;
+    /** Milliseconds since the call this answers, when that call was seen. */
+    ms?: number;
+    /** The error code on a refused call. */
+    code?: string;
+    error?: string;
+    /** Only when a matching tap asked for payloads. */
+    params?: unknown[];
+    result?: unknown;
+    /** Which taps this frame matched, so several people can watch with different filters at once. */
+    taps: string[];
+}
+export interface TapRecord {
+    token: string;
+    filter: TapFilter;
+    /** Epoch milliseconds. */
+    expires: number;
+    frames: number;
+}
+/** Exported so the console can give its own record of a tap the same life as the tap itself. */
+export declare const DEFAULT_TAP_TTL = 300;
+export declare class BusService extends EventEmitter {
+    /** Named in what `taps()` reports, so a reader knows which broker they are looking at. */
+    private readonly busName;
+    rpcEvents: {
+        frame: [frame: TappedFrame];
+    };
+    private readonly active;
+    /** Calls seen and not yet answered, so a reply can be given the time it took and the method. */
+    private readonly pending;
+    private counter;
+    constructor(
+    /** Named in what `taps()` reports, so a reader knows which broker they are looking at. */
+    busName: string);
+    /**
+     * 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?: {
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+    };
+    /**
+     * 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.
+     */
+    private settleSource;
+    /**
+     * Start watching. Returns a token: several people can tap at once with different filters, and
+     * untapping has to remove yours rather than everyone's.
+     */
+    tap(filter?: TapFilter): Promise<{
+        token: string;
+        expires: number;
+        filter: TapFilter;
+    }>;
+    untap(token: string): Promise<{
+        tapping: boolean;
+        already: boolean;
+    }>;
+    /** Who is watching what, including how much each tap has seen. */
+    taps(): Promise<{
+        bus: string;
+        taps: TapRecord[];
+        pending: number;
+    }>;
+    /** Whether anything is listening, so the broker can leave the transport hook unattached. */
+    get tapping(): boolean;
+    private expire;
+    /**
+     * 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: RelayedFrame): void;
+    private matches;
+    private readFrame;
+    /** Fills in what a reply does not carry: the method it answers, and how long it took. */
+    private pair;
+    /** Drops every tap, so a broker shutting down stops building frames for nobody. */
+    releaseAll(): Promise<void>;
+}
+//# sourceMappingURL=bus.d.ts.map

package/dist/bus.d.ts.map

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