[WIP] WebSocket

README.md

@@ -26,6 +26,67 @@ let response = jellyfinClient.signIn(username: "jelly", password: "fin")
 
 Alternatively, you can use your own network stack with the generated **Entities** and **Paths**.
 
+## WebSocket
+
+`JellyfinSocket` creates and manages a persistent WebSocket connection to the Jellyfin server, delivering real-time updates. Once connected, higher volumne endpoints can be subscribed to like sessions, scheduled tasks, or activity logs.
+
+```swift
+/// Create a WebSocket instance with all available parameters
+let socket = JellyfinSocket(
+    client: client,
+    userID: user.id,
+    isSupportsMediaControl: true,
+    supportedCommands: [.displayMessage, .play, .pause],
+    logLevel: .debug
+)
+
+/// Observe socket state changes
+let stateSubscription = socket.$state
+    .receive(on: DispatchQueue.main)
+    .sink { state in
+        switch state {
+        case .idle:
+            print("Socket is idle")
+        case .connecting:
+            print("Connecting...")
+        case .connected(let url):
+            print("Connected to: \(url)")
+        case .disconnecting:
+            print("Disconnecting...")
+        case .closed(let error):
+            print("Closed: \(String(describing: error))")
+        case .error(let error):
+            print("Socket error: \(error)")
+        }
+    }
+
+/// Observe parsed server messages
+let messageSubscription = socket.messages
+    .receive(on: DispatchQueue.main)
+    .sink { message in
+        switch message {
+        case .sessionsMessage(let msg):
+            print("Received session update: \(msg)")
+        case .outboundKeepAliveMessage:
+            print("Received keep-alive pong")
+        default:
+            break
+        }
+    }
+
+/// Connect the socket
+socket.connect()
+
+/// Subscribe to sessions feed immediately with updates every 2 seconds
+socket.subscribe(.sessions(initialDelayMs: 0, intervalMs: 2000))
+
+/// Later, unsubscribe
+socket.unsubscribe(.sessions())
+
+/// Gracefully disconnect (optional; also triggered by deinit)
+socket.disconnect()
+```
+
 ## Quick Connect
 
 The `QuickConnect` object has been provided to perform the Quick Connect authorization flow.
