@tokamakdev/platform-ios-simulator-x64 0.1.1-beta.107 → 0.1.1-beta.114

package/ios-simulator-x64/native-shell/TokamakPlugins.swift

@@ -1,14 +1,25 @@
 import Foundation
 import WebKit
 
+#if os(iOS)
+  import UIKit
+#else
+  import AppKit
+#endif
+
 struct TokamakPluginError: Error {
   let name: String
   let message: String
+  /// JSON details the Worker receives as the error's `cause`.
+  var cause: Any? = nil
 
   static func notSupported(_ message: String) -> Self {
     Self(name: "NotSupportedError", message: message)
   }
 
+  /// A native screen was needed while the app has no window.
+  static let noWindow = Self(name: "InvalidStateError", message: "The app has no window")
+
   /// UI was needed while the app cannot show it.
   static let needsUI = Self(
     name: "NeedsUIError",
@@ -17,6 +28,68 @@ struct TokamakPluginError: Error {
 }
 
 typealias TokamakPluginReply = (Result<Any?, TokamakPluginError>) -> Void
+typealias TokamakPluginBytesReply = (TokamakPluginResult) -> Void
+
+struct TokamakPluginResult {
+  let payload: Data
+  let failed: Bool
+  let done: Bool
+
+  init(payload: Data, failed: Bool, done: Bool) {
+    self.payload = payload
+    self.failed = failed
+    self.done = done
+  }
+
+  init(_ result: Result<Data, TokamakPluginError>, done: Bool) {
+    self.done = done
+    switch result {
+    case .success(let payload):
+      self.payload = payload
+      failed = false
+    case .failure(let error):
+      var failure: [String: Any] = ["name": error.name, "message": error.message]
+      failure["cause"] = error.cause
+      payload = try! JSONSerialization.data(withJSONObject: failure)
+      failed = true
+    }
+  }
+}
+
+/// `value` as a payload: `Data` as it is, and any other value as JSON.
+func encodePluginValue(_ value: Any?) -> Result<Data, TokamakPluginError> {
+  if let data = value as? Data { return .success(data) }
+  let value = value ?? NSNull()
+  // JSONSerialization raises, rather than throws, for values it cannot encode.
+  guard JSONSerialization.isValidJSONObject([value]),
+    let json = try? JSONSerialization.data(withJSONObject: value, options: .fragmentsAllowed)
+  else {
+    return .failure(.init(name: "DataCloneError", message: "The value cannot be encoded as JSON"))
+  }
+  return .success(json)
+}
+
+/// Decodes `payload` as JSON for `call`, and encodes its reply.
+private func callJSON(
+  _ payload: Data,
+  _ reply: @escaping TokamakPluginBytesReply,
+  _ call: (Any, @escaping TokamakPluginReply) -> (() -> Void)?
+) -> (() -> Void)? {
+  do {
+    return call(try decodePluginValue(payload)) {
+      reply(TokamakPluginResult($0.flatMap(encodePluginValue), done: true))
+    }
+  } catch {
+    reply(TokamakPluginResult(.failure(error), done: true))
+    return nil
+  }
+}
+
+func decodePluginValue(_ payload: Data) throws(TokamakPluginError) -> Any {
+  do { return try JSONSerialization.jsonObject(with: payload, options: .fragmentsAllowed) } catch {
+    throw .init(name: "DataCloneError", message: error.localizedDescription)
+  }
+}
 
 /// The app as one plugin sees it.
 final class TokamakHost {
@@ -28,6 +101,11 @@ final class TokamakHost {
     self.plugin = plugin
   }
 
+  var webView: WKWebView? { app.webView }
+
+  /// The native objects plugins share with each other by ID.
+  var resources: TokamakResources { app.resources }
+
   /// Throws `NeedsUIError` unless the app can show UI now: on iOS, while it
   /// is in the foreground. A hidden or minimised macOS app still shows system
   /// prompts. Call it on the main thread, where the plugin decides to show
@@ -38,18 +116,61 @@ final class TokamakHost {
     #endif
   }
 
+  #if os(iOS)
+    /// The view controller to present a native screen from: the top of the
+    /// app window's presentation stack. Throws `NeedsUIError` unless the app
+    /// can show UI now. Call it on the main thread.
+    func presenter() throws(TokamakPluginError) -> UIViewController {
+      try requireUI()
+      guard var top = webView?.window?.rootViewController else { throw .noWindow }
+      while let presented = top.presentedViewController { top = presented }
+      return top
+    }
+  #else
+    /// The app window, to present a native screen over. Call it on the main
+    /// thread.
+    func presenter() throws(TokamakPluginError) -> NSWindow {
+      guard let window = webView?.window else { throw .noWindow }
+      return window
+    }
+  #endif
+
   /// Delivers the plugin's event `name`, which the Worker's listeners
-  /// receive as `<plugin>.<name>`, with `event`, JSON-serialisable, and calls
-  /// `completion` on the main thread with their reply, parsed from JSON, or
-  /// nil. Fails unless they return within `timeout`, which includes runtime
-  /// startup. Call it on the main thread.
+  /// receive as `<plugin>.<name>`, with its encoded `payload`, and calls
+  /// `completion` on the main thread with their encoded reply, which is empty
+  /// when none replied. Fails unless they return within `timeout`, which
+  /// includes runtime startup. Call it on the main thread.
+  func emitBytes(
+    _ name: String,
+    payload: Data,
+    timeout: TimeInterval,
+    completion: @escaping (Result<Data, Error>) -> Void
+  ) {
+    app.emit("\(plugin).\(name)", payload: payload, timeout: timeout, completion: completion)
+  }
+
+  /// `emitBytes` with `event` encoded as JSON, calling `completion` with the
+  /// reply parsed from JSON, or nil when none replied.
   func emit(
     _ name: String,
     event: Any,
     timeout: TimeInterval,
     completion: @escaping (Result<Any?, Error>) -> Void
   ) {
-    app.emit("\(plugin).\(name)", event: event, timeout: timeout, completion: completion)
+    let payload: Data
+    switch encodePluginValue(event) {
+    case .success(let encoded): payload = encoded
+    case .failure(let error): return completion(.failure(error))
+    }
+    emitBytes(name, payload: payload, timeout: timeout) { result in
+      completion(
+        result.flatMap { reply in
+          Result { () throws(TokamakPluginError) -> Any? in
+            let value = reply.isEmpty ? NSNull() : try decodePluginValue(reply)
+            return value is NSNull ? nil : value
+          }.mapError { $0 }
+        })
+    }
   }
 
   /// Fetches what the app serves at `path`, as its WebView would load it: a
@@ -65,18 +186,40 @@ final class TokamakHost {
   }
 }
 
-/// A native plugin, created once per process when the app launches. The page
-/// and the Worker call it on the main thread.
+/// A native plugin, created once per process.
 protocol TokamakPlugin: AnyObject {
   var id: String { get }
 
   init(host: TokamakHost)
 
+  /// Serial executor for this operation and its cancellation.
+  func executor(for method: String) -> DispatchQueue
+
+  func callBytes(method: String, payload: Data, reply: @escaping TokamakPluginBytesReply) -> (
+    () -> Void
+  )?
+  func callBytes(
+    method: String, payload: Data, body: TokamakPluginBody,
+    reply: @escaping TokamakPluginBytesReply
+  ) -> (() -> Void)?
+  func subscribeBytes(method: String, payload: Data, reply: @escaping TokamakPluginBytesReply)
+    throws(TokamakPluginError) -> (() -> Void)
+
+  /// Returns cancellation for pending work when the platform supports it.
   func call(
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  )
+  ) -> (() -> Void)?
+
+  /// A call whose `body` of bytes the Worker streams, which the plugin reads
+  /// one chunk at a time.
+  func call(
+    method: String,
+    arguments: Any,
+    body: TokamakPluginBody,
+    reply: @escaping TokamakPluginReply
+  ) -> (() -> Void)?
 
   /// Replies with each value until the returned function is called. Throws
   /// when the subscription cannot start, which ends it.
@@ -99,12 +242,46 @@ protocol TokamakPlugin: AnyObject {
 }
 
 extension TokamakPlugin {
+  func executor(for method: String) -> DispatchQueue { .main }
+
+  func callBytes(method: String, payload: Data, reply: @escaping TokamakPluginBytesReply) -> (
+    () -> Void
+  )? {
+    callJSON(payload, reply) { call(method: method, arguments: $0, reply: $1) }
+  }
+
+  func callBytes(
+    method: String, payload: Data, body: TokamakPluginBody,
+    reply: @escaping TokamakPluginBytesReply
+  ) -> (() -> Void)? {
+    callJSON(payload, reply) { call(method: method, arguments: $0, body: body, reply: $1) }
+  }
+
+  func subscribeBytes(method: String, payload: Data, reply: @escaping TokamakPluginBytesReply)
+    throws(TokamakPluginError) -> (() -> Void)
+  {
+    try subscribe(method: method, arguments: decodePluginValue(payload)) {
+      reply(TokamakPluginResult($0.flatMap(encodePluginValue), done: false))
+    }
+  }
+
   func call(
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  ) {
+  ) -> (() -> Void)? {
     reply(.failure(.notSupported("\(id).\(method) is not supported")))
+    return nil
+  }
+
+  func call(
+    method: String,
+    arguments: Any,
+    body: TokamakPluginBody,
+    reply: @escaping TokamakPluginReply
+  ) -> (() -> Void)? {
+    reply(.failure(.notSupported("\(id).\(method) does not take a body")))
+    return nil
   }
 
   func subscribe(
@@ -127,183 +304,157 @@ extension TokamakPlugin {
   }
 }
 
-/// Runs one caller's calls and subscriptions, the page's or the Worker's, on
-/// the app's plugins, keyed by `Key`. `send` receives each result on the main
-/// thread, as the JSON object the page's native transport receives without its
-/// session and ID. Use it on the main thread.
-final class TokamakPluginRequests<Key: Hashable> {
-  private let plugins: [String: any TokamakPlugin]
-  private let send: (Key, [String: Any]) -> Void
-  private var cancellations: [Key: () -> Void] = [:]
+/// The bytes the Worker streams to a call, which the plugin reads one chunk
+/// at a time.
+final class TokamakPluginBody {
+  typealias Chunk = (Result<Data?, TokamakPluginError>) -> Void
 
-  init(plugins: [String: any TokamakPlugin], send: @escaping (Key, [String: Any]) -> Void) {
-    self.plugins = plugins
-    self.send = send
-  }
-
-  /// Calls `method` of `plugin`, or subscribes to it when `subscribe`.
-  func run(_ key: Key, subscribe: Bool, plugin: String, method: String, arguments: Any) {
-    guard let target = plugins[plugin], !method.isEmpty else {
-      fail(key, .notSupported("Plugin is not supported"))
-      return
-    }
-    // Plugins reply from any thread.
-    let reply: TokamakPluginReply = { [weak self] result in
-      DispatchQueue.main.async {
-        self?.send(key, Self.result(result, done: !subscribe))
-      }
-    }
-    guard subscribe else {
-      target.call(method: method, arguments: arguments, reply: reply)
-      return
-    }
-    do {
-      cancellations[key] = try target.subscribe(method: method, arguments: arguments, reply: reply)
-    } catch {
-      fail(key, error)
-    }
-  }
+  private let queue: DispatchQueue
+  private let pull: () -> Void
+  private let lock = NSLock()
+  private var reading: Chunk?
 
-  /// Ends the request `key` with `error`.
-  func fail(_ key: Key, _ error: TokamakPluginError) {
-    send(key, Self.result(.failure(error), done: true))
+  init(queue: DispatchQueue, pull: @escaping () -> Void) {
+    self.queue = queue
+    self.pull = pull
   }
 
-  /// Ends the subscription `key`.
-  func cancel(_ key: Key) {
-    cancellations.removeValue(forKey: key)?()
+  /// Reads the next chunk: its bytes, nil after the last, or the Worker's
+  /// error. `handler` runs on the call's executor; read again only after it
+  /// has.
+  func read(_ handler: @escaping Chunk) {
+    lock.withLock { reading = handler }
+    pull()
   }
 
-  /// Ends every subscription.
-  func cancelAll() {
-    let cancelAll = Array(cancellations.values)
-    cancellations.removeAll()
-    for cancel in cancelAll {
-      cancel()
+  /// Answers the pending read with the chunk the Worker sent.
+  fileprivate func receive(_ chunk: TokamakPluginResult) {
+    let handler = lock.withLock {
+      defer { reading = nil }
+      return reading
     }
-  }
-
-  /// `result` as JSON, or the failure to make it JSON.
-  private static func result(
-    _ result: Result<Any?, TokamakPluginError>,
-    done: Bool
-  ) -> [String: Any] {
-    switch result {
-    case .success(let value):
-      let json: [String: Any] = ["value": value ?? NSNull(), "done": done]
-      if JSONSerialization.isValidJSONObject(json) {
-        return json
+    guard let handler else { return }
+    queue.async {
+      if chunk.failed {
+        let error = try? JSONSerialization.jsonObject(with: chunk.payload) as? [String: String]
+        handler(.failure(.init(name: error?["name"] ?? "Error", message: error?["message"] ?? "")))
+      } else {
+        handler(.success(chunk.done ? nil : chunk.payload))
       }
-      let error = TokamakPluginError(
-        name: "OperationError", message: "The plugin's value is not JSON")
-      return Self.result(.failure(error), done: done)
-    case .failure(let error):
-      return ["error": ["name": error.name, "message": error.message], "done": done]
     }
   }
 }
 
-final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
-  private struct RequestKey: Hashable {
-    let session: String
-    let id: Int
+/// What the Worker asked a plugin for.
+enum TokamakPluginRequest {
+  case call, callWithBody, subscribe
+}
+
+/// Runs the Worker's requests on the executor each plugin chooses, and passes
+/// replies straight to the runtime.
+final class TokamakPluginRequests<Key: Hashable> {
+  /// A pending call or subscription. Only its serial executor touches
+  /// `cancellation`, so a cancellation runs after the operation started.
+  private final class Request {
+    let queue: DispatchQueue
+    var body: TokamakPluginBody?
+    var cancellation: (() -> Void)?
+    init(queue: DispatchQueue) { self.queue = queue }
   }
 
-  private let host: String
   private let plugins: [String: any TokamakPlugin]
-  private lazy var requests = TokamakPluginRequests<RequestKey>(plugins: plugins) {
-    [weak self] key, result in
-    self?.deliver(key: key, result: result)
+  private let send: (Key, TokamakPluginResult) -> Void
+  private let pull: (Key) -> Void
+  private let lock = NSLock()
+  private var pending: [Key: Request] = [:]
+
+  /// Routes requests to `plugins`, sending their results with `send` and
+  /// asking the Worker for the next chunk of a call's body with `pull`.
+  init(
+    plugins: [String: any TokamakPlugin],
+    send: @escaping (Key, TokamakPluginResult) -> Void,
+    pull: @escaping (Key) -> Void = { _ in }
+  ) {
+    self.plugins = plugins
+    self.send = send
+    self.pull = pull
   }
-  weak var webView: WKWebView?
 
-  init(host: String, plugins: [String: any TokamakPlugin]) {
-    self.host = host
-    self.plugins = plugins
+  func run(
+    _ key: Key, _ kind: TokamakPluginRequest, plugin: String, method: String, payload: Data
+  ) {
+    guard let target = plugins[plugin], !method.isEmpty else {
+      send(key, TokamakPluginResult(.failure(.notSupported("Plugin is not supported")), done: true))
+      return
+    }
+    let request = Request(queue: target.executor(for: method))
+    if kind == .callWithBody {
+      request.body = TokamakPluginBody(queue: request.queue) { [weak self] in self?.pull(key) }
+    }
+    lock.withLock { pending[key] = request }
+    let subscribe = kind == .subscribe
+    // A weak request lets a completed call release its cancellation.
+    let reply: TokamakPluginBytesReply = { [weak self, weak request] result in
+      guard let self, let request else { return }
+      let last = !subscribe || result.done
+      guard last ? remove(key, request) : isPending(key, request) else { return }
+      send(key, result)
+      if subscribe && result.done { cancel(request) }
+    }
+    request.queue.async { [self] in
+      guard isPending(key, request) else { return }
+      do throws(TokamakPluginError) {
+        if subscribe {
+          request.cancellation = try target.subscribeBytes(
+            method: method, payload: payload, reply: reply)
+        } else if let body = request.body {
+          request.cancellation = target.callBytes(
+            method: method, payload: payload, body: body, reply: reply)
+        } else {
+          request.cancellation = target.callBytes(method: method, payload: payload, reply: reply)
+        }
+      } catch {
+        if remove(key, request) { send(key, TokamakPluginResult(.failure(error), done: true)) }
+      }
+    }
   }
 
-  func install(in controller: WKUserContentController) {
-    controller.add(self, name: "tokamak")
-    controller.addUserScript(
-      WKUserScript(
-        source: Self.bootstrap(host: host),
-        injectionTime: .atDocumentStart,
-        forMainFrameOnly: true
-      )
-    )
+  /// Answers the pending read of the call `key`'s body with the chunk the
+  /// Worker sent.
+  func chunk(_ key: Key, _ chunk: TokamakPluginResult) {
+    lock.withLock { pending[key]?.body }?.receive(chunk)
   }
 
-  func close() {
-    requests.cancelAll()
+  func cancel(_ key: Key) {
+    if let request = lock.withLock({ pending.removeValue(forKey: key) }) { cancel(request) }
   }
 
-  func userContentController(
-    _ userContentController: WKUserContentController,
-    didReceive message: WKScriptMessage
-  ) {
-    guard
-      message.frameInfo.isMainFrame,
-      message.frameInfo.securityOrigin.isAppOrigin(host),
-      let encoded = message.body as? String,
-      let data = encoded.data(using: .utf8),
-      let request = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-      let type = request["type"] as? String,
-      let session = request["session"] as? String
-    else {
-      return
+  func cancelAll() {
+    let requests = lock.withLock {
+      defer { pending.removeAll() }
+      return Array(pending.values)
     }
+    for request in requests { cancel(request) }
+  }
 
-    if type == "reset" {
-      close()
-      return
-    }
-    guard let id = request["id"] as? Int else { return }
-    let key = RequestKey(session: session, id: id)
-    switch type {
-    case "cancel":
-      requests.cancel(key)
-    case "call", "subscribe":
-      requests.run(
-        key,
-        subscribe: type == "subscribe",
-        plugin: request["plugin"] as? String ?? "",
-        method: request["method"] as? String ?? "",
-        arguments: request["arguments"] ?? NSNull()
-      )
-    default:
-      requests.fail(key, .notSupported("Plugin operation is not supported"))
+  /// Runs the operation's cancellation on its executor.
+  private func cancel(_ request: Request) {
+    request.queue.async {
+      request.cancellation?()
+      request.cancellation = nil
     }
   }
 
-  private func deliver(key: RequestKey, result: [String: Any]) {
-    var response = result
-    response["session"] = key.session
-    response["id"] = key.id
-    guard
-      let data = try? JSONSerialization.data(withJSONObject: response),
-      let json = String(data: data, encoding: .utf8),
-      webView?.url?.isAppOrigin(host) == true
-    else {
-      return
-    }
-    webView?.callAsyncJavaScript(
-      "globalThis.__tokamakNative?.onmessage?.({ data })",
-      arguments: ["data": json],
-      in: nil,
-      in: .page
-    )
+  private func isPending(_ key: Key, _ request: Request) -> Bool {
+    lock.withLock { pending[key] === request }
   }
 
-  private static func bootstrap(host: String) -> String {
-    """
-    if (globalThis.location.origin === "https://\(host)") {
-      globalThis.__tokamakNative = {
-        onmessage: null,
-        postMessage(message) {
-          globalThis.webkit.messageHandlers.tokamak.postMessage(message);
-        }
-      };
+  /// Removes `request`, returning whether it was pending.
+  private func remove(_ key: Key, _ request: Request) -> Bool {
+    lock.withLock {
+      guard pending[key] === request else { return false }
+      pending[key] = nil
+      return true
     }
-    """
   }
 }

package/ios-simulator-x64/native-shell/TokamakResources.swift

@@ -0,0 +1,74 @@
+import Foundation
+
+/// Native objects that plugins share by ID. Each belongs to a scope and is
+/// kept until it is released or its scope ends.
+final class TokamakResources {
+  private let lock = NSLock()
+  private var objects: [String: (object: Any, scope: String)] = [:]
+  private var scopes: [String: Set<String>] = [:]
+
+  /// Starts a scope and returns its ID.
+  func open() -> String {
+    let scope = UUID().uuidString
+    lock.withLock { scopes[scope] = [] }
+    return scope
+  }
+
+  /// Keeps `object` in `scope` and returns its ID. An ended scope keeps
+  /// nothing, so the ID finds no object.
+  func retain(_ object: Any, in scope: String) -> String {
+    let id = UUID().uuidString
+    lock.withLock {
+      guard scopes[scope]?.insert(id) != nil else { return }
+      objects[id] = (object, scope)
+    }
+    return id
+  }
+
+  /// Keeps `object` in a scope of its own, replies with its ID, and returns
+  /// the release to return from `subscribe`.
+  func retain(_ object: Any, reply: TokamakPluginReply) -> () -> Void {
+    let scope = open()
+    reply(.success(retain(object, in: scope)))
+    return { [self] in end(scope) }
+  }
+
+  /// Releases the object retained as `id`, if it is still kept.
+  func release(_ id: Any) {
+    let removed = lock.withLock { () -> Any? in
+      guard let id = id as? String, let entry = objects.removeValue(forKey: id) else { return nil }
+      scopes[entry.scope]?.remove(id)
+      return entry.object
+    }
+    drop(removed)
+  }
+
+  /// Releases every object `scope` keeps, and keeps nothing in it later.
+  func end(_ scope: String) {
+    let removed = lock.withLock { () -> [Any] in
+      (scopes.removeValue(forKey: scope) ?? []).compactMap {
+        objects.removeValue(forKey: $0)?.object
+      }
+    }
+    drop(removed)
+  }
+
+  /// The object retained as `id`.
+  func get<Object>(_ id: Any, as type: Object.Type) throws(TokamakPluginError) -> Object {
+    guard let id = id as? String, let object = lock.withLock({ objects[id]?.object }) else {
+      throw TokamakPluginError(name: "InvalidStateError", message: "The native reference is closed")
+    }
+    guard let typed = object as? Object else {
+      throw TokamakPluginError(
+        name: "TypeError", message: "The native reference is not \(Object.self)")
+    }
+    return typed
+  }
+
+  /// Lets go of released objects on the main thread, where UI and run loop
+  /// objects expect to be deallocated.
+  private func drop(_ objects: Any?) {
+    guard let objects else { return }
+    DispatchQueue.main.async { withExtendedLifetime(objects) {} }
+  }
+}