werift 0.24.4 → 0.25.0

package/lib/ice/src/exceptions.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransactionTimeout = exports.TransactionFailed = exports.TransactionError = void 0;
+exports.AddressFamilyMismatch = exports.TransactionTimeout = exports.TransactionFailed = exports.TransactionError = void 0;
 class TransactionError extends Error {
     constructor() {
         super(...arguments);
@@ -52,4 +52,26 @@ class TransactionTimeout extends TransactionError {
     }
 }
 exports.TransactionTimeout = TransactionTimeout;
+/**
+ * The request target is an IP literal of a different family than the socket
+ * that would carry it, so it can never be delivered.
+ */
+class AddressFamilyMismatch extends Error {
+    constructor(addr, socketFamily) {
+        super(`cannot reach ${addr[0]}:${addr[1]} from an IPv${socketFamily} socket`);
+        Object.defineProperty(this, "addr", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: addr
+        });
+        Object.defineProperty(this, "socketFamily", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: socketFamily
+        });
+    }
+}
+exports.AddressFamilyMismatch = AddressFamilyMismatch;
 //# sourceMappingURL=exceptions.js.map

package/lib/ice/src/exceptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../../../ice/src/exceptions.ts"],"names":[],"mappings":";;;AAGA,MAAa,gBAAiB,SAAQ,KAAK;IAA3C;;QACE;;;;;WAAmB;QACnB;;;;;WAAe;IACjB,CAAC;CAAA;AAHD,4CAGC;AAED,MAAa,iBAAkB,SAAQ,gBAAgB;IACrD,YACS,QAAiB,EACjB,IAAa;QAEpB,KAAK,EAAE,CAAC;QAHR;;;;mBAAO,QAAQ;WAAS;QACxB;;;;mBAAO,IAAI;WAAS;IAGtB,CAAC;IAED,IAAI,GAAG;QACL,IAAI,GAAG,GAAG,yBAAyB,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAChE,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;YAC9B,GAAG,IAAI,KAAK,IAAI,MAAM,GAAG,GAAG,CAAC;QAC/B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAjBD,8CAiBC;AAED,MAAa,kBAAmB,SAAQ,gBAAgB;IACtD,IAAI,GAAG;QACL,OAAO,4BAA4B,CAAC;IACtC,CAAC;CACF;AAJD,gDAIC","sourcesContent":["import type { Address } from \"./imports/common\";\nimport type { Message } from \"./stun/message\";\n\nexport class TransactionError extends Error {\n  response?: Message;\n  addr?: Address;\n}\n\nexport class TransactionFailed extends TransactionError {\n  constructor(\n    public response: Message,\n    public addr: Address,\n  ) {\n    super();\n  }\n\n  get str() {\n    let out = \"STUN transaction failed\";\n    const attribute = this.response.getAttributeValue(\"ERROR-CODE\");\n    if (attribute) {\n      const [code, msg] = attribute;\n      out += ` (${code} - ${msg})`;\n    }\n    return out;\n  }\n}\n\nexport class TransactionTimeout extends TransactionError {\n  get str() {\n    return \"STUN transaction timed out\";\n  }\n}\n"]}
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../../../ice/src/exceptions.ts"],"names":[],"mappings":";;;AAGA,MAAa,gBAAiB,SAAQ,KAAK;IAA3C;;QACE;;;;;WAAmB;QACnB;;;;;WAAe;IACjB,CAAC;CAAA;AAHD,4CAGC;AAED,MAAa,iBAAkB,SAAQ,gBAAgB;IACrD,YACS,QAAiB,EACjB,IAAa;QAEpB,KAAK,EAAE,CAAC;QAHR;;;;mBAAO,QAAQ;WAAS;QACxB;;;;mBAAO,IAAI;WAAS;IAGtB,CAAC;IAED,IAAI,GAAG;QACL,IAAI,GAAG,GAAG,yBAAyB,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAChE,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;YAC9B,GAAG,IAAI,KAAK,IAAI,MAAM,GAAG,GAAG,CAAC;QAC/B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAjBD,8CAiBC;AAED,MAAa,kBAAmB,SAAQ,gBAAgB;IACtD,IAAI,GAAG;QACL,OAAO,4BAA4B,CAAC;IACtC,CAAC;CACF;AAJD,gDAIC;AAED;;;GAGG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,YACS,IAAa,EACb,YAAmB;QAE1B,KAAK,CACH,gBAAgB,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,eAAe,YAAY,SAAS,CACvE,CAAC;QALF;;;;mBAAO,IAAI;WAAS;QACpB;;;;mBAAO,YAAY;WAAO;IAK5B,CAAC;CACF;AATD,sDASC","sourcesContent":["import type { Address } from \"./imports/common\";\nimport type { Message } from \"./stun/message\";\n\nexport class TransactionError extends Error {\n  response?: Message;\n  addr?: Address;\n}\n\nexport class TransactionFailed extends TransactionError {\n  constructor(\n    public response: Message,\n    public addr: Address,\n  ) {\n    super();\n  }\n\n  get str() {\n    let out = \"STUN transaction failed\";\n    const attribute = this.response.getAttributeValue(\"ERROR-CODE\");\n    if (attribute) {\n      const [code, msg] = attribute;\n      out += ` (${code} - ${msg})`;\n    }\n    return out;\n  }\n}\n\nexport class TransactionTimeout extends TransactionError {\n  get str() {\n    return \"STUN transaction timed out\";\n  }\n}\n\n/**\n * The request target is an IP literal of a different family than the socket\n * that would carry it, so it can never be delivered.\n */\nexport class AddressFamilyMismatch extends Error {\n  constructor(\n    public addr: Address,\n    public socketFamily: 4 | 6,\n  ) {\n    super(\n      `cannot reach ${addr[0]}:${addr[1]} from an IPv${socketFamily} socket`,\n    );\n  }\n}\n"]}

