@zgeoff/imp-client 0.5.0 → 0.7.0

package/README.md

@@ -1,8 +1,9 @@
 # @zgeoff/imp-client
 
 A typed client for [impd](https://github.com/zgeoff/imp), the imp host daemon. It runs in Bun, in
-Node 22 or later, and in browsers with `Promise.withResolvers`: Chrome 119, Firefox 121 and Safari
-17.4 or later.
+binaries that `bun build --compile` makes, in Node 22.6 or later, and in browsers with
+`Promise.withResolvers`: Chrome 119, Firefox 121 and Safari 17.4 or later. CI checks each release
+under Node, Bun and a compiled Bun binary.
 
 ```sh
 npm install @zgeoff/imp-client
@@ -123,7 +124,8 @@ the command did not run to its exit, `exit` rejects with an `ExecError` whose `c
 in the table below, plus `EXEC_FAILED` when the command cannot start) or one of `UNAUTHORIZED` (also
 for an exec ticket that expired or was used), `UNREACHABLE`, `RESTARTING`, `CONNECTION_CLOSED`,
 `DETACHED`, `BAD_MESSAGE`, `CLOSED`, `OUTPUT_OVERFLOW` and `LOCAL_ERROR`. Its `data` is impd's error
-data.
+data. An abort before the command starts, during the ticket call or the connect, rejects with the
+abort's reason instead, an `AbortError` by default; after the start it ends the session as `CLOSED`.
 
 ## Errors
 

package/dist/index.d.ts

@@ -255,6 +255,14 @@ declare const impContract: {
       memoryMib: z.ZodOptional<z.ZodInt>;
       diskMib: z.ZodOptional<z.ZodInt>;
       httpPort: z.ZodOptional<z.ZodInt>;
+      policy: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+          box: "box";
+          none: "none";
+          open: "open";
+        }>;
+        allow: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+      }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
       id: z.ZodString;
       name: z.ZodString;
@@ -1584,6 +1592,202 @@ declare const impContract: {
         readonly status: 409;
       };
     }>, Record<never, never>>;
