@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/FoundationBridge/UserDefaults.swift

@@ -0,0 +1,183 @@
+// `UserDefaults` that survives reloads (corelibs Foundation's cannot persist on
+// WASI; the CLI's generated file aliases this one in the app). Values live in memory and are mirrored
+// to the host: every change is sent as a `defaults` op (the whole dictionary
+// as JSON), which the browser stores per app in localStorage and hands back at
+// the next launch through the `SB_DEFAULTS` environment variable. Headless
+// runs print the op like any other, so a snapshot shows what an app saves.
+//
+// JSON cannot tell an Int from a Double or carry Data and Date; integers
+// travel as whole numbers (and come back as Int), `Data` as `{"$data": base64}`,
+// `Date` as `{"$date": seconds}`, `URL` as `{"$url": string}`.
+
+import Foundation
+import SwiftUI
+
+/// Equal and hashed by identity, as an `NSObject` is on Apple platforms.
+public final class UserDefaults: Hashable, @unchecked Sendable {
+    nonisolated(unsafe) public static let standard = UserDefaults(persistent: true)
+
+    private var storage: [String: Any] = [:]
+    private var registered: [String: Any] = [:]
+    private let persistent: Bool
+
+    init(persistent: Bool) {
+        self.persistent = persistent
+        if persistent, let text = _environment("SB_DEFAULTS"), let json = try? _JSON.parse(text), case .object(let values) = json {
+            for (key, value) in values { storage[key] = _defaultsValue(fromJSON: value) }
+        }
+    }
+
+    public convenience init() { self.init(persistent: false) }
+    /// Suites are not separated: every suite is the standard defaults.
+    public convenience init?(suiteName: String?) { self.init(persistent: true) }
+
+    // MARK: Reading
+
+    public func object(forKey key: String) -> Any? { storage[key] ?? registered[key] }
+    /// Key-value coding's read, which answers the default for the key.
+    public func value(forKey key: String) -> Any? { object(forKey: key) }
+    public func string(forKey key: String) -> String? {
+        switch object(forKey: key) {
+        case let s as String: s
+        case let n as Int: String(n)
+        case let n as Double: String(n)
+        default: nil
+        }
+    }
+    public func array(forKey key: String) -> [Any]? { object(forKey: key) as? [Any] }
+    public func dictionary(forKey key: String) -> [String: Any]? { object(forKey: key) as? [String: Any] }
+    public func data(forKey key: String) -> Data? { object(forKey: key) as? Data }
+    public func stringArray(forKey key: String) -> [String]? {
+        guard let array = object(forKey: key) as? [Any] else { return nil }
+        let strings = array.compactMap { $0 as? String }
+        return strings.count == array.count ? strings : nil
+    }
+    public func url(forKey key: String) -> URL? {
+        switch object(forKey: key) {
+        case let url as URL: url
+        case let s as String: URL(string: s)
+        default: nil
+        }
+    }
+    public func integer(forKey key: String) -> Int {
+        switch object(forKey: key) {
+        case let n as Int: n
+        case let n as Double: Int(n)
+        case let s as String: Int(s) ?? 0
+        case let b as Bool: b ? 1 : 0
+        default: 0
+        }
+    }
+    public func float(forKey key: String) -> Float { Float(double(forKey: key)) }
+    public func double(forKey key: String) -> Double {
+        switch object(forKey: key) {
+        case let n as Double: n
+        case let n as Int: Double(n)
+        case let s as String: Double(s) ?? 0
+        case let b as Bool: b ? 1 : 0
+        default: 0
+        }
+    }
+    public func bool(forKey key: String) -> Bool {
+        switch object(forKey: key) {
+        case let b as Bool: b
+        case let n as Int: n != 0
+        case let n as Double: n != 0
+        case let s as String: s == "true" || s == "YES" || s == "1"
+        default: false
+        }
+    }
+
+    // MARK: Writing
+
+    public func set(_ value: Any?, forKey key: String) {
+        if let value { storage[key] = value } else { storage[key] = nil }
+        persist()
+        _DefaultsKey.named(key).changed()
+    }
+    public func set(_ value: Int, forKey key: String) { set(value as Any, forKey: key) }
+    public func set(_ value: Double, forKey key: String) { set(value as Any, forKey: key) }
+    public func set(_ value: Float, forKey key: String) { set(Double(value) as Any, forKey: key) }
+    public func set(_ value: Bool, forKey key: String) { set(value as Any, forKey: key) }
+    public func set(_ url: URL?, forKey key: String) { set(url as Any?, forKey: key) }
+    public func removeObject(forKey key: String) { set(nil, forKey: key) }
+
+    /// Fallback values, read when nothing was set; never persisted.
+    public func register(defaults: [String: Any]) {
+        for (key, value) in defaults {
+            registered[key] = value
+            _DefaultsKey.named(key).changed()
+        }
+    }
+    public func dictionaryRepresentation() -> [String: Any] {
+        var all = registered
+        for (key, value) in storage { all[key] = value }
+        return all
+    }
+    public func removePersistentDomain(forName domainName: String) {
+        storage.removeAll()
+        persist()
+        for key in _DefaultsKey.all { key.changed() }
+    }
+    @discardableResult public func synchronize() -> Bool { true }
+
+    /// The saved values as the host stores them.
+    public var _json: _JSON {
+        var fields: [String: _JSON] = [:]
+        for (key, value) in storage {
+            if let json = _defaultsJSON(from: value) { fields[key] = json }
+        }
+        return .object(fields)
+    }
+
+    private func persist() {
+        guard persistent else { return }
+        let json = _json
+        MainActor.assumeIsolated { _Runtime.shared.storeDefaults(json) }
+    }
+
+    public static func == (lhs: UserDefaults, rhs: UserDefaults) -> Bool { lhs === rhs }
+    public func hash(into hasher: inout Hasher) { hasher.combine(ObjectIdentifier(self)) }
+}
+
+/// A defaults value as JSON; nil for a type the store cannot carry.
+func _defaultsJSON(from value: Any) -> _JSON? {
+    switch value {
+    case let v as String: return .string(v)
+    case let v as Bool: return .bool(v)
+    case let v as Int: return .number(Double(v))
+    case let v as Double: return .number(v)
+    case let v as Float: return .number(Double(v))
+    case let v as Data: return .object(["$data": .string(v.base64EncodedString())])
+    case let v as Date: return .object(["$date": .number(v.timeIntervalSince1970)])
+    case let v as URL: return .object(["$url": .string(v.absoluteString)])
+    case let v as [Any]: return .array(v.compactMap(_defaultsJSON(from:)))
+    case let v as [String: Any]:
+        var fields: [String: _JSON] = [:]
+        for (key, item) in v { if let json = _defaultsJSON(from: item) { fields[key] = json } }
+        return .object(fields)
+    default:
+        print("[UserDefaults] cannot save a value of type \(type(of: value)); use a property-list type")
+        return nil
+    }
+}
+
+func _defaultsValue(fromJSON json: _JSON) -> Any? {
+    switch json {
+    case .null: return nil
+    case .bool(let b): return b
+    case .string(let s): return s
+    case .number(let n): return n == n.rounded() && abs(n) < 9_007_199_254_740_992 ? Int(n) as Any : n
+    case .bytes(let bytes): return Data(bytes)
+    case .array(let items): return items.compactMap(_defaultsValue(fromJSON:))
+    case .object(let fields):
+        if fields.count == 1 {
+            if case .string(let b64)? = fields["$data"], let data = Data(base64Encoded: b64) { return data }
+            if case .number(let seconds)? = fields["$date"] { return Date(timeIntervalSince1970: seconds) }
+            if case .string(let text)? = fields["$url"], let url = URL(string: text) { return url }
+        }
+        var out: [String: Any] = [:]
+        for (key, item) in fields { if let value = _defaultsValue(fromJSON: item) { out[key] = value } }
+        return out
+    }
+}

