@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/shared/VoltraWidgetServerFetcher.swift

@@ -1,8 +1,12 @@
 import Foundation
-import UIKit
 
-/// Handles fetching widget content from a remote Voltra SSR server.
-/// Used by the TimelineProvider to pull server-driven widget updates.
+/// Fetches a Voltra payload from the server for a payload-driven widget.
+///
+/// Since ADR 0002 the request itself is built by `shared/WidgetServer`, the same code the Dynamic
+/// engine uses. With no runtime settings set, that produces the request this fetcher always sent,
+/// plus `locale` and a conditional `If-None-Match`; with settings set, this widget gains the
+/// runtime URL, method, headers, query and body too. What the timeline does with the response is
+/// unchanged.
 public enum VoltraWidgetServerFetcher {
   /// Errors that can occur during server fetch
   public enum FetchError: Error, LocalizedError {
@@ -12,6 +16,8 @@ public enum VoltraWidgetServerFetcher {
     case httpError(statusCode: Int)
     case invalidResponse
     case emptyResponse
+    /// `304`: what is already stored is still current, so there is nothing new to render.
+    case notModified
 
     public var errorDescription: String? {
       switch self {
@@ -27,142 +33,81 @@ public enum VoltraWidgetServerFetcher {
         return "Invalid response from server"
       case .emptyResponse:
         return "Empty response from server"
+      case .notModified:
+        return "Server content is unchanged"
       }
     }
   }
 
-  /// Read the server update URL for a widget from Info.plist / UserDefaults config.
+  /// The URL this widget will fetch from, after runtime overrides. Callers use it to decide
+  /// whether a widget is server-driven at all before starting a timeline.
   public static func serverUrl(for widgetId: String) -> String? {
-    // Check Info.plist first (set at build time by config plugin)
-    if let urls = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerUrls) as? [String: String],
-       let url = urls[widgetId]
-    {
-      return url
-    }
-
-    // Fallback to UserDefaults (can be set at runtime)
-    if let group = VoltraConfig.groupIdentifier(),
-       let defaults = UserDefaults(suiteName: group)
-    {
-      return defaults.string(forKey: VoltraStorageKeys.widgetServerUrl(widgetId))
-    }
-
-    return nil
+    VoltraWidgetServer.resolver.resolve(.of(widgetId)).url
   }
 
-  /// Read the update interval (in minutes) for a widget.
+  /// The resolved interval, in minutes. Runtime settings win over app.json.
   public static func updateInterval(for widgetId: String) -> Int {
-    if let intervals = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerIntervals) as? [String: Int],
-       let interval = intervals[widgetId]
-    {
-      return interval
-    }
-    return 60 // default: 1 hour
+    VoltraWidgetServer.resolver.resolve(.of(widgetId)).intervalMinutes
   }
 
+  /// Whether the widget draws a refresh button. Build-time only: the button is generated UI
+  /// structure, so unlike the URL and the interval it cannot be changed at runtime.
   public static func isRefreshEnabled(for widgetId: String) -> Bool {
-    if let refreshDict = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerRefresh) as? [String: Bool],
-       let enabled = refreshDict[widgetId]
-    {
-      return enabled
-    }
-    return false
-  }
-
-  private static func currentColorScheme() -> String {
-    if #available(iOSApplicationExtension 13.0, *) {
-      switch UITraitCollection.current.userInterfaceStyle {
-      case .dark:
-        return "dark"
-      case .light:
-        return "light"
-      default:
-        return "light"
-      }
-    }
-    return "light"
+    VoltraWidgetServer.isRefreshEnabled(for: widgetId)
   }
 
   /// Fetch widget content from the remote Voltra SSR server.
   ///
