Typed throws

.changes/typed-disconnect-error

@@ -0,0 +1 @@
+patch type="fixed" "Report transport-level disconnects as LiveKitError(.network) instead of LiveKitError(.cancelled) so consumers can distinguish network failures from user-initiated cancellation"

.swiftlint.yml

@@ -40,3 +40,14 @@ custom_rules:
     regex: "@objc(?![(\\[])\\s+(?:(?:public|open|final|internal|package)\\s+)*class\\b"
     message: "Use @objcMembers instead of @objc for classes to implicitly expose members to Objective-C."
     severity: warning
+  public_typed_throws:
+    name: "Public typed throws"
+    # `func\s+(?!_objc_)\w+` skips Obj-C-only bridge shims, which by
+    # convention are named `_objc_*` and are hidden from Swift via
+    # `@available(swift, obsoleted: 1.0)`. Typed throws is a Swift-side
+    # concern, so those shims are exempt.
+    regex: "^\\s*(@\\w+(\\([^)]*\\))?\\s+)*(?:(?:static|class|final|override|convenience|nonisolated)\\s+)*(open|public)\\s+(?:(?:static|class|final|override|convenience|nonisolated)\\s+)*func\\s+(?!_objc_)\\w+(?:<[^>]*>)?\\s*\\((?:[^()]|\\([^()]*\\))*\\)\\s*(async\\s+)?\\bthrows\\b(?!\\s*\\()"
+    message: "Public throwing methods should declare a typed throws clause (e.g. `throws(LiveKitError)`). Suppress with // swiftlint:disable:next public_typed_throws if propagation is unbounded; include a one-line comment explaining why."
+    severity: error
+    included:
+      - "Sources/LiveKit/.*\\.swift"

AGENTS.md

