Developer SDK

Java examples

Install the SDK · View source on GitHub ↗

provider/SelfTest.java

java
// The credential-free self-test (PROVIDER_CONTRACT.md, "Self-test"). It
// checks the disclaimer, the status text, the providing state, the payout
// wallet labels, the clients-served count, the JSON values of the C ABI, the
// installation state files and the exit codes without a network, credentials,
// a device or the native SDK runtime: it never calls the SDK, so the native
// library never loads. `--self-test` runs every check and stops at the first
// failure; `mvn package` runs it too.
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.io.PrintStream;
import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.attribute.PosixFilePermissions;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.Comparator;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Stream;

/** The self-test checks. */
final class SelfTest {
  // sha-256 of the consent disclaimer (utf-8, lf line breaks, no trailing
  // newline), published in PROVIDER_CONTRACT.md for every example to check
  private static final String CONSENT_DISCLAIMER_SHA256 =
      "83edee1e45cccd5deb6b86755cc5f6a91b6ade26e7eefc1e7670b5833a95502c";

  // the public Substrate development account, used only as test data
  private static final String WALLET_A =
      "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
  // synthetic ids: the provider, two clients, a stream and contracts
  private static final String PROVIDER_ID = "11111111-1111-1111-1111-111111111111";
  private static final String CLIENT_A_ID = "22222222-2222-2222-2222-222222222222";
  private static final String CLIENT_B_ID = "33333333-3333-3333-3333-333333333333";
  private static final String STREAM_ID = "44444444-4444-4444-4444-444444444444";
  private static final String ZERO_ID = "00000000-0000-0000-0000-000000000000";

  /** A failed check. */
  static final class Failure extends Exception {
    private static final long serialVersionUID = 1;

    /** A failure with the check's message. */
    Failure(String message) { super(message); }
  }

  /** One check; a failure throws. */
  @FunctionalInterface
  private interface Check {
    /** Runs the check. */
    void run() throws Exception;
  }

  /** A call that must fail with an exception. */
  @FunctionalInterface
  private interface Refused {
    /** Runs the call. */
    void run() throws Exception;
  }

  /** Static members only. */
  private SelfTest() {}

  /** Runs every check and throws the first failure. */
  static void run() throws Exception {
    List<Check> checks = List.of(
        SelfTest::checkConsentDisclaimer, SelfTest::checkFormatByteCount,
        SelfTest::checkStatusText, SelfTest::checkStatusLines,
        SelfTest::checkStatusKey, SelfTest::checkProviderState,
        SelfTest::checkPayoutWalletScope, SelfTest::checkPayoutWalletReads,
        SelfTest::checkClientsServed, SelfTest::checkSdkValues,
        SelfTest::checkJson, SelfTest::checkClientJwtClaims,
        SelfTest::checkStateFiles, SelfTest::checkProviderConfig,
        SelfTest::checkStopBeforeStart, SelfTest::checkStopHook,
        SelfTest::checkExitCodes);
    for (Check check : checks) {
      check.run();
    }
  }

  /** The disclaimer is the contract's exact text. */
  private static void checkConsentDisclaimer() throws Exception {
    byte[] digest = MessageDigest.getInstance("SHA-256").digest(
        ProviderStatus.CONSENT_DISCLAIMER.getBytes(StandardCharsets.UTF_8));
    expect(HexFormat.of().formatHex(digest).equals(CONSENT_DISCLAIMER_SHA256),
           "consent disclaimer differs from PROVIDER_CONTRACT.md");
  }

  /** Byte counts use binary units with one decimal, rounded as the Go reference rounds. */
  private static void checkFormatByteCount() throws Failure {
    Object[][] cases = {
        {0L, "0 B"},
        {1023L, "1023 B"},
        {1024L, "1.0 KiB"},
        {1536L, "1.5 KiB"},
        {1048575L, "1.0 MiB"},
        {13002342L, "12.4 MiB"},
        {5L * 1024 * 1024 * 1024, "5.0 GiB"},
        {3L * 1024 * 1024 * 1024 * 1024, "3.0 TiB"},
        // exact halves round to the even tenth, as the contract and Go's
        // %.1f do: 1.25 KiB and 1.75 KiB
        {1280L, "1.2 KiB"},
        {1792L, "1.8 KiB"},
        {Long.MAX_VALUE, "8.0 EiB"},
    };
    for (Object[] c : cases) {
      String text = ProviderStatus.formatByteCount((Long)c[0]);
      expect(text.equals(c[1]), "byte count %s formats as \"%s\", want \"%s\""
                                    .formatted(c[0], text, c[1]));
    }
  }

