Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

provider/Sources/ProviderCore/Status.swift

swift
// The provider status that every provider example shows, with the exact text
// rules of PROVIDER_CONTRACT.md ("Status"): providing state, clients served,
// data provided and the payout wallet, read only. These are plain values and
// functions, so the self-test checks them without a network, credentials or the
// native SDK. ClientsServed is the one type here that is safe for concurrent use.

import Foundation

/// Shown once at start, and in every example's README. The app that integrates
/// a provider owns the consent screen; this example starts without asking.
public let consentDisclaimer = """
  Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.
  Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.
  This example starts providing without asking, because the consent screen belongs to your app.
  """

/// The SDK's provide modes (URNET_PROVIDE_MODE_* in urnetwork_sdk.h). Kept here
/// so the status rules need no native SDK; the executable's self-test checks
/// them against the header.
public let provideModeNone: Int64 = 0
public let provideModeNetwork: Int64 = 1
public let provideModePublic: Int64 = 3

/// The SDK's client limit status values (URNET_CLIENT_LIMIT_STATUS_*): no hold,
/// or the platform disconnected this client for its network's client limit and
/// the SDK holds off reconnecting until the retry time.
public let clientLimitStatusNone = ""
public let clientLimitStatusExceeded = "client_limit_exceeded"

/// The consent_scope values of a GET /sn/wallet entry. The SDK defines network
/// and provider (URNET_SN_WALLET_CONSENT_SCOPE_*). Hotkey delegations come with a
/// later server and SDK change, which adds the SDK's own constant; the app only
/// labels the entry.
public let snWalletConsentScopeNetwork = "network"
public let snWalletConsentScopeProvider = "provider"
public let snWalletConsentScopeHotkey = "hotkey"

/// The payout wallet before the first wallet read finishes.
public let payoutWalletChecking = "checking"
/// The payout wallet when the first wallet read failed.
public let payoutWalletUnavailable = "unavailable"
/// The payout wallet when no wallet is mapped.
public let payoutWalletNotSet = "not set"

/// The owner of the shown payout wallet, in parentheses after its address.
public let payoutWalletScopeHotkey = "hotkey"
public let payoutWalletScopeProvider = "this provider"
public let payoutWalletScopeNetwork = "network"
public let payoutWalletScopeAnotherProvider = "another provider"

/// Distinct clients are counted up to this many; beyond it the count is a lower
/// bound, shown with a trailing "+".
public let clientsServedLimit = 100 * 1000

let zeroIdString = "00000000-0000-0000-0000-000000000000"

/// The providing state, in the order that providerState checks it.
public enum ProviderState: String {
  case stopped
  /// the platform disconnected this client for its network's client limit, and
  /// the SDK holds off reconnecting until the retry time
  case clientLimit = "client limit"
  case paused
  case providing
  case starting
}

/// One status snapshot.
public struct ProviderStatus: Equatable {
  public var state: ProviderState
  /// the end of the client limit hold in unix milliseconds, shown with the
  /// client limit state; 0 when unknown
  public var clientLimitRetryTime: Int64
  public var clientsServed: Int
  public var clientsServedAtLimit: Bool
  public var dataProvidedByteCount: Int64
  /// a coldkey ss58 address, or payoutWalletChecking, payoutWalletUnavailable or
  /// payoutWalletNotSet
  public var payoutWallet: String
  /// "" unless payoutWallet is an address
  public var payoutWalletScope: String

  /// A snapshot; the defaults are the values before anything was counted.
  public init(
    state: ProviderState, clientLimitRetryTime: Int64 = 0, clientsServed: Int = 0,
    clientsServedAtLimit: Bool = false, dataProvidedByteCount: Int64 = 0, payoutWallet: String,
    payoutWalletScope: String = ""
  ) {
    self.state = state
    self.clientLimitRetryTime = clientLimitRetryTime
    self.clientsServed = clientsServed
    self.clientsServedAtLimit = clientsServedAtLimit
    self.dataProvidedByteCount = dataProvidedByteCount
    self.payoutWallet = payoutWallet
    self.payoutWalletScope = payoutWalletScope
  }

  /// The status line, for example
  /// "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5Grw... (network)".
  public var line: String {
    let clientsServedText = clientsServedAtLimit ? "\(clientsServed)+" : "\(clientsServed)"
    let payoutWalletText =
      payoutWalletScope.isEmpty ? payoutWallet : "\(payoutWallet) (\(payoutWalletScope))"
    let statusText = providerStatusText(state, clientLimitRetryTime: clientLimitRetryTime)
    let dataProvidedText = formatByteCount(dataProvidedByteCount)
    return
      "status: \(statusText) | clients served: \(clientsServedText) | data provided: \(dataProvidedText) | payout wallet: \(payoutWalletText)"
  }

  /// The fields that change rarely. A change prints a status line at once; the
  /// data counter alone only prints on the periodic line. The status text
  /// carries the client limit retry time, so a new retry time prints too.
  public var key: String {
    let statusText = providerStatusText(state, clientLimitRetryTime: clientLimitRetryTime)
    return
      "\(statusText)|\(clientsServed)|\(clientsServedAtLimit)|\(payoutWallet)|\(payoutWalletScope)"
  }
}

/// The status field text: the state, and for the client limit state the time
/// the SDK retries, for example "client limit, retry at 19:05 UTC". The retry
/// time (unix milliseconds) is rounded up to the next whole minute in UTC, so
/// the shown time is never before the real retry; a retry time of 0 shows
/// "client limit".
public func providerStatusText(_ state: ProviderState, clientLimitRetryTime: Int64) -> String {
  guard state == .clientLimit, 0 < clientLimitRetryTime else {
    return state.rawValue
  }
  let minuteMillis: Int64 = 60 * 1000
  // rounds up without overflowing near the largest retry time
  let retryMinute =
    clientLimitRetryTime / minuteMillis + (clientLimitRetryTime % minuteMillis == 0 ? 0 : 1)
  let minuteOfDay = retryMinute % (24 * 60)
  let twoDigits = { (value: Int64) -> String in value < 10 ? "0\(value)" : "\(value)" }
  return
    "\(ProviderState.clientLimit.rawValue), retry at \(twoDigits(minuteOfDay / 60)):\(twoDigits(minuteOfDay % 60)) UTC"
}

