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

package/package/lib/util/SubContainer.d.ts

@@ -1,68 +1,133 @@
-import * as T from "../../../base/lib/types";
-import * as cp from "child_process";
-import { Buffer } from "node:buffer";
-import { Drop } from "./Drop";
-import { Mounts } from "../mainFn/Mounts";
-import { BackupEffects } from "../backup/Backups";
+import * as fs from 'fs/promises';
+import * as T from '../../../base/lib/types';
+import * as cp from 'child_process';
+import { Buffer } from 'node:buffer';
+import { Drop } from '../../../base/lib/util/Drop';
+import { Mounts } from '../mainFn/Mounts';
+import { BackupEffects } from '../backup/Backups';
+import { PathBase } from './Volume';
 export declare const execFile: typeof cp.execFile.__promisify__;
-type ExecResults = {
-    exitCode: number | null;
-    exitSignal: NodeJS.Signals | null;
-    stdout: string | Buffer;
-    stderr: string | Buffer;
-};
 export type ExecOptions = {
     input?: string | Buffer;
 };
 /**
- * This is the type that is going to describe what an subcontainer could do. The main point of the
- * subcontainer is to have commands that run in a chrooted environment. This is useful for running
- * commands in a containerized environment. But, I wanted the destroy to sometimes be doable, for example the
- * case where the subcontainer isn't owned by the process, the subcontainer shouldn't be destroyed.
+ * Interface representing an isolated container environment for running service processes.
+ *
+ * Provides methods for executing commands, spawning processes, mounting filesystems,
+ * and writing files within the container's rootfs. Comes in two flavors:
+ * {@link SubContainerOwned} (owns the underlying filesystem) and
+ * {@link SubContainerRc} (reference-counted handle to a shared container).
  */
-export interface ExecSpawnable {
-    get destroy(): undefined | (() => Promise<null>);
-    exec(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null): Promise<ExecResults>;
-    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null): Promise<{
+export interface SubContainer<Manifest extends T.SDKManifest, Effects extends T.Effects = T.Effects> extends Drop, PathBase {
+    readonly imageId: keyof Manifest['images'] & T.ImageId;
+    readonly rootfs: string;
+    readonly guid: T.Guid;
+    /**
+     * Get the absolute path to a file or directory within this subcontainer's rootfs
+     * @param path Path relative to the rootfs
+     */
+    subpath(path: string): string;
+    /**
+     * Apply filesystem mounts (volumes, assets, dependencies, backups) to this subcontainer.
+     * @param mounts - The Mounts configuration to apply
+     * @returns This subcontainer instance for chaining
+     */
+    mount(mounts: Effects extends BackupEffects ? Mounts<Manifest, {
+        subpath: string | null;
+        mountpoint: string;
+    }> : Mounts<Manifest, never>): Promise<this>;
+    /** Destroy this subcontainer and clean up its filesystem */
+    destroy: () => Promise<null>;
+    /**
+     * @description run a command inside this subcontainer
+     * DOES NOT THROW ON NONZERO EXIT CODE (see execFail)
+     * @param commands an array representing the command and args to execute
+     * @param options
+     * @param timeoutMs how long to wait before killing the command in ms
+     * @returns
+     */
+    exec(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
+        throw: () => {
+            stdout: string | Buffer;
+            stderr: string | Buffer;
+        };
+        exitCode: number | null;
+        exitSignal: NodeJS.Signals | null;
+        stdout: string | Buffer;
+        stderr: string | Buffer;
+    }>;
+    /**
+     * @description run a command inside this subcontainer, throwing on non-zero exit status
+     * @param commands an array representing the command and args to execute
+     * @param options
+     * @param timeoutMs how long to wait before killing the command in ms
+     * @returns
+     */
+    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
         stdout: string | Buffer;
         stderr: string | Buffer;
     }>;
+    /**
+     * Launch a command as the init (PID 1) process of the subcontainer.
+     * Replaces the current leader process.
+     * @param command - The command and arguments to execute
+     * @param options - Optional environment, working directory, and user overrides
+     */
+    launch(command: string[], options?: CommandOptions): Promise<cp.ChildProcessWithoutNullStreams>;
+    /**
+     * Spawn a command inside the subcontainer as a non-init process.
+     * @param command - The command and arguments to execute
+     * @param options - Optional environment, working directory, user, and stdio overrides
+     */
     spawn(command: string[], options?: CommandOptions & StdioOptions): Promise<cp.ChildProcess>;
+    /**
+     * @description Write a file to the subcontainer's filesystem
+     * @param path Path relative to the subcontainer rootfs (e.g. "/etc/config.json")
+     * @param data The data to write
+     * @param options Optional write options (same as node:fs/promises writeFile)
+     */
+    writeFile(path: string, data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView>, options?: Parameters<typeof fs.writeFile>[2]): Promise<void>;
+    /**
+     * Create a reference-counted handle to this subcontainer.
+     * The underlying container is only destroyed when all handles are released.
+     */
+    rc(): SubContainerRc<Manifest, Effects>;
+    /** Returns true if this is an owned subcontainer (not a reference-counted handle) */
+    isOwned(): this is SubContainerOwned<Manifest, Effects>;
 }
 /**
  * Want to limit what we can do in a container, so we want to launch a container with a specific image and the mounts.
- *
- * Implements:
- * @see {@link ExecSpawnable}
  */