@@ -130,6 +130,16 @@ private static let playAndRecordOptions: AVAudioSession.CategoryOptions = [.mixW
 - For non-recoverable errors, propagate with `throws` using `LiveKitError` with proper type/code
 - Anticipate invalid states at compile time using algebraic data types, typestates, etc.
 - Unsafe APIs like subscript `[0]` should be wrapped and leverage optional `?`
+- Public throwing methods declare typed throws: `throws(LiveKitError)`. Enforced by the `public_typed_throws` SwiftLint rule
+- At I/O edges (Foundation/AVAudio/WebRTC/protobuf), wrap with `LiveKitError(from: error)` — passes through existing `LiveKitError`, classifies `CancellationError`/`URLError`/`StreamError`, wraps everything else as `.unknown` with `internalError` set
+- Inside `throws(LiveKitError)` contexts, use `try checkCancellation()` (typed helper in `Errors.swift`) instead of `try Task.checkCancellation()`
+
+#### Typed-throws / Obj-C tradeoffs
+
+- `@objc` forbids typed throws. Pair `@nonobjc public func foo() throws(LiveKitError)` with an `@objc(originalSelector)` shim named `_objc_foo`, hidden from Swift via `@available(swift, obsoleted: 1.0)` (the rule's regex exempts `_objc_*`)
+- `@objc` protocol conformers (e.g. `LocalTrackProtocol`) stay untyped — suppress with a one-line reason
+- `Task<_, Failure: Error>` and `withCheckedThrowingContinuation` have no typed-failure initializers; convert at the `await` site with `LiveKitError(from:)`
+- Stored typed-throws closures need macOS 15+; until the floor moves, store untyped and convert at the call site
 
 ### Coding Style
 

Sources/LiveKit/Audio/AudioSessionEngineObserver.swift

@@ -102,7 +102,7 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
     /// of the WebRTC engine lifecycle.
     ///
     /// - Throws: ``LiveKitError`` if the audio session fails to configure or activate.
-    public func acquire(requirement: SessionRequirement) throws -> SessionRequirementHandle {
+    public func acquire(requirement: SessionRequirement) throws(LiveKitError) -> SessionRequirementHandle {
         let id = UUID()
         try set(requirement: requirement, for: id)
         return SessionRequirementHandle(releaseImpl: { [weak self] in
@@ -111,7 +111,7 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
         })
     }
 
-    private func set(requirement: SessionRequirement, for id: UUID) throws {
+    private func set(requirement: SessionRequirement, for id: UUID) throws(LiveKitError) {
         try updateRequirements {
             if requirement == .none {
                 $0.removeValue(forKey: id)
@@ -121,21 +121,21 @@ public class AudioSessionEngineObserver: AudioEngineObserver, Loggable, @uncheck
         }
     }
 
-    fileprivate func removeRequirement(for id: UUID) throws {
+    fileprivate func removeRequirement(for id: UUID) throws(LiveKitError) {
         try updateRequirements {
             $0.removeValue(forKey: id)
         }
     }
 
-    private func updateRequirements(_ block: (inout [UUID: SessionRequirement]) -> Void) throws {
-        try _state.mutate {
-            let oldState = $0
-            block(&$0.sessionRequirements)
-            guard $0.sessionRequirements != oldState.sessionRequirements else { return }
+    private func updateRequirements(_ block: (inout [UUID: SessionRequirement]) -> Void) throws(LiveKitError) {
+        try _state.mutate { state throws(LiveKitError) in
+            let oldState = state
+            block(&state.sessionRequirements)
+            guard state.sessionRequirements != oldState.sessionRequirements else { return }
             do {
-                try configureIfNeeded(oldState: oldState, newState: $0)
+                try configureIfNeeded(oldState: oldState, newState: state)
             } catch {
-                $0 = oldState
+                state = oldState
                 throw LiveKitError(.audioSession, message: "Failed to configure audio session")
             }
         }

Sources/LiveKit/Audio/Manager/AudioManager.swift

@@ -67,6 +67,9 @@ public struct SessionRequirement: OptionSet, Sendable {
 /// If not released explicitly, the requirement is released automatically on deinit.
 public final class SessionRequirementHandle: @unchecked Sendable {
     private struct State {
+        // Stored as untyped throws because typed-throws function types in
+        // stored properties need macOS 15+ runtime support; the wrapping
+        // public API still exposes throws(LiveKitError).
         var releaseImpl: (@Sendable () throws -> Void)?
     }
 
@@ -83,17 +86,22 @@ public final class SessionRequirementHandle: @unchecked Sendable {
     /// Releases the associated audio session requirement.
     ///
     /// Releasing the same handle multiple times is a no-op.
-    public func release() throws {
+    public func release() throws(LiveKitError) {
         try releaseIfNeeded()
     }
 
-    private func releaseIfNeeded() throws {
+    private func releaseIfNeeded() throws(LiveKitError) {
         let releaseImpl = _state.mutate { state -> (@Sendable () throws -> Void)? in
             let releaseImpl = state.releaseImpl
             state.releaseImpl = nil
             return releaseImpl
         }
-        try releaseImpl?()
+        do {
+            try releaseImpl?()
+        } catch {
+            // Constructed via acquire() whose closure throws only LiveKitError.
+            throw LiveKitError(from: error)
+        }
     }
 }
 
@@ -326,7 +334,7 @@ public class AudioManager: Loggable {
     /// Defaults to `true`.
     public var isVoiceProcessingEnabled: Bool { RTC.audioDeviceModule.isVoiceProcessingEnabled }
 
-    public func setVoiceProcessingEnabled(_ enabled: Bool) throws {
+    public func setVoiceProcessingEnabled(_ enabled: Bool) throws(LiveKitError) {
         let result = RTC.audioDeviceModule.setVoiceProcessingEnabled(enabled)
         try checkAdmResult(code: result)
     }
@@ -363,7 +371,7 @@ public class AudioManager: Loggable {
     /// In this mode, you can provide audio buffers by calling `AudioManager.shared.mixer.capture(appAudio:)` continuously.
     /// Remote audio will not play out automatically. Get remote mixed audio buffers with `AudioManager.shared.add(localAudioRenderer:)` or individual tracks with ``RemoteAudioTrack/add(audioRenderer:)``.
     /// - Note: While enabled, the SDK will not configure `AVAudioSession`. Configure it yourself if your app does its own audio I/O.
-    public func setManualRenderingMode(_ enabled: Bool) throws {
+    public func setManualRenderingMode(_ enabled: Bool) throws(LiveKitError) {
         let result = RTC.audioDeviceModule.setManualRenderingMode(enabled)
         try checkAdmResult(code: result)
     }
@@ -387,14 +395,14 @@ public class AudioManager: Loggable {
     /// - Note: Microphone permission is required. iOS may prompt if not already granted.
     /// - Note: This persists across ``Room`` lifecycles and connections until disabled.
     /// - Throws: An error if the underlying audio device module fails to apply the setting.
-    public func setRecordingAlwaysPreparedMode(_ enabled: Bool) async throws {
+    public func setRecordingAlwaysPreparedMode(_ enabled: Bool) async throws(LiveKitError) {
         let result = RTC.audioDeviceModule.setRecordingAlwaysPreparedMode(enabled)
         try checkAdmResult(code: result)
     }
 
     /// Starts mic input to the SDK even without any ``Room`` or a connection.
     /// Audio buffers will flow into ``LocalAudioTrack/add(audioRenderer:)`` and ``capturePostProcessingDelegate``.
-    public func startLocalRecording() throws {
+    public func startLocalRecording() throws(LiveKitError) {
         // Always unmute APM if muted by last session.
         RTC.audioProcessingModule.isMuted = false // TODO: Possibly not required anymore with new libs
         // Start recording on the ADM.
@@ -403,7 +411,7 @@ public class AudioManager: Loggable {
     }
 
     /// Stops mic input after it was started with ``startLocalRecording()``
-    public func stopLocalRecording() throws {
+    public func stopLocalRecording() throws(LiveKitError) {
         let result = RTC.audioDeviceModule.stopRecording()
         try checkAdmResult(code: result)
     }
@@ -423,7 +431,7 @@ public class AudioManager: Loggable {
     /// This is useful when you need to set up connections without touching the audio
     /// device yet (e.g., CallKit flows), or to guarantee the engine remains off
     /// regardless of subscription/publication requests.
-    public func setEngineAvailability(_ availability: AudioEngineAvailability) throws {
+    public func setEngineAvailability(_ availability: AudioEngineAvailability) throws(LiveKitError) {
         let result = RTC.audioDeviceModule.setEngineAvailability(availability.toRTCType())
         try checkAdmResult(code: result)
     }
@@ -450,7 +458,7 @@ public class AudioManager: Loggable {
     /// Acquires an audio session requirement for external ownership.
     ///
     /// On platforms without `AVAudioSession`, this returns a no-op handle.
-    public func acquireSessionRequirement(_ requirement: SessionRequirement) throws -> SessionRequirementHandle {
+    public func acquireSessionRequirement(_ requirement: SessionRequirement) throws(LiveKitError) -> SessionRequirementHandle {
         #if os(iOS) || os(visionOS) || os(tvOS)
         try audioSession.acquire(requirement: requirement)
         #else
@@ -546,7 +554,7 @@ let kAudioEngineErrorAudioSessionCategoryRecordingRequired = -4102
 let kAudioEngineErrorInsufficientDevicePermission = -4101
 
 extension AudioManager {
-    func checkAdmResult(code: Int) throws {
+    func checkAdmResult(code: Int) throws(LiveKitError) {
         if code == kAudioEngineErrorFailedToConfigureAudioSession {
             throw LiveKitError(.audioSession, message: "Failed to configure audio session")
         } else if code == kAudioEngineErrorInsufficientDevicePermission {

Sources/LiveKit/Audio/PlayerNodePool.swift

@@ -63,33 +63,40 @@ class AVAudioPlayerNodePool: @unchecked Sendable, Loggable {
     }
 
     @discardableResult
-    func play(_ buffer: AVAudioPCMBuffer, loop: Bool = false) throws -> SoundPlayback {
-        let acquired = try executionQueue.sync { () throws -> AcquiredNode in
-            guard let index = items.firstIndex(where: { $0.state == .idle }) else {
-                throw LiveKitError(.audioEngine, message: "No available player nodes")
-            }
-
-            items[index].state = .inUse
-            items[index].generation &+= 1
+    func play(_ buffer: AVAudioPCMBuffer, loop: Bool = false) throws(LiveKitError) -> SoundPlayback {
+        let acquired: AcquiredNode
+        do {
+            acquired = try executionQueue.sync { () throws -> AcquiredNode in
+                guard let index = items.firstIndex(where: { $0.state == .idle }) else {
+                    throw LiveKitError(.audioEngine, message: "No available player nodes")
+                }
 
-            let node = items[index].node
-            let generation = items[index].generation
-            node.volume = 1.0
-            node.pan = 0.0
+                items[index].state = .inUse
+                items[index].generation &+= 1
 
-            if loop {
-                node.scheduleBuffer(buffer, at: nil, options: .loops)
-            } else {
-                node.scheduleBuffer(buffer, completionCallbackType: .dataPlayedBack) { [weak self] _ in
-                    self?.executionQueue.async { [weak self] in
-                        self?.releaseCompletedSlot(index: index, generation: generation)
+                let node = items[index].node
+                let generation = items[index].generation
+                node.volume = 1.0
+                node.pan = 0.0
+
+                if loop {
+                    node.scheduleBuffer(buffer, at: nil, options: .loops)
+                } else {
+                    node.scheduleBuffer(buffer, completionCallbackType: .dataPlayedBack) { [weak self] _ in
+                        self?.executionQueue.async { [weak self] in
+                            self?.releaseCompletedSlot(index: index, generation: generation)
+                        }
                     }
                 }
-            }
 
-            node.play()
+                node.play()
 
-            return AcquiredNode(index: index, node: node, generation: generation)
+                return AcquiredNode(index: index, node: node, generation: generation)
+            }
+        } catch let error as LiveKitError {
+            throw error
+        } catch {
+            throw LiveKitError(.audioEngine, internalError: error)
         }
 
         return NodePlayback(node: acquired.node) { [weak self] in

Sources/LiveKit/Audio/SoundPlayer+Types.swift

@@ -85,7 +85,7 @@ public struct SoundHandle: Hashable, Sendable {
     let id: UUID
 
     /// Plays this prepared sound with the provided options.
-    public func play(options: SoundPlaybackOptions = SoundPlaybackOptions()) async throws {
+    public func play(options: SoundPlaybackOptions = SoundPlaybackOptions()) async throws(LiveKitError) {
         try await SoundPlayer.shared.play(self, options: options)
     }
 
@@ -149,7 +149,7 @@ class PreparedSound {
         cleanUp()
     }
 
-    func localBuffer(for playerNodeFormat: AVAudioFormat) throws -> AVAudioPCMBuffer {
+    func localBuffer(for playerNodeFormat: AVAudioFormat) throws(LiveKitError) -> AVAudioPCMBuffer {
         if let cachedLocalBuffer, let cachedLocalBufferFormat, cachedLocalBufferFormat == playerNodeFormat {
             return cachedLocalBuffer
         }

Sources/LiveKit/Audio/SoundPlayer.swift

@@ -85,7 +85,7 @@ public final class SoundPlayer: Loggable {
     /// - Note: Repeated playback of the same short clip should generally reuse a prepared sound
     ///   instead of decoding from disk each time.
     @discardableResult
-    public func prepare(fileURL: URL, named name: String? = nil) async throws -> SoundHandle {
+    public func prepare(fileURL: URL, named name: String? = nil) async throws(LiveKitError) -> SoundHandle {
         let readBuffer = try await Self.decodeBuffer(from: fileURL)
         let sessionRequirementHandle = try AudioManager.shared.acquireSessionRequirement(.playbackOnly)
         let soundId = UUID()
@@ -135,7 +135,7 @@ extension SoundPlayer {
         return format
     }
 
-    func makePlayerNodeFormat(for outputFormat: AVAudioFormat) throws -> AVAudioFormat {
+    func makePlayerNodeFormat(for outputFormat: AVAudioFormat) throws(LiveKitError) -> AVAudioFormat {
         guard let format = AVAudioFormat(commonFormat: .pcmFormatFloat32,
                                          sampleRate: outputFormat.sampleRate,
                                          channels: outputFormat.channelCount,
@@ -168,21 +168,25 @@ extension SoundPlayer {
         invalidateLocalState()
     }
 
-    func reconnectEngine(outputFormat: AVAudioFormat, playerNodeFormat: AVAudioFormat) throws {
+    func reconnectEngine(outputFormat: AVAudioFormat, playerNodeFormat: AVAudioFormat) throws(LiveKitError) {
         playerNodePool.stop()
         engine.stop()
         engine.disconnect(playerNodePool)
         playerNodePool.setMaximumFramesToRender(engine.outputNode.auAudioUnit.maximumFramesToRender)
         engine.connect(playerNodePool, to: engine.mainMixerNode,
                        format: outputFormat, playerNodeFormat: playerNodeFormat)
-        try engine.start()
+        do {
+            try engine.start()
+        } catch {
+            throw LiveKitError(.audioEngine, internalError: error)
+        }
         localEngineState.connectedOutputFormat = outputFormat
         localEngineState.playerNodeFormat = playerNodeFormat
         localEngineState.needsReconnect = false
     }
 
     @discardableResult
-    func startEngineIfNeeded() throws -> AVAudioFormat {
+    func startEngineIfNeeded() throws(LiveKitError) -> AVAudioFormat {
         guard let outputFormat else {
             throw LiveKitError(.soundPlayer, message: "Invalid output format")
         }
@@ -245,7 +249,7 @@ extension SoundPlayer {
         await soundState.stop(destination: destination)
     }
 
-    func play(_ sound: SoundHandle, options: SoundPlaybackOptions = SoundPlaybackOptions()) async throws {
+    func play(_ sound: SoundHandle, options: SoundPlaybackOptions = SoundPlaybackOptions()) async throws(LiveKitError) {
         guard let soundState = sounds[sound.id] else {
             throw LiveKitError(.soundPlayer, message: "Sound not prepared")
         }
@@ -272,12 +276,12 @@ extension SoundPlayer {
         }
     }
 
-    static func decodeBuffer(from fileURL: URL) async throws -> AVAudioPCMBuffer {
+    static func decodeBuffer(from fileURL: URL) async throws(LiveKitError) -> AVAudioPCMBuffer {
         guard fileURL.isFileURL else {
             throw LiveKitError(.invalidParameter, message: "Only file URLs are supported")
         }
 
-        return try await Task.detached(priority: .userInitiated) {
+        let task = Task.detached(priority: .userInitiated) { () throws -> AVAudioPCMBuffer in
             let audioFile = try AVAudioFile(forReading: fileURL)
             guard let readBuffer = AVAudioPCMBuffer(pcmFormat: audioFile.processingFormat,
                                                     frameCapacity: AVAudioFrameCount(audioFile.length))
@@ -286,6 +290,13 @@ extension SoundPlayer {
             }
             try audioFile.read(into: readBuffer, frameCount: AVAudioFrameCount(audioFile.length))
             return readBuffer
-        }.value
+        }
+        do {
+            return try await task.value
+        } catch let error as LiveKitError {
+            throw error
+        } catch {
+            throw LiveKitError(.soundPlayer, internalError: error)
+        }
     }
 }

Sources/LiveKit/Broadcast/IPC/BroadcastAudioCodec.swift

@@ -94,6 +94,8 @@ struct BroadcastAudioCodec {
 }
 
 extension AudioStreamBasicDescription: Codable {
+    // Encodable.encode requires untyped throws.
+    // swiftlint:disable:next public_typed_throws
     public func encode(to encoder: any Encoder) throws {
         var container = encoder.unkeyedContainer()
         try container.encode(mSampleRate)