Developer SDK

C# examples

Install the SDK · View source on GitHub ↗

embed/Session.cs

c#
// The embedded device over the SDK's C ABI: the network space manager, the
// local device with the installation's client JWT, and the listeners that feed
// its status (EMBED_CONTRACT.md, "App lifecycle"). The device routes only the
// traffic the app sends through it; it does not provide.
//
// C ABI callbacks run on SDK threads and the marshaller copies their strings
// before they run. They only record what they carry under a lock and leave the
// work (saving the token, reading the caps, stopping) to the status loop on
// the app's thread, within a second. They never throw, because an exception
// must not unwind into native code.
using System.Diagnostics;
using URnetwork.SDK;

/// One run of the embedded device. The constructor starts the device; Run
/// shows the status until a stop; Dispose closes the subscriptions, the device
/// and the manager. Only the callbacks run concurrently with the app's thread.
internal sealed class EmbedSession : IDisposable {
  // How often the status is read, and the longest gap between status lines.
  private static readonly TimeSpan StatusPollInterval = TimeSpan.FromSeconds(1);
  private static readonly TimeSpan StatusRepeatInterval = TimeSpan.FromSeconds(60);
  // How often the caps are read, and how soon after a contract status change.
  private static readonly TimeSpan CapReadInterval = TimeSpan.FromMinutes(5);
  private static readonly TimeSpan CapReadAfterContractChange = TimeSpan.FromSeconds(1);

  // The device description and spec recorded for this installation's device.
  private const string DeviceDescription = "C# embed example";
  private const string DeviceSpec = "urnetwork-examples/csharp-embed";
  private const string AppVersion = "1";

  // The ur.network main network space, as the integration helper creates it.
  private const string NetworkSpaceKeyJson = """{"host_name":"ur.network","env_name":"main"}""";
  private const string NetworkSpaceValuesJson = """{"migration_host_name":"bringyour.com"}""";
  // The destination of the app's own traffic: the best available location.
  private const string BestAvailableJson = """{"connect_location_id":{"best_available":true}}""";

  // The SDK can call back after Dispose. Every callback delegate stays here
  // for the life of the process, so no native call reaches a collected
  // delegate.
  private static readonly List<Delegate> CallbackRoots = [];

  private readonly EmbedSettings settings;
  private readonly TextWriter output;
  private readonly TextWriter error;
  private readonly Raw.urnet_jwt_refresh_cb jwtRefreshed;
  private readonly Raw.urnet_auth_logout_cb authLogout;
  private readonly Raw.urnet_contract_status_change_cb contractStatusChanged;
  // listener subscription handles, closed and released by Dispose
  private readonly List<ulong> subs = [];
  private Handle? manager;
  private Handle? space;
  private Handle? api;
  private Device? device;
  private bool disposed;

  // owned by the app's thread: the client JWT that cap reads present, the
  // cap readings so far, and the cap read in flight
  private string clientJwt;
  private readonly CapReadings capReadings = new();
  private Task<CapRead>? capRead;
  private TimeSpan nextCapReadTime;

  private readonly object stateLock = new();
  // the newest refreshed client JWT that is not saved yet
  private string? unsavedClientJwt;
  // set when the server rejected the client credential
  private bool loggedOut;
  // set when the contract status changed since the status loop last looked
  private bool contractStatusChangedPending;

  private readonly Stopwatch clock = Stopwatch.StartNew();

  /// Creates the local device with the installation's client JWT, adds the
  /// listeners and sets the connect location to best available. The token
  /// server's cap reading, when there is one, counts as the first.
  public EmbedSession(EmbedSettings settings, ClientCredential credential, TextWriter output,
                      TextWriter error) {
    this.settings = settings;
    this.output = output;
    this.error = error;
    clientJwt = credential.ClientJwt;
    jwtRefreshed = (_, refreshedJwt) => {
      lock (stateLock) {
        unsavedClientJwt = refreshedJwt;
      }
    };
    authLogout = _ => {
      lock (stateLock) {
        loggedOut = true;
      }
    };
    contractStatusChanged = (_, _) => {
      lock (stateLock) {
        contractStatusChangedPending = true;
      }
    };
    lock (CallbackRoots) {
      CallbackRoots.AddRange([jwtRefreshed, authLogout, contractStatusChanged]);
    }
    if (credential.FirstCap != null) {
      capReadings.Record(credential.FirstCap);
      nextCapReadTime = CapReadInterval;
    }
    try {
      manager = new Handle(Raw.urnet_new_network_space_manager_no_storage());
      space = new Handle(Raw.urnet_network_space_manager_update_network_space_values(
          manager.Value, NetworkSpaceKeyJson, NetworkSpaceValuesJson));
      api = new Handle(Raw.urnet_network_space_get_api(space.Value));
      Raw.urnet_api_set_by_jwt(api.Value, clientJwt);
      // no device rpc; the provide mode stays at its default: an embed app
      // does not provide
      ulong handle = Raw.urnet_new_device_local_with_defaults(
          space.Value, clientJwt, DeviceDescription, DeviceSpec, AppVersion,
          settings.InstanceId, 0, out IntPtr createError);
      string? message = Sdk.TakeString(createError);
      if (handle == 0) {
        throw new IOException(message ?? "the sdk did not create the device");
      }
      device = new Device(handle);
      AddSub(Raw.urnet_device_add_jwt_refresh_listener(handle, jwtRefreshed, IntPtr.Zero));
      AddSub(Raw.urnet_device_add_auth_logout_listener(handle, authLogout, IntPtr.Zero));
      AddSub(Raw.urnet_device_add_contract_status_change_listener(
          handle, contractStatusChanged, IntPtr.Zero));
      Raw.urnet_device_set_connect_location(handle, BestAvailableJson);
    } catch {
      Dispose();
      throw;
    }
  }

