@source-repo/rpc 3.0.0

package/dist/Transports/SocketIoServerTransport.d.ts

@@ -0,0 +1,135 @@
+import * as SocketIo from 'socket.io';
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer, type ServerOptions as TlsServerOptions } from 'https';
+import { GenericModule, IGenericModule, Message } from '../RPC/Core.js';
+import { FrameCodec } from '../RPC/Codec.js';
+import { RpcAuthenticator, RpcIdentity } from '../RPC/Auth.js';
+import { RelayRule } from './Presence.js';
+type Servers = HttpServer | HttpsServer | SocketIo.Server;
+export declare class SocketIoServerTransport extends GenericModule<Message, unknown, Message, unknown> {
+    server?: Servers | undefined;
+    authenticate?: RpcAuthenticator | undefined;
+    closed: boolean;
+    /** Set when this transport can never come up - a port already in use, most often. */
+    startupError?: unknown;
+    /** Owned here rather than by a converter above, so the transport decides its own wire form. */
+    codec: FrameCodec;
+    io?: SocketIo.Server;
+    ourServer: boolean;
+    /**
+     * Peer name -> the socket it was last seen on, learned from the source field of inbound frames.
+     * Without it this transport can only broadcast, which puts every reply and every event on every
+     * connected socket. Peer names are expected to be unique; the most recent socket wins, so a
+     * reconnecting peer re-binds to its new socket on its first frame.
+     */
+    peerSockets: Map<string, SocketIo.Socket<SocketIo.DefaultEventsMap, SocketIo.DefaultEventsMap, SocketIo.DefaultEventsMap, any>>;
+    /** Peer name -> the identity its connection authenticated as. Empty when no authenticator is set. */
+    peerIdentities: Map<string, RpcIdentity>;
+    /**
+     * Forward a frame addressed to another connected peer instead of handling it here. On by
+     * default: a peer that can only be reached by dialling out - a browser page hosting an
+     * RpcServer, most obviously - is reachable no other way. `false` keeps a server strictly
+     * point-to-point, and a predicate decides per connection, which is the useful case: an
+     * operator's page may deserve a route to a cell controller where a visitor's does not.
+     */
+    relay: RelayRule;
+    /**
+     * What each connection says it can reach, beyond itself. Kept per socket so a link going away
+     * takes exactly its own peers with it, and so a peer offered by two links can fall back to the
+     * other one instead of vanishing.
+     */
+    private readonly carriedBy;
+    constructor(name: string, server?: Servers | undefined, port?: number, 
+    /**
+     * Certificate and key for a server opened here. Present means HTTPS.
+     *
+     * This used to be `https?: boolean`, and `true` called createHttpsServer() with nothing in
+     * it - a server that listens, completes no handshake, and refuses every client with an
+     * error about missing certificates. There is no useful HTTPS server without key material,
+     * so the material is what asks for one.
+     */
+    tls?: TlsServerOptions, sources?: IGenericModule[], socketIoOptions?: Partial<SocketIo.ServerOptions>, authenticate?: RpcAuthenticator | undefined);
+    private onSocketMessage;
+    /**
+     * Which module carries a peer, or undefined to handle the frame here. The registry is shared
+     * with this server's other transports, so a peer on the broker resolves to the MQTT transport
+     * and a socket.io peer can call it without either end knowing the other's transport.
+     */
+    private peerCarrying;
+    /** Asked only once a frame really is deliverable elsewhere, never about a peer that is absent. */
+    private mayRelay;
+    /**
+     * Routes a rule has already allowed, in both directions. Every call has a reply and most have
+     * events after it, so asking a rule about each frame separately would mean `source === 'hmi'`
+     * silently stranding the answer coming back - the reply's source is the far peer, not the hmi.
+     * A permitted call opens the pair, the way connection tracking does, until one of them leaves.
+     */
+    private readonly openRoutes;
+    private static pair;
+    private permitted;
+    private forgetRoutes;
+    /** Named once each, so a peer that reconnects in a loop does not bury the first report. */
+    private warnedAboutDisplacing;
+    private warnAboutDisplacement;
+    private warnedAboutRelay;
+    /**
+     * Said once, and only when this server actually forwards something. Without an authenticator
+     * the source of a frame is an unverified claim, so a relay passes on whatever it is told and
+     * the peer at the far end has no way to tell who really sent it. Warning at construction would
+     * fire for every ordinary server that never relays anything.
+     */
+    private warnAboutUnauthenticatedRelay;
+    /**
+     * Refuse to register a peer name this transport has not yet decided to trust.
+     *
+     * GenericModule registers a frame's source as it parses the header, which is right for MQTT -
+     * the broker is the authority there, and there is no connection anyone could have checked. Here
+     * there is one, and the header is a claim until it has been checked against it. Registering on
+     * parse let a peer put any name it liked into the registry this server shares with its other
+     * transports, just by sending one frame that was then rejected: enough to have the bus advertise
+     * a peer that does not exist, and to point lookups for a real peer's name at this transport,
+     * where nothing answers to it. The frame never went anywhere - peerSockets is what delivery uses
+     * and only learnPeer writes it - but the routing table had already been told.
+     *
+     * So registration happens where the trust decision is made, in learnPeer and forgetPeer, which
+     * call `super` to say they are past this point. Nothing changes for a transport with no
+     * authenticator: without one, a name was never evidence of anything to begin with.
+     */
+    setKnownSource(source: string): void;
+    /**
+     * Record a peer against the socket that reaches it and tell everyone else it is here.
+     *
+     * A peer announcing itself owns its name and takes the route over. One merely carried by a
+     * neighbour does not: the first link to offer it keeps it, and a second offering the same name
+     * is remembered only as a fallback. Letting carried announcements steal the route would make
+     * two neighbours advertising the same peer flip it back and forth, each flip re-announced
+     * onwards - chatter that never settles.
+     */
+    private learnPeer;
+    /** A peer is gone from here unless another link still offers it. */
+    private forgetPeer;
+    /**
+     * A peer saying who it is, which is the whole of discovery here. It answers with the peers
+     * already connected, standing in for the retained presence an MQTT subscriber is handed.
+     */
+    private onAnnouncement;
+    /**
+     * Everyone this server can put a frame in front of: its own connections, plus whatever its
+     * other transports have registered. On a server holding a socket.io listener and a broker
+     * connection, that is what lets a browser peer see and call a peer on the broker.
+     */
+    reachablePeers(): string[];
+    /** Tell the connected peers about one that arrived or left on a different transport. */
+    announcePeer(peer: string, state: 'online' | 'offline'): void;
+    /** Apply a link's latest claim about what lies behind it, adding and dropping as it changes. */
+    private updateCarried;
+    private broadcastPresence;
+    /** Send to a peer's socket, carrying a hop count the ordinary send path has no reason to know. */
+    forward(message: Message, source: string, target: string, hops: number): void;
+    receive(message: Message, source: string, target: string): Promise<void>;
+    close(): Promise<void>;
+    getIdentity(source: string): RpcIdentity | undefined;
+    isTransport(): boolean;
+}
+export {};
+//# sourceMappingURL=SocketIoServerTransport.d.ts.map