-  /// The request includes:
-  /// - `widgetId` query parameter
-  /// - `family` query parameter (e.g., "systemSmall")
-  /// - `platform` query parameter (`ios`)
-  /// - `theme` query parameter (`light` or `dark`)
-  /// - `Authorization: Bearer <token>` header (if credentials stored in Keychain)
-  /// - Any custom headers stored in Keychain
+  /// The request carries `widgetId`, `family`, `platform`, `theme` and `locale` as query
+  /// parameters, `Accept: application/json`, a Voltra user agent, whatever headers the app has set
+  /// — including `Authorization` from the deprecated credential API — and `If-None-Match` when a
+  /// stored ETag belongs to the URL being fetched.
   ///
   /// Returns the raw JSON data from the server, ready to be parsed by VoltraNode.
   public static func fetchWidgetContent(
     widgetId: String,
     family: String
   ) async throws -> Data {
-    guard let baseUrl = serverUrl(for: widgetId) else {
-      throw FetchError.noServerUrl
-    }
-
-    // Build URL with query parameters
-    guard var components = URLComponents(string: baseUrl) else {
-      throw FetchError.invalidUrl(baseUrl)
-    }
-
-    let theme = currentColorScheme()
+    let scope = WidgetScope.of(widgetId)
+    let settings = VoltraWidgetServer.resolver.resolve(scope)
 
-    var queryItems = components.queryItems ?? []
-    queryItems.append(URLQueryItem(name: "widgetId", value: widgetId))
-    queryItems.append(URLQueryItem(name: "family", value: family))
-    queryItems.append(URLQueryItem(name: "platform", value: "ios"))
-    queryItems.append(URLQueryItem(name: "theme", value: theme))
-    components.queryItems = queryItems
-
-    guard let url = components.url else {
-      throw FetchError.invalidUrl(baseUrl)
+    guard let url = settings.url else {
+      throw FetchError.noServerUrl
     }
 
-    var request = URLRequest(url: url)
-    request.httpMethod = "GET"
-    request.timeoutInterval = 15 // Widgets have limited execution time
-
-    // Add auth token from Keychain if available
-    if let token = VoltraKeychainHelper.readToken() {
-      request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+    // No If-None-Match: a payload widget sends the request it always sent, plus locale. The last
+    // successful response is kept only for this extension process, so a 304 could arrive with
+    // nothing to fall back on and leave the widget on its initial state.
+    guard let request = WidgetServerRequestBuilder.build(
+      scope: scope,
+      settings: settings,
+      context: VoltraWidgetAppearance.requestContext(family: family)
+    ) else {
+      throw FetchError.invalidUrl(url)
     }
 
-    // Add custom headers from Keychain if available
-    if let headers = VoltraKeychainHelper.readHeaders() {
-      for (key, value) in headers {
-        request.setValue(value, forHTTPHeaderField: key)
+    switch await WidgetServerFetcher.fetch(request) {
+    case let .success(body, _, _, _):
+      guard !body.isEmpty else {
+        throw FetchError.emptyResponse
       }
-    }
 
-    // Add Voltra-specific headers
-    let systemVersion = await MainActor.run {
-      UIDevice.current.systemVersion
-    }
-    request.setValue("application/json", forHTTPHeaderField: "Accept")
-    request.setValue("VoltraWidget/1.0 (iOS/\(systemVersion))", forHTTPHeaderField: "User-Agent")
-
-    do {
-      let (data, response) = try await URLSession.shared.data(for: request)
+      return body
 
-      guard let httpResponse = response as? HTTPURLResponse else {
-        throw FetchError.invalidResponse
-      }
+    case .notModified:
+      // Only reachable if the server answers 304 unprompted; nothing was requested conditionally.
+      throw FetchError.notModified
 
-      guard (200 ... 299).contains(httpResponse.statusCode) else {
-        throw FetchError.httpError(statusCode: httpResponse.statusCode)
-      }
+    case let .tooLarge(statusCode):
+      throw FetchError.httpError(statusCode: statusCode)
 
-      guard !data.isEmpty else {
-        throw FetchError.emptyResponse
-      }
+    case let .httpFailure(statusCode, _):
+      throw FetchError.httpError(statusCode: statusCode)
 
-      return data
-    } catch let error as FetchError {
-      throw error
-    } catch {
-      throw FetchError.networkError(error)
+    case let .networkFailure(message):
+      throw FetchError.networkError(NSError(domain: "VoltraWidgetServerFetcher", code: -1, userInfo: [
+        NSLocalizedDescriptionKey: message,
+      ]))
     }
   }
 }

package/ios/shared/WidgetServer/VoltraWidgetAppearance.swift

@@ -0,0 +1,17 @@
+import UIKit
+
+/// The appearance a widget is being drawn in, as the request contract reports it.
+///
+/// Split out from the rest of `WidgetServer` because it is the one piece that needs UIKit, and
+/// keeping it here lets everything else — the resolver, the store, the request builder, the
+/// fetcher — be compiled and tested on its own.
+public enum VoltraWidgetAppearance {
+  public static func currentTheme() -> String {
+    UITraitCollection.current.userInterfaceStyle == .dark ? "dark" : "light"
+  }
+
+  /// The device state a request carries, for callers that are already on a UIKit-capable target.
+  public static func requestContext(family: String? = nil) -> WidgetServerRequestContext {
+    VoltraWidgetServer.requestContext(theme: currentTheme(), family: family)
+  }
+}

package/ios/shared/WidgetServer/VoltraWidgetServer.swift

@@ -0,0 +1,138 @@
+import Foundation
+
+/// Build-time server-update defaults, read from the Info.plist keys the config plugin and the CLI
+/// write.
+///
+/// `Voltra_WidgetServerIntervals` carries an entry for every server-driven widget, so its keys are
+/// the set of widget ids this app may fetch for. `Voltra_WidgetServerUrls` carries only the ones
+/// app.json gave a URL; the rest expect one at runtime from `setWidgetServerUpdate`.
+struct ConfigWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "config"
+
+  private let urls: [String: String]
+  private let intervals: [String: Int]
+
+  init(bundle: Bundle = .main) {
+    urls = bundle.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerUrls) as? [String: String] ?? [:]
+    intervals = bundle.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerIntervals) as? [String: Int] ?? [:]
+  }
+
+  init(urls: [String: String], intervals: [String: Int]) {
+    self.urls = urls
+    self.intervals = intervals
+  }
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings? {
+    guard let interval = intervals[scope.widgetId] else { return nil }
+
+    return WidgetServerUpdateSettings(url: urls[scope.widgetId], intervalMinutes: interval)
+  }
+
+  func isServerDriven(_ scope: WidgetScope) -> Bool {
+    intervals[scope.widgetId] != nil
+  }
+
+  var serverDrivenWidgetIds: Set<String> {
+    Set(intervals.keys)
+  }
+}
+
+/// Assembles the settings stack for the process.
+///
+/// Everything that needs server-update settings goes through here: the payload timeline, the
+/// Dynamic Widget timeline, and the bridge methods. Neither engine reads Info.plist, the Keychain,
+/// or the credential records on its own, which is what keeps the layer order and the merge rule in
+/// one place.
+public enum VoltraWidgetServer {
+  private static let configLayer = ConfigWidgetServerSettingsLayer()
+
+  /// Fixed order, lowest priority first. An instance layer will slot in above `widget`.
+  public static let resolver = WidgetServerSettingsResolver(
+    layers: [
+      configLayer,
+      CredentialsWidgetServerSettingsLayer(),
+      GlobalWidgetServerSettingsLayer(),
+      WidgetWidgetServerSettingsLayer(),
+    ],
+    revisionSource: { WidgetServerSettingsStore.revision() }
+  )
+
+  /// Every widget app.json marked server-driven, whichever engine renders it.
+  public static var serverDrivenWidgetIds: Set<String> {
+    configLayer.serverDrivenWidgetIds
+  }
+
+  public static func isServerDriven(_ widgetId: String) -> Bool {
+    configLayer.isServerDriven(.of(widgetId))
+  }
+
+  /// Whether the widget draws a refresh button. Build-time only: the button is generated UI
+  /// structure, so unlike the URL and the interval it cannot be changed at runtime.
+  public static func isRefreshEnabled(for widgetId: String) -> Bool {
+    guard let refresh = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerRefresh) as? [String: Bool] else {
+      return false
+    }
+
+    return refresh[widgetId] ?? false
+  }
+
+  /// Whether plain http to a local dev host is allowed. Release builds have App Transport Security
+  /// blocking cleartext anyway, so accepting such a URL there would only move the failure to fetch
+  /// time.
+  public static var isDebugBuild: Bool {
+    #if DEBUG
+      return true
+    #else
+      return false
+    #endif
+  }
+
+  /// The device state a request carries. The theme is passed in rather than read here so this
+  /// whole module stays free of UIKit and the request contract can be tested without a simulator;
+  /// `VoltraWidgetAppearance` is the UIKit-side helper that supplies it.
+  public static func requestContext(theme: String, family: String? = nil) -> WidgetServerRequestContext {
+    WidgetServerRequestContext(
+      theme: theme,
+      locale: bcp47Locale(),
+      userAgent: userAgent(),
+      family: family
+    )
+  }
+
+  /// The device locale as a BCP-47 tag, so a backend sees `en-US` from both platforms.
+  /// `Locale.identifier` is the ICU form (`en_US`), which is not what the contract promises.
+  static func bcp47Locale(_ locale: Locale = .current) -> String {
+    if #available(iOS 16.0, macOS 13.0, *) {
+      return locale.identifier(.bcp47)
+    }
+
+    return locale.identifier.replacingOccurrences(of: "_", with: "-")
+  }
+
+  static func userAgent() -> String {
+    "VoltraWidget/\(VoltraConfig.voltraVersion()) (iOS/\(systemVersion))"
+  }
+
+  /// `UIDevice.current.systemVersion` is main-actor isolated and a timeline provider is not, so
+  /// the OS version comes from `ProcessInfo`, which is not.
+  private static var systemVersion: String {
+    let version = ProcessInfo.processInfo.operatingSystemVersion
+
+    return "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
+  }
+
+  /// Resolves settings and builds the request for one scope, or returns nil when there is nothing
+  /// to fetch.
+  public static func request(
+    for scope: WidgetScope,
+    context: WidgetServerRequestContext,
+    etag: String? = nil
+  ) -> URLRequest? {
+    WidgetServerRequestBuilder.build(
+      scope: scope,
+      settings: resolver.resolve(scope),
+      context: context,
+      etag: etag
+    )
+  }
+}

