brainchain-worker 0.2.3 → 0.2.4

package/README.md

@@ -62,7 +62,7 @@ Briefs are written by strangers, and some will try to get your agent to do somet
   | Supervisor | Settings |
   | --- | --- |
   | systemd | `KillMode=mixed` and `TimeoutStopSec=22min` in `[Service]` |
-  | Docker | `stop_grace_period: 22m` in Compose, or `docker run --stop-timeout 1320` |
+  | Docker | `stop_grace_period: 22m` in Compose, or `docker run --stop-timeout 1320`. Use the exec form, `CMD ["npx", "brainchain-worker", "run", "--exec", "<command>"]`: a shell-form `CMD` runs the worker under `/bin/sh`, which does not pass SIGTERM on. |
   | Kubernetes | `terminationGracePeriodSeconds: 1320` in the pod spec |
 
 ## Commands

package/dist/chain.js

@@ -82,17 +82,29 @@ function unquote(text) {
         return text;
     }
 }
-/** The parts of a URL long enough to be an API key: the path, the query and each of their segments. */
+/** The Basic credentials viem sends for a URL's user and password, which a server that echoes requests answers with. */
+function basicAuth(username, password) {
+    if (!username)
+        return [];
+    try {
+        return [btoa(`${decodeURIComponent(username)}:${decodeURIComponent(password)}`)];
+    }
+    catch {
+        return [];
+    }
+}
+/** The parts of a URL long enough to be an API key: its credentials, the path, the query and each of their segments. */
 function secretParts(url) {
     if (!URL.canParse(url))
         return [];
-    const { pathname, search } = new URL(url);
-    return [pathname + search, pathname, search, ...`${pathname}${search}`.split(/[/?&=]/)].filter((part) => part.length >= 8);
+    const { pathname, search, username, password } = new URL(url);
+    const path = pathname + search;
+    return [...basicAuth(username, password), username, password, path, pathname, search, ...path.split(/[/?&=]/)].filter((part) => part.length >= 8);
 }
 /**
- * One short line of an answer, without the RPC URL's path or query: an answer
- * can echo the path, which can hold an API key, and a web page is far longer
- * than one line.
+ * One short line of an answer, without the RPC URL's credentials, path or
+ * query: an answer can echo them, and they can hold an API key. A web page is
+ * far longer than one line.
  */
 function excerpt(details, url) {
     let line = unquote(details);
@@ -104,12 +116,41 @@ function excerpt(details, url) {
         .trim();
     return line.length > 160 ? `${line.slice(0, 159)}…` : line;
 }
+/** A 2xx answer in JSON that is no JSON-RPC reply, such as a REST API's. */
+class NotRpcError extends Error {
+    excerpt;
+    /** One short line of the answer, without the URL's secrets. */
+    constructor(excerpt) {
+        super("The answer is not a JSON-RPC reply");
+        this.excerpt = excerpt;
+    }
+}
+const isReply = (value) => typeof value === "object" && value !== null && ("result" in value || ("error" in value && typeof value.error === "object" && value.error !== null));
+/** viem reads an answer without a result as an empty one, and fails later on whatever needed it, such as "Block could not be found." */
+async function checkReply(response, url) {
+    if (!response.ok)
+        return;
+    const text = await response.clone().text();
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        // viem names an answer that is not JSON itself.
+        return;
+    }
+    // The excerpt is cut here, where the URL still holds the credentials viem leaves out of its errors.
+    if (!(Array.isArray(value) ? value.every(isReply) : isReply(value)))
+        throw new NotRpcError(excerpt(text, url));
+}
 /** A request that failed, named by the RPC's host and the status it answered with. */
 function requestFailure(request) {
     const host = hostOf(request.url);
     // viem passes on a 2xx answer that does not parse as JSON as the parser's error.
     if (request.cause instanceof SyntaxError)
         return `${host} answered, but not as an RPC`;
+    if (request.cause instanceof NotRpcError)
+        return `${host} answered, but not as an RPC (${request.cause.excerpt})`;
     const details = request.details ? excerpt(request.details, request.url) : "";
     const status = request instanceof TimeoutError ? undefined : request.status;
     if (status === undefined)
@@ -146,7 +187,7 @@ export async function unhealthy(service, fetcher = fetch) {
 }
 export function createChain(network, account, store = memoryStore()) {
     const chain = chainOf(network);
-    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3 });
+    const transport = http(network.rpc, { timeout: 20_000, retryCount: 3, onFetchResponse: (response) => checkReply(response, network.rpc) });
     // BrainChain mines a block per transaction, so receipts are polled every second.
     const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain, transport });

