react-nitro-networking 0.0.0-stage → 0.0.1-alpha.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,102 @@
+// swift-tools-version: 6.4
+
+import Foundation
+import PackageDescription
+
+let name = "ReactNitroNetworking"
+let generated = "nitrogen/generated"
+let nitroDependencies: [Target.Dependency] = [
+  .product(name: "NitroModules", package: "nitro-core")
+]
+let cxxSettings: [CXXSetting] = [
+  .define("DEBUG", .when(configuration: .debug)),
+  .define("NDEBUG", .when(configuration: .release)),
+  .disableWarning("nullability-extension"),
+]
+let swiftSources = ["Sources/ReactNitroNetworking", "\(generated)/apple/swift"]
+let bridgeSources = [
+  "c++", "ReactNitroNetworking-Swift-Cxx-Bridge.cpp", "ReactNitroNetworkingAutolinking.cpp",
+]
+
+// Bare-host integration. Nitrogen generates the bindings; this manifest owns the targets.
+let package = Package(
+  name: name,
+  platforms: [.iOS(.v16), .macOS(.v13)],
+  products: [
+    .library(name: name, targets: ["\(name)Cxx", name, "\(name)SwiftBridge"])
+  ],
+  dependencies: [
+    .package(path: "../nitro-core")
+  ],
+  targets: [
+    .target(
+      name: "\(name)Cxx",
+      dependencies: nitroDependencies,
+      path: "\(generated)/shared/c++",
+      exclude: ["include"],
+      publicHeadersPath: "include",
+      cxxSettings: cxxSettings
+    ),
+    .target(
+      name: "\(name)AppleCxx",
+      dependencies: [.target(name: "\(name)Cxx")] + nitroDependencies,
+      path: "\(generated)/apple/\(name)AppleCxx",
+      cxxSettings: cxxSettings
+    ),
+    .target(
+      name: name,
+      dependencies: [.target(name: "\(name)AppleCxx")] + nitroDependencies,
+      path: ".",
+      exclude: excludes(in: ".", keeping: swiftSources),
+      sources: swiftSources,
+      cxxSettings: cxxSettings,
+      swiftSettings: [
+        // UIKit implementations run synchronously on the host's main thread.
+        .swiftLanguageMode(.v5),
+        .unsafeFlags(["-strict-concurrency=minimal"]),
+        .enableUpcomingFeature("InternalImportsByDefault"),
+        .enableUpcomingFeature("MemberImportVisibility"),
+        .interoperabilityMode(.Cxx),
+        .unsafeFlags(["-Xfrontend", "-clang-header-expose-decls=has-expose-attr-or-stdlib"]),
+        .unsafeFlags([
+          "-Xfrontend", "-clang-header-expose-module",
+          "-Xfrontend", "NitroModules=NitroModules-Swift.h",
+        ]),
+      ]
+    ),
+    .target(
+      name: "\(name)SwiftBridge",
+      dependencies: [.target(name: name), .target(name: "\(name)AppleCxx")] + nitroDependencies,
+      path: "\(generated)/apple",
+      exclude: excludes(in: "\(generated)/apple", keeping: bridgeSources) + ["c++/include"],
+      sources: bridgeSources,
+      publicHeadersPath: "c++/include",
+      cxxSettings: cxxSettings + [
+        .unsafeFlags(["-I${GENERATED_MODULEMAP_DIR}", "-fno-modules"])
+      ]
+    ),
+  ],
+  cxxLanguageStandard: .cxx20
+)
+
+func excludes(in path: String, keeping sources: [String]) -> [String] {
+  var parents: Set<String> = [""]
+  for source in sources {
+    var components = source.split(separator: "/").dropLast()
+    while !components.isEmpty {
+      parents.insert(components.joined(separator: "/"))
+      components = components.dropLast()
+    }
+  }
+  let root = URL(fileURLWithPath: Context.packageDirectory).appendingPathComponent(path)
+  return parents.sorted().flatMap { parent in
+    let entries =
+      (try? FileManager.default.contentsOfDirectory(
+        atPath: root.appendingPathComponent(parent).path)) ?? []
+    return entries.sorted().compactMap { entry in
+      let entryPath = parent.isEmpty ? entry : "\(parent)/\(entry)"
+      return entry.hasPrefix(".") || sources.contains(entryPath) || parents.contains(entryPath)
+        ? nil : entryPath
+    }
+  }
+}

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# React Nitro Networking
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Fetch
+
+Call `Networking.fetch()` directly on the imported class:
+
+```ts
+import { Networking, Response } from 'react-nitro-networking'
+
+const response = await Networking.fetch('https://example.com')
+console.log(response instanceof Response) // true
+console.log(await response.text())
+```
+
+## WebSockets
+
+`new WebSocket(url)` starts connecting immediately. Each socket supports text and
+`ArrayBuffer` messages. Listeners are additive and return a subscription with an idempotent `remove()`.
+
+```ts
+import { WebSocket } from 'react-nitro-networking'
+
+const socket = new WebSocket('wss://example.com/socket')
+const messages = socket.addOnMessageReceivedListener((data) => {
+  console.log(data)
+})
+socket.addOnOpenedListener(() => console.log('Connected'))
+socket.addOnErrorListener((error) => console.error(error))
+socket.addOnClosedListener(() => console.log('Closed'))
+
+try {
+  // send() waits for the handshake if the connection is still opening.
+  await socket.send('Hello')
+} catch (error) {
+  console.error('Could not send:', error)
+}
+
+// When the connection is no longer needed:
+messages.remove()
+socket.close()
+```
+
+Binary messages use the same methods. Await sends to preserve their order:
+
+```ts
+await socket.send(new Uint8Array([0, 1, 255]).buffer)
+await socket.send(new ArrayBuffer(0))
+```
+
+Invalid URLs throw from the constructor. Handshake and transport failures notify error listeners,
+then closed listeners. Late opened listeners are notified if the socket is still open; late error
+and closed listeners receive the terminal outcome. `close()` is idempotent, releases listeners,
+and reports local shutdown without waiting for a peer acknowledgement. Reconnecting requires a new socket.
+
+Receiving starts immediately. Until the first message listener is registered, up to 64 messages
+or 1 MiB are buffered. Exceeding either limit closes the connection with an error. After the first
+subscription, messages without listeners are discarded. Closing also discards buffered messages.
+
+The current implementation supports Apple platforms through `URLSessionWebSocketTask`.

