Developer SDK

Electron examples

Install the SDK · View source on GitHub ↗

provider/test/companion.test.mjs

javascript
// The companion child process: where the binary is, its environment (no
// credential, provider mode, a loopback port, stop on input close), its status
// route, the exit policy, and starting and stopping it, with a fake child and
// with a real process running fake-companion.mjs.

import {test} from "node:test";
import assert from "node:assert/strict";
import {EventEmitter} from "node:events";
import {PassThrough} from "node:stream";
import {fileURLToPath} from "node:url";
import {
  CompanionProcess,
  companionEnvironment,
  companionExitAction,
  companionPath,
  fetchProviderStatus,
  newCompanionToken,
  parseCompanionRoutes,
} from "../companion.mjs";
import {parseProviderStatus} from "../status.mjs";

const token = "a".repeat(64);

// the companion stand-in that a real child process runs
const fakeCompanionPath = fileURLToPath(new URL("./fake-companion.mjs", import.meta.url));

// A child process double: piped standard streams, a pid, recorded kills.
function fakeChild() {
  const child = new EventEmitter();
  child.pid = 4242;
  child.stdin = new PassThrough();
  child.stdout = new PassThrough();
  child.stderr = new PassThrough();
  child.stdinEnded = false;
  child.stdin.on("finish", () => {
    child.stdinEnded = true;
  });
  child.kills = [];
  child.kill = signal => child.kills.push(signal);
  return child;
}

// Timers that run only when the test fires them.
function fakeTimers() {
  const pending = new Map();
  let nextId = 1;
  return {
    pending,
    setTimeout: (callback, millis) => {
      const id = nextId;
      nextId += 1;
      pending.set(id, {callback, millis});
      return id;
    },
    clearTimeout: id => pending.delete(id),
    // Runs every pending timer once.
    fire: () => {
      const timers = [...pending.entries()];
      pending.clear();
      for (const [, timer] of timers) {
        timer.callback();
      }
    },
  };
}

// Resolves after the readline interfaces have read what was written.
function settle() {
  return new Promise(resolve => setImmediate(resolve));
}

test("the companion binary is in the resources when packaged and in bin/<platform>-<arch> in development", () => {
  assert.equal(
    companionPath({env: {}, isPackaged: true, resourcesPath: "/Applications/URnetwork Provider.app/Contents/Resources", appPath: "/ignored", platform: "darwin", arch: "arm64"}),
    "/Applications/URnetwork Provider.app/Contents/Resources/ur-companion",
  );
  assert.equal(
    companionPath({env: {}, isPackaged: false, resourcesPath: "/ignored", appPath: "/src/electron/provider", platform: "linux", arch: "x64"}),
    "/src/electron/provider/bin/linux-x64/ur-companion",
  );
  assert.match(
    companionPath({env: {}, isPackaged: false, resourcesPath: "/ignored", appPath: "/src/electron/provider", platform: "win32", arch: "x64"}),
    /bin[\\/]win32-x64[\\/]ur-companion\.exe$/,
  );
  assert.equal(companionPath({env: {URNETWORK_COMPANION_PATH: "/opt/ur-companion"}, isPackaged: true, resourcesPath: "/ignored", appPath: "/ignored", platform: "linux", arch: "x64"}), "/opt/ur-companion");
  assert.throws(() => companionPath({env: {URNETWORK_COMPANION_PATH: "bin/ur-companion"}, isPackaged: false, resourcesPath: "", appPath: "/src", platform: "linux", arch: "x64"}));
});

test("the companion environment selects provider mode and names no credential", () => {
  const parentEnv = {
    PATH: "/usr/bin",
    HOME: "/home/user",
    URNETWORK_CLIENT_JWT: "a-jwt-from-the-developer-shell",
    urnetwork_instance_id: "33333333-3333-3333-3333-333333333333",
    URNETWORK_COMPANION_ADDRESS: "127.0.0.1:8787",
  };
  assert.deepEqual(companionEnvironment(parentEnv, {stateDir: "/state/provider", token}), {
    PATH: "/usr/bin",
    HOME: "/home/user",
    URNETWORK_COMPANION_PROVIDE: "public",
    URNETWORK_PROVIDER_STATE_DIR: "/state/provider",
    URNETWORK_COMPANION_TOKEN: token,
    URNETWORK_COMPANION_ADDRESS: "127.0.0.1:0",
    URNETWORK_COMPANION_STOP_ON_STDIN_CLOSE: "1",
  });
});

