Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

embed/Sources/Embed/Session.swift

swift
// A running embed app on the SDK's C ABI (EMBED_CONTRACT.md, "App lifecycle"):
// the network space manager, the local device with this installation's client
// JWT, and the listeners that feed its status. The device carries only the
// app's own traffic; it does not provide. Handles are SDK object references;
// each one is closed where it has a close function, then released. The
// session runs on the app's thread; the SDK's callbacks and the cap reads only
// reach it through its EmbedInbox.

import CURnetworkSdk
import EmbedCore
import Foundation

/// How often the status is read, and the longest gap between status lines, in
/// seconds.
let statusPollInterval = 1.0
let statusRepeatInterval = 60.0

/// How often the caps are read, in seconds. A contract status change reads them
/// at the next pass of the run loop, well within the contract's 5 seconds;
/// changes during a read add one more read.
let capReadInterval = 5.0 * 60.0

/// The device description and spec recorded for this installation's device.
let deviceDescription = "Swift embed example"
let deviceSpec = "urnetwork-examples/swift-embed"

/// The destination of the app's own traffic: the best available location.
let bestAvailableLocation = #"{"connect_location_id":{"best_available":true}}"#

/// A failure to start the device that is not a configuration problem.
struct EmbedStartError: Error, CustomStringConvertible {
  let description: String

  /// An error with the given text.
  init(_ description: String) {
    self.description = description
  }
}

/// Copies a string the SDK returned and frees the SDK's copy. nil for NULL.
func takeSdkString(_ value: UnsafeMutablePointer<CChar>?) -> String? {
  guard let value else {
    return nil
  }
  defer { urnet_free_string(value) }
  return String(cString: value)
}

/// Runs the body of an SDK callback. SDK threads have no autorelease pool, so on
/// Apple platforms the body runs in its own pool; otherwise an object that
/// Foundation autoreleases there would stay until the long-lived thread exits.
func withCallbackPool(_ body: () -> Void) {
  #if canImport(ObjectiveC)
    autoreleasepool(invoking: body)
  #else
    body()
  #endif
}

/// One run of the app. The initializer starts the device; run shows the status
/// until a stop or a credential error; close stops the device.
final class EmbedSession {
  private var config: EmbedConfig
  private let inbox: EmbedInbox
  /// the inbox as the callbacks' user data. It is retained for the life of the
  /// process: a callback that is already running when its subscription closes
  /// still reaches it.
  private let inboxContext: UnsafeMutableRawPointer

  private var manager: UInt64 = 0
  private var space: UInt64 = 0
  private var api: UInt64 = 0
  private var device: UInt64 = 0
  private var subs: [UInt64] = []
  private var closed = false

  /// the cap readings; only the run loop's thread uses them
  private var caps = Caps()

