typescript // Runs each self-test check as a test, so `npm test` and `--self-test` cover
// the same behavior, and tests the exit codes, the companion child process and
// whole runs against a stand-in companion script, a stand-in token server and
// a stand-in cap API on loopback: no SDK device, credentials or network.
import assert from "node:assert/strict";
import {chmod, mkdir, mkdtemp, readFile, rm, writeFile} from "node:fs/promises";
import {createServer} from "node:http";
import type {AddressInfo} from "node:net";
import {tmpdir} from "node:os";
import {join} from "node:path";
import {test} from "node:test";
import {fileURLToPath} from "node:url";
import {CompanionProcess, companionEnvironment, freeLoopbackAddress, readEmbedStatus} from "./companion.ts";
import {isEntryPoint, run} from "./main.ts";
import {type StandInReply, selfTestChecks, selfTestJwt} from "./selftest.ts";
import {companionExitCode} from "./session.ts";
import type {EmbedStatus} from "./status.ts";
import {clientJwtFileName, writePrivateFile} from "./state.ts";
for (const selfTestCheck of selfTestChecks) {
test(selfTestCheck.name, async () => {
await selfTestCheck();
});
}
const clientA = "11111111-1111-1111-1111-111111111111";
const clientJwtA = selfTestJwt(`{"client_id":"${clientA}"}`);
const demoSession = "d".repeat(32);
// the stand-in companion: it serves /embed-status like the companion in embed
// mode (the k-th read answers the k-th body of FAKE_EMBED_STATUSES, then the
// last one), exits 0 when its standard input closes, and with FAKE_EXIT_CODE
// exits with that code after FAKE_EXIT_AFTER status reads
const fakeCompanionSource = `#!/usr/bin/env node
import {createServer} from "node:http";
const [host, port] = process.env.URNETWORK_COMPANION_ADDRESS.split(":");
const token = process.env.URNETWORK_COMPANION_TOKEN;
const statuses = JSON.parse(process.env.FAKE_EMBED_STATUSES);
const exitCode = process.env.FAKE_EXIT_CODE === undefined ? -1 : Number(process.env.FAKE_EXIT_CODE);
const exitAfter = Number(process.env.FAKE_EXIT_AFTER ?? "2");
let statusReadCount = 0;
const server = createServer((request, response) => {
const url = new URL(request.url, "http://127.0.0.1");
if (url.pathname !== "/embed-status" || url.searchParams.get("token") !== token ||
process.env.URNETWORK_COMPANION_EMBED !== "1" || process.env.URNETWORK_COMPANION_STOP_ON_STDIN_CLOSE !== "1" ||
process.env.URNETWORK_ROOT_JWT !== undefined || process.env.URNETWORK_DEMO_SESSION !== undefined) {
response.statusCode = 401;
response.end();
return;
}
const body = statuses[Math.min(statusReadCount, statuses.length - 1)];
statusReadCount += 1;
response.setHeader("Content-Type", "application/json");
response.end(JSON.stringify(body));
if (0 <= exitCode && statusReadCount === exitAfter) {
response.on("finish", () => process.exit(exitCode));
}
});
server.listen(Number(port), host);
process.stdin.on("end", () => process.exit(0));
process.stdin.resume();
`;
// The fields of an /embed-status body.
interface EmbedStatusFields {
providerStateAdded?: number | null;
clientLimitStatus?: string;
retryTime?: number;
contractStatus?: Record<string, boolean> | null;
}
// An /embed-status body.
function embedStatus({providerStateAdded = null, clientLimitStatus = "", retryTime = 0, contractStatus = null}: EmbedStatusFields = {}): Record<string, unknown> {
return {
ClientId: clientA,
InstanceId: "33333333-3333-3333-3333-333333333333",
WindowStatus: providerStateAdded === null ? null : {TargetSize: 4, MinSatisfied: true, ProviderStateAdded: providerStateAdded},
ClientLimitStatus: {Status: clientLimitStatus, RetryTime: retryTime},
ContractStatus: contractStatus,
};
}
// A fake installation: the state directory and the stand-in companion.
interface FakeInstallation {
stateDir: string;
companionPath: string;
remove: () => Promise<void>;
}
// A private state directory, optionally with a client.jwt, and the stand-in
// companion beside it; remove deletes both.
async function fakeInstallation({clientJwt = clientJwtA}: {clientJwt?: string | null} = {}): Promise<FakeInstallation> {
const rootDir = await mkdtemp(join(tmpdir(), "ur-embed-test-"));
const stateDir = join(rootDir, "state");
await mkdir(stateDir, {mode: 0o700});
await chmod(stateDir, 0o700);
if (clientJwt !== null) {
await writePrivateFile(join(stateDir, clientJwtFileName), `${clientJwt}\n`);
}
const companionPath = join(rootDir, "fake-companion.mjs");
await writeFile(companionPath, fakeCompanionSource);
await chmod(companionPath, 0o755);
return {stateDir, companionPath, remove: () => rm(rootDir, {recursive: true, force: true})};
}
// A request the stand-in backend received.
interface BackendRequest {
method: string | undefined;
url: string | undefined;
authorization: string | undefined;
body: string;
}
// A running stand-in backend.
interface StandInBackend {
url: string;
requests: BackendRequest[];
close: () => Promise<void>;
}
// A stand-in backend on loopback: the token server's POST
// /urnetwork/client-token and the API's GET /network/client-data-cap, which
// answer the given replies. Records the requests.
async function standInBackend({tokenReply, capReply, capReplies = capReply === undefined ? [] : [capReply]}:
{tokenReply: StandInReply; capReply?: StandInReply; capReplies?: StandInReply[]}): Promise<StandInBackend> {
const requests: BackendRequest[] = [];
// the k-th cap read answers the k-th of capReplies, then the last one
let capReadCount = 0;
const server = createServer((request, response) => {
const chunks: Buffer[] = [];
request.on("data", (chunk: Buffer) => chunks.push(chunk));
request.on("end", () => {
requests.push({method: request.method, url: request.url, authorization: request.headers.authorization, body: Buffer.concat(chunks).toString("utf8")});
let reply = tokenReply;
if (request.url !== "/urnetwork/client-token") {
reply = capReplies[Math.min(capReadCount, capReplies.length - 1)];
capReadCount += 1;
}
response.statusCode = reply.status;
response.setHeader("Content-Type", "application/json");
response.end(reply.body);
});
});
await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
return {
url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
requests,
close: () => new Promise<void>(resolve => server.close(() => resolve())),
};
}
// Reads the companion's status until it answers; the deadline only bounds a
// failure.
async function waitForEmbedStatus(address: string, token: string): Promise<EmbedStatus> {
const deadline = Date.now() + 20 * 1000;
while (true) {
try {
return await readEmbedStatus(address, token);
} catch (error) {
if (deadline <= Date.now()) {
throw error;
}
await new Promise(resolve => setTimeout(resolve, 50));
}
}
}
// A line collector for run.
function collector(): {lines: string[]; log: (message: string) => void} {
const lines: string[] = [];
return {lines, log: message => lines.push(message)};
}
test("the program runs as the entry point without import.meta.main", () => {
const url = new URL("./main.ts", import.meta.url).href;
const path = fileURLToPath(url);
assert.equal(isEntryPoint({main: true, url}, undefined), true);
assert.equal(isEntryPoint({main: false, url}, path), false);
// Node 24.0 and 24.1 have no import.meta.main
assert.equal(isEntryPoint({url}, path), true);
assert.equal(isEntryPoint({url}, fileURLToPath(new URL("./status.ts", import.meta.url))), false);
assert.equal(isEntryPoint({url}, undefined), false);
});
// the stand-in companion's answers to --licenses and --version, in embed mode
// only, as the companion prints them; FAKE_FAIL makes it exit 1
const fakeCompanionCommandsSource = `#!/usr/bin/env node
if (process.env.URNETWORK_COMPANION_EMBED !== "1" || process.env.URNETWORK_COMPANION_PROVIDE || process.env.FAKE_FAIL) {
process.exit(1);
}
const answers = {"--licenses": JSON.stringify([{Name: "fake", License: "MPL-2.0"}]), "--version": "URnetwork native embed companion test"};
process.stdout.write(answers[process.argv[2]] + "\\n");
`;
test("--licenses prints the companion's licenses JSON, and --version its version line", {skip: process.platform === "win32"}, async () => {
const rootDir = await mkdtemp(join(tmpdir(), "ur-embed-test-"));
try {
const path = join(rootDir, "fake-companion.mjs");
await writeFile(path, fakeCompanionCommandsSource);
await chmod(path, 0o755);
const lines: string[] = [];
const errors: string[] = [];
const options = {environment: {URNETWORK_COMPANION_PATH: path}, log: (message: string) => lines.push(message), error: (message: string) => errors.push(message)};
assert.equal(await run(["--licenses"], options), 0);
assert.deepEqual(JSON.parse(lines.at(-1) ?? ""), [{Name: "fake", License: "MPL-2.0"}]);
assert.equal(await run(["--version"], options), 0);
assert.equal(lines.at(-1), "URnetwork native embed companion test");
assert.deepEqual(errors, []);
// a companion that fails, and one that is missing
process.env.FAKE_FAIL = "1";
try {
assert.equal(await run(["--licenses"], options), 1);
} finally {
delete process.env.FAKE_FAIL;
}
assert.equal(await run(["--licenses"], {...options, environment: {URNETWORK_COMPANION_PATH: join(rootDir, "missing")}}), 1);
assert.match(errors.join("\n"), /build the native companion first/);
} finally {
await rm(rootDir, {recursive: true, force: true});
}
});
test("a usage error exits with 78", async () => {
const {lines, log} = collector();
assert.equal(await run(["--unknown"], {log: () => {}, error: log}), 78);
assert.match(lines.join("\n"), /usage/);
});
test("a configuration error exits with 78 before the companion starts", async () => {
const {lines, log} = collector();
assert.equal(await run([], {environment: {}, log, error: log}), 78);
assert.equal(await run(["run"], {environment: {URNETWORK_EMBED_STATE_DIR: join("relative", "state")}, log, error: log}), 78);
const installation = await fakeInstallation();
try {
const missingCompanion = {URNETWORK_EMBED_STATE_DIR: installation.stateDir, URNETWORK_COMPANION_PATH: join(installation.stateDir, "missing-companion")};
assert.equal(await run([], {environment: missingCompanion, log, error: log}), 78);
assert.match(lines.join("\n"), /build the native companion first/);
// one of the two token server settings
const halfTokenServer = {URNETWORK_EMBED_STATE_DIR: installation.stateDir, URNETWORK_COMPANION_PATH: installation.companionPath, URNETWORK_DEMO_SESSION: demoSession};
assert.equal(await run([], {environment: halfTokenServer, log, error: log}), 78);
} finally {
await installation.remove();
}
});
test("token server answers map to the exit codes before the companion starts", {skip: process.platform === "win32"}, async () => {
const cases: [StandInReply, number][] = [
[{status: 401, body: '{"error":{"code":"unauthorized","message":"unknown demo session"}}'}, 78],
[{status: 409, body: '{"error":{"code":"client_limit","message":"your network is at its client limit; see https://ur.io/services"}}'}, 78],
[{status: 502, body: '{"error":{"code":"upstream","message":"the URnetwork API failed"}}'}, 1],
];
for (const [tokenReply, exitCode] of cases) {
const installation = await fakeInstallation({clientJwt: null});
const backend = await standInBackend({tokenReply, capReply: {status: 404, body: "{}"}});
try {
const {lines, log} = collector();
const environment = {
URNETWORK_EMBED_STATE_DIR: installation.stateDir,
URNETWORK_COMPANION_PATH: installation.companionPath,
URNETWORK_TOKEN_SERVER_URL: backend.url,
URNETWORK_DEMO_SESSION: demoSession,
};
assert.equal(await run([], {environment, log, error: log}), exitCode);
const tokenError = (JSON.parse(tokenReply.body) as {error: {message: string}}).error.message;
assert.ok(lines.join("\n").includes(tokenError));
// the demo session is never printed
assert.ok(!lines.join("\n").includes(demoSession));
} finally {
await backend.close();
await installation.remove();
}
}
});
test("the companion stops when its standard input closes", {skip: process.platform === "win32"}, async () => {
const installation = await fakeInstallation();
try {
const token = "t".repeat(64);
const address = await freeLoopbackAddress();
const companion = new CompanionProcess(installation.companionPath, companionEnvironment(
{...process.env, URNETWORK_ROOT_JWT: "never forwarded", FAKE_EMBED_STATUSES: JSON.stringify([embedStatus({clientLimitStatus: "client_limit_exceeded", retryTime: 1791313500000})])},
{stateDir: installation.stateDir, token, address},
));
const status = await waitForEmbedStatus(address, token);
assert.equal(status.clientLimitStatus, "client_limit_exceeded");
assert.equal(status.clientLimitRetryTime, 1791313500000);
await assert.rejects(readEmbedStatus(address, "u".repeat(64)), /401/);
assert.equal(companion.exitInfo, null);
const exitInfo = await companion.stop();
assert.equal(exitInfo.code, 0);
assert.equal(companionExitCode(exitInfo), 0);
} finally {
await installation.remove();
}
});
test("a run with the token server fetches the client JWT, shows the caps and exits with the companion's 78", {skip: process.platform === "win32"}, async () => {
const installation = await fakeInstallation({clientJwt: null});
const dataCap = {client_id: clientA, monthly_byte_limit: 5000000000, monthly_used_byte_count: 1234567890, total_byte_limit: null, total_used_byte_count: 1234567890, capped: false, capped_reason: ""};
const backend = await standInBackend({
tokenReply: {status: 200, body: JSON.stringify({client_id: clientA, by_client_jwt: clientJwtA, data_cap: dataCap})},
capReply: {status: 200, body: JSON.stringify(dataCap)},
});
try {
const {lines, log} = collector();
const environment = {
...process.env,
URNETWORK_EMBED_STATE_DIR: installation.stateDir,
URNETWORK_COMPANION_PATH: installation.companionPath,
URNETWORK_TOKEN_SERVER_URL: backend.url,
URNETWORK_DEMO_SESSION: demoSession,
URNETWORK_API_URL: backend.url,
FAKE_EMBED_STATUSES: JSON.stringify([embedStatus({providerStateAdded: 2})]),
FAKE_EXIT_CODE: "78",
FAKE_EXIT_AFTER: "2",
};
const code = await run([], {environment, log, error: log});
const output = lines.join("\n");
assert.equal(code, 78);
assert.match(output, new RegExp(`^embed client ${clientA}, installation [0-9a-f-]{36}$`, "m"));
assert.match(output, /^status: connected \| data this month: 1\.2 GB of 5\.0 GB \| data total: no cap$/m);
assert.match(output, /the native companion exited \(78\)/);
// the token request carried the demo session and the installation's instance-id
const instanceId = (await readFile(join(installation.stateDir, "instance-id"), "utf8")).trim();
const tokenRequest = backend.requests.find(request => request.url === "/urnetwork/client-token");
assert.ok(tokenRequest !== undefined);
assert.equal(tokenRequest.authorization, `Bearer ${demoSession}`);
assert.deepEqual(JSON.parse(tokenRequest.body), {installation_id: instanceId});
assert.equal((await readFile(join(installation.stateDir, clientJwtFileName), "utf8")).trim(), clientJwtA);
// the token server's data_cap is the first reading: no cap read at start
assert.equal(backend.requests.filter(request => request.url === "/network/client-data-cap").length, 0);
assert.ok(!output.includes(demoSession));
} finally {
await backend.close();
await installation.remove();
}
});
test("the Embed-not-enabled refusal clears the cap reading of a run", {skip: process.platform === "win32"}, async () => {
const installation = await fakeInstallation();
const backend = await standInBackend({
tokenReply: {status: 500, body: "{}"},
capReplies: [
{status: 200, body: JSON.stringify({client_id: clientA, monthly_byte_limit: 5000000000, monthly_used_byte_count: 5000000000, capped: true, capped_reason: "monthly"})},
{status: 200, body: JSON.stringify({error: {message: "Embed isn't enabled for this network."}})},
],
});
try {
const {lines, log} = collector();
const environment = {
...process.env,
URNETWORK_EMBED_STATE_DIR: installation.stateDir,
URNETWORK_COMPANION_PATH: installation.companionPath,
URNETWORK_API_URL: backend.url,
// the contract status changes at the second read, which reads the caps again
FAKE_EMBED_STATUSES: JSON.stringify([
embedStatus({providerStateAdded: 3}),
embedStatus({providerStateAdded: 3, contractStatus: {InsufficientBalance: false, NoPermission: true, Premium: false}}),
]),
FAKE_EXIT_CODE: "1",
FAKE_EXIT_AFTER: "5",
};
assert.equal(await run([], {environment, log, error: log}), 1);
// the reading shows until the refusal clears it, unlike a failed read
const capped = lines.indexOf("status: data cap reached | data this month: 5.0 GB of 5.0 GB | data total: no cap");
const cleared = lines.indexOf("status: connected | data this month: unavailable | data total: unavailable");
assert.ok(0 <= capped && capped < cleared, lines.join("\n"));
assert.equal(backend.requests.filter(request => request.url === "/network/client-data-cap").length, 2);
} finally {
await backend.close();
await installation.remove();
}
});
test("a run without a token server reads the caps with the client JWT, again on a contract status change", {skip: process.platform === "win32"}, async () => {
const installation = await fakeInstallation();
const backend = await standInBackend({
tokenReply: {status: 500, body: "{}"},
capReply: {status: 200, body: JSON.stringify({client_id: clientA, monthly_byte_limit: 0, monthly_used_byte_count: 0, capped: true, capped_reason: "monthly"})},
});
try {
const {lines, log} = collector();
const environment = {
...process.env,
URNETWORK_EMBED_STATE_DIR: installation.stateDir,
URNETWORK_COMPANION_PATH: installation.companionPath,
URNETWORK_API_URL: backend.url,
FAKE_EMBED_STATUSES: JSON.stringify([
embedStatus({providerStateAdded: 0, clientLimitStatus: "client_limit_exceeded", retryTime: 1791313500000}),
embedStatus({providerStateAdded: 3}),
embedStatus({providerStateAdded: 3, contractStatus: {InsufficientBalance: false, NoPermission: true, Premium: false}}),
]),
FAKE_EXIT_CODE: "1",
FAKE_EXIT_AFTER: "4",
};
const code = await run([], {environment, log, error: log});
const output = lines.join("\n");
// a companion that fails exits the run with 1
assert.equal(code, 1);
assert.match(output, /^status: client limit, retry at 19:05 UTC \| data this month: (checking|0 B of 0 B) \| data total: (checking|no cap)$/m);
assert.match(output, /^status: paused \| data this month: 0 B of 0 B \| data total: no cap$/m);
assert.match(output, /the native companion exited \(1\)/);
const capRequests = backend.requests.filter(request => request.url === "/network/client-data-cap");
// read at start, and again when the contract status changed
assert.ok(2 <= capRequests.length, `${capRequests.length} cap reads`);
assert.ok(capRequests.every(request => request.authorization === `Bearer ${clientJwtA}`));
assert.equal(backend.requests.filter(request => request.url === "/urnetwork/client-token").length, 0);
} finally {
await backend.close();
await installation.remove();
}
});