test("a companion token is 32 random bytes in hex, new for each launch", () => {
  const first = newCompanionToken();
  assert.match(first, /^[0-9a-f]{64}$/);
  assert.notEqual(newCompanionToken(), first);
});

test("the status route comes from the companion's listening line on a numeric loopback address", () => {
  assert.deepEqual(parseCompanionRoutes("companion listening at http://127.0.0.1:54321/provider-status and ws://127.0.0.1:54321/device-rpc"), {
    statusUrl: "http://127.0.0.1:54321/provider-status",
  });
  assert.deepEqual(parseCompanionRoutes("companion listening at http://[::1]:8787/provider-status and ws://[::1]:8787/device-rpc\r"), {
    statusUrl: "http://[::1]:8787/provider-status",
  });
  for (const line of [
    "provider client 11111111-1111-1111-1111-111111111111, instance 22222222-2222-2222-2222-222222222222",
    "companion listening at http://127.0.0.1:1/provider-status and ws://127.0.0.1:2/device-rpc",
    "companion listening at http://192.0.2.1:1/provider-status and ws://192.0.2.1:1/device-rpc",
    "Companion for client 11111111-1111-1111-1111-111111111111, instance 1 listening at ws://127.0.0.1:8787/device-rpc",
  ]) {
    assert.equal(parseCompanionRoutes(line), null, line);
  }
});

test("the provider status read sends the token to the loopback route", async () => {
  const requests = [];
  const body = {ProvideMode: 3, ClientsServed: 2};
  const answers = [
    {ok: true, status: 200, json: async () => body},
    {ok: false, status: 401, json: async () => ({})},
  ];
  const fetchFunction = async url => {
    requests.push(url);
    return answers.shift();
  };
  assert.deepEqual(await fetchProviderStatus("http://127.0.0.1:54321/provider-status", token, fetchFunction), body);
  assert.deepEqual(requests, [`http://127.0.0.1:54321/provider-status?token=${token}`]);
  await assert.rejects(fetchProviderStatus("http://127.0.0.1:54321/provider-status", token, fetchFunction), /401/);
  await assert.rejects(fetchProviderStatus("http://203.0.113.1:54321/provider-status", token, fetchFunction), /loopback/);
  await assert.rejects(fetchProviderStatus("ws://127.0.0.1:54321/device-rpc", token, fetchFunction), /loopback/);
  await assert.rejects(fetchProviderStatus("http://127.0.0.1:54321/provider-status", "short", fetchFunction), /32 characters/);
});

test("the app restarts a failed companion but not after a stop or a configuration error", () => {
  const cases = [
    {exit: {code: 0, spawnFailed: false, stopRequested: false}, action: "stopped"},
    {exit: {code: 1, spawnFailed: false, stopRequested: true}, action: "stopped"},
    {exit: {code: null, spawnFailed: false, stopRequested: true}, action: "stopped"},
    {exit: {code: 78, spawnFailed: false, stopRequested: false}, action: "config"},
    {exit: {code: null, spawnFailed: true, stopRequested: false}, action: "config"},
    {exit: {code: 1, spawnFailed: false, stopRequested: false}, action: "restart"},
    {exit: {code: null, spawnFailed: false, stopRequested: false}, action: "restart"},
  ];
  for (const c of cases) {
    assert.equal(companionExitAction(c.exit), c.action, JSON.stringify(c.exit));
  }
});

test("a stop closes the companion's input and kills it only after the timeout", async () => {
  const children = [];
  const timers = fakeTimers();
  const spawnFunction = (command, args, options) => {
    const child = fakeChild();
    child.spawned = {command, args, options};
    children.push(child);
    return child;
  };

  // a companion that exits on its own after the input closes
  const companion = new CompanionProcess({command: "/opt/ur-companion", env: {URNETWORK_COMPANION_PROVIDE: "public"}, spawnFunction, timers});
  const child = children[0];
  assert.deepEqual(child.spawned.args, []);
  assert.deepEqual(child.spawned.options.stdio, ["pipe", "pipe", "pipe"]);
  assert.equal(child.spawned.options.windowsHide, true);
  child.stdout.write("companion listening at http://127.0.0.1:54321/provider-status and ws://127.0.0.1:54321/device-rpc\n");
  assert.deepEqual(await companion.routes, {statusUrl: "http://127.0.0.1:54321/provider-status"});
  const stopped = companion.stop();
  await settle();
  assert.equal(child.stdinEnded, true);
  assert.equal(timers.pending.size, 1);
  child.emit("close", 0, null);
  assert.deepEqual(await stopped, {code: 0, signal: null, spawnFailed: false});
  assert.equal(timers.pending.size, 0);
  assert.deepEqual(child.kills, []);

  // a companion that does not exit is killed when the timeout fires
  const stuck = new CompanionProcess({command: "/opt/ur-companion", env: {}, spawnFunction, timers});
  const stuckChild = children[1];
  const stuckStopped = stuck.stop();
  stuck.stop();
  assert.equal(timers.pending.size, 1);
  timers.fire();
  assert.deepEqual(stuckChild.kills, ["SIGKILL"]);
  stuckChild.emit("close", null, "SIGKILL");
  assert.deepEqual(await stuckStopped, {code: null, signal: "SIGKILL", spawnFailed: false});
  await assert.rejects(stuck.routes, /before it listened/);
});