package/Sources/ReactNitroNetworking/HybridNetworking.swift

@@ -0,0 +1,17 @@
+internal import NitroModules
+internal import Foundation
+
+final class HybridNetworking: HybridNetworkingSpec {
+  static let session = URLSession(configuration: .default)
+
+  static func fetch(url: String) throws -> any Promise<any HybridResponseSpec> {
+    guard let url = URL(string: url) else {
+      throw RuntimeError("Invalid URL: \"\(url)\"")
+    }
+    return .async { [session] in
+      let delegate = NetworkingTaskDelegate()
+      let (bytes, response) = try await session.bytes(from: url, delegate: delegate)
+      return try HybridResponse(bytes: bytes, response: response, redirected: delegate.redirected)
+    }
+  }
+}

package/Sources/ReactNitroNetworking/HybridResponse.swift

@@ -0,0 +1,87 @@
+//
+//  HybridResponse.swift
+//  ReactNitroNetworking
+//
+//  Created by Marc Rousavy on 18.09.26.
+//
+
+internal import NitroModules
+internal import Foundation
+
+final class HybridResponse: HybridResponseSpec {
+  private let bytes: URLSession.AsyncBytes
+  private let response: URLResponse
+
+  var headers: [String: String] {
+    guard let response = response as? HTTPURLResponse else { return [:] }
+    var headers: [String: String] = [:]
+    for (name, value) in response.allHeaderFields {
+      guard let name = name as? String else { continue }
+      headers[name.lowercased()] = String(describing: value)
+    }
+    return headers
+  }
+  var status: Double { Double((response as? HTTPURLResponse)?.statusCode ?? 0) }
+  var ok: Bool { (200..<300).contains(status) }
+  var statusText: String { "" }
+  var url: String { response.url?.absoluteString ?? "" }
+  let redirected: Bool
+  var type: ResponseType { .basic }
+  private(set) var bodyUsed = false
+  
+  private lazy var materializedData = Task<Data, Error> { [bytes, response] in
+    var data = Data()
+
+    let expected = response.expectedContentLength
+    if expected > 0 {
+      // Cap initial reservation size at 8MB to not explode memory
+      let reservation = Int(min(expected, 8 * 1024 * 1024))
+      data.reserveCapacity(reservation)
+    }
+
+    for try await byte in bytes {
+      data.append(byte)
+    }
+    return data
+  }
+  private var data: Data {
+    get async throws {
+      bodyUsed = true
+      let data = try await materializedData.value
+      return data
+    }
+  }
+  
+  init(bytes: URLSession.AsyncBytes, response: URLResponse, redirected: Bool) throws {
+    self.bytes = bytes
+    self.response = response
+    self.redirected = redirected
+    try super.init()
+  }
+  
+  func arrayBuffer() -> any Promise<ArrayBuffer> {
+    return .async {
+      // TODO: Maybe we can figure out a way to avoid copying `Data` here and instead map the `ArrayBuffer` zero-copy?
+      let data = try await self.data
+      return try ArrayBuffer.copy(data: data)
+    }
+  }
+  
+  func json() -> any Promise<AnyJSON> {
+    return .async {
+      let data = try await self.data
+      // Like text(), skip a leading UTF-8 BOM.
+      let content = data.starts(with: [0xEF, 0xBB, 0xBF]) ? data.dropFirst(3) : data
+      return AnyJSON(data: content)
+    }
+  }
+  
+  func text() -> any Promise<String> {
+    return .async {
+      let data = try await self.data
+      // Fetch decodes UTF-8 with replacement and strips a leading UTF-8 BOM.
+      let content = data.starts(with: [0xEF, 0xBB, 0xBF]) ? data.dropFirst(3) : data
+      return String(decoding: content, as: UTF8.self)
+    }
+  }
+}

