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

package/dist/cjs/client/Fifo.d.ts

@@ -0,0 +1,31 @@
+import net from 'node:net';
+/**
+ * The FIFOs of the standard streams of a process of containerd (the ones of its cio): created by mkfifo, the shim
+ * writing (or reading) them, read (or written) from the event loop
+ */
+export declare class ProcessFifo {
+    #private;
+    readonly path: string;
+    protected readonly direction: 'read' | 'write';
+    protected constructor(path: string, direction: 'read' | 'write');
+    /**
+     * Whether the FIFOs can be created (mkfifo of the system: coreutils, busybox)
+     */
+    static Supported(): boolean;
+    /**
+     * Create a FIFO, kept open (read and write) for the shim to open its end without waiting
+     * @param path
+     * @param direction read: the shim writes it (stdout, stderr), write: the shim reads it (stdin)
+     */
+    static Create(path: string, direction: 'read' | 'write'): ProcessFifo;
+    /**
+     * Its end opened, once the shim has opened its own one (after the creation of the process): the one kept closed,
+     * the end of the stream is the one of the shim
+     */
+    open(): net.Socket;
+    protected releaseKeeper(): void;
+    /**
+     * Close it
+     */
+    close(): void;
+}

package/dist/cjs/client/Fifo.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessFifo = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_net_1 = __importDefault(require("node:net"));
+/**
+ * The FIFOs of the standard streams of a process of containerd (the ones of its cio): created by mkfifo, the shim
+ * writing (or reading) them, read (or written) from the event loop
+ */
+class ProcessFifo {
+    #keeper;
+    #socket;
+    constructor(path, direction) {
+        this.path = path;
+        this.direction = direction;
+    }
+    /**
+     * Whether the FIFOs can be created (mkfifo of the system: coreutils, busybox)
+     */
+    static Supported() {
+        return (0, node_child_process_1.spawnSync)('mkfifo', ['--help'], { stdio: 'ignore' }).error === undefined;
+    }
+    /**
+     * Create a FIFO, kept open (read and write) for the shim to open its end without waiting
+     * @param path
+     * @param direction read: the shim writes it (stdout, stderr), write: the shim reads it (stdin)
+     */
+    static Create(path, direction) {
+        const result = (0, node_child_process_1.spawnSync)('mkfifo', ['-m', '0600', path], { stdio: ['ignore', 'ignore', 'pipe'] });
+        if (result.error || result.status !== 0)
+            throw new Error(`The FIFO ${path} is not created: ${result.error?.message ?? result.stderr.toString().trim()}`);
+        const fifo = new ProcessFifo(path, direction);
+        fifo.#keeper = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_RDWR | node_fs_1.constants.O_NONBLOCK);
+        return fifo;
+    }
+    /**
+     * Its end opened, once the shim has opened its own one (after the creation of the process): the one kept closed,
+     * the end of the stream is the one of the shim
+     */
+    open() {
+        if (this.#socket)
+            return this.#socket;
+        const flags = (this.direction === 'read' ? node_fs_1.constants.O_RDONLY : node_fs_1.constants.O_WRONLY) | node_fs_1.constants.O_NONBLOCK;
+        this.#socket = new node_net_1.default.Socket({ fd: (0, node_fs_1.openSync)(this.path, flags), readable: this.direction === 'read', writable: this.direction === 'write' });
+        this.releaseKeeper();
+        return this.#socket;
+    }
+    releaseKeeper() {
+        if (this.#keeper === undefined)
+            return;
+        (0, node_fs_1.closeSync)(this.#keeper);
+        this.#keeper = undefined;
+    }
+    /**
+     * Close it
+     */
+    close() {
+        this.releaseKeeper();
+        this.#socket?.destroy();
+    }
+}
+exports.ProcessFifo = ProcessFifo;

package/dist/cjs/client/ImageStore.d.ts

@@ -0,0 +1,258 @@
+import { ContainerdClient, type ContentDescriptor } from './ContainerdClient.js';
+import { type Message } from '@lakutata/grpc';
+import { type Platform } from './Platforms.js';
+import { type RegistryOptions } from './Registry.js';
+/**
+ * A manifest of an image (OCI, Docker)
+ */
+export type ImageManifest = {
+    schemaVersion: number;
+    mediaType?: string;
+    config: ContentDescriptor;
+    layers: ContentDescriptor[];
+    annotations?: Record<string, string>;
+};
+/**
+ * An index of the manifests of the platforms of an image
+ */
+export type ImageIndex = {
+    schemaVersion: number;
+    mediaType?: string;
+    manifests: ContentDescriptor[];
+    annotations?: Record<string, string>;
+};
+/**
+ * The configuration of an image (OCI): its platform, the configuration of its containers, its layers
+ */
+export type ImageConfigFile = {
+    architecture: string;
+    os: string;
+    variant?: string;
+    created?: string;
+    config?: {
+        Env?: string[];
+        Cmd?: string[];
+        Entrypoint?: string[];
+        WorkingDir?: string;
+        User?: string;
+        ExposedPorts?: Record<string, object>;
+        Volumes?: Record<string, object>;
+        Labels?: Record<string, string>;
+        StopSignal?: string;
+    };
+    rootfs: {
+        type: string;
+        diff_ids: string[];
+    };
+};
+/**
+ * The changes of the configuration of an image committed
+ */
+export type ImageConfigChanges = {
+    cmd?: string[];
+    entrypoint?: string[];
+    /**
+     * Its environment variables added or replaced (KEY=value)
+     */
+    env?: string[];
+    workingDir?: string;
+    user?: string;
+    labels?: Record<string, string>;
+    /**
+     * Its ports exposed (80, 53/udp)
+     */
+    exposedPorts?: string[];
+};
+/**
+ * An image of a platform, resolved: its manifest and its configuration
+ */
+export type ResolvedImage = {
+    image: Message;
+    name: string;
+    target: ContentDescriptor;
+    manifestDescriptor: ContentDescriptor;
+    manifest: ImageManifest;
+    config: ImageConfigFile;
+    platform: Platform;
+};
+/**
+ * The progress of the transfer of a blob
+ */
+export type TransferProgress = {
+    digest: string;
+    mediaType: string;
+    current: number;
+    total: number;
+};
+/**
+ * The options of a pull
+ */
+export type PullOptions = {
+    /**
+     * The platforms pulled: the one of the machine by default, all with "all"
+     */
+    platforms?: Platform[] | 'all';
+    registry?: RegistryOptions;
+    /**
+     * Unpack the layers of the platforms the machine runs (the ones of the store) into its snapshots, true by default
+     */
+    unpack?: boolean;
+    progress?: (progress: TransferProgress) => void;
+};
+/**
+ * The identifiers of the chain of layers (OCI): the ones of the snapshots of their unpacking
+ * @param diffIds
+ */
+export declare function chainIds(diffIds: string[]): string[];
+/**
+ * The images of containerd: pulled from the registries, unpacked into the snapshots, pushed, imported and exported
+ * (OCI image layouts, the archives of docker save), as ctr and nerdctl do: their content bound by the labels of the
+ * garbage collection of containerd, under a lease until the image references it
+ */
+export declare class ImageStore {
+    protected readonly client: ContainerdClient;
+    readonly snapshotter: string;
+    readonly temporary: string;
+    readonly runnablePlatforms: () => Platform[];
+    /**
+     * @param client
+     * @param snapshotter
+     * @param temporary the directory of the archives extracted (a disk of the machine, not a small tmpfs)
+     * @param runnablePlatforms the platforms the machine runs, unpacked by the pulls and the imports (the one of the
+     * machine by default)
+     */
+    constructor(client: ContainerdClient, snapshotter: string, temporary?: string, runnablePlatforms?: () => Platform[]);
+    /**
+     * The JSON of a content
+     * @param digest
+     */
+    protected readJson<T>(digest: string): Promise<T>;
+    /**
+     * The best manifest of an index for a platform, among the ones the content store has (or all)
+     * @param index
+     * @param platform
+     * @param local
+     */
+    protected chooseManifest(index: ImageIndex, platform: Platform, local: boolean): Promise<ContentDescriptor | undefined>;
+    /**
+     * The image of a name (the reference given or its normalized name), undefined when it does not exist
+     * @param name
+     */
+    get(name: string): Promise<Message | undefined>;
+    /**
+     * Resolve an image for a platform: its manifest and its configuration (the manifest of the platform of its index)
+     * @param name
+     * @param platform the one of the machine by default
+     */
+    resolve(name: string, platform?: Platform): Promise<ResolvedImage>;
+    /**
+     * The platforms of an image the content store has (the ones pulled)
+     * @param name
+     */
+    platforms(name: string): Promise<Platform[]>;
+    /**
+     * Unpack the layers of an image into the snapshots of the snapshotter (named by the chain of their identifiers), the
+     * configuration bound to the last one
+     * @param manifest
+     * @param lease
+     */
+    unpack(manifest: ImageManifest, lease: string): Promise<string>;
+    /**
+     * Write a manifest, its configuration and its layers (the blobs given by a source), bound by the labels of the
+     * garbage collection
+     * @param manifest
+     * @param blob the bytes of a blob (its stream)
+     * @param lease
+     * @param labels the labels of all the content (its source)
+     * @param progress
+     */
+    protected writeImage(manifest: ImageManifest, blob: (descriptor: ContentDescriptor) => Promise<Uint8Array | AsyncIterable<Uint8Array>>, lease: string, labels: Record<string, string>, progress?: (progress: TransferProgress) => void): Promise<void>;
+    /**
+     * The labels of a manifest binding its configuration and its layers
+     * @param manifest
+     */
+    protected manifestLabels(manifest: ImageManifest): Record<string, string>;
+    /**
+     * Pull an image from its registry: the manifests of the platforms asked (of its index), their configurations and
+     * their layers; the image named by its reference (docker.io/library/busybox:latest), unpacked for the machine
+     * @param reference
+     * @param options
+     */
+    pull(reference: string, options?: PullOptions): Promise<string>;
+    /**
+     * Unpack an image for the platforms the machine runs, among the ones the content store has (its manifests pulled):
+     * not the other platforms, nor the attestations (unknown/unknown)
+     * @param name
+     * @param lease
+     */
+    protected unpackFor(name: string, lease: string): Promise<void>;
+    /**
+     * Push an image to a registry (as another reference): the manifest of the platform asked; without it, the manifests
+     * of all the platforms and the index when the content store has all of them, the manifest of the machine's platform
+     * otherwise
+     * @param name
+     * @param options
+     */
+    push(name: string, options?: {
+        reference?: string;
+        platform?: Platform;
+        registry?: RegistryOptions;
+        progress?: (progress: TransferProgress) => void;
+    }): Promise<void>;
+    /**
+     * Commit the changes of a snapshot (the one of a container) on its image: a layer of their diff, the configuration
+     * of the image with its changes, a manifest of the platform, the image named (and unpacked)
+     * @param options
+     */
+    commit(options: {
+        image: string;
+        platform: Platform;
+        snapshotKey: string;
+        name: string;
+        changes?: ImageConfigChanges;
+        comment?: string;
+        author?: string;
+    }): Promise<string>;
+    /**
+     * Name an image again (a tag), its target the same
+     * @param name
+     * @param reference
+     */
+    tag(name: string, reference: string): Promise<string>;
+    /**
+     * Remove an image (its content and its snapshots are collected by containerd once nothing references them)
+     * @param name
+     */
+    remove(name: string): Promise<void>;
+    /**
+     * Import an archive of images: an OCI image layout (nerdctl save, docker save of Docker 25+), or an archive of
+     * docker save; the images named by the archive (or by a name given, to an archive of one image), unpacked for the
+     * platforms the machine runs
+     * @param source a file, or its stream
+     * @param options
+     */
+    import(source: string | NodeJS.ReadableStream, options?: {
+        name?: string;
+        unpack?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Write a manifest or an index of an archive, and what it references (the manifests the archive has)
+     * @param descriptor
+     * @param blob
+     * @param lease
+     */
+    protected writeTree(descriptor: ContentDescriptor, blob: (descriptor: ContentDescriptor) => Promise<AsyncIterable<Uint8Array>>, lease: string): Promise<void>;
+    /**
+     * Extract an archive into a directory
+     * @param source
+     * @param directory
+     */
+    protected extract(source: NodeJS.ReadableStream, directory: string): Promise<void>;
+    /**
+     * Export images into an archive: an OCI image layout (named by io.containerd.image.name), with the manifest.json of
+     * docker load (the manifest of the platform of the machine, or the first one)
+     * @param names
+     * @param destination a file, or its stream
+     */
+    export(names: string[], destination: string | NodeJS.WritableStream): Promise<void>;
+}