Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

provider/Sources/Provider/Session.swift

swift
// A running provider on the SDK's C ABI (PROVIDER_CONTRACT.md, "App lifecycle"):
// the network space manager, the provider device with the installation's
// identity, and the listeners that feed its status. 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 only reach it
// through its ProviderInbox.

import CURnetworkSdk
import Foundation
import ProviderCore

/// 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 payout wallet is read again, in seconds. The wallet is fixed; a
/// reread shows a mapping that the backend completes while the provider runs.
let walletSyncInterval = 10.0 * 60.0

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

/// The provider extender role's two device settings (PROVIDER_CONTRACT.md,
/// "Extender role"), passed explicitly and both on. provideExtenderEnabled is
/// the embedder's hard switch: false means the role never runs.
/// defaultProvideExtender is the setting the device uses until the user sets
/// one: false turns the default off.
let provideExtenderEnabled = true
let defaultProvideExtender = true

/// A failure to start the provider that is not a configuration problem.
struct ProviderStartError: 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
}

/// Reads one buffer-out value: the first call asks for the size, the second
/// copies. A value that grew in between is asked for again.
func readSdkBytes(_ read: (UnsafeMutablePointer<UInt8>?, UnsafeMutablePointer<Int32>?) -> Bool)
  -> Data
{
  var byteCount: Int32 = 0
  _ = read(nil, &byteCount)
  for _ in 0..<3 {
    if byteCount <= 0 {
      return Data()
    }
    var bytes = [UInt8](repeating: 0, count: Int(byteCount))
    var capacity = byteCount
    let copied = bytes.withUnsafeMutableBufferPointer { read($0.baseAddress, &capacity) }
    if copied {
      return Data(bytes.prefix(Int(capacity)))
    }
    byteCount = capacity
  }
  return Data()
}

/// One run of the provider. The initializer starts providing; run shows the
/// status until a stop or a credential error; close stops providing.
final class ProviderSession {
  private let config: ProviderConfig
  private let inbox: ProviderInbox
  /// 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,
  /// or a wallet read that finishes after the device closed, 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

  /// payoutWalletChecking, payoutWalletUnavailable, payoutWalletNotSet or the
  /// mapped coldkey; only the status loop's thread uses these
  private var payoutWallet = payoutWalletChecking
  private var payoutWalletScope = ""

  /// Creates the provider device with the installation's identity and the
  /// extender role's settings on, saves a new identity on first run, and starts
  /// providing publicly. The SDK declares provide intent on the device's
  /// platform connections by itself while the provide mode is public.
  init(config: ProviderConfig, inbox: ProviderInbox) throws {
    self.config = config
    self.inbox = inbox
    inboxContext = Unmanaged.passRetained(inbox).toOpaque()

    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 ProviderStartError("the sdk did not create the network space")
    }
    urnet_api_set_by_jwt(api, config.clientJwt)

