@use-voltra/ios-client 2.1.1 → 2.3.0

package/ios/shared/WidgetServer/WidgetServerSettingsStore.swift

@@ -0,0 +1,170 @@
+import Foundation
+import Security
+
+/// The only way to write server-update settings, and the storage behind the three runtime layers.
+///
+/// Records live in the same shared Keychain the widget credentials have always used, so nothing
+/// migrates: the deprecated `setWidgetServerCredentials` keeps writing the accounts it always did,
+/// and this store adds its own accounts alongside them. The Keychain is also the only store both
+/// the app and the widget extension can reach without depending on an App Group being configured.
+///
+/// Callers do not read through this class. They read through `WidgetServerSettingsResolver`, which
+/// is what keeps the layer order and the merge rule in one place.
+public enum WidgetServerSettingsStore {
+  private static let service = "voltra-widget-server-credentials"
+  private static let globalAccount = "server_update_global"
+  private static let widgetAccountPrefix = "server_update_widget_"
+  private static let revisionAccount = "server_update_revision"
+
+  // MARK: - Writes
+
+  /// Replaces the global layer, or one widget's layer when `scope` is given.
+  @discardableResult
+  public static func set(_ settings: WidgetServerUpdateSettings, scope: WidgetScope?) -> Bool {
+    guard let data = WidgetServerSettingsCodec.encode(settings) else { return false }
+
+    let saved = write(data, account: account(for: scope))
+    bumpRevision()
+
+    return saved
+  }
+
+  /// Empties the global layer, or one widget's layer when `scope` is given.
+  public static func clear(scope: WidgetScope?) {
+    delete(account: account(for: scope))
+    bumpRevision()
+  }
+
+  /// Bumps the revision without changing a layer. The credentials layer writes through the
+  /// deprecated credential API, which does not go through `set`, so it calls this to make sure an
+  /// in-flight fetch built with the old token does not commit.
+  public static func bumpRevision() {
+    let next = revision() &+ 1
+    write(Data("\(next)".utf8), account: revisionAccount)
+  }
+
+  public static func revision() -> Int {
+    guard let data = read(account: revisionAccount),
+          let text = String(data: data, encoding: .utf8),
+          let value = Int(text)
+    else {
+      return 0
+    }
+
+    return value
+  }
+
+  // MARK: - Reads
+
+  static func settings(scope: WidgetScope?) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsCodec.decode(read(account: account(for: scope)))
+  }
+
+  private static func account(for scope: WidgetScope?) -> String {
+    guard let scope else { return globalAccount }
+
+    return "\(widgetAccountPrefix)\(scope.storageKey)"
+  }
+
+  // MARK: - Keychain
+
+  private static func baseQuery(account: String) -> [String: Any] {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: account,
+    ]
+
+    if let group = VoltraConfig.keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    return query
+  }
+
+  @discardableResult
+  private static func write(_ data: Data, account: String) -> Bool {
+    delete(account: account)
+
+    var query = baseQuery(account: account)
+    query[kSecValueData as String] = data
+    query[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+
+    let status = SecItemAdd(query as CFDictionary, nil)
+
+    if status != errSecSuccess {
+      VoltraLogger.keychain.error("Failed to save widget server settings: \(status, privacy: .public)")
+    }
+
+    return status == errSecSuccess
+  }
+
+  private static func read(account: String) -> Data? {
+    var query = baseQuery(account: account)
+    query[kSecReturnData as String] = true
+    query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+    var item: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+    guard status == errSecSuccess, let data = item as? Data else {
+      if status != errSecItemNotFound {
+        VoltraLogger.keychain.error("Failed to read widget server settings: \(status, privacy: .public)")
+      }
+      return nil
+    }
+
+    return data
+  }
+
+  private static func delete(account: String) {
+    SecItemDelete(baseQuery(account: account) as CFDictionary)
+  }
+}
+
+/// Settings the app set for every server-driven widget.
+struct GlobalWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "global"
+
+  func settings(for _: WidgetScope) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: nil)
+  }
+
+  /// Raw contents of this layer, for reading back what was set — no scope to resolve against.
+  func raw() -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: nil)
+  }
+}
+
+/// Settings the app set for one widget. Highest layer until instance scopes arrive.
+struct WidgetWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "widget"
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings? {
+    WidgetServerSettingsStore.settings(scope: scope)
+  }
+}
+
+/// The deprecated `setWidgetServerCredentials` API, expressed as a settings layer.
+///
+/// It reads the same token and header records it always has, which is why nothing migrates. It
+/// sits below the global layer so an app that has moved to
+/// `setWidgetServerUpdate({ headers: { Authorization: ... } })` overrides whatever an older call
+/// left behind, rather than the other way round.
+struct CredentialsWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "credentials"
+
+  func settings(for _: WidgetScope) -> WidgetServerUpdateSettings? {
+    var headers: [String: String] = [:]
+
+    if let token = VoltraKeychainHelper.readToken(), !token.isEmpty {
+      headers["Authorization"] = "Bearer \(token)"
+    }
+
+    if let custom = VoltraKeychainHelper.readHeaders() {
+      headers.merge(custom) { _, fromCustom in fromCustom }
+    }
+
+    return headers.isEmpty ? nil : WidgetServerUpdateSettings(headers: headers)
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsValidator.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// Call-time rules for `setWidgetServerUpdate`. Rejecting here rather than at fetch time means the
+/// app learns about a bad setting from the promise it just awaited, instead of from a widget that
+/// quietly stops updating hours later.
+public enum WidgetServerSettingsValidator {
+  /// Hosts reachable over plain http, so a debug build can talk to a dev server.
+  static let localHttpHosts: Set<String> = ["localhost", "127.0.0.1", "::1", "10.0.2.2", "10.0.3.2"]
+
+  /// - Parameter isDebugBuild: whether plain http to a local dev host is allowed. Release builds
+  ///   have App Transport Security blocking it anyway, so allowing it there would only defer the
+  ///   failure.
+  /// - Returns: an error message, or nil when the settings are usable.
+  public static func validate(_ settings: WidgetServerUpdateSettings, isDebugBuild: Bool) -> String? {
+    if let url = settings.url, let error = validateUrl(url, isDebugBuild: isDebugBuild) {
+      return error
+    }
+
+    if let interval = settings.intervalMinutes, interval <= 0 {
+      return "intervalMinutes must be a positive number of minutes"
+    }
+
+    if let method = settings.method,
+       !WidgetServerUpdateDefaults.supportedMethods.contains(method.uppercased())
+    {
+      let supported = WidgetServerUpdateDefaults.supportedMethods.sorted().joined(separator: ", ")
+      return "method '\(method)' is not supported. Use one of \(supported)"
+    }
+
+    for key in settings.query?.keys ?? [String: String]().keys
+      where WidgetServerUpdateDefaults.reservedQueryKeys.contains(key)
+    {
+      return "query key '\(key)' is reserved by Voltra and is sent on every request"
+    }
+
+    if let encoded = WidgetServerSettingsCodec.encode(settings),
+       encoded.count > WidgetServerUpdateDefaults.maxLayerBytes
+    {
+      return "settings are larger than \(WidgetServerUpdateDefaults.maxLayerBytes) bytes once serialized"
+    }
+
+    return nil
+  }
+
+  private static func validateUrl(_ url: String, isDebugBuild: Bool) -> String? {
+    if url.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      return "url must not be empty"
+    }
+
+    guard let components = URLComponents(string: url),
+          let scheme = components.scheme?.lowercased(),
+          let host = components.host,
+          !host.isEmpty
+    else {
+      return "url '\(url)' must be an absolute http(s) URL"
+    }
+
+    if scheme == "https" {
+      return nil
+    }
+
+    if scheme != "http" {
+      return "url '\(url)' must be an absolute http(s) URL"
+    }
+
+    if isDebugBuild, localHttpHosts.contains(host) {
+      return nil
+    }
+
+    let hosts = localHttpHosts.sorted().joined(separator: ", ")
+    return "url '\(url)' must use https. Plain http is allowed only in a debug build, and only for \(hosts)."
+  }
+}

