Developer SDK

Swift examples

Install the SDK · View source on GitHub ↗

embed/Sources/EmbedCore/Status.swift

swift
// The status that every embed example shows, with the exact text rules of
// EMBED_CONTRACT.md ("Status"): the status, the data used this month and the
// running total. These are plain values and functions, so the self-test checks
// them without a network, credentials or the native SDK.

import Foundation

/// The status field's texts. GUI apps show the first two; a console app never
/// prints them.
public let statusSignedOut = "signed out"
public let statusStopped = "stopped"
public let statusClientLimit = "client limit"
public let statusPaused = "paused"
public let statusDataCapReached = "data cap reached"
public let statusConnected = "connected"
public let statusConnecting = "connecting"

/// The data fields' texts before and without a reading.
public let dataChecking = "checking"
public let dataUnavailable = "unavailable"

/// The server refuses the cap read with this message while the team has not
/// enabled Embed for the network (EMBED_CONTRACT.md, "Embed enablement"). The
/// refusal clears the last reading, so both data fields read unavailable.
public let embedNotEnabledMessage = "Embed isn't enabled for this network."
public let dataNoCap = "no cap"

/// The capped_reason values of the cap object.
public let cappedReasonMonthly = "monthly"
public let cappedReasonTotal = "total"

/// The SDK's client limit status values (URNET_CLIENT_LIMIT_STATUS_*): no hold,
/// or the platform disconnected this client for its network's concurrent client
/// limit and the SDK holds off reconnecting until the retry time. Kept here so
/// the status rules need no native SDK; the executable's self-test checks them
/// against the header.
public let clientLimitStatusNone = ""
public let clientLimitStatusExceeded = "client_limit_exceeded"

/// "embed client <client_id>, installation <instance_id>", printed at start.
public func startLine(clientId: String, instanceId: String) -> String {
  return "embed client \(clientId), installation \(instanceId)"
}

/// The GetLicenses app kind that --licenses prints: "apple" on Apple platforms,
/// "windows" on Windows, "linux" elsewhere.
#if os(Windows)
  public let licenseApp = "windows"
#elseif canImport(Darwin)
  public let licenseApp = "apple"
#else
  public let licenseApp = "linux"
#endif

/// Decimal units with one decimal: "0 B", "999 B", "1.0 kB", "12.4 GB". Data
/// plans and the Embed plan's monthly data budget are sold in these units. A
/// value that rounds to 1000.0 moves to the next unit. The arithmetic is exact
/// integer arithmetic, so the text does not depend on float formatting: a tie
/// rounds to even on the exact value, so 1050 bytes is "1.0 kB".
public func formatByteCount(_ byteCount: Int64) -> String {
  let units = ["kB", "MB", "GB", "TB", "PB", "EB"]
  if byteCount < 1000 {
    return "\(byteCount) B"
  }
  let count = UInt64(byteCount)
  var divisor: UInt64 = 1000
  var unitIndex = 0
  while unitIndex + 1 < units.count {
    // the value rounds to 1000.0 or more from 999.95 up; at exactly 999.95 the
    // tie rounds to the even 1000.0
    let whole = count / divisor
    let remainder = count % divisor
    if whole < 999 || (whole == 999 && 20 * remainder < 19 * divisor) {
      break
    }
    divisor *= 1000
    unitIndex += 1
  }
  let scaled = count % divisor * 10
  var tenths = count / divisor * 10 + scaled / divisor
  let remainder = scaled % divisor
  if divisor < 2 * remainder || (divisor == 2 * remainder && tenths % 2 == 1) {
    tenths += 1
  }
  return "\(tenths / 10).\(tenths % 10) \(units[unitIndex])"
}

/// Days since 1970-01-01 of a proleptic Gregorian date (Howard Hinnant's
/// days_from_civil).
func daysFromCivil(year: Int64, month: Int64, day: Int64) -> Int64 {
  let y = year - (month <= 2 ? 1 : 0)
  let era = (y >= 0 ? y : y - 399) / 400
  let yearOfEra = y - era * 400
  let dayOfYear = (153 * (month + (month > 2 ? -3 : 9)) + 2) / 5 + day - 1
  let dayOfEra = yearOfEra * 365 + yearOfEra / 4 - yearOfEra / 100 + dayOfYear
  return era * 146097 + dayOfEra - 719468
}

