Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

provider/selftest.go

go
// The credential-free self-test (PROVIDER_CONTRACT.md, "Self-test"). It checks
// the disclaimer, the status text, the providing state, the clients-served
// count and the installation state files without a network, credentials or a
// running device. `--self-test` runs every check; provider_test.go runs each
// one as a test.
package main

import (
	"bytes"
	"crypto/sha256"
	"encoding/base64"
	"encoding/hex"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"runtime"

	sdk "github.com/urnetwork/sdk/v2026"
)

// sha-256 of the consent disclaimer (utf-8, lf line breaks, no trailing
// newline), published in PROVIDER_CONTRACT.md for every example to check
const consentDisclaimerSha256 = "83edee1e45cccd5deb6b86755cc5f6a91b6ade26e7eefc1e7670b5833a95502c"

// Runs every check and returns the first failure.
func runSelfTest() error {
	checks := []func() error{
		checkConsentDisclaimer,
		checkFormatByteCount,
		checkStatusText,
		checkStatusLines,
		checkStatusKey,
		checkProviderState,
		checkPayoutWalletScope,
		checkClientsServed,
		checkClientJwtClaims,
		checkStateFiles,
		checkProviderConfig,
	}
	for _, check := range checks {
		if err := check(); err != nil {
			return err
		}
	}
	return nil
}

// The disclaimer is the contract's exact text.
func checkConsentDisclaimer() error {
	digest := sha256.Sum256([]byte(consentDisclaimer))
	if hex.EncodeToString(digest[:]) != consentDisclaimerSha256 {
		return errors.New("consent disclaimer differs from PROVIDER_CONTRACT.md")
	}
	return nil
}

// Byte counts use binary units with one decimal.
func checkFormatByteCount() error {
	cases := []struct {
		byteCount int64
		text      string
	}{
		{byteCount: 0, text: "0 B"},
		{byteCount: 1023, text: "1023 B"},
		{byteCount: 1024, text: "1.0 KiB"},
		{byteCount: 1536, text: "1.5 KiB"},
		{byteCount: 1048575, text: "1.0 MiB"},
		{byteCount: 13002342, text: "12.4 MiB"},
		{byteCount: 5 * 1024 * 1024 * 1024, text: "5.0 GiB"},
		{byteCount: 3 * 1024 * 1024 * 1024 * 1024, text: "3.0 TiB"},
	}
	for _, c := range cases {
		if text := formatByteCount(c.byteCount); text != c.text {
			return fmt.Errorf("byte count %d formats as %q, want %q", c.byteCount, text, c.text)
		}
	}
	return nil
}

// The client limit status names the sdk's retry time in UTC, rounded up to the
// next whole minute; other states never show it.
func checkStatusText() error {
	cases := []struct {
		state                string
		clientLimitRetryTime int64
		text                 string
	}{
		// 2026-10-06 19:05:00.000 UTC, exactly on a minute
		{state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, text: "client limit, retry at 19:05 UTC"},
		// 19:04:00.001 rounds up, so the shown time is never before the retry
		{state: providerStateClientLimit, clientLimitRetryTime: 1791313440001, text: "client limit, retry at 19:05 UTC"},
		// no retry time
		{state: providerStateClientLimit, clientLimitRetryTime: 0, text: "client limit"},
		// 23:59:00.001 rolls over the hour and the day
		{state: providerStateClientLimit, clientLimitRetryTime: 1791331140001, text: "client limit, retry at 00:00 UTC"},
		{state: providerStateStarting, clientLimitRetryTime: 1791313500000, text: "starting"},
	}
	for _, c := range cases {
		if text := providerStatusText(c.state, c.clientLimitRetryTime); text != c.text {
			return fmt.Errorf("status text %q for %q retrying at %d, want %q", text, c.state, c.clientLimitRetryTime, c.text)
		}
	}
	return nil
}