  /**
   * The client limit status names the sdk's retry time in UTC, rounded up to the next whole
   * minute; other states never show it.
   */
  private static void checkStatusText() throws Failure {
    Object[][] cases = {
        // 2026-10-06 19:05:00.000 UTC, exactly on a minute
        {ProviderStatus.STATE_CLIENT_LIMIT, 1791313500000L,
         "client limit, retry at 19:05 UTC"},
        // 19:04:00.001 rounds up, so the shown time is never before the retry
        {ProviderStatus.STATE_CLIENT_LIMIT, 1791313440001L,
         "client limit, retry at 19:05 UTC"},
        // no retry time
        {ProviderStatus.STATE_CLIENT_LIMIT, 0L, "client limit"},
        // 23:59:00.001 rolls over the hour and the day
        {ProviderStatus.STATE_CLIENT_LIMIT, 1791331140001L,
         "client limit, retry at 00:00 UTC"},
        {ProviderStatus.STATE_STARTING, 1791313500000L, "starting"},
    };
    for (Object[] c : cases) {
      String text = ProviderStatus.statusText((String)c[0], (Long)c[1]);
      expect(text.equals(c[2]),
             "status text \"%s\" for \"%s\" retrying at %s, want \"%s\""
                 .formatted(text, c[0], c[1], c[2]));
    }
  }

  /** The status line matches the contract's golden lines. */
  private static void checkStatusLines() throws Failure {
    Object[][] cases = {
        {new ProviderStatus(ProviderStatus.STATE_STARTING, 0, 0, false, 0,
                            ProviderStatus.PAYOUT_WALLET_CHECKING, ""),
         "status: starting | clients served: 0 | data provided: 0 B | payout wallet: checking"},
        {new ProviderStatus(ProviderStatus.STATE_PROVIDING, 0, 3, false,
                            13002342, WALLET_A,
                            ProviderStatus.PAYOUT_WALLET_SCOPE_NETWORK),
         "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: %s (network)"
             .formatted(WALLET_A)},
        {new ProviderStatus(ProviderStatus.STATE_PROVIDING, 0, 3, false,
                            13002342, WALLET_A,
                            ProviderStatus.PAYOUT_WALLET_SCOPE_HOTKEY),
         "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: %s (hotkey)"
             .formatted(WALLET_A)},
        {new ProviderStatus(ProviderStatus.STATE_PAUSED, 0,
                            ProviderStatus.CLIENTS_SERVED_LIMIT, true, 1536,
                            WALLET_A,
                            ProviderStatus.PAYOUT_WALLET_SCOPE_PROVIDER),
         "status: paused | clients served: 100000+ | data provided: 1.5 KiB | payout wallet: %s (this provider)"
             .formatted(WALLET_A)},
        {new ProviderStatus(ProviderStatus.STATE_STOPPED, 0, 0, false, 0,
                            ProviderStatus.PAYOUT_WALLET_NOT_SET, ""),
         "status: stopped | clients served: 0 | data provided: 0 B | payout wallet: not set"},
        {new ProviderStatus(ProviderStatus.STATE_CLIENT_LIMIT, 1791313500000L,
                            0, false, 0, WALLET_A,
                            ProviderStatus.PAYOUT_WALLET_SCOPE_NETWORK),
         "status: client limit, retry at 19:05 UTC | clients served: 0 | data provided: 0 B | payout wallet: %s (network)"
             .formatted(WALLET_A)},
    };
    for (Object[] c : cases) {
      String line = ((ProviderStatus)c[0]).line();
      expect(line.equals(c[1]),
             "status line \"%s\", want \"%s\"".formatted(line, c[1]));
    }
  }

  /**
   * A change of the status text prints a line at once, including a new client limit retry time;
   * the data counter alone does not.
   */
  private static void checkStatusKey() throws Failure {
    ProviderStatus status = new ProviderStatus(
        ProviderStatus.STATE_CLIENT_LIMIT, 1791313500000L, 0, false, 0,
        ProviderStatus.PAYOUT_WALLET_CHECKING, "");
    // 19:25 UTC
    ProviderStatus retried = new ProviderStatus(
        ProviderStatus.STATE_CLIENT_LIMIT, 1791314700000L, 0, false, 0,
        ProviderStatus.PAYOUT_WALLET_CHECKING, "");
    expect(!status.key().equals(retried.key()),
           "a new client limit retry time does not print a status line");
    ProviderStatus counted = new ProviderStatus(
        ProviderStatus.STATE_CLIENT_LIMIT, 1791313500000L, 0, false, 1536,
        ProviderStatus.PAYOUT_WALLET_CHECKING, "");
    expect(status.key().equals(counted.key()),
           "the data counter alone prints a status line");
  }