package/ios/shared/WidgetServer/WidgetCanonicalConfiguration.swift

@@ -0,0 +1,77 @@
+import Foundation
+
+/// Turns a merged `env.configuration` map into the canonical form ADR 0007 sends on the wire and
+/// hashes into an instance key.
+///
+/// Canonical serialization: keys sorted by Unicode scalar (code point), no whitespace, values as
+/// JSON strings. Decoded, it is byte for byte what the widget sees as `env.configuration`, so
+/// server and widget agree by construction. Both platforms produce this same string for the same
+/// map, which is what lets the hash below be a stable, cross-platform instance identity.
+public enum WidgetCanonicalConfiguration {
+  /// The canonical JSON string for `configuration`, or nil when the map is empty — a widget with
+  /// no configuration parameters has exactly one instance, the widget scope, and sends neither
+  /// `instance` nor `configuration`.
+  public static func canonicalize(_ configuration: [String: String]) -> String? {
+    guard !configuration.isEmpty else { return nil }
+
+    let sortedKeys = configuration.keys.sorted { lhs, rhs in
+      lhs.unicodeScalars.lexicographicallyPrecedes(rhs.unicodeScalars) { $0.value < $1.value }
+    }
+
+    var pieces: [String] = []
+    pieces.reserveCapacity(sortedKeys.count)
+    for key in sortedKeys {
+      let value = configuration[key] ?? ""
+      pieces.append("\(encodeJSONString(key)):\(encodeJSONString(value))")
+    }
+
+    return "{" + pieces.joined(separator: ",") + "}"
+  }
+
+  /// The instance key for `configuration`: FNV-1a, 32-bit, over the UTF-8 bytes of the canonical
+  /// serialization, rendered as 8 lowercase hex digits. Nil when the map is empty, matching
+  /// `canonicalize`.
+  ///
+  /// FNV-1a was picked for being small, dependency-free, and trivial to reproduce identically in
+  /// Kotlin — this is not a cryptographic hash, and nothing about instance identity depends on
+  /// collision resistance beyond "different configurations usually get different keys".
+  public static func key(_ configuration: [String: String]) -> String? {
+    guard let canonical = canonicalize(configuration) else { return nil }
+    return fnv1a32Hex(canonical)
+  }
+
+  /// Minimal, dependency-free JSON string encoder — just enough for configuration keys/values,
+  /// which are plain strings, not arbitrary JSON. Escapes the characters `JSONSerialization` would.
+  private static func encodeJSONString(_ value: String) -> String {
+    var result = "\""
+    for scalar in value.unicodeScalars {
+      switch scalar {
+      case "\"": result += "\\\""
+      case "\\": result += "\\\\"
+      case "\n": result += "\\n"
+      case "\r": result += "\\r"
+      case "\t": result += "\\t"
+      default:
+        if scalar.value < 0x20 {
+          result += String(format: "\\u%04x", scalar.value)
+        } else {
+          result.unicodeScalars.append(scalar)
+        }
+      }
+    }
+    result += "\""
+    return result
+  }
+
+  private static let fnvOffsetBasis: UInt32 = 0x811C_9DC5
+  private static let fnvPrime: UInt32 = 0x0100_0193
+
+  private static func fnv1a32Hex(_ value: String) -> String {
+    var hash = fnvOffsetBasis
+    for byte in Array(value.utf8) {
+      hash ^= UInt32(byte)
+      hash = hash &* fnvPrime
+    }
+    return String(format: "%08x", hash)
+  }
+}