-export declare class SubContainer<Manifest extends T.SDKManifest, Effects extends T.Effects = T.Effects> extends Drop implements ExecSpawnable {
+export declare class SubContainerOwned<Manifest extends T.SDKManifest, Effects extends T.Effects = T.Effects> extends Drop implements SubContainer<Manifest, Effects> {
     readonly effects: Effects;
-    readonly imageId: T.ImageId;
+    readonly imageId: keyof Manifest['images'] & T.ImageId;
     readonly rootfs: string;
     readonly guid: T.Guid;
     private destroyed;
+    rcs: number;
     private leader;
     private leaderExited;
     private waitProc;
     private constructor();
     static of<Manifest extends T.SDKManifest, Effects extends T.Effects>(effects: Effects, image: {
-        imageId: keyof Manifest["images"] & T.ImageId;
+        imageId: keyof Manifest['images'] & T.ImageId;
         sharedRun?: boolean;
     }, mounts: (Effects extends BackupEffects ? Mounts<Manifest, {
         subpath: string | null;
         mountpoint: string;
-    }> : Mounts<Manifest, never>) | null, name: string): Promise<SubContainer<T.SDKManifest, Effects>>;
+    }> : Mounts<Manifest, never>) | null, name: string): Promise<SubContainerOwned<Manifest, Effects>>;
     static withTemp<Manifest extends T.SDKManifest, T, Effects extends T.Effects>(effects: Effects, image: {
-        imageId: keyof Manifest["images"] & T.ImageId;
+        imageId: keyof Manifest['images'] & T.ImageId;
         sharedRun?: boolean;
     }, mounts: (Effects extends BackupEffects ? Mounts<Manifest, {
         subpath: string | null;
         mountpoint: string;
     }> : Mounts<Manifest, never>) | null, name: string, fn: (subContainer: SubContainer<Manifest, Effects>) => Promise<T>): Promise<T>;
+    subpath(path: string): string;
     mount(mounts: Effects extends BackupEffects ? Mounts<Manifest, {
         subpath: string | null;
         mountpoint: string;
-    }> : Mounts<Manifest, never>): Promise<SubContainer<Manifest, Effects>>;
+    }> : Mounts<Manifest, never>): Promise<this>;
     private killLeader;
     get destroy(): () => Promise<null>;
     onDrop(): void;
@@ -74,7 +139,7 @@ export declare class SubContainer<Manifest extends T.SDKManifest, Effects extend
      * @param timeoutMs how long to wait before killing the command in ms
      * @returns
      */
