@source-repo/rpc 3.0.0

package/dist/RPC/Core.d.ts

@@ -0,0 +1,188 @@
+import { EventEmitter } from 'events';
+import { RpcIdentity } from './Auth.js';
+import { FrameCodec } from './Codec.js';
+/**
+ * Upper bound on the framed header, in bytes, including the delimiter.
+ *
+ * It has to fit the largest header this library builds: two 128-character peer names, a timestamp,
+ * a sequence number, a hop count, a 24-character nonce and an 88-character Ed25519 signature come
+ * to roughly 470 bytes. The old value of 256 was under that, and since the receiver stopped looking
+ * for the delimiter at the limit, every frame with a header past it was dropped without a word -
+ * signed frames from peers whose names were merely descriptive, at around 34 characters each.
+ */
+export declare const MAX_HEADER_LENGTH = 1024;
+export declare const HEADER_DELIMITER = "$";
+/**
+ * Lifecycle events emitted by transports. Transports are EventEmitters, so anything above them
+ * can react to the link coming and going rather than discovering it via a call timeout.
+ *
+ * connected/disconnected are emitted by client-side transports on every transition, including
+ * reconnects. peerGone is emitted by server-side transports when an identified peer's connection
+ * drops, and peerOnline when one announces itself, which is how a peer is discovered at all.
+ * rejected is emitted when an inbound frame fails an authentication check. unroutable is emitted
+ * when a frame cannot be delivered to its target. peerDisplaced is emitted when a new connection
+ * announces a name another live connection already holds, and takes the route over.
+ *
+ * relayed is the one that is not about the link: it reports a frame this server is passing between
+ * two other peers, which is the only place traffic nobody here sent or received can be observed.
+ * It fires once per relayed frame, so it is emitted only when something is listening - see the
+ * guard at the call site.
+ */
+export declare const TransportEvent: {
+    readonly connected: 'connected';
+    readonly disconnected: 'disconnected';
+    readonly peerOnline: 'peerOnline';
+    readonly peerGone: 'peerGone';
+    readonly peerDisplaced: 'peerDisplaced';
+    readonly rejected: 'rejected';
+    readonly unroutable: 'unroutable';
+    readonly transportError: 'transportError';
+    readonly relayed: 'relayed';
+};
+/** A frame passing through this server on its way between two other peers. */
+export interface RelayedFrame {
+    source: string;
+    target: string;
+    message: Message;
+}
+export interface IGenericModule<I = unknown, IP = unknown, O = unknown, OP = unknown> {
+    readyFlag: boolean;
+    pipe(target: IGenericModule): void;
+    receive(message: I, source: string, target?: string): Promise<void>;
+    receivePayload(payload: IP, source: string, target?: string): Promise<void>;
+    send(message: O, source: string, target?: string): Promise<void>;
+    sendPayload(payload: OP, messageType: MessageType, source: string, target?: string): Promise<void>;
+    ready(): Promise<boolean>;
+    getName(): string;
+    targetExists(name: string, level?: number): IGenericModule | undefined;
+    isTransport(): boolean;
+    close(): Promise<void>;
+}
+/**
+ * Which module a peer name was last seen on, so a reply can be routed back out of the transport
+ * its request arrived on.
+ *
+ * This was a static on GenericModule, which meant every client and server in one process shared a
+ * single map keyed by names supplied by remote peers. Two graphs using the same peer name routed
+ * into each other's transports, entries were never removed, and it grew for the life of the
+ * process. One registry is now shared by one connected set of modules and nothing wider.
+ */
+export declare class PeerRegistry {
+    /** Upper bound, since the keys come off the wire. Least recently seen entries go first. */
+    maxPeers: number;
+    private peers;
+    constructor(
+    /** Upper bound, since the keys come off the wire. Least recently seen entries go first. */
+    maxPeers?: number);
+    set(source: string, module: IGenericModule): void;
+    get(source: string): IGenericModule<unknown, unknown, unknown, unknown> | undefined;
+    delete(source: string): boolean;
+    clear(): void;
+    get size(): number;
+    /** Every peer currently routed through one module, which is how a bridge lists what it can reach. */
+    namesFor(module: IGenericModule): string[];
+    names(): string[];
+}
+/**
+ * A module that owns its wire format. RpcClient and RpcServer drive these directly rather than
+ * through a converter, so a transport whose framing is structured can see the message itself.
+ */
+export type Transport = GenericModule<Message, unknown, Message, unknown> & {
+    codec: FrameCodec;
+};
+export interface MessageHeader {
+    source: string;
+    target: string;
+    time: number;
+    seq: number;
+    /** How many relays this frame has already passed through. Absent means none. */
+    hops?: number;
+    /** Present on signed frames: single-use value that makes a captured frame unreplayable. */
+    nonce?: string;
+    /** Present on signed frames: base64 signature over the fields above plus the payload. */
+    sig?: string;
+}
+export declare class GenericModule<I = unknown, IP = unknown, O = unknown, OP = unknown> extends EventEmitter implements IGenericModule<I, IP, O, OP> {
+    name: string;
+    destinations: {
+        id: string;
+        target: IGenericModule;
+    }[];
+    /**
+     * Shared with the other modules in this graph by usePeerRegistry(). A module built on its own
+     * gets a private one, so it still routes correctly without leaking into anyone else's.
+     */
+    peerRegistry: PeerRegistry;
+    readyFlag: boolean;
+    seq: number;
+    constructor(name: string, sources?: IGenericModule<unknown, unknown, I, IP>[]);
+    /**
+     * Waits for this module to come up, and gives up rather than waiting forever.
+     *
+     * The loop used to have no way out: a module that never became ready - one that failed to
+     * start, or was closed while something still awaited it - spun on a 10 ms timer for the life of
+     * the process, which is also long enough to keep the process alive with nothing left to do.
+     * Returning false says what happened; the overrides in RpcClient and RpcServer throw with the
+     * startup error instead, which is more than a bare module knows.
+     */
+    ready(timeout?: number): Promise<boolean>;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Build the header a frame will carry. Separate from framing so a transport that signs can
+     * see the exact field values before they are serialised, and add its signature to them.
+     */
+    buildHeader(source: string, target: string, extra?: Partial<MessageHeader>): MessageHeader;
+    prependHeader(source: string, target: string, message: string | Uint8Array): string | Uint8Array;
+    /**
+     * Throws when the header will not fit the frame, rather than emitting one no receiver can read.
+     * The sender is the only party that can do anything about an over-long peer name, and it learns
+     * nothing from a frame that leaves correctly and is discarded at the far end.
+     */
+    frameMessage(header: MessageHeader, message: string | Uint8Array): string | Uint8Array;
+    /**
+     * Split a frame into its header and payload. Never throws: every frame here came off the
+     * network, and one malformed frame from one peer must not take down a process serving the rest.
+     * The third element says why nothing was extracted, so a dropped frame can be diagnosed instead
+     * of merely disappearing.
+     */
+    extractHeader(message: string | Uint8Array): [MessageHeader | undefined, string | Uint8Array, string?];
+    getName(): string;
+    targetExists(name: string, level?: number): IGenericModule<unknown, unknown, unknown, unknown> | undefined;
+    pipe(target: IGenericModule<O, OP, unknown, unknown>): () => void;
+    receive(message: I, source: string, target: string): Promise<void>;
+    receivePayload(message: IP, source: string, target: string): Promise<void>;
+    send(message: O, source: string, target: string): Promise<void>;
+    setKnownSource(source: string): void;
+    /** Route peer lookups for this module through a registry shared with the rest of its graph. */
+    usePeerRegistry(registry: PeerRegistry): this;
+    /**
+     * The authenticated identity bound to a peer name, for transports that authenticate.
+     * Undefined means this transport cannot vouch for the peer, not that the peer is untrusted.
+     */
+    getIdentity(source: string): RpcIdentity | undefined;
+    sendPayload(payload: OP, messageType: MessageType, source: string, target: string): Promise<void>;
+    isTransport(): boolean;
+}
+export declare enum MessageType {
+    RequestMessage = "REQUEST",
+    ResponseMessage = "RESPONSE",
+    ErrorMessage = "ERROR",
+    EventMessage = "EVENT",
+    UnknownMessage = "UNKNOWN"
+}
+export interface Payload {
+}
+export declare class Message<P = Payload> {
+    type?: MessageType;
+    payload?: P;
+}
+export declare class MessageModule<I extends Message<IP>, IP extends Payload, O extends Message<OP>, OP extends Payload> extends GenericModule<I, IP, O, OP> {
+    name: string;
+    constructor(name: string, sources?: IGenericModule<Message, unknown, I, IP>[]);
+    pipe(target: IGenericModule<O, OP, Message, unknown>): () => void;
+    receive(message: I, source: string, target: string): Promise<void>;
+    send(message: O, source: string, target?: string): Promise<void>;
+    sendPayload(payload: OP, messageType: MessageType, source: string, target?: string): Promise<void>;
+}
+//# sourceMappingURL=Core.d.ts.map

