Developer SDK

C# examples

Install the SDK · View source on GitHub ↗

embed/Status.cs

c#
// The status that every embed example shows, with the exact text rules of
// EMBED_CONTRACT.md ("Status"): the status field, the data used this month and
// the running total. The SDK hands the device values over as C ABI JSON with
// the Go field names; the readers and rules here are pure managed code that
// never throws on bad input, so the self-test checks them without the native
// SDK runtime, a network or credentials.
using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;

/// The status rules and the texts they produce.
internal static class StatusRules {
  // GUI and Android only: after an auth logout or a 401 or 409 from the token
  // server, until started again
  public const string StatusSignedOut = "signed out";
  // GUI and Android only: before start or after stop
  public const string StatusStopped = "stopped";
  // the platform disconnected this client for its network's client limit, and
  // the SDK holds off reconnecting until the retry time
  public const string StatusClientLimit = "client limit";
  // a cap of 0 is reached
  public const string StatusPaused = "paused";
  public const string StatusDataCapReached = "data cap reached";
  public const string StatusConnected = "connected";
  public const string StatusConnecting = "connecting";

  // a data field before the first cap reading finishes
  public const string DataChecking = "checking";
  // a data field when the first cap reading failed
  public const string DataUnavailable = "unavailable";
  // a data field whose cap is not set
  public const string DataNoCap = "no cap";

  public const string CappedReasonMonthly = "monthly";
  public const string CappedReasonTotal = "total";
  // URNET_CLIENT_LIMIT_STATUS_*
  public const string ClientLimitStatusNone = "";
  public const string ClientLimitStatusExceeded = "client_limit_exceeded";

  private static readonly Regex Rfc3339 = new(
      @"\A(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?([Zz]|[+-]\d{2}:\d{2})\z");

  /// Decimal units with one decimal: "0 B", "999 B", "1.0 kB", "5.0 GB". Data
  /// plans are sold in decimal units. The tenths round half to even on the
  /// exact integer, never on a binary fraction (1050 bytes is "1.0 kB", 1150
  /// bytes "1.2 kB"), and a value that rounds to 1000.0 moves to the next unit
  /// (999999 bytes is "1.0 MB").
  public static string FormatByteCount(long byteCount) {
    if (byteCount < 1000) {
      return byteCount.ToString(CultureInfo.InvariantCulture) + " B";
    }
    string[] units = ["kB", "MB", "GB", "TB", "PB", "EB"];
    // the bytes in a tenth of the unit
    long tenth = 100;
    for (int unitIndex = 0;; unitIndex += 1) {
      long tenths = byteCount / tenth;
      long remainder = byteCount % tenth;
      if (tenth < 2 * remainder || (2 * remainder == tenth && tenths % 2 == 1)) {
        tenths += 1;
      }
      if (tenths < 10000 || unitIndex == units.Length - 1) {
        return FormattableString.Invariant($"{tenths / 10}.{tenths % 10} {units[unitIndex]}");
      }
      tenth *= 1000;
    }
  }

  /// The line the console apps print once the device runs (EMBED_CONTRACT.md,
  /// "Status").
  public static string StartLine(string clientId, string instanceId) {
    return $"embed client {clientId}, installation {instanceId}";
  }

  /// The kind of app whose licenses --licenses prints: "apple" on macOS,
  /// "windows" on Windows, "linux" elsewhere.
  public static string LicenseApp(bool windows, bool macOs) {
    return windows ? "windows" : macOs ? "apple" : "linux";
  }

  /// The client limit text: "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, or
  /// one after the year 9999, shows "client limit".
  public static string ClientLimitText(long clientLimitRetryTime) {
    if (clientLimitRetryTime <= 0) {
      return StatusClientLimit;
    }
    const long minuteMillis = 60 * 1000;
    long retryMinute = clientLimitRetryTime / minuteMillis +
                       (clientLimitRetryTime % minuteMillis == 0 ? 0 : 1);
    if (DateTimeOffset.MaxValue.ToUnixTimeSeconds() / 60 < retryMinute) {
      return StatusClientLimit;
    }
    var retryTime = DateTimeOffset.FromUnixTimeSeconds(retryMinute * 60);
    return $"{StatusClientLimit}, retry at {retryTime.ToString("HH:mm", CultureInfo.InvariantCulture)} UTC";
  }