package/lib/ice/src/ice.d.ts

@@ -45,6 +45,22 @@ export declare class Connection implements IceConnection {
     readonly stateChanged: Event<[IceState]>;
     readonly onIceCandidate: Event<[Candidate]>;
     constructor(_iceControlling: boolean, options?: Partial<IceOptions>);
+    /**
+     * Replace STUN/TURN servers after construction.
+     * Server-related fields are replaced (not partial-merged) so that removing
+     * TURN clears residual credentials. W3C setConfiguration replaces the ICE
+     * server list rather than merging additively.
+     *
+     * Used when servers are learned after the gatherer was built (e.g. WHIP
+     * Link headers) and must take effect before the next gather pass.
+     */
+    setIceServers(options: Partial<IceOptions>): void;
+    /**
+     * Derive Connection.stunServer / turnServer from this.options.
+     * Shared by the constructor and setIceServers so both paths validate and
+     * default identically.
+     */
+    private applyStunTurnServersFromOptions;
     get iceControlling(): boolean;
     set iceControlling(value: boolean);
     get iceLite(): boolean;
@@ -58,6 +74,12 @@ export declare class Connection implements IceConnection {
     gatherCandidates(): Promise<void>;
     private appendLocalCandidate;
     private ensureProtocol;
+    /**
+     * RFC 6544: the selected TCP connection is the only path for this component;
+     * once it is closed no application data or consent check can reach the peer,
+     * so fail the same way as a consent expiry instead of waiting for it.
+     */
+    private handleConnectionClosed;
     private getCandidatePromises;
     connect(): Promise<void>;
     private unfreezeInitial;
@@ -94,6 +116,24 @@ export declare class Connection implements IceConnection {
         resolve: (value: void | PromiseLike<void>) => void;
         reject: (reason?: any) => void;
     };
+    private isTcpPair;
+    /**
+     * Aggressive nomination lets each side settle on whichever TCP connection
+     * finished first; the two sides can then pick different connections and
+     * pruning destroys the peer's choice. For TCP the controlling agent instead
+     * nominates exactly one valid pair (RFC 8445 §8.1.1 regular nomination).
+     */
+    private usesTcpRegularNomination;
+    private checkRequestOptions;
+    /**
+     * Controlling side: nominate the highest-priority TCP pair once every
+     * higher-priority TCP pair has finished its check, so the choice does not
+     * depend on which connection happened to complete first.
+     */
+    private nominateTcpPairIfReady;
+    private nominateTcpPair;
+    /** The agent was closed or restarted while the nomination was in flight. */
+    private isStaleNomination;
     private addPair;
     checkIncoming(message: Message, addr: Address, protocol: Protocol): void;
     private tryPair;

package/lib/ice/src/ice.js

@@ -49,6 +49,8 @@ const tcpProtocol_1 = require("./stun/tcpProtocol");
 const protocol_2 = require("./turn/protocol");
 const utils_1 = require("./utils");
 const log = (0, common_1.debug)("werift-ice : packages/ice/src/ice.ts : log");
+/** Fallback STUN server when none is configured (constructor / setIceServers). */
+const DEFAULT_STUN_SERVER = ["stun.l.google.com", 19302];
 class Connection {
     constructor(_iceControlling, options) {
         Object.defineProperty(this, "_iceControlling", {
@@ -463,7 +465,8 @@ class Connection {
                 const result = {};
                 const { remotePassword, remoteUsername, generation } = this;
                 const localUsername = pair.localCandidate.ufrag ?? this.localUsername;
-                const nominate = this.iceControlling && !this.remoteIsLite;
+                // TCP pairs use regular nomination (see nominateTcpPairIfReady).
+                const nominate = this.iceControlling && !this.remoteIsLite && !this.isTcpPair(pair);
                 const request = this.buildRequest({
                     nominate,
                     localUsername,
@@ -475,11 +478,7 @@ class Connection {
                 const startTime = performance.now();
                 try {
                     pair.requestsSent++;
-                    const [response, addr] = await pair.protocol.request(request, pair.remoteAddr, Buffer.from(remotePassword, "utf8"), pair.localCandidate.transport.toLowerCase() === "tcp" ? 0 : 4, (attempt) => {
-                        if (attempt > 0) {
-                            pair.retransmissionsSent++;
-                        }
-                    });
+                    const [response, addr] = await pair.protocol.request(request, pair.remoteAddr, Buffer.from(remotePassword, "utf8"), this.checkRequestOptions(pair));
                     pair.responsesReceived++;
                     // Calculate RTT
                     const endTime = performance.now();
@@ -546,6 +545,9 @@ class Connection {
                     // # nominated by agressive nomination or the remote party
                     pair.nominated = true;
                 }
+                else if (this.usesTcpRegularNomination(pair)) {
+                    // # nominated later by nominateTcpPairIfReady (from checkComplete)
+                }
                 else if (this.iceControlling && !this.nominating) {
                     // # perform regular nomination
                     this.nominating = true;
@@ -558,14 +560,11 @@ class Connection {
                     });
                     try {
                         pair.requestsSent++;
-                        await pair.protocol.request(request, pair.remoteAddr, Buffer.from(this.remotePassword, "utf8"), pair.localCandidate.transport.toLowerCase() === "tcp" ? 0 : 4, (attempt) => {
-                            if (attempt > 0) {
-                                pair.retransmissionsSent++;
-                            }
-                        });
+                        await pair.protocol.request(request, pair.remoteAddr, Buffer.from(this.remotePassword, "utf8"), this.checkRequestOptions(pair));
                         pair.responsesReceived++;
                     }
                     catch (error) {
+                        this.nominating = false;
                         pair.updateState(iceBase_1.CandidatePairState.FAILED);
                         this.checkComplete(pair);
                         return;
@@ -594,15 +593,55 @@ class Connection {
         if (this.iceLite) {
             this._iceControlling = false;
         }
-        const { stunServer, turnServer } = this.options;
-        this.stunServer = (0, iceBase_1.validateAddress)(stunServer) ?? [
-            "stun.l.google.com",
-            19302,
-        ];
-        this.turnServer = (0, iceBase_1.validateAddress)(turnServer);
+        this.applyStunTurnServersFromOptions();
         this.restart();
         log("new Connection", this.options);
     }
+    /**
+     * Replace STUN/TURN servers after construction.
+     * Server-related fields are replaced (not partial-merged) so that removing
+     * TURN clears residual credentials. W3C setConfiguration replaces the ICE
+     * server list rather than merging additively.
+     *
+     * Used when servers are learned after the gatherer was built (e.g. WHIP
+     * Link headers) and must take effect before the next gather pass.
+     */
+    setIceServers(options) {
+        // Explicitly assign server fields even when undefined so a STUN-only
+        // update cannot leave a previous TURN host/credential in options.
+        this.options = {
+            ...this.options,
+            stunServer: options.stunServer,
+            turnServer: options.turnServer,
+            turnUsername: options.turnUsername,
+            turnPassword: options.turnPassword,
+            turnTransport: options.turnTransport,
+        };
+        if (options.forceTurn !== undefined) {
+            this.options.forceTurn = options.forceTurn;
+        }
+        if (options.useTcp !== undefined) {
+            this.options.useTcp = options.useTcp;
+        }
+        if (options.turnTlsOptions !== undefined) {
+            this.options.turnTlsOptions = options.turnTlsOptions;
+        }
+        if (options.turnUdpFamily !== undefined) {
+            this.options.turnUdpFamily = options.turnUdpFamily;
+        }
+        this.applyStunTurnServersFromOptions();
+        log("Connection ice servers updated", this.options);
+    }
+    /**
+     * Derive Connection.stunServer / turnServer from this.options.
+     * Shared by the constructor and setIceServers so both paths validate and
+     * default identically.
+     */
+    applyStunTurnServersFromOptions() {
+        this.stunServer =
+            (0, iceBase_1.validateAddress)(this.options.stunServer) ?? DEFAULT_STUN_SERVER;
+        this.turnServer = (0, iceBase_1.validateAddress)(this.options.turnServer);
+    }
     get iceControlling() {
         return this._iceControlling;
     }
@@ -698,7 +737,7 @@ class Connection {
             if (this.options.additionalHostAddresses) {
                 address = Array.from(new Set([...this.options.additionalHostAddresses, ...address]));
             }
-            const candidatePromises = this.getCandidatePromises(address, 5);
+            const candidatePromises = this.getCandidatePromises(address, this.options.stunGatherTimeout);
             await Promise.allSettled(candidatePromises);
             this.localCandidatesEnd = true;
         }
@@ -775,6 +814,29 @@ class Connection {
                 log("dataReceived", error);
             }
         });
+        protocol.onConnectionClosed?.subscribe((remoteAddr) => {
+            this.handleConnectionClosed(protocol, remoteAddr);
+        });
+    }
+    /**
+     * RFC 6544: the selected TCP connection is the only path for this component;
+     * once it is closed no application data or consent check can reach the peer,
+     * so fail the same way as a consent expiry instead of waiting for it.
+     */
+    handleConnectionClosed(protocol, remoteAddr) {
+        const nominated = this.nominated;
+        if (!nominated ||
+            nominated.protocol !== protocol ||
+            nominated.remoteAddr[0] !== remoteAddr[0] ||
+            nominated.remoteAddr[1] !== remoteAddr[1]) {
+            return;
+        }
+        if (this.state === "closed" || this.state === "failed") {
+            return;
+        }
+        log("selected tcp connection closed", nominated.toJSON());
+        this.stopConsentLifecycle();
+        this.setState("failed");
     }
     getCandidatePromises(addresses, timeout = 5) {
         const candidatePromises = [];
@@ -823,16 +885,21 @@ class Connection {
         }
         if (!gatherRelayOnly && this.options.useTcp) {
             const tcpCandidatePromises = addresses.map(async (address) => {
-                const passiveProtocol = new tcpProtocol_1.TcpPassiveProtocol();
-                this.ensureProtocol(passiveProtocol);
-                await passiveProtocol.connectionMade(address, this.options.portRange);
-                passiveProtocol.localIp = address;
-                passiveProtocol.localCandidate = new candidate_1.Candidate((0, candidate_1.candidateFoundation)("host", "tcp", address), 1, "tcp", (0, candidate_1.candidatePriority)("host", {
-                    transport: "tcp",
-                    tcptype: "passive",
-                }), address, passiveProtocol.listeningPort, "host", undefined, undefined, "passive", this.generation, this.localUsername);
-                this.protocols.push(passiveProtocol);
-                this.appendLocalCandidate(passiveProtocol.localCandidate);
+                // Passive candidates open a listening TCP server; skip them when the
+                // agent only makes outbound connections (tcpPassive === false). Active
+                // candidates below still dial out, so direct TCP egress is unaffected.
+                if (this.options.tcpPassive !== false) {
+                    const passiveProtocol = new tcpProtocol_1.TcpPassiveProtocol();
+                    this.ensureProtocol(passiveProtocol);
+                    await passiveProtocol.connectionMade(address, this.options.portRange);
+                    passiveProtocol.localIp = address;
+                    passiveProtocol.localCandidate = new candidate_1.Candidate((0, candidate_1.candidateFoundation)("host", "tcp", address), 1, "tcp", (0, candidate_1.candidatePriority)("host", {
+                        transport: "tcp",
+                        tcptype: "passive",
+                    }), address, passiveProtocol.listeningPort, "host", undefined, undefined, "passive", this.generation, this.localUsername);
+                    this.protocols.push(passiveProtocol);
+                    this.appendLocalCandidate(passiveProtocol.localCandidate);
+                }
                 if (!gatherIceLite) {
                     const activeProtocol = new tcpProtocol_1.TcpActiveProtocol();
                     this.ensureProtocol(activeProtocol);
@@ -890,6 +957,8 @@ class Connection {
                     interfaceAddresses: this.options.interfaceAddresses,
                     transport: turnTransport,
                     tlsOptions: this.options.turnTlsOptions,
+                    connectTimeoutMs: (this.options.turnConnectTimeout ?? 8) * 1000,
+                    udpFamily: this.options.turnUdpFamily,
                 }).catch(async (e) => {
                     if (turnTransport === "udp") {
                         return await (0, protocol_2.createStunOverTurnClient)({
@@ -900,6 +969,7 @@ class Connection {
                             portRange: this.options.portRange,
                             interfaceAddresses: this.options.interfaceAddresses,
                             transport: "tcp",
+                            connectTimeoutMs: (this.options.turnConnectTimeout ?? 8) * 1000,
                         });
                     }
                     else {
@@ -1268,6 +1338,11 @@ class Connection {
                 }
             }
         }
+        this.nominateTcpPairIfReady();
+        // A nomination request is still in flight; its result decides the outcome.
+        if (this.nominating) {
+            return;
+        }
         {
             const list = [iceBase_1.CandidatePairState.SUCCEEDED, iceBase_1.CandidatePairState.FAILED];
             if (this.checkList.find(({ state }) => !list.includes(state))) {
@@ -1287,6 +1362,97 @@ class Connection {
             }));
         }
     }
+    isTcpPair(pair) {
+        return pair.localCandidate.transport.toLowerCase() === "tcp";
+    }
+    /**
+     * Aggressive nomination lets each side settle on whichever TCP connection
+     * finished first; the two sides can then pick different connections and
+     * pruning destroys the peer's choice. For TCP the controlling agent instead
+     * nominates exactly one valid pair (RFC 8445 §8.1.1 regular nomination).
+     */
+    usesTcpRegularNomination(pair) {
+        return this.iceControlling && !this.remoteIsLite && this.isTcpPair(pair);
+    }
+    checkRequestOptions(pair) {
+        const onRequestSent = (attempt) => {
+            if (attempt > 0) {
+                pair.retransmissionsSent++;
+            }
+        };
+        if (this.isTcpPair(pair)) {
+            // RFC 5389 §7.2.2: no retransmissions over a reliable transport.
+            return {
+                retransmissions: 0,
+                responseTimeout: const_1.TCP_CHECK_RESPONSE_TIMEOUT_MS,
+                onRequestSent,
+            };
+        }
+        return { retransmissions: 4, onRequestSent };
+    }
+    /**
+     * Controlling side: nominate the highest-priority TCP pair once every
+     * higher-priority TCP pair has finished its check, so the choice does not
+     * depend on which connection happened to complete first.
+     */
+    nominateTcpPairIfReady() {
+        if (!this.iceControlling ||
+            this.remoteIsLite ||
+            this.nominated ||
+            this.nominating) {
+            return;
+        }
+        for (const pair of this.checkList) {
+            if (!this.isTcpPair(pair)) {
+                continue;
+            }
+            if (pair.state === iceBase_1.CandidatePairState.SUCCEEDED) {
+                this.nominateTcpPair(pair);
+                return;
+            }
+            if (pair.state !== iceBase_1.CandidatePairState.FAILED) {
+                // A higher-priority pair may still succeed.
+                return;
+            }
+        }
+    }
+    nominateTcpPair(pair) {
+        this.nominating = true;
+        const { generation } = this;
+        const request = this.buildRequest({
+            nominate: true,
+            localUsername: pair.localCandidate.ufrag ?? this.localUsername,
+            remoteUsername: this.remoteUsername,
+            iceControlling: this.iceControlling,
+            localCandidate: pair.localCandidate,
+        });
+        pair.requestsSent++;
+        pair.protocol
+            .request(request, pair.remoteAddr, Buffer.from(this.remotePassword, "utf8"), this.checkRequestOptions(pair))
+            .then(() => {
+            if (this.isStaleNomination(pair, generation)) {
+                return;
+            }
+            pair.responsesReceived++;
+            pair.nominated = true;
+            this.nominating = false;
+            this.checkComplete(pair);
+        }, (error) => {
+            if (this.isStaleNomination(pair, generation)) {
+                return;
+            }
+            log("tcp nomination failed", pair.toJSON(), error);
+            this.nominating = false;
+            pair.updateState(iceBase_1.CandidatePairState.FAILED);
+            this.checkComplete(pair);
+        });
+    }
+    /** The agent was closed or restarted while the nomination was in flight. */
+    isStaleNomination(pair, generation) {
+        return (this.state === "closed" ||
+            this.generation !== generation ||
+            !this.checkList.includes(pair));
+    }
     addPair(pair) {
         this.checkList.push(pair);
         this.sortCheckList();