package/dist/Transports/SocketIoServerTransport.d.ts.map

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

package/dist/Transports/SocketIoServerTransport.js

@@ -0,0 +1,505 @@
+import * as SocketIo from 'socket.io';
+import { createServer as createHttpServer } from 'http';
+import { createServer as createHttpsServer } from 'https';
+import { GenericModule, TransportEvent } from '../RPC/Core.js';
+import { msgPackCodec } from '../RPC/Codec.js';
+import { isUsablePeerName, MAX_CARRIED_PEERS, MAX_RELAY_HOPS, PRESENCE_EVENT } from './Presence.js';
+export class SocketIoServerTransport extends GenericModule {
+    server;
+    authenticate;
+    closed = false;
+    /** Set when this transport can never come up - a port already in use, most often. */
+    startupError;
+    /** Owned here rather than by a converter above, so the transport decides its own wire form. */
+    codec = msgPackCodec;
+    io;
+    ourServer = false;
+    /**
+     * Peer name -> the socket it was last seen on, learned from the source field of inbound frames.
+     * Without it this transport can only broadcast, which puts every reply and every event on every
+     * connected socket. Peer names are expected to be unique; the most recent socket wins, so a
+     * reconnecting peer re-binds to its new socket on its first frame.
+     */
+    peerSockets = new Map();
+    /** Peer name -> the identity its connection authenticated as. Empty when no authenticator is set. */
+    peerIdentities = new Map();
+    /**
+     * Forward a frame addressed to another connected peer instead of handling it here. On by
+     * default: a peer that can only be reached by dialling out - a browser page hosting an
+     * RpcServer, most obviously - is reachable no other way. `false` keeps a server strictly
+     * point-to-point, and a predicate decides per connection, which is the useful case: an
+     * operator's page may deserve a route to a cell controller where a visitor's does not.
+     */
+    relay = true;
+    /**
+     * What each connection says it can reach, beyond itself. Kept per socket so a link going away
+     * takes exactly its own peers with it, and so a peer offered by two links can fall back to the
+     * other one instead of vanishing.
+     */
+    carriedBy = new Map();
+    constructor(name, server, port, 
+    /**
+     * Certificate and key for a server opened here. Present means HTTPS.
+     *
+     * This used to be `https?: boolean`, and `true` called createHttpsServer() with nothing in
+     * it - a server that listens, completes no handshake, and refuses every client with an
+     * error about missing certificates. There is no useful HTTPS server without key material,
+     * so the material is what asks for one.
+     */
+    tls, sources, socketIoOptions = {}, authenticate) {
+        super(name, sources);
+        this.server = server;
+        this.authenticate = authenticate;
+        this.ourServer = server === undefined;
+        if (tls && !tls.cert && !tls.pfx && !tls.SNICallback)
+            throw new Error(`SocketIoServerTransport '${name}': tls needs a certificate - pass cert and key, or pfx, or an SNICallback that supplies them`);
+        if (!server)
+            this.server = tls ? createHttpsServer(tls) : createHttpServer();
+        if (this.server instanceof SocketIo.Server)
+            this.io = this.server;
+        else {
+            const configuredAllowRequest = socketIoOptions?.allowRequest;
+            this.io = new SocketIo.Server(this.server, {
+                cors: {
+                    origin: '*',
+                    methods: ['GET', 'POST'],
+                    credentials: true
+                },
+                serveClient: false,
+                ...socketIoOptions,
+                /**
+                 * Refused at the handshake, which is before engine.io builds a Socket for it.
+                 *
+                 * close() disconnects the sockets it can see and then waits for the server to shut
+                 * down. A handshake that completes inside that window is created *after* the sweep
+                 * has passed, so nothing ever disconnects it - and its ping timer keeps the process
+                 * alive with no way to reach the peer it belongs to. Clients reconnect on their own,
+                 * which is what drives connections into the window in the first place.
+                 */
+                allowRequest: (request, callback) => {
+                    if (this.closed)
+                        return callback('server closing', false);
+                    if (configuredAllowRequest)
+                        return configuredAllowRequest(request, callback);
+                    callback(null, true);
+                }
+            });
+        }
+        // Runs before 'connection', so an unauthenticated peer never reaches the RPC layer.
+        if (this.authenticate) {
+            this.io.use(async (socket, next) => {
+                try {
+                    const identity = await this.authenticate(socket.handshake.auth, { address: socket.handshake.address });
+                    if (!identity)
+                        return next(new Error('unauthorized'));
+                    socket.data.identity = identity;
+                    next();
+                }
+                catch {
+                    next(new Error('unauthorized'));
+                }
+            });
+        }
+        this.io.on('connection', (socket) => {
+            // A handshake already in flight when close() began still arrives here. allowRequest
+            // catches the ones that had not started; this catches the rest.
+            if (this.closed) {
+                socket.disconnect(true);
+                return;
+            }
+            this.emit('connection', socket);
+            socket.on(PRESENCE_EVENT, (announcement) => {
+                // Guarded because socket.io emits this synchronously from its parser: a listener
+                // that throws unwinds into the engine rather than into anything that can report it.
+                try {
+                    this.onAnnouncement(socket, announcement);
+                }
+                catch (e) {
+                    this.emit(TransportEvent.rejected, { source: 'unknown', reason: `bad presence announcement: ${String(e)}`, error: e });
+                }
+            });
+            // The whole body is guarded, not just the parse: this is an async listener, so anything
+            // that escapes it is an unhandled rejection, and Node's default is to end the process.
+            // One peer sending one bad frame must not take down a server answering everybody else.
+            socket.on('message', (messageArray) => void this.onSocketMessage(socket, messageArray).catch((e) => this.emit(TransportEvent.rejected, { source: 'unknown', reason: `failed to handle frame: ${String(e)}`, error: e })));
+            socket.on('disconnect', (reason, details) => {
+                this.carriedBy.delete(socket);
+                for (const peer of [...this.peerSockets.keys()]) {
+                    if (this.peerSockets.get(peer) !== socket)
+                        continue;
+                    // forgetPeer keeps it if another link still carries it; otherwise this is what
+                    // lets the RPC layer drop the event subscriptions held for a peer that is gone.
+                    this.forgetPeer(peer, socket);
+                }
+                // Emitted rather than printed. These used to go to console.log, which put three
+                // lines of socket.io internals on the output of every disconnect and gave anything
+                // above this transport no way to see them at all.
+                this.emit(TransportEvent.disconnected, reason, details);
+            });
+        });
+        if (this.server && this.ourServer && !(this.server instanceof SocketIo.Server)) {
+            const listener = this.server;
+            // Without a handler Node throws on the unhandled 'error', so a port already in use took
+            // the process down with a stack trace instead of a diagnosis.
+            listener.on('error', (e) => {
+                // Recorded as well as emitted. A listener that cannot bind never becomes ready, and
+                // without this the only symptom was ready() timing out with nothing about the port.
+                this.startupError = e;
+                this.emit(TransportEvent.transportError, e);
+            });
+            // Ready means listening. It used to be set here regardless, so ready() resolved before
+            // the port was bound and a server could announce itself and then die of EADDRINUSE.
+            listener.listen(port, () => {
+                this.readyFlag = true;
+                console.log(`Socket.io server listening on port ${port}`);
+            });
+        }
+        else
+            this.readyFlag = true;
+    }
+    async onSocketMessage(socket, messageArray) {
+        const [header, payload, reason] = this.extractHeader(new Uint8Array(messageArray));
+        if (!header) {
+            // Reported rather than dropped in silence, which the sender only ever saw as a timeout.
+            this.emit(TransportEvent.rejected, { source: 'unknown', reason: reason ?? 'no msgrpc header' });
+            return;
+        }
+        const identity = socket.data.identity;
+        if (this.authenticate) {
+            // The source field is written by the sender. Pinning it to the identity this
+            // connection authenticated as is what stops one peer addressing messages as
+            // another and inheriting its rights.
+            if (!identity || header.source !== identity.name) {
+                this.emit(TransportEvent.rejected, { source: header.source, reason: 'source does not match authenticated identity' });
+                return;
+            }
+            this.peerIdentities.set(header.source, identity);
+        }
+        // Learned before the routing check, so a peer stays addressable even when a particular
+        // frame turns out to be undeliverable.
+        this.learnPeer(header.source, socket);
+        let message;
+        try {
+            message = this.codec.decode(payload);
+        }
+        catch (e) {
+            this.emit(TransportEvent.rejected, { source: header.source, reason: `undecodable frame: ${String(e)}` });
+            return;
+        }
+        // Whether this frame is for us at all. A server used to run whatever reached it, testing
+        // the target only for being a name it had heard of - so a call addressed to another peer
+        // was executed here, the addressee never saw it, and the caller was answered by the wrong
+        // peer.
+        const elsewhere = header.target !== this.name ? this.peerCarrying(header.target) : undefined;
+        if (elsewhere) {
+            if (!this.mayRelay(header.source, header.target, identity)) {
+                // Deliberately not falling through to local handling: running a call meant for a
+                // peer this caller is not allowed to reach would answer it with the wrong
+                // implementation and call that a success.
+                this.emit(TransportEvent.unroutable, { source: header.source, target: header.target, reason: 'relay refused' });
+                return;
+            }
+            // Announced here rather than in forward(), so that a frame crossing to another
+            // transport is reported too: this is the one point both relay paths pass through, and a
+            // tap that saw only same-transport traffic would quietly miss half a mixed network.
+            // Guarded because this runs per frame, and building the object for nobody is the cost.
+            if (this.listenerCount(TransportEvent.relayed))
+                this.emit(TransportEvent.relayed, { source: header.source, target: header.target, message });
+            // Forwarding within this transport is done here rather than through receive(), so the
+            // hop count survives it. A frame that has been round too many relays is dropped: tables
+            // settle after a link fails, but a frame circling in the meantime never stops on its own.
+            if (elsewhere === this) {
+                const hops = (header.hops ?? 0) + 1;
+                if (hops > MAX_RELAY_HOPS) {
+                    this.emit(TransportEvent.unroutable, { source: header.source, target: header.target, reason: `over ${MAX_RELAY_HOPS} relays` });
+                    return;
+                }
+                this.forward(message, header.source, header.target, hops);
+                return;
+            }
+            await elsewhere.receive(message, header.source, header.target);
+            return;
+        }
+        if (this.targetExists(header.target)) {
+            await this.send(message, header.source, header.target);
+            return;
+        }
+        // Neither this server nor anywhere it can forward to. Reported rather than dropped in
+        // silence, which the caller only ever saw as an unexplained timeout.
+        this.emit(TransportEvent.unroutable, { source: header.source, target: header.target });
+    }
+    /**
+     * Which module carries a peer, or undefined to handle the frame here. The registry is shared
+     * with this server's other transports, so a peer on the broker resolves to the MQTT transport
+     * and a socket.io peer can call it without either end knowing the other's transport.
+     */
+    peerCarrying(target) {
+        if (this.peerSockets.has(target))
+            return this;
+        // The registry is shared with this server's other transports, so a peer on the broker
+        // resolves to the MQTT transport and a socket.io peer can reach it without either end
+        // knowing which transport the other is on.
+        const known = this.peerRegistry.get(target);
+        return known && known !== this && known.isTransport() ? known : undefined;
+    }
+    /** Asked only once a frame really is deliverable elsewhere, never about a peer that is absent. */
+    mayRelay(source, target, identity) {
+        if (this.relay === false)
+            return false;
+        if (typeof this.relay === 'function' && !this.permitted(source, target, identity))
+            return false;
+        this.warnAboutUnauthenticatedRelay();
+        return true;
+    }
+    /**
+     * Routes a rule has already allowed, in both directions. Every call has a reply and most have
+     * events after it, so asking a rule about each frame separately would mean `source === 'hmi'`
+     * silently stranding the answer coming back - the reply's source is the far peer, not the hmi.
+     * A permitted call opens the pair, the way connection tracking does, until one of them leaves.
+     */
+    openRoutes = new Set();
+    static pair = (a, b) => `${a}\u0000${b}`;
+    permitted(source, target, identity) {
+        if (this.openRoutes.has(SocketIoServerTransport.pair(source, target)))
+            return true;
+        let allowed;
+        try {
+            allowed = this.relay({ source, target, identity });
+        }
+        catch {
+            // A rule that throws refuses, for the same reason an authorizer that throws denies.
+            allowed = false;
+        }
+        if (!allowed)
+            return false;
+        this.openRoutes.add(SocketIoServerTransport.pair(source, target));
+        this.openRoutes.add(SocketIoServerTransport.pair(target, source));
+        return true;
+    }
+    forgetRoutes(peer) {
+        const mark = `${peer}\u0000`;
+        for (const route of this.openRoutes)
+            if (route.startsWith(mark) || route.endsWith(`\u0000${peer}`))
+                this.openRoutes.delete(route);
+    }
+    /** Named once each, so a peer that reconnects in a loop does not bury the first report. */
+    warnedAboutDisplacing = new Set();
+    warnAboutDisplacement(name) {
+        this.emit(TransportEvent.peerDisplaced, name);
+        if (this.warnedAboutDisplacing.has(name))
+            return;
+        this.warnedAboutDisplacing.add(name);
+        console.warn(`source-rpc: '${name}' announced itself on '${this.name}' while another live connection already held that name. ` +
+            'The newcomer takes the address, so if both are really running, replies will reach the wrong one. Give them distinct names.');
+    }
+    warnedAboutRelay = false;
+    /**
+     * Said once, and only when this server actually forwards something. Without an authenticator
+     * the source of a frame is an unverified claim, so a relay passes on whatever it is told and
+     * the peer at the far end has no way to tell who really sent it. Warning at construction would
+     * fire for every ordinary server that never relays anything.
+     */
+    warnAboutUnauthenticatedRelay() {
+        if (this.warnedAboutRelay || this.authenticate)
+            return;
+        this.warnedAboutRelay = true;
+        console.warn(`source-rpc: '${this.name}' is relaying frames between peers with no authenticate configured, so their source is an unverified claim. ` +
+            'Set authenticate, or relay: false to forward nothing.');
+    }
+    /**
+     * Refuse to register a peer name this transport has not yet decided to trust.
+     *
+     * GenericModule registers a frame's source as it parses the header, which is right for MQTT -
+     * the broker is the authority there, and there is no connection anyone could have checked. Here
+     * there is one, and the header is a claim until it has been checked against it. Registering on
+     * parse let a peer put any name it liked into the registry this server shares with its other
+     * transports, just by sending one frame that was then rejected: enough to have the bus advertise
+     * a peer that does not exist, and to point lookups for a real peer's name at this transport,
+     * where nothing answers to it. The frame never went anywhere - peerSockets is what delivery uses
+     * and only learnPeer writes it - but the routing table had already been told.
+     *
+     * So registration happens where the trust decision is made, in learnPeer and forgetPeer, which
+     * call `super` to say they are past this point. Nothing changes for a transport with no
+     * authenticator: without one, a name was never evidence of anything to begin with.
+     */
+    setKnownSource(source) {
+        if (this.authenticate)
+            return;
+        super.setKnownSource(source);
+    }
+    /**
+     * Record a peer against the socket that reaches it and tell everyone else it is here.
+     *
+     * A peer announcing itself owns its name and takes the route over. One merely carried by a
+     * neighbour does not: the first link to offer it keeps it, and a second offering the same name
+     * is remembered only as a fallback. Letting carried announcements steal the route would make
+     * two neighbours advertising the same peer flip it back and forth, each flip re-announced
+     * onwards - chatter that never settles.
+     */
+    learnPeer(name, socket, carried = false) {
+        const known = this.peerSockets.get(name);
+        if (known === socket)
+            return;
+        if (known && carried)
+            return;
+        // A live connection already answers to this name, and the newcomer is about to take the
+        // address off it. The takeover is deliberate - a peer reconnecting after a blip announces
+        // itself while the server may still hold the dead socket, and refusing it would lock a peer
+        // out of its own name - but it must not be silent. Two peers genuinely sharing a name send
+        // each other's replies into the wrong socket, which reads as calls timing out for no reason.
+        if (known && known.connected)
+            this.warnAboutDisplacement(name);
+        this.peerSockets.set(name, socket);
+        // Registered as well as recorded: the shared registry is what the switch routes on, and
+        // what a server reads to work out which peers it can advertise onwards. `super`, because
+        // this is the point the name stops being a claim - see setKnownSource above.
+        super.setKnownSource(name);
+        this.emit(TransportEvent.peerOnline, name);
+        this.broadcastPresence({ peer: name, state: 'online' });
+    }
+    /** A peer is gone from here unless another link still offers it. */
+    forgetPeer(name, socket) {
+        if (this.peerSockets.get(name) !== socket)
+            return;
+        this.peerSockets.delete(name);
+        this.peerIdentities.delete(name);
+        for (const [other, carried] of this.carriedBy) {
+            if (other === socket || !carried.has(name))
+                continue;
+            // Still reachable the other way, so nothing above this needs to hear about it.
+            this.peerSockets.set(name, other);
+            super.setKnownSource(name);
+            return;
+        }
+        this.emit(TransportEvent.peerGone, name);
+        this.forgetRoutes(name);
+        this.broadcastPresence({ peer: name, state: 'offline' });
+    }
+    /**
+     * A peer saying who it is, which is the whole of discovery here. It answers with the peers
+     * already connected, standing in for the retained presence an MQTT subscriber is handed.
+     */
+    onAnnouncement(socket, announcement) {
+        const name = announcement?.name;
+        if (!isUsablePeerName(name)) {
+            this.emit(TransportEvent.rejected, { source: String(name), reason: 'unusable peer name in presence announcement' });
+            return;
+        }
+        const identity = socket.data.identity;
+        if (this.authenticate) {
+            // Same rule as a frame's source: a name is a claim until a connection vouches for it,
+            // and an unchecked one here would let a peer be listed and addressed as someone else.
+            if (!identity || name !== identity.name) {
+                this.emit(TransportEvent.rejected, { source: name, reason: 'announced name does not match authenticated identity' });
+                return;
+            }
+            this.peerIdentities.set(name, identity);
+        }
+        this.learnPeer(name, socket);
+        this.updateCarried(socket, name, announcement.carrying);
+        // This peer's own name goes first: a newcomer has to know what to call the thing it just
+        // connected to, and a client that routes on its registry - which RpcServer.proxy does -
+        // cannot address the hub at all until something puts it there.
+        //
+        // Split horizon applies to the rest. Handing a link back the peers it just told this one
+        // about makes it believe they are reachable the way it came, so it stops advertising them,
+        // and they disappear from everyone a hop further out.
+        socket.emit(PRESENCE_EVENT, {
+            peers: [this.name, ...this.reachablePeers().filter((peer) => peer !== name && this.peerSockets.get(peer) !== socket)]
+        });
+    }
+    /**
+     * Everyone this server can put a frame in front of: its own connections, plus whatever its
+     * other transports have registered. On a server holding a socket.io listener and a broker
+     * connection, that is what lets a browser peer see and call a peer on the broker.
+     */
+    reachablePeers() {
+        const names = new Set(this.peerSockets.keys());
+        for (const name of this.peerRegistry.names())
+            names.add(name);
+        names.delete(this.name);
+        return [...names];
+    }
+    /** Tell the connected peers about one that arrived or left on a different transport. */
+    announcePeer(peer, state) {
+        if (this.peerSockets.has(peer))
+            return;
+        this.broadcastPresence({ peer, state });
+    }
+    /** Apply a link's latest claim about what lies behind it, adding and dropping as it changes. */
+    updateCarried(socket, announcer, carrying) {
+        const claimed = new Set((Array.isArray(carrying) ? carrying : [])
+            .slice(0, MAX_CARRIED_PEERS)
+            .filter((peer) => isUsablePeerName(peer) && peer !== this.name && peer !== announcer));
+        const previous = this.carriedBy.get(socket) ?? new Set();
+        this.carriedBy.set(socket, claimed);
+        for (const peer of previous)
+            if (!claimed.has(peer))
+                this.forgetPeer(peer, socket);
+        for (const peer of claimed)
+            if (!previous.has(peer))
+                this.learnPeer(peer, socket, true);
+    }
+    broadcastPresence(update) {
+        // Everyone but the peer it is about; it already knows.
+        const subject = update.peer ? this.peerSockets.get(update.peer) : undefined;
+        for (const socket of new Set(this.peerSockets.values()))
+            if (socket !== subject)
+                socket.emit(PRESENCE_EVENT, update);
+    }
+    /** Send to a peer's socket, carrying a hop count the ordinary send path has no reason to know. */
+    forward(message, source, target, hops) {
+        const socket = this.peerSockets.get(target);
+        if (!socket) {
+            this.emit(TransportEvent.unroutable, { source, target });
+            return;
+        }
+        try {
+            socket.emit('message', this.frameMessage(this.buildHeader(source, target, { hops }), this.codec.encode(message)));
+        }
+        catch (e) {
+            // Relaying is done on someone else's behalf, so there is no caller here to reject.
+            // Reported instead, or an unframeable relay would be indistinguishable from a lost one.
+            this.emit(TransportEvent.unroutable, { source, target, reason: `cannot forward: ${String(e)}`, error: e });
+        }
+    }
+    async receive(message, source, target) {
+        const socket = target === undefined ? undefined : this.peerSockets.get(target);
+        if (!socket) {
+            // Deliberately no io.emit() fallback: broadcasting would put this peer's reply on
+            // every other client's socket. An unknown target means the peer never identified
+            // itself or has gone away, so the frame is dropped.
+            this.emit(TransportEvent.unroutable, { source, target });
+            return;
+        }
+        socket.emit('message', this.frameMessage(this.buildHeader(source, target), this.codec.encode(message)));
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.peerSockets.clear();
+        this.peerIdentities.clear();
+        const io = this.io;
+        const server = this.server;
+        this.io = undefined;
+        this.server = undefined;
+        this.emit('close');
+        const ownHttpServer = server && this.ourServer && !(server instanceof SocketIo.Server) ? server : undefined;
+        io?.disconnectSockets(true);
+        // Keep-alive connections would otherwise hold the listener open long past close().
+        ownHttpServer?.closeAllConnections();
+        if (io)
+            await new Promise((resolve) => io.close(() => resolve()));
+        if (ownHttpServer?.listening)
+            await new Promise((resolve) => ownHttpServer.close(() => resolve()));
+    }
+    getIdentity(source) {
+        return this.peerIdentities.get(source);
+    }
+    isTransport() {
+        return true;
+    }
+}
+//# sourceMappingURL=SocketIoServerTransport.js.map