  /// "resets 2026-11-01 00:00 UTC" for a monthly_period_end in RFC 3339, in UTC
  /// with the seconds rounded up to the next whole minute; null when it does
  /// not parse (or is after the year 9999).
  public static string? ResetText(string? monthlyPeriodEnd) {
    if (monthlyPeriodEnd == null) {
      return null;
    }
    Match match = Rfc3339.Match(monthlyPeriodEnd);
    if (!match.Success) {
      return null;
    }
    int Group(int index) => int.Parse(match.Groups[index].Value, CultureInfo.InvariantCulture);
    try {
      TimeSpan offset = TimeSpan.Zero;
      string zone = match.Groups[8].Value;
      if (zone is not ("Z" or "z")) {
        int sign = zone[0] == '-' ? -1 : 1;
        offset = new TimeSpan(sign * int.Parse(zone[1..3], CultureInfo.InvariantCulture),
                              sign * int.Parse(zone[4..6], CultureInfo.InvariantCulture), 0);
      }
      DateTimeOffset end = new DateTimeOffset(Group(1), Group(2), Group(3), Group(4), Group(5),
                                              Group(6), offset)
                               .ToUniversalTime();
      bool fraction = match.Groups[7].Success && match.Groups[7].Value.Any(c => c != '0');
      DateTimeOffset minute = end.AddSeconds(-end.Second);
      if (end.Second != 0 || fraction) {
        minute = minute.AddMinutes(1);
      }
      return $"resets {minute.ToString("yyyy-MM-dd HH:mm", CultureInfo.InvariantCulture)} UTC";
    } catch (ArgumentException) {
      // an invalid date or offset, or a time after the year 9999
      return null;
    }
  }

  /// The status field: the first rule that applies. started and signedOut
  /// matter to GUI apps only; a console app passes started and not signed out.
  /// latestCap is the latest successful cap reading, null before one.
  public static string Status(bool started, bool signedOut, string clientLimitStatus,
                              long clientLimitRetryTime, DataCap? latestCap,
                              int providersAdded) {
    if (signedOut) {
      return StatusSignedOut;
    }
    if (!started) {
      return StatusStopped;
    }
    if (clientLimitStatus == ClientLimitStatusExceeded) {
      return ClientLimitText(clientLimitRetryTime);
    }
    if (latestCap is { Capped: true } cap) {
      // the cap that capped_reason names; an unknown reason names none
      long? reachedLimit = cap.CappedReason switch {
        CappedReasonMonthly => cap.MonthlyByteLimit,
        CappedReasonTotal => cap.TotalByteLimit,
        _ => null,
      };
      if (reachedLimit == 0) {
        return StatusPaused;
      }
      if (cap.CappedReason == CappedReasonMonthly && ResetText(cap.MonthlyPeriodEnd) is { } reset) {
        return $"{StatusDataCapReached}, {reset}";
      }
      return StatusDataCapReached;
    }
    if (1 <= providersAdded) {
      return StatusConnected;
    }
    return StatusConnecting;
  }

  /// A data field: "checking", "unavailable", "no cap" or "<used> of <limit>".
  /// A field without a cap never shows a used count.
  public static string DataField(CapReadings readings, bool monthly) {
    if (readings.Latest is not { } cap) {
      return readings.Attempted ? DataUnavailable : DataChecking;
    }
    long? limit = monthly ? cap.MonthlyByteLimit : cap.TotalByteLimit;
    if (limit is not long byteLimit) {
      return DataNoCap;
    }
    long used = monthly ? cap.MonthlyUsedByteCount : cap.TotalUsedByteCount;
    return $"{FormatByteCount(used)} of {FormatByteCount(byteLimit)}";
  }

  /// The console status line.
  public static string StatusLine(string status, string monthly, string total) {
    return $"status: {status} | data this month: {monthly} | data total: {total}";
  }

  /// The client limit status of urnet_device_get_client_limit_status. NULL,
  /// which the call returns only when it cannot run, reads as no limit.
  public static (string Status, long RetryTime) ParseClientLimitStatus(string? json) {
    if (ParseObject(json) is not { } status) {
      return (Status: ClientLimitStatusNone, RetryTime: 0);
    }
    return (Status: StringProperty(status, "Status"), RetryTime: Int64Property(status, "RetryTime"));
  }

  /// ProviderStateAdded of urnet_device_get_window_status: the providers in
  /// the window. NULL before the window exists reads as 0.
  public static int ProvidersAdded(string? windowStatusJson) {
    if (ParseObject(windowStatusJson) is not { } windowStatus) {
      return 0;
    }
    long added = Int64Property(windowStatus, "ProviderStateAdded");
    return (int)Math.Clamp(added, 0, int.MaxValue);
  }

  /// The root object of a C ABI JSON value; null for NULL, JSON null, another
  /// kind of value, or text that does not parse.
  private static JsonElement? ParseObject(string? json) {
    if (json == null) {
      return null;
    }
    try {
      using var document = JsonDocument.Parse(json);
      if (document.RootElement.ValueKind != JsonValueKind.Object) {
        return null;
      }
      return document.RootElement.Clone();
    } catch (Exception e) when (e is JsonException or ArgumentException) {
      return null;
    }
  }

  /// A string property, or "" when it is missing or not a string.
  private static string StringProperty(JsonElement element, string name) {
    if (element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String) {
      return value.GetString() ?? "";
    }
    return "";
  }

  /// An integer property, or 0 when it is missing or not an integer.
  private static long Int64Property(JsonElement element, string name) {
    if (element.TryGetProperty(name, out var value) &&
        value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long number)) {
      return number;
    }
    return 0;
  }
}