@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/lib/peer/peerConnection.d.ts

@@ -0,0 +1,458 @@
+import type { RTCDataChannel } from './dataChannel.js';
+import { EventTarget } from './helper.js';
+import { type Address, Event, type InterfaceAddresses, type TlsConnectionOptions } from './imports/common.js';
+import type { CandidatePair, Message, Protocol } from './imports/ice.js';
+import { type MediaStream, type MediaStreamTrack, type RTCRtpCodecParameters, RTCRtpHeaderExtensionParameters, type RTCRtpReceiver, type RTCRtpSender, type RTCRtpSenderOptions, type RTCRtpTransceiver, type TransceiverOptions } from './media/index.js';
+import { type RTCStatsReport } from './media/stats.js';
+import { type BundlePolicy, type GroupDescription, type RTCSessionDescription, SessionDescription } from './sdp.js';
+import { type MLineReuse, type RTCSessionDescriptionInit } from './sdpManager.js';
+import type { DtlsKeys, RTCCertificate, RTCDtlsTransport } from './transport/dtls.js';
+import type { RTCIceCandidate, RTCIceCandidateInit, RTCIceTransport } from './transport/ice.js';
+import { type RTCSctpTransport } from './transport/sctp.js';
+import type { Kind, RTCSignalingState } from './types/domain.js';
+import type { Callback, CallbackWithValue } from './types/util.js';
+/**
+ * W3C compatibility notes kept near the public RTCPeerConnection surface so the
+ * reviewable diff does not depend on external PR text.
+ *
+ * - `current/pending*Description`, `canTrickleIceCandidates`, `sctp`,
+ *   `addIceCandidate(null)`, and `RTCConfiguration` round-trip behavior are
+ *   implemented here and covered by `tests/wpt/peerConnectionApiCompatibility.test.ts`.
+ * - `addIceCandidate()` also validates `sdpMid` / `sdpMLineIndex` /
+ *   `usernameFragment` against the applied remote description and appends
+ *   candidates or end-of-candidates markers to the corresponding m-section.
+ *   The public API keeps werift's historical pre-SRD buffering behavior, while
+ *   the WPT runner wraps the class to exercise strict spec rejection.
+ * - `bundlePolicy: "balanced"` is accepted for input compatibility but is
+ *   normalized to werift's `"max-compat"` behavior, so `getConfiguration()`
+ *   returns the normalized value.
+ * - `setLocalDescription()` keeps the historical `SessionDescription` return
+ *   value for non-rollback calls, while `{ type: "rollback" }` resolves `void`
+ *   to match the actual behavior without pretending to return a description.
+ * - API reference markdown is regenerated with `cd packages/webrtc && npm run doc`.
+ *   The generated output lives under `packages/webrtc/doc/`; compatibility
+ *   notes remain here and in the package README so review context is visible
+ *   even when generated docs are not committed in the same change.
+ */
+export declare class RTCPeerConnection extends EventTarget {
+    readonly id: string;
+    readonly cname: string;
+    config: Required<PeerConfig>;
+    signalingState: RTCSignalingState;
+    negotiationneeded: boolean;
+    /**同じ tick の複数の変更で negotiationneeded を重複発火しないための予約フラグ */
+    private negotiationneededScheduled;
+    /**交渉が必要な変更の通し番号 */
+    private negotiationChangeSeq;
+    /**answer まで確定した local offer が反映している変更の通し番号 */
+    private negotiatedChangeSeq;
+    /**適用中の local offer が反映している変更の通し番号 (rollback で破棄) */
+    private pendingOfferChangeSeq?;
+    private lastCreatedOfferChangeSeq;
+    needRestart: boolean;
+    private readonly router;
+    private readonly sdpManager;
+    private readonly transceiverManager;
+    private readonly sctpManager;
+    private readonly secureManager;
+    private isClosed;
+    private shouldNegotiationneeded;
+    private lastCreatedAnswer?;
+    private lastCreatedOffer?;
+    private readonly pendingRemoteCandidates;
+    readonly iceGatheringStateChange: Event<["new" | "complete" | "gathering"]>;
+    readonly iceConnectionStateChange: Event<["disconnected" | "connected" | "failed" | "closed" | "new" | "completed" | "checking"]>;
+    readonly signalingStateChange: Event<["stable" | "closed" | "have-local-offer" | "have-local-pranswer" | "have-remote-offer" | "have-remote-pranswer"]>;
+    readonly connectionStateChange: Event<["disconnected" | "connected" | "failed" | "closed" | "connecting" | "new"]>;
+    readonly onDataChannel: Event<[RTCDataChannel]>;
+    readonly onRemoteTransceiverAdded: Event<[RTCRtpTransceiver]>;
+    readonly onTransceiverAdded: Event<[RTCRtpTransceiver]>;
+    readonly onIceCandidate: Event<[RTCIceCandidate | undefined]>;
+    readonly onNegotiationneeded: Event<[]>;
+    readonly onTrack: Event<[MediaStreamTrack]>;
+    private readonly eventHandlers;
+    get ondatachannel(): CallbackWithValue<RTCDataChannelEvent> | null;
+    set ondatachannel(value: CallbackWithValue<RTCDataChannelEvent> | null);
+    get onicecandidate(): CallbackWithValue<RTCPeerConnectionIceEvent> | null;
+    set onicecandidate(value: CallbackWithValue<RTCPeerConnectionIceEvent> | null);
+    get onicecandidateerror(): CallbackWithValue<any> | null;
+    set onicecandidateerror(value: CallbackWithValue<any> | null);
+    get onicegatheringstatechange(): CallbackWithValue<any> | null;
+    set onicegatheringstatechange(value: CallbackWithValue<any> | null);
+    get onnegotiationneeded(): CallbackWithValue<any> | null;
+    set onnegotiationneeded(value: CallbackWithValue<any> | null);
+    get onsignalingstatechange(): CallbackWithValue<any> | null;
+    set onsignalingstatechange(value: CallbackWithValue<any> | null);
+    get ontrack(): CallbackWithValue<RTCTrackEvent> | null;
+    set ontrack(value: CallbackWithValue<RTCTrackEvent> | null);
+    get onconnectionstatechange(): Callback | null;
+    set onconnectionstatechange(value: Callback | null);
+    get oniceconnectionstatechange(): Callback | null;
+    set oniceconnectionstatechange(value: Callback | null);
+    constructor(config?: RTCPeerConnectionConfig);
+    get connectionState(): "disconnected" | "connected" | "failed" | "closed" | "connecting" | "new";
+    get iceConnectionState(): "disconnected" | "connected" | "failed" | "closed" | "new" | "completed" | "checking";
+    get iceGathererState(): "new" | "complete" | "gathering";
+    get iceGatheringState(): "new" | "complete" | "gathering";
+    get dtlsTransports(): RTCDtlsTransport[];
+    get sctpTransport(): RTCSctpTransport | undefined;
+    get sctp(): RTCSctpTransport | null;
+    get sctpRemotePort(): number | undefined;
+    get iceTransports(): RTCIceTransport[];
+    get extIdUriMap(): {
+        [id: number]: string;
+    };
+    get iceGeneration(): number;
+    get localDescription(): RTCSessionDescription | null;
+    get currentLocalDescription(): RTCSessionDescription | null;
+    get pendingLocalDescription(): RTCSessionDescription | null;
+    get remoteDescription(): RTCSessionDescription | null;
+    get currentRemoteDescription(): RTCSessionDescription | null;
+    get pendingRemoteDescription(): RTCSessionDescription | null;
+    get canTrickleIceCandidates(): boolean | null;
+    get remoteIsBundled(): GroupDescription | undefined;
+    /**@private */
+    get _localDescription(): SessionDescription | undefined;
+    /**@private */
+    get _remoteDescription(): SessionDescription | undefined;
+    getTransceivers(): RTCRtpTransceiver[];
+    getSenders(): RTCRtpSender[];
+    getReceivers(): RTCRtpReceiver[];
+    setConfiguration(config: RTCPeerConnectionConfig): void;
+    getConfiguration(): {
+        codecs: {
+            audio: RTCRtpCodecParameters[] | undefined;
+            video: RTCRtpCodecParameters[] | undefined;
+        };
+        headerExtensions: {
+            audio: RTCRtpHeaderExtensionParameters[] | undefined;
+            video: RTCRtpHeaderExtensionParameters[] | undefined;
+        };
+        iceServers: {
+            urls: string | string[];
+            username?: string;
+            credential?: string;
+        }[];
+        icePortRange: [number, number] | undefined;
+        iceAdditionalHostAddresses: string[] | undefined;
+        dtls: {
+            keys?: DtlsKeys | undefined;
+        };
+        certificates: RTCCertificate[];
+        debug: {
+            inboundPacketLoss?: number | undefined;
+            outboundPacketLoss?: number | undefined;
+            receiverReportDelay?: number | undefined;
+            disableSendNack?: boolean | undefined;
+            disableRecvRetransmit?: boolean | undefined;
+        };
+        sctp: {
+            mtu: number;
+        };
+        pendingRtp: boolean | {
+            enabled?: boolean;
+            maxLength?: number;
+        };
+        iceTransportPolicy: "all" | "relay";
+        /** Advertise local ICE lite and operate in the controlled role. */
+        iceLite: boolean;
+        iceInterfaceAddresses: InterfaceAddresses | undefined;
+        iceUseIpv4: boolean;
+        iceUseIpv6: boolean;
+        iceUseTcp: boolean;
+        /** Gather passive (listening) TCP host candidates. Defaults to true. */
+        iceTcpPassive: boolean;
+        /**
+       * Seconds to wait for server-reflexive candidates while gathering.
+       * Defaults to 5 when undefined.
+       */
+        iceStunGatherTimeout: number | undefined;
+        /**
+       * Seconds to wait for a TURN TCP/TLS connection to be established.
+       * Defaults to 8 when undefined.
+       */
+        iceTurnConnectTimeout: number | undefined;
+        turnTransport: "udp" | "tcp" | "tls" | undefined;
+        turnTlsOptions: TlsConnectionOptions | undefined;
+        /**
+       * Preferred IP family of the TURN/UDP socket, applied only when the TURN
+       * server is a hostname. Ignored for an IP literal server, whose own family
+       * always selects the socket. Defaults to 4 when undefined.
+       */
+        turnUdpFamily: 4 | 6 | undefined;
+        /** @deprecated Prefer turn URL transport parameters or turnTransport. */
+        forceTurnTCP: boolean;
+        /** such as google cloud run */
+        iceUseLinkLocalAddress: boolean | undefined;
+        /** If provided, is called on each STUN request.
+       * Return `true` if a STUN response should be sent, false if it should be skipped. */
+        iceFilterStunResponse: ((message: Message, addr: Address, protocol: Protocol) => boolean) | undefined;
+        iceFilterCandidatePair: ((pair: CandidatePair) => boolean) | undefined;
+        icePasswordPrefix: string | undefined;
+        bundlePolicy: BundlePolicy;
+        rtcpMuxPolicy: "require";
+        iceCandidatePoolSize: number;
+        midSuffix: boolean;
+        /** Advertised local SCTP max-message-size in SDP. Use 0 for unlimited. */
+        maxMessageSize: number;
+        /**
+       * How local SDP marks inactive / stopped m-lines. Cannot be changed after construction.
+       * - `"compatible"` (default): an accepted `inactive` m-line keeps a non-zero port.
+       *   Only rejected (no common codec / remote port 0) or stopped m-lines use port 0,
+       *   and only those negotiated port 0 positions are reused by new transceivers.
+       * - `"aggressive"`: legacy behavior. `inactive` m-lines are also written with port 0.
+       */
+        mLineReuse: MLineReuse;
+    };
+    /**
+     * The header extensions of a media not negotiated yet: the ones configured, with the ids the connection negotiated
+     * for them in its other media (an extension has one id in all the media of a bundle: a browser refuses another one),
+     * else their configured ids when not taken by another extension, else free ones
+     */
+    private headerExtensionsFor;
+    createOffer({ iceRestart }?: {
+        iceRestart?: boolean;
+    }): Promise<RTCSessionDescription>;
+    private createSctpTransport;
+    createDataChannel(label: string, options?: Partial<{
+        maxPacketLifeTime?: number;
+        protocol: string;
+        maxRetransmits?: number;
+        ordered: boolean;
+        negotiated: boolean;
+        id?: number;
+    }>): RTCDataChannel;
+    removeTrack(sender: RTCRtpSender): void;
+    /**交渉が必要な変更を記録し、negotiationneeded を予約する */
+    private needNegotiation;
+    /**未交渉の変更が残っていれば negotiationneeded を予約する (stable 復帰時の再判定にも使う) */
+    private scheduleNegotiationneeded;
+    private invalidateLastCreatedDescriptions;
+    private waitForPendingDescriptionTask;
+    private findOrCreateTransport;
+    /**
+   * @param inheritCredentials false の場合は BUNDLE 外の独立 transport として
+   * 既存 transport と異なる ICE credentials を使う
+   */
+    private createDtlsTransport;
+    /**
+   * local candidate の sdpMid / sdpMLineIndex を、その ICE transport を実際に
+   * 所有する受け入れ済み m-line (BUNDLE なら tag) に合わせる。
+   */
+    private resolveLocalCandidateOwner;
+    /**
+   * answer 確定後の stopping transceiver を整理する。
+   * @returns port 0 を自分の offer で交渉すべき transceiver が残っているか
+   */
+    private settleStoppingTransceivers;
+    /**停止した transceiver の transport のうち、live な利用者がいないものを閉じる */
+    private closeIdleTransports;
+    setLocalDescription(sessionDescription: {
+        type: 'rollback';
+    }): Promise<void>;
+    setLocalDescription(sessionDescription?: RTCLocalSessionDescriptionInit): Promise<SessionDescription>;
+    private gatherCandidates;
+    addIceCandidate(candidateMessage?: RTCIceCandidate | RTCIceCandidateInit | null): Promise<void>;
+    private applyRemoteIceCandidate;
+    private flushPendingRemoteCandidates;
+    private connect;
+    restartIce(): void;
+    setRemoteDescription(sessionDescription: RTCSessionDescriptionInit): Promise<void>;
+    /**
+   * remote answer / pranswer の検証 (offerer 側、状態を変更する前に実行する)。
+   * local offer で 1 つの transport を共有した m-line を、answer が同じ BUNDLE group に置かずに
+   * 異なる ICE credentials で受け入れることはできない (RFC 8843 7.3.2)。共有 transport は分割できず、
+   * 新しい transport を作ると offer で渡した ICE credentials とも一致しなくなる。
+   * group の記述が MID と一致しなくても remote の ICE credentials が同じなら、同じ transport のまま扱う。
+   */
+    private assertAnswerKeepsSharedTransports;
+    /**
+   * remote m-line に対応する transceiver を探す。MID の一致を優先し、
+   * 未関連付け transceiver は同じ offer 内で異なる m-line に割り当てる。
+   */
+    private findTransceiverForRemoteMedia;
+    /**
+   * remote offer / answer の m-line 用に transceiver を作る。
+   * 同じ位置に停止済みの旧 transceiver があれば、それを復活させず新しい receiver/router で置き換える。
+   */
+    private addRemoteTransceiver;
+    addTransceiver(trackOrKind: Kind | MediaStreamTrack, options?: Partial<TransceiverOptions>): RTCRtpTransceiver;
+    addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender;
+    /**
+     * Whether addTrack may give a track of its kind to a transceiver, rather than adding one
+     * @param transceiver
+     */
+    reusableForTrack(transceiver: RTCRtpTransceiver): boolean;
+    /**
+     * addTrack, on the transceiver chosen already (by the main thread, for a connection served in a worker thread) if
+     * it may still take the track, else on a new one, as for null
+     * @param chosen
+     * @param track
+     * @param streams
+     */
+    addTrackOn(chosen: RTCRtpTransceiver | null | undefined, track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender;
+    createAnswer(): Promise<RTCSessionDescription>;
+    private assertNotClosed;
+    private stableSctp?;
+    /**
+   * The signaling state is stable: the associations of the transceivers and of the data channels are kept, for a
+   * rollback of the next local offer
+   */
+    private markStable;
+    /**
+   * A local offer is rolled back: the transceivers and the data channels are associated as before it
+   */
+    private rollbackLocalOffer;
+    private setSignalingState;
+    private createPeerConnectionStats;
+    getStats(selector?: MediaStreamTrack | null): Promise<RTCStatsReport>;
+    close(): Promise<void>;
+    private completePeerEvents;
+}
+export type DebugConfig = Partial<{
+    /**% */
+    inboundPacketLoss: number;
+    /**% */
+    outboundPacketLoss: number;
+    /**ms */
+    receiverReportDelay: number;
+    disableSendNack: boolean;
+    disableRecvRetransmit: boolean;
+}>;
+export interface PeerConfig {
+    codecs: Partial<{
+        /**
+         * When specifying a codec with a fixed payloadType such as PCMU,
+         * it is necessary to set the correct PayloadType in RTCRtpCodecParameters in advance.
+         */
+        audio: RTCRtpCodecParameters[];
+        video: RTCRtpCodecParameters[];
+    }>;
+    headerExtensions: Partial<{
+        audio: RTCRtpHeaderExtensionParameters[];
+        video: RTCRtpHeaderExtensionParameters[];
+    }>;
+    iceTransportPolicy: 'all' | 'relay';
+    /** Advertise local ICE lite and operate in the controlled role. */
+    iceLite: boolean;
+    iceServers: RTCIceServer[];
+    /**Minimum port and Maximum port must not be the same value */
+    icePortRange: [number, number] | undefined;
+    iceInterfaceAddresses: InterfaceAddresses | undefined;
+    /** Add additional host (local) addresses to use for candidate gathering.
+   * Notably, you can include hosts that are normally excluded, such as loopback, tun interfaces, etc.
+   */
+    iceAdditionalHostAddresses: string[] | undefined;
+    iceUseIpv4: boolean;
+    iceUseIpv6: boolean;
+    iceUseTcp: boolean;
+    /** Gather passive (listening) TCP host candidates. Defaults to true. */
+    iceTcpPassive: boolean;
+    /**
+   * Seconds to wait for server-reflexive candidates while gathering.
+   * Defaults to 5 when undefined.
+   */
+    iceStunGatherTimeout: number | undefined;
+    /**
+   * Seconds to wait for a TURN TCP/TLS connection to be established.
+   * Defaults to 8 when undefined.
+   */
+    iceTurnConnectTimeout: number | undefined;
+    turnTransport: 'udp' | 'tcp' | 'tls' | undefined;
+    turnTlsOptions: TlsConnectionOptions | undefined;
+    /**
+   * Preferred IP family of the TURN/UDP socket, applied only when the TURN
+   * server is a hostname. Ignored for an IP literal server, whose own family
+   * always selects the socket. Defaults to 4 when undefined.
+   */
+    turnUdpFamily: 4 | 6 | undefined;
+    /** @deprecated Prefer turn URL transport parameters or turnTransport. */
+    forceTurnTCP: boolean;
+    /** such as google cloud run */
+    iceUseLinkLocalAddress: boolean | undefined;
+    /** If provided, is called on each STUN request.
+   * Return `true` if a STUN response should be sent, false if it should be skipped. */
+    iceFilterStunResponse: ((message: Message, addr: Address, protocol: Protocol) => boolean) | undefined;
+    iceFilterCandidatePair: ((pair: CandidatePair) => boolean) | undefined;
+    dtls: Partial<{
+        keys: DtlsKeys;
+    }>;
+    icePasswordPrefix: string | undefined;
+    bundlePolicy: BundlePolicy;
+    rtcpMuxPolicy: 'require';
+    iceCandidatePoolSize: number;
+    certificates: RTCCertificate[];
+    debug: DebugConfig;
+    midSuffix: boolean;
+    /** Advertised local SCTP max-message-size in SDP. Use 0 for unlimited. */
+    maxMessageSize: number;
+    /** SCTP outbound packet MTU used for DATA chunk fragmentation. */
+    sctp: {
+        mtu: number;
+    };
+    /**
+   * Queue outbound RTP on each sender until DTLS is connected.
+   * Disabled by default. Pass `true` or `{ enabled: true, maxLength }` to buffer.
+   */
+    pendingRtp: NonNullable<RTCRtpSenderOptions['pendingRtp']>;
+    /**
+   * How local SDP marks inactive / stopped m-lines. Cannot be changed after construction.
+   * - `"compatible"` (default): an accepted `inactive` m-line keeps a non-zero port.
+   *   Only rejected (no common codec / remote port 0) or stopped m-lines use port 0,
+   *   and only those negotiated port 0 positions are reused by new transceivers.
+   * - `"aggressive"`: legacy behavior. `inactive` m-lines are also written with port 0.
+   */
+    mLineReuse: MLineReuse;
+}
+export declare const findCodecByMimeType: (codecs: RTCRtpCodecParameters[], target: RTCRtpCodecParameters) => RTCRtpCodecParameters | undefined;
+export type RTCIceServer = {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+};
+export type RTCBundlePolicy = 'balanced' | 'max-compat' | 'max-bundle';
+export type RTCRtcpMuxPolicy = 'require';
+export interface RTCSctpConfiguration {
+    /** SCTP outbound packet MTU used for DATA chunk fragmentation. Defaults to 1191. */
+    mtu?: number;
+}
+export interface RTCConfiguration {
+    iceServers?: RTCIceServer[];
+    iceTransportPolicy?: PeerConfig['iceTransportPolicy'];
+    bundlePolicy?: RTCBundlePolicy;
+    rtcpMuxPolicy?: RTCRtcpMuxPolicy;
+    iceCandidatePoolSize?: number;
+    certificates?: RTCCertificate[];
+}
+export interface RTCLocalSessionDescriptionInit extends RTCSessionDescriptionInit {
+    type?: Exclude<RTCSessionDescriptionInit['type'], 'rollback'> | 'rollback';
+}
+type RTCPeerConnectionRTCConfiguration = Omit<RTCConfiguration, 'bundlePolicy'> & {
+    bundlePolicy?: PeerConfig['bundlePolicy'] | RTCBundlePolicy;
+};
+export type RTCPeerConnectionConfig = Partial<Omit<PeerConfig, 'bundlePolicy' | 'rtcpMuxPolicy' | 'iceCandidatePoolSize' | 'certificates' | 'sctp'>> & RTCPeerConnectionRTCConfiguration & {
+    sctp?: RTCSctpConfiguration;
+};
+export declare const defaultPeerConfig: PeerConfig;
+export declare class RTCTrackEvent {
+    readonly type = "track";
+    readonly track: MediaStreamTrack;
+    readonly streams: MediaStream[];
+    readonly transceiver: RTCRtpTransceiver;
+    readonly receiver: RTCRtpReceiver;
+    constructor(init: {
+        track: MediaStreamTrack;
+        streams: MediaStream[];
+        transceiver: RTCRtpTransceiver;
+        receiver: RTCRtpReceiver;
+    });
+}
+export interface RTCDataChannelEvent {
+    type?: 'datachannel';
+    channel: RTCDataChannel;
+}
+export interface RTCPeerConnectionIceEvent {
+    type?: 'icecandidate';
+    candidate?: RTCIceCandidate;
+}
+export {};