Developer SDK

C++ examples

Install the SDK · View source on GitHub ↗

provider/session.hpp

c++
// A running provider on the C++ SDK (urnetwork_sdk.hpp, a header-only facade
// over the C ABI): the network space manager, the provider device with the
// installation's identity, and the listeners that feed its status. sdk
// listeners run on sdk threads: they copy what they carry into SessionEvents,
// which they hold by shared_ptr, and hand the work to the thread that runs
// the session, which saves refreshed tokens, applies wallet reads and ends the
// run on a logout.
#pragma once

#include <chrono>
#include <condition_variable>
#include <csignal>
#include <iostream>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <tuple>
#include <utility>
#include <vector>

#include <urnetwork_sdk.hpp>

#include "command.hpp"
#include "state.hpp"
#include "status.hpp"

namespace provider {

// How often the status is read, and the longest gap between status lines.
inline constexpr auto statusPollInterval = std::chrono::seconds(1);
inline constexpr auto statusRepeatInterval = std::chrono::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.
inline constexpr auto walletSyncInterval = std::chrono::minutes(10);

// The device description and spec recorded for this installation's device.
inline constexpr const char* deviceDescription = "C++ provider example";
inline constexpr const char* deviceSpec = "urnetwork-examples/cpp-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.
inline constexpr bool provideExtenderEnabled = true;
inline constexpr bool defaultProvideExtender = true;

// Set from a signal handler or the Windows console handler; the run loop
// stops within one status poll.
inline volatile std::sig_atomic_t stopRequested = 0;

// Work that sdk listeners hand to the run loop, guarded by stateLock.
struct SessionEvents {
    std::mutex stateLock;
    // notified when work arrives, so the run loop does it at once
    std::condition_variable changed;
    // the server rejected the client credential
    bool logout = false;
    // a refreshed client jwt that is not saved yet
    std::optional<std::string> refreshedClientJwt;
    // the outcome of a wallet read that the run loop has not applied yet
    std::optional<bool> walletReadSucceeded;
    // fed by the provider contract listeners, which lock it themselves
    ClientsServed clientsServed{clientsServedLimit};
};

// Keeps closed subscriptions, and the listeners they own, until the process
// exits: a native callback that raced the close can still run a listener, so
// it must never see freed memory.
inline void retainUntilExit(std::vector<urnet::Sub>& subs) {
    static auto* retainedSubs = new std::vector<urnet::Sub>();
    for (auto& sub : subs) {
        retainedSubs->push_back(std::move(sub));
    }
    subs.clear();
}

// The key material that recreates the device's identity. Empty without an
// identity (the first run, or another client's identity): the device then
// makes a new identity, which the app saves.
inline urnet::DeviceLocalKeyMaterial providerKeyMaterial(const std::optional<ProviderIdentity>& identity) {
    if (!identity) {
        return urnet::DeviceLocalKeyMaterial{};
    }
    auto keyMaterial = urnet::newDeviceLocalKeyMaterial(
        identity->clientKeySeed.data(),
        static_cast<int32_t>(identity->clientKeySeed.size()),
        identity->provideTlsCertificatePem.data(),
        static_cast<int32_t>(identity->provideTlsCertificatePem.size()),
        identity->provideTlsPrivateKeyPem.data(),
        static_cast<int32_t>(identity->provideTlsPrivateKeyPem.size()));
    keyMaterial.setExtenderKeySeed(identity->extenderKeySeed.data(), static_cast<int32_t>(identity->extenderKeySeed.size()));
    return keyMaterial;
}

// One run of the provider. The constructor starts providing; run shows the
// status; close (also run by the destructor) stops providing. The wallet
// fields belong to the thread that runs the session.
class ProviderSession {
public:
    // 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.
    explicit ProviderSession(const ProviderConfig& providerConfig)
        : config(providerConfig), events(std::make_shared<SessionEvents>()),
          manager(urnet::newNetworkSpaceManagerNoStorage()) {
        try {
            urnet::NetworkSpaceKey key;
            key.host_name = "ur.network";
            key.env_name = "main";
            urnet::NetworkSpaceValues values;
            values.migration_host_name = "bringyour.com";
            space = manager.updateNetworkSpaceValues(key, values);
            if (!space) {
                throw std::runtime_error("the sdk did not create the network space");
            }
            api = space.getApi();
            api.setByJwt(config.clientJwt);
            // one call for both runs: on first run there is no identity, the
            // key material is empty and the device makes a new identity,
            // saved below; the key material handle is released after the call
            device = urnet::newDeviceLocalWithProvideExtender(
                space,
                config.clientJwt,
                deviceDescription,
                deviceSpec,
                "1",
                config.instanceId,
                false,
                providerKeyMaterial(config.identity),
                provideExtenderEnabled,
                defaultProvideExtender);
            if (!device) {
                throw std::runtime_error("the sdk did not create the device");
            }
            if (!config.identity) {
                saveNewIdentity();
            }

            // the listeners share the events, so a late callback still finds them
            subs.push_back(device.addJwtRefreshListener([sessionEvents = events](std::string clientJwt) {
                std::lock_guard<std::mutex> lock(sessionEvents->stateLock);
                sessionEvents->refreshedClientJwt = std::move(clientJwt);
                sessionEvents->changed.notify_one();
            }));
            subs.push_back(device.addAuthLogoutListener([sessionEvents = events]() {
                std::lock_guard<std::mutex> lock(sessionEvents->stateLock);
                sessionEvents->logout = true;
                sessionEvents->changed.notify_one();
            }));
            subs.push_back(device.addProviderIngressContractDetailsChangeListener(
                [sessionEvents = events](std::optional<urnet::ContractDetails> details) {
                    sessionEvents->clientsServed.add(details, true);
                }));
            subs.push_back(device.addProviderEgressContractDetailsChangeListener(
                [sessionEvents = events](std::optional<urnet::ContractDetails> details) {
                    sessionEvents->clientsServed.add(details, false);
                }));
            device.setProvideMode(urnet::ProvideModePublic);
            syncWallet();
        } catch (...) {
            for (auto& sub : subs) {
                sub.close();
            }
            retainUntilExit(subs);
            if (device) {
                device.close();
            }
            manager.close();
            throw;
        }
    }

