@use-voltra/ios-client 2.1.1 → 2.3.0

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)"
+  }
+}

package/ios/shared/WidgetServer/WidgetServerFetcher.swift

@@ -0,0 +1,179 @@
+import Foundation
+
+/// What came back from the server, before either engine decides what it means.
+///
+/// The request side is identical for a payload widget and a Dynamic Widget, so it lives here once.
+/// Only the interpretation of `body` differs: one parses a Voltra payload, the other props.
+public enum WidgetServerFetchResult: Sendable {
+  /// `200` with a body. `etag` is present when the response carried one.
+  case success(body: Data, etag: String?, httpStatus: Int, nextIntervalMinutes: Int?)
+  /// `304`: what is already committed is still current.
+  case notModified(nextIntervalMinutes: Int?)
+  /// The request never completed: no connectivity, DNS, TLS, or a timeout.
+  case networkFailure(message: String)
+  /// The server answered with a status we cannot use.
+  case httpFailure(httpStatus: Int, retryAfterMinutes: Int?)
+  /// A `2xx` whose body is over `WidgetServerUpdateDefaults.maxBodyBytes`. Kept apart from
+  /// `httpFailure` because the server did answer: this is a body the device refuses, so it is
+  /// reported as a parse failure and asking again is pointless.
+  case tooLarge(httpStatus: Int)
+
+  public var isUnauthorized: Bool {
+    if case let .httpFailure(status, _) = self {
+      return status == 401 || status == 403
+    }
+    return false
+  }
+
+  /// True when waiting and asking again could plausibly succeed.
+  public var isTransient: Bool {
+    switch self {
+    case .networkFailure:
+      return true
+    case let .httpFailure(status, _):
+      return status >= 500 || status == 429
+    default:
+      return false
+    }
+  }
+}
+
+/// Executes a request built by `WidgetServerRequestBuilder` and reports what happened, without
+/// deciding what to do about it.
+public enum WidgetServerFetcher {
+  /// Refuses to leave the host the app configured, so an `Authorization` header or a request body
+  /// cannot be replayed somewhere the app never agreed to send it.
+  private final class SameHostRedirectDelegate: NSObject, URLSessionTaskDelegate {
+    func urlSession(
+      _: URLSession,
+      task: URLSessionTask,
+      willPerformHTTPRedirection _: HTTPURLResponse,
+      newRequest request: URLRequest,
+      completionHandler: @escaping (URLRequest?) -> Void
+    ) {
+      guard let originalHost = task.originalRequest?.url?.host,
+            let originalScheme = task.originalRequest?.url?.scheme,
+            let nextHost = request.url?.host,
+            nextHost.caseInsensitiveCompare(originalHost) == .orderedSame,
+            request.url?.scheme == originalScheme
+      else {
+        VoltraLogger.widget.warning("Refusing cross-host redirect for a widget server request")
+        completionHandler(nil)
+        return
+      }
+
+      completionHandler(request)
+    }
+  }
+
+  private static let redirectDelegate = SameHostRedirectDelegate()
+
+  public static func fetch(
+    _ request: URLRequest,
+    session: URLSession = .shared
+  ) async -> WidgetServerFetchResult {
+    do {
+      // bytes(for:) rather than data(for:) so an oversized body is abandoned mid-stream. A widget
+      // extension has a 30 MB ceiling for the whole render, and buffering first would spend it
+      // before we ever got to check.
+      let (stream, response) = try await session.bytes(for: request, delegate: redirectDelegate)
+
+      guard let http = response as? HTTPURLResponse else {
+        return .networkFailure(message: "Response was not an HTTP response")
+      }
+
+      let nextIntervalMinutes = maxAgeMinutes(http.value(forHTTPHeaderField: "Cache-Control"))
+
+      if http.statusCode == 304 {
+        return .notModified(nextIntervalMinutes: nextIntervalMinutes)
+      }
+
+      guard (200 ... 299).contains(http.statusCode) else {
+        return .httpFailure(
+          httpStatus: http.statusCode,
+          retryAfterMinutes: retryAfterMinutes(http.value(forHTTPHeaderField: "Retry-After"))
+        )
+      }
+
+      guard let body = try await readBody(stream) else {
+        // Asking again returns the same oversized body, so this is a failure the app has to fix
+        // rather than one to back off from.
+        VoltraLogger.widget.error(
+          "Response is larger than \(WidgetServerUpdateDefaults.maxBodyBytes, privacy: .public) bytes"
+        )
+        return .tooLarge(httpStatus: http.statusCode)
+      }
+
+      return .success(
+        body: body,
+        etag: http.value(forHTTPHeaderField: "ETag"),
+        httpStatus: http.statusCode,
+        nextIntervalMinutes: nextIntervalMinutes
+      )
+    } catch {
+      return .networkFailure(message: error.localizedDescription)
+    }
+  }
+
+  /// Returns nil as soon as the body passes the cap, without holding the rest of it.
+  private static func readBody(_ stream: URLSession.AsyncBytes) async throws -> Data? {
+    var body = Data()
+    body.reserveCapacity(16 * 1024)
+
+    for try await byte in stream {
+      if body.count >= WidgetServerUpdateDefaults.maxBodyBytes {
+        return nil
+      }
+
+      body.append(byte)
+    }
+
+    return body
+  }
+
+  /// `Cache-Control: max-age=N`, in minutes, rounded down.
+  static func maxAgeMinutes(_ header: String?) -> Int? {
+    guard let header else { return nil }
+
+    let pattern = try? NSRegularExpression(pattern: "max-age\\s*=\\s*(\\d+)", options: .caseInsensitive)
+    let range = NSRange(header.startIndex ..< header.endIndex, in: header)
+
+    guard let match = pattern?.firstMatch(in: header, range: range),
+          let secondsRange = Range(match.range(at: 1), in: header),
+          let seconds = Int(header[secondsRange])
+    else {
+      return nil
+    }
+
+    return seconds / 60
+  }
+
+  /// `Retry-After`, in minutes, rounded up so we never retry early.
+  ///
+  /// The header is delta-seconds or an HTTP date; both are in the wild, so both are read.
+  static func retryAfterMinutes(_ header: String?, now: Date = Date()) -> Int? {
+    guard let value = header?.trimmingCharacters(in: .whitespaces), !value.isEmpty else {
+      return nil
+    }
+
+    if let seconds = Int(value) {
+      return seconds > 0 ? (seconds + 59) / 60 : nil
+    }
+
+    guard let date = httpDateFormatter.date(from: value) else {
+      return nil
+    }
+
+    let seconds = Int(date.timeIntervalSince(now))
+
+    return seconds > 0 ? (seconds + 59) / 60 : nil
+  }
+
+  private static let httpDateFormatter: DateFormatter = {
+    let formatter = DateFormatter()
+    formatter.locale = Locale(identifier: "en_US_POSIX")
+    formatter.timeZone = TimeZone(identifier: "GMT")
+    formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
+    return formatter
+  }()
+}

