@zgeoff/imp-client 0.16.0 → 0.17.0

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.16.0";
+const CLIENT_VERSION = "0.17.0";
 async function checkServer(rpc) {
 	const info = await rpc.system.info();
 	return {
@@ -28,6 +28,137 @@ function parseVersion(version) {
 //#endregion
 //#region ../api/src/name-schema.ts
 const NameSchema = z.string().regex(/^[a-z][a-z0-9-]{0,30}$/, "must be a lowercase letter followed by up to 30 lowercase letters, digits or hyphens");
+z.enum(["tailnet", "public"]);
+const PublicAuthSchema = z.enum([
+	"none",
+	"token",
+	"basic"
+]);
+const BasicUserSchema = z.string().regex(/^[!-9;-~]{1,64}$/, "must be 1 to 64 printable characters, without a colon");
+z.object({
+	name: NameSchema,
+	auth: PublicAuthSchema.default("token"),
+	user: BasicUserSchema.optional()
+}).refine((input) => input.auth === "basic" || input.user === void 0, {
+	message: "only basic auth takes a user",
+	path: ["user"]
+});
+z.object({
+	url: z.url(),
+	auth: PublicAuthSchema,
+	user: z.string().nullable(),
+	credential: z.string().nullable(),
+	warning: z.string().optional()
+});
+z.string().regex(/^[\w.:-]{1,64}$/, "must be 1–64 letters, digits, dots, underscores, colons or hyphens");
+z.int().min(10).max(3600);
+const LeaseOwnerSchema = z.object({
+	principal: z.string(),
+	display: z.string(),
+	label: z.string()
+});
+const LeaseSchema = z.object({
+	name: NameSchema,
+	owner: LeaseOwnerSchema,
+	until: z.date().nullable()
+});
+const LeaseSummarySchema = z.object({
+	leases: z.array(LeaseSchema).readonly(),
+	otherCount: z.int().nonnegative()
+});
+//#endregion
+//#region ../api/src/move-schema.ts
+const MoveStateSchema = z.enum([
+	"sending",
+	"moved",
+	"receiving"
+]);
+const PeerUrlSchema = z.url({ protocol: /^https?$/ });
+z.object({
+	bytes: z.int().nonnegative(),
+	checkpoints: z.int().nonnegative()
+});
+z.object({
+	ticket: z.string(),
+	expiresAt: z.date(),
+	peerUrl: PeerUrlSchema
+});
+z.object({
+	state: MoveStateSchema.nullable(),
+	peer: z.string().nullable(),
+	sentBytes: z.int().nonnegative(),
+	totalBytes: z.int().nonnegative(),
+	isDone: z.boolean(),
+	error: z.string().nullable()
+});
+//#endregion
+//#region ../api/src/imp-schema.ts
+const ImpStateSchema = z.enum([
+	"creating",
+	"running",
+	"sleeping",
+	"stopped",
+	"error"
+]);
+const OutdatedPartSchema = z.enum([
+	"firecracker",
+	"kernel",
+	"agent",
+	"impd",
+	"ipv6"
+]);
+const ImpResourcesSchema = z.object({
+	wakeCount: z.int().nonnegative(),
+	awakeMs: z.int().nonnegative(),
+	sample: z.object({
+		measuredAt: z.date(),
+		since: z.date(),
+		cpuPercent: z.number().nonnegative().optional(),
+		cpuThrottledMs: z.int().nonnegative(),
+		netRxBytes: z.int().nonnegative(),
+		netTxBytes: z.int().nonnegative()
+	}).optional()
+});
+z.object({
+	id: z.string(),
+	name: NameSchema,
+	image: NameSchema,
+	state: ImpStateSchema,
+	vcpus: z.int().positive(),
+	memoryMib: z.int().positive(),
+	diskMib: z.int().positive(),
+	diskUsage: z.object({
+		exclusiveBytes: z.int().nonnegative(),
+		sharedBytes: z.int().nonnegative(),
+		measuredAt: z.date(),
+		isPartial: z.boolean(),
+		isUpperBound: z.boolean()
+	}).optional(),
+	ip: z.ipv4(),
+	slot: z.int().nonnegative(),
+	port: z.int().positive(),
+	httpPort: z.int().positive(),
+	url: z.url(),
+	public: z.object({ auth: PublicAuthSchema }).optional(),
+	createdAt: z.date(),
+	lastActiveAt: z.date(),
+	ramMib: z.int().nonnegative().optional(),
+	rssMib: z.int().nonnegative().optional(),
+	sleptAt: z.date().optional(),
+	holdUntil: z.date().optional(),
+	leases: LeaseSummarySchema.optional(),
+	error: z.string().optional(),
+	sessions: z.int().nonnegative().optional(),
+	coldBootReason: z.string().optional(),
+	agentSilentSince: z.date().optional(),
+	outdated: z.array(OutdatedPartSchema).readonly().optional(),
+	cpu: z.object({
+		limit: z.number().positive().nullable(),
+		weight: z.int()
+	}).optional(),
+	resources: ImpResourcesSchema.optional(),
+	move: MoveStateSchema.optional()
+});
 //#endregion
 //#region ../api/src/image-schema.ts
 const ImageSourceSchema = z.enum(["oci", "imp"]);
@@ -54,6 +185,67 @@ const ImageBuildErrorSchema = z.object({
 	message: z.string()
 });
 //#endregion
+//#region ../api/src/session-output-schema.ts
+const ExecutionGenerationSchema = z.string().regex(/^[0-9a-f]{32}$/);
+const OffsetSchema = z.int().nonnegative();
+const ColdBootCauseSchema = z.enum([
+	"start",
+	"wake_fallback",
+	"watchdog",
+	"restore",
+	"recovery",
+	"unknown"
+]);
+const ColdBootSchema = z.object({
+	bootId: z.string(),
+	cause: ColdBootCauseSchema,
+	at: z.iso.datetime()
+}).readonly();
+const ColdBootsSchema = z.array(ColdBootSchema).max(4).readonly();
+const PreviousGenerationSchema = z.object({
+	executionGeneration: ExecutionGenerationSchema,
+	end: OffsetSchema,
+	exitCode: z.int().nullable()
+}).readonly();
+const ResumeFromSchema = z.object({
+	executionGeneration: ExecutionGenerationSchema,
+	offset: OffsetSchema
+}).readonly();
+const ResumeResultSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("exact") }),
+	z.object({
+		kind: z.literal("gap"),
+		from: OffsetSchema,
+		to: OffsetSchema
+	}),
+	z.object({
+		kind: z.literal("generation_changed"),
+		executionGeneration: ExecutionGenerationSchema,
+		firstOffset: OffsetSchema
+	})
+]).readonly();
+const SessionOutputSchema = z.discriminatedUnion("continuity", [z.object({ continuity: z.literal("none") }), z.object({
+	continuity: z.literal("offsets"),
+	bootId: z.string(),
+	executionGeneration: ExecutionGenerationSchema,
+	bufferStart: OffsetSchema,
+	end: OffsetSchema,
+	offset: OffsetSchema,
+	prelude: OffsetSchema,
+	coldBoots: ColdBootsSchema,
+	previous: PreviousGenerationSchema.optional(),
+	resume: ResumeResultSchema.optional()
+})]).readonly();
+const NoSessionDataSchema = z.object({
+	bootId: z.string(),
+	coldBoots: ColdBootsSchema,
+	previous: PreviousGenerationSchema.optional()
+}).readonly();
+const InvalidResumeDataSchema = z.object({
+	end: OffsetSchema,
+	bufferStart: OffsetSchema
+}).readonly();
+//#endregion
 //#region ../api/src/session-schema.ts
 const SessionNameSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/, "must be a lowercase letter or digit followed by up to 31 lowercase letters, digits or hyphens");
 const SessionExitSchema = z.object({
@@ -69,7 +261,12 @@ z.object({
 	cols: z.int().positive(),
 	rows: z.int().positive(),
 	startedAt: z.date(),
-	exit: SessionExitSchema.optional()
+	exit: SessionExitSchema.optional(),
+	continuity: z.enum(["none", "offsets"]).optional(),
+	executionGeneration: ExecutionGenerationSchema.optional(),
+	bootId: z.string().optional(),
+	end: z.int().nonnegative().optional(),
+	endObservedAt: z.date().optional()
 });
 //#endregion
 //#region ../api/src/exec-protocol.ts
@@ -92,10 +289,14 @@ const ExecStartMessageSchema = z.object({
 	rows: DimensionSchema.optional(),
 	session: SessionNameSchema.optional(),
 	tool: z.enum(["tar"]).optional(),
-	killGraceMs: z.int().min(1).max(6e4).optional()
+	killGraceMs: z.int().min(1).max(6e4).optional(),
+	resumeFrom: ResumeFromSchema.optional()
 }).refine((start) => start.session === void 0 || start.tty, {
 	message: "a session needs a tty",
 	path: ["tty"]
+}).refine((start) => start.resumeFrom === void 0 || start.session !== void 0, {
+	message: "only a session resumes",
+	path: ["resumeFrom"]
 }).refine((start) => start.killGraceMs === void 0 || !start.tty, {
 	message: "a tty exec takes no kill grace",
 	path: ["killGraceMs"]
@@ -108,7 +309,9 @@ const ExecAttachMessageSchema = z.object({
 	name: NameSchema,
 	session: SessionNameSchema,
 	cols: DimensionSchema.optional(),
-	rows: DimensionSchema.optional()
+	rows: DimensionSchema.optional(),
+	resumeFrom: ResumeFromSchema.optional(),
+	wake: z.boolean().optional()
 });
 z.discriminatedUnion("type", [
 	ExecStartMessageSchema,
@@ -134,12 +337,14 @@ const ExecServerMessageSchema = z.discriminatedUnion("type", [
 		pid: z.int().positive(),
 		session: SessionNameSchema.optional(),
 		created: z.boolean().optional(),
-		groupKill: z.boolean().optional()
+		groupKill: z.boolean().optional(),
+		output: SessionOutputSchema.optional()
 	}),
 	z.object({
 		type: z.literal("exit"),
 		code: z.int().nullable(),
-		signal: z.string().nullable()
+		signal: z.string().nullable(),
+		offset: z.int().nonnegative().optional()
 	}),
 	z.object({
 		type: z.literal("detached"),
@@ -147,7 +352,8 @@ const ExecServerMessageSchema = z.discriminatedUnion("type", [
 			"taken_over",
 			"slow",
 			"lost"
-		])
+		]),
+		offset: z.int().nonnegative().optional()
 	}),
 	z.object({
 		type: z.literal("stdin_ack"),
@@ -235,6 +441,102 @@ const TunnelServerMessageSchema = z.discriminatedUnion("type", [
 	})
 ]);
 //#endregion
+//#region ../api/src/define-errors.ts
+function defineErrors(errors) {
+	return errors;
+}
+//#endregion
+//#region ../api/src/imp-errors.ts
+const ResourceKindSchema = z.enum([
+	"imp",
+	"image",
+	"checkpoint",
+	"session",
+	"service",
+	"secret",
+	"grant",
+	"backup",
+	"token",
+	"ssh-key",
+	"network"
+]);
+const ResourceDataSchema = z.object({
+	kind: ResourceKindSchema,
+	name: z.string()
+});
+const ProtectedImpSchema = z.object({
+	name: NameSchema,
+	ramMib: z.int().nonnegative(),
+	leased: z.boolean(),
+	busy: z.boolean()
+});
+const IMP_ERRORS = defineErrors({
+	NOT_FOUND: {
+		message: "Not found",
+		data: ResourceDataSchema
+	},
+	CONFLICT: {
+		message: "Already exists",
+		data: ResourceDataSchema
+	},
+	FORBIDDEN: { message: "Not allowed" },
+	PRECONDITION_FAILED: { message: "Not possible on this host" },
+	RAM_BUDGET_EXCEEDED: {
+		message: "Not enough RAM budget, even after sleeping idle imps",
+		status: 503,
+		data: z.object({
+			budgetMib: z.int().nonnegative(),
+			usedMib: z.int().nonnegative(),
+			requestedMib: z.int().nonnegative(),
+			neededMib: z.int().nonnegative().optional(),
+			protected: z.array(ProtectedImpSchema).readonly().optional(),
+			protectedHidden: z.int().nonnegative().optional()
+		})
+	},
+	SERVICE_UNAVAILABLE: { message: "impd is stopping" },
+	INVALID_STATE: {
+		message: "The imp is not in a state that allows this",
+		status: 409,
+		data: z.object({
+			state: ImpStateSchema,
+			allowed: z.array(ImpStateSchema),
+			coldBoots: ColdBootsSchema.optional()
+		})
+	},
+	INVALID_RESUME: {
+		message: "The resume offset is past the end of the output",
+		status: 409,
+		data: InvalidResumeDataSchema
+	},
+	DISK_FULL: {
+		message: "Not enough free disk on the host",
+		status: 507,
+		data: z.object({
+			availableBytes: z.int().nonnegative(),
+			reserveBytes: z.int().nonnegative(),
+			requestedBytes: z.int().nonnegative()
+		})
+	},
+	LEASED: {
+		message: "The imp is leased",
+		status: 409,
+		data: LeaseSummarySchema
+	},
+	LEASE_NOT_HELD: {
+		message: "The caller holds no such lease",
+		status: 409
+	},
+	AGENT_OUTDATED: {
+		message: "The imp's agent is too old for this",
+		status: 409
+	},
+	MOVING: {
+		message: "The imp is moving between hosts",
+		status: 409,
+		data: z.object({ retryAfterS: z.int().positive() })
+	}
+});
+//#endregion
 //#region ../api/src/login-shell.ts
 const CONSOLE_SHELL = [
 	"uid=$(id -u 2>/dev/null) || uid=0",
@@ -297,15 +599,6 @@ var ExecError = class extends Error {
 		this.data = options.data;
 	}
 };
-function toExecError(outcome) {
-	if (outcome.kind === "failed") return new ExecError(outcome.code ?? "EXEC_ERROR", outcome.message, { data: outcome.data });
-	if (outcome.kind === "unauthorized") return new ExecError("UNAUTHORIZED", outcome.ticketRefused === true ? "impd refused the exec ticket: it expired (30 s) or was used already" : "impd rejected the token");
-	if (outcome.kind === "unreachable") return new ExecError("UNREACHABLE", `cannot reach impd (${outcome.detail})`);
-	if (outcome.kind === "detached") return new ExecError("DETACHED", `detached from the session (${outcome.reason})`, { data: { reason: outcome.reason } });
-	if (outcome.kind === "closed") return outcome.closeCode === 1012 ? new ExecError("RESTARTING", "impd is restarting") : new ExecError("CONNECTION_CLOSED", `exec connection closed (${outcome.reason})`);
-	if (outcome.kind === "bad_message") return new ExecError("BAD_MESSAGE", `bad message from impd: ${outcome.detail}`);
-	return new ExecError("LOCAL_ERROR", "an output handler threw", { cause: outcome.error });
-}
 //#endregion
 //#region src/exec/check-impd-access.ts
 const CHECK_TIMEOUT_MS = 5e3;
@@ -391,16 +684,19 @@ function openExecSession(options) {
 				pid: message.pid,
 				session: message.session ?? null,
 				created: message.created ?? false,
-				groupKill: message.groupKill ?? false
+				groupKill: message.groupKill ?? false,
+				output: message.output ?? { continuity: "none" }
 			});
 		} else if (message.type === "exit") resolveOutcome({
 			kind: "exit",
 			code: message.code,
-			signal: message.signal
+			signal: message.signal,
+			...message.offset !== void 0 && { offset: message.offset }
 		});
 		else if (message.type === "detached") resolveOutcome({
 			kind: "detached",
-			reason: message.reason
+			reason: message.reason,
+			...message.offset !== void 0 && { offset: message.offset }
 		});
 		else if (message.type === "stdin_ack") {} else resolveOutcome({
 			kind: "failed",
@@ -510,6 +806,59 @@ function buildOpenMessage(start) {
 	};
 }
 //#endregion
+//#region src/exec/invalid-resume-error.ts
+var InvalidResumeError = class extends ExecError {
+	constructor(message, data) {
+		super("INVALID_RESUME", message, { data });
+		this.name = "InvalidResumeError";
+	}
+};
+//#endregion
+//#region src/exec/invalid-state-error.ts
+var InvalidStateError = class extends ExecError {
+	constructor(message, data) {
+		super("INVALID_STATE", message, { data });
+		this.name = "InvalidStateError";
+	}
+};
+//#endregion
+//#region src/exec/no-session-error.ts
+var NoSessionError = class extends ExecError {
+	constructor(message, data) {
+		super("NO_SESSION", message, { data });
+		this.name = "NoSessionError";
+	}
+};
+//#endregion
+//#region src/exec/to-exec-error.ts
+function toExecError(outcome) {
+	if (outcome.kind === "failed") return toFailedError(outcome.code, outcome.message, outcome.data);
+	if (outcome.kind === "unauthorized") return new ExecError("UNAUTHORIZED", outcome.ticketRefused === true ? "impd refused the exec ticket: it expired (30 s) or was used already" : "impd rejected the token");
+	if (outcome.kind === "unreachable") return new ExecError("UNREACHABLE", `cannot reach impd (${outcome.detail})`);
+	if (outcome.kind === "detached") return new ExecError("DETACHED", `detached from the session (${outcome.reason})`, { data: {
+		reason: outcome.reason,
+		...outcome.offset !== void 0 && { offset: outcome.offset }
+	} });
+	if (outcome.kind === "closed") return outcome.closeCode === 1012 ? new ExecError("RESTARTING", "impd is restarting") : new ExecError("CONNECTION_CLOSED", `exec connection closed (${outcome.reason})`);
+	if (outcome.kind === "bad_message") return new ExecError("BAD_MESSAGE", `bad message from impd: ${outcome.detail}`);
+	return new ExecError("LOCAL_ERROR", "an output handler threw", { cause: outcome.error });
+}
+function toFailedError(code, message, data) {
+	if (code === "NO_SESSION") {
+		const parsed = NoSessionDataSchema.safeParse(data);
+		return new NoSessionError(message, parsed.success ? parsed.data : void 0);
+	}
+	if (code === "INVALID_STATE") {
+		const parsed = IMP_ERRORS.INVALID_STATE.data.safeParse(data);
+		if (parsed.success) return new InvalidStateError(message, parsed.data);
+	}
+	if (code === "INVALID_RESUME") {
+		const parsed = InvalidResumeDataSchema.safeParse(data);
+		if (parsed.success) return new InvalidResumeError(message, parsed.data);
+	}
+	return new ExecError(code ?? "EXEC_ERROR", message, { data });
+}
+//#endregion
 //#region src/exec/open-exec.ts
 const DEFAULT_MAX_UNREAD_BYTES = 8388608;
 const TTY_SIGNAL_KEYS = {
@@ -527,7 +876,8 @@ function openExec(deps, name, argv, options = {}) {
 		...options.cols !== void 0 && { cols: options.cols },
 		...options.rows !== void 0 && { rows: options.rows },
 		...options.session !== void 0 && { session: options.session },
-		...options.killGraceMs !== void 0 && { killGraceMs: options.killGraceMs }
+		...options.killGraceMs !== void 0 && { killGraceMs: options.killGraceMs },
+		...options.resumeFrom !== void 0 && { resumeFrom: options.resumeFrom }
 	});
 }
 function openAttach(deps, name, session, options = {}) {
@@ -535,7 +885,9 @@ function openAttach(deps, name, session, options = {}) {
 		name,
 		session,
 		...options.cols !== void 0 && { cols: options.cols },
-		...options.rows !== void 0 && { rows: options.rows }
+		...options.rows !== void 0 && { rows: options.rows },
+		...options.resumeFrom !== void 0 && { resumeFrom: options.resumeFrom },
+		...options.wake !== void 0 && { wake: options.wake }
 	});
 }
 async function openHandle(deps, options, tty, start) {
@@ -606,7 +958,8 @@ async function openHandle(deps, options, tty, start) {
 		const outcome = await session.outcome;
 		const result = outcome.kind === "exit" ? { value: {
 			code: outcome.code,
-			signal: outcome.signal
+			signal: outcome.signal,
+			...outcome.offset !== void 0 && { offset: outcome.offset }
 		} } : { error: toExecError(outcome) };
 		resolveHandle(result);
 	};
@@ -1046,4 +1399,4 @@ function openReverseForward(options) {
 	};
 }
 //#endregion
-export { CLIENT_VERSION, CONSOLE_SHELL, ExecError, ORPCError, createImpClient, isDefinedError, openExecSession, openReverseForward, safe };
+export { CLIENT_VERSION, CONSOLE_SHELL, ExecError, InvalidResumeError, InvalidStateError, NoSessionError, ORPCError, createImpClient, isDefinedError, openExecSession, openReverseForward, safe };

package/package.json

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