/// The date of a day since 1970-01-01 (Howard Hinnant's civil_from_days).
func civilFromDays(_ days: Int64) -> (year: Int64, month: Int64, day: Int64) {
  let z = days + 719468
  let era = (z >= 0 ? z : z - 146096) / 146097
  let dayOfEra = z - era * 146097
  let yearOfEra = (dayOfEra - dayOfEra / 1460 + dayOfEra / 36524 - dayOfEra / 146096) / 365
  let dayOfYear = dayOfEra - (365 * yearOfEra + yearOfEra / 4 - yearOfEra / 100)
  let monthIndex = (5 * dayOfYear + 2) / 153
  let day = dayOfYear - (153 * monthIndex + 2) / 5 + 1
  let month = monthIndex < 10 ? monthIndex + 3 : monthIndex - 9
  return (yearOfEra + era * 400 + (month <= 2 ? 1 : 0), month, day)
}

/// An RFC 3339 time as unix seconds in UTC, with whether its fraction is above
/// zero: "2026-11-01T00:00:00Z", or with a fraction and an offset such as
/// "2026-10-31T19:00:00.5-05:00".
func parseRfc3339(_ text: String) -> (unixSeconds: Int64, hasFraction: Bool)? {
  let bytes = Array(text.utf8)
  func digits(_ start: Int, _ count: Int) -> Int64? {
    if bytes.count < start + count {
      return nil
    }
    var value: Int64 = 0
    for byte in bytes[start..<start + count] {
      guard UInt8(ascii: "0") <= byte && byte <= UInt8(ascii: "9") else {
        return nil
      }
      value = value * 10 + Int64(byte - UInt8(ascii: "0"))
    }
    return value
  }
  guard bytes.count >= 20, bytes[4] == UInt8(ascii: "-"), bytes[7] == UInt8(ascii: "-"),
    bytes[10] == UInt8(ascii: "T") || bytes[10] == UInt8(ascii: "t"),
    bytes[13] == UInt8(ascii: ":"), bytes[16] == UInt8(ascii: ":"),
    let year = digits(0, 4), let month = digits(5, 2), let day = digits(8, 2),
    let hour = digits(11, 2), let minute = digits(14, 2), let second = digits(17, 2)
  else {
    return nil
  }
  let monthDays: [Int64] = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
  let leap = year % 4 == 0 && (year % 100 != 0 || year % 400 == 0)
  if month < 1 || 12 < month || day < 1 || monthDays[Int(month) - 1] < day
    || (month == 2 && day == 29 && !leap) || 23 < hour || 59 < minute || 59 < second
  {
    return nil
  }
  var index = 19
  var hasFraction = false
  if index < bytes.count && bytes[index] == UInt8(ascii: ".") {
    index += 1
    guard index < bytes.count, UInt8(ascii: "0") <= bytes[index], bytes[index] <= UInt8(ascii: "9")
    else {
      return nil
    }
    while index < bytes.count && UInt8(ascii: "0") <= bytes[index]
      && bytes[index] <= UInt8(ascii: "9")
    {
      if bytes[index] != UInt8(ascii: "0") {
        hasFraction = true
      }
      index += 1
    }
  }
  let rest = bytes[index...]
  var offsetSeconds: Int64 = 0
  if rest.count == 1 && (rest.first == UInt8(ascii: "Z") || rest.first == UInt8(ascii: "z")) {
    offsetSeconds = 0
  } else if rest.count == 6, rest.first == UInt8(ascii: "+") || rest.first == UInt8(ascii: "-"),
    bytes[index + 3] == UInt8(ascii: ":"), let offsetHour = digits(index + 1, 2),
    let offsetMinute = digits(index + 4, 2), offsetHour <= 23, offsetMinute <= 59
  {
    offsetSeconds = offsetHour * 3600 + offsetMinute * 60
    if rest.first == UInt8(ascii: "-") {
      offsetSeconds = -offsetSeconds
    }
  } else {
    return nil
  }
  let unixSeconds =
    daysFromCivil(year: year, month: month, day: day) * 86400 + hour * 3600 + minute * 60 + second
    - offsetSeconds
  return (unixSeconds, hasFraction)
}

/// Two digits, zero padded.
func twoDigits(_ value: Int64) -> String {
  return value < 10 ? "0\(value)" : "\(value)"
}

/// "resets YYYY-MM-DD HH:MM UTC" for the monthly cap's period end, in UTC with
/// the seconds rounded up to the next whole minute, so the shown time is never
/// before the real reset. nil when the time does not parse.
public func resetText(_ periodEnd: String) -> String? {
  guard let parsed = parseRfc3339(periodEnd) else {
    return nil
  }
  let (unixSeconds, hasFraction) = parsed
  var minutes = unixSeconds / 60 - (unixSeconds % 60 < 0 ? 1 : 0)
  if unixSeconds - minutes * 60 != 0 || hasFraction {
    minutes += 1
  }
  let days = minutes / 1440 - (minutes % 1440 < 0 ? 1 : 0)
  let minuteOfDay = minutes - days * 1440
  let (year, month, day) = civilFromDays(days)
  var yearText = "\(year)"
  while yearText.count < 4 {
    yearText = "0" + yearText
  }
  return
    "resets \(yearText)-\(twoDigits(month))-\(twoDigits(day)) \(twoDigits(minuteOfDay / 60)):\(twoDigits(minuteOfDay % 60)) UTC"
}

