@source-repo/rpc 3.0.0

package/dist/RPC/RpcServerHandler.js

@@ -0,0 +1,676 @@
+import { MessageModule, MessageType } from './Core.js';
+import { RpcMessageType, toRemoteError } from './Messages.js';
+export * from './Messages.js';
+import { v4 as uuidv4 } from 'uuid';
+import { isFailedOutcome } from './Idempotency.js';
+import EventEmitter from 'events';
+import { declaredNamespace, declaredSemantics, markedMethods } from './Expose.js';
+import { validateParams, validateValue } from './Schema.js';
+import { describeProblems, namespaceProblems } from './Compatibility.js';
+export class EventProxy {
+    rpcServer;
+    instance;
+    event;
+    target;
+    instanceName;
+    /**
+     * Held so the listener can be removed again. Binding at registration time produced a fresh
+     * function that removeListener() could never match.
+     */
+    listener = (...args) => {
+        // Caught here, because an emit is not a call: nothing above this is awaiting the delivery,
+        // so a transport that cannot publish - a broker that has gone away, most obviously - would
+        // otherwise reject a promise nobody holds, and Node ends the process on one of those.
+        void this.rpcServer.sendEvent(this.target, this.event, args, this.instanceName).catch((e) => this.rpcServer.emit('deliveryError', { target: this.target, event: this.event, path: this.instanceName, error: e }));
+    };
+    constructor(rpcServer, instance, event, target, instanceName) {
+        this.rpcServer = rpcServer;
+        this.instance = instance;
+        this.event = event;
+        this.target = target;
+        this.instanceName = instanceName;
+    }
+    attach() {
+        this.instance.on(this.event, this.listener);
+    }
+    detach() {
+        this.instance.removeListener(this.event, this.listener);
+    }
+}
+/**
+ * Identifies one subscription. Previously a Map keyed by a freshly allocated object literal, so
+ * lookups compared by reference and never matched - every repeated on() stacked another listener.
+ */
+const eventProxyKey = (instanceName, event, source) => `${instanceName}\u0000${event}\u0000${source}`;
+const isRpcCallInstanceMethodPayload = (payload) => {
+    return payload.type === RpcMessageType.CallInstanceMethod;
+};
+/**
+ * The codes a method may answer with by throwing an error that carries one.
+ *
+ * Everything a method threw used to come back as `Exception`, so a service that wanted to say
+ * "you may not do that" could say it only in the message - and a caller reading `code` to decide
+ * whether to retry, re-authenticate or give up learned nothing. Restricted to the codes the
+ * protocol already defines, so an error carrying an unrelated `code` - a Node `ENOENT`, say - is
+ * still reported as the exception it is.
+ */
+const CHOSEN_CODES = new Set([
+    'Unauthorized',
+    'Forbidden',
+    'InvalidParams',
+    'IncompatibleVersion',
+    'ClassNotFound',
+    'MethodNotFound',
+    'TransportError',
+    'Timeout',
+    // A method that talked to something else and did not learn the answer may say so. It is the
+    // honest reply from a gateway whose own downstream call timed out, and inventing a result or
+    // reporting a plain exception would both claim more than is known.
+    'UnknownOutcome'
+]);
+const chosenCode = (e) => {
+    const code = e?.code;
+    return typeof code === 'string' && CHOSEN_CODES.has(code) ? code : 'Exception';
+};
+export class RpcServerHandler extends MessageModule {
+    manageRpc = new ManageRpc();
+    eventProxies = new Map();
+    /** Decides whether a call may proceed. When unset, every call that resolves is allowed. */
+    authorize;
+    /** Supplied by RpcServer; asks the transports which identity a peer name is bound to. */
+    resolveIdentity;
+    /** Reject calls from peers no transport can vouch for. */
+    requireIdentity = false;
+    /**
+     * Suppress duplicate requests. MQTT at QoS 1 is at-least-once, so the same request can be
+     * delivered twice; without this a retransmission would run the method a second time, which is
+     * not something a caller can undo. A duplicate is answered from the cache instead.
+     */
+    deduplicateRequests = true;
+    /** How many recent request ids to remember. Oldest are evicted first. */
+    maxTrackedRequests = 1000;
+    /**
+     * Refuse a call whose caller has already stopped waiting for it, instead of running it late.
+     *
+     * A request carries the milliseconds its caller intended to wait, and that budget is counted
+     * from the moment this process received the frame. A read arriving late only wastes work; a
+     * command does not - the operator saw a timeout, did something else about it, and then the
+     * original 'start pump' runs anyway. On by default, because that outcome is worse than the
+     * failed call it replaces.
+     */
+    refuseExpiredCalls = true;
+    /**
+     * Where to record what a non-repeatable command did, so a redelivery after a crash is answered
+     * rather than executed a second time. Unset means execution is at least once - see
+     * RPC/Idempotency.ts, which spells out exactly what that leaves open.
+     */
+    idempotency;
+    /** Describes what exposed methods accept. Absent means nothing is checked. */
+    schema;
+    /**
+     * 'described' checks calls into namespaces the schema covers and lets the rest through, so a
+     * partial schema is useful. 'required' refuses anything the schema does not describe.
+     */
+    validation = 'described';
+    /** Check what handlers return as well as what callers send. Off by default: it is a self-check. */
+    validateResults = false;
+    /**
+     * What to do with a caller declaring a contract version this schema has no history for.
+     * 'allow' by default, because truncating history is a legitimate operational choice and should
+     * not strand peers.
+     */
+    unknownVersion = 'allow';
+    /** Verdicts by namespace and declared version, so the comparison runs once per peer, not per call. */
+    compatibility = new Map();
+    recentResponses = new Map();
+    inFlightRequests = new Set();
+    constructor(name, sources) {
+        super(name, sources);
+        this.manageRpc.logger?.log('Information', 'RpcServerHandler {name} starting', { name });
+    }
+    /**
+     * Gate a call before it reaches an exposed method. Returns an error code to reject with, or
+     * undefined to allow. Subscriptions go through here too: without that, anyone could attach to
+     * an instance's events and receive everything it emits.
+     */
+    async checkAccess(payload, source, subscription) {
+        const identity = this.resolveIdentity?.(source);
+        if (this.requireIdentity && !identity)
+            return 'Unauthorized';
+        if (!this.authorize)
+            return undefined;
+        const context = {
+            identity,
+            source,
+            instanceName: payload.path,
+            method: payload.method,
+            params: payload.params,
+            subscription
+        };
+        try {
+            return (await this.authorize(context)) ? undefined : 'Forbidden';
+        }
+        catch {
+            // An authorizer that throws denies. Failing open here would turn a bug in the
+            // authorizer into an access-control bypass.
+            return 'Forbidden';
+        }
+    }
+    /**
+     * Returns a reason to refuse the call, or undefined. The namespace's contract version rides
+     * along in the message, because a caller built against an older contract otherwise looks
+     * indistinguishable from one sending plain rubbish.
+     */
+    checkParams(payload) {
+        if (!this.schema || this.validation === 'off')
+            return undefined;
+        const namespace = this.schema.namespaces[payload.path];
+        if (!namespace)
+            return this.validation === 'required' ? `${payload.path} is not described by the schema` : undefined;
+        if (namespace.validate === false)
+            return undefined;
+        const method = namespace.methods[payload.method];
+        if (!method)
+            return this.validation === 'required' ? `${payload.path}.${payload.method} is not described by the schema` : undefined;
+        const failure = validateParams(payload.params, method, this.schema.types);
+        if (!failure)
+            return undefined;
+        return namespace.version ? `${failure} (this server serves ${payload.path}@${namespace.version})` : failure;
+    }
+    /**
+     * Compares the contract a caller declares with the one served here. Only a genuine structural
+     * incompatibility is refused: a caller whose contract still holds keeps working, which is why
+     * this compares schemas rather than gating on a version or a hash being equal.
+     */
+    checkVersion(payload) {
+        if (!this.schema || this.validation === 'off' || !payload.version)
+            return undefined;
+        const namespace = this.schema.namespaces[payload.path];
+        if (!namespace || payload.version === namespace.version)
+            return undefined;
+        const key = `${payload.path}@${payload.version}`;
+        if (this.compatibility.has(key))
+            return this.compatibility.get(key);
+        const previous = namespace.history?.[payload.version];
+        let verdict;
+        if (!previous) {
+            verdict =
+                this.unknownVersion === 'reject'
+                    ? `${payload.path}@${payload.version} is unknown to this server, which serves ${payload.path}@${namespace.version ?? 'an unversioned contract'}`
+                    : undefined;
+        }
+        else {
+            verdict = describeProblems(payload.path, payload.version, namespace.version, namespaceProblems(previous, namespace, this.schema.types));
+        }
+        this.compatibility.set(key, verdict);
+        return verdict;
+    }
+    async receive(message, source, target) {
+        this.manageRpc.logger?.log('Debug', 'RpcServerHandler {name} received message type {type} from {source} to {target}: {message}', {
+            name: this.name,
+            type: message.type,
+            source,
+            target,
+            message: JSON.stringify(message)
+        });
+        // Deliberately not awaited: awaiting would serialise every request arriving on one
+        // connection behind the slowest handler. The catch is what stops an unawaited promise
+        // becoming an unhandled rejection - receivePayload answers the caller itself, so reaching
+        // here at all means even that failed.
+        if (message.payload)
+            void this.receivePayload(message.payload, source, target).catch((e) => this.emit('handlerError', { source, target, error: e }));
+    }
+    /**
+     * Send a response and remember it against its request id, so a redelivered request can be
+     * answered without running the method again.
+     */
+    respond(requestId, source, response, messageType) {
+        if (this.deduplicateRequests) {
+            this.inFlightRequests.delete(requestId);
+            this.recentResponses.set(requestId, response);
+            while (this.recentResponses.size > this.maxTrackedRequests) {
+                const oldest = this.recentResponses.keys().next();
+                if (oldest.done)
+                    break;
+                this.recentResponses.delete(oldest.value);
+            }
+        }
+        return this.sendPayload(response, messageType, this.name, source);
+    }
+    async receivePayload(payload, source, target) {
+        try {
+            await this.dispatch(payload, source, target);
+        }
+        catch (e) {
+            // Anything that escaped dispatch - a transport that could not publish the reply, a
+            // schema check that threw, a bug here - used to be an unhandled rejection, and the
+            // caller learned nothing until its own timeout expired. Tell it what happened instead.
+            await this.reportDispatchFailure(payload, source, e);
+        }
+    }
+    /**
+     * Last resort when dispatch itself failed. Answers the caller if the request can still be
+     * identified, and never throws: the thing that failed may well be the transport this reply
+     * would go out on, and a failure to report a failure has nowhere left to go.
+     */
+    async reportDispatchFailure(payload, source, error) {
+        this.emit('handlerError', { source, payload, error });
+        const id = payload.id;
+        if (!isRpcCallInstanceMethodPayload(payload) || !id)
+            return;
+        if (this.deduplicateRequests)
+            this.inFlightRequests.delete(id);
+        try {
+            await this.sendPayload({ type: RpcMessageType.error, id, code: 'Exception', error: toRemoteError(error) }, MessageType.ErrorMessage, this.name, source);
+        }
+        catch {
+            // The link is gone; the caller's timeout is all that is left.
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async dispatch(payload, source, target) {
+        // Stamped here, on arrival, and by this process's own clock. Comparing the caller's clock
+        // with this one would need the two to agree, which over MQTT they broadly do and from a
+        // browser they do not.
+        const arrived = Date.now();
+        if (isRpcCallInstanceMethodPayload(payload)) {
+            if (this.deduplicateRequests) {
+                const cached = this.recentResponses.get(payload.id);
+                if (cached) {
+                    const messageType = cached.code ? MessageType.ErrorMessage : MessageType.ResponseMessage;
+                    await this.sendPayload(cached, messageType, this.name, source);
+                    return;
+                }
+                // Still running: the original call will answer, so drop the redelivery.
+                if (this.inFlightRequests.has(payload.id))
+                    return;
+                this.inFlightRequests.add(payload.id);
+            }
+            // Deliberately not getNameSpaceMethodMap(): that creates a map on miss, which would let
+            // unknown remote paths grow exposedNameSpaceMethodMaps without bound.
+            const map = this.manageRpc.findNameSpaceMethodMap(payload.path);
+            const handler = map?.get(payload.method);
+            if (!handler) {
+                const instanceName = payload.path;
+                const event = payload.params[0];
+                const inst = this.manageRpc.exposedNameSpaceInstances[instanceName];
+                if (payload.method === 'on' && inst instanceof EventEmitter) {
+                    const denied = await this.checkAccess(payload, source, true);
+                    if (denied) {
+                        await this.sendError(payload.id, source, denied, `not permitted to subscribe to ${payload.path}.${event}`);
+                        return;
+                    }
+                    // Idempotent: a client replaying its subscriptions after a reconnect must not
+                    // stack a second listener for a subscription the server already holds.
+                    const eventKey = eventProxyKey(instanceName, event, source);
+                    let eventProxy = this.eventProxies.get(eventKey);
+                    let result = 'ok - already exists';
+                    if (!eventProxy) {
+                        eventProxy = new EventProxy(this, inst, event, source, instanceName);
+                        this.eventProxies.set(eventKey, eventProxy);
+                        eventProxy.attach();
+                        result = 'ok';
+                    }
+                    await this.respond(payload.id, source, { type: RpcMessageType.success, result, id: payload.id }, MessageType.ResponseMessage);
+                }
+                else if ((payload.method === 'off' || payload.method === 'removeListener') && inst instanceof EventEmitter) {
+                    // Deliberately not authorized. The key includes the caller, so a peer can only
+                    // drop its own subscription, and refusing to let someone stop receiving events
+                    // would be a strange thing to enforce.
+                    const eventKey = eventProxyKey(instanceName, event, source);
+                    const eventProxy = this.eventProxies.get(eventKey);
+                    if (eventProxy) {
+                        eventProxy.detach();
+                        this.eventProxies.delete(eventKey);
+                    }
+                    await this.respond(payload.id, source, { type: RpcMessageType.success, result: eventProxy ? 'ok' : 'ok - was not subscribed', id: payload.id }, MessageType.ResponseMessage);
+                }
+                else
+                    await this.sendError(payload.id, source, map ? 'MethodNotFound' : 'ClassNotFound', `${payload.path}.${payload.method} is not exposed`);
+                return;
+            }
+            const denied = await this.checkAccess(payload, source, false);
+            if (denied) {
+                await this.sendError(payload.id, source, denied, `not permitted to call ${payload.path}.${payload.method}`);
+                return;
+            }
+            // After authorization: no point spending the check on a caller already being refused.
+            const incompatible = this.checkVersion(payload);
+            if (incompatible) {
+                await this.sendError(payload.id, source, 'IncompatibleVersion', incompatible);
+                return;
+            }
+            const invalid = this.checkParams(payload);
+            if (invalid) {
+                await this.sendError(payload.id, source, 'InvalidParams', invalid);
+                return;
+            }
+            // The queue, when this instance asked for one, wraps everything from here on: the
+            // deadline has to be read after waiting in it, since that wait is exactly what it
+            // exists to catch, and a duplicate has to be recognised before a sibling call can start
+            // running the same command alongside it.
+            const key = this.executionKey(payload, source);
+            if (key === undefined)
+                await this.invoke(payload, source, arrived, handler);
+            else
+                await this.serialise(key, () => this.invoke(payload, source, arrived, handler));
+        }
+    }
+    /**
+     * Run one call: check the budget, claim the command, invoke it, answer.
+     *
+     * Split out of dispatch because it is what a serial instance runs one at a time, and because
+     * the order of these four is the whole of the delivery semantics.
+     */
+    async invoke(payload, source, arrived, handler) {
+        const spent = this.expiredBy(payload, arrived);
+        if (spent !== undefined) {
+            await this.sendError(payload.id, source, 'Timeout', `${payload.path}.${payload.method} was not run: its caller stopped waiting ${spent} ms ago`);
+            return;
+        }
+        const invocation = this.invocationFor(payload, source);
+        let claimed = false;
+        if (invocation) {
+            let claim;
+            try {
+                claim = await this.idempotency.begin(invocation);
+            }
+            catch (e) {
+                // Refused rather than run. A store that cannot be reached is the one condition under
+                // which running would risk the double execution it was installed to prevent, and an
+                // operator would rather see a command refused than a pump started twice.
+                await this.sendError(payload.id, source, 'UnknownOutcome', `${payload.path}.${payload.method} was not run: its idempotency store could not be reached (${e instanceof Error ? e.message : String(e)})`);
+                return;
+            }
+            // Somebody else holds this command. They will answer the caller, and two answers to one
+            // request would be worse than waiting for theirs.
+            if (claim === 'in-progress') {
+                this.inFlightRequests.delete(payload.id);
+                return;
+            }
+            if (claim !== 'acquired') {
+                // It already ran. This is what it answered, sent again without running anything.
+                const stored = isFailedOutcome(claim)
+                    ? { type: RpcMessageType.error, id: payload.id, code: claim.code, error: claim.error }
+                    : { type: RpcMessageType.success, id: payload.id, result: claim.result };
+                await this.respond(payload.id, source, stored, stored.type === RpcMessageType.error ? MessageType.ErrorMessage : MessageType.ResponseMessage);
+                return;
+            }
+            claimed = true;
+        }
+        const params = [...payload.params];
+        let result;
+        try {
+            result = await handler(...params);
+            const badResult = this.checkResult(payload, result);
+            if (badResult) {
+                // Recorded as the failure it is: the method ran, so a redelivery must not run it
+                // again just because this server disliked what it returned.
+                await this.settle(invocation, claimed, { code: 'InvalidParams', error: { name: 'RpcError', message: badResult } });
+                await this.sendError(payload.id, source, 'InvalidParams', badResult);
+                return;
+            }
+            await this.settle(invocation, claimed, { result });
+            await this.respond(payload.id, source, { type: RpcMessageType.success, id: payload.id, result }, MessageType.ResponseMessage);
+        }
+        catch (e) {
+            const code = chosenCode(e);
+            await this.settle(invocation, claimed, { code, error: toRemoteError(e) });
+            await this.respond(payload.id, source, { type: RpcMessageType.error, id: payload.id, code, error: toRemoteError(e) }, MessageType.ErrorMessage);
+        }
+    }
+    /**
+     * Write down what the command did, before its answer is sent.
+     *
+     * This order is the one that matters. Recording after answering would leave a window in which
+     * the caller has the result and the store does not, so a redelivery arriving in that window
+     * runs the command again - which is the whole failure this is here to prevent. A store that
+     * cannot record it is reported and the answer still goes out: the command has already run, and
+     * withholding the result would not un-run it.
+     */
+    async settle(invocation, claimed, outcome) {
+        if (!invocation || !claimed)
+            return;
+        try {
+            await this.idempotency.complete(invocation, outcome);
+        }
+        catch (e) {
+            this.emit('idempotencyError', { invocation, outcome, error: e });
+        }
+    }
+    /** The command a call is an attempt at, or undefined when nothing here needs to know. */
+    invocationFor(payload, source) {
+        // Only where a repeat would cost something. A store round trip on every read would be paid
+        // by the calls that least need it.
+        if (!this.idempotency || this.semanticsOf(payload) !== 'non-repeatable-command')
+            return undefined;
+        return {
+            idempotencyKey: payload.idempotencyKey ?? payload.id,
+            requestId: payload.id,
+            scope: `${payload.path}.${payload.method}`,
+            source,
+            ...(payload.ttl !== undefined ? { ttl: payload.ttl } : {})
+        };
+    }
+    /**
+     * What a method says it does to the world: the running class first, then the schema.
+     *
+     * The class wins because it is what will actually run. A schema is a description, and a server
+     * whose description has drifted from its code should act on the code.
+     */
+    semanticsOf(payload) {
+        return this.manageRpc.exposedSemantics[payload.path]?.get(payload.method) ?? this.schema?.namespaces[payload.path]?.methods[payload.method]?.semantics;
+    }
+    /** The queue a call belongs in, or undefined when this instance lets calls overlap. */
+    executionKey(payload, source) {
+        const execution = this.manageRpc.exposedExecution[payload.path];
+        if (!execution || execution === 'parallel')
+            return undefined;
+        if (execution === 'serial')
+            return payload.path;
+        const context = {
+            identity: this.resolveIdentity?.(source),
+            source,
+            instanceName: payload.path,
+            method: payload.method,
+            params: payload.params,
+            subscription: false
+        };
+        try {
+            return `${payload.path}\u0000${execution(context)}`;
+        }
+        catch {
+            // A key function that throws serialises the whole instance rather than letting the call
+            // run unordered. The safe reading of "I cannot tell you which queue" is the strictest one.
+            return payload.path;
+        }
+    }
+    /** One promise chain per key. Entries go away once nothing is waiting, so idle costs nothing. */
+    executionQueues = new Map();
+    async serialise(key, run) {
+        const ahead = this.executionQueues.get(key) ?? Promise.resolve();
+        let release;
+        const mine = new Promise((resolve) => (release = resolve));
+        // The tail is what the next arrival waits behind. It only ever resolves - release() is in a
+        // finally - so a method that throws cannot leave the queue permanently rejected.
+        const tail = ahead.then(() => mine);
+        this.executionQueues.set(key, tail);
+        await ahead;
+        try {
+            return await run();
+        }
+        finally {
+            release();
+            if (this.executionQueues.get(key) === tail)
+                this.executionQueues.delete(key);
+        }
+    }
+    /**
+     * How long ago the caller's budget ran out, or undefined while it still has one.
+     *
+     * The budget starts when the frame arrived here, so it covers the wait in front of this method
+     * and nothing before it. What came before is the transport's to account for: MQTT 5 hands the
+     * broker the same budget as a message expiry, so a request that sat in a queue arrives already
+     * shortened, or does not arrive at all.
+     */
+    expiredBy(payload, arrived) {
+        if (!this.refuseExpiredCalls || payload.ttl === undefined)
+            return undefined;
+        if (!Number.isFinite(payload.ttl) || payload.ttl < 0)
+            return undefined;
+        const overdue = Date.now() - (arrived + payload.ttl);
+        return overdue > 0 ? overdue : undefined;
+    }
+    /** Catches this server returning something its own contract does not allow. */
+    checkResult(payload, result) {
+        if (!this.validateResults || !this.schema)
+            return undefined;
+        const returns = this.schema.namespaces[payload.path]?.methods[payload.method]?.returns;
+        if (!returns)
+            return undefined;
+        const failure = validateValue(result, returns, this.schema.types, 'result');
+        return failure ? `${payload.path}.${payload.method} returned a value its own schema forbids: ${failure}` : undefined;
+    }
+    sendError(id, target, code, message) {
+        return this.respond(id, target, { type: RpcMessageType.error, id, code, error: { name: 'RpcError', message } }, MessageType.ErrorMessage);
+    }
+    /**
+     * Release every event subscription held for a peer that has gone away. Without this the
+     * exposed instance keeps the listener forever and each emit produces an undeliverable frame.
+     */
+    removePeer(source) {
+        for (const [key, eventProxy] of this.eventProxies) {
+            if (eventProxy.target !== source)
+                continue;
+            eventProxy.detach();
+            this.eventProxies.delete(key);
+        }
+    }
+    async sendEvent(target, event, params, path) {
+        return await this.sendPayload({ type: RpcMessageType.event, event, params, path }, MessageType.EventMessage, this.name, target);
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class DummyLogger {
+    log(level, messageTemplate, properties) {
+        console.log(`LEVEL ${level.toString()}, messageTemplate: ${messageTemplate}, properties: "${properties ? JSON.stringify(properties) : '<empty>'}"`);
+    }
+}
+export class ManageRpc {
+    logger;
+    exposedNameSpaceMethodMaps = {};
+    exposedNameSpaceInstances = {};
+    exposedClasses = {};
+    createdInstances = new Map();
+    /** What each exposed namespace's methods declare about repeating them. */
+    exposedSemantics = {};
+    /** How each exposed namespace lets its calls overlap. Absent is `parallel`. */
+    exposedExecution = {};
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Make the management surface callable remotely. Off unless RpcServer is constructed with
+     * exposeManagement, because it is the most dangerous thing this library can offer.
+     *
+     * Only createRpcInstance is published, and only for classes already passed to exposeClass().
+     * The previous behaviour was exposeClassInstance(this, 'manageRpc'), which published every
+     * method on this class - including exposeClassInstance and exposeObject themselves, letting
+     * any peer that could reach the transport publish arbitrary objects and instantiate arbitrary
+     * exposed classes. The logger was published the same way, so anyone could write log entries.
+     */
+    exposeManagement() {
+        const map = this.getNameSpaceMethodMap('manageRpc');
+        map.set('createRpcInstance', (...args) => this.createRpcInstance(args[0], args[1], ...args.slice(2)));
+        this.exposedNameSpaceInstances['manageRpc'] = this;
+    }
+    getNameSpaceMethodMap(name) {
+        let result = this.exposedNameSpaceMethodMaps[name];
+        if (!result) {
+            result = new Map();
+            this.exposedNameSpaceMethodMaps[name] = result;
+        }
+        return result;
+    }
+    /** Look up a namespace without creating one. Use this on paths that came off the wire. */
+    findNameSpaceMethodMap(name) {
+        return this.exposedNameSpaceMethodMaps[name];
+    }
+    /** Set by RpcServer: refuse to expose a class that marks nothing. */
+    requireExplicitExposure = false;
+    exposeClassInstance(instance, name, options) {
+        const declared = declaredNamespace(instance);
+        const namespace = name ?? declared?.name;
+        if (!namespace)
+            throw new Error(`exposeClassInstance: ${instance.constructor.name} declares no @rpcNamespace, so a name is required`);
+        // A bare number is the old third argument, which was prototypeSteps and nothing else.
+        const settings = typeof options === 'number' ? { prototypeSteps: options } : (options ?? {});
+        let prototypeSteps = settings.prototypeSteps;
+        // Marked methods are an allow-list. Without marks every function on the prototype chain is
+        // published, including helpers the class never meant to offer.
+        const allowed = markedMethods(instance);
+        if (!allowed && this.requireExplicitExposure)
+            throw new Error(`exposeClassInstance: ${instance.constructor.name} marks no @rpc methods and requireExplicitExposure is on`);
+        this.exposedNameSpaceInstances[namespace] = instance;
+        // The call site wins over the class, since it is the one that knows how this particular
+        // instance is being used - the same class may front one device here and a pool there.
+        const execution = settings.execution ?? declared?.execution;
+        if (execution)
+            this.exposedExecution[namespace] = execution;
+        const semantics = declaredSemantics(instance);
+        if (semantics.size)
+            this.exposedSemantics[namespace] = semantics;
+        // Iterate upwards to find all the methods within the prototype chain.
+        let props = Object.getOwnPropertyNames(instance.constructor.prototype);
+        let parent = Object.getPrototypeOf(instance.constructor.prototype);
+        while (parent && parent.constructor.name !== 'Object' && parent.constructor.name !== 'EventEmitter') {
+            const parentProps = Object.getOwnPropertyNames(parent);
+            props = props.concat(parentProps);
+            parent = Object.getPrototypeOf(parent);
+            if (prototypeSteps && prototypeSteps-- === 0)
+                break;
+        }
+        // All methods was found.
+        const map = this.getNameSpaceMethodMap(namespace);
+        for (const f of props) {
+            if (f === 'constructor' || typeof instance[f] !== 'function')
+                continue;
+            if (allowed && !allowed.has(f))
+                continue;
+            map.set(f, instance[f].bind(instance));
+        }
+    }
+    exposeClass(constructor, aliasName) {
+        let name = constructor.name;
+        if (aliasName)
+            name = aliasName;
+        this.exposedClasses[name] = constructor;
+    }
+    exposeObject(obj, name) {
+        this.exposedNameSpaceInstances[name] = obj;
+        const props = Object.getOwnPropertyNames(obj);
+        for (const f of props) {
+            if (f !== 'constructor' && typeof obj[f] === 'function') {
+                const map = this.getNameSpaceMethodMap(name);
+                map.set(f, obj[f]);
+            }
+        }
+    }
+    expose(methodName, method) {
+        const map = this.getNameSpaceMethodMap(methodName);
+        map.set(methodName, method);
+    }
+    async createRpcInstance(className, instanceName, ...args) {
+        let result = '';
+        const con = this.exposedClasses[className];
+        if (con) {
+            const id = instanceName ? instanceName : uuidv4();
+            const instance = new con(...args);
+            this.createdInstances.set(id, instance);
+            this.exposeClassInstance(instance, id);
+            result = id;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=RpcServerHandler.js.map