package/Sources/ReactNitroNetworking/HybridWebSocket.swift

@@ -0,0 +1,188 @@
+internal import Darwin
+internal import Foundation
+internal import NitroModules
+internal import NitroModulesCxx
+
+final class HybridWebSocket: HybridWebSocketSpec, @unchecked Sendable {
+  private let task: URLSessionWebSocketTask
+  private let delegate = WebSocketTaskDelegate()
+  private let queue = DispatchQueue(label: "com.margelo.nitro.websocket")
+  private let openedListeners: WebSocketListeners<Void>
+  private let messageListeners: WebSocketListeners<Variant_ArrayBuffer_String>
+  private let closedListeners: WebSocketListeners<Void>
+  private let errorListeners: WebSocketListeners<Error>
+
+  // Accessed only on queue.
+  private var isClosed = false
+  private var receiveTask: Task<Void, Never>?
+  private var hasMessageListener = false
+  private var pendingMessages: [URLSessionWebSocketTask.Message] = []
+  private var pendingByteCount = 0
+
+  convenience init(url: String) throws {
+    try self.init(session: HybridNetworking.session, url: try WebSocketURL.parse(url))
+  }
+
+  init(session: URLSession, url: URL) throws {
+    task = session.webSocketTask(with: url)
+    openedListeners = WebSocketListeners(queue: queue)
+    messageListeners = WebSocketListeners(queue: queue)
+    closedListeners = WebSocketListeners(queue: queue)
+    errorListeners = WebSocketListeners(queue: queue)
+    try super.init()
+    delegate.socket = self
+    task.delegate = delegate
+    task.resume()
+    queue.async { self.startReceiving() }
+  }
+
+  deinit {
+    receiveTask?.cancel()
+    task.cancel(with: .goingAway, reason: nil)
+  }
+
+  func send(data: Variant_ArrayBuffer_String) throws -> any Promise<Void> {
+    let message: URLSessionWebSocketTask.Message
+    switch data {
+    case .first(let buffer):
+      message = .data(buffer.toData(copyIfNeeded: true))
+    case .second(let text):
+      message = .string(text)
+    }
+    return .async { [task] in
+      try await task.send(message)
+    }
+  }
+
+  func close() {
+    queue.async { self.finish() }
+    // Cancel before returning so a subsequent send cannot race local shutdown.
+    // The queued finish runs before any delegate notification caused by cancellation.
+    task.cancel(with: .normalClosure, reason: nil)
+  }
+
+  func dispose() {
+    close()
+  }
+
+  func addOnOpenedListener(listener: any Callback<(), Void>) -> ListenerSubscription {
+    return openedListeners.add(listener)
+  }
+
+  func addOnMessageReceivedListener(
+    listener: any Callback<(Variant_ArrayBuffer_String), Void>
+  ) -> ListenerSubscription {
+    return messageListeners.add(
+      listener,
+      onAdded: { [weak self] in
+        guard let self, !self.hasMessageListener else { return }
+        self.hasMessageListener = true
+        for message in self.pendingMessages {
+          self.emitMessage(message)
+        }
+        self.pendingMessages.removeAll()
+        self.pendingByteCount = 0
+      })
+  }
+
+  func addOnClosedListener(listener: any Callback<(), Void>) -> ListenerSubscription {
+    return closedListeners.add(listener)
+  }
+
+  func addOnErrorListener(listener: any Callback<(Error), Void>) -> ListenerSubscription {
+    return errorListeners.add(listener)
+  }
+
+  func didOpen() {
+    queue.async {
+      guard !self.isClosed else { return }
+      self.openedListeners.finish(replaying: ())
+    }
+  }
+
+  func didComplete(error: Error?) {
+    queue.async {
+      // Once receiving, let the receive loop deliver preceding messages before closing.
+      if self.receiveTask == nil {
+        self.finish(error: error)
+      }
+    }
+  }
+
+  private func startReceiving() {
+    guard !isClosed, receiveTask == nil else { return }
+    receiveTask = Task { [weak self, task] in
+      do {
+        while !Task.isCancelled {
+          let message = try await task.receive()
+          self?.didReceive(message)
+        }
+      } catch {
+        // A peer close can also end receive() with an error. Its close code distinguishes
+        // a received close frame from a transport failure.
+        let failure = task.closeCode == .invalid || task.closeCode == .abnormalClosure ? error : nil
+        self?.queue.async { [weak self] in self?.finish(error: failure) }
+      }
+    }
+  }
+
+  private func didReceive(_ message: URLSessionWebSocketTask.Message) {
+    queue.async {
+      guard !self.isClosed else { return }
+      if !self.hasMessageListener {
+        let byteCount: Int
+        switch message {
+        case .string(let text): byteCount = text.utf8.count
+        case .data(let data): byteCount = data.count
+        @unknown default:
+          self.finish(error: RuntimeError("Unsupported WebSocket message type"))
+          return
+        }
+        guard self.pendingMessages.count < 64, self.pendingByteCount + byteCount <= 1_048_576 else {
+          self.finish(
+            error: RuntimeError(
+              "WebSocket receive buffer is full. Register a message listener before receiving more messages."
+            ))
+          return
+        }
+        self.pendingMessages.append(message)
+        self.pendingByteCount += byteCount
+      } else {
+        self.emitMessage(message)
+      }
+    }
+  }
+
+  private func emitMessage(_ message: URLSessionWebSocketTask.Message) {
+    guard !isClosed else { return }
+    do {
+      let value: Variant_ArrayBuffer_String
+      switch message {
+      case .string(let text):
+        value = .second(text)
+      case .data(let data):
+        let buffer = data.isEmpty ? ArrayBuffer.allocate(0) : try ArrayBuffer.copy(data: data)
+        value = .first(buffer)
+      @unknown default:
+        throw RuntimeError("Unsupported WebSocket message type")
+      }
+      messageListeners.emit(value)
+    } catch {
+      finish(error: error)
+    }
+  }
+
+  private func finish(error: Error? = nil) {
+    guard !isClosed else { return }
+    isClosed = true
+    receiveTask?.cancel()
+    receiveTask = nil
+    pendingMessages.removeAll()
+    pendingByteCount = 0
+    task.cancel(with: .normalClosure, reason: nil)
+    openedListeners.finish()
+    messageListeners.finish()
+    errorListeners.finish(replaying: error)
+    closedListeners.finish(replaying: ())
+  }
+}