package/dist/RPC/Core.d.ts.map

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

package/dist/RPC/Core.js

@@ -0,0 +1,354 @@
+import { EventEmitter } from 'events';
+import { stringToUint8Array, uint8ArrayToString } from 'uint8array-extras';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Upper bound on the framed header, in bytes, including the delimiter.
+ *
+ * It has to fit the largest header this library builds: two 128-character peer names, a timestamp,
+ * a sequence number, a hop count, a 24-character nonce and an 88-character Ed25519 signature come
+ * to roughly 470 bytes. The old value of 256 was under that, and since the receiver stopped looking
+ * for the delimiter at the limit, every frame with a header past it was dropped without a word -
+ * signed frames from peers whose names were merely descriptive, at around 34 characters each.
+ */
+export const MAX_HEADER_LENGTH = 1024;
+export const HEADER_DELIMITER = '$';
+const CHAR = { openBrace: 0x7b, closeBrace: 0x7d, quote: 0x22, backslash: 0x5c, delimiter: 0x24 };
+/**
+ * Index of the delimiter that ends the header, or -1 when there is no header to be found.
+ *
+ * Deliberately not indexOf('$'): the header is JSON, and a peer name containing a '$' puts one
+ * inside a quoted string where it is data rather than punctuation. Splitting on the first one cut
+ * the header mid-string, and the JSON.parse that followed threw - on the MQTT path, into an
+ * unhandled rejection. Reading with JSON's own quoting rules makes the split unambiguous, so a name
+ * can never reshape the frame it travels in.
+ *
+ * Scans code units rather than decoded text because every character it looks for is ASCII, and
+ * UTF-8 never produces those bytes inside a multi-byte sequence. A payload cut mid-character
+ * therefore cannot confuse it, which the previous decode-the-first-256-bytes approach could.
+ */
+const findHeaderEnd = (at, length) => {
+    if (length === 0 || at(0) !== CHAR.openBrace)
+        return -1;
+    const limit = Math.min(length, MAX_HEADER_LENGTH);
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < limit; index++) {
+        const code = at(index);
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (code === CHAR.backslash)
+                escaped = true;
+            else if (code === CHAR.quote)
+                inString = false;
+            continue;
+        }
+        if (code === CHAR.quote)
+            inString = true;
+        else if (code === CHAR.openBrace)
+            depth++;
+        else if (code === CHAR.closeBrace && --depth === 0) {
+            // The delimiter has to be the very next byte, or this is not a framed message.
+            const delimiter = index + 1;
+            return delimiter < limit && at(delimiter) === CHAR.delimiter ? delimiter : -1;
+        }
+    }
+    return -1;
+};
+/**
+ * Lifecycle events emitted by transports. Transports are EventEmitters, so anything above them
+ * can react to the link coming and going rather than discovering it via a call timeout.
+ *
+ * connected/disconnected are emitted by client-side transports on every transition, including
+ * reconnects. peerGone is emitted by server-side transports when an identified peer's connection
+ * drops, and peerOnline when one announces itself, which is how a peer is discovered at all.
+ * rejected is emitted when an inbound frame fails an authentication check. unroutable is emitted
+ * when a frame cannot be delivered to its target. peerDisplaced is emitted when a new connection
+ * announces a name another live connection already holds, and takes the route over.
+ *
+ * relayed is the one that is not about the link: it reports a frame this server is passing between
+ * two other peers, which is the only place traffic nobody here sent or received can be observed.
+ * It fires once per relayed frame, so it is emitted only when something is listening - see the
+ * guard at the call site.
+ */
+export const TransportEvent = {
+    connected: 'connected',
+    disconnected: 'disconnected',
+    peerOnline: 'peerOnline',
+    peerGone: 'peerGone',
+    peerDisplaced: 'peerDisplaced',
+    rejected: 'rejected',
+    unroutable: 'unroutable',
+    transportError: 'transportError',
+    relayed: 'relayed'
+};
+/**
+ * Which module a peer name was last seen on, so a reply can be routed back out of the transport
+ * its request arrived on.
+ *
+ * This was a static on GenericModule, which meant every client and server in one process shared a
+ * single map keyed by names supplied by remote peers. Two graphs using the same peer name routed
+ * into each other's transports, entries were never removed, and it grew for the life of the
+ * process. One registry is now shared by one connected set of modules and nothing wider.
+ */
+export class PeerRegistry {
+    maxPeers;
+    peers = new Map();
+    constructor(
+    /** Upper bound, since the keys come off the wire. Least recently seen entries go first. */
+    maxPeers = 10000) {
+        this.maxPeers = maxPeers;
+    }
+    set(source, module) {
+        // Re-inserting moves the entry to the end, which is what makes eviction least-recent-first.
+        this.peers.delete(source);
+        this.peers.set(source, module);
+        while (this.peers.size > this.maxPeers) {
+            const oldest = this.peers.keys().next();
+            if (oldest.done)
+                break;
+            this.peers.delete(oldest.value);
+        }
+    }
+    get(source) {
+        return this.peers.get(source);
+    }
+    delete(source) {
+        return this.peers.delete(source);
+    }
+    clear() {
+        this.peers.clear();
+    }
+    get size() {
+        return this.peers.size;
+    }
+    /** Every peer currently routed through one module, which is how a bridge lists what it can reach. */
+    namesFor(module) {
+        const result = [];
+        for (const [name, carrier] of this.peers)
+            if (carrier === module)
+                result.push(name);
+        return result;
+    }
+    names() {
+        return [...this.peers.keys()];
+    }
+}
+export class GenericModule extends EventEmitter {
+    name;
+    destinations = [];
+    /**
+     * Shared with the other modules in this graph by usePeerRegistry(). A module built on its own
+     * gets a private one, so it still routes correctly without leaking into anyone else's.
+     */
+    peerRegistry = new PeerRegistry();
+    readyFlag = false;
+    seq = 0;
+    constructor(name, sources) {
+        super();
+        this.name = name;
+        if (!name)
+            this.name = uuidv4();
+        if (sources) {
+            sources.forEach((src) => {
+                src.pipe(this);
+            });
+        }
+    }
+    /**
+     * Waits for this module to come up, and gives up rather than waiting forever.
+     *
+     * The loop used to have no way out: a module that never became ready - one that failed to
+     * start, or was closed while something still awaited it - spun on a 10 ms timer for the life of
+     * the process, which is also long enough to keep the process alive with nothing left to do.
+     * Returning false says what happened; the overrides in RpcClient and RpcServer throw with the
+     * startup error instead, which is more than a bare module knows.
+     */
+    async ready(timeout = 30000) {
+        const deadline = Date.now() + timeout;
+        while (!this.readyFlag) {
+            if (Date.now() > deadline)
+                return false;
+            await new Promise((res) => setTimeout(res, 10));
+        }
+        return true;
+    }
+    async open() { }
+    async close() { }
+    /**
+     * Build the header a frame will carry. Separate from framing so a transport that signs can
+     * see the exact field values before they are serialised, and add its signature to them.
+     */
+    buildHeader(source, target, extra) {
+        return { source, target, time: Date.now(), seq: this.seq++, ...extra };
+    }
+    prependHeader(source, target, message) {
+        return this.frameMessage(this.buildHeader(source, target), message);
+    }
+    /**
+     * Throws when the header will not fit the frame, rather than emitting one no receiver can read.
+     * The sender is the only party that can do anything about an over-long peer name, and it learns
+     * nothing from a frame that leaves correctly and is discarded at the far end.
+     */
+    frameMessage(header, message) {
+        const headerText = JSON.stringify(header) + HEADER_DELIMITER;
+        const headerBuffer = stringToUint8Array(headerText);
+        if (headerBuffer.length > MAX_HEADER_LENGTH)
+            throw new Error(`message header is ${headerBuffer.length} bytes, over the ${MAX_HEADER_LENGTH} byte limit ` +
+                `(source '${header.source}', target '${header.target}') - shorten the peer names`);
+        if (typeof message === 'string')
+            return headerText + message;
+        const result = new Uint8Array(headerBuffer.length + message.length);
+        result.set(headerBuffer, 0);
+        result.set(message, headerBuffer.length);
+        return result;
+    }
+    /**
+     * Split a frame into its header and payload. Never throws: every frame here came off the
+     * network, and one malformed frame from one peer must not take down a process serving the rest.
+     * The third element says why nothing was extracted, so a dropped frame can be diagnosed instead
+     * of merely disappearing.
+     */
+    extractHeader(message) {
+        const isText = typeof message === 'string';
+        const end = isText
+            ? findHeaderEnd((index) => message.charCodeAt(index), message.length)
+            : findHeaderEnd((index) => message[index], message.length);
+        if (end < 0)
+            return [undefined, '', 'no msgrpc header'];
+        const headerText = isText ? message.substring(0, end) : uint8ArrayToString(message.subarray(0, end));
+        let header;
+        try {
+            header = JSON.parse(headerText);
+        }
+        catch (e) {
+            return [undefined, '', `unparsable header: ${String(e)}`];
+        }
+        if (!header || typeof header !== 'object')
+            return [undefined, '', 'header is not an object'];
+        if (typeof header.target !== 'string' || !header.target)
+            return [undefined, '', 'header names no target'];
+        if (typeof header.source !== 'string' || !header.source)
+            return [undefined, '', 'header names no source'];
+        const start = end + HEADER_DELIMITER.length;
+        // Copied rather than viewed: the MQTT path hands us a view over a pooled Node Buffer, which
+        // is reused for the next packet the moment this one returns.
+        const payload = isText ? message.substring(start) : message.slice(start);
+        this.setKnownSource(header.source);
+        return [header, payload];
+    }
+    getName() {
+        return this.name;
+    }
+    targetExists(name, level) {
+        let result;
+        if (this.name === name) {
+            result = this;
+        }
+        const knownPeer = this.peerRegistry.get(name);
+        if (knownPeer)
+            result = knownPeer;
+        if (!result) {
+            this.destinations.map((dest) => {
+                if (!result && !dest.target.isTransport() && dest.target.targetExists(name, (level ? level : 0) + 1))
+                    result = dest.target;
+            });
+        }
+        return result;
+    }
+    pipe(target) {
+        const id = uuidv4();
+        this.destinations.push({ id, target });
+        return () => {
+            this.destinations = this.destinations.filter((el) => el.id !== id);
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async receive(message, source, target) {
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async receivePayload(message, source, target) {
+        return;
+    }
+    async send(message, source, target) {
+        await Promise.all(this.destinations.map(async (dest) => {
+            return await dest.target.receive(message, source, target);
+        }));
+    }
+    setKnownSource(source) {
+        this.peerRegistry.set(source, this);
+    }
+    /** Route peer lookups for this module through a registry shared with the rest of its graph. */
+    usePeerRegistry(registry) {
+        this.peerRegistry = registry;
+        return this;
+    }
+    /**
+     * The authenticated identity bound to a peer name, for transports that authenticate.
+     * Undefined means this transport cannot vouch for the peer, not that the peer is untrusted.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    getIdentity(source) {
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async sendPayload(payload, messageType, source, target) { }
+    isTransport() {
+        return false;
+    }
+}
+export var MessageType;
+(function (MessageType) {
+    MessageType["RequestMessage"] = "REQUEST";
+    MessageType["ResponseMessage"] = "RESPONSE";
+    MessageType["ErrorMessage"] = "ERROR";
+    MessageType["EventMessage"] = "EVENT";
+    MessageType["UnknownMessage"] = "UNKNOWN";
+})(MessageType || (MessageType = {}));
+export class Message {
+    type;
+    payload;
+}
+const makeMessage = (payload, source, target, messageType) => {
+    const result = new Message();
+    result.type = messageType ? messageType : MessageType.UnknownMessage;
+    result.payload = payload;
+    return result;
+};
+export class MessageModule extends GenericModule {
+    name;
+    constructor(name, sources) {
+        super(name);
+        this.name = name;
+        if (!name)
+            this.name = uuidv4();
+        if (sources) {
+            sources.forEach((src) => {
+                src.pipe(this);
+            });
+        }
+    }
+    pipe(target) {
+        const id = uuidv4();
+        this.destinations.push({ id, target });
+        return () => {
+            this.destinations = this.destinations.filter((el) => el.id !== id);
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    receive(message, source, target) {
+        return Promise.resolve();
+    }
+    async send(message, source, target) {
+        await Promise.all(this.destinations.map(async (dest) => {
+            return await dest.target.receive(message, source, target);
+        }));
+    }
+    async sendPayload(payload, messageType, source, target) {
+        const message = makeMessage(payload, this.name, target, messageType);
+        await this.send(message, source, target);
+    }
+}
+//# sourceMappingURL=Core.js.map

package/dist/RPC/Core.js.map

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

package/dist/RPC/Expose.d.ts

@@ -0,0 +1,90 @@
+import type { RpcCallContext } from './Auth.js';
+import type { RpcMethodSemantics } from './Messages.js';
+/**
+ * How calls into one exposed instance may overlap.
+ *
+ * `parallel` is the default and has always been the behaviour: calls run as they arrive, which is
+ * right for stateless services and for unrelated devices behind one server. It is not right for a
+ * long-lived object holding mutable state, where `setMode('manual'); start(); setSetpoint(80)` from
+ * one caller can interleave with `stop(); setMode('automatic')` from another and leave a machine in
+ * a combination neither of them asked for.
+ *
+ * `serial` runs one call at a time per exposed instance. A function instead runs one call at a time
+ * per key it returns, which is how a server fronting many devices keeps each device's commands in
+ * order without serialising the whole server behind the slowest one.
+ *
+ * **A serial instance must not call back into itself over RPC.** The second call queues behind the
+ * first, which is waiting for it, and neither ever runs. That is why `parallel` remains the default
+ * rather than the safer-sounding option: serialising by default would deadlock re-entrant designs
+ * that work today, silently and only under load.
+ */
+export type RpcExecution = 'parallel' | 'serial' | ((context: RpcCallContext) => string);
+export interface RpcMethodOptions {
+    /**
+     * What this method does to the world: `query`, `idempotent-command` or
+     * `non-repeatable-command`. Read by a caller deciding whether an uncertain answer may be
+     * retried, and by the server deciding whether to consult a durable idempotency store.
+     */
+    semantics?: RpcMethodSemantics;
+}
+type RpcMethodDecorator<This, Args extends unknown[], Return> = (target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => void;
+/**
+ * Marks a method as remotely callable, and optionally says what it does to the world.
+ *
+ * ```typescript
+ * class Plant {
+ *     @rpc async readSetpoint() { ... }                                    // marked, nothing declared
+ *     @rpc({ semantics: 'idempotent-command' }) async writeSetpoint(v: number) { ... }
+ *     @rpc({ semantics: 'non-repeatable-command' }) async advanceBatch() { ... }
+ *     private recompute() { ... }                                          // unmarked, so unreachable
+ * }
+ * ```
+ *
+ * Both spellings are the same decorator: bare `@rpc` where there is nothing to say, and `@rpc({…})`
+ * where there is. A standard ECMAScript decorator either way, so no experimentalDecorators is
+ * needed, and the mark is recorded per instance at construction, which is when the RPC layer needs
+ * it.
+ */
+export declare function rpc<This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>): void;
+export declare function rpc<This, Args extends unknown[], Return>(options: RpcMethodOptions): RpcMethodDecorator<This, Args, Return>;
+/**
+ * Marks methods without decorators, for JavaScript callers or code that prefers not to use them.
+ * Names that are not functions on the prototype are rejected, since a typo would silently expose
+ * nothing.
+ */
+export declare const exposeMethods: <T>(constructor: new (...args: never[]) => T, methods: string[]) => new (...args: never[]) => T;
+export interface DeclaredNamespace {
+    name: string;
+    version?: string;
+    execution?: RpcExecution;
+}
+/**
+ * Declares the name a class is exposed under, and optionally the version of its contract and how
+ * its calls may overlap.
+ *
+ * The exposure name only existed at the call site - `exposeClassInstance(instance, 'plant')` - so
+ * nothing reading the source could tell which namespace a class belongs to. Declaring it here lets
+ * the extraction CLI key a schema correctly, and lets exposeClassInstance take the name as read.
+ *
+ * ```typescript
+ * @rpcNamespace('plant', { version: '3', execution: 'serial' })
+ * class Plant { @rpc async writeSetpoint(value: number) { ... } }
+ * ```
+ */
+export declare const rpcNamespace: (name: string, options?: {
+    version?: string;
+    execution?: RpcExecution;
+}) => <T extends abstract new (...args: never[]) => unknown>(target: T, _context: ClassDecoratorContext) => T;
+/** The namespace an instance's class declares, walking up so a subclass inherits it. */
+export declare const declaredNamespace: (instance: object) => DeclaredNamespace | undefined;
+/** The marked method names for an instance, or undefined when the class marks nothing. */
+export declare const markedMethods: (instance: object) => Set<string> | undefined;
+/**
+ * The semantics an instance's methods declare, walking the chain so a subclass inherits them.
+ *
+ * A subclass that redeclares wins, which is why the nearest constructor is consulted first: an
+ * override that turns a query into a command has to be able to say so.
+ */
+export declare const declaredSemantics: (instance: object) => Map<string, RpcMethodSemantics>;
+export {};
+//# sourceMappingURL=Expose.d.ts.map

package/dist/RPC/Expose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expose.d.ts","sourceRoot":"","sources":["../../src/RPC/Expose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,CAAC,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,CAAC,CAAA;AA4BxF,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAA;CACjC;AAED,KAAK,kBAAkB,CAAC,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,IAAI,CAC5D,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC7C,OAAO,EAAE,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,KAChF,IAAI,CAAA;AAaT;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACpD,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC7C,OAAO,EAAE,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,GAClF,IAAI,CAAA;AACP,wBAAgB,GAAG,CAAC,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;AAY5H;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,eAAe,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,MAAM,EAAE,mBAAhC,KAAK,EAAE,KAAK,CAOvE,CAAA;AAKD,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,SACd,MAAM,YAAW;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,MACrE,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,UAAU,CAAC,YAAY,qBAAqB,MAGhG,CAAA;AAEL,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,aAAc,MAAM,kCAMjD,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,aAAc,MAAM,KAAG,GAAG,CAAC,MAAM,CAAC,GAAG,SAO9D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,KAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAMlF,CAAA"}