test("the companion's last own error line explains its exit, not a later sdk log line", async () => {
  const child = fakeChild();
  const companion = new CompanionProcess({command: "/opt/ur-companion", env: {}, spawnFunction: () => child, timers: fakeTimers()});
  child.stderr.write("the server rejected the client credential; issue a new scoped client JWT from your backend\n");
  child.stderr.write("E1006 19:05:00.000001 1 device_local.go:1] synthetic sdk error while closing\n");
  child.stdout.write("status line on stdout\n");
  await settle();
  child.emit("close", 78, null);
  assert.equal((await companion.exited).code, 78);
  assert.equal(companion.lastErrorLine, "the server rejected the client credential; issue a new scoped client JWT from your backend");
});

test("a companion binary that cannot run is a configuration error", async () => {
  // a process that never started has no pid
  const child = fakeChild();
  child.pid = undefined;
  const companion = new CompanionProcess({command: "/opt/missing/ur-companion", env: {}, spawnFunction: () => child, timers: fakeTimers()});
  child.emit("error", Object.assign(new Error("spawn /opt/missing/ur-companion ENOENT"), {code: "ENOENT"}));
  child.emit("close", -2, null);
  const exit = await companion.exited;
  assert.deepEqual(exit, {code: null, signal: null, spawnFailed: true});
  assert.equal(companionExitAction({...exit, stopRequested: false}), "config");
  assert.match(companion.lastErrorLine, /could not run the companion at \/opt\/missing\/ur-companion/);

  // the same with a real spawn of a missing binary
  const missing = new CompanionProcess({command: "/nonexistent.example/ur-companion", env: {}});
  assert.deepEqual(await missing.exited, {code: null, signal: null, spawnFailed: true});
  assert.match(missing.lastErrorLine, /ENOENT/);
});

test("a real companion process reports its status route and status and stops when its input closes", async t => {
  const companion = new CompanionProcess({
    command: process.execPath,
    args: [fakeCompanionPath],
    env: companionEnvironment(process.env, {stateDir: "/state/provider", token}),
  });
  // a failed check still stops the child, whose pipes would keep the test alive
  t.after(() => companion.stop());
  const routes = await companion.routes;
  const deviceValues = parseProviderStatus(await fetchProviderStatus(routes.statusUrl, token));
  assert.equal(deviceValues.clientLimitStatus, "client_limit_exceeded");
  assert.equal(deviceValues.clientLimitRetryTime, 1791313500000);
  assert.equal(deviceValues.dataProvidedByteCount, 1536);
  assert.equal(deviceValues.clientsServed, 2);
  await assert.rejects(fetchProviderStatus(routes.statusUrl, "b".repeat(64)), /401/);
  const exit = await companion.stop();
  assert.equal(exit.code, 0);
  assert.equal(companionExitAction({...exit, stopRequested: companion.stopRequested}), "stopped");
  assert.ok(companion.recentLines.includes("status: stopped"));
});

test("a real companion with a configuration error exits 78 with its message", async t => {
  const companion = new CompanionProcess({
    command: process.execPath,
    args: [fakeCompanionPath],
    env: {...companionEnvironment(process.env, {stateDir: "/state/provider", token}), FAKE_COMPANION_EXIT: "78"},
  });
  t.after(() => companion.stop());
  const exit = await companion.exited;
  assert.equal(exit.code, 78);
  assert.equal(companionExitAction({...exit, stopRequested: false}), "config");
  assert.equal(companion.lastErrorLine, "client.jwt is missing; write the scoped client JWT from your backend");
  await assert.rejects(companion.routes, /before it listened/);
});