@tokamakdev/platform-ios-simulator-x64 0.1.1-beta.83 → 0.1.1-beta.85

package/ios-simulator-x64/frameworks/TokamakRuntime.framework/Headers/TokamakRuntime.h

@@ -21,14 +21,27 @@ typedef struct {
   TokamakBytes private_key;
 } TokamakIdentity;
 
+typedef void (*TokamakPluginRequest)(void *context, uint64_t id,
+                                     const char *plugin, const char *method,
+                                     const char *arguments);
+
+typedef struct {
+  void *context;
+  TokamakPluginRequest call;
+  TokamakPluginRequest subscribe;
+  void (*unsubscribe)(void *context, uint64_t id);
+} TokamakPluginHandler;
+
 void *tokamak_runtime_start(const char *packaged_dir, const char *state_dir,
                             const char *storage_dir, const char *host,
-                            bool foreground, char *error, size_t error_len);
+                            bool foreground, TokamakPluginHandler plugins,
+                            char *error, size_t error_len);
 void *tokamak_runtime_start_development(const char *state_dir, const char *host,
                                      const char *endpoint,
                                      const char *session_token,
-                                     bool foreground, char *error,
-                                     size_t error_len);
+                                     bool foreground,
+                                     TokamakPluginHandler plugins,
+                                     char *error, size_t error_len);
 uint16_t tokamak_runtime_port(const void *runtime);
 uint16_t tokamak_runtime_restore_gateway(const void *runtime, char *error,
                                       size_t error_len);
@@ -36,6 +49,9 @@ void tokamak_runtime_stop(void *runtime);
 bool tokamak_runtime_emit(const void *runtime, const char *name,
                           const char *event, uint64_t timeout_ms,
                           TokamakBytes *reply, char *error, size_t error_len);
+bool tokamak_runtime_set_foreground(const void *runtime, bool foreground);
+bool tokamak_runtime_is_foreground(const void *runtime);
+void tokamak_runtime_reply(const void *runtime, uint64_t id, const char *result);
 
 int32_t tokamak_runtime_server_authority(const void *runtime, const char *host,
                                       TokamakBytes *authority);

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