package/ios/shared/WidgetServer/WidgetServerUpdateSettings.swift

@@ -0,0 +1,123 @@
+import Foundation
+
+/// Server-update settings as one layer holds them: every field is optional, and an unset field
+/// means "this layer has no opinion, ask the layer below".
+///
+/// `body` is kept as the raw JSON text the app supplied rather than a parsed tree, because Voltra
+/// never inspects it — it only forwards it as the request body.
+public struct WidgetServerUpdateSettings: Equatable, Sendable {
+  public var url: String?
+  public var intervalMinutes: Int?
+  public var enabled: Bool?
+  public var method: String?
+  public var query: [String: String]?
+  public var headers: [String: String]?
+  public var body: String?
+
+  public init(
+    url: String? = nil,
+    intervalMinutes: Int? = nil,
+    enabled: Bool? = nil,
+    method: String? = nil,
+    query: [String: String]? = nil,
+    headers: [String: String]? = nil,
+    body: String? = nil
+  ) {
+    self.url = url
+    self.intervalMinutes = intervalMinutes
+    self.enabled = enabled
+    self.method = method
+    self.query = query
+    self.headers = headers
+    self.body = body
+  }
+
+  public var isEmpty: Bool {
+    url == nil && intervalMinutes == nil && enabled == nil && method == nil
+      && query == nil && headers == nil && body == nil
+  }
+
+  public static let empty = WidgetServerUpdateSettings()
+}
+
+/// The flattened settings a fetch actually runs on. Every field is decided: `intervalMinutes` has
+/// the floor and ceiling applied, `enabled` and `method` have their defaults filled in, and `query`
+/// and `headers` are the per-key merge of every layer.
+///
+/// `url` is the one field that can still be absent, and it means the widget is server-driven but
+/// has nowhere to fetch from yet — the app is expected to supply one with `setWidgetServerUpdate`.
+public struct ResolvedWidgetServerSettings: Equatable, Sendable {
+  public let url: String?
+  public let intervalMinutes: Int
+  public let enabled: Bool
+  public let method: String
+  public let query: [String: String]
+  public let headers: [String: String]
+  public let body: String?
+
+  public init(
+    url: String?,
+    intervalMinutes: Int,
+    enabled: Bool,
+    method: String,
+    query: [String: String],
+    headers: [String: String],
+    body: String?
+  ) {
+    self.url = url
+    self.intervalMinutes = intervalMinutes
+    self.enabled = enabled
+    self.method = method
+    self.query = query
+    self.headers = headers
+    self.body = body
+  }
+
+  /// True when this widget has both a URL to fetch and permission to do it.
+  public var shouldFetch: Bool {
+    guard enabled, let url, !url.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+      return false
+    }
+
+    return true
+  }
+}
+
+public enum WidgetServerUpdateDefaults {
+  /// WidgetKit stretches a timeline asking for entries much closer together than five minutes, and
+  /// the reload budget is shared across every widget in the app, so a smaller number would only
+  /// misreport what the widget actually does. Matches Android's WorkManager floor.
+  public static let minIntervalMinutes = 15
+
+  /// A day. Past this the widget is effectively not server-driven, and `Cache-Control: max-age`
+  /// from a misconfigured server should not be able to park a widget for a week.
+  public static let maxIntervalMinutes = 24 * 60
+
+  public static let defaultIntervalMinutes = minIntervalMinutes
+
+  public static let defaultMethod = "GET"
+
+  /// Methods either platform's HTTP stack can send.
+  public static let supportedMethods: Set<String> = ["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+  /// Methods that cannot carry a body. A body set alongside one of these is dropped.
+  public static let bodylessMethods: Set<String> = ["GET", "HEAD"]
+
+  /// Query keys Voltra puts on every request. An app that set one of these would silently shadow
+  /// what the server relies on, so `setWidgetServerUpdate` rejects them.
+  public static let reservedQueryKeys: Set<String> = [
+    "widgetId", "platform", "family", "theme", "locale", "instance", "configuration",
+  ]
+
+  /// Serialized size cap for one layer, so a runaway `body` cannot fill the settings store.
+  public static let maxLayerBytes = 16 * 1024
+
+  /// Response bodies larger than this are refused. The widget extension has a 30 MB ceiling for
+  /// the whole render, and a widget needing a quarter of a megabyte of props will not fit on a
+  /// home screen either.
+  public static let maxBodyBytes = 256 * 1024
+
+  public static func clampIntervalMinutes(_ intervalMinutes: Int) -> Int {
+    min(max(intervalMinutes, minIntervalMinutes), maxIntervalMinutes)
+  }
+}

package/ios/shared/WidgetServer/WidgetServerUpdateSettingsJson.swift

@@ -0,0 +1,115 @@
+import Foundation
+
+/// Reads the settings object an app passes to `setWidgetServerUpdate`.
+///
+/// Separate from `WidgetServerSettingsCodec`, which is the versioned storage format: what the app
+/// sends and what Voltra persists are allowed to diverge, and conflating them would make either one
+/// hard to change. The one real difference today is `body`, which arrives as arbitrary JSON and is
+/// kept as text because Voltra only forwards it.
+public enum WidgetServerUpdateSettingsJson {
+  public enum Result: Equatable {
+    case parsed(WidgetServerUpdateSettings)
+    case invalid(reason: String)
+  }
+
+  public static func parse(_ json: String) -> Result {
+    guard let object = try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any] else {
+      return .invalid(reason: "settings must be a JSON object")
+    }
+
+    guard let query = stringMap(object, "query") else {
+      return .invalid(reason: "query must be an object of strings")
+    }
+
+    guard let headers = stringMap(object, "headers") else {
+      return .invalid(reason: "headers must be an object of strings")
+    }
+
+    var body: String?
+
+    if let rawBody = object["body"], !(rawBody is NSNull) {
+      guard let text = jsonText(rawBody) else {
+        return .invalid(reason: "body must be a JSON value")
+      }
+
+      body = text
+    }
+
+    return .parsed(
+      WidgetServerUpdateSettings(
+        url: object["url"] as? String,
+        intervalMinutes: object["intervalMinutes"] as? Int,
+        enabled: object["enabled"] as? Bool,
+        method: (object["method"] as? String)?.uppercased(),
+        query: object["query"] == nil ? nil : query,
+        headers: object["headers"] == nil ? nil : headers,
+        body: body
+      )
+    )
+  }
+
+  /// The other direction of `parse`: serializes settings back to the same JSON shape, for
+  /// `getWidgetServerUpdate` to hand across the bridge. No envelope — that is
+  /// `WidgetServerSettingsCodec`'s job for storage, not this one's for a single read.
+  public static func stringify(_ settings: WidgetServerUpdateSettings) -> String? {
+    var object: [String: Any] = [:]
+
+    if let url = settings.url {
+      object["url"] = url
+    }
+    if let intervalMinutes = settings.intervalMinutes {
+      object["intervalMinutes"] = intervalMinutes
+    }
+    if let enabled = settings.enabled {
+      object["enabled"] = enabled
+    }
+    if let method = settings.method {
+      object["method"] = method
+    }
+    if let query = settings.query {
+      object["query"] = query
+    }
+    if let headers = settings.headers {
+      object["headers"] = headers
+    }
+
+    if let body = settings.body {
+      guard let bodyData = body.data(using: .utf8),
+            let bodyValue = try? JSONSerialization.jsonObject(with: bodyData, options: [.fragmentsAllowed])
+      else {
+        return nil
+      }
+
+      object["body"] = bodyValue
+    }
+
+    guard let data = try? JSONSerialization.data(withJSONObject: object) else { return nil }
+
+    return String(data: data, encoding: .utf8)
+  }
+
+  /// Re-serializes a parsed value back to JSON text. A string body has to keep its quotes: without
+  /// them the request would carry something that is not JSON at all.
+  private static func jsonText(_ value: Any) -> String? {
+    if JSONSerialization.isValidJSONObject(value) {
+      return (try? JSONSerialization.data(withJSONObject: value)).flatMap { String(data: $0, encoding: .utf8) }
+    }
+
+    // A top-level scalar is not a valid JSON *object*, so it is wrapped, encoded and unwrapped.
+    guard let wrapped = try? JSONSerialization.data(withJSONObject: ["v": value]),
+          let text = String(data: wrapped, encoding: .utf8),
+          let start = text.firstIndex(of: ":")
+    else {
+      return nil
+    }
+
+    return String(text[text.index(after: start) ..< text.index(before: text.endIndex)])
+  }
+
+  /// Returns an empty map when the key is absent, and nil when it is present but not usable.
+  private static func stringMap(_ object: [String: Any], _ key: String) -> [String: String]? {
+    guard let raw = object[key], !(raw is NSNull) else { return [:] }
+
+    return raw as? [String: String]
+  }
+}

