@start9labs/start-sdk 0.4.0-beta.9 → 1.0.0

package/package/lib/mainFn/CommandController.d.ts

@@ -1,33 +1,50 @@
-import * as T from "../../../base/lib/types";
-import { SubContainerHandle, SubContainer } from "../util/SubContainer";
-import { Drop } from "../util";
-export declare class CommandController<Manifest extends T.SDKManifest> extends Drop {
-    readonly runningAnswer: Promise<unknown>;
+import * as T from '../../../base/lib/types';
+import { SubContainer } from '../util/SubContainer';
+import { Drop } from '../util';
+import { DaemonCommandType } from './Daemons';
+/**
+ * Low-level controller for a single running process inside a subcontainer (or as a JS function).
+ *
+ * Manages the child process lifecycle: spawning, waiting, and signal-based termination.
+ * Used internally by {@link Daemon} to manage individual command executions.
+ *
+ * @typeParam Manifest - The service manifest type
+ * @typeParam C - The subcontainer type, or `null` for JS-only commands
+ */
+export declare class CommandController<Manifest extends T.SDKManifest, C extends SubContainer<Manifest> | null> extends Drop {
+    readonly runningAnswer: Promise<null>;
     private state;
     private readonly subcontainer;
     private process;
     readonly sigtermTimeout: number;
     private constructor();
-    static of<Manifest extends T.SDKManifest>(): (effects: T.Effects, subcontainer: SubContainer<Manifest>, command: T.CommandType, options: {
-        sigtermTimeout?: number;
-        runAsInit?: boolean;
-        env?: {
-            [variable: string]: string;
-        } | undefined;
-        cwd?: string | undefined;
-        user?: string | undefined;
-        onStdout?: (chunk: Buffer | string | any) => void;
-        onStderr?: (chunk: Buffer | string | any) => void;
-    }) => Promise<CommandController<Manifest>>;
-    get subContainerHandle(): SubContainerHandle;
-    wait({ timeout, keepSubcontainer }?: {
+    /**
+     * Factory method to create a new CommandController.
+     *
+     * Returns a curried async function: `(effects, subcontainer, exec) => CommandController`.
+     * If the exec spec has an `fn` property, runs the function; otherwise spawns a shell command
+     * in the subcontainer.
+     */
+    static of<Manifest extends T.SDKManifest, C extends SubContainer<Manifest> | null>(): (effects: T.Effects, subcontainer: C, exec: DaemonCommandType<Manifest, C>) => Promise<CommandController<Manifest, C>>;
+    /**
+     * Wait for the command to finish. Optionally terminate after a timeout.
+     * @param options.timeout - Milliseconds to wait before terminating. Defaults to no timeout.
+     */
+    wait({ timeout }?: {
         timeout?: number | undefined;
-        keepSubcontainer?: boolean | undefined;
-    }): Promise<unknown>;
-    term({ signal, timeout, keepSubcontainer, }?: {
+    }): Promise<void>;
+    /**
+     * Terminate the running command by sending a signal.
+     *
+     * Sends the specified signal (default: SIGTERM), then escalates to SIGKILL
+     * after the timeout expires. Destroys the subcontainer after the process exits.
+     *
+     * @param options.signal - The signal to send (default: SIGTERM)
+     * @param options.timeout - Milliseconds before escalating to SIGKILL
+     */
+    term({ signal, timeout }?: {
         signal?: NodeJS.Signals | undefined;
         timeout?: number | undefined;
-        keepSubcontainer?: boolean | undefined;
     }): Promise<void>;
     onDrop(): void;
 }

package/package/lib/mainFn/CommandController.js

@@ -37,9 +37,18 @@ exports.CommandController = void 0;
 const _1 = require(".");
 const types_1 = require("../../../base/lib/types");
 const T = __importStar(require("../../../base/lib/types"));
-const SubContainer_1 = require("../util/SubContainer");
 const util_1 = require("../util");
 const fs = __importStar(require("node:fs/promises"));
+const logErrorOnce_1 = require("../../../base/lib/util/logErrorOnce");
+/**
+ * Low-level controller for a single running process inside a subcontainer (or as a JS function).
+ *
+ * Manages the child process lifecycle: spawning, waiting, and signal-based termination.
+ * Used internally by {@link Daemon} to manage individual command executions.
+ *
+ * @typeParam Manifest - The service manifest type
+ * @typeParam C - The subcontainer type, or `null` for JS-only commands
+ */
 class CommandController extends util_1.Drop {
     constructor(runningAnswer, state, subcontainer, process, sigtermTimeout = _1.DEFAULT_SIGTERM_TIMEOUT) {
         super();
@@ -49,45 +58,73 @@ class CommandController extends util_1.Drop {
         this.process = process;
         this.sigtermTimeout = sigtermTimeout;
     }
+    /**
+     * Factory method to create a new CommandController.
+     *
+     * Returns a curried async function: `(effects, subcontainer, exec) => CommandController`.
+     * If the exec spec has an `fn` property, runs the function; otherwise spawns a shell command
+     * in the subcontainer.
+     */
     static of() {
-        return async (effects, subcontainer, command, options) => {
+        return async (effects, subcontainer, exec) => {
             try {
+                if ('fn' in exec) {
+                    const abort = new AbortController();
+                    const cell = {
+                        ctrl: new CommandController(exec.fn(subcontainer, abort.signal).then(async (command) => {
+                            if (subcontainer && command && !abort.signal.aborted) {
+                                const newCtrl = (await CommandController.of()(effects, subcontainer, command)).leak();
+                                Object.assign(cell.ctrl, newCtrl);
+                                return await cell.ctrl.runningAnswer;
+                            }
+                            else {
+                                cell.ctrl.state.exited = true;
+                            }
+                            return null;
+                        }), { exited: false }, subcontainer, abort, exec.sigtermTimeout),
+                    };
+                    return cell.ctrl;
+                }
                 let commands;
-                if (command instanceof T.UseEntrypoint) {
+                if (T.isUseEntrypoint(exec.command)) {
                     const imageMeta = await fs
                         .readFile(`/media/startos/images/${subcontainer.imageId}.json`, {
-                        encoding: "utf8",
+                        encoding: 'utf8',
                     })
-                        .catch(() => "{}")
+                        .catch(() => '{}')
                         .then(JSON.parse);
                     commands = imageMeta.entrypoint ?? [];
-                    commands = commands.concat(...(command.overridCmd ?? imageMeta.cmd ?? []));
+                    commands = commands.concat(...(exec.command.overridCmd ?? imageMeta.cmd ?? []));
                 }
                 else
-                    commands = (0, util_1.splitCommand)(command);
+                    commands = (0, util_1.splitCommand)(exec.command);
                 let childProcess;
-                if (options.runAsInit) {
+                if (exec.runAsInit) {
                     childProcess = await subcontainer.launch(commands, {
-                        env: options.env,
+                        env: exec.env,
+                        user: exec.user,
+                        cwd: exec.cwd,
                     });
                 }
                 else {
                     childProcess = await subcontainer.spawn(commands, {
-                        env: options.env,
-                        stdio: options.onStdout || options.onStderr ? "pipe" : "inherit",
+                        env: exec.env,
+                        user: exec.user,
+                        cwd: exec.cwd,
+                        stdio: exec.onStdout || exec.onStderr ? 'pipe' : 'inherit',
                     });
                 }
-                if (options.onStdout)
-                    childProcess.stdout?.on("data", options.onStdout);
-                if (options.onStderr)
-                    childProcess.stderr?.on("data", options.onStderr);
+                if (exec.onStdout)
+                    childProcess.stdout?.on('data', exec.onStdout);
+                if (exec.onStderr)
+                    childProcess.stderr?.on('data', exec.onStderr);
                 const state = { exited: false };
                 const answer = new Promise((resolve, reject) => {
-                    childProcess.on("exit", (code) => {
+                    childProcess.on('exit', (code) => {
                         state.exited = true;
                         if (code === 0 ||
                             code === 143 ||
-                            (code === null && childProcess.signalCode == "SIGTERM")) {
+                            (code === null && childProcess.signalCode == 'SIGTERM')) {
                             return resolve(null);
                         }
                         if (code) {
@@ -98,55 +135,82 @@ class CommandController extends util_1.Drop {
                         }
                     });
                 });
-                return new CommandController(answer, state, subcontainer, childProcess, options.sigtermTimeout);
+                return new CommandController(answer, state, subcontainer, childProcess, exec.sigtermTimeout);
             }
             catch (e) {
-                await subcontainer.destroy();
+                await subcontainer?.destroy();
                 throw e;
             }
         };
     }
-    get subContainerHandle() {
-        return new SubContainer_1.SubContainerHandle(this.subcontainer);
-    }
-    async wait({ timeout = types_1.NO_TIMEOUT, keepSubcontainer = false } = {}) {
+    /**
+     * Wait for the command to finish. Optionally terminate after a timeout.
+     * @param options.timeout - Milliseconds to wait before terminating. Defaults to no timeout.
+     */
+    async wait({ timeout = types_1.NO_TIMEOUT } = {}) {
         if (timeout > 0)
             setTimeout(() => {
-                this.term({ keepSubcontainer });
+                this.term();
             }, timeout);
         try {
-            return await this.runningAnswer;
+            if (timeout > 0 && this.process instanceof AbortController)
+                await Promise.race([
+                    this.runningAnswer,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for js command to exit')), timeout * 2)),
+                ]);
+            else
+                await this.runningAnswer;
         }
         finally {
             if (!this.state.exited) {
-                this.process.kill("SIGKILL");
+                if (this.process instanceof AbortController)
+                    this.process.abort();
+                else
+                    this.process.kill('SIGKILL');
             }
-            if (!keepSubcontainer)
-                await this.subcontainer.destroy();
+            await this.subcontainer?.destroy();
         }
     }
-    async term({ signal = types_1.SIGTERM, timeout = this.sigtermTimeout, keepSubcontainer = false, } = {}) {
+    /**
+     * Terminate the running command by sending a signal.
+     *
+     * Sends the specified signal (default: SIGTERM), then escalates to SIGKILL
+     * after the timeout expires. Destroys the subcontainer after the process exits.
+     *
+     * @param options.signal - The signal to send (default: SIGTERM)
+     * @param options.timeout - Milliseconds before escalating to SIGKILL
+     */
+    async term({ signal = types_1.SIGTERM, timeout = this.sigtermTimeout } = {}) {
         try {
             if (!this.state.exited) {
-                if (signal !== "SIGKILL") {
+                if (this.process instanceof AbortController)
+                    return this.process.abort();
+                if (signal !== 'SIGKILL') {
                     setTimeout(() => {
-                        if (!this.state.exited)
-                            this.process.kill("SIGKILL");
+                        if (this.process instanceof AbortController)
+                            this.process.abort();
+                        else
+                            this.process.kill('SIGKILL');
                     }, timeout);
                 }
                 if (!this.process.kill(signal)) {
                     console.error(`failed to send signal ${signal} to pid ${this.process.pid}`);
                 }
             }
-            await this.runningAnswer;
+            if (this.process instanceof AbortController)
+                await Promise.race([
+                    this.runningAnswer,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for js command to exit')), timeout * 2)),
+                ]);
+            else
+                await this.runningAnswer;
         }
         finally {
-            if (!keepSubcontainer)
-                await this.subcontainer.destroy();
+            await this.subcontainer?.destroy();
         }
     }
     onDrop() {
-        this.term({ keepSubcontainer: true }).catch(console.error);
+        this.term().catch(logErrorOnce_1.logErrorOnce);
     }
 }
 exports.CommandController = CommandController;

package/package/lib/mainFn/CommandController.js.map

@@ -1 +1 @@
-{"version":3,"file":"CommandController.js","sourceRoot":"","sources":["../../../../package/lib/mainFn/CommandController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CommandController.js","sourceRoot":"","sources":["../../../../package/lib/mainFn/CommandController.ts"],"names":[],"mappings":"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"}

package/package/lib/mainFn/Daemon.d.ts

@@ -1,33 +1,77 @@
-import * as T from "../../../base/lib/types";
-import { ExecSpawnable, SubContainer } from "../util/SubContainer";
-import { CommandController } from "./CommandController";
+import * as T from '../../../base/lib/types';
+import { Drop } from '../util';
+import { SubContainer, SubContainerRc } from '../util/SubContainer';
+import { CommandController } from './CommandController';
+import { DaemonCommandType } from './Daemons';
+import { Oneshot } from './Oneshot';
 /**
- * This is a wrapper around CommandController that has a state of off, where the command shouldn't be running
- * and the others state of running, where it will keep a living running command
+ * A managed long-running process wrapper around {@link CommandController}.
+ *
+ * When started, the daemon automatically restarts its underlying command on failure
+ * with exponential backoff (up to 30 seconds). When stopped, the command is terminated
+ * gracefully. Implements {@link Drop} for automatic cleanup when the context is left.
+ *
+ * @typeParam Manifest - The service manifest type
+ * @typeParam C - The subcontainer type, or `null` for JS-only daemons
  */
-export declare class Daemon<Manifest extends T.SDKManifest> {
+export declare class Daemon<Manifest extends T.SDKManifest, C extends SubContainer<Manifest> | null = SubContainer<Manifest> | null> extends Drop {
+    private subcontainer;
     private startCommand;
+    readonly oneshot: boolean;
     private commandController;
-    private shouldBeRunning;
-    constructor(startCommand: () => Promise<CommandController<Manifest>>);
-    get subContainerHandle(): undefined | ExecSpawnable;
-    static of<Manifest extends T.SDKManifest>(): (effects: T.Effects, subcontainer: SubContainer<Manifest>, command: T.CommandType, options: {
-        env?: {
-            [variable: string]: string;
-        } | undefined;
-        cwd?: string | undefined;
-        user?: string | undefined;
-        onStdout?: (chunk: Buffer | string | any) => void;
-        onStderr?: (chunk: Buffer | string | any) => void;
-        sigtermTimeout?: number;
-    }) => Promise<Daemon<Manifest>>;
+    protected exitedSuccess: boolean;
+    private onExitFns;
+    private loop;
+    private _managed;
+    protected constructor(subcontainer: C, startCommand: () => Promise<CommandController<Manifest, C>>, oneshot?: boolean);
+    /** Returns true if this daemon is a one-shot process (exits after success) */
+    isOneshot(): this is Oneshot<Manifest>;
+    /**
+     * Factory method to create a new Daemon.
+     *
+     * Returns a curried function: `(effects, subcontainer, exec) => Daemon`.
+     * Registers an `onLeaveContext` callback that terminates the daemon when the
+     * effects context is left.
+     */
+    static of<Manifest extends T.SDKManifest>(): <C extends SubContainer<Manifest> | null>(effects: T.Effects, subcontainer: C, exec: DaemonCommandType<Manifest, C>) => Daemon<Manifest, SubContainer<Manifest, T.Effects> | null>;
+    /**
+     * Start the daemon. If it is already running, this is a no-op.
+     *
+     * The daemon will automatically restart on failure with increasing backoff
+     * until {@link term} is called.
+     */
     start(): Promise<void>;
+    private runLoop;
+    /**
+     * Terminate the daemon, stopping its underlying command.
+     *
+     * Sends the configured signal (default SIGTERM) and waits for the process to exit.
+     * Optionally destroys the subcontainer after termination.
+     *
+     * @param termOptions - Optional termination settings
+     * @param termOptions.signal - The signal to send (default: SIGTERM)
+     * @param termOptions.timeout - Milliseconds to wait before SIGKILL
+     * @param termOptions.destroySubcontainer - Whether to destroy the subcontainer after exit
+     */
     term(termOptions?: {
         signal?: NodeJS.Signals | undefined;
         timeout?: number | undefined;
+        destroySubcontainer?: boolean;
     }): Promise<void>;
-    stop(termOptions?: {
-        signal?: NodeJS.Signals | undefined;
-        timeout?: number | undefined;
-    }): Promise<void>;
+    /**
+     * Mark this daemon as managed by a {@link Daemons} instance.
+     * Suppresses the individual `onLeaveContext` termination since the
+     * `Daemons` instance handles ordered shutdown.
+     */
+    markManaged(): void;
+    /** Get a reference-counted handle to the daemon's subcontainer, or null if there is none */
+    subcontainerRc(): SubContainerRc<Manifest> | null;
+    /** Check whether this daemon shares the same subcontainer as another daemon */
+    sharesSubcontainerWith(other: Daemon<Manifest, SubContainer<Manifest> | null>): boolean;
+    /**
+     * Register a callback to be invoked each time the daemon's process exits.
+     * @param fn - Callback receiving `true` on clean exit, `false` on error
+     */
+    onExit(fn: (success: boolean) => void): void;
+    onDrop(): void;
 }

package/package/lib/mainFn/Daemon.js

@@ -2,61 +2,183 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Daemon = void 0;
 const asError_1 = require("../../../base/lib/util/asError");
+const logErrorOnce_1 = require("../../../base/lib/util/logErrorOnce");
+const util_1 = require("../util");
 const CommandController_1 = require("./CommandController");
 const TIMEOUT_INCREMENT_MS = 1000;
 const MAX_TIMEOUT_MS = 30000;
 /**
- * This is a wrapper around CommandController that has a state of off, where the command shouldn't be running
- * and the others state of running, where it will keep a living running command
+ * A managed long-running process wrapper around {@link CommandController}.
+ *
+ * When started, the daemon automatically restarts its underlying command on failure
+ * with exponential backoff (up to 30 seconds). When stopped, the command is terminated
+ * gracefully. Implements {@link Drop} for automatic cleanup when the context is left.
+ *
+ * @typeParam Manifest - The service manifest type
+ * @typeParam C - The subcontainer type, or `null` for JS-only daemons
  */
-class Daemon {
-    constructor(startCommand) {
+class Daemon extends util_1.Drop {
+    constructor(subcontainer, startCommand, oneshot = false) {
+        super();
+        this.subcontainer = subcontainer;
         this.startCommand = startCommand;
+        this.oneshot = oneshot;
         this.commandController = null;
-        this.shouldBeRunning = false;
+        this.exitedSuccess = false;
+        this.onExitFns = [];
+        this.loop = null;
+        this._managed = false;
     }
-    get subContainerHandle() {
-        return this.commandController?.subContainerHandle;
+    /** Returns true if this daemon is a one-shot process (exits after success) */
+    isOneshot() {
+        return this.oneshot;
     }
+    /**
+     * Factory method to create a new Daemon.
+     *
+     * Returns a curried function: `(effects, subcontainer, exec) => Daemon`.
+     * Registers an `onLeaveContext` callback that terminates the daemon when the
+     * effects context is left.
+     */
     static of() {
-        return async (effects, subcontainer, command, options) => {
-            const startCommand = () => CommandController_1.CommandController.of()(effects, subcontainer, command, options);
-            return new Daemon(startCommand);
+        return (effects, subcontainer, exec) => {
+            let subc = subcontainer;
+            if (subcontainer && subcontainer.isOwned())
+                subc = subcontainer.rc();
+            const startCommand = () => CommandController_1.CommandController.of()(effects, (subc?.rc() ?? null), exec);
+            const res = new Daemon(subc, startCommand);
+            effects.onLeaveContext(() => {
+                if (!res._managed) {
+                    res.term({ destroySubcontainer: true }).catch((e) => (0, logErrorOnce_1.logErrorOnce)(e));
+                }
+            });
+            return res;
         };
     }
+    /**
+     * Start the daemon. If it is already running, this is a no-op.
+     *
+     * The daemon will automatically restart on failure with increasing backoff
+     * until {@link term} is called.
+     */
     async start() {
-        if (this.commandController) {
+        if (this.loop) {
             return;
         }
-        this.shouldBeRunning = true;
+        const abort = new AbortController();
+        const done = this.runLoop(abort.signal);
+        this.loop = { abort, done };
+    }
+    async runLoop(signal) {
         let timeoutCounter = 0;
-        (async () => {
-            while (this.shouldBeRunning) {
-                if (this.commandController)
-                    await this.commandController
-                        .term({ keepSubcontainer: true })
-                        .catch((err) => console.error(err));
-                this.commandController = await this.startCommand();
-                await this.commandController
-                    .wait({ keepSubcontainer: true })
-                    .catch((err) => console.error(err));
-                await new Promise((resolve) => setTimeout(resolve, timeoutCounter));
+        try {
+            while (!signal.aborted) {
+                if (this.commandController) {
+                    await this.commandController.term({}).catch(logErrorOnce_1.logErrorOnce);
+                    this.commandController = null;
+                }
+                try {
+                    this.commandController = await this.startCommand();
+                    if (signal.aborted) {
+                        await this.commandController.term({}).catch(logErrorOnce_1.logErrorOnce);
+                        this.commandController = null;
+                        break;
+                    }
+                    const success = await this.commandController.wait().then((_) => true, (err) => {
+                        if (!signal.aborted)
+                            (0, logErrorOnce_1.logErrorOnce)(err);
+                        return false;
+                    });
+                    this.commandController = null;
+                    if (signal.aborted)
+                        break;
+                    for (const fn of this.onExitFns) {
+                        try {
+                            fn(success);
+                        }
+                        catch (e) {
+                            console.error('EXIT handler', e);
+                        }
+                    }
+                    if (success && this.oneshot) {
+                        this.exitedSuccess = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    if (!signal.aborted)
+                        console.error(e);
+                }
+                if (signal.aborted)
+                    break;
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, timeoutCounter);
+                    signal.addEventListener('abort', () => {
+                        clearTimeout(timer);
+                        resolve();
+                    }, { once: true });
+                });
                 timeoutCounter += TIMEOUT_INCREMENT_MS;
                 timeoutCounter = Math.min(MAX_TIMEOUT_MS, timeoutCounter);
             }
-        })().catch((err) => {
-            console.error((0, asError_1.asError)(err));
-        });
+        }
+        finally {
+            this.loop = null;
+        }
     }
+    /**
+     * Terminate the daemon, stopping its underlying command.
+     *
+     * Sends the configured signal (default SIGTERM) and waits for the process to exit.
+     * Optionally destroys the subcontainer after termination.
+     *
+     * @param termOptions - Optional termination settings
+     * @param termOptions.signal - The signal to send (default: SIGTERM)
+     * @param termOptions.timeout - Milliseconds to wait before SIGKILL
+     * @param termOptions.destroySubcontainer - Whether to destroy the subcontainer after exit
+     */
     async term(termOptions) {
-        return this.stop(termOptions);
-    }
-    async stop(termOptions) {
-        this.shouldBeRunning = false;
-        await this.commandController
-            ?.term({ ...termOptions })
-            .catch((e) => console.error((0, asError_1.asError)(e)));
+        this.exitedSuccess = false;
+        this.onExitFns = [];
+        if (this.loop) {
+            this.loop.abort.abort();
+        }
+        const exiting = this.commandController?.term({ ...termOptions });
         this.commandController = null;
+        if (exiting)
+            await exiting.catch(logErrorOnce_1.logErrorOnce);
+        if (this.loop) {
+            await this.loop.done;
+        }
+        if (termOptions?.destroySubcontainer) {
+            await this.subcontainer?.destroy();
+        }
+    }
+    /**
+     * Mark this daemon as managed by a {@link Daemons} instance.
+     * Suppresses the individual `onLeaveContext` termination since the
+     * `Daemons` instance handles ordered shutdown.
+     */
+    markManaged() {
+        this._managed = true;
+    }
+    /** Get a reference-counted handle to the daemon's subcontainer, or null if there is none */
+    subcontainerRc() {
+        return this.subcontainer?.rc() ?? null;
+    }
+    /** Check whether this daemon shares the same subcontainer as another daemon */
+    sharesSubcontainerWith(other) {
+        return this.subcontainer?.guid === other.subcontainer?.guid;
+    }
+    /**
+     * Register a callback to be invoked each time the daemon's process exits.
+     * @param fn - Callback receiving `true` on clean exit, `false` on error
+     */
+    onExit(fn) {
+        this.onExitFns.push(fn);
+    }
+    onDrop() {
+        this.term().catch((e) => (0, logErrorOnce_1.logErrorOnce)((0, asError_1.asError)(e)));
     }
 }
 exports.Daemon = Daemon;