@@ -59,4 +120,4 @@ quickConnect.start()
 $ make update
 ```
 
-Alternatively, you can generate your own Swift Jellyfin SDK using [CreateAPI](https://github.com/CreateAPI/CreateAPI) or any other OpenAPI generator.
+Alternatively, you can generate your own Swift Jellyfin SDK using [CreateAPI](https://github.com/CreateAPI/CreateAPI) or any other OpenAPI generator.

Sources/Extensions/SocketError.swift

@@ -0,0 +1,54 @@
+//
+// jellyfin-sdk-swift is subject to the terms of the Mozilla Public
+// License, v2.0. If a copy of the MPL was not distributed with this
+// file, you can obtain one at https://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) 2025 Jellyfin & Jellyfin Contributors
+//
+
+import Foundation
+
+/// Error types specific to the JellyfinSocket
+public enum SocketError: Error, LocalizedError, Equatable {
+    case notConnected
+    case missingAccessTokenOrConfig
+    case invalidURL
+    case encodingFailed(String)
+    case maxReconnectAttemptsReached
+    case explicitDisconnect
+    case connectionTimeout
+    case serverMessageError(String)
+    case underlyingError(String)
+    case decodingError(String)
+
+    /// Human-readable error descriptions
+    public var errorDescription: String? {
+        switch self {
+        case .notConnected: 
+            return "WebSocket is not connected."
+        case .missingAccessTokenOrConfig: 
+            return "Missing access token, device ID, or server URL for WebSocket connection."
+        case .invalidURL: 
+            return "Invalid WebSocket URL."
+        case .encodingFailed(let reason):
+            return "Failed to encode message: \(reason)"
+        case .maxReconnectAttemptsReached: 
+            return "Maximum reconnection attempts reached."
+        case .explicitDisconnect: 
+            return "Disconnected by client."
+        case .connectionTimeout: 
+            return "Connection attempt timed out or server unresponsive."
+        case .serverMessageError(let message): 
+            return "Server returned an error message: \(message)"
+        case .underlyingError(let message): 
+            return "An underlying error occurred: \(message)"
+        case .decodingError(let message): 
+            return "Failed to decode server message: \(message)"
+        }
+    }
+
+    /// Equality comparison for SocketError types
+    public static func == (lhs: SocketError, rhs: SocketError) -> Bool {
+        lhs.localizedDescription == rhs.localizedDescription
+    }
+}

Sources/Extensions/SocketMessages.swift

@@ -0,0 +1,93 @@
+//
+// jellyfin-sdk-swift is subject to the terms of the Mozilla Public
+// License, v2.0. If a copy of the MPL was not distributed with this
+// file, you can obtain one at https://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) 2025 Jellyfin & Jellyfin Contributors
+//
+
+extension InboundWebSocketMessage {
+    /// Returns the message type for the inbound message
+    var sessionMessageType: SessionMessageType? {
+        switch self {
+        case .activityLogEntryStartMessage(let message):
+            return message.messageType
+        case .activityLogEntryStopMessage(let message):
+            return message.messageType
+        case .inboundKeepAliveMessage(let message):
+            return message.messageType
+        case .scheduledTasksInfoStartMessage(let message):
+            return message.messageType
+        case .scheduledTasksInfoStopMessage(let message):
+            return message.messageType
+        case .sessionsStartMessage(let message):
+            return message.messageType
+        case .sessionsStopMessage(let message):
+            return message.messageType
+        }
+    }
+}
+
+extension OutboundWebSocketMessage {
+    /// Returns the message type for the outbound message
+    var sessionMessageType: SessionMessageType? {
+        switch self {
+        case .activityLogEntryMessage(let message):
+            return message.messageType
+        case .forceKeepAliveMessage(let message):
+            return message.messageType
+        case .generalCommandMessage(let message):
+            return message.messageType
+        case .libraryChangedMessage(let message):
+            return message.messageType
+        case .outboundKeepAliveMessage(let message):
+            return message.messageType
+        case .playMessage(let message):
+            return message.messageType
+        case .playstateMessage(let message):
+            return message.messageType
+        case .pluginInstallationCancelledMessage(let message):
+            return message.messageType
+        case .pluginInstallationCompletedMessage(let message):
+            return message.messageType
+        case .pluginInstallationFailedMessage(let message):
+            return message.messageType
+        case .pluginInstallingMessage(let message):
+            return message.messageType
+        case .pluginUninstalledMessage(let message):
+            return message.messageType
+        case .refreshProgressMessage(let message):
+            return message.messageType
+        case .restartRequiredMessage(let message):
+            return message.messageType
+        case .scheduledTaskEndedMessage(let message):
+            return message.messageType
+        case .scheduledTasksInfoMessage(let message):
+            return message.messageType
+        case .seriesTimerCancelledMessage(let message):
+            return message.messageType
+        case .seriesTimerCreatedMessage(let message):
+            return message.messageType
+        case .serverRestartingMessage(let message):
+            return message.messageType
+        case .serverShuttingDownMessage(let message):
+            return message.messageType
+        case .sessionsMessage(let message):
+            return message.messageType
+        case .syncPlayCommandMessage(let message):
+            return message.messageType
+        case .syncPlayGroupUpdateCommandMessage(let message):
+            return message.messageType
+        case .timerCancelledMessage(let message):
+            return message.messageType
+        case .timerCreatedMessage(let message):
+            return message.messageType
+        case .userDataChangedMessage(let message):
+            return message.messageType
+        case .userDeletedMessage(let message):
+            return message.messageType
+        case .userUpdatedMessage(let message):
+            return message.messageType
+        }
+    }
+}

Sources/Extensions/SocketState.swift

@@ -0,0 +1,67 @@
+//
+// jellyfin-sdk-swift is subject to the terms of the Mozilla Public
+// License, v2.0. If a copy of the MPL was not distributed with this
+// file, you can obtain one at https://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) 2025 Jellyfin & Jellyfin Contributors
+//
+
+import Foundation
+
+/// Represents the possible states of the WebSocket connection
+public enum SocketState: Equatable {
+    case idle
+    case connecting
+    case connected(url: URL)
+    case disconnecting
+    case closed(error: Error?)
+    case error(Error)
+
+    /// Indicates whether the socket is currently in connected state
+    var isConnected: Bool {
+        if case .connected = self { return true }
+        return false
+    }
+
+    /// Equality comparison for JellyfinSocket.State
+    public static func == (lhs: SocketState, rhs: SocketState) -> Bool {
+        switch (lhs, rhs) {
+        case (.idle, .idle):
+            return true
+        case (.connecting, .connecting):
+            return true
+        case let (.connected(url1), .connected(url2)):
+            return url1 == url2
+        case (.disconnecting, .disconnecting):
+            return true
+        case let (.closed(err1), .closed(err2)):
+            if err1 == nil && err2 == nil {
+                return true
+            }
+            if let e1 = err1 as? SocketError, let e2 = err2 as? SocketError {
+                return e1 == e2
+            }
+            return err1?.localizedDescription == err2?.localizedDescription
+        case let (.error(err1), .error(err2)):
+            if let e1 = err1 as? SocketError, let e2 = err2 as? SocketError {
+                return e1 == e2
+            }
+            return err1.localizedDescription == err2.localizedDescription
+        default:
+            return false
+        }
+    }
+
+    /// Checks if the state is a closed error with the specified error
+    /// - Parameter error: The error to compare against
+    /// - Returns: Whether the state is a closed error with the specified error
+    func isClosedError(_ error: Error) -> Bool {
+        if case .closed(let e) = self {
+            if let socketErr = e as? SocketError, let comparableErr = error as? SocketError {
+                return socketErr == comparableErr
+            }
+            return e?.localizedDescription == error.localizedDescription
+        }
+        return false
+    }
+}

Sources/Extensions/SocketSubscription.swift

@@ -0,0 +1,30 @@
+//
+// jellyfin-sdk-swift is subject to the terms of the Mozilla Public
+// License, v2.0. If a copy of the MPL was not distributed with this
+// file, you can obtain one at https://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) 2025 Jellyfin & Jellyfin Contributors
+//
+
+import Foundation
+
+/// Types of subscriptions supported by the Jellyfin WebSocket
+public enum SocketSubscription: Hashable {
+    case sessions(initialDelayMs: Int = 0, intervalMs: Int = 10000)
+    case scheduledTasks(initialDelayMs: Int = 0, intervalMs: Int = 60000)
+    case activityLog(initialDelayMs: Int = 0, intervalMs: Int = 5000)
+
+    /// Formats the subscription parameters as a string for the server
+    var data: String? {
+        let parameters: (Int, Int)
+        switch self {
+        case .sessions(let delay, let interval):
+            parameters = (delay, interval)
+        case .scheduledTasks(let delay, let interval):
+            parameters = (delay, interval)
+        case .activityLog(let delay, let interval):
+            parameters = (delay, interval)
+        }
+        return "\(parameters.0),\(parameters.1)"
+    }
+}