    ProviderSession(const ProviderSession&) = delete;
    ProviderSession& operator=(const ProviderSession&) = delete;

    // Stops providing if close has not run.
    ~ProviderSession() {
        close();
    }

    // Prints status lines until a stop is requested or the server rejects the
    // credential, and returns the process exit code.
    int run() {
        std::string lastKey;
        bool printed = false;
        auto lastPrintTime = std::chrono::steady_clock::now();
        auto nextWalletSyncTime = lastPrintTime + walletSyncInterval;
        for (;;) {
            if (takeEvents()) {
                std::cerr << "the server rejected the client credential; issue a new scoped client JWT from your backend"
                          << std::endl;
                return exitConfig;
            }
            if (stopRequested) {
                return exitStopped;
            }
            ProviderStatus status = readStatus();
            auto now = std::chrono::steady_clock::now();
            std::string key = status.key();
            if (!printed || key != lastKey || statusRepeatInterval <= now - lastPrintTime) {
                printLine(status.line());
                lastKey = key;
                lastPrintTime = now;
                printed = true;
            }
            if (nextWalletSyncTime <= now) {
                syncWallet();
                nextWalletSyncTime = now + walletSyncInterval;
            }
            std::unique_lock<std::mutex> lock(events->stateLock);
            if (!events->logout && !events->refreshedClientJwt && !events->walletReadSucceeded) {
                events->changed.wait_for(lock, statusPollInterval);
            }
        }
    }

    // Stops providing and closes the subscriptions, the device and the manager;
    // the handles are released when the session is destroyed. A token refreshed
    // before the close is still saved.
    void close() {
        if (closed) {
            return;
        }
        closed = true;
        device.setProvideMode(urnet::ProvideModeNone);
        for (auto& sub : subs) {
            sub.close();
        }
        retainUntilExit(subs);
        takeEvents();
        device.close();
        manager.close();
        printLine("status: stopped");
    }

private:
    // Reads the identity of a device that was created without one and saves it
    // as identity.json, so later starts present the same provider.
    void saveNewIdentity() {
        ProviderIdentity identity;
        identity.clientId = config.clientId;
        identity.clientKeySeed = device.getClientKeySeed();
        identity.provideTlsCertificatePem = device.getProvideTlsCertificatePem();
        identity.provideTlsPrivateKeyPem = device.getProvideTlsPrivateKeyPem();
        identity.extenderKeySeed = device.getExtenderKeySeed();
        if (identity.clientKeySeed.size() != 32) {
            throw std::runtime_error("the device has no provider identity to save");
        }
        try {
            saveProviderIdentity(config.stateDir, identity);
        } catch (const std::exception& e) {
            throw std::runtime_error(std::string("save ") + identityFileName + ": " + e.what());
        }
    }