@@ -17,9 +17,19 @@ private let lifecycleDeadline: TimeInterval = 10
 /// WebView, so plugins receive app events before a page loads and a Worker
 /// event can run while no page is loaded.
 final class TokamakApp {
-  private(set) var plugins: [any TokamakPlugin] = []
+  /// Every plugin, by ID.
+  private(set) var plugins: [String: any TokamakPlugin] = [:]
   private var runtime: Result<RuntimeHandle, Error>?
   private var waiting: [(Result<RuntimeHandle, Error>) -> Void] = []
+  /// The Worker's calls and subscriptions on the plugins.
+  private lazy var workerRequests = TokamakPluginRequests<UInt64>(plugins: plugins) {
+    [unowned self] id, result in
+    whenStarted { started in
+      if case .success(let runtime) = started {
+        runtime.reply(id, result: result)
+      }
+    }
+  }
   /// Delivers `resume` and `suspend` one at a time, in order.
   private let lifecycle = DispatchQueue(label: "tokamak.lifecycle")
   #if os(iOS)
@@ -29,19 +39,60 @@ final class TokamakApp {
 
   /// Creates the plugins. Call it before launch finishes.
   init() {
-    plugins = tokamakPlugins(app: self)
+    for plugin in tokamakPlugins(app: self) {
+      precondition(plugins.updateValue(plugin, forKey: plugin.id) == nil, "Duplicate plugin ID")
+    }
   }
 
   /// Starts the runtime in the background, which delivers `start` with
   /// `foreground`. Call it once, on the main thread.
   func start(foreground: Bool) {
     dispatchPrecondition(condition: .onQueue(.main))
+    let plugins = workerPlugins
     DispatchQueue.global(qos: .userInitiated).async {
-      let result = Result { try RuntimeHandle(foreground: foreground) }
+      let result = Result { try RuntimeHandle(foreground: foreground, plugins: plugins) }
       DispatchQueue.main.async { self.started(result) }
     }
   }
 
+  /// The plugins as the runtime calls them, on its own threads. The app
+  /// outlives the runtime, which holds it unretained.
+  private var workerPlugins: TokamakPluginHandler {
+    TokamakPluginHandler(
+      context: Unmanaged.passUnretained(self).toOpaque(),
+      call: { context, id, plugin, method, arguments in
+        TokamakApp.receive(context, id, subscribe: false, plugin, method, arguments)
+      },
+      subscribe: { context, id, plugin, method, arguments in
+        TokamakApp.receive(context, id, subscribe: true, plugin, method, arguments)
+      },
+      unsubscribe: { context, id in
+        let app = Unmanaged<TokamakApp>.fromOpaque(context!).takeUnretainedValue()
+        DispatchQueue.main.async { app.workerRequests.cancel(id) }
+      }
+    )
+  }
+
+  /// Runs a call or subscription the Worker made through `context`'s app.
+  private static func receive(
+    _ context: UnsafeMutableRawPointer?,
+    _ id: UInt64,
+    subscribe: Bool,
+    _ plugin: UnsafePointer<CChar>?,
+    _ method: UnsafePointer<CChar>?,
+    _ arguments: UnsafePointer<CChar>?
+  ) {
+    let app = Unmanaged<TokamakApp>.fromOpaque(context!).takeUnretainedValue()
+    let (plugin, method) = (String(cString: plugin!), String(cString: method!))
+    let arguments =
+      (try? JSONSerialization.jsonObject(
+        with: Data(String(cString: arguments!).utf8), options: .fragmentsAllowed)) ?? NSNull()
+    DispatchQueue.main.async {
+      app.workerRequests.run(
+        id, subscribe: subscribe, plugin: plugin, method: method, arguments: arguments)
+    }
+  }
+
   /// Calls `completion` on the main thread once the runtime has started or
   /// failed to start.
   func whenStarted(_ completion: @escaping (Result<RuntimeHandle, Error>) -> Void) {
@@ -81,8 +132,9 @@ final class TokamakApp {
     }
   }
 
-  /// Delivers `resume` when the app moves into the foreground and `suspend`
-  /// when it moves out. Call it on the main thread.
+  /// Records the app moving into or out of the foreground once the runtime
+  /// has started, and delivers `resume` or `suspend` when that changed its
+  /// stage. Call it on the main thread.
   func moved(toForeground foreground: Bool) {
     let name = foreground ? "resume" : "suspend"
     #if os(iOS)
@@ -103,11 +155,17 @@ final class TokamakApp {
       let finish = {}
       let timeout = lifecycleDeadline
     #endif
-    emit(name, event: [String: Any](), timeout: timeout, on: lifecycle) { result in
-      if case .failure(let error) = result {
-        print("tokamak \(name) failed: \(error)")
+    whenStarted { started in
+      guard case .success(let runtime) = started, runtime.setForeground(foreground) else {
+        finish()
+        return
+      }
+      self.emit(name, event: [String: Any](), timeout: timeout, on: self.lifecycle) { result in
+        if case .failure(let error) = result {
+          print("tokamak \(name) failed: \(error)")
+        }
+        finish()
       }
-      finish()
     }
   }
 
@@ -129,19 +187,27 @@ final class TokamakApp {
     }
 
     /// Whether a scene is in the foreground.
-    var isInForeground: Bool {
+    var hasForegroundScene: Bool {
       foregroundScenes > 0
     }
+
+    /// Whether the app is in the foreground, as the runtime records it, or
+    /// until the runtime has started, whether a scene is in the foreground.
+    /// Read it on the main thread.
+    var isInForeground: Bool {
+      guard case .success(let runtime) = runtime else { return hasForegroundScene }
+      return runtime.isForeground
+    }
   #endif
 
   func didRegisterForRemoteNotifications(deviceToken: Data) {
-    for plugin in plugins {
+    for plugin in plugins.values {
       plugin.didRegisterForRemoteNotifications(deviceToken: deviceToken)
     }
   }
 
   func didFailToRegisterForRemoteNotifications(error: Error) {
-    for plugin in plugins {
+    for plugin in plugins.values {
       plugin.didFailToRegisterForRemoteNotifications(error: error)
     }
   }
@@ -154,7 +220,7 @@ final class TokamakApp {
   ) {
     let group = DispatchGroup()
     var results: [TokamakBackgroundResult] = []
-    for plugin in plugins {
+    for plugin in plugins.values {
       group.enter()
       plugin.didReceiveRemoteNotification(userInfo) { result in
         DispatchQueue.main.async {
@@ -223,8 +289,9 @@ final class RuntimeHandle {
   let appHost: String
   private var handle: UnsafeMutableRawPointer?
 
-  /// Starts the runtime, which delivers `start` with `foreground`.
-  init(foreground: Bool) throws {
+  /// Starts the runtime, which delivers `start` with `foreground`, and whose
+  /// Worker calls `plugins`.
+  init(foreground: Bool, plugins: TokamakPluginHandler) throws {
     guard
       let appHost = Bundle.main.object(forInfoDictionaryKey: "TokamakHost") as? String,
       !appHost.isEmpty
@@ -250,6 +317,7 @@ final class RuntimeHandle {
                   endpoint,
                   sessionToken,
                   foreground,
+                  plugins,
                   error.baseAddress,
                   error.count
                 )
@@ -275,6 +343,7 @@ final class RuntimeHandle {
                   storagePath,
                   appHost,
                   foreground,
+                  plugins,
                   error.baseAddress,
                   error.count
                 )
@@ -347,6 +416,25 @@ final class RuntimeHandle {
     return value is NSNull ? nil : value
   }
 
+  /// Records whether the app is in the foreground, which the Worker's
+  /// `getLifecycleStage()` reports from then on, and returns whether that
+  /// changed.
+  func setForeground(_ foreground: Bool) -> Bool {
+    tokamak_runtime_set_foreground(handle, foreground)
+  }
+
+  /// Whether the app is in the foreground, as last recorded.
+  var isForeground: Bool {
+    tokamak_runtime_is_foreground(handle)
+  }
+
+  /// Passes a plugin's `result`, JSON-serialisable, to the Worker's call or
+  /// subscription `id`.
+  func reply(_ id: UInt64, result: [String: Any]) {
+    guard let json = try? JSONSerialization.data(withJSONObject: result) else { return }
+    String(decoding: json, as: UTF8.self).withCString { tokamak_runtime_reply(handle, id, $0) }
+  }
+
   func serverAuthority(host: String) -> AuthenticationMaterial<Data> {
     var bytes = TokamakBytes()
     let decision = host.withCString {

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

@@ -8,6 +8,12 @@ struct TokamakPluginError: Error {
   static func notSupported(_ message: String) -> Self {
     Self(name: "NotSupportedError", message: message)
   }
+
+  /// UI was needed while the app cannot show it.
+  static let needsUI = Self(
+    name: "NeedsUIError",
+    message: "The app cannot show UI while it is in the background"
+  )
 }
 
 typealias TokamakPluginReply = (Result<Any?, TokamakPluginError>) -> Void
@@ -22,6 +28,16 @@ final class TokamakHost {
     self.plugin = plugin
   }
 
+  /// 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
+  /// UI.
+  func requireUI() throws(TokamakPluginError) {
+    #if os(iOS)
+      guard app.isInForeground else { throw .needsUI }
+    #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
@@ -37,7 +53,8 @@ final class TokamakHost {
   }
 }
 
-/// A native plugin, created once per process when the app launches.
+/// A native plugin, created once per process when the app launches. The page
+/// and the Worker call it on the main thread.
 protocol TokamakPlugin: AnyObject {
   var id: String { get }
 
@@ -49,11 +66,13 @@ protocol TokamakPlugin: AnyObject {
     reply: @escaping TokamakPluginReply
   )
 
+  /// Replies with each value until the returned function is called. Throws
+  /// when the subscription cannot start, which ends it.
   func subscribe(
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  ) -> (() -> Void)
+  ) throws(TokamakPluginError) -> (() -> Void)
 
   func didRegisterForRemoteNotifications(deviceToken: Data)
 
@@ -80,9 +99,8 @@ extension TokamakPlugin {
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  ) -> (() -> Void) {
-    reply(.failure(.notSupported("\(id).\(method) is not supported")))
-    return {}
+  ) throws(TokamakPluginError) -> (() -> Void) {
+    throw .notSupported("\(id).\(method) is not supported")
   }
 
   func didRegisterForRemoteNotifications(deviceToken: Data) {}
@@ -97,6 +115,82 @@ 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] = [:]
+
+  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)
+    }
+  }
+
+  /// Ends the request `key` with `error`.
+  func fail(_ key: Key, _ error: TokamakPluginError) {
+    send(key, Self.result(.failure(error), done: true))
+  }
+
+  /// Ends the subscription `key`.
+  func cancel(_ key: Key) {
+    cancellations.removeValue(forKey: key)?()
+  }
+
+  /// Ends every subscription.
+  func cancelAll() {
+    let cancelAll = Array(cancellations.values)
+    cancellations.removeAll()
+    for cancel in cancelAll {
+      cancel()
+    }
+  }
+
+  /// `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
+      }
+      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
@@ -105,17 +199,15 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
 
   private let host: String
   private let plugins: [String: any TokamakPlugin]
-  private var cancellations: [RequestKey: () -> Void] = [:]
+  private lazy var requests = TokamakPluginRequests<RequestKey>(plugins: plugins) {
+    [weak self] key, result in
+    self?.deliver(key: key, result: result)
+  }
   weak var webView: WKWebView?
 
-  init(host: String, plugins: [any TokamakPlugin]) {
+  init(host: String, plugins: [String: any TokamakPlugin]) {
     self.host = host
-    var pluginsById: [String: any TokamakPlugin] = [:]
-    for plugin in plugins {
-      precondition(pluginsById[plugin.id] == nil, "Duplicate plugin ID")
-      pluginsById[plugin.id] = plugin
-    }
-    self.plugins = pluginsById
+    self.plugins = plugins
   }
 
   func install(in controller: WKUserContentController) {
@@ -130,11 +222,7 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
   }
 
   func close() {
-    let cancelAll = Array(cancellations.values)
-    cancellations.removeAll()
-    for cancel in cancelAll {
-      cancel()
-    }
+    requests.cancelAll()
   }
 
   func userContentController(
@@ -159,66 +247,27 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
     }
     guard let id = request["id"] as? Int else { return }
     let key = RequestKey(session: session, id: id)
-    if type == "cancel" {
-      cancellations.removeValue(forKey: key)?()
-      return
-    }
-    dispatch(type: type, key: key, request: request)
-  }
-
-  private func dispatch(type: String, key: RequestKey, request: [String: Any]) {
-    guard
-      let pluginId = request["plugin"] as? String,
-      let method = request["method"] as? String,
-      let plugin = plugins[pluginId]
-    else {
-      send(key: key, result: .failure(.notSupported("Plugin is not supported")), done: true)
-      return
-    }
-    let arguments = request["arguments"] ?? NSNull()
-    let reply: TokamakPluginReply = { [weak self] result in
-      self?.send(key: key, result: result, done: type == "call")
-    }
     switch type {
-    case "call":
-      plugin.call(method: method, arguments: arguments, reply: reply)
-    case "subscribe":
-      let cancellation = plugin.subscribe(
-        method: method,
-        arguments: arguments,
-        reply: reply
+    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()
       )
-      cancellations[key] = cancellation
     default:
-      send(
-        key: key, result: .failure(.notSupported("Plugin operation is not supported")), done: true)
+      requests.fail(key, .notSupported("Plugin operation is not supported"))
     }
   }
 
-  /// Plugins reply from any thread; delivery happens on the main thread.
-  private func send(key: RequestKey, result: Result<Any?, TokamakPluginError>, done: Bool) {
-    DispatchQueue.main.async { [weak self] in
-      self?.deliver(key: key, result: result, done: done)
-    }
-  }
-
-  private func deliver(key: RequestKey, result: Result<Any?, TokamakPluginError>, done: Bool) {
-    if done {
-      cancellations.removeValue(forKey: key)?()
-    }
-    var response: [String: Any] = [
-      "session": key.session,
-      "id": key.id,
-      "done": done,
-    ]
-    switch result {
-    case .success(let value):
-      response["value"] = value ?? NSNull()
-    case .failure(let error):
-      response["error"] = ["name": error.name, "message": error.message]
-    }
+  private func deliver(key: RequestKey, result: [String: Any]) {
+    var response = result
+    response["session"] = key.session
+    response["id"] = key.id
     guard
-      JSONSerialization.isValidJSONObject(response),
       let data = try? JSONSerialization.data(withJSONObject: response),
       let json = String(data: data, encoding: .utf8),
       webView?.url?.isAppOrigin(host) == true

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

@@ -431,7 +431,7 @@ private final class TokamakController {
       didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
     ) -> Bool {
       DispatchQueue.main.async {
-        self.app.start(foreground: self.app.isInForeground)
+        self.app.start(foreground: self.app.hasForegroundScene)
       }
       return true
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/platform-ios-simulator-x64",
-  "version": "0.1.1-beta.83",
+  "version": "0.1.1-beta.85",
   "description": "The tokamak platform pack for ios-simulator-x64",
   "repository": {
     "type": "git",