package/Sources/FoundationBridge/WebAuthRedirects.swift

@@ -0,0 +1,227 @@
+// OAuth redirects to the app's own URL scheme, in the browser. An iOS app
+// signs in by registering `myapp://…` as its OAuth redirect URI and letting
+// `ASWebAuthenticationSession` catch the provider's redirect to it. A web
+// page cannot receive a redirect to a custom scheme: the browser would hand
+// it to another app, or fail. So the page serves a callback page at its own
+// origin (Web/public/app/oauth-callback.html), and wherever one of the app's
+// schemes appears as an OAuth redirect, the shim puts that page's URL in its
+// place, with the original scheme (and what followed it) in the query so the
+// app's URL can be rebuilt:
+//
+//     icecubesapp://          →  <page>/app/oauth-callback.html?sb_scheme=icecubesapp
+//     myapp://auth/done?x=1   →  <page>/app/oauth-callback.html?sb_scheme=myapp&sb_target=%2F%2Fauth%2Fdone%3Fx%3D1
+//
+// The swap is narrow. Only the app's own schemes: those it declares
+// (CFBundleURLTypes in its Info.plist; the CLI hands them to the page, and
+// the page to the app as `SB_URL_SCHEMES`), plus the `callbackURLScheme` of
+// a session once it starts. Only the redirect parameters, `redirect_uri` and
+// `redirect_uris`: in the query of a URLSession request, in a form or JSON
+// body (top-level keys; bodies up to 64 KiB), and in the authorize URL a
+// web authentication session opens. The app's registration, the authorize
+// request and the token exchange so all carry the same page URL, and the
+// provider sees one consistent redirect URI. The provider redirects the
+// sign-in window to the callback page, which hands its URL back to the app's
+// page; `appURL(fromCallback:)` rebuilds `icecubesapp://?code=…` for the app
+// (docs/ops-protocol.md, "Signing in").
+
+import Foundation
+import SwiftUI
+
+public enum _WebAuthRedirects {
+    /// The parameters whose values are redirect URIs (OAuth 2's `redirect_uri`,
+    /// and `redirect_uris` of dynamic client registration and Mastodon's apps API).
+    public static let parameterNames: Set<String> = ["redirect_uri", "redirect_uris"]
+
+    /// The query items that carry the app's redirect on the callback page.
+    static let schemeItem = "sb_scheme"
+    static let targetItem = "sb_target"
+
+    /// Where the page serves its callback page when it does not say
+    /// (`SB_WEB_AUTH_CALLBACK` unset: headless runs).
+    public static let defaultCallbackPage = "http://localhost/app/oauth-callback.html"
+
+    /// Bodies larger than this are uploads, not OAuth forms; they are not examined.
+    static let bodyLimit = 64 * 1024
+
+    /// Schemes sessions registered. Only ever added to; one thread on WASI.
+    nonisolated(unsafe) static var sessionSchemes: Set<String> = []
+
+    /// The app's URL schemes, lower-cased: `SB_URL_SCHEMES`, plus those
+    /// sessions registered.
+    public static var schemes: Set<String> {
+        parseSchemes(_environment("SB_URL_SCHEMES") ?? "").union(sessionSchemes)
+    }
+
+    /// `SB_URL_SCHEMES`: schemes separated by commas or spaces.
+    static func parseSchemes(_ text: String) -> Set<String> {
+        Set(text.split(whereSeparator: { $0 == "," || $0 == " " || $0 == "\n" }).map { $0.lowercased() })
+    }
+
+    /// Adds a scheme for the rest of the run (a session's `callbackURLScheme`).
+    public static func register(scheme: String) {
+        let scheme = scheme.lowercased()
+        guard !scheme.isEmpty, scheme != "http", scheme != "https" else { return }
+        sessionSchemes.insert(scheme)
+    }
+
+    /// The page's callback page (`SB_WEB_AUTH_CALLBACK`, which the page sets).
+    public static var callbackPage: String {
+        _environment("SB_WEB_AUTH_CALLBACK") ?? defaultCallbackPage
+    }
+
+    // MARK: Redirect URIs
+
+    /// Whether `value` is a URI in one of the app's schemes.
+    public static func isAppRedirect(_ value: String) -> Bool {
+        guard let colon = value.firstIndex(of: ":") else { return false }
+        let scheme = value[..<colon].lowercased()
+        guard !scheme.isEmpty, scheme != "http", scheme != "https" else { return false }
+        return schemes.contains(scheme)
+    }
+
+    /// The callback page URL that stands for the app's redirect `value`, or
+    /// nil when `value` is not in one of the app's schemes.
+    public static func pageURL(forAppRedirect value: String) -> String? {
+        guard isAppRedirect(value), let colon = value.firstIndex(of: ":") else { return nil }
+        let scheme = String(value[..<colon])
+        let target = String(value[value.index(after: colon)...])
+        var url = callbackPage
+        url += url.contains("?") ? "&" : "?"
+        url += "\(schemeItem)=\(encode(scheme))"
+        // `myapp://` is the common case; its `//` is implied.
+        if target != "//" { url += "&\(targetItem)=\(encode(target))" }
+        return url
+    }
+
+    /// The app's URL for a URL the callback page was opened at: its scheme and
+    /// target back in front, the provider's query items (`code`, `state`, …)
+    /// added to the target's query, and the fragment kept. Nil when `url` is
+    /// not a callback page URL.
+    public static func appURL(fromCallback url: String) -> String? {
+        guard let components = URLComponents(string: url),
+              let items = components.percentEncodedQueryItems,
+              let scheme = items.first(where: { $0.name == schemeItem })?.value?.removingPercentEncoding,
+              !scheme.isEmpty
+        else { return nil }
+        let target = items.first(where: { $0.name == targetItem })?.value?.removingPercentEncoding ?? "//"
+        var result = "\(scheme):\(target)"
+        let rest = items.filter { $0.name != schemeItem && $0.name != targetItem }
+        if !rest.isEmpty {
+            result += result.contains("?") ? "&" : "?"
+            result += rest.map { item in item.value.map { "\(item.name)=\($0)" } ?? item.name }.joined(separator: "&")
+        }
+        if let fragment = components.percentEncodedFragment { result += "#\(fragment)" }
+        return result
+    }
+
+    /// A redirect parameter's value with each of the app's URIs replaced; a
+    /// space- or newline-separated list (`redirect_uris`) is rewritten item by item.
+    public static func rewriteRedirectValue(_ value: String) -> String {
+        let separator: Character = value.contains("\n") ? "\n" : " "
+        guard value.contains(separator) else { return pageURL(forAppRedirect: value) ?? value }
+        return value.split(separator: separator, omittingEmptySubsequences: false)
+            .map { pageURL(forAppRedirect: String($0)) ?? String($0) }
+            .joined(separator: String(separator))
+    }
+
+    // MARK: Requests
+
+    /// `url` with the app's URIs in its redirect query items replaced (the
+    /// URL itself when there are none).
+    public static func rewriting(url: URL) -> URL {
+        guard !schemes.isEmpty, let query = url.query, query.contains("redirect_uri"),
+              var components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              let items = components.percentEncodedQueryItems
+        else { return url }
+        var changed = false
+        let rewritten = items.map { item -> URLQueryItem in
+            guard parameterNames.contains(item.name), let value = item.value?.removingPercentEncoding else { return item }
+            let new = rewriteRedirectValue(value)
+            guard new != value else { return item }
+            changed = true
+            return URLQueryItem(name: item.name, value: encode(new))
+        }
+        guard changed else { return url }
+        components.percentEncodedQueryItems = rewritten
+        return components.url ?? url
+    }
+
+    /// `body` with the app's URIs in its redirect parameters replaced: the
+    /// top-level keys of a JSON object, or the fields of a form
+    /// (`application/x-www-form-urlencoded`). Other bodies come back as they were.
+    public static func rewriting(body: Data?, contentType: String?) -> Data? {
+        guard let body, !body.isEmpty, body.count <= bodyLimit, !schemes.isEmpty else { return body }
+        let text = String(decoding: body, as: UTF8.self)
+        guard text.contains("redirect_uri") else { return body }
+        let type = contentType?.lowercased() ?? ""
+        if type.contains("json") || (type.isEmpty && text.first(where: { !$0.isWhitespace }) == "{") {
+            return rewritingJSON(text).map { Data($0.utf8) } ?? body
+        }
+        if type.contains("x-www-form-urlencoded") || type.isEmpty {
+            return rewritingForm(text).map { Data($0.utf8) } ?? body
+        }
+        return body
+    }
+
+    /// The JSON object with its redirect keys rewritten; nil when nothing changed.
+    static func rewritingJSON(_ text: String) -> String? {
+        guard case .object(var object)? = try? _JSON.parse(text) else { return nil }
+        var changed = false
+        for name in parameterNames {
+            switch object[name] {
+            case .string(let value)?:
+                let new = rewriteRedirectValue(value)
+                if new != value { object[name] = .string(new); changed = true }
+            case .array(let values)?:
+                let new = values.map { item -> _JSON in
+                    if case .string(let value) = item { return .string(rewriteRedirectValue(value)) }
+                    return item
+                }
+                if new != values { object[name] = .array(new); changed = true }
+            default:
+                break
+            }
+        }
+        return changed ? _JSON.object(object).serialized : nil
+    }
+
+    /// The form with its redirect fields rewritten; nil when nothing changed.
+    static func rewritingForm(_ text: String) -> String? {
+        var changed = false
+        let fields = text.split(separator: "&", omittingEmptySubsequences: false).map { field -> String in
+            guard let equals = field.firstIndex(of: "=") else { return String(field) }
+            let name = formDecode(field[..<equals])
+            guard parameterNames.contains(name) else { return String(field) }
+            let value = formDecode(field[field.index(after: equals)...])
+            let new = rewriteRedirectValue(value)
+            guard new != value else { return String(field) }
+            changed = true
+            return "\(field[..<equals])=\(encode(new))"
+        }
+        return changed ? fields.joined(separator: "&") : nil
+    }
+
+    // MARK: Encoding
+
+    /// RFC 3986's unreserved characters stay; everything else is percent-encoded.
+    static func encode(_ text: String) -> String {
+        var out = ""
+        for byte in text.utf8 {
+            switch byte {
+            case UInt8(ascii: "A")...UInt8(ascii: "Z"), UInt8(ascii: "a")...UInt8(ascii: "z"),
+                 UInt8(ascii: "0")...UInt8(ascii: "9"), UInt8(ascii: "-"), UInt8(ascii: "."),
+                 UInt8(ascii: "_"), UInt8(ascii: "~"):
+                out.unicodeScalars.append(UnicodeScalar(byte))
+            default:
+                let hex = Array("0123456789ABCDEF")
+                out += "%\(hex[Int(byte >> 4)])\(hex[Int(byte & 15)])"
+            }
+        }
+        return out
+    }
+
+    static func formDecode(_ text: Substring) -> String {
+        let spaced = text.replacingOccurrences(of: "+", with: " ")
+        return spaced.removingPercentEncoding ?? spaced
+    }
+}