-    exec(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null): Promise<{
+    exec(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
         throw: () => {
             stdout: string | Buffer;
             stderr: string | Buffer;
@@ -91,35 +156,104 @@ export declare class SubContainer<Manifest extends T.SDKManifest, Effects extend
      * @param timeoutMs how long to wait before killing the command in ms
      * @returns
      */
-    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null): Promise<{
+    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
         stdout: string | Buffer;
         stderr: string | Buffer;
     }>;
     launch(command: string[], options?: CommandOptions): Promise<cp.ChildProcessWithoutNullStreams>;
     spawn(command: string[], options?: CommandOptions & StdioOptions): Promise<cp.ChildProcess>;
+    /**
+     * @description Write a file to the subcontainer's filesystem
+     * @param path Path relative to the subcontainer rootfs (e.g. "/etc/config.json")
+     * @param data The data to write
+     * @param options Optional write options (same as node:fs/promises writeFile)
+     */
+    writeFile(path: string, data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView>, options?: Parameters<typeof fs.writeFile>[2]): Promise<void>;
+    rc(): SubContainerRc<Manifest, Effects>;
+    isOwned(): this is SubContainerOwned<Manifest, Effects>;
 }
 /**
- * Take an subcontainer but remove the ability to add the mounts and the destroy function.
- * Lets other functions, like health checks, to not destroy the parents.
+ * A reference-counted handle to a {@link SubContainerOwned}.
  *
+ * Multiple `SubContainerRc` instances can share one underlying subcontainer.
+ * The subcontainer is destroyed only when the last reference is released via `destroy()`.
  */
-export declare class SubContainerHandle implements ExecSpawnable {
-    private subContainer;
-    constructor(subContainer: ExecSpawnable);
-    get destroy(): undefined;
-    exec(command: string[], options?: CommandOptions, timeoutMs?: number | null): Promise<ExecResults>;
-    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null): Promise<{
+export declare class SubContainerRc<Manifest extends T.SDKManifest, Effects extends T.Effects = T.Effects> extends Drop implements SubContainer<Manifest, Effects> {
+    private readonly subcontainer;
+    get imageId(): keyof Manifest["images"] & string;
+    get rootfs(): string;
+    get guid(): string;
+    subpath(path: string): string;
+    private destroyed;
+    private destroying;
+    constructor(subcontainer: SubContainerOwned<Manifest, Effects>);
+    static of<Manifest extends T.SDKManifest, Effects extends T.Effects>(effects: Effects, image: {
+        imageId: keyof Manifest['images'] & T.ImageId;
+        sharedRun?: boolean;
+    }, mounts: (Effects extends BackupEffects ? Mounts<Manifest, {
+        subpath: string | null;
+        mountpoint: string;
+    }> : Mounts<Manifest, never>) | null, name: string): Promise<SubContainerRc<Manifest, Effects>>;
+    static withTemp<Manifest extends T.SDKManifest, T, Effects extends T.Effects>(effects: Effects, image: {
+        imageId: keyof Manifest['images'] & T.ImageId;
+        sharedRun?: boolean;
+    }, mounts: (Effects extends BackupEffects ? Mounts<Manifest, {
+        subpath: string | null;
+        mountpoint: string;
+    }> : Mounts<Manifest, never>) | null, name: string, fn: (subContainer: SubContainer<Manifest, Effects>) => Promise<T>): Promise<T>;
+    mount(mounts: Effects extends BackupEffects ? Mounts<Manifest, {
+        subpath: string | null;
+        mountpoint: string;
+    }> : Mounts<Manifest, never>): Promise<this>;
+    get destroy(): () => Promise<null>;
+    onDrop(): void;
+    /**
+     * @description run a command inside this subcontainer
+     * DOES NOT THROW ON NONZERO EXIT CODE (see execFail)
+     * @param commands an array representing the command and args to execute
+     * @param options
+     * @param timeoutMs how long to wait before killing the command in ms
+     * @returns
+     */
+    exec(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
+        throw: () => {
+            stdout: string | Buffer;
+            stderr: string | Buffer;
+        };
+        exitCode: number | null;
+        exitSignal: NodeJS.Signals | null;
         stdout: string | Buffer;
         stderr: string | Buffer;
     }>;
+    /**
+     * @description run a command inside this subcontainer, throwing on non-zero exit status
+     * @param commands an array representing the command and args to execute
+     * @param options
+     * @param timeoutMs how long to wait before killing the command in ms
+     * @returns
+     */
+    execFail(command: string[], options?: CommandOptions & ExecOptions, timeoutMs?: number | null, abort?: AbortController): Promise<{
+        stdout: string | Buffer;
+        stderr: string | Buffer;
+    }>;
+    launch(command: string[], options?: CommandOptions): Promise<cp.ChildProcessWithoutNullStreams>;
     spawn(command: string[], options?: CommandOptions & StdioOptions): Promise<cp.ChildProcess>;
+    /**
+     * @description Write a file to the subcontainer's filesystem
+     * @param path Path relative to the subcontainer rootfs (e.g. "/etc/config.json")
+     * @param data The data to write
+     * @param options Optional write options (same as node:fs/promises writeFile)
+     */
+    writeFile(path: string, data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView>, options?: Parameters<typeof fs.writeFile>[2]): Promise<void>;
+    rc(): SubContainerRc<Manifest, Effects>;
+    isOwned(): this is SubContainerOwned<Manifest, Effects>;
 }
 export type CommandOptions = {
     /**
      * Environment variables to set for this command
      */
     env?: {
-        [variable: string]: string;
+        [variable in string]?: string;
     };
     /**
      * the working directory to run this command in
@@ -133,28 +267,62 @@ export type CommandOptions = {
 export type StdioOptions = {
     stdio?: cp.IOType;
 };
+/** UID/GID mapping for mount id-remapping (see kernel idmappings docs) */
+export type IdMap = {
+    fromId: number;
+    toId: number;
+    range: number;
+};
+/** Union of all mount option types supported by the subcontainer runtime */
 export type MountOptions = MountOptionsVolume | MountOptionsAssets | MountOptionsPointer | MountOptionsBackup;
+/** Mount options for binding a service volume into a subcontainer */
 export type MountOptionsVolume = {
-    type: "volume";
-    id: string;
+    type: 'volume';
+    volumeId: string;
     subpath: string | null;
     readonly: boolean;
+    filetype: 'file' | 'directory' | 'infer';
+    idmap: IdMap[];
 };
+/** Mount options for binding packaged static assets into a subcontainer */
 export type MountOptionsAssets = {
-    type: "assets";
+    type: 'assets';
     subpath: string | null;
+    filetype: 'file' | 'directory' | 'infer';
+    idmap: {
+        fromId: number;
+        toId: number;
+        range: number;
+    }[];
 };
+/** Mount options for binding a dependency package's volume into a subcontainer */
 export type MountOptionsPointer = {
-    type: "pointer";
+    type: 'pointer';
     packageId: string;
     volumeId: string;
     subpath: string | null;
     readonly: boolean;
+    idmap: {
+        fromId: number;
+        toId: number;
+        range: number;
+    }[];
 };
+/** Mount options for binding the backup directory into a subcontainer */
 export type MountOptionsBackup = {
-    type: "backup";
+    type: 'backup';
     subpath: string | null;
+    filetype: 'file' | 'directory' | 'infer';
+    idmap: {
+        fromId: number;
+        toId: number;
+        range: number;
+    }[];
 };
+/**
+ * Error thrown when a subcontainer command exits with a non-zero code or signal.
+ * Contains the full result including stdout, stderr, exit code, and exit signal.
+ */
 export declare class ExitError extends Error {
     readonly command: string;
     readonly result: {
@@ -170,4 +338,3 @@ export declare class ExitError extends Error {
         stderr: string | Buffer;
     });
 }
-export {};