@gjermundgaraba/clankerbox-rivet-sandbox-agent 0.15.5 → 0.16.0

package/dist/index.d.mts

@@ -2,9 +2,8 @@ import { Client } from "@gjermundgaraba/clankerbox-sdk";
 import { SandboxProvider } from "sandbox-agent";
 //#region src/options.d.ts
 /**
- * What a new sandbox is made from: a profile file, whose setup installs the Sandbox Agent; a
- * checkpoint of a machine that has it; or a machine that runs it, to fork. A fork or a `ram`
- * restore carries its source's sessions and processes, so take either from an idle machine.
+ * A profile whose setup installs the Sandbox Agent, a checkpoint of a machine that has it, or a
+ * machine to fork. A fork or `ram` restore carries its source's sessions: take it from an idle one.
  */
 type Source = {
   readonly profile: string;
@@ -14,34 +13,27 @@ type Source = {
   readonly machine: string;
 };
 interface Options {
-  /** The hosts to make sandboxes on, in placement order, as in the client config. */
+  /** In placement order, as in the client config. */
   readonly hosts: ReadonlyArray<Client.HostEntry>;
   readonly from: Source;
-  /**
-   * Whether a profile's setup runs even when the sandbox's host has a prebuild of it. By default
-   * a create from a profile with a setup restores that prebuild when there is one, as
-   * `clankerbox create` does; `clankerbox prebuild --profile <the same file>` makes it.
-   */
+  /** Runs a profile's setup even when the host has its prebuild, from `clankerbox prebuild`. */
   readonly fresh?: boolean | undefined;
-  /** What every sandbox's machine name starts with, `sandbox` by default. */
+  /** `sandbox` by default. */
   readonly namePrefix?: string | undefined;
-  /** The guest user the tunnel logs in as; by default the machine's own login user. */
+  /** The machine's own login user by default. */
   readonly sshUser?: string | undefined;
   /**
-   * More arguments for the tunnel's ssh, such as `["-i", "/path/to/key"]`. Neither these nor the
-   * user's ssh config for the machine may fork the forward (`-f`, `-N`, `ForkAfterAuthentication`,
-   * `SessionType none`) or hand it to a connection master (`-M`, `-S`): the tunnel ends with its
-   * ssh process, and one of those would outlive it.
+   * Such as `["-i", "/path/to/key"]`. Neither these nor ssh config may fork the forward (`-f`,
+   * `-N`, `ForkAfterAuthentication`, `SessionType none`) or give it to a connection master (`-M`,
+   * `-S`): the tunnel ends with its ssh, and those would outlive it.
    */
   readonly sshArguments?: ReadonlyArray<string> | undefined;
-  /** The directory sessions start in, `/home/sandbox` by default, as the recipes make it. */
+  /** `/home/sandbox` by default, as the recipes make it. */
   readonly cwd?: string | undefined;
 }
 /**
- * The provider, with `dispose`, which ends its tunnels and leaves the machines as they are. The
- * SDK never calls it: a program that keeps running after it is done with its sandboxes does.
- * The SDK's optional members it has are declared present, so a caller can call them; each takes
- * the machine's ID, `sdk.sandboxId` without its `clankerbox/`.
+ * `dispose` ends the tunnels and leaves the machines; the SDK never calls it. Each method takes the
+ * machine's ID, `sdk.sandboxId` without its `clankerbox/`.
  */
 interface ClankerboxProvider extends SandboxProvider {
   reconnect(sandboxId: string): Promise<void>;
@@ -54,9 +46,8 @@ interface ClankerboxProvider extends SandboxProvider {
 //#endregion
 //#region src/index.d.ts
 /**
- * A Sandbox Agent provider whose sandboxes are clankerbox machines on `options.hosts`. Each
- * sandbox's ID is `clankerbox/<machine ID>`, so `SandboxAgent.start({ sandbox, sandboxId })`
- * reconnects to a machine by its ID. Its tunnels end with the process; `dispose` ends them sooner.
+ * Sandboxes on clankerbox machines, with IDs `clankerbox/<machine ID>`, so `sandboxId` reconnects
+ * to a machine. Their tunnels end with the process, or at `dispose`.
  */
 export declare const clankerbox: (options: Options) => ClankerboxProvider;
 //#endregion

package/dist/index.mjs

@@ -2,49 +2,41 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as NodeClient from "@gjermundgaraba/clankerbox-sdk/node";
 import { Data, Duration, Effect, Exit, FileSystem, Layer, ManagedRuntime, Option, Predicate, Schedule, Schema, Scope, Semaphore } from "effect";
 import { randomBytes } from "node:crypto";
-import { Client, Internal, Prebuild, Precondition, loadProfile, pinnedSsh, readSetup, sshTarget } from "@gjermundgaraba/clankerbox-sdk";
+import { Client, Internal, Prebuild, Precondition, actionsByName, loadProfile, pinnedSsh, specRequest, sshTarget } from "@gjermundgaraba/clankerbox-sdk";
 import { SandboxDestroyedError } from "sandbox-agent";
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { Socket, connect, createServer } from "node:net";
 import { join } from "node:path";
+//#region src/agent.ts
+/** The Sandbox Agent's default port, which the recipes keep, on the guest's loopback. */
+const agentPort = 2468;
+const healthPath = "/v1/health";
+//#endregion
 //#region src/tunnel.ts
 /**
-* A sandbox's tunnel: the system `ssh` forwarding a loopback port of this machine to the Sandbox
-* Agent's port on the guest's loopback, over the machine's one published port, guest port 22.
-*
-* The tunnel runs `cat` in the guest and holds the pipe to its stdin, so it ends when this
-* process does, however that ends: the pipe closes, `cat` reads its end, and ssh exits. Neither
-* the child nor the pipe keeps the event loop alive, so a program that leaves a sandbox running
-* still exits. That takes `node:child_process` itself: Effect's process handle has no way to
-* unref the pipe.
+* The tunnel's ssh runs `cat` on a pipe this process holds, so it ends however this process ends.
+* Neither keeps the event loop alive; that takes `node:child_process`, as Effect's process handle
+* can't unref the pipe.
 */
 const loopback = "127.0.0.1";
-/**
-* A tunnel that couldn't open for a reason of this machine's: its port taken, ssh not runnable,
-* its files not written. No start of the sandbox's machine changes it.
-*/
+/** A failure on this machine's side, such as a taken port, which no start of the guest changes. */
 var LocalTunnelError = class extends Data.TaggedError("LocalTunnelError") {};
-/**
-* How long ssh may take to log in and listen: ssh's own default ConnectTimeout is the system's
-* TCP timeout, minutes, and a tunnel the SDK waits on should fail sooner than that.
-*/
+/** ssh's default ConnectTimeout is the system's TCP timeout, minutes; the SDK waits on this. */
 const openWait = Duration.seconds(30);
-/** How often the port is tried while ssh logs in: a login takes about a second. */
+/** A login takes about a second. */
 const openPause = Duration.millis(100);
-/** How long ssh may take to end once told to, before it is killed: it ends in milliseconds. */
+/** ssh ends in milliseconds once told to. */
 const closeWait = Duration.seconds(5);
-/** A loopback port nothing listens on now. */
 const freePort = Effect.callback((resume) => {
 	const server = createServer();
-	server.once("error", (error) => resume(Effect.fail(new Internal({ message: `couldn't find a free port: ${error.message}` }))));
+	server.once("error", (error) => resume(Effect.fail(new LocalTunnelError({ message: `couldn't find a free port: ${error.message}` }))));
 	server.listen(0, loopback, () => {
 		const address = server.address();
-		server.close(() => resume(address === null || Predicate.isString(address) ? Effect.fail(new Internal({ message: "couldn't find a free port" })) : Effect.succeed(address.port)));
+		server.close(() => resume(address === null || Predicate.isString(address) ? Effect.fail(new LocalTunnelError({ message: "couldn't find a free port" })) : Effect.succeed(address.port)));
 	});
 });
-/** Whether something accepts a connection on the loopback port. */
 const listening = (port) => Effect.callback((resume) => {
 	const socket = connect({
 		host: loopback,
@@ -57,14 +49,9 @@ const listening = (port) => Effect.callback((resume) => {
 	socket.once("error", () => resume(Effect.succeed(false)));
 	return Effect.sync(() => socket.destroy());
 });
-/** The port the Sandbox Agent listens on in the guest: its default, which the recipes keep. */
-const agentPort = 2468;
 /**
-* The arguments that forward `port` to the guest's Sandbox Agent, after the pinned ones, with the
-* caller's `extra` among them. The forward is this ssh's own, never a connection master's, which
-* would outlive it; and keepalives end it when the guest stops answering without closing. These
-* come before `extra`: OpenSSH keeps an option's first value, so neither `extra` nor the user's
-* ssh config can change them.
+* No connection master, which would outlive the forward, and keepalives that end it when the
+* guest stops answering. These precede `extra`: OpenSSH keeps an option's first value.
 */
 const forwarding = (port, extra) => [
 	"-T",
@@ -85,12 +72,9 @@ const forwarding = (port, extra) => [
 	`${loopback}:${port}:${loopback}:${agentPort}`,
 	"cat"
 ];
-/** Whether the child has ended, or failed to start: Node sets an exit code for either. */
+/** Node sets an exit code for a child that failed to start too. */
 const over = (child) => child.exitCode !== null || child.signalCode !== null;
-/**
-* Waits for the child to end. A program that couldn't be run says so in an `error` event, with
-* no `exit`.
-*/
+/** A program that couldn't be run emits `error`, with no `exit`. */
 const exited = (child) => Effect.callback((resume) => {
 	if (over(child)) return resume(Effect.void);
 	const done = () => resume(Effect.void);
@@ -102,10 +86,8 @@ const exited = (child) => Effect.callback((resume) => {
 	});
 });
 /**
-* Starts ssh and waits until it listens on the port. Closing the scope ends it, and waits for
-* its exit, so the port is free for the next tunnel. An ssh that exits first fails the open with
-* the last of what it printed, and one that couldn't be run with why. A port another program
-* holds is refused first: the wait for the port to listen can't tell whose listener it finds.
+* A port another program holds is refused first: the wait for the port to listen can't tell whose
+* listener it finds. Closing the scope waits for ssh's exit, so the port is free again.
 */
 const open = (start) => Effect.gen(function* () {
 	if (yield* listening(start.port)) return yield* new LocalTunnelError({ message: `the tunnel to ${start.machine} can't use port ${start.port}: another program listens on it` });
@@ -150,30 +132,17 @@ const open = (start) => Effect.gen(function* () {
 });
 //#endregion
 //#region src/sandboxes.ts
-/**
-* Sandboxes for Rivet's Sandbox Agent, each a clankerbox machine: the lifecycle a
-* `SandboxProvider` asks for, over the clankerbox client, and a tunnel to the Sandbox Agent
-* each machine runs.
-*
-* The machine runs the Sandbox Agent itself: its setup installs it, and its
-* `/etc/clankerbox/start` launches it on the guest's loopback at every activation, as the
-* recipes beside this package do. A machine exposes only guest port 22, so the provider reaches
-* the agent through an ssh port forward, pinned to the machine's host key, and gives the SDK a
-* loopback URL of this machine.
-*/
-/** The provider's name, which prefixes every sandbox ID the SDK hands out. */
+/** The calls that make a machine, whose failure may leave it on its host. */
+const makers = [
+	actionsByName.createMachine,
+	actionsByName.forkMachine,
+	actionsByName.restoreMachine
+];
 const name = "clankerbox";
-/**
-* How long a health check through the tunnel may take: the agent answers on loopback in
-* milliseconds, so one that takes longer is treated as not answering.
-*/
+/** The agent answers on loopback in milliseconds, so a slower one counts as not answering. */
 const healthWait = Duration.seconds(3);
 const Health = Schema.Struct({ status: Schema.Literal("ok") });
 const isHealth = Schema.is(Health);
-/**
-* The sandboxes of one provider. `ssh` is the program its tunnels run. A sandbox's ID is its
-* machine's ID.
-*/
 const make = (options, ssh = "ssh") => {
 	const sandboxes = /* @__PURE__ */ new Map();
 	const sandbox = (id) => {
@@ -185,16 +154,11 @@ const make = (options, ssh = "ssh") => {
 		sandboxes.set(id, known);
 		return known;
 	};
-	/**
-	* Runs `use` on the sandbox's record, holding its lock: each of the sandbox's operations runs
-	* whole under it, so two never overlap, as the host would refuse the second's start or stop
-	* while the first's runs.
-	*/
+	/** A sandbox's operations never overlap: the host would refuse a second start or stop as busy. */
 	const locked = (id, use) => Effect.suspend(() => {
 		const known = sandbox(id);
 		return Semaphore.withPermit(known.lock, Effect.suspend(() => use(known)));
 	});
-	/** The sandbox's port: its own, or a free one no other sandbox of this provider keeps. */
 	const portOf = (known) => Effect.gen(function* () {
 		if (known.port !== void 0) return known.port;
 		const taken = (port) => [...sandboxes.values()].some((other) => other.port === port);
@@ -203,16 +167,12 @@ const make = (options, ssh = "ssh") => {
 		known.port = port;
 		return port;
 	});
-	/** Ends the sandbox's tunnel, if it has one. */
 	const closed = (known) => Effect.suspend(() => {
 		const was = known.held;
 		known.held = void 0;
 		return was === void 0 ? Effect.void : Scope.close(was.scope, Exit.void);
 	});
-	/**
-	* The sandbox's port, with its tunnel open: the one it has while that runs, and otherwise a
-	* new one. The machine is read for each tunnel, as its endpoint changes: on boat at every start.
-	*/
+	/** The machine is read for each tunnel, as its endpoint changes: on boat at every start. */
 	const opened = (id, known) => Effect.gen(function* () {
 		if (known.held?.tunnel.running() === true) return yield* portOf(known);
 		yield* closed(known);
@@ -237,105 +197,61 @@ const make = (options, ssh = "ssh") => {
 		};
 		return port;
 	});
-	/** Whether the Sandbox Agent answers its health check through the tunnel. */
-	const healthy = (port) => Effect.tryPromise((signal) => fetch(`http://127.0.0.1:${port}/v1/health`, { signal }).then((reply) => reply.json())).pipe(Effect.map(isHealth), Effect.timeoutOrElse({
+	const healthy = (port) => Effect.tryPromise((signal) => fetch(`http://127.0.0.1:${port}${healthPath}`, { signal }).then((reply) => reply.json())).pipe(Effect.map(isHealth), Effect.timeoutOrElse({
 		duration: healthWait,
 		orElse: () => Effect.succeed(false)
 	}), Effect.catch(() => Effect.succeed(false)));
-	/**
-	* Starts the machine, which boots a stopped one and runs a running one's preparation again,
-	* and so its `/etc/clankerbox/start`. Its tunnel ends: the endpoint may have changed. A machine
-	* that no longer exists is the SDK's `SandboxDestroyedError`, for `reconnect` and
-	* `ensureServer` alike.
-	*/
+	/** A start reruns a running machine's start hook and may move its endpoint: the tunnel ends. */
 	const started = (id, known) => Effect.gen(function* () {
 		yield* (yield* Client.Client).start(id);
 		yield* closed(known);
 	}).pipe(Effect.catchTag("NotFound", (cause) => Effect.fail(new SandboxDestroyedError(id, name, { cause }))));
-	/**
-	* Makes the machine `named`, from the options' source. A profile with a setup is restored from
-	* its host's prebuild of it when there is one, as `clankerbox create` does, unless `fresh`.
-	*/
 	const made = (named) => Effect.gen(function* () {
 		const client = yield* Client.Client;
 		const { from } = options;
 		if ("checkpoint" in from) return yield* client.restore(from.checkpoint, named);
 		if ("machine" in from) return yield* client.fork(from.machine, named);
-		const { label, host, setup, ...sizes } = yield* loadProfile(from.profile);
-		let spec = {
-			...sizes,
-			profile: label
-		};
-		if (setup !== void 0) {
-			const { path, ...timeout } = setup;
-			spec = {
-				...spec,
-				setup: {
-					script: yield* readSetup(path),
-					...timeout
-				}
-			};
-		}
-		if (options.fresh === true) return yield* client.create(named, spec, { host });
-		const { machine } = yield* Prebuild.create(client, named, spec, { host });
+		const { spec, host } = yield* specRequest("create", yield* loadProfile(from.profile), {});
+		const { machine } = yield* Prebuild.create(client, named, spec, {
+			host,
+			fresh: options.fresh
+		});
 		return machine;
 	});
 	/**
-	* Tries to delete what a failed create may have left: a machine whose setup failed, or whose
-	* fork or restore failed natively, stays on its host, and only the provider knows its name. The
-	* host is the placement's to pick, so the machine is found by its name, which is random. A host
-	* that doesn't answer, or a delete that fails, leaves it to `clankerbox machines`.
+	* Only a failed create, fork or restore leaves its machine on the host, and then its error names
+	* it. A placement or prebuild read failure left nothing. A failed delete leaves it to the user.
 	*/
-	const discard = (named) => Effect.gen(function* () {
+	const discard = (error) => Effect.gen(function* () {
 		const client = yield* Client.Client;
-		const { answers } = yield* client.machines;
-		yield* Effect.forEach(answers.filter((machine) => machine.id.endsWith(`_${named}`)), (machine) => Effect.ignore(client.delete(machine.id)), { discard: true });
+		if (error.id !== void 0 && makers.some(({ name }) => name === error.action)) yield* Effect.ignore(client.delete(error.id));
+		return yield* error;
 	});
 	return {
-		/**
-		* Makes a sandbox's machine, and returns its ID once its create, fork or restore is done.
-		* Only the failures that can leave a machine behind discard it: a refusal, such as a name
-		* already taken, leaves nothing of this create's.
-		*/
 		create: Effect.suspend(() => {
 			const named = `${options.namePrefix ?? "sandbox"}-${randomBytes(4).toString("hex")}`;
-			const discarding = (error) => Effect.andThen(discard(named), Effect.fail(error));
 			return made(named).pipe(Effect.map((machine) => machine.id), Effect.catchTags({
-				Precondition: discarding,
-				Internal: discarding,
-				Unavailable: discarding
+				Precondition: discard,
+				Internal: discard,
+				Unavailable: discard
 			}));
 		}),
-		/**
-		* Deletes the machine, holding the sandbox's lock throughout. One that is already gone is
-		* destroyed. Its port goes only once it is: a delete that fails leaves the sandbox as it was,
-		* its tunnel aside.
-		*/
 		destroy: (id) => locked(id, (known) => Effect.gen(function* () {
 			const client = yield* Client.Client;
 			yield* closed(known);
 			yield* Effect.catchTag(client.delete(id), "NotFound", () => Effect.void);
 			known.port = void 0;
 		})),
-		/** Stops the machine: its disk stays, and `reconnect` starts it again. */
 		pause: (id) => locked(id, (known) => Effect.gen(function* () {
 			const client = yield* Client.Client;
 			yield* closed(known);
 			yield* client.stop(id);
 		})),
-		/**
-		* Starts the machine, which boots a stopped one and leaves a running one running. A machine
-		* that no longer exists is the SDK's `SandboxDestroyedError`. The SDK's `ensureServer`,
-		* which follows, opens the tunnel.
-		*/
+		/** The SDK's `ensureServer`, which follows, opens the tunnel. */
 		reconnect: (id) => locked(id, (known) => started(id, known)),
 		/**
-		* Brings back what a failed health check may have lost. A tunnel that ended is opened again;
-		* if the agent still doesn't answer, or the tunnel can't open for a reason on the machine's
-		* side, the machine is started, whose start hook relaunches an agent that doesn't answer, and
-		* its tunnel opened anew. A tunnel that fails for a reason of this machine's fails at once,
-		* since no start changes it. The SDK calls this only while it starts: a tunnel that ends
-		* later stays down until a caller calls it again.
+		* A local tunnel failure fails at once, since no start changes it. The SDK calls this only
+		* while it starts: a tunnel that ends later stays down until a caller calls it again.
 		*/
 		ensureServer: (id) => locked(id, (known) => Effect.gen(function* () {
 			const port = yield* opened(id, known).pipe(Effect.asSome, Effect.catchIf((error) => !(error instanceof LocalTunnelError), () => Effect.succeedNone));
@@ -343,22 +259,12 @@ const make = (options, ssh = "ssh") => {
 			yield* started(id, known);
 			yield* opened(id, known);
 		})),
-		/** The loopback URL that leads to the sandbox's agent. */
 		url: (id) => locked(id, (known) => Effect.map(opened(id, known), (port) => `http://127.0.0.1:${port}`)),
-		/** Ends every tunnel. The machines stay as they are. */
 		closeAll: Effect.suspend(() => Effect.forEach([...sandboxes.keys()], (id) => locked(id, closed), { discard: true }))
 	};
 };
 //#endregion
 //#region src/provider.ts
-/**
-* The `SandboxProvider` the Sandbox Agent SDK takes: the sandboxes' effects, run as promises
-* over the layer that gives them the clankerbox client and the platform.
-*/
-/**
-* The provider over `layer`, whose tunnels run `ssh`. Nothing is built until the first call.
-* Tests give it an in-memory host and a stand-in for ssh.
-*/
 const provider = (options, layer, ssh) => {
 	const runtime = ManagedRuntime.make(layer);
 	const sandboxes = make(options, ssh);
@@ -380,13 +286,8 @@ const provider = (options, layer, ssh) => {
 //#endregion
 //#region src/index.ts
 /**
-* clankerbox machines as sandboxes for Rivet's Sandbox Agent:
-* `SandboxAgent.start({ sandbox: clankerbox({ hosts, from }) })`.
-*/
-/**
-* A Sandbox Agent provider whose sandboxes are clankerbox machines on `options.hosts`. Each
-* sandbox's ID is `clankerbox/<machine ID>`, so `SandboxAgent.start({ sandbox, sandboxId })`
-* reconnects to a machine by its ID. Its tunnels end with the process; `dispose` ends them sooner.
+* Sandboxes on clankerbox machines, with IDs `clankerbox/<machine ID>`, so `sandboxId` reconnects
+* to a machine. Their tunnels end with the process, or at `dispose`.
 */
 const clankerbox = (options) => provider(options, Layer.mergeAll(NodeClient.layer(options.hosts), NodeServices.layer));
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerbox-rivet-sandbox-agent",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "description": "clankerbox machines as sandboxes for Rivet's Sandbox Agent",
   "license": "MIT",
   "repository": {
@@ -25,20 +25,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@gjermundgaraba/clankerbox-sdk": "0.15.5"
+    "@gjermundgaraba/clankerbox-sdk": "0.16.0"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.2",
+    "@effect/platform-node": "4.0.4",
     "@types/node": "26.6.4",
-    "effect": "4.0.2",
+    "effect": "4.0.4",
     "sandbox-agent": "0.5.2",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
     "vite-plus": "1.1.0"
   },
   "peerDependencies": {
-    "@effect/platform-node": "~4.0.2",
-    "effect": "~4.0.2",
+    "@effect/platform-node": "~4.0.4",
+    "effect": "~4.0.4",
     "sandbox-agent": "~0.5.2"
   },
   "scripts": {