  /// Creates the local device with the installation's client JWT and instance
  /// id, adds the listeners and sets the destination of the app's traffic. The
  /// provide mode stays at its default: an embed app does not provide.
  init(config: EmbedConfig, inbox: EmbedInbox) throws {
    self.config = config
    self.inbox = inbox
    inboxContext = Unmanaged.passRetained(inbox).toOpaque()
    if let firstCap = config.firstCap {
      caps.apply(firstCap)
    }

    manager = urnet_new_network_space_manager_no_storage()
    space = urnet_network_space_manager_update_network_space_values(
      manager, #"{"host_name":"ur.network","env_name":"main"}"#,
      #"{"migration_host_name":"bringyour.com"}"#)
    api = urnet_network_space_get_api(space)
    if manager == 0 || space == 0 || api == 0 {
      releaseHandles()
      throw EmbedStartError("the sdk did not create the network space")
    }
    urnet_api_set_by_jwt(api, config.clientJwt)

    var error: UnsafeMutablePointer<CChar>?
    device = urnet_new_device_local_with_defaults(
      space, config.clientJwt, deviceDescription, deviceSpec, "1", config.instanceId, false,
      &error)
    let errorText = takeSdkString(error)
    if device == 0 || errorText != nil {
      releaseHandles()
      throw EmbedStartError(errorText ?? "the sdk did not create the device")
    }

    // each callback copies what it carries before returning
    subs = [
      urnet_device_add_jwt_refresh_listener(
        device,
        { userData, clientJwt in
          withCallbackPool {
            guard let inbox = EmbedInbox.of(userData), let clientJwt else {
              return
            }
            inbox.jwtRefreshed(String(cString: clientJwt))
          }
        }, inboxContext),
      urnet_device_add_auth_logout_listener(
        device,
        { userData in
          withCallbackPool {
            EmbedInbox.of(userData)?.authLogout()
          }
        }, inboxContext),
      urnet_device_add_contract_status_change_listener(
        device,
        { userData, _ in
          withCallbackPool {
            EmbedInbox.of(userData)?.contractStatusChanged()
          }
        }, inboxContext),
    ]
    urnet_device_set_connect_location(device, bestAvailableLocation)
  }

  /// Reads the status inputs from the device getters and the caps.
  func readStatusLine() -> String {
    // "client_limit_exceeded" with the hold's end in RetryTime while the
    // platform holds this client off for its network's concurrent client limit
    let clientLimitStatus = decodeClientLimitStatus(
      takeSdkString(urnet_device_get_client_limit_status(device)))
    // NULL before the window exists
    let providersAdded = decodeProvidersAdded(takeSdkString(urnet_device_get_window_status(device)))
    return statusLine(
      StatusInput(
        clientLimitStatus: clientLimitStatus.status,
        clientLimitRetryTime: clientLimitStatus.retryTime, caps: caps,
        providersAdded: providersAdded))
  }

  /// Starts a cap read on its own thread with the current client JWT, so a slow
  /// answer never holds up the status. The thread hands its reading to the run
  /// loop through the inbox.
  func startCapRead() {
    let inbox = inbox
    let apiUrl = config.apiUrl
    let clientJwt = config.clientJwt
    Thread.detachNewThread {
      do {
        let cap = try readCaps(http: urlSessionHttp, apiUrl: apiUrl, clientJwt: clientJwt)
        inbox.capReadFinished(CapRead(cap: cap, error: ""))
      } catch let error as EmbedNotEnabledError {
        inbox.capReadFinished(CapRead(cap: nil, error: "\(error)", notEnabled: true))
      } catch {
        inbox.capReadFinished(CapRead(cap: nil, error: "\(error)"))
      }
    }
  }

  /// Prints status lines until a stop request or until the server rejects the
  /// credential, and returns the process exit code. The caps are read at start
  /// (unless the token server's data_cap was the first reading), every 5
  /// minutes and after a contract status change.
  func run() -> Int32 {
    var lastLine: String?
    var lastPrintTime = 0.0
    var capReadRunning = false
    var capReadFailing = false
    var contractCapReadPending = false
    var nextCapReadTime =
      ProcessInfo.processInfo.systemUptime + (config.firstCap != nil ? capReadInterval : 0)
    while true {
      let items = inbox.take()
      saveRefreshedClientJwt(items.refreshedClientJwt)
      if items.authLoggedOut {
        writeError(
          "the server rejected the client credential; sign in again to obtain a new client JWT from your backend"
        )
        return EmbedExitCode.config
      }
      if items.stopRequested {
        return EmbedExitCode.stopped
      }
      let now = ProcessInfo.processInfo.systemUptime
      if let capRead = items.capRead {
        capReadRunning = false
        // the Embed-not-enabled refusal clears the last reading; another
        // failure keeps it
        caps.record(capRead.cap, notEnabled: capRead.notEnabled)
        if capRead.cap == nil && !capReadFailing {
          writeError("could not read the data caps: \(capRead.error)")
        }
        capReadFailing = capRead.cap == nil
      }
      if items.contractStatusChanged {
        contractCapReadPending = true
      }
      if !capReadRunning && (nextCapReadTime <= now || contractCapReadPending) {
        startCapRead()
        capReadRunning = true
        nextCapReadTime = now + capReadInterval
        contractCapReadPending = false
      }
      let line = readStatusLine()
      if line != lastLine || statusRepeatInterval <= now - lastPrintTime {
        writeOutput(line)
        lastLine = line
        lastPrintTime = now
      }
      inbox.wait(seconds: statusPollInterval)
    }
  }

  /// Closes the subscriptions, the device and the manager, and releases their
  /// handles. A token refreshed before the close is still saved. A console app
  /// prints no stopped line.
  func close() {
    if closed {
      return
    }
    closed = true
    releaseHandles()
    saveRefreshedClientJwt(inbox.take().refreshedClientJwt)
  }

  /// Closes and releases every handle the session holds, in the contract's
  /// order: subscriptions, device, then the space's handles and the manager.
  private func releaseHandles() {
    for sub in subs where sub != 0 {
      urnet_sub_close(sub)
      urnet_release(sub)
    }
    subs = []
    if device != 0 {
      urnet_device_close(device)
      urnet_release(device)
      device = 0
    }
    if api != 0 {
      urnet_release(api)
      api = 0
    }
    if space != 0 {
      urnet_release(space)
      space = 0
    }
    if manager != 0 {
      urnet_network_space_manager_close(manager)
      urnet_release(manager)
      manager = 0
    }
  }

  /// Keeps a refreshed credential, so later cap reads and the next start use a
  /// valid token. The token itself is never printed.
  private func saveRefreshedClientJwt(_ clientJwt: String?) {
    guard let clientJwt else {
      return
    }
    config.clientJwt = clientJwt
    do {
      try saveClientJwt(stateDir: config.stateDir, clientJwt: clientJwt)
    } catch {
      writeError("could not save the refreshed client credential: \(error)")
    }
  }
}