  /** The providing state follows the provide mode, client limit, pause, enable and connected rules, in that order. */
  private static void checkProviderState() throws Failure {
    String none = ProviderStatus.CLIENT_LIMIT_STATUS_NONE;
    String exceeded = ProviderStatus.CLIENT_LIMIT_STATUS_EXCEEDED;
    // provide mode, client limit status, paused, enabled, connected, state
    Object[][] cases = {
        {ProviderStatus.PROVIDE_MODE_NONE, none, false, false, false,
         ProviderStatus.STATE_STOPPED},
        {ProviderStatus.PROVIDE_MODE_NETWORK, none, false, true, true,
         ProviderStatus.STATE_STOPPED},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, none, false, true, false,
         ProviderStatus.STATE_STARTING},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, none, false, false, true,
         ProviderStatus.STATE_STARTING},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, none, false, true, true,
         ProviderStatus.STATE_PROVIDING},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, none, true, true, true,
         ProviderStatus.STATE_PAUSED},
        // the client limit comes after stopped and before every other state
        {ProviderStatus.PROVIDE_MODE_NETWORK, exceeded, false, true, true,
         ProviderStatus.STATE_STOPPED},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, exceeded, true, true, true,
         ProviderStatus.STATE_CLIENT_LIMIT},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, exceeded, false, false, false,
         ProviderStatus.STATE_CLIENT_LIMIT},
        {ProviderStatus.PROVIDE_MODE_PUBLIC, none, true, true, true,
         ProviderStatus.STATE_PAUSED},
    };
    for (Object[] c : cases) {
      String state = ProviderStatus.providerState(
          (Long)c[0], (String)c[1], (Boolean)c[2], (Boolean)c[3], (Boolean)c[4]);
      expect(state.equals(c[5]), "provider state \"" + state + "\" for " +
                                     Arrays.toString(c));
    }
  }

  /** The payout wallet is labeled by its consent scope first, then by the owner of its mapping. */
  private static void checkPayoutWalletScope() throws Failure {
    // wallet consent scope, wallet client id, label
    Object[][] cases = {
        // a hotkey delegation is network-level but not the network's wallet
        {ProviderStatus.SN_WALLET_CONSENT_SCOPE_HOTKEY, "",
         ProviderStatus.PAYOUT_WALLET_SCOPE_HOTKEY},
        {ProviderStatus.SN_WALLET_CONSENT_SCOPE_HOTKEY, PROVIDER_ID,
         ProviderStatus.PAYOUT_WALLET_SCOPE_HOTKEY},
        {ProviderStatus.SN_WALLET_CONSENT_SCOPE_NETWORK, "",
         ProviderStatus.PAYOUT_WALLET_SCOPE_NETWORK},
        {"", "", ProviderStatus.PAYOUT_WALLET_SCOPE_NETWORK},
        {ProviderStatus.SN_WALLET_CONSENT_SCOPE_PROVIDER, PROVIDER_ID,
         ProviderStatus.PAYOUT_WALLET_SCOPE_PROVIDER},
        {"", PROVIDER_ID, ProviderStatus.PAYOUT_WALLET_SCOPE_PROVIDER},
        {ProviderStatus.SN_WALLET_CONSENT_SCOPE_PROVIDER, CLIENT_A_ID,
         ProviderStatus.PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER},
    };
    for (Object[] c : cases) {
      String scope = ProviderStatus.payoutWalletScope((String)c[0],
                                                      (String)c[1], PROVIDER_ID);
      expect(scope.equals(c[2]),
             "payout wallet scope \"%s\" for consent scope \"%s\" and client \"%s\", want \"%s\""
                 .formatted(scope, c[0], c[1], c[2]));
    }
  }

  /**
   * The payout wallet shows checking until the first read, unavailable after a failed first read,
   * the last value after a later failure, and not set without a mapped wallet.
   */
  private static void checkPayoutWalletReads() throws Failure {
    ProviderStatus.PayoutWallet checking = ProviderStatus.PAYOUT_WALLET_BEFORE_READ;
    expect(checking.wallet().equals(ProviderStatus.PAYOUT_WALLET_CHECKING),
           "the payout wallet does not start as checking");
    ProviderStatus.PayoutWallet unavailable =
        ProviderStatus.payoutWalletAfterRead(checking, false, null, PROVIDER_ID);
    expect(unavailable.equals(new ProviderStatus.PayoutWallet(
               ProviderStatus.PAYOUT_WALLET_UNAVAILABLE, "")),
           "a failed first wallet read shows " + unavailable);
    ProviderStatus.PayoutWallet network = ProviderStatus.payoutWalletAfterRead(
        unavailable, true,
        new ProviderStatus.SnWallet(WALLET_A, "",
                                    ProviderStatus.SN_WALLET_CONSENT_SCOPE_NETWORK),
        PROVIDER_ID);
    expect(network.equals(new ProviderStatus.PayoutWallet(
               WALLET_A, ProviderStatus.PAYOUT_WALLET_SCOPE_NETWORK)),
           "a network wallet shows " + network);
    ProviderStatus.PayoutWallet kept =
        ProviderStatus.payoutWalletAfterRead(network, false, null, PROVIDER_ID);
    expect(kept.equals(network), "a later failed read shows " + kept);
    ProviderStatus.PayoutWallet notSet =
        ProviderStatus.payoutWalletAfterRead(network, true, null, PROVIDER_ID);
    expect(notSet.equals(new ProviderStatus.PayoutWallet(
               ProviderStatus.PAYOUT_WALLET_NOT_SET, "")),
           "a read without a wallet shows " + notSet);
  }

  /** Contract peers resolve by direction from the c abi's JSON and count once per client, up to the limit. */
  private static void checkClientsServed() throws Failure {
    // the peer is the source of a receive contract and the destination of a send contract
    Object[][] keyCases = {
        {contractJson("55555555-5555-5555-5555-555555555555", CLIENT_A_ID,
                      PROVIDER_ID, null),
         true, CLIENT_A_ID},
        {contractJson("66666666-6666-6666-6666-666666666666", PROVIDER_ID,
                      CLIENT_A_ID, null),
         false, CLIENT_A_ID},
        {contractJson("77777777-7777-7777-7777-777777777777", ZERO_ID,
                      PROVIDER_ID, STREAM_ID),
         true, "stream:" + STREAM_ID},
        {contractJson("88888888-8888-8888-8888-888888888888", null, null, null),
         true, "contract:88888888-8888-8888-8888-888888888888"},
        // nothing to key by
        {"null", true, ""},
        {"""
         {"ContractId":null,"ContractTransferPath":null,"Status":"open"}""",
         true, ""},
    };
    for (Object[] c : keyCases) {
      String peerKey = ProviderStatus.contractPeerKey((String)c[0], (Boolean)c[1]);
      expect(peerKey.equals(c[2]), "contract peer key \"%s\", want \"%s\" for %s"
                                       .formatted(peerKey, c[2], c[0]));
    }

    // both directions of one client count once
    ProviderStatus.ClientsServed served = new ProviderStatus.ClientsServed(2);
    served.add(ProviderStatus.contractPeerKey(
        contractJson("55555555-5555-5555-5555-555555555555", CLIENT_A_ID,
                     PROVIDER_ID, null),
        true));
    served.add(ProviderStatus.contractPeerKey(
        contractJson("66666666-6666-6666-6666-666666666666", PROVIDER_ID,
                     CLIENT_A_ID, null),
        false));
    served.add(ProviderStatus.contractPeerKey(
        contractJson("99999999-9999-9999-9999-999999999999", CLIENT_A_ID,
                     PROVIDER_ID, null),
        true));
    expect(served.count().equals(new ProviderStatus.ClientsServed.Count(1, false)),
           "one client counted as " + served.count());
    served.add(ProviderStatus.contractPeerKey(
        contractJson("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", CLIENT_B_ID,
                     PROVIDER_ID, null),
        true));
    expect(served.count().equals(new ProviderStatus.ClientsServed.Count(2, false)),
           "two clients counted as " + served.count());
    // a third distinct peer reaches the limit of 2
    served.add(ProviderStatus.contractPeerKey(
        contractJson("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", ZERO_ID,
                     PROVIDER_ID, STREAM_ID),
        true));
    expect(served.count().equals(new ProviderStatus.ClientsServed.Count(2, true)),
           "limited count " + served.count());
  }

  /** The c abi's JSON values read as the contract's examples show them. */
  private static void checkSdkValues() throws Exception {
    ProviderStatus.ClientLimit clientLimit = ProviderStatus.parseClientLimit("""
        {"Status": "client_limit_exceeded", "RetryTime": 1791313500000}""");
    expect(clientLimit.equals(new ProviderStatus.ClientLimit(
               ProviderStatus.CLIENT_LIMIT_STATUS_EXCEEDED, 1791313500000L)),
           "the client limit status reads as " + clientLimit);
    expect(ProviderStatus.parseClientLimit("""
               {"Status": "", "RetryTime": 0}""")
               .equals(ProviderStatus.NO_CLIENT_LIMIT),
           "no client limit does not read as none");
    // NULL: the call could not run, read as no limit
    expect(ProviderStatus.parseClientLimit(null).equals(
               ProviderStatus.NO_CLIENT_LIMIT),
           "a NULL client limit status does not read as none");

    expect(ProviderStatus.dataProvidedByteCount("""
               {"RemoteEgressByteCount": 5, "RemoteIngressByteCount": 7, "LocalEgressByteCount": 11}""") == 12,
           "data provided is not the remote egress and ingress bytes");
    expect(ProviderStatus.dataProvidedByteCount(null) == 0 &&
               ProviderStatus.dataProvidedByteCount("null") == 0,
           "null packet stats are not 0 bytes");

    ProviderStatus.SnWallet wallet = ProviderStatus.parseSnWallet("""
        {"coldkey_ss58": "%s", "client_id": "%s", "set_at_millis": 1, "consent_scope": "provider"}"""
        .formatted(WALLET_A, PROVIDER_ID));
    expect(wallet != null &&
               wallet.equals(new ProviderStatus.SnWallet(
                   WALLET_A, PROVIDER_ID,
                   ProviderStatus.SN_WALLET_CONSENT_SCOPE_PROVIDER)),
           "the wallet does not read: " + wallet);
    ProviderStatus.SnWallet networkWallet = ProviderStatus.parseSnWallet("""
        {"coldkey_ss58": "%s", "set_at_millis": 1, "consent_scope": "network"}"""
        .formatted(WALLET_A));
    expect(networkWallet != null && networkWallet.clientId().isEmpty(),
           "a network wallet has a client id");
    expect(ProviderStatus.parseSnWallet(null) == null &&
               ProviderStatus.parseSnWallet("null") == null,
           "no wallet reads as a wallet");

    expect(ProviderStatus.walletReadSucceeded("""
               {"wallet": {"coldkey_ss58": "%s", "set_at_millis": 1}, "wallets": []}"""
                   .formatted(WALLET_A),
               null),
           "a wallet result reads as a failure");
    expect(ProviderStatus.walletReadSucceeded("{}", null),
           "an empty wallet result reads as a failure");
    expect(!ProviderStatus.walletReadSucceeded("""
               {"error": {"message": "synthetic failure"}}""", null),
           "a wallet result error reads as a success");
    expect(!ProviderStatus.walletReadSucceeded(null, "synthetic network error"),
           "a wallet callback error reads as a success");
    expect(!ProviderStatus.walletReadSucceeded("null", null),
           "a null wallet result reads as a success");
  }

  /** The JSON reader accepts JSON and only JSON, and the writer's output reads back. */
  private static void checkJson() throws Exception {
    Object value = Json.parse(
        " {\"a\": [1, -2.5e3, true, false, null, \"x\\u00e9\\n\\\"\\ud83d\\ude00\"], \"b\": {}} ");
    Map<String, Object> expected = new LinkedHashMap<>();
    expected.put("a", Arrays.asList(new BigDecimal("1"), new BigDecimal("-2.5e3"),
                                    true, false, null, "x\u00e9\n\"\ud83d\ude00"));
    expected.put("b", Map.of());
    expect(expected.equals(value), "json reads as " + value);
    expect(Json.parseObject("{\"a\":1,\"a\":2}").get("a").equals(new BigDecimal("2")),
           "a duplicate member does not keep its last value");
    expect(Json.parse("[".repeat(64) + "]".repeat(64)) != null,
           "64 nested arrays are refused");

    List<String> invalidTexts = List.of(
        "", " ", "{", "}", "{\"a\":}", "{\"a\":1,}", "[1,]", "[1 2]", "01",
        "1.", ".5", "-", "+1", "1e", "\"\\x\"", "\"unterminated",
        "\"tab\there\"", "{} x", "nul", "True", "{'a':1}", "{a:1}",
        "\"\\u12G4\"", "\"\\u\uff10\uff10\uff10\uff10\"", "\uff11",
        // an exponent beyond the range of BigDecimal's scale
        "1e2147483649", "[".repeat(65) + "]".repeat(65));
    for (String invalidText : invalidTexts) {
      expectRefused(() -> Json.parse(invalidText),
                    "invalid json accepted: " + invalidText);
    }

    Map<String, Object> members = new LinkedHashMap<>();
    members.put("text", "quote \" backslash \\ line\n tab\t control\u0001 \u00e9");
    members.put("count", 7);
    members.put("time", 1791313500000L);
    members.put("flag", true);
    members.put("missing", null);
    members.put("items", List.of(1, "x"));
    Map<String, Object> expectedMembers = new LinkedHashMap<>(members);
    expectedMembers.put("count", new BigDecimal(7));
    expectedMembers.put("time", new BigDecimal(1791313500000L));
    expectedMembers.put("items", List.of(new BigDecimal(1), "x"));
    expect(Json.parseObject(Json.write(members)).equals(expectedMembers),
           "written json reads back as " + Json.parseObject(Json.write(members)));
  }

  /** Only a JWT with a valid client_id claim is a client credential. */
  private static void checkClientJwtClaims() throws Exception {
    String clientId = InstallationState.parseClientJwtClientId(selfTestJwt("""
        {"client_id":"%s","network_id":"%s"}""".formatted(PROVIDER_ID, CLIENT_A_ID)));
    expect(clientId.equals(PROVIDER_ID), "client jwt claim " + clientId);
    // the claim is kept in canonical form
    String upperCaseClientId = InstallationState.parseClientJwtClientId(selfTestJwt("""
        {"client_id":"AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA"}"""));
    expect(upperCaseClientId.equals("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
           "client jwt claim " + upperCaseClientId);
    List<String> invalidJwts = List.of(
        "", "not-a-jwt", "e30.e30", "e30..test",
        // a network jwt has no client_id claim
        selfTestJwt("""
            {"network_id":"%s"}""".formatted(CLIENT_A_ID)),
        selfTestJwt("""
            {"client_id":"not-a-uuid"}"""),
        selfTestJwt("""
            {"client_id":11111111}"""),
        selfTestJwt("""
            ["%s"]""".formatted(PROVIDER_ID)),
        "e30.%%%.test");
    for (String invalidJwt : invalidJwts) {
      expectRefused(() -> InstallationState.parseClientJwtClientId(invalidJwt),
                    "invalid client jwt accepted: " + invalidJwt);
    }
  }

  /** State files are private, replaced atomically, created once and bound to their client. */
  private static void checkStateFiles() throws Exception {
    Path stateDir = newPrivateTempDir();
    try {
      boolean posix = InstallationState.hasPosixPermissions(stateDir);

      // an atomic private write leaves no temporary file behind
      Path path = stateDir.resolve(InstallationState.CLIENT_JWT_FILE_NAME);
      InstallationState.writePrivateFile(path, utf8("first\n"));
      InstallationState.writePrivateFile(path, utf8("second\n"));
      expect(Arrays.equals(InstallationState.readPrivateFile(path), utf8("second\n")),
             "private file round trip");
      expect(fileNames(stateDir).equals(List.of(InstallationState.CLIENT_JWT_FILE_NAME)),
             "the private write left " + fileNames(stateDir));
      if (posix) {
        expect(Files.getPosixFilePermissions(path).equals(
                   InstallationState.OWNER_READ_WRITE),
               "private file mode " + Files.getPosixFilePermissions(path));
        // a file or directory that others can read is refused
        Files.setPosixFilePermissions(path, PosixFilePermissions.fromString("rw-r--r--"));
        expectRefused(() -> InstallationState.readPrivateFile(path),
                      "a group-readable credential file was accepted");
        Files.setPosixFilePermissions(path, InstallationState.OWNER_READ_WRITE);
        // a symlinked file is refused, so the credential cannot be redirected
        Path linkPath = stateDir.resolve("linked.jwt");
        Files.createSymbolicLink(linkPath, path);
        expectRefused(() -> InstallationState.readPrivateFile(linkPath),
                      "a symlinked credential file was accepted");
        Files.delete(linkPath);
        Files.setPosixFilePermissions(stateDir,
                                      PosixFilePermissions.fromString("rwxr-xr-x"));
        expectRefused(() -> InstallationState.checkStateDir(stateDir.toString()),
                      "a group-readable state directory was accepted");
        Files.setPosixFilePermissions(stateDir, InstallationState.OWNER_ALL);
      }
      InstallationState.checkStateDir(stateDir.toString());

      // the instance id is created once and reused
      String instanceId = InstallationState.loadOrCreateInstanceId(stateDir);
      expect(InstallationState.parseId(instanceId) != null,
             "instance id " + instanceId + " is not a uuid");
      String again = InstallationState.loadOrCreateInstanceId(stateDir);
      expect(again.equals(instanceId),
             "instance id changed from " + instanceId + " to " + again);

      // the identity belongs to its client
      InstallationState.ProviderIdentity identity = new InstallationState.ProviderIdentity(
          PROVIDER_ID, filled(32, 1), utf8("synthetic certificate"),
          utf8("synthetic private key"), filled(32, 2));
      InstallationState.saveProviderIdentity(stateDir, identity);
      InstallationState.ProviderIdentity loaded =
          InstallationState.loadProviderIdentity(stateDir, PROVIDER_ID);
      expect(loaded != null && sameIdentity(loaded, identity),
             "identity round trip failed");
      // another client's identity is not used: the device gets no key
      // material and makes a new identity
      expect(InstallationState.loadProviderIdentity(stateDir, CLIENT_A_ID) == null,
             "another client's identity was used");
      // the extender seed is optional
      InstallationState.ProviderIdentity withoutExtender =
          new InstallationState.ProviderIdentity(
              PROVIDER_ID, filled(32, 1), utf8("synthetic certificate"),
              utf8("synthetic private key"), new byte[0]);
      InstallationState.saveProviderIdentity(stateDir, withoutExtender);
      loaded = InstallationState.loadProviderIdentity(stateDir, PROVIDER_ID);
      expect(loaded != null && sameIdentity(loaded, withoutExtender),
             "identity without an extender seed failed");
      String seed31 = Base64.getEncoder().encodeToString(filled(31, 1));
      String seed32 = Base64.getEncoder().encodeToString(filled(32, 1));
      String certificate = Base64.getEncoder().encodeToString(utf8("synthetic certificate"));
      // the go reference writes an empty byte field as null
      Path identityPath = stateDir.resolve(InstallationState.IDENTITY_FILE_NAME);
      InstallationState.writePrivateFile(identityPath, utf8("""
          {"version":1,"client_id":"%s","client_key_seed":"%s","provide_tls_certificate_pem":"%s","provide_tls_private_key_pem":null}"""
          .formatted(PROVIDER_ID, seed32, certificate)));
      loaded = InstallationState.loadProviderIdentity(stateDir, PROVIDER_ID);
      expect(loaded != null &&
                 sameIdentity(loaded, new InstallationState.ProviderIdentity(
                                          PROVIDER_ID, filled(32, 1),
                                          utf8("synthetic certificate"),
                                          new byte[0], new byte[0])),
             "an identity with a null field failed");

      List<String> invalidIdentities = List.of(
          """
          {"version":1}""",
          "not json",
          "[]",
          """
          {"version":2,"client_id":"%s","client_key_seed":"%s"}""".formatted(PROVIDER_ID, seed32),
          """
          {"version":1,"client_id":"%s","client_key_seed":"%s"}""".formatted(PROVIDER_ID, seed31),
          """
          {"version":1,"client_id":"%s","client_key_seed":"not base64"}""".formatted(PROVIDER_ID),
          """
          {"version":"1","client_id":"%s","client_key_seed":"%s"}""".formatted(PROVIDER_ID, seed32));
      for (String invalidIdentity : invalidIdentities) {
        InstallationState.writePrivateFile(identityPath, utf8(invalidIdentity));
        expectRefused(() -> InstallationState.loadProviderIdentity(stateDir, PROVIDER_ID),
                      "an invalid identity was accepted: " + invalidIdentity);
      }
    } finally {
      deleteRecursively(stateDir);
    }
  }

  /** A missing or incomplete installation state is refused; a first run loads. */
  private static void checkProviderConfig() throws Exception {
    expectRefused(() -> InstallationState.load(""),
                  "a missing state directory was accepted");
    expectRefused(() -> InstallationState.load(null),
                  "an unset state directory was accepted");
    expectRefused(() -> InstallationState.load("relative/state"),
                  "a relative state directory was accepted");
    Path stateDir = newPrivateTempDir();
    try {
      expectRefused(() -> InstallationState.load(stateDir.toString()),
                    "a state directory without client.jwt was accepted");
      // a network jwt has no client_id claim
      String networkJwt = selfTestJwt("""
          {"network_id":"%s"}""".formatted(CLIENT_A_ID));
      Path clientJwtPath = stateDir.resolve(InstallationState.CLIENT_JWT_FILE_NAME);
      InstallationState.writePrivateFile(clientJwtPath, utf8(networkJwt + "\n"));
      expectRefused(() -> InstallationState.load(stateDir.toString()),
                    "a network jwt was accepted");
      String clientJwt = selfTestJwt("""
          {"client_id":"%s"}""".formatted(PROVIDER_ID));
      InstallationState.writePrivateFile(clientJwtPath, utf8(clientJwt + "\n"));
      InstallationState.ProviderConfig config =
          InstallationState.load(stateDir.toString());
      expect(config.clientJwt().equals(clientJwt) &&
                 config.clientId().equals(PROVIDER_ID) &&
                 InstallationState.parseId(config.instanceId()) != null &&
                 config.identity() == null,
             "first-run configuration differs: " + config);
      expect(!config.toString().contains(clientJwt),
             "the configuration prints the credential");
    } finally {
      deleteRecursively(stateDir);
    }
  }

  /**
   * Ctrl-C or SIGTERM can come while the provider starts: the shutdown hook then requests a stop
   * from a session that has not started. The session keeps the request, so it never starts, and
   * closing a session that never started makes no sdk call and prints nothing. Creating a session
   * makes no sdk call either.
   */
  private static void checkStopBeforeStart() throws Failure {
    ByteArrayOutputStream output = new ByteArrayOutputStream();
    ProviderSession session = newUnstartedSession(output);
    expect(!session.stopRequested(), "a new session has a stop requested");
    session.requestStop();
    expect(session.stopRequested(), "a stop requested before start is not kept");
    session.close();
    expect(output.size() == 0, "closing a session that never started printed " +
                                   output.toString(StandardCharsets.UTF_8));
  }

  /**
   * The shutdown hook always ends the process with the decided exit code, never with the JVM's
   * signal status (130, 143): with main's code when main closed the session first, and with 0 when
   * a signal came first, also when main then fails while it starts. The halt is recorded here
   * instead of run.
   */
  private static void checkStopHook() throws Exception {
    // main closed the session first, here after the server rejected the credential
    ProviderSession mainFirst = newUnstartedSession(new ByteArrayOutputStream());
    List<Integer> mainFirstHalts = Collections.synchronizedList(new ArrayList<>());
    Main.StopHook mainFirstHook = new Main.StopHook(mainFirst, mainFirstHalts::add);
    mainFirstHook.closed(Main.EXIT_CONFIG);
    mainFirstHook.stop();
    expect(mainFirstHalts.equals(List.of(Main.EXIT_CONFIG)),
           "after main's exit with 78 the hook ends the process with " + mainFirstHalts);
    expect(!mainFirst.stopRequested(), "after main's exit the hook requested a stop");

    // a signal came first: the hook requests the stop and waits for main to close
    ProviderSession signalFirst = newUnstartedSession(new ByteArrayOutputStream());
    List<Integer> signalFirstHalts = Collections.synchronizedList(new ArrayList<>());
    Main.StopHook signalFirstHook = new Main.StopHook(signalFirst, signalFirstHalts::add);
    Thread hookThread = new Thread(signalFirstHook::stop, "self-test-stop-hook");
    hookThread.start();
    // the requested stop shows that the hook found no exit code from main
    long deadline = System.nanoTime() + Duration.ofSeconds(30).toNanos();
    while (!signalFirst.stopRequested()) {
      expect(System.nanoTime() - deadline < 0, "the hook did not request a stop");
      Thread.onSpinWait();
    }
    // main then fails while it starts, and closes
    signalFirstHook.closed(Main.EXIT_FAILURE);
    hookThread.join(Duration.ofSeconds(30).toMillis());
    expect(signalFirstHalts.equals(List.of(Main.EXIT_STOPPED)),
           "after a signal the hook ends the process with " + signalFirstHalts);
  }

  /**
   * A usage error and a configuration error exit with 78 before anything loads the native
   * runtime; the provider prints the disclaimer before it reads the state.
   */
  private static void checkExitCodes() throws Failure {
    PrintStream discard = new PrintStream(OutputStream.nullOutputStream());
    for (String[] args : List.of(new String[] {"--unknown"},
                                 new String[] {"run", "extra"},
                                 new String[] {"--self-test", "extra"})) {
      int exitCode = Main.run(args, null, discard, discard);
      expect(exitCode == Main.EXIT_CONFIG, "usage error " + Arrays.toString(args) +
                                               " exits with " + exitCode);
    }
    for (String stateDir : Arrays.asList(null, "", "relative/state")) {
      ByteArrayOutputStream output = new ByteArrayOutputStream();
      int exitCode = Main.run(new String[] {"run"}, stateDir,
                              new PrintStream(output, true, StandardCharsets.UTF_8),
                              discard);
      expect(exitCode == Main.EXIT_CONFIG,
             "state directory \"" + stateDir + "\" exits with " + exitCode);
      expect(output.toString(StandardCharsets.UTF_8)
                 .startsWith(ProviderStatus.CONSENT_DISCLAIMER),
             "the provider does not print the disclaimer first");
    }
  }

  /** A session for a synthetic installation that has not started; it prints to output. */
  private static ProviderSession newUnstartedSession(ByteArrayOutputStream output) {
    InstallationState.ProviderConfig config = new InstallationState.ProviderConfig(
        Path.of("unused-state"), selfTestJwt("""
            {"client_id":"%s"}""".formatted(PROVIDER_ID)),
        PROVIDER_ID, "55555555-5555-5555-5555-555555555555", null);
    PrintStream printStream = new PrintStream(output, true, StandardCharsets.UTF_8);
    return new ProviderSession(config, printStream, printStream);
  }

  /** A synthetic, unsigned JWT with the given payload json. */
  private static String selfTestJwt(String payloadJson) {
    return "e30." +
        Base64.getUrlEncoder().withoutPadding().encodeToString(utf8(payloadJson)) +
        ".test";
  }

  /** The c abi's contract details JSON for one contract; a null id is JSON null. */
  private static String contractJson(String contractId, String sourceId,
                                     String destinationId, String streamId) {
    Map<String, Object> details = new LinkedHashMap<>();
    details.put("ContractId", contractId);
    details.put("ContractUsedByteCount", 0);
    details.put("ContractByteCount", 0);
    details.put("ContractBitRate", 0);
    if (sourceId == null && destinationId == null && streamId == null) {
      details.put("ContractTransferPath", null);
    } else {
      Map<String, Object> path = new LinkedHashMap<>();
      path.put("SourceId", sourceId);
      path.put("DestinationId", destinationId);
      path.put("StreamId", streamId);
      details.put("ContractTransferPath", path);
    }
    details.put("Status", "open");
    return Json.write(details);
  }

  /** Whether two identities hold the same client and keys. */
  private static boolean sameIdentity(InstallationState.ProviderIdentity a,
                                      InstallationState.ProviderIdentity b) {
    return a.clientId().equals(b.clientId()) &&
        Arrays.equals(a.clientKeySeed(), b.clientKeySeed()) &&
        Arrays.equals(a.provideTlsCertificatePem(), b.provideTlsCertificatePem()) &&
        Arrays.equals(a.provideTlsPrivateKeyPem(), b.provideTlsPrivateKeyPem()) &&
        Arrays.equals(a.extenderKeySeed(), b.extenderKeySeed());
  }

  /** A new temporary directory, private to its owner where the file system has POSIX permissions. */
  private static Path newPrivateTempDir() throws IOException {
    Path dir = Files.createTempDirectory("ur-provider-self-test-");
    if (InstallationState.hasPosixPermissions(dir)) {
      Files.setPosixFilePermissions(dir, InstallationState.OWNER_ALL);
    }
    return dir.toRealPath();
  }

  /** The sorted names in a directory. */
  private static List<String> fileNames(Path dir) throws IOException {
    try (Stream<Path> paths = Files.list(dir)) {
      return paths.map(path -> path.getFileName().toString()).sorted().toList();
    }
  }

  /** Deletes a directory tree. */
  private static void deleteRecursively(Path dir) throws IOException {
    List<Path> paths;
    try (Stream<Path> walk = Files.walk(dir)) {
      paths = new ArrayList<>(walk.sorted(Comparator.reverseOrder()).toList());
    }
    for (Path path : paths) {
      Files.deleteIfExists(path);
    }
  }

  /** count bytes of one value. */
  private static byte[] filled(int count, int value) {
    byte[] bytes = new byte[count];
    Arrays.fill(bytes, (byte)value);
    return bytes;
  }

  /** The utf-8 bytes of text. */
  private static byte[] utf8(String text) {
    return text.getBytes(StandardCharsets.UTF_8);
  }

  /** Fails with message unless condition holds. */
  private static void expect(boolean condition, String message) throws Failure {
    if (!condition) {
      throw new Failure(message);
    }
  }

  /** Fails with message unless the call throws. */
  private static void expectRefused(Refused call, String message) throws Failure {
    try {
      call.run();
    } catch (Exception e) {
      return;
    }
    throw new Failure(message);
  }
}