Developer SDK

Ruby examples

Install the SDK · View source on GitHub ↗

provider/status.rb

ruby
# frozen_string_literal: true

# The provider status that every provider example shows, with the exact text
# rules of PROVIDER_CONTRACT.md ("Status"): providing state, clients served,
# data provided and the payout wallet, read only. Everything here is plain
# Ruby, so the self-test checks it without the native SDK, a network or
# credentials. ClientsServed is the one stateful class; it is safe for use from
# SDK threads.

require "json"

module Provider
  # Shown once at start, and in every example's README. The app that integrates
  # a provider owns the consent screen; this example starts without asking.
  CONSENT_DISCLAIMER = <<~TEXT.chomp
    Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.
    Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.
    This example starts providing without asking, because the consent screen belongs to your app.
  TEXT

  # provide modes of the C ABI (URNET_PROVIDE_MODE_NONE, _NETWORK and _PUBLIC)
  PROVIDE_MODE_NONE = 0
  PROVIDE_MODE_NETWORK = 1
  PROVIDE_MODE_PUBLIC = 3

  # client limit status values (URNET_CLIENT_LIMIT_STATUS_NONE and _EXCEEDED)
  CLIENT_LIMIT_STATUS_NONE = ""
  CLIENT_LIMIT_STATUS_EXCEEDED = "client_limit_exceeded"

  # consent_scope values of a GET /sn/wallet entry
  # (URNET_SN_WALLET_CONSENT_SCOPE_NETWORK and _PROVIDER). Hotkey delegations
  # come with a later server and SDK change, which adds the SDK's own constant;
  # the app only labels the entry.
  SN_WALLET_CONSENT_SCOPE_NETWORK = "network"
  SN_WALLET_CONSENT_SCOPE_PROVIDER = "provider"
  SN_WALLET_CONSENT_SCOPE_HOTKEY = "hotkey"

  PROVIDER_STATE_STOPPED = "stopped"
  # the platform disconnected this client for its network's client limit, and
  # the SDK holds off reconnecting until the retry time
  PROVIDER_STATE_CLIENT_LIMIT = "client limit"
  PROVIDER_STATE_STARTING = "starting"
  PROVIDER_STATE_PAUSED = "paused"
  PROVIDER_STATE_PROVIDING = "providing"

  # the payout wallet before the first wallet read finishes
  PAYOUT_WALLET_CHECKING = "checking"
  # the payout wallet when the first wallet read failed
  PAYOUT_WALLET_UNAVAILABLE = "unavailable"
  # the payout wallet when no wallet is mapped
  PAYOUT_WALLET_NOT_SET = "not set"

  PAYOUT_WALLET_SCOPE_HOTKEY = "hotkey"
  PAYOUT_WALLET_SCOPE_PROVIDER = "this provider"
  PAYOUT_WALLET_SCOPE_NETWORK = "network"
  PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER = "another provider"

  # Distinct clients are counted up to this many; beyond it the count is a
  # lower bound, shown with a trailing "+".
  CLIENTS_SERVED_LIMIT = 100 * 1000

  ZERO_ID = "00000000-0000-0000-0000-000000000000"

  BYTE_UNITS = %w[KiB MiB GiB TiB PiB EiB].freeze

  # One status snapshot.
  class Status
    attr_reader :state, :client_limit_retry_time, :clients_served, :clients_served_at_limit,
                :data_provided_byte_count, :payout_wallet, :payout_wallet_scope

    # state is one of the PROVIDER_STATE_* texts; client_limit_retry_time is
    # the end of the client limit hold in unix milliseconds, 0 when unknown;
    # payout_wallet is a coldkey ss58 address or one of the PAYOUT_WALLET_*
    # texts, and payout_wallet_scope is "" unless payout_wallet is an address.
    def initialize(state:, client_limit_retry_time: 0, clients_served: 0, clients_served_at_limit: false,
                   data_provided_byte_count: 0, payout_wallet: PAYOUT_WALLET_CHECKING, payout_wallet_scope: "")
      @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

    # The status line, for example
    # "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5Grw... (network)".
    def line
      clients_served = @clients_served.to_s
      clients_served += "+" if @clients_served_at_limit
      payout_wallet = @payout_wallet_scope.empty? ? @payout_wallet : "#{@payout_wallet} (#{@payout_wallet_scope})"
      status_text = Provider.provider_status_text(@state, @client_limit_retry_time)
      data_provided = Provider.format_byte_count(@data_provided_byte_count)
      "status: #{status_text} | clients served: #{clients_served} | data provided: #{data_provided} | payout wallet: #{payout_wallet}"
    end

    # The fields that change rarely. A change prints a status line at once; the
    # data counter alone only prints on the periodic line. The status text
    # carries the client limit retry time, so a new retry time prints too.
    def key
      [
        Provider.provider_status_text(@state, @client_limit_retry_time),
        @clients_served,
        @clients_served_at_limit,
        @payout_wallet,
        @payout_wallet_scope,
      ]
    end
  end

  # The status field text: the state, and for the client limit state the time
  # the SDK retries, for example "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; 0 shows "client limit".
  def self.provider_status_text(state, client_limit_retry_time)
    return state if state != PROVIDER_STATE_CLIENT_LIMIT || client_limit_retry_time <= 0

    minute_millis = 60 * 1000
    retry_minute = (client_limit_retry_time + minute_millis - 1) / minute_millis
    # unix time has no leap seconds, so every utc day is 24 * 60 minutes
    minute_of_day = retry_minute % (24 * 60)
    format("%s, retry at %02d:%02d UTC", PROVIDER_STATE_CLIENT_LIMIT, minute_of_day / 60, minute_of_day % 60)
  end

  # Binary units with one decimal: "0 B", "1023 B", "1.0 KiB", "12.4 MiB". A
  # value that rounds to 1024.0 moves to the next unit.
  def self.format_byte_count(byte_count)
    return "#{byte_count} B" if byte_count < 1024

    value = byte_count / 1024.0
    unit_index = 0
    while unit_index < BYTE_UNITS.length - 1 && 1024 <= (value * 10).round / 10.0
      value /= 1024
      unit_index += 1
    end
    format("%.1f %s", value, BYTE_UNITS[unit_index])
  end

  # The providing state from the device getters, in this order: stopped unless
  # the provide mode is public; client limit while the SDK holds this client
  # off for its network's client limit; paused while paused; providing once the
  # provider is enabled and its platform carrier is connected; starting
  # otherwise.
  def self.provider_state(provide_mode, client_limit_status, provide_paused, provide_enabled, provider_connected)
    return PROVIDER_STATE_STOPPED if provide_mode != PROVIDE_MODE_PUBLIC
    return PROVIDER_STATE_CLIENT_LIMIT if client_limit_status == CLIENT_LIMIT_STATUS_EXCEEDED
    return PROVIDER_STATE_PAUSED if provide_paused
    return PROVIDER_STATE_PROVIDING if provide_enabled && provider_connected

    PROVIDER_STATE_STARTING
  end

  # Which owner the effective payout wallet belongs to. The consent scope comes
  # first: a hotkey delegation is network-level, with no client id, but is not
  # the network's wallet. Otherwise by the wallet's client id: this provider's
  # own mapping, the network's wallet, or another provider of the network.
  def self.payout_wallet_scope(wallet_consent_scope, wallet_client_id, client_id)
    return PAYOUT_WALLET_SCOPE_HOTKEY if wallet_consent_scope == SN_WALLET_CONSENT_SCOPE_HOTKEY
    return PAYOUT_WALLET_SCOPE_NETWORK if wallet_client_id.empty?
    return PAYOUT_WALLET_SCOPE_PROVIDER if wallet_client_id == client_id

    PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER
  end

  # The peer of one provider contract (the C ABI's ContractDetails JSON
  # object), by direction as the SDK's contract screens resolve it: the source
  # of a receive (ingress) contract, the destination of a send (egress)
  # contract. A path without that client id is keyed by its stream id, then by
  # the contract id; "" when the contract names none of them.
  def self.contract_peer_key(details, receive)
    present = ->(value) { value.is_a?(String) && !value.empty? && value != ZERO_ID }
    path = details["ContractTransferPath"]
    if path.is_a?(Hash)
      peer_id = receive ? path["SourceId"] : path["DestinationId"]
      return peer_id if present.call(peer_id)
      return "stream:#{path['StreamId']}" if present.call(path["StreamId"])
    end
    return "contract:#{details['ContractId']}" if present.call(details["ContractId"])

    ""
  end

  # A JSON object from the C ABI, or nil for NULL, JSON null or anything that
  # is not an object.
  def self.parse_json_object(text)
    return nil if text.nil? || text.empty?

    value = JSON.parse(text)
    value.is_a?(Hash) ? value : nil
  rescue JSON::ParserError
    nil
  end

  # A JSON integer field, or 0 when it is missing or not an integer.
  def self.json_int(value)
    value.is_a?(Integer) ? value : 0
  end

  # A JSON string field, or "" when it is missing or not a string.
  def self.json_text(value)
    value.is_a?(String) ? value : ""
  end

  # The client limit status and its retry time (unix milliseconds) from the
  # JSON of urnet_device_get_client_limit_status. The C ABI returns NULL only
  # when the call cannot run, and NULL reads as no limit.
  def self.parse_client_limit_status(status_json)
    status = parse_json_object(status_json)
    return [CLIENT_LIMIT_STATUS_NONE, 0] if status.nil?

    [json_text(status["Status"]), json_int(status["RetryTime"])]
  end

  # Bytes relayed for clients in both directions since the device started,
  # from the JSON of urnet_device_get_provider_packet_stats; 0 when the stats
  # are null.
  def self.parse_data_provided_byte_count(packet_stats_json)
    packet_stats = parse_json_object(packet_stats_json)
    return 0 if packet_stats.nil?

    json_int(packet_stats["RemoteEgressByteCount"]) + json_int(packet_stats["RemoteIngressByteCount"])
  end

  # The distinct clients that held a contract with this provider since the app
  # started. Safe for concurrent use: the SDK delivers contract details on its
  # own threads.
  class ClientsServed
    # An empty count that keeps at most limit distinct peers.
    def initialize(limit)
      @limit = limit
      @state_lock = Mutex.new
      # set of contract_peer_key values, as hash keys
      @peer_keys = {}
      @at_limit = false
    end

    # Counts the peer of one provider contract.
    def add(details, receive)
      return if details.nil?

      peer_key = Provider.contract_peer_key(details, receive)
      return if peer_key.empty?

      @state_lock.synchronize do
        next if @peer_keys.key?(peer_key)

        if @limit <= @peer_keys.length
          @at_limit = true
          next
        end
        @peer_keys[peer_key] = true
      end
    end

    # The distinct count, and whether the count stopped at the limit.
    def count
      @state_lock.synchronize { [@peer_keys.length, @at_limit] }
    end
  end
end