// The status line matches the contract's golden lines.
func checkStatusLines() error {
	cases := []struct {
		status providerStatus
		line   string
	}{
		{
			status: providerStatus{state: providerStateStarting, payoutWallet: payoutWalletChecking},
			line:   "status: starting | clients served: 0 | data provided: 0 B | payout wallet: checking",
		},
		{
			status: providerStatus{state: providerStateProviding, clientsServed: 3, dataProvidedByteCount: 13002342, payoutWallet: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", payoutWalletScope: payoutWalletScopeNetwork},
			line:   "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY (network)",
		},
		{
			status: providerStatus{state: providerStateProviding, clientsServed: 3, dataProvidedByteCount: 13002342, payoutWallet: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", payoutWalletScope: payoutWalletScopeHotkey},
			line:   "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY (hotkey)",
		},
		{
			status: providerStatus{state: providerStatePaused, clientsServed: clientsServedLimit, clientsServedAtLimit: true, dataProvidedByteCount: 1536, payoutWallet: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", payoutWalletScope: payoutWalletScopeProvider},
			line:   "status: paused | clients served: 100000+ | data provided: 1.5 KiB | payout wallet: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY (this provider)",
		},
		{
			status: providerStatus{state: providerStateStopped, payoutWallet: payoutWalletNotSet},
			line:   "status: stopped | clients served: 0 | data provided: 0 B | payout wallet: not set",
		},
		{
			status: providerStatus{state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, payoutWallet: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", payoutWalletScope: payoutWalletScopeNetwork},
			line:   "status: client limit, retry at 19:05 UTC | clients served: 0 | data provided: 0 B | payout wallet: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY (network)",
		},
	}
	for _, c := range cases {
		if line := c.status.String(); line != c.line {
			return fmt.Errorf("status line %q, want %q", line, c.line)
		}
	}
	return nil
}

// A change of the status text prints a line at once, including a new client
// limit retry time; the data counter alone does not.
func checkStatusKey() error {
	status := providerStatus{state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, payoutWallet: payoutWalletChecking}
	// 19:25 UTC
	retried := status
	retried.clientLimitRetryTime = 1791314700000
	if status.key() == retried.key() {
		return errors.New("a new client limit retry time does not print a status line")
	}
	counted := status
	counted.dataProvidedByteCount = 1536
	if status.key() != counted.key() {
		return errors.New("the data counter alone prints a status line")
	}
	return nil
}

// The providing state follows the provide mode, client limit, pause, enable
// and connected rules, in that order.
func checkProviderState() error {
	cases := []struct {
		provideMode       int
		clientLimitStatus string
		providePaused     bool
		provideEnabled    bool
		providerConnected bool
		state             string
	}{
		{provideMode: sdk.ProvideModeNone, provideEnabled: false, providerConnected: false, state: providerStateStopped},
		{provideMode: sdk.ProvideModeNetwork, provideEnabled: true, providerConnected: true, state: providerStateStopped},
		{provideMode: sdk.ProvideModePublic, provideEnabled: true, providerConnected: false, state: providerStateStarting},
		{provideMode: sdk.ProvideModePublic, provideEnabled: false, providerConnected: true, state: providerStateStarting},
		{provideMode: sdk.ProvideModePublic, provideEnabled: true, providerConnected: true, state: providerStateProviding},
		{provideMode: sdk.ProvideModePublic, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStatePaused},
		// the client limit comes after stopped and before every other state
		{provideMode: sdk.ProvideModeNetwork, clientLimitStatus: sdk.ClientLimitStatusExceeded, provideEnabled: true, providerConnected: true, state: providerStateStopped},
		{provideMode: sdk.ProvideModePublic, clientLimitStatus: sdk.ClientLimitStatusExceeded, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStateClientLimit},
		{provideMode: sdk.ProvideModePublic, clientLimitStatus: sdk.ClientLimitStatusExceeded, provideEnabled: false, providerConnected: false, state: providerStateClientLimit},
		{provideMode: sdk.ProvideModePublic, clientLimitStatus: sdk.ClientLimitStatusNone, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStatePaused},
	}
	for _, c := range cases {
		if state := providerState(c.provideMode, c.clientLimitStatus, c.providePaused, c.provideEnabled, c.providerConnected); state != c.state {
			return fmt.Errorf("provider state %q for %+v", state, c)
		}
	}
	return nil
}

// The payout wallet is labeled by its consent scope first, then by the owner
// of its mapping.
func checkPayoutWalletScope() error {
	clientId := "11111111-1111-1111-1111-111111111111"
	cases := []struct {
		walletConsentScope string
		walletClientId     string
		scope              string
	}{
		// a hotkey delegation is network-level but not the network's wallet
		{walletConsentScope: snWalletConsentScopeHotkey, walletClientId: "", scope: payoutWalletScopeHotkey},
		{walletConsentScope: snWalletConsentScopeHotkey, walletClientId: clientId, scope: payoutWalletScopeHotkey},
		{walletConsentScope: sdk.SnWalletConsentScopeNetwork, walletClientId: "", scope: payoutWalletScopeNetwork},
		{walletConsentScope: "", walletClientId: "", scope: payoutWalletScopeNetwork},
		{walletConsentScope: sdk.SnWalletConsentScopeProvider, walletClientId: clientId, scope: payoutWalletScopeProvider},
		{walletConsentScope: "", walletClientId: clientId, scope: payoutWalletScopeProvider},
		{walletConsentScope: sdk.SnWalletConsentScopeProvider, walletClientId: "22222222-2222-2222-2222-222222222222", scope: payoutWalletScopeAnotherProvider},
	}
	for _, c := range cases {
		if scope := payoutWalletScope(c.walletConsentScope, c.walletClientId, clientId); scope != c.scope {
			return fmt.Errorf("payout wallet scope %q for consent scope %q and client %q, want %q", scope, c.walletConsentScope, c.walletClientId, c.scope)
		}
	}
	return nil
}

// Contract peers resolve by direction and count once per client, up to the limit.
func checkClientsServed() error {
	parseId := func(text string) *sdk.Id {
		id, err := sdk.ParseId(text)
		if err != nil {
			panic(err)
		}
		return id
	}
	provider := parseId("11111111-1111-1111-1111-111111111111")
	clientA := parseId("22222222-2222-2222-2222-222222222222")
	clientB := parseId("33333333-3333-3333-3333-333333333333")
	stream := parseId("44444444-4444-4444-4444-444444444444")
	zero := parseId(zeroIdString)
	contract := func(contractId string, sourceId *sdk.Id, destinationId *sdk.Id, streamId *sdk.Id) *sdk.ContractDetails {
		return &sdk.ContractDetails{
			ContractId:           parseId(contractId),
			ContractTransferPath: sdk.NewTransferPath(sourceId, destinationId, streamId),
			Status:               sdk.ContractStatusOpen,
		}
	}

	// the peer is the source of a receive contract and the destination of a send contract
	keyCases := []struct {
		details *sdk.ContractDetails
		receive bool
		peerKey string
	}{
		{details: contract("55555555-5555-5555-5555-555555555555", clientA, provider, nil), receive: true, peerKey: clientA.String()},
		{details: contract("66666666-6666-6666-6666-666666666666", provider, clientA, nil), receive: false, peerKey: clientA.String()},
		{details: contract("77777777-7777-7777-7777-777777777777", zero, provider, stream), receive: true, peerKey: "stream:" + stream.String()},
		{details: contract("88888888-8888-8888-8888-888888888888", nil, nil, nil), receive: true, peerKey: "contract:88888888-8888-8888-8888-888888888888"},
	}
	for _, c := range keyCases {
		if peerKey := contractPeerKey(c.details, c.receive); peerKey != c.peerKey {
			return fmt.Errorf("contract peer key %q, want %q", peerKey, c.peerKey)
		}
	}

	// both directions of one client count once
	served := newClientsServed(2)
	served.Add(contract("55555555-5555-5555-5555-555555555555", clientA, provider, nil), true)
	served.Add(contract("66666666-6666-6666-6666-666666666666", provider, clientA, nil), false)
	served.Add(contract("99999999-9999-9999-9999-999999999999", clientA, provider, nil), true)
	if count, atLimit := served.Count(); count != 1 || atLimit {
		return fmt.Errorf("one client counted as %d (at limit %t)", count, atLimit)
	}
	served.Add(contract("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", clientB, provider, nil), true)
	if count, atLimit := served.Count(); count != 2 || atLimit {
		return fmt.Errorf("two clients counted as %d (at limit %t)", count, atLimit)
	}
	// a third distinct peer reaches the limit of 2
	served.Add(contract("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", zero, provider, stream), true)
	if count, atLimit := served.Count(); count != 2 || !atLimit {
		return fmt.Errorf("limited count %d (at limit %t)", count, atLimit)
	}
	return nil
}

// A synthetic, unsigned JWT with the given payload json.
func selfTestJwt(payloadJson string) string {
	return "e30." + base64.RawURLEncoding.EncodeToString([]byte(payloadJson)) + ".test"
}

// Only a JWT with a valid client_id claim is a client credential.
func checkClientJwtClaims() error {
	clientId, err := parseClientJwtClientId(selfTestJwt(`{"client_id":"11111111-1111-1111-1111-111111111111","network_id":"22222222-2222-2222-2222-222222222222"}`))
	if err != nil || clientId != "11111111-1111-1111-1111-111111111111" {
		return fmt.Errorf("client jwt claim %q (%v)", clientId, err)
	}
	invalidJwts := []string{
		"",
		"not-a-jwt",
		selfTestJwt(`{"network_id":"22222222-2222-2222-2222-222222222222"}`),
		selfTestJwt(`{"client_id":"not-a-uuid"}`),
		"e30.%%%.test",
	}
	for _, invalidJwt := range invalidJwts {
		if _, err := parseClientJwtClientId(invalidJwt); err == nil {
			return fmt.Errorf("invalid client jwt %q accepted", invalidJwt)
		}
	}
	return nil
}

// State files are private, replaced atomically, created once and bound to their client.
func checkStateFiles() error {
	stateDir, err := os.MkdirTemp("", "ur-provider-self-test-")
	if err != nil {
		return err
	}
	defer os.RemoveAll(stateDir)
	if err := os.Chmod(stateDir, 0o700); err != nil {
		return err
	}

	// an atomic private write
	path := filepath.Join(stateDir, clientJwtFileName)
	if err := writePrivateFile(path, []byte("first\n")); err != nil {
		return err
	}
	if err := writePrivateFile(path, []byte("second\n")); err != nil {
		return err
	}
	data, err := readPrivateFile(path)
	if err != nil || !bytes.Equal(data, []byte("second\n")) {
		return fmt.Errorf("private file round trip %q (%v)", data, err)
	}
	if runtime.GOOS != "windows" {
		info, err := os.Stat(path)
		if err != nil || info.Mode().Perm() != 0o600 {
			return fmt.Errorf("private file mode %v (%v)", info.Mode().Perm(), err)
		}
		// a file or directory that others can read is refused
		if err := os.Chmod(path, 0o644); err != nil {
			return err
		}
		if _, err := readPrivateFile(path); err == nil {
			return errors.New("a group-readable credential file was accepted")
		}
		if err := os.Chmod(stateDir, 0o755); err != nil {
			return err
		}
		if err := checkStateDir(stateDir); err == nil {
			return errors.New("a group-readable state directory was accepted")
		}
		if err := os.Chmod(stateDir, 0o700); err != nil {
			return err
		}
	}
	if err := checkStateDir(stateDir); err != nil {
		return err
	}

	// the instance id is created once and reused
	instanceId, err := loadOrCreateInstanceId(stateDir)
	if err != nil {
		return err
	}
	if _, err := sdk.ParseId(instanceId); err != nil {
		return fmt.Errorf("instance id %q is not a uuid", instanceId)
	}
	again, err := loadOrCreateInstanceId(stateDir)
	if err != nil || again != instanceId {
		return fmt.Errorf("instance id changed from %q to %q (%v)", instanceId, again, err)
	}

	// the identity belongs to its client
	clientId := "11111111-1111-1111-1111-111111111111"
	identity := &providerIdentity{
		Version:                  providerIdentityVersion,
		ClientId:                 clientId,
		ClientKeySeed:            bytes.Repeat([]byte{1}, 32),
		ProvideTlsCertificatePem: []byte("synthetic certificate"),
		ProvideTlsPrivateKeyPem:  []byte("synthetic private key"),
	}
	if err := saveProviderIdentity(stateDir, identity); err != nil {
		return err
	}
	loaded, err := loadProviderIdentity(stateDir, clientId)
	if err != nil || loaded == nil || !bytes.Equal(loaded.ClientKeySeed, identity.ClientKeySeed) || !bytes.Equal(loaded.ProvideTlsPrivateKeyPem, identity.ProvideTlsPrivateKeyPem) {
		return fmt.Errorf("identity round trip failed (%v)", err)
	}
	if keyMaterial := loaded.keyMaterial(); !bytes.Equal(keyMaterial.GetClientKeySeed(), identity.ClientKeySeed) {
		return errors.New("identity key material differs")
	}
	other, err := loadProviderIdentity(stateDir, "22222222-2222-2222-2222-222222222222")
	if err != nil || other != nil {
		return fmt.Errorf("another client's identity was used (%v)", err)
	}
	// without an identity the device gets no key material and makes a new identity
	if keyMaterial := other.keyMaterial(); keyMaterial != nil {
		return errors.New("a first run passes key material")
	}
	if err := writePrivateFile(filepath.Join(stateDir, identityFileName), []byte(`{"version":1}`)); err != nil {
		return err
	}
	if _, err := loadProviderIdentity(stateDir, clientId); err == nil {
		return errors.New("an invalid identity was accepted")
	}
	return nil
}

// A missing or incomplete installation state is refused; a first run loads.
func checkProviderConfig() error {
	if _, err := loadProviderConfig(""); err == nil {
		return errors.New("a missing state directory was accepted")
	}
	if _, err := loadProviderConfig("relative/state"); err == nil {
		return errors.New("a relative state directory was accepted")
	}
	stateDir, err := os.MkdirTemp("", "ur-provider-self-test-")
	if err != nil {
		return err
	}
	defer os.RemoveAll(stateDir)
	if err := os.Chmod(stateDir, 0o700); err != nil {
		return err
	}
	if _, err := loadProviderConfig(stateDir); err == nil {
		return errors.New("a state directory without client.jwt was accepted")
	}
	// a network jwt has no client_id claim
	networkJwt := selfTestJwt(`{"network_id":"22222222-2222-2222-2222-222222222222"}`)
	if err := writePrivateFile(filepath.Join(stateDir, clientJwtFileName), []byte(networkJwt+"\n")); err != nil {
		return err
	}
	if _, err := loadProviderConfig(stateDir); err == nil {
		return errors.New("a network jwt was accepted")
	}
	clientJwt := selfTestJwt(`{"client_id":"11111111-1111-1111-1111-111111111111"}`)
	if err := writePrivateFile(filepath.Join(stateDir, clientJwtFileName), []byte(clientJwt+"\n")); err != nil {
		return err
	}
	config, err := loadProviderConfig(stateDir)
	if err != nil {
		return err
	}
	if config.clientJwt != clientJwt || config.clientId != "11111111-1111-1111-1111-111111111111" || config.instanceId == "" || config.identity != nil {
		return errors.New("first-run configuration differs")
	}
	return nil
}