package/ios/shared/WidgetServer/WidgetScope.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+/// The unit everything server-driven is keyed by: settings, fetched props, the stored ETag, fetch
+/// coalescing, and the settings revision.
+///
+/// `.widget` is a whole widget id. `.instance` (ADR 0007) is one distinct merged configuration of a
+/// widget: two placements with identical configuration share one key, one fetch, one ETag and one
+/// props slot. The settings resolver, ETag store, status store, runner and request builder take
+/// either case with no signature change; the settings layers keep resolving by widget id, so an
+/// instance inherits the widget's URL, interval, method, headers and body.
+public enum WidgetScope: Hashable, Sendable {
+  case widget(id: String)
+
+  /// One distinct merged configuration of `id`. `key` is the hash of that configuration's
+  /// canonical serialization (see `WidgetCanonicalConfiguration`) — opaque, stable, and produced
+  /// identically on Android for the same configuration. WidgetKit has no placement id, so this is
+  /// the only identity an iOS placement can have.
+  case instance(id: String, key: String)
+
+  /// Widget id this scope belongs to. An instance scope reports the id it is an instance of.
+  public var widgetId: String {
+    switch self {
+    case let .widget(id):
+      return id
+    case let .instance(id, _):
+      return id
+    }
+  }
+
+  /// Stable key for per-scope storage. An instance scope appends its placement key, so
+  /// widget-scoped records written today keep their keys.
+  public var storageKey: String {
+    switch self {
+    case let .widget(id):
+      return id
+    case let .instance(id, key):
+      return "\(id)#\(key)"
+    }
+  }
+
+  /// Convenience for the common case, so callers do not spell out the case name.
+  public static func of(_ widgetId: String) -> WidgetScope {
+    .widget(id: widgetId)
+  }
+
+  /// The scope for one placement's merged `configuration` (ADR 0007): `.instance` when the
+  /// configuration is non-empty, `.widget` when it is — a widget with no configuration parameters
+  /// has exactly one instance, the widget scope, and its requests and storage are unchanged.
+  public static func of(_ widgetId: String, configuration: [String: String]) -> WidgetScope {
+    if let key = WidgetCanonicalConfiguration.key(configuration) {
+      return .instance(id: widgetId, key: key)
+    }
+    return .widget(id: widgetId)
+  }
+}