package/Sources/FoundationBridge/WebSocket.swift

@@ -0,0 +1,187 @@
+// `URLSessionWebSocketTask` over the browser's WebSocket. Each call is a host
+// request of kind `websocket` (docs/ops-protocol.md, "WebSockets"):
+// `open` connects and answers the socket's id once it is open, `send` sends a
+// message, `receive` answers the next message (queued by the page as it
+// arrives), and `close` closes. The pull model matches the task's own: an
+// app calls `receive` again for every message.
+
+import Foundation
+import SwiftUI
+
+open class URLSessionWebSocketTask: URLSessionTask, @unchecked Sendable {
+    public enum Message: Sendable {
+        case data(Data)
+        case string(String)
+    }
+
+    public enum CloseCode: Int, Sendable {
+        case invalid = 0
+        case normalClosure = 1000
+        case goingAway = 1001
+        case protocolError = 1002
+        case unsupportedData = 1003
+        case noStatusReceived = 1005
+        case abnormalClosure = 1006
+        case invalidFramePayloadData = 1007
+        case policyViolation = 1008
+        case messageTooBig = 1009
+        case mandatoryExtensionMissing = 1010
+        case internalServerError = 1011
+        case tlsHandshakeFailure = 1015
+    }
+
+    public var maximumMessageSize = 1_048_576
+    public private(set) var closeCode: CloseCode = .invalid
+    public private(set) var closeReason: Data?
+
+    let url: URL
+    let protocols: [String]
+    /// The connection, opened on `resume()` (or the first send or receive).
+    private var connection: Task<Int, any Error>?
+
+    init(identifier: Int, request: URLRequest, url: URL, protocols: [String]) {
+        self.url = url
+        self.protocols = protocols
+        super.init(identifier: identifier, request: request) { task in
+            _ = try? await (task as! URLSessionWebSocketTask).socket()
+        }
+    }
+
+    /// The page's id for the open socket.
+    @MainActor func socket() async throws -> Int {
+        if connection == nil {
+            let params: _JSON = .object([
+                "action": .string("open"),
+                "url": .string(url.absoluteString),
+                "protocols": .array(protocols.map { .string($0) }),
+            ])
+            let url = self.url
+            connection = Task { @MainActor in
+                let value = try await Self.host(params, url: url)
+                guard case .object(let fields) = value, case .number(let id)? = fields["socket"] else {
+                    throw URLError(.badServerResponse, userInfo: ["NSErrorFailingURLKey": url])
+                }
+                return Int(id)
+            }
+        }
+        return try await connection!.value
+    }
+
+    @MainActor static func host(_ params: _JSON, url: URL) async throws -> _JSON {
+        do {
+            return try await _Runtime.shared._hostRequest(kind: "websocket", params: params)
+        } catch let failure as _HostRequestError {
+            throw URLSession.urlError(from: failure.message, url: url)
+        }
+    }
+
+    // MARK: Messages
+
+    @MainActor public func send(_ message: Message) async throws {
+        let id = try await socket()
+        var params: [String: _JSON] = ["action": .string("send"), "socket": .number(Double(id))]
+        switch message {
+        case .string(let text): params["string"] = .string(text)
+        case .data(let data): params["data"] = .string(data.base64EncodedString())
+        }
+        _ = try await Self.host(.object(params), url: url)
+    }
+
+    public func send(_ message: Message, completionHandler: @escaping @Sendable ((any Error)?) -> Void) {
+        Task { @MainActor in
+            do {
+                try await self.send(message)
+                completionHandler(nil)
+            } catch {
+                completionHandler(error)
+            }
+        }
+    }
+
+    /// The next message; fails once the socket is closed.
+    @MainActor public func receive() async throws -> Message {
+        let id = try await socket()
+        let value = try await Self.host(.object(["action": .string("receive"), "socket": .number(Double(id))]), url: url)
+        guard case .object(let fields) = value else { throw URLError(.badServerResponse) }
+        if case .string(let text)? = fields["string"] { return .string(text) }
+        if case .string(let encoded)? = fields["data"], let data = Data(base64Encoded: encoded) { return .data(data) }
+        if case .number(let code)? = fields["closeCode"] {
+            closeCode = CloseCode(rawValue: Int(code)) ?? .abnormalClosure
+            if case .string(let reason)? = fields["reason"], !reason.isEmpty { closeReason = Data(reason.utf8) }
+            finish(response: response, error: URLError(.networkConnectionLost))
+        }
+        throw URLError(.networkConnectionLost, userInfo: ["NSErrorFailingURLKey": url])
+    }
+
+    public func receive(completionHandler: @escaping @Sendable (Result<Message, any Error>) -> Void) {
+        Task { @MainActor in
+            do {
+                completionHandler(.success(try await self.receive()))
+            } catch {
+                completionHandler(.failure(error))
+            }
+        }
+    }
+
+    /// Browsers send pings themselves and do not expose them: the handler is called once the socket is open.
+    public func sendPing(pongReceiveHandler: @escaping @Sendable ((any Error)?) -> Void) {
+        Task { @MainActor in
+            do {
+                _ = try await self.socket()
+                pongReceiveHandler(nil)
+            } catch {
+                pongReceiveHandler(error)
+            }
+        }
+    }
+
+    public func cancel(with closeCode: CloseCode, reason: Data?) {
+        self.closeCode = closeCode
+        closeReason = reason
+        close(code: closeCode == .invalid ? .normalClosure : closeCode, reason: reason)
+    }
+
+    public override func cancel() {
+        close(code: .normalClosure, reason: nil)
+    }
+
+    private func close(code: CloseCode, reason: Data?) {
+        let connection = self.connection
+        let url = self.url
+        finish(response: response, error: URLError(.cancelled))
+        guard let connection else { return }
+        Task { @MainActor in
+            guard let id = try? await connection.value else { return }
+            var params: [String: _JSON] = ["action": .string("close"), "socket": .number(Double(id)), "code": .number(Double(code.rawValue))]
+            if let reason { params["reason"] = .string(String(decoding: reason, as: UTF8.self)) }
+            _ = try? await Self.host(.object(params), url: url)
+        }
+    }
+}
+
+public protocol URLSessionWebSocketDelegate: URLSessionTaskDelegate {
+    func urlSession(_ session: URLSession, webSocketTask: URLSessionWebSocketTask, didOpenWithProtocol protocol: String?)
+    func urlSession(_ session: URLSession, webSocketTask: URLSessionWebSocketTask, didCloseWith closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?)
+}
+
+extension URLSessionWebSocketDelegate {
+    public func urlSession(_ session: URLSession, webSocketTask: URLSessionWebSocketTask, didOpenWithProtocol protocol: String?) {}
+    public func urlSession(_ session: URLSession, webSocketTask: URLSessionWebSocketTask, didCloseWith closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?) {}
+}
+
+extension URLSession {
+    public func webSocketTask(with url: URL) -> URLSessionWebSocketTask {
+        webSocketTask(with: url, protocols: [])
+    }
+
+    public func webSocketTask(with url: URL, protocols: [String]) -> URLSessionWebSocketTask {
+        URLSessionWebSocketTask(identifier: takeIdentifier(), request: URLRequest(url: url), url: url, protocols: protocols)
+    }
+
+    public func webSocketTask(with request: URLRequest) -> URLSessionWebSocketTask {
+        let url = request.url ?? URL(string: "about:blank")!
+        let protocols = request.value(forHTTPHeaderField: "Sec-WebSocket-Protocol")?
+            .split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) } ?? []
+        return URLSessionWebSocketTask(identifier: takeIdentifier(), request: request, url: url, protocols: protocols)
+    }
+}