    // Reads the status from the device getters and the listener state.
    ProviderStatus readStatus() {
        // "client_limit_exceeded" with the hold's end in RetryTime while the
        // platform holds this client off for its network's client limit; empty
        // only when the call cannot run, which reads as no limit
        urnet::ClientLimitStatus clientLimitStatus = device.getClientLimitStatus().value_or(urnet::ClientLimitStatus{});
        ProviderStatus status;
        // GetProviderReady also waits for processed client key registration,
        // which default device settings do not enable, so the connected
        // carrier is the readiness signal here
        status.state = std::string(providerState(
            device.getProvideMode(),
            clientLimitStatus.Status,
            device.getProvidePaused(),
            device.getProvideEnabled(),
            device.getProviderConnected()));
        status.clientLimitRetryTime = clientLimitStatus.RetryTime;
        status.dataProvidedByteCount = dataProvidedByteCount(device.getProviderPacketStats());
        std::tie(status.clientsServed, status.clientsServedAtLimit) = events->clientsServed.count();
        status.payoutWallet = payoutWallet;
        status.payoutWalletScope = payoutWalletScopeText;
        return status;
    }

    // Reads the payout wallet (GET /sn/wallet with the client credential). The
    // app only displays the wallet: the backend maps it, never the app.
    void syncWallet() {
        device.syncSnWallet([sessionEvents = events](
                                std::optional<urnet::SnGetWalletResult> result, std::optional<std::string> error) {
            bool succeeded = walletReadSucceeded(result, error);
            std::lock_guard<std::mutex> lock(sessionEvents->stateLock);
            sessionEvents->walletReadSucceeded = succeeded;
            sessionEvents->changed.notify_one();
        });
    }

    // Takes the work that listeners handed over and does it on this thread.
    // Returns whether the server rejected the credential.
    bool takeEvents() {
        std::optional<std::string> refreshedClientJwt;
        std::optional<bool> walletRead;
        bool logout = false;
        {
            std::lock_guard<std::mutex> lock(events->stateLock);
            std::swap(refreshedClientJwt, events->refreshedClientJwt);
            std::swap(walletRead, events->walletReadSucceeded);
            logout = events->logout;
        }
        if (refreshedClientJwt) {
            try {
                writePrivateFile(config.stateDir / clientJwtFileName, *refreshedClientJwt + "\n");
            } catch (const std::exception& e) {
                // never print the token itself
                std::cerr << "could not save the refreshed client credential: " << e.what() << std::endl;
            }
        }
        if (walletRead) {
            applyWalletRead(*walletRead);
        }
        return logout;
    }

    // Applies a wallet read. A failure keeps the last known wallet; after a
    // success the sdk has cached the effective wallet: this client's own
    // consent, else the network consent, else (with hotkey delegations) the
    // network's hotkey entry, else a non-consent wallet.
    void applyWalletRead(bool succeeded) {
        if (!succeeded) {
            if (payoutWallet == payoutWalletChecking) {
                payoutWallet = std::string(payoutWalletUnavailable);
            }
            return;
        }
        std::tie(payoutWallet, payoutWalletScopeText) = payoutWalletDisplay(device.getSnWallet(), config.clientId);
    }

    const ProviderConfig& config;
    std::shared_ptr<SessionEvents> events;
    // released in reverse order: the device, then the api, the space and the
    // manager
    urnet::NetworkSpaceManager manager;
    urnet::NetworkSpace space;
    urnet::Api api;
    urnet::DeviceLocal device;
    std::vector<urnet::Sub> subs;
    bool closed = false;
    // payoutWalletChecking, payoutWalletUnavailable, payoutWalletNotSet or the
    // mapped coldkey
    std::string payoutWallet = std::string(payoutWalletChecking);
    std::string payoutWalletScopeText;
};

}  // namespace provider