+    policy: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+      name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      mode: z.ZodEnum<{
+        box: "box";
+        none: "none";
+        open: "open";
+      }>;
+      allow: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, {
+      NOT_FOUND: {
+        readonly message: "Not found";
+        readonly data: z.ZodObject<{
+          kind: z.ZodEnum<{
+            backup: "backup";
+            checkpoint: "checkpoint";
+            grant: "grant";
+            image: "image";
+            imp: "imp";
+            secret: "secret";
+            session: "session";
+            token: "token";
+          }>;
+          name: z.ZodString;
+        }, z.core.$strip>;
+      };
+      CONFLICT: {
+        readonly message: "Already exists";
+        readonly data: z.ZodObject<{
+          kind: z.ZodEnum<{
+            backup: "backup";
+            checkpoint: "checkpoint";
+            grant: "grant";
+            image: "image";
+            imp: "imp";
+            secret: "secret";
+            session: "session";
+            token: "token";
+          }>;
+          name: z.ZodString;
+        }, z.core.$strip>;
+      };
+      FORBIDDEN: {
+        readonly message: "Not allowed";
+      };
+      PRECONDITION_FAILED: {
+        readonly message: "Not possible on this host";
+      };
+      RAM_BUDGET_EXCEEDED: {
+        readonly message: "Not enough RAM budget, even after sleeping idle imps";
+        readonly status: 503;
+        readonly data: z.ZodObject<{
+          budgetMib: z.ZodInt;
+          usedMib: z.ZodInt;
+          requestedMib: z.ZodInt;
+        }, z.core.$strip>;
+      };
+      SERVICE_UNAVAILABLE: {
+        readonly message: "impd is stopping";
+      };
+      INVALID_STATE: {
+        readonly message: "The imp is not in a state that allows this";
+        readonly status: 409;
+        readonly data: z.ZodObject<{
+          state: z.ZodEnum<{
+            creating: "creating";
+            error: "error";
+            running: "running";
+            sleeping: "sleeping";
+            stopped: "stopped";
+          }>;
+          allowed: z.ZodArray<z.ZodEnum<{
+            creating: "creating";
+            error: "error";
+            running: "running";
+            sleeping: "sleeping";
+            stopped: "stopped";
+          }>>;
+        }, z.core.$strip>;
+      };
+      DISK_FULL: {
+        readonly message: "Not enough free disk on the host";
+        readonly status: 507;
+        readonly data: z.ZodObject<{
+          availableBytes: z.ZodInt;
+          reserveBytes: z.ZodInt;
+          requestedBytes: z.ZodInt;
+        }, z.core.$strip>;
+      };
+      AGENT_OUTDATED: {
+        readonly message: "The imp's agent is too old for this";
+        readonly status: 409;
+      };
+    }>, Record<never, never>>;
+    setPolicy: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+      name: z.ZodString;
+      policy: z.ZodObject<{
+        mode: z.ZodEnum<{
+          box: "box";
+          none: "none";
+          open: "open";
+        }>;
+        allow: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+      }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+      mode: z.ZodEnum<{
+        box: "box";
+        none: "none";
+        open: "open";
+      }>;
+      allow: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, {
+      NOT_FOUND: {
+        readonly message: "Not found";
+        readonly data: z.ZodObject<{
+          kind: z.ZodEnum<{
+            backup: "backup";
+            checkpoint: "checkpoint";
+            grant: "grant";
+            image: "image";
+            imp: "imp";
+            secret: "secret";
+            session: "session";
+            token: "token";
+          }>;
+          name: z.ZodString;
+        }, z.core.$strip>;
+      };
+      CONFLICT: {
+        readonly message: "Already exists";
+        readonly data: z.ZodObject<{
+          kind: z.ZodEnum<{
+            backup: "backup";
+            checkpoint: "checkpoint";
+            grant: "grant";
+            image: "image";
+            imp: "imp";
+            secret: "secret";
+            session: "session";
+            token: "token";
+          }>;
+          name: z.ZodString;
+        }, z.core.$strip>;
+      };
+      FORBIDDEN: {
+        readonly message: "Not allowed";
+      };
+      PRECONDITION_FAILED: {
+        readonly message: "Not possible on this host";
+      };
+      RAM_BUDGET_EXCEEDED: {
+        readonly message: "Not enough RAM budget, even after sleeping idle imps";
+        readonly status: 503;
+        readonly data: z.ZodObject<{
+          budgetMib: z.ZodInt;
+          usedMib: z.ZodInt;
+          requestedMib: z.ZodInt;
+        }, z.core.$strip>;
+      };
+      SERVICE_UNAVAILABLE: {
+        readonly message: "impd is stopping";
+      };
+      INVALID_STATE: {
+        readonly message: "The imp is not in a state that allows this";
+        readonly status: 409;
+        readonly data: z.ZodObject<{
+          state: z.ZodEnum<{
+            creating: "creating";
+            error: "error";
+            running: "running";
+            sleeping: "sleeping";
+            stopped: "stopped";
+          }>;
+          allowed: z.ZodArray<z.ZodEnum<{
+            creating: "creating";
+            error: "error";
+            running: "running";
+            sleeping: "sleeping";
+            stopped: "stopped";
+          }>>;
+        }, z.core.$strip>;
+      };
+      DISK_FULL: {
+        readonly message: "Not enough free disk on the host";
+        readonly status: 507;
+        readonly data: z.ZodObject<{
+          availableBytes: z.ZodInt;
+          reserveBytes: z.ZodInt;
+          requestedBytes: z.ZodInt;
+        }, z.core.$strip>;
+      };
+      AGENT_OUTDATED: {
+        readonly message: "The imp's agent is too old for this";
+        readonly status: 409;
+      };
+    }>, Record<never, never>>;
     fork: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
       source: z.ZodString;
       name: z.ZodString;

package/dist/index.js

@@ -3,7 +3,7 @@ import { RPCLink } from "@orpc/client/fetch";
 import * as z from "zod";
 //#endregion
 //#region src/check-server.ts