    // one call for both runs: on first run there is no identity, the key
    // material handle is 0 and the device makes a new identity, saved below
    var keyMaterial: UInt64 = 0
    if let material = providerKeyMaterial(config.identity) {
      keyMaterial = urnet_new_device_local_key_material(
        material.clientKeySeed, Int32(material.clientKeySeed.count),
        material.provideTlsCertificatePem, Int32(material.provideTlsCertificatePem.count),
        material.provideTlsPrivateKeyPem, Int32(material.provideTlsPrivateKeyPem.count))
      if keyMaterial == 0 {
        releaseHandles()
        throw ProviderStartError("the sdk did not take the provider identity")
      }
      if !material.extenderKeySeed.isEmpty {
        urnet_device_local_key_material_set_extender_key_seed(
          keyMaterial, material.extenderKeySeed, Int32(material.extenderKeySeed.count))
      }
    }
    var error: UnsafeMutablePointer<CChar>?
    device = urnet_new_device_local_with_provide_extender(
      space, config.clientJwt, deviceDescription, deviceSpec, "1", config.instanceId, false,
      keyMaterial, provideExtenderEnabled, defaultProvideExtender, &error)
    if keyMaterial != 0 {
      urnet_release(keyMaterial)
    }
    let errorText = takeSdkString(error)
    if device == 0 {
      releaseHandles()
      throw ProviderStartError(errorText ?? "the sdk did not create the device")
    }
    if config.identity == nil {
      // keep the new identity, so later starts present the same provider
      let device = device
      let identity = ProviderIdentity(
        version: providerIdentityVersion, clientId: config.clientId,
        clientKeySeed: readSdkBytes { urnet_device_local_get_client_key_seed(device, $0, $1) },
        provideTlsCertificatePem: readSdkBytes {
          urnet_device_local_get_provide_tls_certificate_pem(device, $0, $1)
        },
        provideTlsPrivateKeyPem: readSdkBytes {
          urnet_device_local_get_provide_tls_private_key_pem(device, $0, $1)
        },
        extenderKeySeed: readSdkBytes { urnet_device_local_get_extender_key_seed(device, $0, $1) })
      if identity.clientKeySeed.count != 32 {
        releaseHandles()
        throw ProviderStartError("the device has no provider identity to save")
      }
      do {
        try saveProviderIdentity(stateDir: config.stateDir, identity: identity)
      } catch {
        releaseHandles()
        throw ProviderStartError("save \(identityFileName): \(error)")
      }
    }