package/ios/shared/WidgetServer/WidgetServerRequestBuilder.swift

@@ -0,0 +1,114 @@
+import Foundation
+
+/// The device state a request carries that is not part of the settings: the theme and locale the
+/// widget is being drawn in, and who is asking.
+///
+/// Passed in rather than read here so the request contract can be tested without UIKit, and so a
+/// timeline request built for one appearance cannot accidentally report another.
+public struct WidgetServerRequestContext: Equatable, Sendable {
+  public let theme: String
+  public let locale: String
+  public let userAgent: String
+  /// Only payload widgets send `family`: one Dynamic Widget fetch serves every size, so its props
+  /// must be size-agnostic and the entry picks its layout from `env.widgetFamily`.
+  public let family: String?
+
+  public init(theme: String, locale: String, userAgent: String, family: String? = nil) {
+    self.theme = theme
+    self.locale = locale
+    self.userAgent = userAgent
+    self.family = family
+  }
+}
+
+/// Turns resolved settings plus Voltra's own request parameters into the request the device sends.
+///
+/// Both engines build their requests here, so a payload widget and a Dynamic Widget send the same
+/// shape and the app's runtime overrides apply to both. Only the response and what the device does
+/// with it differ.
+public enum WidgetServerRequestBuilder {
+  /// Widgets have limited execution time, so a request that has not answered in this long is not
+  /// going to be useful even if it eventually does.
+  public static let timeoutSeconds: TimeInterval = 15
+
+  /// - Parameter etag: from the last `200`, sent as `If-None-Match`. Callers pass nil when the
+  ///   stored ETag belongs to a different URL than the one being fetched now.
+  /// - Returns: nil when there is nothing to fetch — no URL, fetching is off, or the URL will not
+  ///   parse.
+  public static func build(
+    scope: WidgetScope,
+    settings: ResolvedWidgetServerSettings,
+    context: WidgetServerRequestContext,
+    etag: String? = nil,
+    // The placement's merged configuration (ADR 0007). Empty for a widget with no configuration
+    // parameters, or when the caller only knows the scope's key — the caller is responsible for
+    // passing the same map that produced `scope`'s key, since the key alone cannot be reversed
+    // back into the configuration that produced it.
+    configuration: [String: String] = [:]
+  ) -> URLRequest? {
+    guard settings.shouldFetch, let url = settings.url, var components = URLComponents(string: url) else {
+      return nil
+    }
+
+    var queryItems = components.queryItems ?? []
+    queryItems.append(URLQueryItem(name: "widgetId", value: scope.widgetId))
+    queryItems.append(URLQueryItem(name: "platform", value: "ios"))
+
+    if let family = context.family {
+      queryItems.append(URLQueryItem(name: "family", value: family))
+    }
+
+    queryItems.append(URLQueryItem(name: "theme", value: context.theme))
+    queryItems.append(URLQueryItem(name: "locale", value: context.locale))
+
+    // Present for every method, absent when the widget has no configuration parameters (ADR
+    // 0007). `instance` is the hash of the canonical `configuration`, sent so a backend can cache
+    // or log per instance without recomputing it.
+    if case let .instance(_, key) = scope, let canonicalConfiguration = WidgetCanonicalConfiguration.canonicalize(configuration) {
+      queryItems.append(URLQueryItem(name: "instance", value: key))
+      queryItems.append(URLQueryItem(name: "configuration", value: canonicalConfiguration))
+    }
+
+    // Voltra's own keys are appended first and the app's keys are rejected at call time if they
+    // collide, so nothing here can shadow what the server relies on.
+    for key in settings.query.keys.sorted() {
+      queryItems.append(URLQueryItem(name: key, value: settings.query[key]))
+    }
+
+    components.queryItems = queryItems
+
+    guard let resolvedUrl = components.url else { return nil }
+
+    var request = URLRequest(url: resolvedUrl)
+    let method = settings.method.uppercased()
+
+    request.httpMethod = method
+    request.timeoutInterval = timeoutSeconds
+    request.setValue("application/json", forHTTPHeaderField: "Accept")
+    request.setValue(context.userAgent, forHTTPHeaderField: "User-Agent")
+
+    for (key, value) in settings.headers {
+      request.setValue(value, forHTTPHeaderField: key)
+    }
+
+    if let etag {
+      request.setValue(etag, forHTTPHeaderField: "If-None-Match")
+    }
+
+    if let body = settings.body {
+      if WidgetServerUpdateDefaults.bodylessMethods.contains(method) {
+        // URLSession sends a Content-Length and drops the body on GET, so the server would see a
+        // request the app did not mean to send. Dropping it here is the lesser surprise, and it is
+        // documented.
+        VoltraLogger.widget.warning(
+          "Dropping request body for widget '\(scope.widgetId, privacy: .public)': \(method, privacy: .public) cannot carry one"
+        )
+      } else {
+        request.httpBody = Data(body.utf8)
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+      }
+    }
+
+    return request
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsCodec.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// Serializes one settings layer for storage. Written as a small versioned envelope so a future
+/// shape change can be recognised rather than guessed at, the same way Dynamic Widget props are
+/// stored.
+public enum WidgetServerSettingsCodec {
+  private static let versionKey = "widgetServerSettingsVersion"
+  private static let settingsKey = "widgetServerSettings"
+  private static let version = 1
+
+  public static func encode(_ settings: WidgetServerUpdateSettings) -> Data? {
+    var payload: [String: Any] = [:]
+
+    settings.url.map { payload["url"] = $0 }
+    settings.intervalMinutes.map { payload["intervalMinutes"] = $0 }
+    settings.enabled.map { payload["enabled"] = $0 }
+    settings.method.map { payload["method"] = $0 }
+    settings.query.map { payload["query"] = $0 }
+    settings.headers.map { payload["headers"] = $0 }
+    settings.body.map { payload["body"] = $0 }
+
+    let envelope: [String: Any] = [versionKey: version, settingsKey: payload]
+
+    return try? JSONSerialization.data(withJSONObject: envelope)
+  }
+
+  /// Returns nil for anything this version cannot read, so a bad record reads as "no opinion".
+  public static func decode(_ data: Data?) -> WidgetServerUpdateSettings? {
+    guard let data,
+          let envelope = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          envelope[versionKey] as? Int == version,
+          let payload = envelope[settingsKey] as? [String: Any]
+    else {
+      return nil
+    }
+
+    return WidgetServerUpdateSettings(
+      url: payload["url"] as? String,
+      intervalMinutes: payload["intervalMinutes"] as? Int,
+      enabled: payload["enabled"] as? Bool,
+      method: payload["method"] as? String,
+      query: payload["query"] as? [String: String],
+      headers: payload["headers"] as? [String: String],
+      body: payload["body"] as? String
+    )
+  }
+}

package/ios/shared/WidgetServer/WidgetServerSettingsResolver.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+/// One source of server-update settings. Implementations return a partial
+/// `WidgetServerUpdateSettings`, or nil when they have nothing to say about the scope.
+///
+/// Layers are stacked in a fixed order by `WidgetServerSettingsResolver` and never consulted
+/// directly: nothing outside this folder reads Info.plist, the Keychain, or anything else for
+/// server-update purposes.
+public protocol WidgetServerSettingsLayer: Sendable {
+  /// A short name used in logs, so a surprising resolved value can be traced to its source.
+  var name: String { get }
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings?
+
+  /// Whether this layer knows the scope to be server-driven at all. Only the config layer can
+  /// answer this — a runtime layer setting a URL does not turn a locally-rendered widget into a
+  /// server-driven one, because the engine is chosen at generate time.
+  func isServerDriven(_ scope: WidgetScope) -> Bool
+}
+
+public extension WidgetServerSettingsLayer {
+  func isServerDriven(_: WidgetScope) -> Bool {
+    false
+  }
+}
+
+/// The only way to read server-update settings.
+///
+/// Layers are walked lowest to highest and merged by the rule stated once here: `headers` and
+/// `query` merge per key, everything else takes the value from the highest layer that sets it.
+/// Adding a layer later — an instance layer above `widget`, say — is a new
+/// `WidgetServerSettingsLayer` plus one entry in `layers`; this API and every caller stay as they
+/// are.
+public struct WidgetServerSettingsResolver: Sendable {
+  private let layers: [any WidgetServerSettingsLayer]
+  private let revisionSource: @Sendable () -> Int
+
+  /// - Parameter layers: lowest priority first: config, credentials, global, widget.
+  public init(layers: [any WidgetServerSettingsLayer], revisionSource: @escaping @Sendable () -> Int) {
+    self.layers = layers
+    self.revisionSource = revisionSource
+  }
+
+  /// Flattens every layer for `scope`. Safe to call for any widget: a widget that is not
+  /// server-driven resolves to disabled with no URL, so a caller that fetches on `shouldFetch`
+  /// does nothing rather than guessing.
+  public func resolve(_ scope: WidgetScope) -> ResolvedWidgetServerSettings {
+    var merged = WidgetServerUpdateSettings.empty
+    var intervalFromConfig = false
+
+    for (index, layer) in layers.enumerated() {
+      guard let settings = layer.settings(for: scope) else { continue }
+
+      if settings.intervalMinutes != nil {
+        // Index 0 is the config layer. An interval that came from app.json was already validated
+        // against this platform's rules when the native project was generated, so clamping it
+        // again here would silently change an existing widget's schedule.
+        intervalFromConfig = index == 0
+      }
+
+      merged = Self.merge(lower: merged, higher: settings)
+    }
+
+    let serverDriven = isServerDriven(scope)
+    let url = serverDriven ? merged.url.flatMap { $0.isEmpty ? nil : $0 } : nil
+    let intervalMinutes = merged.intervalMinutes ?? WidgetServerUpdateDefaults.defaultIntervalMinutes
+
+    return ResolvedWidgetServerSettings(
+      url: url,
+      intervalMinutes: intervalFromConfig
+        ? intervalMinutes
+        : WidgetServerUpdateDefaults.clampIntervalMinutes(intervalMinutes),
+      enabled: serverDriven && (merged.enabled ?? true),
+      method: merged.method ?? WidgetServerUpdateDefaults.defaultMethod,
+      query: merged.query ?? [:],
+      headers: merged.headers ?? [:],
+      body: merged.body
+    )
+  }
+
+  /// True when app.json marked this widget server-driven. The engine is chosen at generate time,
+  /// so a runtime URL cannot make a widget server-driven and `setWidgetServerUpdate` rejects
+  /// settings for one that is not.
+  public func isServerDriven(_ scope: WidgetScope) -> Bool {
+    layers.contains { $0.isServerDriven(scope) }
+  }
+
+  /// Raw contents of the global layer: no defaulting, no merge — there is nothing to resolve
+  /// against without a widget scope. Nil when nothing has been set globally.
+  public func globalSettings() -> WidgetServerUpdateSettings? {
+    layers.lazy.compactMap { $0 as? GlobalWidgetServerSettingsLayer }.first?.raw()
+  }
+
+  /// Monotonic counter of settings changes. A fetcher records it before fetching and commits only
+  /// if it is still current, so settings changed mid-flight cannot commit a response built from
+  /// the old ones.
+  ///
+  /// It is one counter for the whole store rather than one per scope: a change to another widget
+  /// can make an in-flight fetch drop its result, and the reload that every `set` queues fetches
+  /// again, so the cost is one wasted request in a rare race.
+  public func revision(_: WidgetScope) -> Int {
+    revisionSource()
+  }
+
+  static func merge(
+    lower: WidgetServerUpdateSettings,
+    higher: WidgetServerUpdateSettings
+  ) -> WidgetServerUpdateSettings {
+    WidgetServerUpdateSettings(
+      url: higher.url ?? lower.url,
+      intervalMinutes: higher.intervalMinutes ?? lower.intervalMinutes,
+      enabled: higher.enabled ?? lower.enabled,
+      method: higher.method ?? lower.method,
+      query: mergePerKey(lower.query, higher.query),
+      headers: mergePerKey(lower.headers, higher.headers),
+      body: higher.body ?? lower.body
+    )
+  }
+
+  private static func mergePerKey(
+    _ lower: [String: String]?,
+    _ higher: [String: String]?
+  ) -> [String: String]? {
+    guard let lower else { return higher }
+    guard let higher else { return lower }
+
+    return lower.merging(higher) { _, fromHigher in fromHigher }
+  }
+}