  /// Keeps a listener subscription for Dispose. 0 means the SDK did not add the
  /// listener.
  private void AddSub(ulong sub) {
    if (sub == 0) {
      throw new IOException("the sdk did not add a device listener");
    }
    subs.Add(sub);
  }

  /// The status line from the device getters and the latest cap reading.
  public string StatusLine() {
    ulong handle = device!.Value;
    var (clientLimitStatus, clientLimitRetryTime) = StatusRules.ParseClientLimitStatus(
        Sdk.TakeString(Raw.urnet_device_get_client_limit_status(handle)));
    int providersAdded = StatusRules.ProvidersAdded(
        Sdk.TakeString(Raw.urnet_device_get_window_status(handle)));
    string status = StatusRules.Status(started: true, signedOut: false, clientLimitStatus,
                                       clientLimitRetryTime, capReadings.Latest, providersAdded);
    return StatusRules.StatusLine(status, StatusRules.DataField(capReadings, monthly: true),
                                  StatusRules.DataField(capReadings, monthly: false));
  }

  /// Prints status lines until stop is cancelled (exit 0) or the server
  /// rejects the credential (exit 78), and returns the process exit code. It
  /// also does the work that the callbacks handed over.
  public int Run(CancellationToken stop) {
    string? lastLine = null;
    TimeSpan lastPrintTime = TimeSpan.Zero;
    while (true) {
      SaveRefreshedClientJwt();
      SyncCaps();
      string line = StatusLine();
      TimeSpan now = clock.Elapsed;
      if (line != lastLine || StatusRepeatInterval <= now - lastPrintTime) {
        output.WriteLine(line);
        lastLine = line;
        lastPrintTime = now;
      }
      if (stop.WaitHandle.WaitOne(StatusPollInterval)) {
        return Program.ExitStopped;
      }
      bool credentialRejected;
      lock (stateLock) {
        credentialRejected = loggedOut;
      }
      if (credentialRejected) {
        error.WriteLine("the server rejected the client credential; sign in again to get a new client JWT from your backend");
        return Program.ExitConfig;
      }
    }
  }

  /// Applies a finished cap read, and starts the next one at start, every 5
  /// minutes and soon after a contract status change. One read at a time; a
  /// read runs on the thread pool so the status keeps its pace.
  private void SyncCaps() {
    TimeSpan now = clock.Elapsed;
    bool contractChanged;
    lock (stateLock) {
      contractChanged = contractStatusChangedPending;
      contractStatusChangedPending = false;
    }
    if (contractChanged && now + CapReadAfterContractChange < nextCapReadTime) {
      nextCapReadTime = now + CapReadAfterContractChange;
    }
    if (capRead is { IsCompleted: true } finished) {
      // the Embed-not-enabled refusal clears the last reading; another failure
      // keeps it
      capReadings.RecordRead(finished.IsCompletedSuccessfully ? finished.Result : new CapRead(null));
      capRead = null;
    }
    if (capRead == null && nextCapReadTime <= now) {
      capRead = CapClient.ReadAsync(settings.ApiOrigin, clientJwt);
      nextCapReadTime = now + CapReadInterval;
    }
  }

  /// Keeps the refreshed credential, so the next start and the next cap read
  /// use a valid token.
  private void SaveRefreshedClientJwt() {
    string? refreshedJwt;
    lock (stateLock) {
      refreshedJwt = unsavedClientJwt;
      unsavedClientJwt = null;
    }
    if (string.IsNullOrWhiteSpace(refreshedJwt)) {
      return;
    }
    clientJwt = refreshedJwt.Trim();
    try {
      StateFiles.SaveClientJwt(settings.StateDir, clientJwt);
    } catch (EmbedConfigException e) {
      // never print the token itself
      error.WriteLine($"could not save the refreshed client credential: {e.Message}");
    }
  }

  /// Closes the subscriptions, closes the device and then the manager, and
  /// releases every handle. Also saves a refreshed credential that arrived
  /// after the status loop's last pass.
  public void Dispose() {
    if (disposed) {
      return;
    }
    disposed = true;
    foreach (ulong sub in subs) {
      Raw.urnet_sub_close(sub);
      Raw.urnet_release(sub);
    }
    subs.Clear();
    // closes the device, then releases its handle
    device?.Dispose();
    api?.Dispose();
    space?.Dispose();
    if (manager != null) {
      Raw.urnet_network_space_manager_close(manager.Value);
      manager.Dispose();
    }
    SaveRefreshedClientJwt();
  }
}