    // each callback copies what it carries before returning
    subs = [
      urnet_device_add_jwt_refresh_listener(
        device,
        { userData, clientJwt in
          withCallbackPool {
            guard let inbox = ProviderInbox.of(userData), let clientJwt else {
              return
            }
            inbox.jwtRefreshed(String(cString: clientJwt))
          }
        }, inboxContext),
      urnet_device_add_auth_logout_listener(
        device,
        { userData in
          withCallbackPool {
            ProviderInbox.of(userData)?.authLogout()
          }
        }, inboxContext),
      urnet_device_add_provider_ingress_contract_details_change_listener(
        device,
        { userData, detailsJson in
          withCallbackPool {
            guard let inbox = ProviderInbox.of(userData), let detailsJson,
              let details = decodeContractDetails(String(cString: detailsJson))
            else {
              return
            }
            inbox.clientsServed.add(details, receive: true)
          }
        }, inboxContext),
      urnet_device_add_provider_egress_contract_details_change_listener(
        device,
        { userData, detailsJson in
          withCallbackPool {
            guard let inbox = ProviderInbox.of(userData), let detailsJson,
              let details = decodeContractDetails(String(cString: detailsJson))
            else {
              return
            }
            inbox.clientsServed.add(details, receive: false)
          }
        }, inboxContext),
    ]
    urnet_device_set_provide_mode(device, Int64(URNET_PROVIDE_MODE_PUBLIC))
    syncWallet()
  }

  /// Reads the status from the device getters and the counted clients.
  func status() -> ProviderStatus {
    // "client_limit_exceeded" with the hold's end in RetryTime while the
    // platform holds this client off for its network's client limit
    let clientLimitStatus = decodeClientLimitStatus(
      takeSdkString(urnet_device_get_client_limit_status(device)))
    // urnet_device_local_get_provider_ready also waits for processed client key
    // registration, which default device settings do not enable, so the
    // connected carrier is the readiness signal here
    let state = providerState(
      provideMode: urnet_device_get_provide_mode(device),
      clientLimitStatus: clientLimitStatus.status,
      providePaused: urnet_device_get_provide_paused(device),
      provideEnabled: urnet_device_get_provide_enabled(device),
      providerConnected: urnet_device_local_get_provider_connected(device))
    let clientsServed = inbox.clientsServed.count()
    return ProviderStatus(
      state: state, clientLimitRetryTime: clientLimitStatus.retryTime,
      clientsServed: clientsServed.count, clientsServedAtLimit: clientsServed.atLimit,
      dataProvidedByteCount: decodeDataProvidedByteCount(
        takeSdkString(urnet_device_get_provider_packet_stats(device))),
      payoutWallet: payoutWallet, payoutWalletScope: payoutWalletScope)
  }

  /// Starts a payout wallet read (GET /sn/wallet with the client credential).
  /// The app only displays the wallet: the backend maps it, never the app.
  func syncWallet() {
    urnet_device_local_sync_sn_wallet(
      device,
      { userData, resultJson, errorText in
        withCallbackPool {
          let succeeded = snGetWalletSucceeded(
            resultJson: resultJson.map { String(cString: $0) },
            errorText: errorText.map { String(cString: $0) })
          ProviderInbox.of(userData)?.walletSynced(succeeded: succeeded)
        }
      }, inboxContext)
  }

  /// Prints status lines until a stop request or until the server rejects the
  /// credential, and returns the process exit code.
  func run() -> Int32 {
    var lastKey = ""
    var lastPrintTime = -Double.infinity
    var nextWalletSyncTime = ProcessInfo.processInfo.systemUptime + walletSyncInterval
    while true {
      let items = inbox.take()
      applyWalletSync(succeeded: items.walletSyncSucceeded, failed: items.walletSyncFailed)
      saveRefreshedClientJwt(items.refreshedClientJwt)
      let status = self.status()
      let now = ProcessInfo.processInfo.systemUptime
      if status.key != lastKey || statusRepeatInterval <= now - lastPrintTime {
        writeOutput(status.line)
        lastKey = status.key
        lastPrintTime = now
      }
      if nextWalletSyncTime <= now {
        syncWallet()
        nextWalletSyncTime = now + walletSyncInterval
      }
      if items.stopRequested {
        return ProviderExitCode.stopped
      }
      if items.authLoggedOut {
        writeError(
          "the server rejected the client credential; issue a new scoped client JWT from your backend"
        )
        return ProviderExitCode.config
      }
      inbox.wait(seconds: statusPollInterval)
    }
  }

  /// Stops providing, closes the subscriptions, the device and the manager, and
  /// releases their handles.
  func close() {
    if closed {
      return
    }
    closed = true
    urnet_device_set_provide_mode(device, Int64(URNET_PROVIDE_MODE_NONE))
    releaseHandles()
    // a token refreshed while stopping is still saved for the next start
    saveRefreshedClientJwt(inbox.take().refreshedClientJwt)
    writeOutput("status: stopped")
  }

  /// 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
    }
  }

  /// Records a finished wallet read. A failure keeps the last known wallet.
  private func applyWalletSync(succeeded: Bool, failed: Bool) {
    if succeeded {
      // the sdk caches the effective wallet before the callback: this client's
      // own consent, else the network consent, else (with hotkey delegations)
      // the network's hotkey entry, else a non-consent wallet
      guard let wallet = decodeSnWallet(takeSdkString(urnet_device_local_get_sn_wallet(device)))
      else {
        payoutWallet = payoutWalletNotSet
        payoutWalletScope = ""
        return
      }
      payoutWallet = wallet.coldkeySs58
      payoutWalletScope = payoutWalletScopeOf(
        walletConsentScope: wallet.consentScope, walletClientId: wallet.clientId,
        clientId: config.clientId)
    } else if failed && payoutWallet == payoutWalletChecking {
      payoutWallet = payoutWalletUnavailable
    }
  }

  /// Keeps a refreshed credential, so the next start uses a valid token.
  private func saveRefreshedClientJwt(_ clientJwt: String?) {
    guard let clientJwt else {
      return
    }
    do {
      try writePrivateFile(
        joinPath(config.stateDir, clientJwtFileName), Data((clientJwt + "\n").utf8))
    } catch {
      // never print the token itself
      writeError("could not save the refreshed client credential: \(error)")
    }
  }
}