package/dist/index.js

@@ -219,7 +219,7 @@ async function run(network, { key, account }, values, once) {
     lock(`${file}.lock`);
     const store = fileStore(`${file}.json`, network.contracts.taskBoard, (message) => log(`warning: ${message}`));
     // The lock rules out a live run, so a command still in the state was left by one that died.
-    stopLeftover(store, log);
+    await stopLeftover(store, log);
     const chain = createChain(network, account, store);
     const command = shellCommand(exec);
     // An idle stop keeps the exit code of a task that failed earlier in a --once pass.
@@ -238,10 +238,19 @@ async function run(network, { key, account }, values, once) {
     });
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
         process.on(signal, stop.signal);
-    const gas = await chain.ethBalance().catch((error) => {
+    let gas;
+    try {
+        gas = await chain.ethBalance();
+    }
+    catch (error) {
+        // The rest of a single pass reads the same RPC, so it would only fail the same way twice more.
+        if (once) {
+            log(`could not read the chain: ${reason(error)}`);
+            process.exitCode = 1;
+            return;
+        }
         log(`could not read the wallet's ETH balance: ${reason(error)}`);
-        return undefined;
-    });
+    }
     if (gas === 0n)
         throw noGas(chain, network);
     const [line, sick] = await Promise.all([
@@ -252,8 +261,12 @@ async function run(network, { key, account }, values, once) {
     if (sick)
         log(`warning: ${sick}`);
     if (once) {
-        const result = await work.round();
-        if (result.hired === 0 && result.delivered === 0)
+        const result = await work.round().catch((error) => {
+            log(`round failed: ${reason(error)}`);
+            process.exitCode = 1;
+            return undefined;
+        });
+        if (result?.hired === 0 && result.delivered === 0)
             log("no task is hired to this worker right now");
         return;
     }

package/dist/state.js

@@ -6,10 +6,35 @@ const empty = (board) => ({ board: board.toLowerCase(), tasks: {}, done: [] });
 export function memoryStore(board = "") {
     return { state: empty(board), save: () => undefined };
 }
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+const isHash = (value) => typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value);
+const isIds = (value) => Array.isArray(value) && value.every((id) => typeof id === "string" && /^\d+$/.test(id));
+function isTask(value) {
+    if (!isObject(value) || !isCount(value.failures) || !isCount(value.nextAt))
+        return false;
+    if (value.result !== undefined && typeof value.result !== "string")
+        return false;
+    if (value.tx !== undefined && !isHash(value.tx))
+        return false;
+    return value.stored === undefined || (isObject(value.stored) && typeof value.stored.uri === "string" && isHash(value.stored.hash));
+}
+/** Whether a parsed file is a state this worker can go on from; any other shape fails every round that reads it. */
+function isState(value) {
+    if (!isObject(value) || typeof value.board !== "string" || !isObject(value.tasks) || !isIds(value.done))
+        return false;
+    if (!Object.values(value.tasks).every(isTask))
+        return false;
+    const { hired, command } = value;
+    if (hired !== undefined && !(isObject(hired) && isCount(hired.block) && isIds(hired.tasks)))
+        return false;
+    // Group 0 is this process's own and -1 is every process, so only a real command's group is signalled.
+    return command === undefined || (isObject(command) && isCount(command.pgid) && command.pgid > 1 && isCount(command.startedAt));
+}
 function parse(text) {
     try {
         const value = JSON.parse(text);
-        return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+        return isState(value) ? value : undefined;
     }
     catch {
         return undefined;
@@ -28,12 +53,12 @@ export function fileStore(file, board, warn = console.warn) {
     }
     const saved = text === undefined ? undefined : parse(text);
     if (saved?.board === state.board)
-        state = { ...state, ...saved, tasks: saved.tasks ?? {}, done: saved.done ?? [] };
+        state = saved;
     if (text !== undefined && saved === undefined) {
         // Refusing to start would turn one bad file into a crash loop under a supervisor.
         const aside = `${file}.corrupt-${new Date().toISOString().replace(/\.\d+Z$/, "Z").replace(/[-:]/g, "")}`;
         renameSync(file, aside);
-        warn(`${file} was not valid JSON, so it was moved to ${aside} and this run starts with no saved work`);
+        warn(`${file} could not be read as saved worker state, so it was moved to ${aside} and this run starts with no saved work`);
     }
     return {
         state,

package/dist/work.js

@@ -79,32 +79,72 @@ function signalGroup(pid, signal) {
             throw error;
     }
 }
+/** One field of `ps` for a process, or undefined when it is gone or ps cannot tell. */
+function ps(pid, field) {
+    const result = spawnSync("ps", ["-o", `${field}=`, "-p", String(pid)], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
 /** When a process started, in ms since the epoch, or undefined when it is gone or ps cannot tell. */
 function startTime(pid) {
-    const ps = spawnSync("ps", ["-o", "etime=", "-p", String(pid)], { encoding: "utf8" });
-    const elapsed = /^\s*(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)\s*$/.exec(ps.stdout ?? "");
-    if (ps.status !== 0 || !elapsed)
+    const elapsed = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(ps(pid, "etime") ?? "");
+    if (!elapsed)
         return undefined;
     const [days, hours, minutes, seconds] = elapsed.slice(1).map((part) => Number(part ?? 0));
     return Date.now() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
 }
+function exists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Whether a process group still has a process this user can signal. */
+function groupAlive(pgid) {
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a group lives on without its leader, as when the shell exits while
+ * what it started runs on. Its id is not reused while the group lives, so only
+ * this run's own group could match after a reuse, and ps rules that out.
+ */
+function orphaned(pgid) {
+    if (exists(pgid) || !groupAlive(pgid))
+        return false;
+    const own = ps(process.pid, "pgid");
+    return own !== undefined && own !== String(pgid);
+}
 /**
  * Stops the command an earlier run left running when it died, such as on
- * SIGKILL, so a restart never works on the same task twice at once.
+ * SIGKILL, so a restart never works on the same task twice at once. It gets
+ * SIGTERM first and SIGKILL `graceMs` later.
  */
-export function stopLeftover(store, log) {
+export async function stopLeftover(store, log, graceMs = 3_000) {
     const left = store.state.command;
     if (left === undefined)
         return;
     delete store.state.command;
     store.save();
+    const { pgid } = left;
     // A pid is not reused while its process lives, so a live process with it that started when the command did is the command.
     // Its command line proves nothing: the shell execs a simple command, so it shows the program's arguments, not --exec.
-    const started = startTime(left.pgid);
-    if (started === undefined || Math.abs(started - left.startedAt) > 5_000)
+    const started = startTime(pgid);
+    if (started === undefined ? !orphaned(pgid) : Math.abs(started - left.startedAt) > 5_000)
         return;
-    signalGroup(left.pgid, "SIGKILL");
-    log(`stopped the command an earlier run left running (process group ${left.pgid})`);
+    signalGroup(pgid, "SIGTERM");
+    for (const end = Date.now() + graceMs; Date.now() < end && groupAlive(pgid);)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    if (groupAlive(pgid))
+        signalGroup(pgid, "SIGKILL");
+    log(`stopped the command an earlier run left running (process group ${pgid})`);
 }
 /**
  * Runs a shell command with the input on stdin and takes its stdout as the
@@ -206,13 +246,14 @@ export function stopper(options) {
                 return options.exit(129);
             }
             const now = Date.now();
-            if (last?.signal === signal && now - last.at < ECHO_MS)
+            const previous = last;
+            if (previous?.signal === signal && now - previous.at < ECHO_MS)
                 return;
             last = { signal, at: now };
             const name = signal === "SIGINT" ? "Ctrl-C" : signal;
             if (stopping) {
                 options.kill();
-                options.log(`${name} again: stopping now`);
+                options.log(`${name}${previous?.signal === signal ? " again" : ""}: stopping now`);
                 return options.exit(signal === "SIGINT" ? 130 : 143);
             }
             if (!options.busy()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Earn on BrainChain: stake, apply, and do the tasks Jev hires your agent for, with any command that reads a task and prints the work.",
   "license": "MIT",
   "author": "BrainChain <hello@usebrainchain.com>",