diff --git a/.changeset/prewarm_signalling_connection.md b/.changeset/prewarm_signalling_connection.md new file mode 100644 index 0000000000..ee8f1169cb --- /dev/null +++ b/.changeset/prewarm_signalling_connection.md @@ -0,0 +1,12 @@ +--- +livekit-net: minor +livekit-signaling: minor +livekit: minor +livekit-ffi: minor +livekit-api: patch +livekit-capture: patch +livekit-telemetry: patch +livekit-token-source: patch +--- + +Add `PrewarmedConnection` and `RoomOptions::prewarmed_connection` to open the signalling TCP/TLS connection ahead of `Room::connect`, so the connect only performs the WebSocket upgrade; exposed over FFI through `PrewarmRequest` and `RoomOptions.prewarmed_connection_handle`. diff --git a/Cargo.lock b/Cargo.lock index ea227ea3fb..09fd3c099a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3948,13 +3948,16 @@ dependencies = [ "futures-util", "http 1.4.2", "log", + "native-tls", "reqwest 0.12.28", "rustls-native-certs", "tokio", + "tokio-native-tls", "tokio-rustls", "tokio-tungstenite", "uniffi", "url", + "webpki-roots 0.26.11", ] [[package]] diff --git a/livekit-ffi-node-bindings/proto/ffi_pb.d.ts b/livekit-ffi-node-bindings/proto/ffi_pb.d.ts index b57869975e..abf250e31b 100644 --- a/livekit-ffi-node-bindings/proto/ffi_pb.d.ts +++ b/livekit-ffi-node-bindings/proto/ffi_pb.d.ts @@ -19,7 +19,7 @@ import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf"; import { Message, proto2 } from "@bufbuild/protobuf"; -import type { ConnectCallback, ConnectRequest, ConnectResponse, DisconnectCallback, DisconnectRequest, DisconnectResponse, EditChatMessageRequest, GetSessionStatsCallback, GetSessionStatsRequest, GetSessionStatsResponse, PublishDataCallback, PublishDataRequest, PublishDataResponse, PublishSipDtmfCallback, PublishSipDtmfRequest, PublishSipDtmfResponse, PublishTrackCallback, PublishTrackRequest, PublishTrackResponse, PublishTranscriptionCallback, PublishTranscriptionRequest, PublishTranscriptionResponse, ReadyForRoomEventRequest, ReadyForRoomEventResponse, RoomEvent, SendChatMessageCallback, SendChatMessageRequest, SendChatMessageResponse, SendStreamChunkCallback, SendStreamChunkRequest, SendStreamChunkResponse, SendStreamHeaderCallback, SendStreamHeaderRequest, SendStreamHeaderResponse, SendStreamTrailerCallback, SendStreamTrailerRequest, SendStreamTrailerResponse, SetDataChannelBufferedAmountLowThresholdRequest, SetDataChannelBufferedAmountLowThresholdResponse, SetLocalAttributesCallback, SetLocalAttributesRequest, SetLocalAttributesResponse, SetLocalMetadataCallback, SetLocalMetadataRequest, SetLocalMetadataResponse, SetLocalNameCallback, SetLocalNameRequest, SetLocalNameResponse, SetSubscribedRequest, SetSubscribedResponse, SimulateScenarioCallback, SimulateScenarioRequest, SimulateScenarioResponse, UnpublishTrackCallback, UnpublishTrackRequest, UnpublishTrackResponse } from "./room_pb.js"; +import type { ConnectCallback, ConnectRequest, ConnectResponse, DisconnectCallback, DisconnectRequest, DisconnectResponse, EditChatMessageRequest, GetSessionStatsCallback, GetSessionStatsRequest, GetSessionStatsResponse, PrewarmCallback, PrewarmedConnectionAliveRequest, PrewarmedConnectionAliveResponse, PrewarmRequest, PrewarmResponse, PublishDataCallback, PublishDataRequest, PublishDataResponse, PublishSipDtmfCallback, PublishSipDtmfRequest, PublishSipDtmfResponse, PublishTrackCallback, PublishTrackRequest, PublishTrackResponse, PublishTranscriptionCallback, PublishTranscriptionRequest, PublishTranscriptionResponse, ReadyForRoomEventRequest, ReadyForRoomEventResponse, RoomEvent, SendChatMessageCallback, SendChatMessageRequest, SendChatMessageResponse, SendStreamChunkCallback, SendStreamChunkRequest, SendStreamChunkResponse, SendStreamHeaderCallback, SendStreamHeaderRequest, SendStreamHeaderResponse, SendStreamTrailerCallback, SendStreamTrailerRequest, SendStreamTrailerResponse, SetDataChannelBufferedAmountLowThresholdRequest, SetDataChannelBufferedAmountLowThresholdResponse, SetLocalAttributesCallback, SetLocalAttributesRequest, SetLocalAttributesResponse, SetLocalMetadataCallback, SetLocalMetadataRequest, SetLocalMetadataResponse, SetLocalNameCallback, SetLocalNameRequest, SetLocalNameResponse, SetSubscribedRequest, SetSubscribedResponse, SimulateScenarioCallback, SimulateScenarioRequest, SimulateScenarioResponse, UnpublishTrackCallback, UnpublishTrackRequest, UnpublishTrackResponse } from "./room_pb.js"; import type { CreateAudioTrackRequest, CreateAudioTrackResponse, CreateVideoTrackRequest, CreateVideoTrackResponse, EnableRemoteTrackRequest, EnableRemoteTrackResponse, GetStatsCallback, GetStatsRequest, GetStatsResponse, LocalTrackMuteRequest, LocalTrackMuteResponse, SetTrackSubscriptionPermissionsRequest, SetTrackSubscriptionPermissionsResponse, TrackEvent } from "./track_pb.js"; import type { CaptureEncodedVideoFrameRequest, CaptureEncodedVideoFrameResponse, CaptureVideoFrameRequest, CaptureVideoFrameResponse, NewVideoSourceRequest, NewVideoSourceResponse, NewVideoStreamRequest, NewVideoStreamResponse, TakeEncodedVideoSourceFeedbackRequest, TakeEncodedVideoSourceFeedbackResponse, VideoConvertRequest, VideoConvertResponse, VideoStreamEvent, VideoStreamFromParticipantRequest, VideoStreamFromParticipantResponse } from "./video_frame_pb.js"; import type { ApmProcessReverseStreamRequest, ApmProcessReverseStreamResponse, ApmProcessStreamRequest, ApmProcessStreamResponse, ApmSetStreamDelayRequest, ApmSetStreamDelayResponse, AudioStreamEvent, AudioStreamFromParticipantRequest, AudioStreamFromParticipantResponse, CaptureAudioFrameCallback, CaptureAudioFrameRequest, CaptureAudioFrameResponse, ClearAudioBufferRequest, ClearAudioBufferResponse, FlushSoxResamplerRequest, FlushSoxResamplerResponse, GetAudioDevicesRequest, GetAudioDevicesResponse, LoadAudioFilterPluginRequest, LoadAudioFilterPluginResponse, NewApmRequest, NewApmResponse, NewAudioResamplerRequest, NewAudioResamplerResponse, NewAudioSourceRequest, NewAudioSourceResponse, NewAudioStreamRequest, NewAudioStreamResponse, NewPlatformAudioRequest, NewPlatformAudioResponse, NewSoxResamplerRequest, NewSoxResamplerResponse, PushSoxResamplerRequest, PushSoxResamplerResponse, RemixAndResampleRequest, RemixAndResampleResponse, SetPlayoutDeviceRequest, SetPlayoutDeviceResponse, SetRecordingDeviceRequest, SetRecordingDeviceResponse, StartRecordingRequest, StartRecordingResponse, StopRecordingRequest, StopRecordingResponse } from "./audio_frame_pb.js"; @@ -652,6 +652,20 @@ export declare class FfiRequest extends Message { */ value: JoinCaptureRequest; case: "joinCapture"; + } | { + /** + * Signalling transport prewarm + * + * @generated from field: livekit.proto.PrewarmRequest prewarm = 93; + */ + value: PrewarmRequest; + case: "prewarm"; + } | { + /** + * @generated from field: livekit.proto.PrewarmedConnectionAliveRequest prewarmed_connection_alive = 94; + */ + value: PrewarmedConnectionAliveRequest; + case: "prewarmedConnectionAlive"; } | { case: undefined; value?: undefined }; constructor(data?: PartialMessage); @@ -1254,6 +1268,20 @@ export declare class FfiResponse extends Message { */ value: JoinCaptureResponse; case: "joinCapture"; + } | { + /** + * Signalling transport prewarm + * + * @generated from field: livekit.proto.PrewarmResponse prewarm = 93; + */ + value: PrewarmResponse; + case: "prewarm"; + } | { + /** + * @generated from field: livekit.proto.PrewarmedConnectionAliveResponse prewarmed_connection_alive = 94; + */ + value: PrewarmedConnectionAliveResponse; + case: "prewarmedConnectionAlive"; } | { case: undefined; value?: undefined }; constructor(data?: PartialMessage); @@ -1576,6 +1604,14 @@ export declare class FfiEvent extends Message { */ value: JoinCaptureCallback; case: "joinCapture"; + } | { + /** + * Signalling transport prewarm + * + * @generated from field: livekit.proto.PrewarmCallback prewarm = 50; + */ + value: PrewarmCallback; + case: "prewarm"; } | { case: undefined; value?: undefined }; constructor(data?: PartialMessage); diff --git a/livekit-ffi-node-bindings/proto/ffi_pb.js b/livekit-ffi-node-bindings/proto/ffi_pb.js index 13234b355e..e630ba777e 100644 --- a/livekit-ffi-node-bindings/proto/ffi_pb.js +++ b/livekit-ffi-node-bindings/proto/ffi_pb.js @@ -21,7 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true }); const { proto2 } = require("@bufbuild/protobuf"); -const { ConnectCallback, ConnectRequest, ConnectResponse, DisconnectCallback, DisconnectRequest, DisconnectResponse, EditChatMessageRequest, GetSessionStatsCallback, GetSessionStatsRequest, GetSessionStatsResponse, PublishDataCallback, PublishDataRequest, PublishDataResponse, PublishSipDtmfCallback, PublishSipDtmfRequest, PublishSipDtmfResponse, PublishTrackCallback, PublishTrackRequest, PublishTrackResponse, PublishTranscriptionCallback, PublishTranscriptionRequest, PublishTranscriptionResponse, ReadyForRoomEventRequest, ReadyForRoomEventResponse, RoomEvent, SendChatMessageCallback, SendChatMessageRequest, SendChatMessageResponse, SendStreamChunkCallback, SendStreamChunkRequest, SendStreamChunkResponse, SendStreamHeaderCallback, SendStreamHeaderRequest, SendStreamHeaderResponse, SendStreamTrailerCallback, SendStreamTrailerRequest, SendStreamTrailerResponse, SetDataChannelBufferedAmountLowThresholdRequest, SetDataChannelBufferedAmountLowThresholdResponse, SetLocalAttributesCallback, SetLocalAttributesRequest, SetLocalAttributesResponse, SetLocalMetadataCallback, SetLocalMetadataRequest, SetLocalMetadataResponse, SetLocalNameCallback, SetLocalNameRequest, SetLocalNameResponse, SetSubscribedRequest, SetSubscribedResponse, SimulateScenarioCallback, SimulateScenarioRequest, SimulateScenarioResponse, UnpublishTrackCallback, UnpublishTrackRequest, UnpublishTrackResponse } = require("./room_pb.js"); +const { ConnectCallback, ConnectRequest, ConnectResponse, DisconnectCallback, DisconnectRequest, DisconnectResponse, EditChatMessageRequest, GetSessionStatsCallback, GetSessionStatsRequest, GetSessionStatsResponse, PrewarmCallback, PrewarmedConnectionAliveRequest, PrewarmedConnectionAliveResponse, PrewarmRequest, PrewarmResponse, PublishDataCallback, PublishDataRequest, PublishDataResponse, PublishSipDtmfCallback, PublishSipDtmfRequest, PublishSipDtmfResponse, PublishTrackCallback, PublishTrackRequest, PublishTrackResponse, PublishTranscriptionCallback, PublishTranscriptionRequest, PublishTranscriptionResponse, ReadyForRoomEventRequest, ReadyForRoomEventResponse, RoomEvent, SendChatMessageCallback, SendChatMessageRequest, SendChatMessageResponse, SendStreamChunkCallback, SendStreamChunkRequest, SendStreamChunkResponse, SendStreamHeaderCallback, SendStreamHeaderRequest, SendStreamHeaderResponse, SendStreamTrailerCallback, SendStreamTrailerRequest, SendStreamTrailerResponse, SetDataChannelBufferedAmountLowThresholdRequest, SetDataChannelBufferedAmountLowThresholdResponse, SetLocalAttributesCallback, SetLocalAttributesRequest, SetLocalAttributesResponse, SetLocalMetadataCallback, SetLocalMetadataRequest, SetLocalMetadataResponse, SetLocalNameCallback, SetLocalNameRequest, SetLocalNameResponse, SetSubscribedRequest, SetSubscribedResponse, SimulateScenarioCallback, SimulateScenarioRequest, SimulateScenarioResponse, UnpublishTrackCallback, UnpublishTrackRequest, UnpublishTrackResponse } = require("./room_pb.js"); const { CreateAudioTrackRequest, CreateAudioTrackResponse, CreateVideoTrackRequest, CreateVideoTrackResponse, EnableRemoteTrackRequest, EnableRemoteTrackResponse, GetStatsCallback, GetStatsRequest, GetStatsResponse, LocalTrackMuteRequest, LocalTrackMuteResponse, SetTrackSubscriptionPermissionsRequest, SetTrackSubscriptionPermissionsResponse, TrackEvent } = require("./track_pb.js"); const { CaptureEncodedVideoFrameRequest, CaptureEncodedVideoFrameResponse, CaptureVideoFrameRequest, CaptureVideoFrameResponse, NewVideoSourceRequest, NewVideoSourceResponse, NewVideoStreamRequest, NewVideoStreamResponse, TakeEncodedVideoSourceFeedbackRequest, TakeEncodedVideoSourceFeedbackResponse, VideoConvertRequest, VideoConvertResponse, VideoStreamEvent, VideoStreamFromParticipantRequest, VideoStreamFromParticipantResponse } = require("./video_frame_pb.js"); const { ApmProcessReverseStreamRequest, ApmProcessReverseStreamResponse, ApmProcessStreamRequest, ApmProcessStreamResponse, ApmSetStreamDelayRequest, ApmSetStreamDelayResponse, AudioStreamEvent, AudioStreamFromParticipantRequest, AudioStreamFromParticipantResponse, CaptureAudioFrameCallback, CaptureAudioFrameRequest, CaptureAudioFrameResponse, ClearAudioBufferRequest, ClearAudioBufferResponse, FlushSoxResamplerRequest, FlushSoxResamplerResponse, GetAudioDevicesRequest, GetAudioDevicesResponse, LoadAudioFilterPluginRequest, LoadAudioFilterPluginResponse, NewApmRequest, NewApmResponse, NewAudioResamplerRequest, NewAudioResamplerResponse, NewAudioSourceRequest, NewAudioSourceResponse, NewAudioStreamRequest, NewAudioStreamResponse, NewPlatformAudioRequest, NewPlatformAudioResponse, NewSoxResamplerRequest, NewSoxResamplerResponse, PushSoxResamplerRequest, PushSoxResamplerResponse, RemixAndResampleRequest, RemixAndResampleResponse, SetPlayoutDeviceRequest, SetPlayoutDeviceResponse, SetRecordingDeviceRequest, SetRecordingDeviceResponse, StartRecordingRequest, StartRecordingResponse, StopRecordingRequest, StopRecordingResponse } = require("./audio_frame_pb.js"); @@ -146,6 +146,8 @@ const FfiRequest = /*@__PURE__*/ proto2.makeMessageType( { no: 89, name: "start_capture", kind: "message", T: StartCaptureRequest, oneof: "message" }, { no: 90, name: "stop_capture", kind: "message", T: StopCaptureRequest, oneof: "message" }, { no: 92, name: "join_capture", kind: "message", T: JoinCaptureRequest, oneof: "message" }, + { no: 93, name: "prewarm", kind: "message", T: PrewarmRequest, oneof: "message" }, + { no: 94, name: "prewarmed_connection_alive", kind: "message", T: PrewarmedConnectionAliveRequest, oneof: "message" }, ], ); @@ -247,6 +249,8 @@ const FfiResponse = /*@__PURE__*/ proto2.makeMessageType( { no: 89, name: "start_capture", kind: "message", T: StartCaptureResponse, oneof: "message" }, { no: 90, name: "stop_capture", kind: "message", T: StopCaptureResponse, oneof: "message" }, { no: 92, name: "join_capture", kind: "message", T: JoinCaptureResponse, oneof: "message" }, + { no: 93, name: "prewarm", kind: "message", T: PrewarmResponse, oneof: "message" }, + { no: 94, name: "prewarmed_connection_alive", kind: "message", T: PrewarmedConnectionAliveResponse, oneof: "message" }, ], ); @@ -307,6 +311,7 @@ const FfiEvent = /*@__PURE__*/ proto2.makeMessageType( { no: 46, name: "get_schema", kind: "message", T: GetSchemaCallback, oneof: "message" }, { no: 47, name: "new_capture_source", kind: "message", T: NewCaptureSourceCallback, oneof: "message" }, { no: 49, name: "join_capture", kind: "message", T: JoinCaptureCallback, oneof: "message" }, + { no: 50, name: "prewarm", kind: "message", T: PrewarmCallback, oneof: "message" }, ], ); diff --git a/livekit-ffi-node-bindings/proto/room_pb.d.ts b/livekit-ffi-node-bindings/proto/room_pb.d.ts index a02ee142a3..62d6b36339 100644 --- a/livekit-ffi-node-bindings/proto/room_pb.d.ts +++ b/livekit-ffi-node-bindings/proto/room_pb.d.ts @@ -19,12 +19,12 @@ import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf"; import { Message, proto2 } from "@bufbuild/protobuf"; +import type { FfiOwnedHandle } from "./handle_pb.js"; import type { DisconnectReason, OwnedParticipant, ParticipantInfo, ParticipantPermission } from "./participant_pb.js"; import type { FrameMetadataFeature, OwnedTrack, OwnedTrackPublication, TrackPublicationInfo, TrackSource } from "./track_pb.js"; import type { RtcStats } from "./stats_pb.js"; import type { VideoCodec } from "./video_frame_pb.js"; import type { E2eeOptions, EncryptionState } from "./e2ee_pb.js"; -import type { FfiOwnedHandle } from "./handle_pb.js"; import type { OwnedByteStreamReader, OwnedTextStreamReader } from "./data_stream_pb.js"; import type { OwnedRemoteDataTrack } from "./data_track_pb.js"; @@ -265,6 +265,156 @@ export declare enum DataPacketKind { KIND_RELIABLE = 1, } +/** + * Open a connection (TCP, plus TLS for wss) to a server ahead of a ConnectRequest. + * Pass the returned handle as RoomOptions.prewarmed_connection_handle so the + * connect only performs the WebSocket upgrade. The connection is used at most + * once; dropping the handle closes it. + * + * @generated from message livekit.proto.PrewarmRequest + */ +export declare class PrewarmRequest extends Message { + /** + * @generated from field: required string url = 1; + */ + url?: string; + + /** + * @generated from field: optional uint64 request_async_id = 2; + */ + requestAsyncId?: bigint; + + constructor(data?: PartialMessage); + + static readonly runtime: typeof proto2; + static readonly typeName = "livekit.proto.PrewarmRequest"; + static readonly fields: FieldList; + + static fromBinary(bytes: Uint8Array, options?: Partial): PrewarmRequest; + + static fromJson(jsonValue: JsonValue, options?: Partial): PrewarmRequest; + + static fromJsonString(jsonString: string, options?: Partial): PrewarmRequest; + + static equals(a: PrewarmRequest | PlainMessage | undefined, b: PrewarmRequest | PlainMessage | undefined): boolean; +} + +/** + * @generated from message livekit.proto.PrewarmResponse + */ +export declare class PrewarmResponse extends Message { + /** + * @generated from field: required uint64 async_id = 1; + */ + asyncId?: bigint; + + constructor(data?: PartialMessage); + + static readonly runtime: typeof proto2; + static readonly typeName = "livekit.proto.PrewarmResponse"; + static readonly fields: FieldList; + + static fromBinary(bytes: Uint8Array, options?: Partial): PrewarmResponse; + + static fromJson(jsonValue: JsonValue, options?: Partial): PrewarmResponse; + + static fromJsonString(jsonString: string, options?: Partial): PrewarmResponse; + + static equals(a: PrewarmResponse | PlainMessage | undefined, b: PrewarmResponse | PlainMessage | undefined): boolean; +} + +/** + * @generated from message livekit.proto.PrewarmCallback + */ +export declare class PrewarmCallback extends Message { + /** + * @generated from field: required uint64 async_id = 1; + */ + asyncId?: bigint; + + /** + * @generated from oneof livekit.proto.PrewarmCallback.message + */ + message: { + /** + * @generated from field: string error = 2; + */ + value: string; + case: "error"; + } | { + /** + * @generated from field: livekit.proto.FfiOwnedHandle connection = 3; + */ + value: FfiOwnedHandle; + case: "connection"; + } | { case: undefined; value?: undefined }; + + constructor(data?: PartialMessage); + + static readonly runtime: typeof proto2; + static readonly typeName = "livekit.proto.PrewarmCallback"; + static readonly fields: FieldList; + + static fromBinary(bytes: Uint8Array, options?: Partial): PrewarmCallback; + + static fromJson(jsonValue: JsonValue, options?: Partial): PrewarmCallback; + + static fromJsonString(jsonString: string, options?: Partial): PrewarmCallback; + + static equals(a: PrewarmCallback | PlainMessage | undefined, b: PrewarmCallback | PlainMessage | undefined): boolean; +} + +/** + * Whether a pre-warmed connection can still be used: not used yet, and not + * closed by the server. + * + * @generated from message livekit.proto.PrewarmedConnectionAliveRequest + */ +export declare class PrewarmedConnectionAliveRequest extends Message { + /** + * @generated from field: required uint64 connection_handle = 1; + */ + connectionHandle?: bigint; + + constructor(data?: PartialMessage); + + static readonly runtime: typeof proto2; + static readonly typeName = "livekit.proto.PrewarmedConnectionAliveRequest"; + static readonly fields: FieldList; + + static fromBinary(bytes: Uint8Array, options?: Partial): PrewarmedConnectionAliveRequest; + + static fromJson(jsonValue: JsonValue, options?: Partial): PrewarmedConnectionAliveRequest; + + static fromJsonString(jsonString: string, options?: Partial): PrewarmedConnectionAliveRequest; + + static equals(a: PrewarmedConnectionAliveRequest | PlainMessage | undefined, b: PrewarmedConnectionAliveRequest | PlainMessage | undefined): boolean; +} + +/** + * @generated from message livekit.proto.PrewarmedConnectionAliveResponse + */ +export declare class PrewarmedConnectionAliveResponse extends Message { + /** + * @generated from field: required bool alive = 1; + */ + alive?: boolean; + + constructor(data?: PartialMessage); + + static readonly runtime: typeof proto2; + static readonly typeName = "livekit.proto.PrewarmedConnectionAliveResponse"; + static readonly fields: FieldList; + + static fromBinary(bytes: Uint8Array, options?: Partial): PrewarmedConnectionAliveResponse; + + static fromJson(jsonValue: JsonValue, options?: Partial): PrewarmedConnectionAliveResponse; + + static fromJsonString(jsonString: string, options?: Partial): PrewarmedConnectionAliveResponse; + + static equals(a: PrewarmedConnectionAliveResponse | PlainMessage | undefined, b: PrewarmedConnectionAliveResponse | PlainMessage | undefined): boolean; +} + /** * Connect to a new LiveKit room * @@ -2121,6 +2271,14 @@ export declare class RoomOptions extends Message { */ otherSdks?: string; + /** + * Handle from a PrewarmCallback. The first signal connection attempt runs the + * WebSocket upgrade over it, or dials a fresh connection if it is unusable. + * + * @generated from field: optional uint64 prewarmed_connection_handle = 12; + */ + prewarmedConnectionHandle?: bigint; + constructor(data?: PartialMessage); static readonly runtime: typeof proto2; diff --git a/livekit-ffi-node-bindings/proto/room_pb.js b/livekit-ffi-node-bindings/proto/room_pb.js index 539db79d91..c4d9c9d9a2 100644 --- a/livekit-ffi-node-bindings/proto/room_pb.js +++ b/livekit-ffi-node-bindings/proto/room_pb.js @@ -21,12 +21,12 @@ Object.defineProperty(exports, "__esModule", { value: true }); const { proto2 } = require("@bufbuild/protobuf"); +const { FfiOwnedHandle } = require("./handle_pb.js"); const { DisconnectReason, OwnedParticipant, ParticipantInfo, ParticipantPermission } = require("./participant_pb.js"); const { FrameMetadataFeature, OwnedTrack, OwnedTrackPublication, TrackPublicationInfo, TrackSource } = require("./track_pb.js"); const { RtcStats } = require("./stats_pb.js"); const { VideoCodec } = require("./video_frame_pb.js"); const { E2eeOptions, EncryptionState } = require("./e2ee_pb.js"); -const { FfiOwnedHandle } = require("./handle_pb.js"); const { OwnedByteStreamReader, OwnedTextStreamReader } = require("./data_stream_pb.js"); const { OwnedRemoteDataTrack } = require("./data_track_pb.js"); @@ -143,6 +143,67 @@ const DataPacketKind = /*@__PURE__*/ proto2.makeEnum( ], ); +/** + * Open a connection (TCP, plus TLS for wss) to a server ahead of a ConnectRequest. + * Pass the returned handle as RoomOptions.prewarmed_connection_handle so the + * connect only performs the WebSocket upgrade. The connection is used at most + * once; dropping the handle closes it. + * + * @generated from message livekit.proto.PrewarmRequest + */ +const PrewarmRequest = /*@__PURE__*/ proto2.makeMessageType( + "livekit.proto.PrewarmRequest", + () => [ + { no: 1, name: "url", kind: "scalar", T: 9 /* ScalarType.STRING */, req: true }, + { no: 2, name: "request_async_id", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true }, + ], +); + +/** + * @generated from message livekit.proto.PrewarmResponse + */ +const PrewarmResponse = /*@__PURE__*/ proto2.makeMessageType( + "livekit.proto.PrewarmResponse", + () => [ + { no: 1, name: "async_id", kind: "scalar", T: 4 /* ScalarType.UINT64 */, req: true }, + ], +); + +/** + * @generated from message livekit.proto.PrewarmCallback + */ +const PrewarmCallback = /*@__PURE__*/ proto2.makeMessageType( + "livekit.proto.PrewarmCallback", + () => [ + { no: 1, name: "async_id", kind: "scalar", T: 4 /* ScalarType.UINT64 */, req: true }, + { no: 2, name: "error", kind: "scalar", T: 9 /* ScalarType.STRING */, oneof: "message" }, + { no: 3, name: "connection", kind: "message", T: FfiOwnedHandle, oneof: "message" }, + ], +); + +/** + * Whether a pre-warmed connection can still be used: not used yet, and not + * closed by the server. + * + * @generated from message livekit.proto.PrewarmedConnectionAliveRequest + */ +const PrewarmedConnectionAliveRequest = /*@__PURE__*/ proto2.makeMessageType( + "livekit.proto.PrewarmedConnectionAliveRequest", + () => [ + { no: 1, name: "connection_handle", kind: "scalar", T: 4 /* ScalarType.UINT64 */, req: true }, + ], +); + +/** + * @generated from message livekit.proto.PrewarmedConnectionAliveResponse + */ +const PrewarmedConnectionAliveResponse = /*@__PURE__*/ proto2.makeMessageType( + "livekit.proto.PrewarmedConnectionAliveResponse", + () => [ + { no: 1, name: "alive", kind: "scalar", T: 8 /* ScalarType.BOOL */, req: true }, + ], +); + /** * Connect to a new LiveKit room * @@ -807,6 +868,7 @@ const RoomOptions = /*@__PURE__*/ proto2.makeMessageType( { no: 9, name: "connect_timeout_ms", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true }, { no: 10, name: "data_stream", kind: "message", T: RoomDataStreamOptions, opt: true }, { no: 11, name: "other_sdks", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true }, + { no: 12, name: "prewarmed_connection_handle", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true }, ], ); @@ -1673,6 +1735,11 @@ exports.ContinualGatheringPolicy = ContinualGatheringPolicy; exports.ConnectionQuality = ConnectionQuality; exports.ConnectionState = ConnectionState; exports.DataPacketKind = DataPacketKind; +exports.PrewarmRequest = PrewarmRequest; +exports.PrewarmResponse = PrewarmResponse; +exports.PrewarmCallback = PrewarmCallback; +exports.PrewarmedConnectionAliveRequest = PrewarmedConnectionAliveRequest; +exports.PrewarmedConnectionAliveResponse = PrewarmedConnectionAliveResponse; exports.ConnectRequest = ConnectRequest; exports.ConnectResponse = ConnectResponse; exports.ConnectCallback = ConnectCallback; diff --git a/livekit-ffi/protocol/ffi.proto b/livekit-ffi/protocol/ffi.proto index 31d70854a2..e67f87aa2a 100644 --- a/livekit-ffi/protocol/ffi.proto +++ b/livekit-ffi/protocol/ffi.proto @@ -195,7 +195,11 @@ message FfiRequest { StopCaptureRequest stop_capture = 90; JoinCaptureRequest join_capture = 92; - // NEXT_ID: 93 + // Signalling transport prewarm + PrewarmRequest prewarm = 93; + PrewarmedConnectionAliveRequest prewarmed_connection_alive = 94; + + // NEXT_ID: 95 } } @@ -334,7 +338,11 @@ message FfiResponse { StopCaptureResponse stop_capture = 90; JoinCaptureResponse join_capture = 92; - // NEXT_ID: 93 + // Signalling transport prewarm + PrewarmResponse prewarm = 93; + PrewarmedConnectionAliveResponse prewarmed_connection_alive = 94; + + // NEXT_ID: 95 } } @@ -408,7 +416,10 @@ message FfiEvent { NewCaptureSourceCallback new_capture_source = 47; JoinCaptureCallback join_capture = 49; - // NEXT_ID: 50 + // Signalling transport prewarm + PrewarmCallback prewarm = 50; + + // NEXT_ID: 51 } } diff --git a/livekit-ffi/protocol/room.proto b/livekit-ffi/protocol/room.proto index eb7bdeeb89..e083b58ba2 100644 --- a/livekit-ffi/protocol/room.proto +++ b/livekit-ffi/protocol/room.proto @@ -26,6 +26,34 @@ import "stats.proto"; import "data_stream.proto"; import "data_track.proto"; +// Open a connection (TCP, plus TLS for wss) to a server ahead of a ConnectRequest. +// Pass the returned handle as RoomOptions.prewarmed_connection_handle so the +// connect only performs the WebSocket upgrade. The connection is used at most +// once; dropping the handle closes it. +message PrewarmRequest { + required string url = 1; + optional uint64 request_async_id = 2; +} +message PrewarmResponse { + required uint64 async_id = 1; +} +message PrewarmCallback { + required uint64 async_id = 1; + oneof message { + string error = 2; + FfiOwnedHandle connection = 3; + } +} + +// Whether a pre-warmed connection can still be used: not used yet, and not +// closed by the server. +message PrewarmedConnectionAliveRequest { + required uint64 connection_handle = 1; +} +message PrewarmedConnectionAliveResponse { + required bool alive = 1; +} + // Connect to a new LiveKit room message ConnectRequest { required string url = 1; @@ -402,6 +430,9 @@ message RoomOptions { // Comma separated list of additional LiveKit SDKs layered on top of this one, with versions, // e.g. "components-js:1.2.3,track-processors-js:1.2.3". Forwarded to ClientInfo.other_sdks. optional string other_sdks = 11; + // Handle from a PrewarmCallback. The first signal connection attempt runs the + // WebSocket upgrade over it, or dials a fresh connection if it is unusable. + optional uint64 prewarmed_connection_handle = 12; } // diff --git a/livekit-ffi/src/room_apis/server/mod.rs b/livekit-ffi/src/room_apis/server/mod.rs index 43a2dcd302..2a903dc63d 100644 --- a/livekit-ffi/src/room_apis/server/mod.rs +++ b/livekit-ffi/src/room_apis/server/mod.rs @@ -84,6 +84,7 @@ impl FfiHandle for AudioFrame<'static> {} impl FfiHandle for BoxVideoBuffer {} impl FfiHandle for Box<[u8]> {} impl FfiHandle for () {} +impl FfiHandle for livekit::PrewarmedConnection {} pub struct FfiServer { /// Store all Ffi handles inside an HashMap, if this isn't efficient enough diff --git a/livekit-ffi/src/room_apis/server/requests.rs b/livekit-ffi/src/room_apis/server/requests.rs index cc18e94b8e..d200820af4 100644 --- a/livekit-ffi/src/room_apis/server/requests.rs +++ b/livekit-ffi/src/room_apis/server/requests.rs @@ -19,7 +19,7 @@ use livekit::{ prelude::*, register_audio_filter_plugin, webrtc::{native::apm, native::audio_resampler, prelude::*}, - AudioFilterPlugin, SimulateScenario, + AudioFilterPlugin, PrewarmedConnection, SimulateScenario, }; use parking_lot::Mutex; @@ -60,6 +60,51 @@ fn on_connect( Ok(room::FfiRoom::connect(server, connect)) } +/// Open a connection to a server for a later connect. +/// This is an async function; the FfiClient must wait for the PrewarmCallback. +fn on_prewarm( + server: &'static FfiServer, + request: proto::PrewarmRequest, +) -> FfiResult { + let async_id = server.resolve_async_id(request.request_async_id); + let handle = server.async_runtime.spawn(async move { + let result = PrewarmedConnection::connect(&request.url).await; + complete_prewarm(server, async_id, result); + }); + server.watch_panic(handle); + Ok(proto::PrewarmResponse { async_id }) +} + +/// Hand a finished prewarm to the client. If the callback cannot be delivered (the +/// server was disposed meanwhile), nobody can learn the handle, so it is released. +pub(crate) fn complete_prewarm( + server: &FfiServer, + async_id: u64, + result: Result, +) { + let (message, id) = match result { + Ok(connection) => { + let id = server.next_id(); + server.store_handle(id, connection); + (proto::prewarm_callback::Message::Connection(proto::FfiOwnedHandle { id }), Some(id)) + } + Err(err) => (proto::prewarm_callback::Message::Error(err.to_string()), None), + }; + let sent = + server.send_event(proto::PrewarmCallback { async_id, message: Some(message) }.into()); + if let (Err(_), Some(id)) = (sent, id) { + server.drop_handle(id); + } +} + +fn on_prewarmed_connection_alive( + server: &'static FfiServer, + request: proto::PrewarmedConnectionAliveRequest, +) -> FfiResult { + let connection = server.retrieve_handle::(request.connection_handle)?; + Ok(proto::PrewarmedConnectionAliveResponse { alive: connection.is_alive() }) +} + /// Disconnect to a room /// This is an async function, the FfiClient must wait for the DisconnectCallback fn on_disconnect( @@ -1400,6 +1445,10 @@ pub fn handle_request( res.message = Some(match request { Request::Dispose(req) => on_dispose(server, req)?.into(), Request::Connect(req) => on_connect(server, req)?.into(), + Request::Prewarm(req) => on_prewarm(server, req)?.into(), + Request::PrewarmedConnectionAlive(req) => { + on_prewarmed_connection_alive(server, req)?.into() + } Request::Disconnect(req) => on_disconnect(server, req)?.into(), Request::SimulateScenario(req) => on_simulate_scenario(server, req)?.into(), Request::ReadyForRoomEvent(req) => on_ready_for_room_event(server, req)?.into(), diff --git a/livekit-ffi/src/room_apis/server/room.rs b/livekit-ffi/src/room_apis/server/room.rs index bc4f17cbc7..aa786cd4d9 100644 --- a/livekit-ffi/src/room_apis/server/room.rs +++ b/livekit-ffi/src/room_apis/server/room.rs @@ -151,7 +151,14 @@ impl FfiRoom { let async_id = server.resolve_async_id(connect.request_async_id); let req = connect.clone(); + let prewarmed_handle = connect.options.prewarmed_connection_handle; let mut options: RoomOptions = connect.options.into(); + if let Some(id) = prewarmed_handle { + match server.retrieve_handle::(id) { + Ok(connection) => options.prewarmed_connection = Some(connection.clone()), + Err(err) => log::warn!("ignoring prewarmed connection handle {id}: {err}"), + } + } { let config = server.config.lock(); diff --git a/livekit-ffi/src/room_apis/server/tests.rs b/livekit-ffi/src/room_apis/server/tests.rs index cb6fddc4dc..7008b019e9 100644 --- a/livekit-ffi/src/room_apis/server/tests.rs +++ b/livekit-ffi/src/room_apis/server/tests.rs @@ -350,7 +350,7 @@ use std::sync::{ }; use super::{FfiConfig, FfiHandle}; -use crate::{FfiHandleId, FFI_SERVER}; +use crate::{proto, FfiHandleId, FFI_SERVER}; struct DropsHandle { handle: FfiHandleId, @@ -430,3 +430,114 @@ fn dispose_cleans_up_resources() { assert!(FFI_SERVER.ffi_handles.is_empty()); assert!(!FFI_SERVER.is_setup()); } + +/// Sets up and disposes the global server and checks its handle map is empty, so it +/// runs alone like `dispose_cleans_up_resources`. +#[serial_test::serial] +#[test] +fn prewarmed_connection_handle_lifecycle() { + use std::time::Duration; + use tokio::{io::AsyncReadExt, sync::mpsc}; + + let (event_tx, mut event_rx) = mpsc::unbounded_channel(); + FFI_SERVER.setup(FfiConfig { + callback_fn: Arc::new(move |event| { + if let Some(proto::ffi_event::Message::Prewarm(cb)) = event.message { + let _ = event_tx.send(cb); + } + }), + capture_logs: false, + sdk: "livekit-ffi-test".to_owned(), + sdk_version: "test".to_owned(), + }); + + let request = |message| { + crate::server::requests::handle_request( + &FFI_SERVER, + proto::FfiRequest { message: Some(message) }, + ) + .unwrap() + .message + .unwrap() + }; + let prewarm = |url: &str| { + request(proto::ffi_request::Message::Prewarm(proto::PrewarmRequest { + url: url.to_owned(), + request_async_id: None, + })) + }; + let alive = |handle| { + let res = request(proto::ffi_request::Message::PrewarmedConnectionAlive( + proto::PrewarmedConnectionAliveRequest { connection_handle: handle }, + )); + let proto::ffi_response::Message::PrewarmedConnectionAlive(res) = res else { + panic!("unexpected response"); + }; + res.alive + }; + + FFI_SERVER.async_runtime.block_on(async { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let url = format!("ws://{}", listener.local_addr().unwrap()); + + for _ in 0..20 { + prewarm(&url); + let (mut server, _) = listener.accept().await.unwrap(); + let cb = tokio::time::timeout(Duration::from_secs(5), event_rx.recv()) + .await + .unwrap() + .unwrap(); + let Some(proto::prewarm_callback::Message::Connection(handle)) = cb.message else { + panic!("prewarm failed: {:?}", cb.message); + }; + assert!(alive(handle.id)); + + // Dropping the handle closes the socket. + assert!(FFI_SERVER.drop_handle(handle.id)); + let mut buf = [0u8; 1]; + let n = tokio::time::timeout(Duration::from_secs(2), server.read(&mut buf)).await; + assert!(matches!(n, Ok(Ok(0))), "socket not closed after the handle was dropped"); + } + + // A failed prewarm reports an error and stores no handle. + drop(listener); + prewarm(&url); + let cb = + tokio::time::timeout(Duration::from_secs(5), event_rx.recv()).await.unwrap().unwrap(); + assert!(matches!(cb.message, Some(proto::prewarm_callback::Message::Error(_)))); + }); + + assert!(FFI_SERVER.ffi_handles.is_empty()); + FFI_SERVER.async_runtime.block_on(FFI_SERVER.dispose()); +} + +/// A prewarm that finishes after dispose cannot reach a client, so its socket must not +/// stay in the handle map. Uses the global server, so it runs alone. +#[serial_test::serial] +#[test] +fn prewarm_completed_after_dispose_releases_the_connection() { + use std::time::Duration; + use tokio::io::AsyncReadExt; + + FFI_SERVER.setup(FfiConfig { + callback_fn: Arc::new(|_| {}), + capture_logs: false, + sdk: "livekit-ffi-test".to_owned(), + sdk_version: "test".to_owned(), + }); + + FFI_SERVER.async_runtime.block_on(async { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let url = format!("ws://{}", listener.local_addr().unwrap()); + let connection = livekit::PrewarmedConnection::connect(&url).await; + let (mut server, _) = listener.accept().await.unwrap(); + + FFI_SERVER.dispose().await; + crate::server::requests::complete_prewarm(&FFI_SERVER, 1, connection); + + assert!(FFI_SERVER.ffi_handles.is_empty()); + let mut buf = [0u8; 1]; + let n = tokio::time::timeout(Duration::from_secs(2), server.read(&mut buf)).await; + assert!(matches!(n, Ok(Ok(0))), "socket not closed after a failed callback"); + }); +} diff --git a/livekit-net/Cargo.toml b/livekit-net/Cargo.toml index 2260fe0627..f9cba111c9 100644 --- a/livekit-net/Cargo.toml +++ b/livekit-net/Cargo.toml @@ -24,10 +24,14 @@ native = ["dep:tokio-tungstenite", "dep:reqwest", "dep:tokio", "dep:futures-util native-tls = [ "tokio-tungstenite?/native-tls", "reqwest?/native-tls", + "dep:native-tls", + "dep:tokio-native-tls", ] native-tls-vendored = [ "tokio-tungstenite?/native-tls-vendored", "reqwest?/native-tls-vendored", + "dep:native-tls", + "dep:tokio-native-tls", ] rustls-tls-native-roots = [ "tokio-tungstenite?/rustls-tls-native-roots", @@ -39,8 +43,10 @@ rustls-tls-native-roots = [ rustls-tls-webpki-roots = [ "tokio-tungstenite?/rustls-tls-webpki-roots", "reqwest?/rustls-tls-webpki-roots", + "dep:tokio-rustls", + "dep:webpki-roots", ] -__rustls-tls = ["tokio-tungstenite?/__rustls-tls", "reqwest?/__rustls"] +__rustls-tls = ["tokio-tungstenite?/__rustls-tls", "reqwest?/__rustls", "dep:tokio-rustls"] # How CI checks this crate's features, read by # `.github/workflows/feature-combinations-curated.yml` via `cargo metadata`. @@ -64,6 +70,11 @@ tokio-tungstenite = { version = "0.29", features = ["url"], optional = true } tokio = { workspace = true, default-features = false, features = ["sync", "macros", "io-util", "net", "time", "rt-multi-thread"], optional = true } tokio-rustls = { version = "0.26", default-features = false, features = ["logging", "tls12", "ring"], optional = true } rustls-native-certs = { version = "0.8", optional = true } +# Direct TLS deps for pre-warmed connections, which run the TLS handshake before +# handing the stream to tokio-tungstenite. Versions match tokio-tungstenite's own. +webpki-roots = { version = "0.26", optional = true } +native-tls = { version = "0.2.11", optional = true } +tokio-native-tls = { version = "0.3.1", optional = true } futures-util = { workspace = true, default-features = false, features = ["sink"], optional = true } bytes = { workspace = true, optional = true } reqwest = { version = "0.12", default-features = false, features = ["json"], optional = true } diff --git a/livekit-net/src/lib.rs b/livekit-net/src/lib.rs index 31e1ee237b..2e072293ae 100644 --- a/livekit-net/src/lib.rs +++ b/livekit-net/src/lib.rs @@ -13,12 +13,14 @@ // limitations under the License. mod bounded; +mod prewarm; mod transport; mod types; #[cfg(feature = "native")] mod native; +pub use prewarm::PrewarmedConnection; pub use transport::{ HttpClient, HttpClientExt, HttpMethod, WsClient, WsConnectResult, WsConnection, }; diff --git a/livekit-net/src/native/mod.rs b/livekit-net/src/native/mod.rs index 1fc9dd3a99..22fd9afab9 100644 --- a/livekit-net/src/native/mod.rs +++ b/livekit-net/src/native/mod.rs @@ -13,6 +13,7 @@ // limitations under the License. mod connection; +pub(crate) mod prewarm; mod proxy; use crate::{ @@ -113,6 +114,22 @@ pub(crate) fn native_http_client_with_response_limit(limit: u64) -> Arc Result, TransportError> { + use tokio_tungstenite::tungstenite::client::IntoClientRequest; + + let mut request = + url.clone().into_client_request().map_err(|e| TransportError::Connection(e.to_string()))?; + for h in headers { + let name: http::header::HeaderName = + h.name.parse().map_err(|_| TransportError::Other("bad header name".into()))?; + let value = http::header::HeaderValue::from_str(&h.value) + .map_err(|_| TransportError::Other("bad header value".into()))?; + request.headers_mut().insert(name, value); + } + Ok(request) +} + #[async_trait::async_trait] impl WsClient for NativeTransport { async fn connect( @@ -123,20 +140,7 @@ impl WsClient for NativeTransport { ) -> Result { let parsed = url::Url::parse(&url).map_err(|e| TransportError::Connection(e.to_string()))?; - - use tokio_tungstenite::tungstenite::client::IntoClientRequest; - - let mut request = parsed - .clone() - .into_client_request() - .map_err(|e| TransportError::Connection(e.to_string()))?; - for h in &headers { - let name: http::header::HeaderName = - h.name.parse().map_err(|_| TransportError::Other("bad header name".into()))?; - let value = http::header::HeaderValue::from_str(&h.value) - .map_err(|_| TransportError::Other("bad header value".into()))?; - request.headers_mut().insert(name, value); - } + let request = build_request(&parsed, &headers)?; let connect_fut = async { let ws = self::proxy::connect_ws(request, &parsed).await?; diff --git a/livekit-net/src/native/prewarm.rs b/livekit-net/src/native/prewarm.rs new file mode 100644 index 0000000000..2a642c6809 --- /dev/null +++ b/livekit-net/src/native/prewarm.rs @@ -0,0 +1,417 @@ +// Copyright 2026 LiveKit, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//! Native backend of [`crate::PrewarmedConnection`]. + +use std::{ + sync::{Arc, Mutex, MutexGuard, PoisonError}, + time::Duration, +}; + +use tokio::{io::AsyncReadExt, net::TcpStream, sync::oneshot}; +use tokio_tungstenite::{tungstenite, MaybeTlsStream}; + +use crate::{Header, TransportError, WsConnectResult}; + +pub(super) type Stream = MaybeTlsStream; + +/// Upper bound on the WebSocket upgrade over a pre-warmed stream. A close (FIN) +/// or reset (RST) is seen by the watcher or fails the upgrade at once; this only +/// fires when a middlebox dropped the stream silently, which never fails on its +/// own. Kept well above a normal upgrade (~1 RTT), as giving up on a slow but +/// live server makes the fresh dial send a second join for the same identity. +const UPGRADE_TIMEOUT: Duration = Duration::from_millis(1500); + +/// Upper bound on opening a pre-warmed stream (TCP connect plus TLS handshake), +/// matching the default signal connect timeout. +const DIAL_TIMEOUT: Duration = Duration::from_secs(5); + +/// The server a stream is connected to. A pre-warmed stream is only used for +/// the exact scheme, host and port it was opened for. +#[derive(Debug, Clone, PartialEq, Eq)] +struct Endpoint { + tls: bool, + host: String, + port: u16, +} + +impl TryFrom<&url::Url> for Endpoint { + type Error = TransportError; + + fn try_from(url: &url::Url) -> Result { + // Signalling rewrites http(s) to ws(s) before connecting, so both + // spellings of a URL must match. + let tls = match url.scheme() { + "wss" | "https" => true, + "ws" | "http" => false, + other => { + return Err(TransportError::Connection(format!("unsupported scheme: {other}"))) + } + }; + let host = match url.host() { + Some(url::Host::Domain(domain)) => domain.to_owned(), + Some(url::Host::Ipv4(ip)) => ip.to_string(), + Some(url::Host::Ipv6(ip)) => ip.to_string(), + None => return Err(TransportError::Connection("URL has no host".into())), + }; + let port = url.port().unwrap_or(if tls { 443 } else { 80 }); + Ok(Self { tls, host, port }) + } +} + +/// Asks the watcher for its stream. +type TakeTx = oneshot::Sender>; + +/// An open stream waiting for its WebSocket upgrade. +pub(crate) struct Warm { + endpoint: Endpoint, + /// `None` once the stream was taken or the connection closed. Dropping it + /// stops the watcher, which owns the stream. + take_tx: Mutex>, +} + +impl Warm { + pub(crate) async fn open(url: &str) -> Result { + Self::open_with_timeout(url, DIAL_TIMEOUT).await + } + + async fn open_with_timeout(url: &str, timeout: Duration) -> Result { + let url = url::Url::parse(url).map_err(|e| TransportError::Connection(e.to_string()))?; + let endpoint = Endpoint::try_from(&url)?; + if super::proxy::proxy_for(endpoint.tls).is_some() { + // A direct stream would bypass the proxy the connect path uses. + return Err(TransportError::Other("prewarm is not supported through a proxy".into())); + } + + let stream = tokio::time::timeout(timeout, dial(&endpoint)) + .await + .map_err(|_| TransportError::Timeout)??; + let (take_tx, take_rx) = oneshot::channel(); + tokio::spawn(Watcher { take_rx, stream }.run()); + log::debug!("pre-warmed connection to {}", crate::redact_url(&url)); + Ok(Self { endpoint, take_tx: Mutex::new(Some(take_tx)) }) + } + + pub(crate) fn is_alive(&self) -> bool { + self.take_tx().as_ref().is_some_and(|tx| !tx.is_closed()) + } + + pub(crate) fn close(&self) { + let take_tx = self.take_tx().take(); + drop(take_tx); + } + + /// Run the WebSocket upgrade for `url` over the pre-warmed stream. + /// + /// Returns `Ok(None)` when the stream cannot be used (already used, closed, + /// opened for another server, or the upgrade failed or timed out), in which + /// case the caller should dial a fresh connection. An HTTP error status from + /// the server is the server's real answer and is returned as an error. The + /// stream is consumed either way. + pub(crate) async fn upgrade( + &self, + url: &str, + headers: &[Header], + timeout: Duration, + ) -> Result, TransportError> { + let parsed = url::Url::parse(url).map_err(|e| TransportError::Connection(e.to_string()))?; + let Some(take_tx) = self.take_tx().take() else { return Ok(None) }; + if Endpoint::try_from(&parsed).ok().as_ref() != Some(&self.endpoint) { + log::debug!("pre-warmed connection is for another server, dialing a fresh one"); + return Ok(None); + } + if super::proxy::proxy_for(self.endpoint.tls).is_some() { + return Ok(None); + } + + let (reply_tx, reply_rx) = oneshot::channel(); + // Both fail if the watcher already exited because the server closed the stream. + if take_tx.send(reply_tx).is_err() { + return Ok(None); + } + let Ok(stream) = reply_rx.await else { return Ok(None) }; + + let request = super::build_request(&parsed, headers)?; + let upgrade = tokio_tungstenite::client_async_with_config(request, stream, None); + match tokio::time::timeout(timeout.min(UPGRADE_TIMEOUT), upgrade).await { + Ok(Ok((ws, _))) => { + log::debug!("using pre-warmed connection to {}", crate::redact_url(&parsed)); + Ok(Some(WsConnectResult { + connection: Arc::new(super::connection::NativeConnection::new(ws)), + })) + } + Ok(Err(e @ tungstenite::Error::Http(_))) => Err(super::proxy::map_ws_err(e)), + Ok(Err(e)) => { + log::warn!("pre-warmed connection failed, dialing a fresh one: {e}"); + Ok(None) + } + Err(_) => { + log::warn!("pre-warmed connection timed out, dialing a fresh one"); + Ok(None) + } + } + } + + fn take_tx(&self) -> MutexGuard<'_, Option> { + // Every critical section is a single `Option` operation. + self.take_tx.lock().unwrap_or_else(PoisonError::into_inner) + } +} + +/// Owns the stream until it is taken, the server closes it, or its [`Warm`] is dropped. +struct Watcher { + take_rx: oneshot::Receiver>, + stream: Stream, +} + +impl Watcher { + async fn run(self) { + let Self { take_rx, mut stream } = self; + let mut buf = [0u8; 64]; + tokio::select! { + // `Err` means the connection was closed or dropped. + reply_tx = take_rx => { + if let Ok(reply_tx) = reply_tx { + let _ = reply_tx.send(stream); + } + } + // The server sends nothing before the upgrade request, so any + // application data, EOF, or error means the stream is unusable. + // TLS 1.3 session tickets are consumed by the TLS layer and never + // complete this read. + _ = stream.read(&mut buf) => log::debug!("pre-warmed connection closed by the server"), + } + } +} + +async fn dial(endpoint: &Endpoint) -> Result { + let tcp = TcpStream::connect((endpoint.host.as_str(), endpoint.port)) + .await + .map_err(|e| TransportError::Connection(e.to_string()))?; + let _ = tcp.set_nodelay(true); + if !endpoint.tls { + return Ok(MaybeTlsStream::Plain(tcp)); + } + tls::connect(&endpoint.host, tcp).await +} + +/// TLS for pre-warmed streams, mirroring the backend tokio-tungstenite picks when +/// it is given no connector: native-tls when enabled, otherwise rustls. +mod tls { + use super::Stream; + use crate::TransportError; + use tokio::net::TcpStream; + + #[cfg(any(feature = "native-tls", feature = "native-tls-vendored"))] + pub(super) async fn connect(host: &str, tcp: TcpStream) -> Result { + use tokio_tungstenite::MaybeTlsStream; + + let connector = native_tls::TlsConnector::new() + .map_err(|e| TransportError::Connection(e.to_string()))?; + let stream = tokio_native_tls::TlsConnector::from(connector) + .connect(host, tcp) + .await + .map_err(|e| TransportError::Connection(format!("TLS connection error: {e}")))?; + Ok(MaybeTlsStream::NativeTls(stream)) + } + + #[cfg(all( + not(any(feature = "native-tls", feature = "native-tls-vendored")), + any( + feature = "rustls-tls-native-roots", + feature = "rustls-tls-webpki-roots", + feature = "__rustls-tls" + ) + ))] + pub(super) async fn connect(host: &str, tcp: TcpStream) -> Result { + use tokio_rustls::{rustls::pki_types::ServerName, TlsConnector}; + use tokio_tungstenite::MaybeTlsStream; + + let server_name = ServerName::try_from(host.to_owned()) + .map_err(|_| TransportError::Connection(format!("Invalid DNS name: {host}")))?; + let stream = TlsConnector::from(rustls_config()?) + .connect(server_name, tcp) + .await + .map_err(|e| TransportError::Connection(format!("TLS connection error: {e}")))?; + Ok(MaybeTlsStream::Rustls(stream)) + } + + /// The client config, built once: loading native roots is slow, and a + /// shared config also shares its TLS session cache. + #[cfg(all( + not(any(feature = "native-tls", feature = "native-tls-vendored")), + any( + feature = "rustls-tls-native-roots", + feature = "rustls-tls-webpki-roots", + feature = "__rustls-tls" + ) + ))] + fn rustls_config() -> Result, TransportError> + { + use std::sync::{Arc, OnceLock}; + use tokio_rustls::rustls::{ClientConfig, RootCertStore}; + + static CONFIG: OnceLock> = OnceLock::new(); + if let Some(config) = CONFIG.get() { + return Ok(Arc::clone(config)); + } + + #[allow(unused_mut)] + let mut roots = RootCertStore::empty(); + #[cfg(feature = "rustls-tls-native-roots")] + { + let result = rustls_native_certs::load_native_certs(); + if !result.errors.is_empty() { + log::warn!("native root CA certificate loading errors: {:?}", result.errors); + } + roots.add_parsable_certificates(result.certs); + } + #[cfg(feature = "rustls-tls-webpki-roots")] + roots.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned()); + if roots.is_empty() { + return Err(TransportError::Connection("no root CA certificates available".into())); + } + + let config = + Arc::new(ClientConfig::builder().with_root_certificates(roots).with_no_client_auth()); + Ok(Arc::clone(CONFIG.get_or_init(|| config))) + } + + #[cfg(not(any( + feature = "native-tls", + feature = "native-tls-vendored", + feature = "rustls-tls-native-roots", + feature = "rustls-tls-webpki-roots", + feature = "__rustls-tls" + )))] + pub(super) async fn connect(_host: &str, _tcp: TcpStream) -> Result { + Err(TransportError::Connection("TLS support is not enabled".into())) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use tokio::{io::AsyncWriteExt, net::TcpListener}; + + async fn listener() -> (TcpListener, String) { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let url = format!("ws://{}", listener.local_addr().unwrap()); + (listener, url) + } + + async fn wait_until(cond: impl Fn() -> bool) { + let deadline = tokio::time::Instant::now() + Duration::from_secs(2); + while !cond() { + assert!(tokio::time::Instant::now() < deadline, "condition not met in time"); + tokio::time::sleep(Duration::from_millis(10)).await; + } + } + + async fn assert_eof(server: &mut TcpStream) { + let mut buf = [0u8; 1]; + let n = tokio::time::timeout(Duration::from_secs(2), server.read(&mut buf)).await; + assert!(matches!(n, Ok(Ok(0))), "server side did not see the stream close"); + } + + #[test] + fn endpoint_normalizes_scheme_and_port() { + let parse = |s: &str| Endpoint::try_from(&url::Url::parse(s).unwrap()).unwrap(); + assert_eq!(parse("https://example.com"), parse("wss://example.com:443/rtc/v1?x=1")); + assert_eq!(parse("http://example.com:7880"), parse("ws://example.com:7880/rtc")); + assert_ne!(parse("ws://example.com"), parse("wss://example.com")); + assert_eq!(parse("ws://[::1]:7880").host, "::1"); + } + + #[tokio::test] + async fn server_close_marks_dead() { + let (listener, url) = listener().await; + let warm = Warm::open(&url).await.unwrap(); + let (server, _) = listener.accept().await.unwrap(); + assert!(warm.is_alive()); + + drop(server); + wait_until(|| !warm.is_alive()).await; + let used = warm.upgrade(&url, &[], Duration::from_secs(1)).await.unwrap(); + assert!(used.is_none()); + } + + #[tokio::test] + async fn drop_closes_the_stream() { + let (listener, url) = listener().await; + let warm = Warm::open(&url).await.unwrap(); + let (mut server, _) = listener.accept().await.unwrap(); + + drop(warm); + assert_eof(&mut server).await; + } + + #[tokio::test] + async fn close_closes_the_stream() { + let (listener, url) = listener().await; + let warm = Warm::open(&url).await.unwrap(); + let (mut server, _) = listener.accept().await.unwrap(); + + warm.close(); + assert!(!warm.is_alive()); + assert_eof(&mut server).await; + } + + #[tokio::test] + async fn other_server_is_not_used_and_closes() { + let (listener, url) = listener().await; + let warm = Warm::open(&url).await.unwrap(); + let (mut server, _) = listener.accept().await.unwrap(); + + let used = warm.upgrade("ws://127.0.0.1:1", &[], Duration::from_secs(1)).await.unwrap(); + assert!(used.is_none()); + assert!(!warm.is_alive()); + assert_eof(&mut server).await; + } + + #[tokio::test] + async fn silent_server_times_out() { + let (listener, url) = listener().await; + let warm = Warm::open(&url).await.unwrap(); + // Accept but never answer the upgrade, like a silently dropped stream. + let (mut server, _) = listener.accept().await.unwrap(); + + let started = tokio::time::Instant::now(); + let used = warm.upgrade(&url, &[], Duration::from_millis(200)).await.unwrap(); + assert!(used.is_none()); + assert!(started.elapsed() < Duration::from_secs(1)); + let _ = server.shutdown().await; + } + + #[cfg(any( + feature = "native-tls", + feature = "native-tls-vendored", + feature = "rustls-tls-native-roots", + feature = "rustls-tls-webpki-roots", + feature = "__rustls-tls" + ))] + #[tokio::test] + async fn stalled_tls_handshake_times_out() { + let (listener, _) = listener().await; + let url = format!("wss://{}", listener.local_addr().unwrap()); + // Accept TCP but never answer the ClientHello. + let accept = tokio::spawn(async move { listener.accept().await.unwrap() }); + + let started = tokio::time::Instant::now(); + let result = Warm::open_with_timeout(&url, Duration::from_millis(200)).await; + assert!(matches!(result, Err(TransportError::Timeout))); + assert!(started.elapsed() < Duration::from_secs(1)); + drop(accept.await.unwrap()); + } +} diff --git a/livekit-net/src/native/proxy.rs b/livekit-net/src/native/proxy.rs index 19487001b5..faa2a66682 100644 --- a/livekit-net/src/native/proxy.rs +++ b/livekit-net/src/native/proxy.rs @@ -22,7 +22,7 @@ use std::env; /// on the /rtc endpoint), tungstenite surfaces it as `Error::Http(response)`. /// We extract the status code and return `TransportError::Http { status }` so /// callers can distinguish HTTP error codes (403, 404) from network errors. -fn map_ws_err(e: tokio_tungstenite::tungstenite::Error) -> TransportError { +pub(super) fn map_ws_err(e: tokio_tungstenite::tungstenite::Error) -> TransportError { use tokio_tungstenite::tungstenite::Error; match e { Error::Http(resp) => TransportError::Http { status: resp.status().as_u16() }, @@ -43,16 +43,9 @@ pub(super) async fn connect_ws( request: http::Request<()>, url: &url::Url, ) -> Result>, TransportError> { - // Check for HTTP_PROXY or HTTPS_PROXY environment variables - let proxy_env = if url.scheme() == "wss" { - env::var("HTTPS_PROXY").or_else(|_| env::var("https_proxy")) - } else { - env::var("HTTP_PROXY").or_else(|_| env::var("http_proxy")) - }; - // Connect directly or through proxy - let ws_stream = if let Ok(proxy_url) = proxy_env { - if !proxy_url.is_empty() { + let ws_stream = if let Some(proxy_url) = proxy_for(url.scheme() == "wss") { + { let proxy_url = url::Url::parse(&proxy_url) .map_err(|e| TransportError::Connection(format!("Invalid proxy URL: {}", e)))?; log::info!("Using proxy: {}", crate::redact_url(&proxy_url)); @@ -213,16 +206,21 @@ pub(super) async fn connect_ws( .await .map_err(map_ws_err)?; ws_stream - } else { - // Proxy var is empty, connect directly - let (ws_stream, _) = connect_async(request).await.map_err(map_ws_err)?; - ws_stream } } else { - // No proxy env var set, connect directly let (ws_stream, _) = connect_async(request).await.map_err(map_ws_err)?; ws_stream }; Ok(ws_stream) } + +/// The proxy configured for the given scheme through `HTTP(S)_PROXY`, if any. +pub(super) fn proxy_for(tls: bool) -> Option { + let proxy = if tls { + env::var("HTTPS_PROXY").or_else(|_| env::var("https_proxy")) + } else { + env::var("HTTP_PROXY").or_else(|_| env::var("http_proxy")) + }; + proxy.ok().filter(|p| !p.is_empty()) +} diff --git a/livekit-net/src/prewarm.rs b/livekit-net/src/prewarm.rs new file mode 100644 index 0000000000..e203303663 --- /dev/null +++ b/livekit-net/src/prewarm.rs @@ -0,0 +1,97 @@ +// Copyright 2026 LiveKit, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +use std::fmt; + +#[cfg(feature = "native")] +use std::{sync::Arc, time::Duration}; + +#[cfg(feature = "native")] +use crate::{Header, TransportError, WsConnectResult}; + +/// A TCP (and, for `wss`, TLS) connection to a LiveKit server, opened ahead of +/// a connect so that the connect only performs the WebSocket upgrade. +/// +/// The connection is used at most once. Clones share it, so whichever clone is +/// used first consumes it. Dropping the last clone, or calling +/// [`close`](Self::close), closes the socket. +/// +/// Only the built-in native transport can use it: with a host-registered +/// [`WsClient`](crate::WsClient), a connect dials through that client instead. +#[derive(Clone)] +pub struct PrewarmedConnection { + #[cfg(feature = "native")] + inner: Arc, + // Without the native backend there is no way to create one. + #[cfg(not(feature = "native"))] + _unconstructible: std::convert::Infallible, +} + +impl PrewarmedConnection { + /// Open a connection to the server at `url`. + /// + /// `http(s)` URLs are treated as `ws(s)`, so either spelling matches a later + /// connect to the same host and port. Fails if the connection cannot be + /// opened within 5 s, or if an `HTTP(S)_PROXY` is configured for the scheme. + #[cfg(feature = "native")] + pub async fn connect(url: &str) -> Result { + let inner = crate::native::prewarm::Warm::open(url).await?; + Ok(Self { inner: Arc::new(inner) }) + } + + /// Whether the connection can still be used: it has not been used or + /// closed, and the server has not closed it. + pub fn is_alive(&self) -> bool { + #[cfg(feature = "native")] + return self.inner.is_alive(); + #[cfg(not(feature = "native"))] + match self._unconstructible {} + } + + /// Close the connection without using it. + pub fn close(&self) { + #[cfg(feature = "native")] + self.inner.close(); + #[cfg(not(feature = "native"))] + match self._unconstructible {} + } + + /// Perform the WebSocket upgrade for `url` over this connection. + /// + /// Returns `Ok(None)` if the connection cannot be used: it was already used + /// or closed, it was opened for a different server, or the upgrade failed + /// or exceeded `timeout` (capped at 1.5 s, which only a silently dropped + /// connection reaches; a close or reset fails at once). The caller should then + /// dial a fresh connection. An HTTP error status from the server is + /// returned as an error. The connection is consumed either way. + #[cfg(feature = "native")] + pub async fn upgrade( + &self, + url: &str, + headers: &[Header], + timeout: Duration, + ) -> Result, TransportError> { + if crate::has_ws_client() { + self.close(); + return Ok(None); + } + self.inner.upgrade(url, headers, timeout).await + } +} + +impl fmt::Debug for PrewarmedConnection { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("PrewarmedConnection").field("alive", &self.is_alive()).finish() + } +} diff --git a/livekit-net/tests/prewarm.rs b/livekit-net/tests/prewarm.rs new file mode 100644 index 0000000000..c4e6890960 --- /dev/null +++ b/livekit-net/tests/prewarm.rs @@ -0,0 +1,107 @@ +// Copyright 2026 LiveKit, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#![cfg(feature = "native")] + +use std::time::Duration; + +use futures_util::{SinkExt, StreamExt}; +use livekit_net::PrewarmedConnection; +use tokio::net::{TcpListener, TcpStream}; + +async fn echo(stream: TcpStream) { + let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap(); + while let Some(Ok(msg)) = ws.next().await { + if msg.is_binary() { + ws.send(msg).await.unwrap(); + } + } +} + +#[tokio::test] +async fn upgrade_runs_over_the_prewarmed_stream() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + + let warm = PrewarmedConnection::connect(&format!("http://{addr}")).await.unwrap(); + let (stream, _) = listener.accept().await.unwrap(); + let server = tokio::spawn(echo(stream)); + + let url = format!("ws://{addr}/rtc/v1?join_request=abc"); + let conn = warm.upgrade(&url, &[], Duration::from_secs(5)).await.unwrap().unwrap().connection; + conn.send(b"ping".to_vec()).await.unwrap(); + assert_eq!(conn.recv().await.unwrap(), Some(b"ping".to_vec())); + conn.close().await; + server.await.unwrap(); + + assert!(!warm.is_alive(), "a used connection must not be reported as alive"); + let second = tokio::time::timeout(Duration::from_millis(200), listener.accept()).await; + assert!(second.is_err(), "the upgrade dialed a new stream"); +} + +#[tokio::test] +async fn upgrade_is_once_across_clones() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + let url = format!("ws://{addr}"); + + let warm = PrewarmedConnection::connect(&url).await.unwrap(); + let clone = warm.clone(); + let (stream, _) = listener.accept().await.unwrap(); + let server = tokio::spawn(echo(stream)); + + assert!(warm.upgrade(&url, &[], Duration::from_secs(5)).await.unwrap().is_some()); + assert!(clone.upgrade(&url, &[], Duration::from_secs(5)).await.unwrap().is_none()); + server.abort(); +} + +#[tokio::test] +async fn http_error_status_is_returned() { + use tokio::io::{AsyncReadExt, AsyncWriteExt}; + + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + let url = format!("ws://{addr}"); + + let warm = PrewarmedConnection::connect(&url).await.unwrap(); + let (mut stream, _) = listener.accept().await.unwrap(); + tokio::spawn(async move { + let mut buf = [0u8; 1024]; + let _ = stream.read(&mut buf).await; + let _ = stream.write_all(b"HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n").await; + }); + + let res = warm.upgrade(&url, &[], Duration::from_secs(5)).await; + assert!(matches!(res, Err(livekit_net::TransportError::Http { status: 401 }))); +} + +#[tokio::test] +async fn failed_upgrade_asks_for_a_fresh_dial() { + use tokio::io::AsyncReadExt; + + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + let url = format!("ws://{addr}"); + + let warm = PrewarmedConnection::connect(&url).await.unwrap(); + let (mut stream, _) = listener.accept().await.unwrap(); + tokio::spawn(async move { + // Look alive until the upgrade request arrives, then drop the stream + // without answering, like a server that timed out the idle connection. + let mut buf = [0u8; 1024]; + let _ = stream.read(&mut buf).await; + }); + + assert!(warm.upgrade(&url, &[], Duration::from_secs(5)).await.unwrap().is_none()); +} diff --git a/livekit-signaling/src/lib.rs b/livekit-signaling/src/lib.rs index d55f48a2e7..293a39cba3 100644 --- a/livekit-signaling/src/lib.rs +++ b/livekit-signaling/src/lib.rs @@ -77,6 +77,7 @@ const CLIENT_CAPABILITIES: &[proto::client_info::Capability] = &[ pub use livekit_common::{ CLIENT_PROTOCOL_DATA_STREAM_RPC, CLIENT_PROTOCOL_DATA_STREAM_V2, CLIENT_PROTOCOL_DEFAULT, }; +pub use livekit_net::PrewarmedConnection; /// The client protocol which is sent to other clients and indicates the set of apis that other /// clients should assume this client supports. @@ -216,6 +217,9 @@ pub struct SignalOptions { /// /// The default token is never cancelled. pub cancellation_token: CancellationToken, + /// A connection opened ahead of time, used by the first connection attempt + /// to skip TCP and TLS setup. See [`PrewarmedConnection`]. + pub prewarmed_connection: Option, } impl Default for SignalOptions { @@ -231,6 +235,7 @@ impl Default for SignalOptions { client_capabilities: CLIENT_CAPABILITIES.to_vec(), client_protocol: CLIENT_PROTOCOL_VERSION, cancellation_token: CancellationToken::new(), + prewarmed_connection: None, } } } @@ -633,7 +638,9 @@ impl SignalInner { let use_v1_path = options.single_peer_connection; // For initial connection: reconnect=false, reconnect_reason=None, participant_sid="" let lk_url = get_livekit_url(url, options, use_v1_path, false, None, "", publisher_offer)?; - match SignalStream::connect(lk_url.clone(), token, options.connect_timeout).await { + let prewarmed = options.prewarmed_connection.as_ref(); + match SignalStream::connect(lk_url.clone(), token, options.connect_timeout, prewarmed).await + { Ok((new_stream, stream_events)) => { log::debug!( "signal connection successful: path={}, single_pc_mode={}", @@ -662,8 +669,13 @@ impl SignalInner { if use_v1_path && is_not_found { let lk_url_v0 = get_livekit_url(url, options, false, false, None, "", None)?; log::warn!("v1 path not found (404), falling back to v0 path"); - match SignalStream::connect(lk_url_v0.clone(), token, options.connect_timeout) - .await + match SignalStream::connect( + lk_url_v0.clone(), + token, + options.connect_timeout, + None, + ) + .await { Ok((new_stream, stream_events)) => Ok((new_stream, stream_events, false)), Err(err) => { @@ -780,6 +792,7 @@ impl SignalInner { lk_url, &token, self.options.connect_timeout, + None, )) .await .ok_or(SignalError::Cancelled)??; @@ -1535,6 +1548,7 @@ mod tests { url::Url::parse("wss://localhost:7880/rtc").unwrap(), "", Duration::from_secs(1), + None, ) .await .expect("the mock transport always connects") @@ -2404,6 +2418,7 @@ mod tests { url::Url::parse("ws://mock/rtc").unwrap(), "tok", Duration::from_secs(1), + None, ) .await .unwrap(); diff --git a/livekit-signaling/src/signal_stream.rs b/livekit-signaling/src/signal_stream.rs index faabb8f292..b477d158b6 100644 --- a/livekit-signaling/src/signal_stream.rs +++ b/livekit-signaling/src/signal_stream.rs @@ -55,10 +55,14 @@ impl SignalStream { /// Returns SignalError if the connection failed. /// /// SignalStream will never try to reconnect if the connection has been closed. + /// + /// When `prewarmed` is usable, the WebSocket upgrade runs over it instead of + /// a freshly dialed connection. pub async fn connect( url: url::Url, token: &str, connect_timeout: Duration, + prewarmed: Option<&livekit_net::PrewarmedConnection>, ) -> SignalResult<(Self, mpsc::UnboundedReceiver>)> { log::info!("connecting to {}", livekit_net::redact_url(&url)); @@ -71,17 +75,26 @@ impl SignalStream { let headers = super::bearer_headers(token); - // Delegate the connect deadline to the transport via `timeout_ms`, but keep - // an outer Rust-side timeout as a backstop: a foreign/host transport that - // ignores or mishandles `timeout_ms` must not be able to hang connect (and - // thus the engine's reconnect loop) forever. - let conn = tokio::time::timeout( - connect_timeout, - transport.connect(url.to_string(), headers, connect_timeout.as_millis() as u64), - ) - .await - .map_err(|_| SignalError::Timeout("signal connection timed out".into()))?? - .connection; + // One deadline covers the pre-warmed attempt and any fresh dial after it. + let deadline = tokio::time::Instant::now() + connect_timeout; + let conn = match Self::upgrade_prewarmed(prewarmed, &url, &headers, connect_timeout).await? + { + Some(conn) => conn, + // Delegate the connect deadline to the transport via `timeout_ms`, but keep + // an outer Rust-side timeout as a backstop: a foreign/host transport that + // ignores or mishandles `timeout_ms` must not be able to hang connect (and + // thus the engine's reconnect loop) forever. + None => { + let remaining = deadline.saturating_duration_since(tokio::time::Instant::now()); + tokio::time::timeout( + remaining, + transport.connect(url.to_string(), headers, remaining.as_millis() as u64), + ) + .await + .map_err(|_| SignalError::Timeout("signal connection timed out".into()))?? + .connection + } + }; Ok(Self::spawn(conn)) } @@ -98,6 +111,29 @@ impl SignalStream { (Self { internal_tx, read_handle, write_handle }, events) } + /// Upgrade over `prewarmed` if it is usable; `None` means dial a fresh connection. + #[cfg(feature = "native")] + async fn upgrade_prewarmed( + prewarmed: Option<&livekit_net::PrewarmedConnection>, + url: &url::Url, + headers: &[livekit_net::Header], + timeout: Duration, + ) -> SignalResult>> { + let Some(prewarmed) = prewarmed else { return Ok(None) }; + let result = prewarmed.upgrade(url.as_str(), headers, timeout).await?; + Ok(result.map(|r| r.connection)) + } + + #[cfg(not(feature = "native"))] + async fn upgrade_prewarmed( + _prewarmed: Option<&livekit_net::PrewarmedConnection>, + _url: &url::Url, + _headers: &[livekit_net::Header], + _timeout: Duration, + ) -> SignalResult>> { + Ok(None) + } + /// Close the websocket. /// It sends a Close message before closing when `notify_close` is set. /// diff --git a/livekit/src/lib.rs b/livekit/src/lib.rs index dba3b5bc53..cc72c83d4c 100644 --- a/livekit/src/lib.rs +++ b/livekit/src/lib.rs @@ -36,6 +36,7 @@ pub mod webrtc { } } +pub use livekit_signaling::PrewarmedConnection; pub use room::*; /// `use livekit::prelude::*;` to import livekit types diff --git a/livekit/src/room/mod.rs b/livekit/src/room/mod.rs index e0f7a3cef1..605885a75b 100644 --- a/livekit/src/room/mod.rs +++ b/livekit/src/room/mod.rs @@ -31,7 +31,8 @@ use livekit_rpc::backend::{ HandleRequestOptions, RpcClientManager, RpcServerManager, RPC_REQUEST_TOPIC, RPC_RESPONSE_TOPIC, }; use livekit_signaling::{ - SignalOptions, SignalSdkOptions, CLIENT_PROTOCOL_DEFAULT, SIGNAL_CONNECT_TIMEOUT, + PrewarmedConnection, SignalOptions, SignalSdkOptions, CLIENT_PROTOCOL_DEFAULT, + SIGNAL_CONNECT_TIMEOUT, }; use parking_lot::RwLock; pub use proto::DisconnectReason; @@ -451,6 +452,11 @@ pub struct RoomOptions { /// Timeout for each individual signal connection attempt pub connect_timeout: Duration, pub data_stream: RoomDataStreamOptions, + /// A connection to the server opened ahead of time with + /// [`PrewarmedConnection::connect`]. The first signal connection attempt + /// runs only the WebSocket upgrade over it, and dials a fresh connection + /// if it is no longer usable or was opened for a different server. + pub prewarmed_connection: Option, } impl Default for RoomOptions { @@ -469,6 +475,7 @@ impl Default for RoomOptions { single_peer_connection: true, connect_timeout: SIGNAL_CONNECT_TIMEOUT, data_stream: Default::default(), + prewarmed_connection: None, } } } @@ -577,6 +584,7 @@ impl Room { signal_options.adaptive_stream = options.adaptive_stream; signal_options.single_peer_connection = options.single_peer_connection; signal_options.connect_timeout = options.connect_timeout; + signal_options.prewarmed_connection = options.prewarmed_connection.clone(); let (rtc_engine, join_response, engine_events) = RtcEngine::connect( url, token,