/// "client limit, retry at HH:MM UTC": the retry time (unix milliseconds)
/// rounded up to the next whole minute in UTC; a retry time of 0 shows "client
/// limit". Unix time has no leap seconds, so every day is 1440 minutes.
public func clientLimitText(retryTime: Int64) -> String {
  if retryTime <= 0 {
    return statusClientLimit
  }
  let minuteMillis: Int64 = 60 * 1000
  let retryMinute = retryTime / minuteMillis + (retryTime % minuteMillis != 0 ? 1 : 0)
  let minuteOfDay = retryMinute % (24 * 60)
  return "\(statusClientLimit), retry at \(twoDigits(minuteOfDay / 60)):\(twoDigits(minuteOfDay % 60)) UTC"
}

/// One cap object (EMBED_CONTRACT.md, "The cap object"), read. A nil limit is no
/// cap; an absent used count is 0.
public struct Cap: Equatable {
  public var monthlyByteLimit: Int64?
  public var monthlyUsedByteCount: Int64
  /// RFC 3339, as the server wrote it; empty when absent
  public var monthlyPeriodEnd: String
  public var totalByteLimit: Int64?
  public var totalUsedByteCount: Int64
  public var capped: Bool
  /// monthly, total, empty, or another value
  public var cappedReason: String

  /// A cap object with the given fields.
  public init(
    monthlyByteLimit: Int64? = nil, monthlyUsedByteCount: Int64 = 0, monthlyPeriodEnd: String = "",
    totalByteLimit: Int64? = nil, totalUsedByteCount: Int64 = 0, capped: Bool = false,
    cappedReason: String = ""
  ) {
    self.monthlyByteLimit = monthlyByteLimit
    self.monthlyUsedByteCount = monthlyUsedByteCount
    self.monthlyPeriodEnd = monthlyPeriodEnd
    self.totalByteLimit = totalByteLimit
    self.totalUsedByteCount = totalUsedByteCount
    self.capped = capped
    self.cappedReason = cappedReason
  }
}

/// A JSON value of any kind whose content is not read: decoding it only shows
/// that the member is present and not null.
struct PresentValue: Decodable {
  /// Accepts any value.
  init(from decoder: Decoder) throws {}
}

/// The cap object's JSON. A field of the wrong type fails to decode; null and
/// absent are the same.
struct CapObject: Decodable {
  var monthlyByteLimit: Int64?
  var monthlyUsedByteCount: Int64?
  var monthlyPeriodEnd: String?
  var totalByteLimit: Int64?
  var totalUsedByteCount: Int64?
  var capped: Bool?
  var cappedReason: String?
  var error: PresentValue?

  /// The API's field names.
  enum CodingKeys: String, CodingKey {
    case monthlyByteLimit = "monthly_byte_limit"
    case monthlyUsedByteCount = "monthly_used_byte_count"
    case monthlyPeriodEnd = "monthly_period_end"
    case totalByteLimit = "total_byte_limit"
    case totalUsedByteCount = "total_used_byte_count"
    case capped
    case cappedReason = "capped_reason"
    case error
  }

  /// The cap it holds; nil for an error answer.
  var cap: Cap? {
    if error != nil {
      return nil
    }
    return Cap(
      monthlyByteLimit: monthlyByteLimit, monthlyUsedByteCount: monthlyUsedByteCount ?? 0,
      monthlyPeriodEnd: monthlyPeriodEnd ?? "", totalByteLimit: totalByteLimit,
      totalUsedByteCount: totalUsedByteCount ?? 0, capped: capped ?? false,
      cappedReason: cappedReason ?? "")
  }
}

/// Reads a cap object. nil for anything else: not an object, an error answer,
/// or a field of the wrong type.
public func parseCap(_ data: Data) -> Cap? {
  guard let object = try? JSONDecoder().decode(CapObject.self, from: data) else {
    return nil
  }
  return object.cap
}

/// Whether an answer is the Embed-not-enabled refusal,
/// {"error": {"message": "Embed isn't enabled for this network."}}.
public func capNotEnabled(_ data: Data) -> Bool {
  struct Refusal: Decodable {
    struct Body: Decodable {
      var message: String?
    }
    var error: Body?
  }
  return (try? JSONDecoder().decode(Refusal.self, from: data))?.error?.message == embedNotEnabledMessage
}