package/ios/shared/dynamic-live-activity/DynamicLiveActivityPropsCodec.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+enum DynamicLiveActivityPropsCodec {
+  static func encode(_ props: [String: VoltraDynamicLiveActivityJSONValue]) -> String? {
+    guard
+      let data = try? JSONEncoder().encode(props),
+      let json = String(data: data, encoding: .utf8)
+    else {
+      return nil
+    }
+    return json
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityBundleSource.swift

@@ -0,0 +1,156 @@
+import Foundation
+
+enum VoltraDynamicLiveActivityBundleSource {
+  private static let metroTimeout: TimeInterval = 1
+
+  enum LoadError: LocalizedError {
+    case metroHTTP(Int)
+    case metroTimeout
+    case nonUTF8
+    case bakedBundleNotFound(definitionId: String)
+    case cacheUnavailable
+
+    var errorDescription: String? {
+      switch self {
+      case let .metroHTTP(status):
+        return "Metro HTTP \(status) while loading a Dynamic Live Activity bundle"
+      case .metroTimeout:
+        return "Metro timed out while loading a Dynamic Live Activity bundle"
+      case .nonUTF8:
+        return "Dynamic Live Activity bundle was not UTF-8 text"
+      case let .bakedBundleNotFound(definitionId):
+        return "Production Dynamic Live Activity bundle missing for definitionId=\(definitionId)"
+      case .cacheUnavailable:
+        return "Dynamic Live Activity debug cache is unavailable"
+      }
+    }
+  }
+
+  static func load(definitionId: String) throws -> String {
+    #if DEBUG
+      if let cached = try? loadFromDebugCache(definitionId: definitionId) {
+        return cached
+      }
+      return try loadFromMetroBounded(definitionId: definitionId)
+    #else
+      return try loadFromBakedAsset(definitionId: definitionId)
+    #endif
+  }
+
+  /// App-side preflight and Fast Refresh use an asynchronous fetch, then publish
+  /// the source into the App Group cache consumed by the extension process.
+  static func loadForApp(definitionId: String) async throws -> String {
+    #if DEBUG
+      let request = try metroRequest(definitionId: definitionId)
+      let (data, response) = try await URLSession.shared.data(for: request)
+      let source = try validateMetroResponse(data: data, response: response)
+      try saveToDebugCache(source, definitionId: definitionId)
+      return source
+    #else
+      return try loadFromBakedAsset(definitionId: definitionId)
+    #endif
+  }
+
+  /// A cheap token that changes whenever the bytes behind `load` change, used to
+  /// invalidate the render cache. In DEBUG it is the debug-cache file's
+  /// modification time, which the app process rewrites on every hot reload; the
+  /// extension reads only the file's metadata, never decoding the whole bundle.
+  /// In release the baked asset never changes at runtime, so the token is
+  /// constant and the render cache stays valid for the process lifetime.
+  static func revision(definitionId: String) -> String {
+    #if DEBUG
+      guard
+        let url = try? debugCacheURL(definitionId: definitionId),
+        let modified = (try? FileManager.default.attributesOfItem(atPath: url.path))?[.modificationDate] as? Date
+      else {
+        return ""
+      }
+      return String(modified.timeIntervalSince1970)
+    #else
+      return "baked"
+    #endif
+  }
+
+  private static func metroRequest(definitionId: String) throws -> URLRequest {
+    let base = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    guard let url = URL(string: "\(base)/voltra/live-activities/\(definitionId).bundle?platform=ios&dev=true") else {
+      throw LoadError.metroHTTP(-1)
+    }
+    var request = URLRequest(url: url)
+    request.timeoutInterval = metroTimeout
+    return request
+  }
+
+  /// WidgetKit rendering is synchronous. On a cold debug process we permit one
+  /// short, bounded bootstrap request; all subsequent renders read the App Group
+  /// cache and never wait on the network.
+  private static func loadFromMetroBounded(definitionId: String) throws -> String {
+    let request = try metroRequest(definitionId: definitionId)
+    let semaphore = DispatchSemaphore(value: 0)
+    var result: Result<(Data, URLResponse), Error>?
+    let configuration = URLSessionConfiguration.ephemeral
+    configuration.timeoutIntervalForRequest = metroTimeout
+    configuration.timeoutIntervalForResource = metroTimeout
+    let session = URLSession(configuration: configuration)
+    let task = session.dataTask(with: request) { data, response, error in
+      if let error {
+        result = .failure(error)
+      } else if let data, let response {
+        result = .success((data, response))
+      } else {
+        result = .failure(LoadError.metroHTTP(-1))
+      }
+      semaphore.signal()
+    }
+    task.resume()
+    guard semaphore.wait(timeout: .now() + metroTimeout) == .success else {
+      task.cancel()
+      session.invalidateAndCancel()
+      throw LoadError.metroTimeout
+    }
+    session.finishTasksAndInvalidate()
+    guard let result else { throw LoadError.metroTimeout }
+    let (data, response) = try result.get()
+    let source = try validateMetroResponse(data: data, response: response)
+    try saveToDebugCache(source, definitionId: definitionId)
+    return source
+  }
+
+  private static func validateMetroResponse(data: Data, response: URLResponse) throws -> String {
+    if let httpResponse = response as? HTTPURLResponse, !(200 ... 299).contains(httpResponse.statusCode) {
+      throw LoadError.metroHTTP(httpResponse.statusCode)
+    }
+    guard let source = String(data: data, encoding: .utf8) else {
+      throw LoadError.nonUTF8
+    }
+    return source
+  }
+
+  private static func loadFromDebugCache(definitionId: String) throws -> String {
+    try String(contentsOf: debugCacheURL(definitionId: definitionId), encoding: .utf8)
+  }
+
+  private static func saveToDebugCache(_ source: String, definitionId: String) throws {
+    try Data(source.utf8).write(to: debugCacheURL(definitionId: definitionId), options: .atomic)
+  }
+
+  private static func debugCacheURL(definitionId: String) throws -> URL {
+    guard
+      let group = VoltraConfig.groupIdentifier(),
+      let container = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: group)
+    else {
+      throw LoadError.cacheUnavailable
+    }
+    return container.appendingPathComponent("voltra-live-activity-debug-\(definitionId).bundle")
+  }
+
+  private static func loadFromBakedAsset(definitionId: String) throws -> String {
+    guard
+      let url = Bundle.main.url(forResource: "voltra-live-activity-\(definitionId)", withExtension: "bundle"),
+      let source = try? String(contentsOf: url, encoding: .utf8)
+    else {
+      throw LoadError.bakedBundleNotFound(definitionId: definitionId)
+    }
+    return source
+  }
+}