@solarisdk/core 0.4.3 → 0.4.4

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 {
@@ -172,10 +182,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`. */

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 ` +
@@ -399,9 +410,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 +633,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 +641,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 +684,7 @@ export class SessionHandle {
         if (this.hooks.kill)
             await this.hooks.kill(this.id);
         this.killed = true;
+        markSessionReleased(this.id);
         this.close();
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
+export { DEFAULT_COMMAND_TIMEOUT_MS, 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 { DEFAULT_COMMAND_TIMEOUT_MS, 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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",