windows-development-sandbox 1.10.0 → 1.11.3

package/dist/host/web/live.js

@@ -0,0 +1,107 @@
+import { NO_QUESTIONS } from '../../app/kernel/index.js';
+/** A query unchanged this many reads in a row is read less often... */
+const CALM_READS = 4;
+/** ...down to this many times its own interval. */
+const SLOWEST = 4;
+export class LiveHub {
+    host;
+    polls = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    /** How many polls run (for tests and the idle check). */
+    get size() {
+        return this.polls.size;
+    }
+    /**
+     * Starts listening; the listener gets the current answer (at once when one is known) and every change. Returns the
+     * function that stops listening.
+     */
+    watch(query, input, listener) {
+        const key = query + '\u0000' + JSON.stringify(input ?? null);
+        let poll = this.polls.get(key);
+        if (!poll) {
+            poll = {
+                query,
+                input,
+                everyMs: this.host.liveMs(query) ?? 0,
+                listeners: new Set(),
+                timer: undefined,
+                busy: false,
+                last: undefined,
+                lastOutput: undefined,
+                calm: 0,
+                again: false,
+            };
+            this.polls.set(key, poll);
+            void this.read(poll);
+        }
+        else if (poll.last !== undefined)
+            listener({ output: poll.lastOutput });
+        else if (!poll.busy)
+            void this.read(poll); // the last read failed: try again for the newcomer
+        poll.listeners.add(listener);
+        const p = poll;
+        return () => {
+            p.listeners.delete(listener);
+            if (p.listeners.size)
+                return;
+            clearTimeout(p.timer);
+            this.polls.delete(key);
+        };
+    }
+    /** Something changed (an operation ran): every query reads again now, at its own pace. */
+    poke() {
+        for (const poll of this.polls.values()) {
+            poll.calm = 0;
+            void this.read(poll);
+        }
+    }
+    schedule(poll) {
+        clearTimeout(poll.timer);
+        if (!poll.everyMs || !this.isLive(poll))
+            return;
+        const factor = poll.calm >= CALM_READS ? Math.min(SLOWEST, 1 + Math.floor(poll.calm / CALM_READS)) : 1;
+        poll.timer = setTimeout(() => void this.read(poll), poll.everyMs * factor);
+        poll.timer.unref?.();
+    }
+    isLive(poll) {
+        return [...this.polls.values()].includes(poll);
+    }
+    async read(poll) {
+        if (poll.busy) {
+            poll.again = true;
+            return;
+        }
+        poll.busy = true;
+        clearTimeout(poll.timer);
+        try {
+            const output = await this.host.run(poll.query, poll.input, NO_QUESTIONS);
+            const text = JSON.stringify(output);
+            if (text === poll.last)
+                poll.calm++;
+            else {
+                poll.calm = 0;
+                poll.last = text;
+                poll.lastOutput = output;
+                for (const l of [...poll.listeners])
+                    l({ output });
+            }
+        }
+        catch (error) {
+            poll.calm = 0;
+            poll.last = undefined;
+            for (const l of [...poll.listeners])
+                l({ error });
+        }
+        finally {
+            poll.busy = false;
+        }
+        if (poll.again) {
+            poll.again = false;
+            void this.read(poll);
+            return;
+        }
+        this.schedule(poll);
+    }
+}

package/dist/host/web/rpc.d.ts

@@ -1,12 +1,17 @@
 import type { WebSocket } from 'ws';
 import { type RpcHost } from '../../app/kernel/index.js';