package/Sources/ReactNitroNetworking/NetworkingTaskDelegate.swift

@@ -0,0 +1,16 @@
+internal import Foundation
+
+final class NetworkingTaskDelegate: NSObject, URLSessionTaskDelegate {
+  private(set) var redirected = false
+
+  func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    willPerformHTTPRedirection response: HTTPURLResponse,
+    newRequest request: URLRequest,
+    completionHandler: @escaping (URLRequest?) -> Void
+  ) {
+    redirected = true
+    completionHandler(request)
+  }
+}

package/Sources/ReactNitroNetworking/WebSocketListeners.swift

@@ -0,0 +1,49 @@
+internal import Foundation
+internal import NitroModules
+
+/// All registry state and emissions belong to the socket's serial queue.
+final class WebSocketListeners<Value> {
+  private let queue: DispatchQueue
+  private var listeners: [UUID: any Callback<(Value), Void>] = [:]
+  private var replay: Value?
+  private var isFinished = false
+
+  init(queue: DispatchQueue) {
+    self.queue = queue
+  }
+
+  func add(
+    _ listener: any Callback<(Value), Void>,
+    onAdded: @escaping () -> Void = {}
+  ) -> ListenerSubscription {
+    let id = UUID()
+    queue.async {
+      if let value = self.replay {
+        listener.callAndForget(value)
+      }
+      if !self.isFinished {
+        self.listeners[id] = listener
+        onAdded()
+      }
+    }
+    return ListenerSubscription(remove: .native { [weak self] in
+      guard let self else { return }
+      self.queue.async { self.listeners.removeValue(forKey: id) }
+    })
+  }
+
+  func emit(_ value: Value) {
+    for listener in listeners.values {
+      listener.callAndForget(value)
+    }
+  }
+
+  func finish(replaying value: Value? = nil) {
+    if let value {
+      emit(value)
+    }
+    replay = value
+    isFinished = true
+    listeners.removeAll()
+  }
+}

