@solarisdk/core 0.4.4 → 0.4.6

package/dist/handle.d.ts

@@ -131,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: {
@@ -146,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>;
@@ -161,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>;
@@ -300,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

@@ -127,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")
@@ -191,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);
@@ -210,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 () => {
@@ -320,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)
@@ -343,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,
@@ -387,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
@@ -621,11 +687,10 @@ export class SessionHandle {
         if (!this.hooks.revert) {
             return Promise.reject(new Error("revert requires a client-created handle"));
         }
+        const hadSocket = this.channel.hasSocket;
         return this.hooks.revert(this.id, snapshotId).then(async () => {
-            if (this.channel.connected) {
-                this.close({ quiet: true });
-                await this.channel.connect().catch(() => undefined);
-            }
+            if (hadSocket)
+                await this.channel.refresh();
         });
     }
     async pause() {
@@ -728,6 +793,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, markSessionReleased, unreleasedSessionIds, exitReminderMessages } 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, markSessionReleased, unreleasedSessionIds, exitReminderMessages } 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/transport.d.ts

@@ -81,6 +81,17 @@ export declare class ControlChannel {
      * `commands.start` / `pty.create` survive so callers can re-subscribe.
      */
     reconnect(): Promise<void>;
+    /**
+     * Swap the socket for a fresh, working one after the guest behind it was replaced in place (revert). The old socket
+     * is detached first, so its close, arriving whenever it likes (it may even have arrived already), cannot fail calls
+     * made on the new connection. Right after a restore the host can still be re-accepting the guest's control
+     * connection and closes a connection opened in that window within milliseconds (seen on staging as the first call
+     * failing with 1000/1005), so the new connection is proven with a cheap request and re-dialled a few times before
+     * this resolves. Never rejects: if no working connection can be had, calls retry lazily.
+     */
+    refresh(): Promise<void>;
+    /** True while the channel holds a socket, open or not. */
+    get hasSocket(): boolean;
     /** Register a "channel closed" callback for a stream id (cmdId/ptyId) so a
      * drop rejects its in-flight wait. Cleared on the stream's terminal frame.
      *

package/dist/transport.js

@@ -2,6 +2,9 @@ import { ActionError, ConnectionError, SolariError, TimeoutError, } from "./erro
 import { openWebSocket } from "./ws.js";
 const DEFAULT_CALL_TIMEOUT_MS = 300_000;
 const CONNECT_TIMEOUT_MS = 15_000;
+const REFRESH_MAX_ATTEMPTS = 4;
+const REFRESH_RETRY_BASE_MS = 300;
+const REFRESH_PROBE_TIMEOUT_MS = 5_000;
 const CONNECT_MAX_ATTEMPTS = 3;
 const CONNECT_RETRY_BASE_MS = 150;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -41,6 +44,7 @@ export class ControlChannel {
             return Promise.resolve();
         if (this.connecting)
             return this.connecting;
+        this.#detachSocket();
         this.closed = false;
         this.connecting = this.#connectWithRetry();
         return this.connecting;
@@ -117,15 +121,39 @@ export class ControlChannel {
     async reconnect() {
         if (this.connected)
             return;
-        if (this.ws) {
-            const old = this.ws;
-            this.ws = null;
-            this.#failAll(new ConnectionError("Control channel replaced by a reconnect"));
-            old.close();
-        }
+        this.#detachSocket();
         this.connecting = null;
         await this.connect();
     }
+    async refresh() {
+        for (let attempt = 1; attempt <= REFRESH_MAX_ATTEMPTS; attempt++) {
+            if (this.closed)
+                return;
+            try {
+                this.#detachSocket();
+                this.connecting = null;
+                await this.connect();
+                await this.#send("fs.stat", { path: "/" }, { timeoutMs: REFRESH_PROBE_TIMEOUT_MS });
+                return;
+            }
+            catch (err) {
+                if (!(err instanceof ConnectionError))
+                    return;
+                await sleep(REFRESH_RETRY_BASE_MS * attempt);
+            }
+        }
+    }
+    get hasSocket() {
+        return this.ws !== null;
+    }
+    #detachSocket() {
+        if (!this.ws)
+            return;
+        const old = this.ws;
+        this.ws = null;
+        this.#failAll(new ConnectionError("Control channel replaced by a reconnect"));
+        old.close();
+    }
     onStreamClose(id, cb) {
         if (this.closed || !this.ws || !this.ws.isOpen) {
             cb(new ConnectionError("Control channel closed"));

package/dist/types.d.ts

@@ -767,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 {
@@ -835,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.4",
+  "version": "0.4.6",
   "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",