-const CLIENT_VERSION = "0.5.0";
+const CLIENT_VERSION = "0.7.0";
 async function checkServer(rpc) {
 	const info = await rpc.system.info();
 	return {
@@ -65,10 +65,14 @@ const ExecStartMessageSchema = z.object({
 	tty: z.boolean(),
 	cols: DimensionSchema.optional(),
 	rows: DimensionSchema.optional(),
-	session: SessionNameSchema.optional()
+	session: SessionNameSchema.optional(),
+	tool: z.enum(["tar"]).optional()
 }).refine((start) => start.session === void 0 || start.tty, {
 	message: "a session needs a tty",
 	path: ["tty"]
+}).refine((start) => start.tool === void 0 || !start.tty && start.session === void 0 && start.env === void 0 && start.cwd === void 0, {
+	message: "a tool takes no tty, session, env or cwd",
+	path: ["tool"]
 });
 const ExecAttachMessageSchema = z.object({
 	type: z.literal("attach"),
@@ -89,6 +93,10 @@ z.discriminatedUnion("type", [
 	z.object({
 		type: z.literal("signal"),
 		signal: z.string().regex(/^SIG[A-Z0-9]+$/)
+	}),
+	z.object({
+		type: z.literal("stdout_ack"),
+		bytes: z.int().positive()
 	})
 ]);
 const ExecServerMessageSchema = z.discriminatedUnion("type", [
@@ -111,6 +119,10 @@ const ExecServerMessageSchema = z.discriminatedUnion("type", [
 			"lost"
 		])
 	}),
+	z.object({
+		type: z.literal("stdin_ack"),
+		bytes: z.int().positive()
+	}),
 	z.object({
 		type: z.literal("error"),
 		message: z.string(),
@@ -210,7 +222,8 @@ function openExecSession(options) {
 	const state = {
 		opened: false,
 		started: false,
-		finished: false
+		finished: false,
+		refused: false
 	};
 	ws.binaryType = "arraybuffer";
 	const stopSocket = () => {
@@ -270,7 +283,7 @@ function openExecSession(options) {
 			kind: "detached",
 			reason: message.reason
 		});
-		else resolveOutcome({
+		else if (message.type === "stdin_ack") {} else resolveOutcome({
 			kind: "failed",
 			code: message.code ?? null,
 			message: message.message,
@@ -299,6 +312,8 @@ function openExecSession(options) {
 		}
 	});
 	const resolveRefusal = async (reason) => {
+		if (state.refused) return;
+		state.refused = true;
 		const access = await checkImpdAccess(options.baseUrl, options.token, options.fetch);
 		if (access === "unauthorized") resolveOutcome({ kind: "unauthorized" });
 		else if (access === "reachable" && options.ticket !== void 0) resolveOutcome({
@@ -314,6 +329,9 @@ function openExecSession(options) {
 			reason
 		});
 	};
+	ws.addEventListener("error", () => {
+		if (!state.opened && !state.finished) resolveRefusal("the connection failed");
+	});
 	ws.addEventListener("close", (event) => {
 		if (state.finished) return;
 		const reason = event.reason === "" ? `code ${String(event.code)}` : event.reason;
@@ -449,13 +467,21 @@ async function openHandle(deps, options, tty, start) {
 		state.ended = true;
 		stdout.end();
 		stderr.end();
-		abort?.removeEventListener("abort", stopSession);
+		abort?.removeEventListener("abort", stopForAbort);
 		if ("error" in result) started.resolve({ error: result.error });
 		ended.resolve(result);
 	};
 	const stopSession = () => {
 		stopWith("CLOSED", "the exec session was closed");
 	};
+	const stopForAbort = () => {
+		if (session.isStarted()) {
+			stopSession();
+			return;
+		}
+		session.stop();
+		resolveHandle({ error: readAbortReason(abort) });
+	};
 	const waitForOutcome = async () => {
 		const outcome = await session.outcome;
 		const result = outcome.kind === "exit" ? { value: {
@@ -464,8 +490,8 @@ async function openHandle(deps, options, tty, start) {
 		} } : { error: toExecError(outcome) };
 		resolveHandle(result);
 	};
-	if (abort?.aborted === true) stopSession();
-	else abort?.addEventListener("abort", stopSession, { once: true });
+	if (abort?.aborted === true) stopForAbort();
+	else abort?.addEventListener("abort", stopForAbort, { once: true });
 	waitForOutcome();
 	return buildHandle(session, {
 		started: started.promise,
@@ -476,6 +502,10 @@ async function openHandle(deps, options, tty, start) {
 		streams: [stdout.stream, stderr.stream]
 	});
 }
+function readAbortReason(abort) {
+	const reason = abort?.reason;
+	return reason instanceof Error ? reason : new DOMException("the exec was aborted", "AbortError");
+}
 function openConsole(deps, name, options = {}) {
 	return openExec(deps, name, [
 		"/bin/sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/imp-client",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Typed client for impd, the imp host daemon: imps, checkpoints, images and exec",
   "license": "MIT",
   "repository": {