+import { LiveHub } from './live.js';
 export declare class RpcSession {
     private readonly ws;
     private readonly host;
+    /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
+    private readonly live;
     private readonly calls;
     private readonly subscriptions;
     private closed;
-    constructor(ws: WebSocket, host: RpcHost);
+    constructor(ws: WebSocket, host: RpcHost, 
+    /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
+    live?: LiveHub);
     start(): void;
     private send;
     /** A browser that sends something that is not one of our messages is closed. */

package/dist/host/web/rpc.js

@@ -1,4 +1,5 @@
-import { ANSWER_SCHEMAS, ClientMessageSchema, MAX_OPEN_PER_SOCKET, NO_QUESTIONS, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
+import { ANSWER_SCHEMAS, ClientMessageSchema, MAX_OPEN_PER_SOCKET, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
+import { LiveHub } from './live.js';
 /** What a question gets when the browser goes away before answering: no. */
 function declined(q) {
     return q.kind === 'confirm' ? false : undefined;
@@ -6,12 +7,16 @@ function declined(q) {
 export class RpcSession {
     ws;
     host;
+    live;
     calls = new Map();
     subscriptions = new Map();
     closed = false;
-    constructor(ws, host) {
+    constructor(ws, host, 
+    /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
+    live = new LiveHub(host)) {
         this.ws = ws;
         this.host = host;
+        this.live = live;
     }
     start() {
         this.ws.on('message', (data, binary) => this.receive(data, binary));
@@ -86,7 +91,12 @@ export class RpcSession {
         this.host
             .run(op, input, io)
             .then((output) => this.send({ t: 'result', id, output }), (e) => this.send({ t: 'error', id, error: toWireError(e) }))
-            .finally(() => this.calls.delete(id));
+            .finally(() => {
+            this.calls.delete(id);
+            // An operation may have changed what the live queries show: they read again now.
+            if (this.host.kind(op) === 'operation')
+                this.live.poke();
+        });
     }
     answer(id, value) {
         const waiting = this.calls.get(id);
@@ -103,38 +113,20 @@ export class RpcSession {
             this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + query + ' here.' } });
             return;
         }
-        const sub = { timer: undefined, last: undefined, busy: false };
-        this.subscriptions.set(id, sub);
-        const read = async () => {
-            if (sub.busy)
+        const stop = this.live.watch(query, input, (event) => {
+            if (this.subscriptions.get(id) !== stop)
                 return;
-            sub.busy = true;
-            try {
-                const output = await this.host.run(query, input, NO_QUESTIONS);
-                const text = JSON.stringify(output);
-                if (text !== sub.last && this.subscriptions.get(id) === sub) {
-                    sub.last = text;
-                    this.send({ t: 'data', id, output });
-                }
-            }
-            catch (e) {
-                sub.last = undefined;
-                this.send({ t: 'error', id, error: toWireError(e) });
-            }
-            finally {
-                sub.busy = false;
-            }
-        };
-        void read();
-        const every = this.host.liveMs(query);
-        if (every)
-            sub.timer = setInterval(() => void read(), every);
+            if ('output' in event)
+                this.send({ t: 'data', id, output: event.output });
+            else
+                this.send({ t: 'error', id, error: toWireError(event.error) });
+        });
+        this.subscriptions.set(id, stop);
     }
     unsubscribe(id) {
-        const sub = this.subscriptions.get(id);
-        if (sub?.timer)
-            clearInterval(sub.timer);
+        const stop = this.subscriptions.get(id);
         this.subscriptions.delete(id);
+        stop?.();
     }
     /** The browser went away: subscriptions stop, and questions still open are answered no. */
     close() {

package/dist/host/web/runner.d.ts

@@ -6,6 +6,10 @@ export interface WebRunOptions {
     readonly backend: WebBackend;
     readonly rpc?: RpcHost;
     readonly staticRoot: string;
+    /** This program's version, kept in the state file. */
+    readonly version: string;
+    /** End after this long unused while no sandbox runs (WebServerOptions.idleExitMs). */
+    readonly idleExitMs?: number;
 }
 export declare class WebRunner {
     private readonly options;

package/dist/host/web/runner.js

@@ -1,4 +1,5 @@
 import { fail } from '../../core/util/index.js';
+import { keepTasklistFresh } from '../sandbox/index.js';
 import { newToken } from './auth.js';
 import { WebServer } from './server.js';
 import { WebStore } from './state.js';
@@ -20,6 +21,7 @@ export class WebRunner {
             backend: this.options.backend,
             rpc: this.options.rpc,
             staticRoot: this.options.staticRoot,
+            idleExitMs: this.options.idleExitMs,
             onStop: stop,
         });
         try {
@@ -30,13 +32,22 @@ export class WebRunner {
                 fail('Port ' + this.options.port + ' is taken by another program.', 'Pick another with the web.port setting, then run sandbox web start again.');
             throw e;
         }
-        this.store.write({ pid: process.pid, port: server.port, token, startedAt: new Date().toISOString() });
+        this.store.write({
+            pid: process.pid,
+            port: server.port,
+            token,
+            startedAt: new Date().toISOString(),
+            version: this.options.version,
+        });
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
+        // Every browser's status reads share one process list instead of each running tasklist.
+        const stopTasklist = keepTasklistFresh();
         try {
             await stopped;
         }
         finally {
+            stopTasklist();
             this.store.clear();
             await server.stop();
         }

package/dist/host/web/server.d.ts

@@ -4,6 +4,8 @@ import type { Endpoint } from '../../shared/pty/index.js';
 import type { WebBackend } from './backend.js';
 /** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
 export declare const CONTENT_SECURITY_POLICY: string;
+/** The server ends after this long with no request, no socket and no sandbox running (it starts again with one). */
+export declare const IDLE_EXIT_MS: number;
 export declare const RPC_PATH = "/api/rpc";
 export interface WebServerOptions {
     /** 0 picks a free port (tests). */
@@ -18,6 +20,16 @@ export interface WebServerOptions {
     readonly dial?: (endpoint: Endpoint) => Promise<net.Socket>;
     /** The shared core's operations and queries the browser may run (none: /api/rpc is not served). */
     readonly rpc?: RpcHost;
+    /** End by itself (onStop) after this long unused while no sandbox runs; 0 or missing: never (tests). */
+    readonly idleExitMs?: number;
+    /** Heartbeat period (tests make it short). */
+    readonly heartbeatMs?: number;
+}
+/** A browser's socket: which kind, whether it answered the last ping, and when it was opened. */
+interface Tracked {
+    readonly kind: 'terminal' | 'rpc';
+    readonly opened: number;
+    alive: boolean;
 }
 export declare class WebServer {
     private readonly options;
@@ -25,12 +37,27 @@ export declare class WebServer {
     private readonly sockets;
     private readonly auth;
     private readonly files;
-    private terminals;
-    private rpcSockets;
+    private readonly tracked;
+    /** One poll per live query for all browsers together. */
+    private readonly live;
     private actualPort;
+    private lastUsed;
+    private heartbeat;
+    private idleCheck;
     constructor(options: WebServerOptions);
     get port(): number;
     start(): Promise<void>;
+    /** How many browser sockets are open, by kind. */
+    openSockets(kind: Tracked['kind']): number;
+    /**
+     * Drops sockets that did not answer the last ping (a tab that went away without closing: sleep, a killed browser),
+     * so they never hold a slot or a session connection.
+     */
+    private beat;
+    /** Nothing has used the server for a while and no sandbox runs: it ends (the next launch starts it again). */
+    private checkIdle;
+    /** Counts a new socket; at the limit, the oldest of its kind makes room (a new tab always works). */
+    private track;
     stop(): Promise<void>;
     private headers;
     private json;
@@ -45,3 +72,4 @@ export declare class WebServer {
     /** The RPC socket (after the same Origin and cookie checks as a terminal). */
     private upgradeRpc;
 }
+export {};

package/dist/host/web/server.js

@@ -5,9 +5,10 @@ import fs from 'node:fs';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
 import { UserError, safeText } from '../../core/util/index.js';
-import { MAX_CLIENT_MESSAGE_BYTES, MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS, } from '../../shared/web/index.js';
+import { MAX_CLIENT_MESSAGE_BYTES, MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS } from '../../shared/web/index.js';
 import { cookieHeader, csrfOk, hostAllowed, originAllowed, WebAuth } from './auth.js';
 import { TerminalBridge } from './bridge.js';
+import { LiveHub } from './live.js';
 import { RpcSession } from './rpc.js';
 import { StaticFiles } from './static-files.js';
 /** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
@@ -16,6 +17,10 @@ export const CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; s
 const MAX_BODY_BYTES = 16 * 1024;
 const MAX_TERMINALS = 16;
 const MAX_RPC_SOCKETS = 8;
+/** Every socket is pinged this often; one that has not answered the last ping by the next is dropped. */
+const HEARTBEAT_MS = 20_000;
+/** The server ends after this long with no request, no socket and no sandbox running (it starts again with one). */
+export const IDLE_EXIT_MS = 30 * 60_000;
 const SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
 export const RPC_PATH = '/api/rpc';
 class HttpFailure extends Error {
@@ -35,15 +40,23 @@ export class WebServer {
     });
     auth;
     files;
-    terminals = 0;
-    rpcSockets = 0;
+    tracked = new Map();
+    /** One poll per live query for all browsers together. */
+    live;
     actualPort = 0;
+    lastUsed = Date.now();
+    heartbeat;
+    idleCheck;
     constructor(options) {
         this.options = options;
         this.auth = new WebAuth(options.token);
         this.files = new StaticFiles(options.staticRoot);
+        this.live = options.rpc ? new LiveHub(options.rpc) : undefined;
         this.server = http.createServer((req, res) => void this.handle(req, res));
-        this.server.on('upgrade', (req, socket, head) => this.upgrade(req, socket, head));
+        this.server.on('upgrade', (req, socket, head) => {
+            this.lastUsed = Date.now();
+            this.upgrade(req, socket, head);
+        });
         this.server.headersTimeout = 15000;
         this.server.requestTimeout = 0; // creating a session waits for the agent to start
     }
@@ -56,11 +69,75 @@ export class WebServer {
             this.server.listen(this.options.port, '127.0.0.1', () => {
                 this.server.off('error', reject);
                 this.actualPort = this.server.address().port;
+                this.heartbeat = setInterval(() => this.beat(), this.options.heartbeatMs ?? HEARTBEAT_MS);
+                this.heartbeat.unref();
+                if (this.options.idleExitMs) {
+                    this.idleCheck = setInterval(() => void this.checkIdle(), Math.min(60_000, this.options.idleExitMs));
+                    this.idleCheck.unref();
+                }
                 resolve();
             });
         });
     }
+    /** How many browser sockets are open, by kind. */
+    openSockets(kind) {
+        return [...this.tracked.values()].filter((t) => t.kind === kind).length;
+    }
+    /**
+     * Drops sockets that did not answer the last ping (a tab that went away without closing: sleep, a killed browser),
+     * so they never hold a slot or a session connection.
+     */
+    beat() {
+        for (const [ws, t] of this.tracked) {
+            if (!t.alive) {
+                ws.terminate();
+                continue;
+            }
+            t.alive = false;
+            try {
+                ws.ping();
+            }
+            catch {
+                ws.terminate(); // the socket broke between the check and the ping
+            }
+        }
+    }
+    /** Nothing has used the server for a while and no sandbox runs: it ends (the next launch starts it again). */
+    async checkIdle() {
+        const limit = this.options.idleExitMs ?? 0;
+        if (!limit || this.tracked.size > 0 || Date.now() - this.lastUsed < limit)
+            return;
+        try {
+            if ((await this.options.backend.info()).sandbox === 'running')
+                return;
+        }
+        catch {
+            return; // cannot tell: keep running
+        }
+        this.options.onStop?.();
+    }
+    /** Counts a new socket; at the limit, the oldest of its kind makes room (a new tab always works). */
+    track(ws, kind, limit) {
+        const same = [...this.tracked.entries()]
+            .filter(([, t]) => t.kind === kind)
+            .sort((a, b) => a[1].opened - b[1].opened);
+        for (const [old] of same.slice(0, Math.max(0, same.length - limit + 1)))
+            old.close(4000, 'replaced by a newer page');
+        this.tracked.set(ws, { kind, opened: Date.now(), alive: true });
+        ws.on('pong', () => {
+            const t = this.tracked.get(ws);
+            if (t)
+                t.alive = true;
+        });
+        ws.on('message', () => (this.lastUsed = Date.now()));
+        ws.on('close', () => {
+            this.tracked.delete(ws);
+            this.lastUsed = Date.now();
+        });
+    }
     stop() {
+        clearInterval(this.heartbeat);
+        clearInterval(this.idleCheck);
         for (const client of this.sockets.clients)
             client.close(1001, 'server stopping');
         this.server.closeAllConnections();
@@ -82,6 +159,7 @@ export class WebServer {
         res.end(JSON.stringify(body));
     }
     async handle(req, res) {
+        this.lastUsed = Date.now();
         try {
             if (!hostAllowed(req.headers.host, this.actualPort))
                 throw new HttpFailure(421, 'Wrong host name.');
@@ -141,13 +219,6 @@ export class WebServer {
             return this.json(res, 200, await backend.info());
         if (pathname === '/api/sessions' && method === 'GET')
             return this.json(res, 200, await backend.sessions());
-        if (pathname === '/api/sessions' && method === 'POST') {
-            this.requireSameSite(req);
-            const request = newSessionRequest(await this.body(req));
-            if (!request)
-                throw new HttpFailure(400, 'Choose an agent and a project.');
-            return this.json(res, 201, await backend.create(request));
-        }
         if (pathname === '/api/stop' && method === 'POST') {
             this.requireSameSite(req);
             this.json(res, 200, { ok: true });
@@ -198,30 +269,24 @@ export class WebServer {
         if (!this.auth.signedIn(req.headers.cookie))
             return refuse('401 Unauthorized');
         if (rpc)
-            return this.upgradeRpc(req, socket, head, rpc, refuse);
+            return this.upgradeRpc(req, socket, head, rpc);
         if (!match)
             return refuse('404 Not Found');
-        if (this.terminals >= MAX_TERMINALS)
-            return refuse('503 Service Unavailable');
         const endpoint = this.options.backend.endpoint(match[1]);
         if (!endpoint)
             return refuse('404 Not Found');
         const cols = bounded(url.searchParams.get('cols'), MIN_COLS, MAX_COLS, 120);
         const rows = bounded(url.searchParams.get('rows'), MIN_ROWS, MAX_ROWS, 30);
         this.sockets.handleUpgrade(req, socket, head, (ws) => {
-            this.terminals++;
-            ws.on('close', () => this.terminals--);
+            this.track(ws, 'terminal', MAX_TERMINALS);
             void new TerminalBridge(ws, endpoint, cols, rows, this.options.dial).start();
         });
     }
     /** The RPC socket (after the same Origin and cookie checks as a terminal). */
-    upgradeRpc(req, socket, head, rpc, refuse) {
-        if (this.rpcSockets >= MAX_RPC_SOCKETS)
-            return refuse('503 Service Unavailable');
+    upgradeRpc(req, socket, head, rpc) {
         this.sockets.handleUpgrade(req, socket, head, (ws) => {
-            this.rpcSockets++;
-            ws.on('close', () => this.rpcSockets--);
-            new RpcSession(ws, rpc).start();
+            this.track(ws, 'rpc', MAX_RPC_SOCKETS);
+            new RpcSession(ws, rpc, this.live).start();
         });
     }
 }
@@ -229,10 +294,3 @@ function bounded(text, min, max, fallback) {
     const n = Number(text);
     return text !== null && Number.isInteger(n) && n >= min && n <= max ? n : fallback;
 }
-function newSessionRequest(body) {
-    if (typeof body !== 'object' || body === null)
-        return null;
-    const { harness, project } = body;
-    const ok = (v) => typeof v === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(v);
-    return ok(harness) && ok(project) ? { harness, project } : null;
-}

package/dist/host/web/state.d.ts

@@ -4,6 +4,7 @@ export declare const WebStateSchema: z.ZodObject<{
     port: z.ZodNumber;
     token: z.ZodString;
     startedAt: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type WebState = z.output<typeof WebStateSchema>;
 export declare class WebStore {

package/dist/host/web/state.js

@@ -10,6 +10,8 @@ export const WebStateSchema = z.strictObject({
     port: z.number().int().min(1).max(65535),
     token: z.string().regex(/^[0-9a-f]{64}$/),
     startedAt: z.string().max(64),
+    /** The version that started it (missing: an older one). Another version is replaced, never reused. */
+    version: z.string().max(64).optional(),
 });
 export class WebStore {
     storageRoot;