@lakutata/containerd 0.0.0-stage → 3.0.0-beta.1

package/dist/types/client/ContainerStore.d.ts

@@ -0,0 +1,558 @@
+import { type BigIntStats } from 'node:fs';
+import { Readable } from 'node:stream';
+import { ContainerdClient } from './ContainerdClient.js';
+import { type Message } from '@lakutata/grpc';
+import { type Platform } from './Platforms.js';
+import { ImageStore, type ImageConfigChanges, type ResolvedImage } from './ImageStore.js';
+import { VolumeStore } from './Volumes.js';
+import { NetworkStore, type CNINetwork, type ContainerNetworkInterface, type PortMapping } from './Networks.js';
+import { type SpecDevice } from './Spec.js';
+import { type SeccompProfile } from './Seccomp.js';
+/**
+ * The labels of the containers: the ones of nerdctl (nerdctl ps, nerdctl logs know them), the ones of the restart
+ * monitor of containerd
+ */
+export declare const ContainerLabels: {
+    readonly NAME: "nerdctl/name";
+    readonly HOSTNAME: "nerdctl/hostname";
+    readonly PLATFORM: "nerdctl/platform";
+    readonly LOG_URI: "nerdctl/log-uri";
+    readonly STATE_DIR: "nerdctl/state-dir";
+    readonly NETWORKS: "nerdctl/networks";
+    readonly PORTS: "nerdctl/ports";
+    readonly MOUNTS: "nerdctl/mounts";
+    readonly STOP_SIGNAL: "io.containerd.image.config.stop-signal";
+    readonly RESTART_POLICY: "containerd.io/restart.policy";
+    readonly RESTART_STATUS: "containerd.io/restart.status";
+    readonly RESTART_LOG_URI: "containerd.io/restart.loguri";
+};
+/**
+ * The restart policies of the containers (the ones of the restart monitor of containerd): no, always,
+ * unless-stopped, on-failure (on-failure:N, N restarts at most)
+ */
+export type RestartPolicy = 'no' | 'always' | 'unless-stopped' | 'on-failure' | `on-failure:${number}`;
+/**
+ * The statuses of the containers
+ */
+export type ContainerStatus = 'created' | 'running' | 'paused' | 'pausing' | 'restarting' | 'exited' | 'unknown';
+/**
+ * The state of a container: its task (its process), its last exit
+ */
+export type ContainerRuntimeState = {
+    status: ContainerStatus;
+    running: boolean;
+    paused: boolean;
+    pid: number;
+    exitCode: number;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+};
+/**
+ * A mount of a container: a directory or a file of the host (bind), a tmpfs
+ */
+export type ContainerMount = {
+    type?: 'bind' | 'tmpfs' | 'volume';
+    /**
+     * The directory (or the file) of the host of a bind, the name of a volume (created when it does not exist)
+     */
+    source?: string;
+    target: string;
+    readonly?: boolean;
+    /**
+     * The options of the mount (size=64m for a tmpfs, the propagation of a bind: rshared…)
+     */
+    options?: string[];
+};
+/**
+ * A device of the host given to a container
+ */
+export type ContainerDeviceMapping = {
+    hostPath: string;
+    containerPath?: string;
+    permissions?: string;
+};
+/**
+ * The options of the creation of a container
+ */
+export type ContainerCreateOptions = {
+    image: string;
+    name?: string;
+    platform?: Platform;
+    hostname?: string;
+    cmd?: string[];
+    entrypoint?: string[];
+    env?: Record<string, string>;
+    workingDir?: string;
+    user?: string;
+    labels?: Record<string, string>;
+    terminal?: boolean;
+    privileged?: boolean;
+    readonlyRootfs?: boolean;
+    capAdd?: string[];
+    capDrop?: string[];
+    /**
+     * The profile of seccomp: the default one of containerd (and nerdctl), unconfined, or the file of a profile of OCI
+     * (the linux.seccomp of its specification); the privileged containers are unconfined
+     */
+    seccompProfile?: 'default' | 'unconfined' | string;
+    mounts?: ContainerMount[];
+    devices?: ContainerDeviceMapping[];
+    /**
+     * The devices the cgroup allows besides the ones given, as Docker writes them ("c 188:* rwm"): the devices plugged
+     * after the start, given by a bind mount of /dev (or of /dev/serial, /dev/bus/usb)
+     */
+    deviceCgroupRules?: string[];
+    /**
+     * The network of the container: the one of the host, none (its loopback only), or networks of CNI (bridge, the
+     * default one of nerdctl), with their addresses
+     */
+    network?: 'host' | 'none' | {
+        name: string;
+        ip?: string;
+        ipv6?: string;
+    }[];
+    /**
+     * The ports published on the host (on its first network of CNI)
+     */
+    ports?: PortMapping[];
+    pidHost?: boolean;
+    ipcHost?: boolean;
+    /**
+     * The cgroup namespace: a private one (on cgroup v2), or the one of the host
+     */
+    cgroupns?: 'private' | 'host';
+    memory?: number;
+    memorySwap?: number;
+    cpus?: number;
+    cpuShares?: number;
+    cpuset?: string;
+    pidsLimit?: number;
+    oomKillDisable?: boolean;
+    sysctls?: Record<string, string>;
+    shmSize?: number;
+    restart?: RestartPolicy;
+    stopSignal?: string;
+    extraHosts?: Record<string, string>;
+    dns?: string[];
+};
+/**
+ * The options of the store of the containers
+ */
+export type ContainerStoreOptions = {
+    snapshotter: string;
+    runtime: string;
+    cgroupManager: 'cgroupfs' | 'systemd';
+    /**
+     * The directory of the states of the containers (their logs, their hosts, resolv.conf and hostname)
+     */
+    dataRoot: string;
+    /**
+     * The size of the logs of a container rotated (once): 0 never
+     */
+    logMaxSize: number;
+};
+/**
+ * The result of an execution in a container
+ */
+export type ExecResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * The state of a container written by the store (its last exit, its task deleted)
+ */
+type StoredState = {
+    startedAt?: string;
+    finishedAt?: string;
+    exitCode?: number;
+};
+/**
+ * The resolv.conf of a container: the one of the host, without its local name servers on its own network (the ones of
+ * Google when it has no other one, as Docker does)
+ * @param content
+ * @param ownNetwork
+ */
+export declare function resolvConf(content: string, ownNetwork: boolean): string;
+/**
+ * An error of the runtime refusing the profile of seccomp of a container (a runc built without seccomp), with what to do
+ * @param error
+ */
+export declare function seccompHint(error: unknown): unknown;
+/**
+ * The resources of a container used (its cgroup, its interfaces of network)
+ */
+export type ContainerResourceStats = {
+    read: Date;
+    pids: {
+        current: number;
+        limit: number;
+    };
+    cpu: {
+        /**
+         * Its time on the CPUs in nanoseconds, in the user mode and in the kernel mode
+         */
+        usage: number;
+        user: number;
+        system: number;
+        throttledPeriods: number;
+        throttledTime: number;
+        onlineCpus: number;
+        /**
+         * Its use of the CPUs during the interval of the sampling (100 is one CPU used all the time)
+         */
+        percent: number;
+    };
+    memory: {
+        usage: number;
+        /**
+         * Its usage without the cache which can be freed (the one of docker stats)
+         */
+        workingSet: number;
+        limit: number;
+        cache: number;
+        swap: number;
+        oomKills: number;
+    };
+    blkio: {
+        readBytes: number;
+        writeBytes: number;
+        readOps: number;
+        writeOps: number;
+    };
+    networks: Record<string, {
+        rxBytes: number;
+        rxPackets: number;
+        rxErrors: number;
+        rxDropped: number;
+        txBytes: number;
+        txPackets: number;
+        txErrors: number;
+        txDropped: number;
+    }>;
+};
+/**
+ * A terminal of a process executed in a container: its input, its output, its size, its exit
+ */
+export type ContainerTerminal = {
+    execId: string;
+    input: NodeJS.WritableStream & {
+        end(): unknown;
+    };
+    output: Readable;
+    resize(cols: number, rows: number): Promise<void>;
+    exited: Promise<number>;
+    close(): Promise<void>;
+};
+/**
+ * The resources of a running container updated
+ */
+export type ContainerResourceUpdate = {
+    memory?: number;
+    memorySwap?: number;
+    cpus?: number;
+    cpuShares?: number;
+    cpuset?: string;
+    pidsLimit?: number;
+    oomKillDisable?: boolean;
+    restart?: RestartPolicy | '';
+};
+/**
+ * The number of a signal (SIGTERM, TERM, 15)
+ * @param signal
+ */
+export declare function signalNumber(signal: string | number): number;
+/**
+ * Whether the kernel limits the swap of the cgroups (Docker discards the swap limits otherwise): the files of the swap
+ * limits, in the cgroups below the root on cgroup v2 (the root has none)
+ */
+export declare function isSwapLimitSupported(): boolean;
+/**
+ * The swap limit of a container (its memory and its swap together), as Docker and nerdctl give it: twice its memory
+ * limit by default, -1 unlimited; none without a memory limit, or when the kernel does not limit the swap
+ * @param memory
+ * @param memorySwap
+ */
+export declare function swapLimit(memory: number | undefined, memorySwap: number | undefined): number | undefined;
+/**
+ * The containers of containerd: created from the images (their specifications of OCI, their snapshots), their tasks
+ * started, stopped, executed in; their logs written by the shims of containerd (file://), kept by the restart monitor
+ * of containerd as their restart policies ask
+ */
+export declare class ContainerStore {
+    protected readonly client: ContainerdClient;
+    protected readonly images: ImageStore;
+    protected readonly networks: NetworkStore;
+    readonly options: ContainerStoreOptions;
+    readonly volumes: VolumeStore;
+    constructor(client: ContainerdClient, images: ImageStore, networks: NetworkStore, options: ContainerStoreOptions, volumes?: VolumeStore);
+    /**
+     * The names of the volumes of a container
+     * @param container
+     */
+    static Volumes(container: Message): string[];
+    /**
+     * The networks of CNI of a container
+     * @param network
+     * @protected
+     */
+    protected cniNetworks(network: ContainerCreateOptions['network']): Promise<{
+        network: CNINetwork;
+        ip?: string;
+        ipv6?: string;
+    }[]>;
+    /**
+     * The profile of seccomp of a container, as nerdctl gives it: none for the privileged ones, unconfined ones and when
+     * the kernel does not filter the system calls; the default one by its capabilities; the one of a file
+     * @param options
+     * @protected
+     */
+    protected seccomp(options: ContainerCreateOptions): Promise<SeccompProfile | undefined>;
+    /**
+     * The interfaces of a container on its networks of CNI (their addresses while it runs)
+     * @param container
+     */
+    interfaces(container: Message): Promise<ContainerNetworkInterface[]>;
+    /**
+     * The directory of the state of a container
+     * @param id
+     */
+    stateDir(id: string): string;
+    /**
+     * The file of the logs of a container
+     * @param id
+     */
+    logFile(id: string): string;
+    /**
+     * The state written of a container
+     * @param id
+     */
+    protected readState(id: string): Promise<StoredState>;
+    protected writeState(id: string, state: StoredState): Promise<void>;
+    /**
+     * The settings a container was created with by the component (its update creates it again with them)
+     * @param id
+     */
+    readSettings<T = Record<string, any>>(id: string): Promise<T | undefined>;
+    writeSettings(id: string, settings: object): Promise<void>;
+    /**
+     * Name a container again (its label of nerdctl)
+     * @param container
+     * @param name
+     */
+    rename(container: Message, name: string): Promise<void>;
+    /**
+     * Find a container: by its identifier, by its name, by a prefix of its identifier (only one)
+     * @param idOrName
+     */
+    find(idOrName: string): Promise<Message | undefined>;
+    /**
+     * The containers
+     * @param filters the filters of containerd (labels."app"==web)
+     */
+    list(filters?: string[]): Promise<Message[]>;
+    /**
+     * The devices of a host path (a device, or the ones of a directory)
+     * @param mapping
+     */
+    protected devices(mapping: ContainerDeviceMapping): Promise<SpecDevice[]>;
+    /**
+     * A device of the host, by the stats of its node (its major and minor numbers of its rdev, as glibc splits it)
+     * @param hostPath
+     * @param containerPath
+     * @param stats
+     * @param permissions
+     */
+    protected static Device(hostPath: string, containerPath: string, stats: BigIntStats, permissions: string): SpecDevice;
+    /**
+     * The devices of the host given to a privileged container, as containerd's WithHostDevices gives them: the
+     * character and block devices of /dev and of its subdirectories, without the links, the console and the directories
+     * of the pseudo terminals, the shared memory, the descriptors and the queues
+     * @param directory
+     */
+    protected hostDevices(directory?: string): Promise<SpecDevice[]>;
+    /**
+     * The arguments of the process of a container: its entrypoint and its command, as Docker composes them
+     * @param resolved
+     * @param options
+     */
+    protected args(resolved: ResolvedImage, options: ContainerCreateOptions): string[];
+    /**
+     * Create a container of an image: its snapshot (its root file system, the image unpacked), its specification, its
+     * state directory (its hosts, resolv.conf, hostname, logs)
+     * @param options
+     */
+    create(options: ContainerCreateOptions): Promise<Message>;
+    /**
+     * The state of a container: the one of its task, its last exit when it has none
+     * @param container
+     */
+    state(container: Message): Promise<ContainerRuntimeState>;
+    /**
+     * Rotate the logs of a container once they are larger than the size of the options: copied to the file .1, the
+     * file truncated (the shim writes to its end)
+     * @param id
+     */
+    rotateLogs(id: string): Promise<void>;
+    /**
+     * Delete the task of a container (stopped), its exit kept
+     * @param id
+     */
+    protected deleteTask(id: string): Promise<void>;
+    /**
+     * Set the labels of a container
+     * @param container
+     * @param labels
+     */
+    protected label(container: Message, labels: Record<string, string>): Promise<void>;
+    /**
+     * Start a container: a new task of its snapshot (the one of its previous run deleted), its output written to its
+     * logs
+     * @param container
+     */
+    start(container: Message): Promise<number>;
+    /**
+     * Wait for the task of a container to exit, at most a time
+     * @param id
+     * @param timeout milliseconds
+     */
+    protected waitExit(id: string, timeout: number): Promise<boolean>;
+    /**
+     * Stop a container: its stop signal (SIGTERM, the one of its image) sent, then SIGKILL to all its processes after a
+     * time; its task deleted, its restart monitor told not to restart it
+     * @param container
+     * @param options
+     */
+    stop(container: Message, options?: {
+        timeout?: number;
+        signal?: string | number;
+    }): Promise<void>;
+    /**
+     * Send a signal to a container (its main process, or all its processes)
+     * @param container
+     * @param signal
+     * @param all
+     */
+    kill(container: Message, signal?: string | number, all?: boolean): Promise<void>;
+    pause(container: Message): Promise<void>;
+    resume(container: Message): Promise<void>;
+    /**
+     * Check that a container has a task which did not exit (the shim refuses to pause or resume a stopped one with an
+     * error of no code)
+     * @param container
+     * @protected
+     */
+    protected running(container: Message): Promise<void>;
+    /**
+     * The processes of a running container (their identifiers on the host)
+     * @param container
+     */
+    processes(container: Message): Promise<number[]>;
+    /**
+     * Wait for the main process of a container to exit: its exit code; the last one at once when it has no task (never
+     * started: 0, stopped: its task deleted, its exit kept by the store)
+     * @param container
+     * @param signal
+     */
+    wait(container: Message, signal?: AbortSignal): Promise<number>;
+    /**
+     * The error of an operation on the task of a container: the container is not running when it has no task (or its
+     * process exited)
+     * @param container
+     * @param error
+     * @protected
+     */
+    protected taskError(container: Message, error: unknown): unknown;
+    /**
+     * Remove a container: its task (a running one only when forced), its snapshot, its state directory
+     * @param container
+     * @param force
+     */
+    remove(container: Message, force?: boolean): Promise<void>;
+    /**
+     * Execute a command in a running container, its output captured: its standard output and its error apart (FIFOs,
+     * mkfifo of the system), or together in its standard output without mkfifo (the files of the shim)
+     * @param container
+     * @param options
+     */
+    exec(container: Message, options: {
+        cmd: string[];
+        env?: Record<string, string>;
+        workingDir?: string;
+        user?: string;
+        stdin?: string | Buffer;
+        timeout?: number;
+    }): Promise<ExecResult>;
+    /**
+     * The logs of a container: its last lines, followed while it runs (until the signal aborts)
+     * @param container
+     * @param options
+     */
+    logs(container: Message, options?: {
+        tail?: number;
+        follow?: boolean;
+        signal?: AbortSignal;
+    }): Readable;
+    /**
+     * A sample of the resources a running container uses
+     * @param container
+     * @protected
+     */
+    protected sample(container: Message): Promise<Omit<ContainerResourceStats, 'cpu'> & {
+        cpu: Omit<ContainerResourceStats['cpu'], 'percent'>;
+    }>;
+    /**
+     * The resources a running container uses: two samples, its use of the CPUs between them
+     * @param container
+     * @param interval milliseconds between the samples
+     */
+    stats(container: Message, interval?: number): Promise<ContainerResourceStats>;
+    /**
+     * Open a terminal in a running container: a process executed with its pseudo terminal, its input and its output by
+     * FIFOs (mkfifo of the system)
+     * @param container
+     * @param options
+     */
+    terminal(container: Message, options: {
+        cmd: string[];
+        cols?: number;
+        rows?: number;
+        env?: Record<string, string>;
+        workingDir?: string;
+        user?: string;
+    }): Promise<ContainerTerminal>;
+    /**
+     * Update the resources of a container (its specification, the cgroup of its running task) and its restart policy,
+     * without restarting it (docker update)
+     * @param container
+     * @param update
+     */
+    updateResources(container: Message, update: ContainerResourceUpdate): Promise<void>;
+    /**
+     * Commit a container: the changes of its file system as a layer on its image, a new image (its container paused
+     * meanwhile when it runs, by default)
+     * @param container
+     * @param options
+     */
+    commit(container: Message, options: {
+        name: string;
+        pause?: boolean;
+        changes?: ImageConfigChanges;
+        comment?: string;
+        author?: string;
+    }): Promise<string>;
+    /**
+     * Archive a path of the file system of a container (tar): the one of its running process (its mounts with it), or
+     * the one of its snapshot when it is not running; its symbolic links resolved in it
+     * @param container
+     * @param file an absolute path in the container
+     * @param destination
+     */
+    archive(container: Message, file: string, destination: NodeJS.WritableStream): Promise<void>;
+    /**
+     * The name of a container
+     * @param container
+     */
+    static Name(container: Message): string;
+}
+export {};