/// What the data fields show: no reading yet, the first reading failed (or the
/// Embed-not-enabled refusal cleared the reading), or the latest reading.
public enum CapsState: Equatable {
  case checking
  case unavailable
  case read(Cap)
}

/// The cap readings. A reading replaces the last one; a failure before any
/// reading shows unavailable, and a later failure keeps the last reading.
public struct Caps: Equatable {
  public private(set) var state: CapsState = .checking

  /// No reading yet.
  public init() {}

  /// Applies one reading; nil is a failed reading.
  public mutating func apply(_ reading: Cap?) {
    if let reading {
      state = .read(reading)
    } else if state == .checking {
      state = .unavailable
    }
  }

  /// The Embed-not-enabled refusal clears the last reading: both data fields
  /// read unavailable, and the status rules see no cap reading.
  public mutating func clear() {
    state = .unavailable
  }

  /// Applies the outcome of a cap read: its reading, the Embed-not-enabled refusal, which clears
  /// the last reading, or another failure, which keeps it.
  public mutating func record(_ reading: Cap?, notEnabled: Bool) {
    if notEnabled {
      clear()
    } else {
      apply(reading)
    }
  }

  /// The latest reading, if any.
  public var cap: Cap? {
    if case .read(let cap) = state {
      return cap
    }
    return nil
  }
}

/// One data field: checking, unavailable, no cap for a nil limit (never a used
/// count), or "<used> of <limit>".
public func dataField(_ caps: Caps, monthly: Bool) -> String {
  switch caps.state {
  case .checking:
    return dataChecking
  case .unavailable:
    return dataUnavailable
  case .read(let cap):
    guard let limit = monthly ? cap.monthlyByteLimit : cap.totalByteLimit else {
      return dataNoCap
    }
    let used = monthly ? cap.monthlyUsedByteCount : cap.totalUsedByteCount
    return "\(formatByteCount(used)) of \(formatByteCount(limit))"
  }
}

/// The inputs of the status rules.
public struct StatusInput {
  /// GUI apps: before start or after stop; a console app is always started
  public var started = true
  /// GUI apps: after an auth logout or a token server refusal
  public var signedOut = false
  /// clientLimitStatusNone or clientLimitStatusExceeded
  public var clientLimitStatus = clientLimitStatusNone
  /// the end of the client limit hold in unix milliseconds, 0 without one
  public var clientLimitRetryTime: Int64 = 0
  public var caps = Caps()
  /// ProviderStateAdded of the window status, 0 before the window exists
  public var providersAdded: Int64 = 0

  /// The inputs with the given values.
  public init(
    started: Bool = true, signedOut: Bool = false, clientLimitStatus: String = clientLimitStatusNone,
    clientLimitRetryTime: Int64 = 0, caps: Caps = Caps(), providersAdded: Int64 = 0
  ) {
    self.started = started
    self.signedOut = signedOut
    self.clientLimitStatus = clientLimitStatus
    self.clientLimitRetryTime = clientLimitRetryTime
    self.caps = caps
    self.providersAdded = providersAdded
  }
}

/// The status: the first rule that applies, in the contract's order.
public func statusText(_ input: StatusInput) -> String {
  if input.signedOut {
    return statusSignedOut
  }
  if !input.started {
    return statusStopped
  }
  if input.clientLimitStatus == clientLimitStatusExceeded {
    return clientLimitText(retryTime: input.clientLimitRetryTime)
  }
  if let cap = input.caps.cap, cap.capped {
    // a cap of 0, the one capped_reason names, is a pause
    let paused =
      (cap.cappedReason == cappedReasonMonthly && cap.monthlyByteLimit == 0)
      || (cap.cappedReason == cappedReasonTotal && cap.totalByteLimit == 0)
    if paused {
      return statusPaused
    }
    if cap.cappedReason == cappedReasonMonthly, let reset = resetText(cap.monthlyPeriodEnd) {
      return "\(statusDataCapReached), \(reset)"
    }
    // a total cap, a monthly cap without a readable period end, or an unknown
    // reason
    return statusDataCapReached
  }
  return input.providersAdded >= 1 ? statusConnected : statusConnecting
}

/// The console status line, for example
/// "status: connected | data this month: 1.2 GB of 5.0 GB | data total: no cap".
public func statusLine(_ input: StatusInput) -> String {
  return
    "status: \(statusText(input)) | data this month: \(dataField(input.caps, monthly: true)) | data total: \(dataField(input.caps, monthly: false))"
}