Developer SDK

Ruby examples

Install the SDK · View source on GitHub ↗

provider/session.rb

ruby
# frozen_string_literal: true

# A running provider over the SDK's C ABI, through the urnetwork gem (FFI):
# the network space manager, the provider device with the installation's
# identity, and the listeners that feed its status.
#
# SDK callbacks run on SDK threads, which FFI hands to a Ruby thread. They copy
# what they carry, then either count it under the clients-served lock or hand
# it to the run loop through the events queue; the run loop's thread owns every
# other field and makes every other SDK call. The callback procs stay
# referenced for the life of the process, because the SDK can still answer a
# wallet read after the device closes.
#
# The URnetwork module is passed in rather than required, so that the
# self-test never loads the native runtime and the tests can run the lifecycle
# against a stand-in for the C ABI.

require "ffi"
require "fileutils"
require_relative "state"
require_relative "status"

module Provider
  # One run of the provider. The constructor starts providing; run shows the
  # status until a stop request; close stops providing.
  class Session
    # How often the status is read, and the longest gap between status lines.
    STATUS_POLL_INTERVAL_SECONDS = 1
    STATUS_REPEAT_INTERVAL_SECONDS = 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.
    WALLET_SYNC_INTERVAL_SECONDS = 10 * 60

    # The device description and spec recorded for this installation's device.
    DEVICE_DESCRIPTION = "Ruby provider example"
    DEVICE_SPEC = "urnetwork-examples/ruby-provider"
    APP_VERSION = "1"

    # The provider extender role's two device settings (PROVIDER_CONTRACT.md,
    # "Extender role"), passed explicitly and both on.
    # PROVIDE_EXTENDER_ENABLED is the embedder's hard switch: false means the
    # role never runs. DEFAULT_PROVIDE_EXTENDER is the setting the device uses
    # until the user sets one: false turns the default off.
    PROVIDE_EXTENDER_ENABLED = true
    DEFAULT_PROVIDE_EXTENDER = true

    # the ur.network main network space, as the integration helpers create it
    NETWORK_SPACE_KEY_JSON = '{"host_name":"ur.network","env_name":"main"}'
    NETWORK_SPACE_VALUES_JSON = '{"migration_host_name":"bringyour.com"}'

    # run loop events, each an array that starts with one of these
    EVENT_STOP = :stop
    EVENT_JWT_REFRESHED = :jwt_refreshed
    EVENT_AUTH_LOGOUT = :auth_logout
    EVENT_WALLET_SYNCED = :wallet_synced

    # FFI callback procs that the SDK may still call; one set per session
    CALLBACK_ROOTS = []

    # Keeps the SDK's log files in log_dir, which the SDK bounds (16 MiB files,
    # the newest four kept at each start), instead of the system temp
    # directory. The SDK also copies its log lines to stderr, and the C ABI
    # keeps that copy. sdk is the URnetwork module.
    def self.configure_sdk_logs(sdk, log_dir)
      FileUtils.mkdir_p(log_dir, mode: 0o700)
      error = FFI::MemoryPointer.new(:pointer)
      return if sdk::Raw.urnet_set_log_dir(log_dir, error)

      raise IOError, sdk.take_string(error.read_pointer) || "the sdk refused the log directory"
    end

    # 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.
    # sdk is the URnetwork module; events is the run loop's queue, which also
    # carries stop requests.
    def initialize(config, sdk, events)
      @config = config
      @sdk = sdk
      @raw = sdk::Raw
      @events = events
      @clients_served = ClientsServed.new(CLIENTS_SERVED_LIMIT)
      # PAYOUT_WALLET_CHECKING, PAYOUT_WALLET_UNAVAILABLE, PAYOUT_WALLET_NOT_SET
      # or the mapped coldkey
      @payout_wallet = PAYOUT_WALLET_CHECKING
      @payout_wallet_scope = ""
      @subs = []
      @closed = false
      # what close undoes, run last first: the subscriptions, the device, then the manager
      @closers = []

      @jwt_refresh_callback = method(:jwt_refreshed).to_proc
      @auth_logout_callback = method(:auth_logout).to_proc
      @ingress_callback = method(:ingress_contract_details_changed).to_proc
      @egress_callback = method(:egress_contract_details_changed).to_proc
      @wallet_callback = method(:wallet_synced).to_proc
      CALLBACK_ROOTS.push(@jwt_refresh_callback, @auth_logout_callback, @ingress_callback, @egress_callback, @wallet_callback)

      begin
        start
      rescue StandardError
        run_closers
        raise
      end
      sync_wallet
    end

    # Reads the status from the device getters and the listener state.
    def status
      device = @device.handle
      # "client_limit_exceeded" with the hold's end in RetryTime while the
      # platform holds this client off for its network's client limit
      client_limit_status, client_limit_retry_time = Provider.parse_client_limit_status(
        @sdk.take_string(@raw.urnet_device_get_client_limit_status(device)),
      )
      # urnet_device_get_provider_ready also waits for processed client key
      # registration, which default device settings do not enable, so the
      # connected carrier is the readiness signal here
      state = Provider.provider_state(
        @raw.urnet_device_get_provide_mode(device),
        client_limit_status,
        @raw.urnet_device_get_provide_paused(device),
        @raw.urnet_device_get_provide_enabled(device),
        @raw.urnet_device_local_get_provider_connected(device),
      )
      data_provided_byte_count = Provider.parse_data_provided_byte_count(
        @sdk.take_string(@raw.urnet_device_get_provider_packet_stats(device)),
      )
      clients_served, clients_served_at_limit = @clients_served.count
      Status.new(
        state: state,
        client_limit_retry_time: client_limit_retry_time,
        clients_served: clients_served,
        clients_served_at_limit: clients_served_at_limit,
        data_provided_byte_count: data_provided_byte_count,
        payout_wallet: @payout_wallet,
        payout_wallet_scope: @payout_wallet_scope,
      )
    end

    # Reads the payout wallet (GET /sn/wallet with the client credential). The
    # app only displays the wallet: the backend maps it, never the app.
    def sync_wallet
      @raw.urnet_device_local_sync_sn_wallet(@device.handle, @wallet_callback, nil)
    end

    # Prints status lines until a stop request. Raises ConfigError when the
    # server rejects the client credential.
    def run
      last_key = nil
      last_print_time = 0.0
      next_wallet_sync_time = monotonic_now + WALLET_SYNC_INTERVAL_SECONDS
      loop do
        snapshot = status
        now = monotonic_now
        if snapshot.key != last_key || STATUS_REPEAT_INTERVAL_SECONDS <= now - last_print_time
          puts snapshot.line
          last_key = snapshot.key
          last_print_time = now
        end
        if next_wallet_sync_time <= now
          sync_wallet
          next_wallet_sync_time = now + WALLET_SYNC_INTERVAL_SECONDS
        end
        return if apply_events_until(now + STATUS_POLL_INTERVAL_SECONDS)
      end
    end

    # Stops providing, closes the subscriptions, the device and then the
    # manager, and saves a refreshed credential that arrived meanwhile.
    def close
      return if @closed

      @closed = true
      @raw.urnet_device_set_provide_mode(@device.handle, PROVIDE_MODE_NONE)
      run_closers
      # keep a refresh that arrived after the run loop's last read
      while (event = @events.pop(timeout: 0))
        save_client_jwt(event[1]) if event[0] == EVENT_JWT_REFRESHED
      end
      puts "status: stopped"
    end

    private

    # Creates the manager, the network space and the device, then adds the
    # listeners and starts providing. Each step registers what undoes it.
    def start
      raw = @raw
      manager = @sdk::Handle.new(raw.urnet_new_network_space_manager_no_storage)
      manager_handle = manager.handle
      @closers << -> { manager.close }
      @closers << -> { raw.urnet_network_space_manager_close(manager_handle) }
      space = @sdk::Handle.new(
        raw.urnet_network_space_manager_update_network_space_values(manager_handle, NETWORK_SPACE_KEY_JSON, NETWORK_SPACE_VALUES_JSON),
      )
      @closers << -> { space.close }
      api = @sdk::Handle.new(raw.urnet_network_space_get_api(space.handle))
      @closers << -> { api.close }
      raw.urnet_api_set_by_jwt(api.handle, @config.client_jwt)
      @device = @sdk::Device.new(new_device(space.handle))
      @closers << -> { @device.close }
      # keep the new identity, so later starts present the same provider
      save_new_identity if @config.identity.nil?
      device = @device.handle
      @subs = [
        raw.urnet_device_add_jwt_refresh_listener(device, @jwt_refresh_callback, nil),
        raw.urnet_device_add_auth_logout_listener(device, @auth_logout_callback, nil),
        raw.urnet_device_add_provider_ingress_contract_details_change_listener(device, @ingress_callback, nil),
        raw.urnet_device_add_provider_egress_contract_details_change_listener(device, @egress_callback, nil),
      ]
      @closers << -> { close_subs }
      raw.urnet_device_set_provide_mode(device, PROVIDE_MODE_PUBLIC)
    end

    # Creates the device with the extender-aware constructor: one call for both
    # runs. On first run there is no identity, the key material is 0 and the
    # device makes a new identity, which the caller saves.
    def new_device(space)
      key_material = new_key_material(State.key_material(@config.identity))
      error = FFI::MemoryPointer.new(:pointer)
      begin
        device = @raw.urnet_new_device_local_with_provide_extender(
          space,
          @config.client_jwt,
          DEVICE_DESCRIPTION,
          DEVICE_SPEC,
          APP_VERSION,
          @config.instance_id,
          false,
          key_material,
          PROVIDE_EXTENDER_ENABLED,
          DEFAULT_PROVIDE_EXTENDER,
          error,
        )
        message = @sdk.take_string(error.read_pointer)
      ensure
        @raw.urnet_release(key_material) unless key_material.zero?
      end
      raise message if message
      raise "the sdk did not create the device" if device.zero?

      device
    end

    # A native key material handle for the device constructor, which the
    # caller releases after the call; 0 without key material (the first run).
    def new_key_material(key_material)
      return 0 if key_material.nil?

      buffer = lambda do |data|
        next [nil, 0] if data.empty?

        memory = FFI::MemoryPointer.new(:uint8, data.bytesize)
        memory.put_bytes(0, data)
        [memory, data.bytesize]
      end
      seed, seed_length = buffer.call(key_material.client_key_seed)
      certificate, certificate_length = buffer.call(key_material.provide_tls_certificate_pem)
      private_key, private_key_length = buffer.call(key_material.provide_tls_private_key_pem)
      handle = @raw.urnet_new_device_local_key_material(
        seed, seed_length, certificate, certificate_length, private_key, private_key_length,
      )
      raise "the sdk did not create the key material" if handle.zero?

      unless key_material.extender_key_seed.empty?
        extender_seed, extender_seed_length = buffer.call(key_material.extender_key_seed)
        @raw.urnet_device_local_key_material_set_extender_key_seed(handle, extender_seed, extender_seed_length)
      end
      handle
    end

    # Bytes from a buffer-out getter of the C ABI: the first call asks for the
    # size, the second copies. "" when the device has none.
    def read_device_bytes(getter, device)
      size = FFI::MemoryPointer.new(:int32)
      size.write_int32(0)
      @raw.public_send(getter, device, nil, size)
      length = size.read_int32
      return "".b if length <= 0

      buffer = FFI::MemoryPointer.new(:uint8, length)
      return "".b unless @raw.public_send(getter, device, buffer, size)

      buffer.read_bytes(size.read_int32)
    end

    # Saves the device's new identity as identity.json, on first run.
    def save_new_identity
      device = @device.handle
      identity = Identity.new(
        client_id: @config.client_id,
        client_key_seed: read_device_bytes(:urnet_device_local_get_client_key_seed, device),
        provide_tls_certificate_pem: read_device_bytes(:urnet_device_local_get_provide_tls_certificate_pem, device),
        provide_tls_private_key_pem: read_device_bytes(:urnet_device_local_get_provide_tls_private_key_pem, device),
        extender_key_seed: read_device_bytes(:urnet_device_local_get_extender_key_seed, device),
      )
      raise "the device has no provider identity to save" if identity.client_key_seed.bytesize != 32

      begin
        State.save_identity(@config.state_dir, identity)
      rescue SystemCallError, IOError => error
        raise "save #{State::IDENTITY_FILE_NAME}: #{error.message}"
      end
    end

    # Applies run loop events as they arrive until the deadline; true when a
    # stop was requested.
    def apply_events_until(deadline)
      loop do
        timeout = deadline - monotonic_now
        return false if timeout <= 0

        event = @events.pop(timeout: timeout)
        return false if event.nil?
        return true if apply_event(event)
      end
    end

    # Applies one run loop event; true for a stop request. Raises ConfigError
    # when the server rejected the client credential.
    def apply_event(event)
      case event[0]
      when EVENT_STOP
        return true
      when EVENT_AUTH_LOGOUT
        raise ConfigError, "the server rejected the client credential; issue a new scoped client JWT from your backend"
      when EVENT_JWT_REFRESHED
        save_client_jwt(event[1])
      when EVENT_WALLET_SYNCED
        record_wallet_read(event[1], event[2])
      end
      false
    end

    # Runs what close undoes, last first, once.
    def run_closers
      @closers.reverse_each(&:call)
      @closers.clear
    end

    # Closes and releases the listener subscriptions.
    def close_subs
      @subs.each do |sub|
        @raw.urnet_sub_close(sub)
        @raw.urnet_release(sub)
      end
      @subs = []
    end

    # Keeps the refreshed credential, so the next start uses a valid token.
    def save_client_jwt(client_jwt)
      return if client_jwt.nil? || client_jwt.empty?

      State.write_private_file(File.join(@config.state_dir, State::CLIENT_JWT_FILE_NAME), "#{client_jwt}\n")
    rescue SystemCallError, IOError => error
      # never print the token itself
      warn "could not save the refreshed client credential: #{error.message}"
    end

    # Records a payout wallet read. A failure keeps the last known wallet.
    def record_wallet_read(result_json, error_text)
      result = Provider.parse_json_object(result_json)
      if !error_text.nil? || result.nil? || !result["error"].nil?
        @payout_wallet = PAYOUT_WALLET_UNAVAILABLE if @payout_wallet == PAYOUT_WALLET_CHECKING
        return
      end
      # 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
      wallet = Provider.parse_json_object(@sdk.take_string(@raw.urnet_device_local_get_sn_wallet(@device.handle)))
      coldkey = wallet.nil? ? "" : Provider.json_text(wallet["coldkey_ss58"])
      if coldkey.empty?
        @payout_wallet = PAYOUT_WALLET_NOT_SET
        @payout_wallet_scope = ""
        return
      end
      @payout_wallet = coldkey
      @payout_wallet_scope = Provider.payout_wallet_scope(
        Provider.json_text(wallet["consent_scope"]),
        Provider.json_text(wallet["client_id"]),
        @config.client_id,
      )
    end

    # Hands a refreshed client JWT to the run loop, which saves it. Runs on an
    # SDK thread.
    def jwt_refreshed(_user_data, client_jwt)
      @events.push([EVENT_JWT_REFRESHED, client_jwt&.dup])
    end

    # Ends the run: the server no longer accepts this client's credential. Runs
    # on an SDK thread.
    def auth_logout(_user_data)
      @events.push([EVENT_AUTH_LOGOUT])
    end

    # Counts the peer of a receive contract. Runs on an SDK thread.
    def ingress_contract_details_changed(_user_data, details_json)
      @clients_served.add(Provider.parse_json_object(details_json), true)
    end

    # Counts the peer of a send contract. Runs on an SDK thread.
    def egress_contract_details_changed(_user_data, details_json)
      @clients_served.add(Provider.parse_json_object(details_json), false)
    end

    # Hands a payout wallet read to the run loop. Runs on an SDK thread.
    def wallet_synced(_user_data, result_json, error_text)
      @events.push([EVENT_WALLET_SYNCED, result_json&.dup, error_text&.dup])
    end

    # Seconds on a clock that never goes back.
    def monotonic_now
      Process.clock_gettime(Process::CLOCK_MONOTONIC)
    end
  end
end