/// Binary units with one decimal: "0 B", "1023 B", "1.0 KiB", "12.4 MiB". The
/// value rounds to the nearest tenth with ties to even, as Go's %.1f does, so
/// 1280 bytes (1.25 KiB) is "1.2 KiB". A value that rounds to 1024.0 moves to
/// the next unit. The rounding is exact integer arithmetic, because printf's
/// tie rule depends on the C runtime: the Windows one before Windows 10 version
/// 2004 rounds ties up.
public func formatByteCount(_ byteCount: Int64) -> String {
  if byteCount < 1024 {
    return "\(byteCount) B"
  }
  let units = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB"]
  let roundedTenths = { (unitIndex: Int) -> UInt64 in
    var unitByteCount: UInt64 = 1024
    for _ in 0..<unitIndex {
      unitByteCount *= 1024
    }
    let bytes = UInt64(byteCount)
    // the remainder is below 1024 to the 6th power, so ten times it fits
    let scaledRemainder = bytes % unitByteCount * 10
    var tenths = bytes / unitByteCount * 10 + scaledRemainder / unitByteCount
    let rest = scaledRemainder % unitByteCount
    // up past the half, and at exactly half only to an even last digit
    if unitByteCount < rest * 2 || (unitByteCount == rest * 2 && tenths % 2 == 1) {
      tenths += 1
    }
    return tenths
  }
  var unitIndex = 0
  var tenths = roundedTenths(unitIndex)
  while unitIndex < units.count - 1 && 1024 * 10 <= tenths {
    unitIndex += 1
    tenths = roundedTenths(unitIndex)
  }
  return "\(tenths / 10).\(tenths % 10) \(units[unitIndex])"
}

/// The providing state from the device getters, in this order: stopped unless
/// the provide mode is public; client limit while the SDK holds this client off
/// for its network's client limit; paused while paused; providing once the
/// provider is enabled and its platform carrier is connected; starting
/// otherwise.
public func providerState(
  provideMode: Int64, clientLimitStatus: String, providePaused: Bool, provideEnabled: Bool,
  providerConnected: Bool
) -> ProviderState {
  if provideMode != provideModePublic {
    return .stopped
  }
  if clientLimitStatus == clientLimitStatusExceeded {
    return .clientLimit
  }
  if providePaused {
    return .paused
  }
  if provideEnabled && providerConnected {
    return .providing
  }
  return .starting
}

/// Which owner the effective payout wallet belongs to. The consent scope comes
/// first: a hotkey delegation is network-level, with no client id, but is not
/// the network's wallet. Otherwise by the wallet's client id: this provider's
/// own mapping, the network's wallet, or another provider of the network.
public func payoutWalletScopeOf(
  walletConsentScope: String, walletClientId: String, clientId: String
) -> String {
  if walletConsentScope == snWalletConsentScopeHotkey {
    return payoutWalletScopeHotkey
  }
  if walletClientId.isEmpty {
    return payoutWalletScopeNetwork
  }
  if walletClientId.lowercased() == clientId.lowercased() {
    return payoutWalletScopeProvider
  }
  return payoutWalletScopeAnotherProvider
}

/// The peer of one provider contract, by direction as the SDK's contract
/// screens resolve it: the source of a receive (ingress) contract, the
/// destination of a send (egress) contract. A path without that client id is
/// keyed by its stream id, then by the contract id. "" when the contract names
/// no peer at all.
public func contractPeerKey(_ details: ContractDetails, receive: Bool) -> String {
  // a present id is a valid uuid other than the zero id, in canonical form
  let present = { (id: String?) -> String? in
    guard let id, let uuid = UUID(uuidString: id) else {
      return nil
    }
    let text = uuid.uuidString.lowercased()
    return text == zeroIdString ? nil : text
  }
  if let path = details.contractTransferPath {
    if let peerId = present(receive ? path.sourceId : path.destinationId) {
      return peerId
    }
    if let streamId = present(path.streamId) {
      return "stream:" + streamId
    }
  }
  if let contractId = present(details.contractId) {
    return "contract:" + contractId
  }
  return ""
}

/// The distinct clients that held a contract with this provider since the app
/// started. Safe for concurrent use: the SDK delivers contract details on its
/// own threads, and the status loop reads the count on the app's thread.
public final class ClientsServed {
  private let limit: Int

  private let stateLock = NSLock()
  /// contractPeerKey values
  private var peerKeys = Set<String>()
  private var atLimit = false

  /// An empty count that keeps at most limit distinct peers.
  public init(limit: Int) {
    self.limit = limit
  }

  /// Counts the peer of one provider contract.
  public func add(_ details: ContractDetails, receive: Bool) {
    let peerKey = contractPeerKey(details, receive: receive)
    if peerKey.isEmpty {
      return
    }
    stateLock.lock()
    defer { stateLock.unlock() }
    if peerKeys.contains(peerKey) {
      return
    }
    if limit <= peerKeys.count {
      atLimit = true
      return
    }
    peerKeys.insert(peerKey)
  }

  /// The distinct count, and whether the count stopped at the limit.
  public func count() -> (count: Int, atLimit: Bool) {
    stateLock.lock()
    defer { stateLock.unlock() }
    return (peerKeys.count, atLimit)
  }
}