@solarisdk/core 0.4.3 → 0.4.5

package/dist/desktop.d.ts

@@ -41,6 +41,11 @@ export declare class Desktop extends SessionHandle {
         doubleClick: (x: number, y: number, opts?: ClickOptions) => Promise<void>;
         down: (x: number, y: number, button?: MouseButton) => Promise<void>;
         up: (x: number, y: number, button?: MouseButton) => Promise<void>;
+        /**
+         * Scroll the wheel with the pointer at (x, y). `direction` defaults to "down", `amount` (wheel clicks, 1-50)
+         * to 3. The guest takes the wheel delta in the `y` field and does not move the pointer, so the pointer is moved
+         * first and (x, y) is never passed as the delta (it used to be: scroll(x, 500) fired 500 clicks, 20-30 s).
+         */
         scroll: (x: number, y: number, opts?: ScrollOptions) => Promise<void>;
         drag: (from: {
             x: number;

package/dist/desktop.js

@@ -1,4 +1,5 @@
 import { SessionHandle } from "./handle.js";
+import { SolariError } from "./errors.js";
 import { base64ToBytes } from "./transport.js";
 function buttonToCode(button) {
     if (button === undefined)
@@ -79,7 +80,23 @@ export class Desktop extends SessionHandle {
         }).then(() => undefined),
         down: (x, y, button = "left") => this.mouseCall(x, y, "down", button),
         up: (x, y, button = "left") => this.mouseCall(x, y, "up", button),
-        scroll: (x, y, opts = {}) => this.mouseCall(x, y, "scroll", opts.button, opts.humanize),
+        scroll: async (x, y, opts = {}) => {
+            const amount = opts.amount ?? 3;
+            if (!Number.isInteger(amount) || amount < 1 || amount > 50) {
+                throw new SolariError("scroll amount must be a whole number of wheel clicks from 1 to 50");
+            }
+            const direction = opts.direction ?? "down";
+            if (direction !== "up" && direction !== "down") {
+                throw new SolariError('scroll direction must be "up" or "down"');
+            }
+            await this.mouseCall(x, y, "move", undefined, opts.humanize);
+            await this.guiCall("input.mouse", {
+                x,
+                y: direction === "up" ? amount : -amount,
+                action: "scroll",
+                button: buttonToCode(opts.button),
+            });
+        },
         drag: (from, to, button = "left") => this.guiCall("input.drag", { from, to, button: buttonToCode(button) }).then(() => undefined),
     };
     mouseCall(x, y, action, button, humanize) {

package/dist/handle.d.ts

@@ -56,6 +56,16 @@ export interface SessionConfig extends ControlChannelConfig {
 }
 /** The longest `timeoutMs` the gateway accepts for a command (600 000 ms), and the default for `commands.run`. */
 export declare const DEFAULT_COMMAND_TIMEOUT_MS = 600000;
+/**
+ * The session `id` is no longer running (killed or paused, through any handle or by id), so the exit reminder must not
+ * name it. Tracking is by id, not by handle: two handles to one session, or a `client.kill(id)` with no handle at all,
+ * all clear the same entry.
+ */
+export declare function markSessionReleased(id: string): void;
+/** The lines the exit reminder prints: one per distinct session id, however many handles track it. */
+export declare function exitReminderMessages(): string[];
+/** Ids the exit reminder would name right now (for tests). */
+export declare function unreleasedSessionIds(): string[];
 /** Cap on PTY output held before the first onData() subscriber (bytes, total). */
 export declare const PTY_EARLY_BUFFER_MAX: number;
 export interface SessionHandle {
@@ -121,6 +131,8 @@ export declare class SessionHandle {
         connect: () => Promise<void>;
     };
     private startCommand;
+    /** SIGTERM + close stdin now, SIGKILL after CANCEL_KILL_GRACE_MS. Best effort: a dead channel or a finished command is fine. */
+    private cancelCommand;
     private runCommand;
     private runCommandInner;
     readonly pty: {
@@ -136,6 +148,7 @@ export declare class SessionHandle {
     /** Create a fresh stateful kernel context (`code.context.create`). */
     createCodeContext(language?: CodeLanguageArg): Promise<string>;
     readonly files: {
+        /** Read a whole file. Chunked under the hood (4 MiB per frame), so a big file never travels as one frame. */
         read: (path: string) => Promise<Uint8Array>;
         readText: (path: string) => Promise<string>;
         write: (path: string, data: Uint8Array | string, mode?: number) => Promise<void>;
@@ -151,7 +164,7 @@ export declare class SessionHandle {
          * Returns an unwatch function.
          */
         watch: (path: string, cb: (ev: FsWatchEvent) => void, recursive?: boolean) => Promise<() => Promise<void>>;
-        /** Upload local bytes to an in-guest path (chunked base64 under the hood). */
+        /** Upload local bytes to an in-guest path: sent in 4 MiB chunks (offset/truncate), so a big file never travels as one frame. */
         upload: (path: string, data: Uint8Array | string) => Promise<void>;
         /** Download an in-guest file's bytes. */
         download: (path: string) => Promise<Uint8Array>;
@@ -172,10 +185,11 @@ export declare class SessionHandle {
     }>;
     readonly volumes: {
         /**
-         * Mount a volume into the guest at `path`. Thin pass-through to the guest
-         * `volume.mount` RPC; the gateway volume routes may be a 501 stub today.
+         * Not available at runtime. A volume is mounted when the sandbox is created (or resumed): the guest cannot fetch the
+         * storage credentials itself, and the gateway has no runtime-mount route, so the old pass-through to the guest
+         * `volume.mount` RPC always failed with "bucket is required". Pass `volumes: [{ volumeId, path }]` at create.
          */
-        mount: (volId: string, path: string) => Promise<void>;
+        mount: (_volId: string, _path: string) => Promise<void>;
     };
     readonly git: {
         /** Clone `url` into `opts.path` (or git's default dir) under `opts.cwd`. */
@@ -289,4 +303,10 @@ export declare class SessionHandle {
 }
 /** Local helper type for `createCodeContext` to avoid a hard import cycle. */
 type CodeLanguageArg = "python" | "javascript" | "typescript" | "bash" | "r";
+/** How long a cancelled command gets between SIGTERM and SIGKILL. */
+export declare const CANCEL_KILL_GRACE_MS = 2000;
+/** Bytes per fs.upload / fs.download frame. */
+export declare const FILE_CHUNK_BYTES: number;
+/** Largest whole-file payload one single-frame call (files.write) accepts; above it use files.upload / files.download / a signed URL. */
+export declare const MAX_SINGLE_CALL_BYTES: number;
 export {};

package/dist/handle.js

@@ -6,6 +6,18 @@ export const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
 const unreleased = new Map();
 const MAX_TRACKED_UNRELEASED = 1000;
 let exitHookInstalled = false;
+export function markSessionReleased(id) {
+    for (const [token, tracked] of unreleased)
+        if (tracked === id)
+            unreleased.delete(token);
+}
+export function exitReminderMessages() {
+    return [...new Set(unreleased.values())].map((id) => `[solari] this process is exiting but session ${shortId(id)} is still running and will bill until its ` +
+        `idle timeout. Call kill() to release it (or declare it with \`await using\`).`);
+}
+export function unreleasedSessionIds() {
+    return [...unreleased.values()];
+}
 function trackUnreleased(token, id) {
     unreleased.set(token, id);
     if (unreleased.size > MAX_TRACKED_UNRELEASED)
@@ -14,10 +26,8 @@ function trackUnreleased(token, id) {
         return;
     exitHookInstalled = true;
     process.on("exit", () => {
-        for (const id of unreleased.values()) {
-            console.warn(`[solari] this process is exiting but session ${shortId(id)} is still running and will bill until its ` +
-                `idle timeout. Call kill() to release it (or declare it with \`await using\`).`);
-        }
+        for (const line of exitReminderMessages())
+            console.warn(line);
         unreleased.clear();
     });
 }
@@ -70,7 +80,8 @@ export class SessionHandle {
         return this.channel.reconnect();
     }
     close(opts = {}) {
-        unreleased.delete(this.releaseToken);
+        if (!opts.quiet)
+            unreleased.delete(this.releaseToken);
         if (!this.killed && !opts.quiet && typeof console !== "undefined") {
             console.warn(`[solari] close() on session ${shortId(this.id)} closed the local channel only — ` +
                 `the remote machine is still running and will bill until its idle ` +
@@ -116,6 +127,22 @@ export class SessionHandle {
                 exitResolve?.(-1);
             }, opts.timeoutMs);
         }
+        if (opts.signal) {
+            const signal = opts.signal;
+            const onAbort = () => {
+                clearTimeout(deadline);
+                void this.cancelCommand(cmdId);
+                this.channel.offFrame("cmd.data", cmdId);
+                this.channel.offFrame("cmd.exit", cmdId);
+                this.channel.offStreamClose(cmdId);
+                exitReject?.(abortReason(signal));
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+            void exitPromise.then(() => signal.removeEventListener("abort", onAbort), () => signal.removeEventListener("abort", onAbort));
+        }
         if (acc) {
             dataCbs.push((c) => {
                 if (c.stream === "stdout")
@@ -180,6 +207,13 @@ export class SessionHandle {
                 .then(() => undefined),
         };
     }
+    async cancelCommand(cmdId) {
+        await this.channel.call("cmd.kill", { cmdId, signal: 15 }).catch(() => undefined);
+        await this.channel.call("cmd.stdin", { cmdId, base64: "", eof: true }).catch(() => undefined);
+        setTimeout(() => {
+            this.channel.call("cmd.kill", { cmdId, signal: 9 }).catch(() => undefined);
+        }, CANCEL_KILL_GRACE_MS).unref?.();
+    }
     async runCommand(cmd, opts) {
         try {
             return await this.runCommandInner(cmd, opts);
@@ -199,6 +233,7 @@ export class SessionHandle {
             !opts.onStderr &&
             !opts.env &&
             !opts.user &&
+            !opts.signal &&
             timeoutMs >= MIN_REST_TIMEOUT_MS &&
             timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS;
         const viaRest = async () => {
@@ -309,11 +344,34 @@ export class SessionHandle {
         };
     }
     async runCode(code, opts = {}) {
-        const r = await this.channel.call("code.run", {
-            code,
-            language: opts.language,
-            contextId: opts.contextId,
-        });
+        const params = { code, language: opts.language, contextId: opts.contextId };
+        const running = this.channel.call("code.run", params);
+        let r;
+        const signal = opts.signal;
+        if (signal) {
+            let onAbort;
+            const aborted = new Promise((_, reject) => {
+                onAbort = () => {
+                    this.channel.call("code.interrupt", { language: opts.language, contextId: opts.contextId }).catch(() => undefined);
+                    reject(abortReason(signal));
+                };
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            });
+            running.catch(() => undefined);
+            try {
+                r = await Promise.race([running, aborted]);
+            }
+            finally {
+                if (onAbort)
+                    signal.removeEventListener("abort", onAbort);
+            }
+        }
+        else {
+            r = await running;
+        }
         const results = Array.isArray(r.results) ? r.results : [];
         for (const item of results) {
             if (item.type === "stdout" && item.text)
@@ -332,16 +390,29 @@ export class SessionHandle {
     }
     files = {
         read: async (path) => {
-            const r = await this.channel.call("fs.read", { path });
-            return base64ToBytes(r.base64);
+            try {
+                return await downloadAll((method, params) => this.channel.call(method, { ...params, length: FILE_CHUNK_BYTES }), path);
+            }
+            catch (err) {
+                if (!isUnknownMethod(err))
+                    throw err;
+                const r = await this.channel.call("fs.read", { path });
+                return base64ToBytes(r.base64);
+            }
         },
         readText: async (path) => {
             const bytes = await this.files.read(path);
             return new TextDecoder().decode(bytes);
         },
-        write: (path, data, mode) => this.channel
-            .call("fs.write", { path, base64: toB64(data), mode })
-            .then(() => undefined),
+        write: (path, data, mode) => {
+            const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+            if (bytes.length > MAX_SINGLE_CALL_BYTES) {
+                return Promise.reject(singleCallTooLarge(bytes.length));
+            }
+            return this.channel
+                .call("fs.write", { path, base64: toB64(bytes), mode })
+                .then(() => undefined);
+        },
         list: async (path) => {
             const r = await this.channel.call("fs.list", {
                 path,
@@ -376,10 +447,16 @@ export class SessionHandle {
                 await this.channel.call("fs.unwatch", { watchId });
             };
         },
-        upload: (path, data) => this.channel
-            .call("fs.upload", { path, base64: toB64(data) })
-            .then(() => undefined),
-        download: (path) => downloadAll((method, params) => this.channel.call(method, params), path),
+        upload: async (path, data) => {
+            const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+            let offset = 0;
+            do {
+                const slice = bytes.subarray(offset, offset + FILE_CHUNK_BYTES);
+                await this.channel.call("fs.upload", { path, base64: toB64(slice), offset, truncate: offset === 0 });
+                offset += slice.length;
+            } while (offset < bytes.length);
+        },
+        download: (path) => downloadAll((method, params) => this.channel.call(method, { ...params, length: FILE_CHUNK_BYTES }), path),
     };
     env(vars) {
         return this.channel
@@ -399,9 +476,7 @@ export class SessionHandle {
         return this.hooks.uploadUrl(this.id, path);
     }
     volumes = {
-        mount: (volId, path) => this.channel
-            .call("volume.mount", { volumeId: volId, path })
-            .then(() => undefined),
+        mount: (_volId, _path) => Promise.reject(new SolariError("volumes.mount() is not supported on a running sandbox: pass volumes: [{ volumeId, path }] when you create it")),
     };
     git = {
         clone: (url, opts = {}) => this.gitClone(url, opts),
@@ -624,6 +699,7 @@ export class SessionHandle {
             throw new Error("pause requires a client-created handle");
         }
         await this.hooks.pause(this.id);
+        markSessionReleased(this.id);
         this.close({ quiet: true });
     }
     async resume() {
@@ -631,6 +707,7 @@ export class SessionHandle {
             throw new Error("resume requires a client-created handle");
         }
         const r = await this.hooks.resume(this.id);
+        trackUnreleased(this.releaseToken, this.id);
         this.channel.setControlUrl(r.controlUrl);
         await this.channel.reconnect();
     }
@@ -673,6 +750,7 @@ export class SessionHandle {
         if (this.hooks.kill)
             await this.hooks.kill(this.id);
         this.killed = true;
+        markSessionReleased(this.id);
         this.close();
     }
 }
@@ -716,6 +794,23 @@ function isRouteUnavailable(err) {
     return (err instanceof GatewayError &&
         (err.status === 404 || err.status === 405 || err.status === 501));
 }
+function isUnknownMethod(err) {
+    return /unknown method|method not found|not implemented/i.test(err instanceof Error ? err.message : String(err));
+}
+export const CANCEL_KILL_GRACE_MS = 2000;
+function abortReason(signal) {
+    const r = signal.reason;
+    if (r instanceof Error)
+        return r;
+    const e = new Error("The command was cancelled");
+    e.name = "AbortError";
+    return e;
+}
+export const FILE_CHUNK_BYTES = 4 * 1024 * 1024;
+export const MAX_SINGLE_CALL_BYTES = 32 * 1024 * 1024;
+function singleCallTooLarge(n) {
+    return new SolariError(`file too large for a single call (${n} bytes, max ${MAX_SINGLE_CALL_BYTES}): use files.upload()/files.download() or uploadUrl()`);
+}
 function toB64(data) {
     const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
     return bytesToBase64(bytes);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
+export { CANCEL_KILL_GRACE_MS, DEFAULT_COMMAND_TIMEOUT_MS, FILE_CHUNK_BYTES, MAX_SINGLE_CALL_BYTES, SessionHandle, markSessionReleased, unreleasedSessionIds, exitReminderMessages } from "./handle.js";
 export { shortId } from "./ids.js";
 export { formatIdlePolicy } from "./idle-policy.js";
 export type { SessionConfig, SessionHooks } from "./handle.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
+export { CANCEL_KILL_GRACE_MS, DEFAULT_COMMAND_TIMEOUT_MS, FILE_CHUNK_BYTES, MAX_SINGLE_CALL_BYTES, SessionHandle, markSessionReleased, unreleasedSessionIds, exitReminderMessages } from "./handle.js";
 export { shortId } from "./ids.js";
 export { formatIdlePolicy } from "./idle-policy.js";
 export { Desktop } from "./desktop.js";

package/dist/types.d.ts

@@ -632,6 +632,10 @@ export interface MouseResult {
 export interface ScrollOptions {
     button?: MouseButton;
     humanize?: boolean;
+    /** Which way the wheel turns. Default "down". */
+    direction?: "up" | "down";
+    /** Wheel clicks, a whole number from 1 to 50. Default 3. */
+    amount?: number;
 }
 export interface ClickOptions {
     button?: MouseButton;
@@ -763,6 +767,12 @@ export interface CommandOptions {
     background?: boolean;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
+    /**
+     * Cancel the command. On abort the process in the sandbox gets SIGTERM and its stdin is closed, then SIGKILL after
+     * 2 s if it is still running; the call rejects with the signal's reason. Giving a signal runs the command over the live
+     * connection (the one-shot REST route has nothing to kill).
+     */
+    signal?: AbortSignal;
 }
 /** Terminal result of `commands.run`. */
 export interface CommandResult {
@@ -831,6 +841,8 @@ export interface RunCodeOptions {
     contextId?: string;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
+    /** Cancel the run: the cell is interrupted in the kernel (KeyboardInterrupt) and the call rejects with the signal's reason. */
+    signal?: AbortSignal;
 }
 /** Kind of a structured chart extracted from a matplotlib figure. */
 export type ChartType = "line" | "scatter" | "bar" | "pie" | "box_and_whisker" | "composite" | "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Shared runtime for the Solari SDK \u2014 transport, session handles, images, templates, and types used by @solarisdk/desktop and @solarisdk/sandbox.",
   "type": "module",
   "main": "./dist/index.js",