package/Sources/ReactNitroNetworking/WebSocketTaskDelegate.swift

@@ -0,0 +1,26 @@
+internal import Foundation
+
+final class WebSocketTaskDelegate: NSObject, URLSessionWebSocketDelegate {
+  weak var socket: HybridWebSocket?
+
+  func urlSession(
+    _ session: URLSession,
+    webSocketTask: URLSessionWebSocketTask,
+    didOpenWithProtocol protocol: String?
+  ) {
+    socket?.didOpen()
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    webSocketTask: URLSessionWebSocketTask,
+    didCloseWith closeCode: URLSessionWebSocketTask.CloseCode,
+    reason: Data?
+  ) {
+    socket?.didComplete(error: nil)
+  }
+
+  func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+    socket?.didComplete(error: error)
+  }
+}

package/Sources/ReactNitroNetworking/WebSocketURL.swift

@@ -0,0 +1,18 @@
+internal import Foundation
+internal import NitroModules
+
+enum WebSocketURL {
+  static func parse(_ value: String) throws -> URL {
+    guard let url = URL(string: value),
+      let scheme = url.scheme?.lowercased(),
+      scheme == "ws" || scheme == "wss",
+      let host = url.host, !host.isEmpty,
+      url.fragment == nil
+    else {
+      throw RuntimeError(
+        "Invalid WebSocket URL: \"\(value)\". Expected an absolute ws:// or wss:// URL without a fragment."
+      )
+    }
+    return url
+  }
+}

package/nitrogen/generated/.gitattributes

@@ -0,0 +1 @@
+** linguist-generated=true