Developer SDK

C# examples

Install the SDK · View source on GitHub ↗

provider/Session.cs

c#
// A running provider over the SDK's C ABI: the network space manager, the
// provider device with the installation's identity, and the listeners that
// feed its status (PROVIDER_CONTRACT.md, "App lifecycle"). 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: the contract listeners count the
// peer at once, the others leave the work (saving the token, reading the
// wallet, 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 System.Runtime.InteropServices;
using System.Text;
using URnetwork.SDK;

/// One run of the provider. The constructor starts providing; Run shows the
/// status until a stop; Dispose stops providing and releases the device, then
/// the manager. Only the callbacks run concurrently with the app's thread.
internal sealed class ProviderSession : 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 payout wallet is read again. The wallet is fixed; a reread
  // shows a mapping that the backend completes while the provider runs.
  private static readonly TimeSpan WalletSyncInterval = TimeSpan.FromMinutes(10);

  // The device description and spec recorded for this installation's device.
  private const string DeviceDescription = "C# provider example";
  private const string DeviceSpec = "urnetwork-examples/csharp-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.
  private const bool ProvideExtenderEnabled = true;
  private const bool DefaultProvideExtender = true;

  // 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 SDK can call back after Dispose, for example with a wallet read that
  // the device close cancels. Every callback delegate stays here for the life
  // of the process, as in the messages example, so no native call reaches a
  // collected delegate.
  private static readonly List<Delegate> CallbackRoots = [];

  private readonly ProviderConfig config;
  private readonly TextWriter output;
  private readonly TextWriter error;
  private readonly ServedClients servedClients = new(StatusRules.ClientsServedLimit);
  private readonly Raw.urnet_jwt_refresh_cb jwtRefreshed;
  private readonly Raw.urnet_auth_logout_cb authLogout;
  private readonly Raw.urnet_contract_details_change_cb ingressContractDetailsChanged;
  private readonly Raw.urnet_contract_details_change_cb egressContractDetailsChanged;
  private readonly Raw.urnet_sn_get_wallet_cb walletRead;
  // 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 started;
  private bool disposed;

  // the payout wallet that the status shows, kept by the app's thread: a
  // coldkey address, or StatusRules.PayoutWalletChecking,
  // PayoutWalletUnavailable or PayoutWalletNotSet
  private string payoutWallet = StatusRules.PayoutWalletChecking;
  private string payoutWalletScope = "";

  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;
  // whether wallet reads finished since the status loop last looked, and
  // whether one of them succeeded
  private bool walletReadPending;
  private bool walletReadSucceeded;

  /// 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.
  public ProviderSession(ProviderConfig config, TextWriter output,
                         TextWriter error) {
    this.config = config;
    this.output = output;
    this.error = error;
    jwtRefreshed = (_, clientJwt) => {
      lock (stateLock) {
        unsavedClientJwt = clientJwt;
      }
    };
    authLogout = _ => {
      lock (stateLock) {
        loggedOut = true;
      }
    };
    ingressContractDetailsChanged = (_, contractDetailsJson) =>
        servedClients.Add(contractDetailsJson, receive: true);
    egressContractDetailsChanged = (_, contractDetailsJson) =>
        servedClients.Add(contractDetailsJson, receive: false);
    walletRead = (_, resultJson, errorText) => {
      bool succeeded = StatusRules.WalletReadSucceeded(resultJson, errorText);
      lock (stateLock) {
        walletReadPending = true;
        walletReadSucceeded |= succeeded;
      }
    };
    lock (CallbackRoots) {
      CallbackRoots.AddRange([jwtRefreshed, authLogout, ingressContractDetailsChanged,
                              egressContractDetailsChanged, walletRead]);
    }
    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, config.ClientJwt);
      device = NewDevice(space.Value, config);
      ulong handle = device.Value;
      if (config.Identity == null) {
        SaveNewIdentity(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_provider_ingress_contract_details_change_listener(
          handle, ingressContractDetailsChanged, IntPtr.Zero));
      AddSub(Raw.urnet_device_add_provider_egress_contract_details_change_listener(
          handle, egressContractDetailsChanged, IntPtr.Zero));
      Raw.urnet_device_set_provide_mode(handle, StatusRules.ProvideModePublic);
      SyncWallet();
      started = true;
    } catch {
      Dispose();
      throw;
    }
  }

  /// The key material handle that recreates the device's identity, which the
  /// caller releases. 0 without an identity (the first run, or another
  /// client's identity): the device then makes a new identity. That case
  /// touches no native code, so the self-test checks it.
  public static ulong NewKeyMaterial(ProviderIdentity? identity) {
    if (identity == null) {
      return 0;
    }
    using var clientKeySeed = new PinnedBytes(identity.ClientKeySeed ?? []);
    using var certificatePem = new PinnedBytes(identity.ProvideTlsCertificatePem ?? []);
    using var privateKeyPem = new PinnedBytes(identity.ProvideTlsPrivateKeyPem ?? []);
    ulong keyMaterial = Raw.urnet_new_device_local_key_material(
        clientKeySeed.Pointer, clientKeySeed.Length, certificatePem.Pointer,
        certificatePem.Length, privateKeyPem.Pointer, privateKeyPem.Length);
    if (keyMaterial == 0) {
      throw new IOException("the sdk did not accept the provider identity");
    }
    if (identity.ExtenderKeySeed is { Length: > 0 } extenderKeySeedBytes) {
      using var extenderKeySeed = new PinnedBytes(extenderKeySeedBytes);
      Raw.urnet_device_local_key_material_set_extender_key_seed(
          keyMaterial, extenderKeySeed.Pointer, extenderKeySeed.Length);
    }
    return keyMaterial;
  }

  /// Creates the local device. One call serves both runs: on first run there
  /// is no identity, the key material handle is 0 and the device makes a new
  /// identity, which the constructor saves.
  private static Device NewDevice(ulong spaceHandle, ProviderConfig config) {
    ulong keyMaterial = NewKeyMaterial(config.Identity);
    try {
      // no device rpc; the extender settings as above
      ulong handle = Raw.urnet_new_device_local_with_provide_extender(
          spaceHandle, config.ClientJwt, DeviceDescription, DeviceSpec, "1",
          config.InstanceId, CBool(false), keyMaterial,
          CBool(ProvideExtenderEnabled), CBool(DefaultProvideExtender),
          out IntPtr createError);
      string? message = Sdk.TakeString(createError);
      if (handle == 0) {
        throw new IOException(message ?? "the sdk did not create the device");
      }
      return new Device(handle);
    } finally {
      // the device keeps its own copy of the identity
      if (keyMaterial != 0) {
        Raw.urnet_release(keyMaterial);
      }
    }
  }

  /// Keeps the new identity of a first run, so later starts present the same
  /// provider.
  private void SaveNewIdentity(ulong deviceHandle) {
    byte[] clientKeySeed =
        ReadDeviceBytes(deviceHandle, Raw.urnet_device_local_get_client_key_seed);
    if (clientKeySeed.Length != 32) {
      throw new IOException("the device has no provider identity to save");
    }
    byte[] extenderKeySeed =
        ReadDeviceBytes(deviceHandle, Raw.urnet_device_local_get_extender_key_seed);
    var identity = new ProviderIdentity {
      Version = ProviderIdentity.CurrentVersion,
      ClientId = config.ClientId,
      ClientKeySeed = clientKeySeed,
      ProvideTlsCertificatePem = ReadDeviceBytes(
          deviceHandle, Raw.urnet_device_local_get_provide_tls_certificate_pem),
      ProvideTlsPrivateKeyPem = ReadDeviceBytes(
          deviceHandle, Raw.urnet_device_local_get_provide_tls_private_key_pem),
      ExtenderKeySeed = extenderKeySeed.Length == 0 ? null : extenderKeySeed,
    };
    try {
      StateFiles.SaveProviderIdentity(config.StateDir, identity);
    } catch (Exception e) when (e is IOException or UnauthorizedAccessException) {
      throw new IOException($"save {StateFiles.IdentityFileName}: {e.Message}", e);
    }
  }

  // A C ABI buffer-out getter: it always sets length to the size it needs, and
  // copies (returning true) only when output has that capacity.
  private delegate byte BufferGetter(ulong handle, IntPtr output, ref int length);

  /// One identity value of the device: the first call reads its size, the
  /// second copies it into a pinned array.
  private static byte[] ReadDeviceBytes(ulong deviceHandle, BufferGetter getter) {
    int length = 0;
    getter(deviceHandle, IntPtr.Zero, ref length);
    if (length <= 0) {
      return [];
    }
    byte[] bytes = new byte[length];
    using var pinned = new PinnedBytes(bytes);
    int capacity = length;
    if (getter(deviceHandle, pinned.Pointer, ref capacity) == 0 ||
        capacity != length) {
      throw new IOException("the device identity changed while it was read");
    }
    return bytes;
  }

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

  /// 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.
  private void SyncWallet() {
    Raw.urnet_device_local_sync_sn_wallet(device!.Value, walletRead, IntPtr.Zero);
  }

  /// Reads the status from the device getters and the listener state.
  public ProviderStatus Status() {
    ulong handle = device!.Value;
    // "client_limit_exceeded", with the hold's end in RetryTime, while the
    // platform holds this client off for its network's client limit
    var (clientLimitStatus, clientLimitRetryTime) = StatusRules.ParseClientLimitStatus(
        Sdk.TakeString(Raw.urnet_device_get_client_limit_status(handle)));
    // GetProviderReady also waits for processed client key registration, which
    // default device settings do not enable, so the connected carrier is the
    // readiness signal here
    string state = StatusRules.ProviderState(
        Raw.urnet_device_get_provide_mode(handle), clientLimitStatus,
        Raw.urnet_device_get_provide_paused(handle) != 0,
        Raw.urnet_device_get_provide_enabled(handle) != 0,
        Raw.urnet_device_local_get_provider_connected(handle) != 0);
    long dataProvidedByteCount = StatusRules.DataProvidedByteCount(
        Sdk.TakeString(Raw.urnet_device_get_provider_packet_stats(handle)));
    var (clientsServed, clientsServedAtLimit) = servedClients.Count();
    return new ProviderStatus {
      State = state,
      ClientLimitRetryTime = clientLimitRetryTime,
      ClientsServed = clientsServed,
      ClientsServedAtLimit = clientsServedAtLimit,
      DataProvidedByteCount = dataProvidedByteCount,
      PayoutWallet = payoutWallet,
      PayoutWalletScope = payoutWalletScope,
    };
  }

  /// 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) {
    StatusKey? lastKey = null;
    var clock = Stopwatch.StartNew();
    TimeSpan lastPrintTime = TimeSpan.Zero;
    TimeSpan nextWalletSyncTime = WalletSyncInterval;
    while (true) {
      SaveRefreshedClientJwt();
      ApplyWalletRead();
      ProviderStatus status = Status();
      TimeSpan now = clock.Elapsed;
      StatusKey key = status.Key();
      if (key != lastKey || StatusRepeatInterval <= now - lastPrintTime) {
        output.WriteLine(status);
        lastKey = key;
        lastPrintTime = now;
      }
      if (nextWalletSyncTime <= now) {
        SyncWallet();
        nextWalletSyncTime = now + WalletSyncInterval;
      }
      if (stop.WaitHandle.WaitOne(StatusPollInterval)) {
        return Program.ExitStopped;
      }
      bool credentialRejected;
      lock (stateLock) {
        credentialRejected = loggedOut;
      }
      if (credentialRejected) {
        error.WriteLine("the server rejected the client credential; issue a new scoped client JWT from your backend");
        return Program.ExitConfig;
      }
    }
  }

  /// Keeps the refreshed credential, so the next start uses a valid token.
  private void SaveRefreshedClientJwt() {
    string? clientJwt;
    lock (stateLock) {
      clientJwt = unsavedClientJwt;
      unsavedClientJwt = null;
    }
    if (clientJwt == null) {
      return;
    }
    try {
      StateFiles.WritePrivateFile(
          Path.Combine(config.StateDir, StateFiles.ClientJwtFileName),
          Encoding.UTF8.GetBytes(clientJwt + "\n"));
    } catch (Exception e) when (e is IOException or UnauthorizedAccessException) {
      // never print the token itself
      error.WriteLine($"could not save the refreshed client credential: {e.Message}");
    }
  }

  /// Applies the wallet reads that finished. A failure keeps the last known
  /// wallet; before the first successful read it shows "unavailable".
  private void ApplyWalletRead() {
    bool pending;
    bool succeeded;
    lock (stateLock) {
      pending = walletReadPending;
      succeeded = walletReadSucceeded;
      walletReadPending = false;
      walletReadSucceeded = false;
    }
    if (!pending) {
      return;
    }
    if (!succeeded) {
      if (payoutWallet == StatusRules.PayoutWalletChecking) {
        payoutWallet = StatusRules.PayoutWalletUnavailable;
      }
      return;
    }
    // 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
    (payoutWallet, payoutWalletScope) = StatusRules.ParsePayoutWallet(
        Sdk.TakeString(Raw.urnet_device_local_get_sn_wallet(device!.Value)),
        config.ClientId);
  }

  /// Stops providing, 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;
    if (device != null) {
      Raw.urnet_device_set_provide_mode(device.Value, StatusRules.ProvideModeNone);
    }
    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();
    if (started) {
      output.WriteLine("status: stopped");
    }
  }

  /// A C bool argument.
  private static byte CBool(bool value) {
    return value ? (byte)1 : (byte)0;
  }
}

/// Bytes pinned for C ABI calls, so the SDK reads or fills them in place
/// instead of through a copy in unmanaged memory (they hold identity secrets).
internal readonly struct PinnedBytes : IDisposable {
  private readonly GCHandle handle;

  /// Pins bytes until Dispose.
  public PinnedBytes(byte[] bytes) {
    handle = GCHandle.Alloc(bytes, GCHandleType.Pinned);
    Length = bytes.Length;
  }

  /// The address of the first byte, valid until Dispose.
  public IntPtr Pointer => handle.AddrOfPinnedObject();

  /// The number of bytes.
  public int Length { get; }

  /// Unpins the bytes.
  public void Dispose() {
    handle.Free();
  }
}