package/ios/shared/WidgetServer/WidgetServerEtagStore.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+/// The ETag from the last `200`, stored with the URL it came from.
+///
+/// Keeping the URL alongside it is what makes `If-None-Match` safe once the app can change the URL
+/// at runtime: an ETag minted by one endpoint says nothing about another, and sending it could
+/// produce a `304` that leaves the widget showing the previous endpoint's data forever.
+///
+/// Lives in the App Group so the widget extension and the app agree on it. Without an App Group
+/// there is nowhere shared to put it, and the widget simply revalidates nothing.
+public enum WidgetServerEtagStore {
+  /// The stored ETag, but only if it was minted by `url`.
+  public static func etag(for scope: WidgetScope, url: String?) -> String? {
+    guard let url, let defaults = defaults(),
+          defaults.string(forKey: urlKey(scope)) == url
+    else {
+      return nil
+    }
+
+    return defaults.string(forKey: etagKey(scope))
+  }
+
+  public static func put(_ etag: String?, for scope: WidgetScope, url: String) {
+    guard let defaults = defaults() else { return }
+
+    guard let etag else {
+      clear(scope)
+      return
+    }
+
+    defaults.set(etag, forKey: etagKey(scope))
+    defaults.set(url, forKey: urlKey(scope))
+  }
+
+  public static func clear(_ scope: WidgetScope) {
+    guard let defaults = defaults() else { return }
+
+    defaults.removeObject(forKey: etagKey(scope))
+    defaults.removeObject(forKey: urlKey(scope))
+  }
+
+  private static func defaults() -> UserDefaults? {
+    guard let group = VoltraConfig.groupIdentifier() else { return nil }
+
+    return UserDefaults(suiteName: group)
+  }
+
+  private static func etagKey(_ scope: WidgetScope) -> String {
+    "Voltra_WidgetServerEtag_\(scope.storageKey)"
+  }
+
+  private static func urlKey(_ scope: WidgetScope) -> String {
+    "Voltra_WidgetServerEtagUrl_\(scope.storageKey)"
+  }
+}