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

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

@@ -0,0 +1,221 @@
+/**
+ * A network of CNI (a configuration list of /etc/cni/net.d): the ones of nerdctl, the others of the machine
+ */
+export type CNINetwork = {
+    name: string;
+    /**
+     * Its identifier (the one of nerdctl, or the digest of its name)
+     */
+    id: string;
+    /**
+     * Its configuration list
+     */
+    file: string;
+    labels: Record<string, string>;
+    cniVersion: string;
+    /**
+     * The type of its first plugin (bridge, macvlan, ipvlan…)
+     */
+    driver: string;
+    subnets: string[];
+    gateways: string[];
+    plugins: Record<string, any>[];
+    /**
+     * Created by nerdctl (or by this package): removable
+     */
+    managed: boolean;
+};
+/**
+ * The options of the creation of a network
+ */
+export type CNINetworkCreateOptions = {
+    name: string;
+    driver?: 'bridge' | 'macvlan' | 'ipvlan';
+    /**
+     * Its subnet (CIDR of IPv4), a free one of 10.4.0.0/16 by default
+     */
+    subnet?: string;
+    gateway?: string;
+    /**
+     * The range of its addresses given to the containers (CIDR in its subnet)
+     */
+    ipRange?: string;
+    /**
+     * The interface of the host of a macvlan or ipvlan network
+     */
+    parent?: string;
+    /**
+     * Without the gateway and the masquerade of the host (bridge)
+     */
+    internal?: boolean;
+    mtu?: number;
+    labels?: Record<string, string>;
+    /**
+     * Its subnet of IPv6 (CIDR), besides its subnet of IPv4
+     */
+    ipv6Subnet?: string;
+    /**
+     * Its gateway of IPv6, the first address of its subnet by default
+     */
+    ipv6Gateway?: string;
+};
+/**
+ * A port of a container published on the host
+ */
+export type PortMapping = {
+    hostPort: number;
+    containerPort: number;
+    protocol: 'tcp' | 'udp' | 'sctp';
+    hostIP?: string;
+};
+/**
+ * An interface of a container on a network (its result of CNI)
+ */
+export type ContainerNetworkInterface = {
+    network: string;
+    interface: string;
+    mac?: string;
+    ip?: string;
+    prefixLength?: number;
+    gateway?: string;
+    ipv6?: string;
+    ipv6Gateway?: string;
+};
+/**
+ * A network of a container asked: its name, its address
+ */
+export type ContainerNetworkRequest = {
+    name: string;
+    ip?: string;
+    ipv6?: string;
+};
+/**
+ * The default network of nerdctl
+ */
+export declare const DEFAULT_NETWORK: string;
+/**
+ * The script of the networks of the containers, run by runc as their hooks: add (createRuntime, the networks of CNI
+ * added to the namespace of the container, its /etc/hosts given its address), del (poststop, the networks deleted, their
+ * addresses released). The plugins of each network are chained as libcni chains them (the result of each one is the
+ * previous result of the next one); their configurations are the files written for the container
+ */
+export declare const HOOK_SCRIPT: string;
+/**
+ * The first and the last addresses of a subnet (CIDR of IPv4)
+ * @param cidr
+ */
+export declare function parseSubnet(cidr: string): {
+    network: number;
+    broadcast: number;
+    prefix: number;
+    cidr: string;
+};
+/**
+ * A subnet of IPv6 (CIDR): its network, its prefix, its first address
+ * @param cidr
+ */
+export declare function parseIPv6Subnet(cidr: string): {
+    cidr: string;
+    first: string;
+    network: bigint;
+    last: bigint;
+};
+/**
+ * The networks of CNI of the machine (the configuration lists of its directory), the ones of nerdctl created and
+ * removed, the configurations of the networks of the containers written for their hooks
+ */
+export declare class NetworkStore {
+    #private;
+    readonly confDir: string;
+    readonly cniPath: string[];
+    constructor(confDir: string, cniPath: string[]);
+    /**
+     * The directories of the plugins which exist
+     */
+    pluginDirectories(): string[];
+    /**
+     * The path of a plugin, undefined when it is not installed
+     * @param type
+     */
+    plugin(type: string): string | undefined;
+    /**
+     * The version of CNI of the configurations written: the newest one of the plugins (1.0.0, or 0.4.0)
+     */
+    protected cniVersion(): string;
+    /**
+     * A network of a configuration list
+     * @param file
+     * @param content
+     */
+    protected parse(file: string, content: string): CNINetwork | undefined;
+    /**
+     * The networks of CNI of the machine
+     */
+    list(): Promise<CNINetwork[]>;
+    /**
+     * A network, by its name or its identifier (or a prefix of it); the default one of nerdctl created when it is asked
+     * @param nameOrId
+     */
+    get(nameOrId: string): Promise<CNINetwork | undefined>;
+    /**
+     * The plugins added after the main one, as nerdctl adds them (the ones installed)
+     * @param driver
+     * @protected
+     */
+    protected chainedPlugins(driver: string): Record<string, any>[];
+    /**
+     * Write a configuration list
+     * @param name
+     * @param id
+     * @param labels
+     * @param plugins
+     * @protected
+     */
+    protected write(name: string, id: string, labels: Record<string, string>, plugins: Record<string, any>[]): Promise<CNINetwork>;
+    /**
+     * Create the default network of nerdctl (bridge, nerdctl0, 10.4.0.0/24)
+     * @protected
+     */
+    protected createDefault(): Promise<CNINetwork>;
+    /**
+     * A free subnet of 10.4.0.0/16 (the ones of nerdctl)
+     * @param used
+     * @protected
+     */
+    protected freeSubnet(used: string[]): string;
+    /**
+     * Create a network (bridge, macvlan, ipvlan), as nerdctl network create does
+     * @param options
+     */
+    create(options: CNINetworkCreateOptions): Promise<CNINetwork>;
+    /**
+     * Remove a network (one of nerdctl): its configuration, its bridge and the rules of its firewall, the leases of its
+     * addresses, as nerdctl network rm does
+     * @param network
+     */
+    remove(network: CNINetwork): Promise<void>;
+    /**
+     * Write the configurations of the networks of a container for its hooks (the configurations of their plugins, their
+     * runtime configurations: the ports published on the first one)
+     * @param stateDir
+     * @param containerId
+     * @param networks
+     * @param ports
+     */
+    render(stateDir: string, containerId: string, networks: {
+        network: CNINetwork;
+        ip?: string;
+        ipv6?: string;
+    }[], ports: PortMapping[]): Promise<void>;
+    /**
+     * Delete the networks of a container whose hook did not (its task killed with its shim): the hook run as runc runs
+     * it
+     * @param stateDir
+     */
+    teardown(stateDir: string): Promise<void>;
+    /**
+     * The interfaces of a container on its networks (their results of CNI)
+     * @param stateDir
+     */
+    interfaces(stateDir: string): Promise<ContainerNetworkInterface[]>;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * A platform of the images (OCI): its system, its architecture, its variant
+ */
+export type Platform = {
+    os: string;
+    architecture: string;
+    variant?: string;
+};
+/**
+ * The platforms of the ELF binaries an entry of binfmt_misc runs (by the machine of the ELF header of its magic): the
+ * emulators of QEMU, Rosetta, whatever their names
+ * @param entry the content of the entry
+ */
+export declare function binfmtPlatforms(entry: string): Platform[];
+/**
+ * A platform written as OCI writes it (linux/arm64/v8)
+ * @param platform
+ */
+export declare function formatPlatform(platform: Platform): string;
+/**
+ * The variant of an architecture given without it: the one its images are matched to (arm64 is v8, arm v7)
+ * @param platform
+ */
+export declare function normalizePlatform(platform: Platform): Platform;
+/**
+ * Parse a platform: linux/arm64, linux/arm/v7, or an architecture (arm64), on Linux
+ * @param value
+ */
+export declare function parsePlatform(value: string): Platform;
+/**
+ * The platform of the machine running Node.js
+ */
+export declare function hostPlatform(): Platform;
+/**
+ * Whether a platform of an image runs on a platform: the same system and architecture, a variant up to the one of the
+ * platform (an arm/v7 runs the images of arm/v6 and arm/v5)
+ * @param image
+ * @param platform
+ */
+export declare function matchPlatform(image: Platform, platform: Platform): boolean;
+/**
+ * How much a platform of an image suits a platform: the exact one first (lower is better), undefined when it does not
+ * run there
+ * @param image
+ * @param platform
+ */
+export declare function platformRank(image: Platform, platform: Platform): number | undefined;
+/**
+ * The platforms the machine runs the containers of: its own one, and the ones of the emulators registered in
+ * binfmt_misc (enabled)
+ * @param binfmt the directory of binfmt_misc
+ */
+export declare function supportedPlatforms(binfmt?: string): Platform[];

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

@@ -0,0 +1,33 @@
+/**
+ * A reference of an image: its registry, its repository, its tag or its digest
+ */
+export type ImageReference = {
+    /**
+     * The registry, as named by the references (docker.io)
+     */
+    registry: string;
+    /**
+     * The host of the API of the registry (registry-1.docker.io for docker.io)
+     */
+    host: string;
+    repository: string;
+    tag?: string;
+    digest?: string;
+    /**
+     * The name of the image in containerd, the one of ctr and nerdctl (docker.io/library/busybox:latest)
+     */
+    name: string;
+};
+/**
+ * Parse a reference of an image as Docker (and containerd) normalize it: busybox is docker.io/library/busybox:latest,
+ * user/app docker.io/user/app:latest, the first part of a reference is its registry when it has a dot, a port or is
+ * localhost
+ * @param reference
+ */
+export declare function parseReference(reference: string): ImageReference;
+/**
+ * The name of an image in containerd of a reference given by the users (busybox → docker.io/library/busybox:latest),
+ * the reference itself when it is not one
+ * @param reference
+ */
+export declare function imageName(reference: string): string;

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

@@ -0,0 +1,145 @@
+import type { ContentDescriptor } from './ContainerdClient.js';
+import type { ImageReference } from './Reference.js';
+/**
+ * The credentials of a registry: a user and its password (or its token), or an identity token
+ */
+export type RegistryCredentials = {
+    username?: string;
+    password?: string;
+    identityToken?: string;
+};
+/**
+ * The options of the registries: their credentials by their hosts (docker.io, registry.example.com:5000), the ones
+ * served over HTTP
+ */
+export type RegistryOptions = {
+    credentials?: Record<string, RegistryCredentials>;
+    insecure?: string[];
+    signal?: AbortSignal;
+};
+/**
+ * The media types of the manifests and of the indexes (OCI, Docker)
+ */
+export declare const MediaTypes: {
+    readonly OCI_INDEX: "application/vnd.oci.image.index.v1+json";
+    readonly OCI_MANIFEST: "application/vnd.oci.image.manifest.v1+json";
+    readonly OCI_CONFIG: "application/vnd.oci.image.config.v1+json";
+    readonly OCI_LAYER: "application/vnd.oci.image.layer.v1.tar";
+    readonly OCI_LAYER_GZIP: "application/vnd.oci.image.layer.v1.tar+gzip";
+    readonly DOCKER_LIST: "application/vnd.docker.distribution.manifest.list.v2+json";
+    readonly DOCKER_MANIFEST: "application/vnd.docker.distribution.manifest.v2+json";
+    readonly DOCKER_CONFIG: "application/vnd.docker.container.image.v1+json";
+    readonly DOCKER_LAYER: "application/vnd.docker.image.rootfs.diff.tar";
+    readonly DOCKER_LAYER_GZIP: "application/vnd.docker.image.rootfs.diff.tar.gzip";
+};
+/**
+ * Whether a media type is the one of an index (of the manifests of the platforms)
+ * @param mediaType
+ */
+export declare function isIndex(mediaType: string): boolean;
+/**
+ * Whether a media type is the one of a manifest (of an image of a platform)
+ * @param mediaType
+ */
+export declare function isManifest(mediaType: string): boolean;
+/**
+ * The digest of bytes
+ * @param data
+ */
+export declare function digestOf(data: Uint8Array): string;
+/**
+ * The token of a registry for scopes, from its token service (its realm): with the credentials (an identity token by
+ * OAuth2, a user and its password by the basic authentication), or anonymous
+ * @param params
+ * @param credentials
+ * @param signal
+ */
+export declare function fetchRegistryToken(params: {
+    realm: string;
+    service?: string;
+    scopes: string[];
+}, credentials?: RegistryCredentials, signal?: AbortSignal): Promise<{
+    token: string;
+    expiresIn?: number;
+    issuedAt?: number;
+} | undefined>;
+/**
+ * An error of a registry
+ */
+export declare class RegistryError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * The client of a repository of a registry (the distribution API of OCI): its manifests and its blobs, the tokens of
+ * its authentication requested as its challenges ask (Bearer, Basic), with its credentials or anonymously
+ */
+export declare class RegistryClient {
+    #private;
+    protected readonly reference: ImageReference;
+    protected readonly options: RegistryOptions;
+    constructor(reference: ImageReference, options?: RegistryOptions);
+    /**
+     * The credentials of the registry (by its name or by its host)
+     */
+    protected credentials(): RegistryCredentials | undefined;
+    /**
+     * The base URL of the repository
+     */
+    protected base(): string;
+    /**
+     * The authorization of a challenge: a token of its realm (with the credentials when there are), or the credentials
+     * @param challenge
+     * @param scope
+     */
+    protected authorize(challenge: string, scope: string): Promise<string | undefined>;
+    /**
+     * A request to the repository, authenticated as its registry asks
+     * @param path the path under the repository (/manifests/latest), or a URL (the location of an upload)
+     * @param init
+     * @param actions the actions of its scope: pull, or push and pull
+     */
+    request(path: string, init?: RequestInit, actions?: string): Promise<Response>;
+    /**
+     * Fail on an error response
+     * @param response
+     * @param what
+     */
+    protected check(response: Response, what: string): Promise<Response>;
+    /**
+     * Resolve a reference (a tag or a digest): the descriptor of its manifest or of its index, and its bytes
+     * @param reference
+     */
+    resolve(reference: string): Promise<{
+        descriptor: ContentDescriptor;
+        data: Buffer;
+    }>;
+    /**
+     * Fetch a manifest (or an index) by its descriptor, checked by its digest
+     * @param descriptor
+     */
+    fetchManifest(descriptor: ContentDescriptor): Promise<Buffer>;
+    /**
+     * Fetch a blob: its bytes streamed (the redirections of the registry to its storage followed)
+     * @param descriptor
+     */
+    fetchBlob(descriptor: ContentDescriptor): Promise<AsyncIterable<Uint8Array>>;
+    /**
+     * Whether the repository has a blob
+     * @param digest
+     */
+    hasBlob(digest: string): Promise<boolean>;
+    /**
+     * Push a blob, unless the repository has it: uploaded at once
+     * @param descriptor
+     * @param data its bytes, or the function giving their stream
+     */
+    pushBlob(descriptor: ContentDescriptor, data: Uint8Array | (() => AsyncIterable<Uint8Array>)): Promise<void>;
+    /**
+     * Push a manifest (or an index), by a tag or by its digest
+     * @param reference
+     * @param mediaType
+     * @param data
+     */
+    pushManifest(reference: string, mediaType: string, data: Uint8Array): Promise<void>;
+}

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

@@ -0,0 +1,83 @@
+import type { Stats } from 'node:fs';
+import type { SnapshotMount } from './ContainerdClient.js';
+/**
+ * The user of a process: its identifiers and its groups
+ */
+export type ProcessUser = {
+    uid: number;
+    gid: number;
+    additionalGids: number[];
+    home: string;
+};
+/**
+ * The directories of the layers of the mounts of a snapshot, the top one first (overlay: its upper directory and its
+ * lower ones, bind: its source)
+ * @param mounts
+ */
+export declare function layerDirectories(mounts: SnapshotMount[]): string[];
+/**
+ * Read a file of the root file system of a snapshot from the directories of its layers (the snapshotter of the host,
+ * readable by root): the top layer having it first, its deletions (the whiteouts of overlay) honoured, its symbolic
+ * links resolved in the root file system
+ * @param mounts
+ * @param file an absolute path in the root file system
+ * @param depth
+ */
+export declare function readRootfsFile(mounts: SnapshotMount[], file: string, depth?: number): Promise<Buffer | undefined>;
+/**
+ * Resolve the user of a process in a root file system (its /etc/passwd and /etc/group): user, user:group, uid, uid:gid
+ * @param mounts
+ * @param user empty for root
+ */
+export declare function resolveUser(mounts: SnapshotMount[], user: string | undefined): Promise<ProcessUser>;
+/**
+ * A file system read from the host: a directory (the root of a process), or the directories of the layers of a snapshot
+ */
+export interface FileTree {
+    /**
+     * A path whose symbolic links are resolved in the file system (not in the one of the host)
+     * @param file an absolute path in the file system
+     */
+    resolve(file: string): Promise<string>;
+    /**
+     * The stats of a path (its link not followed) and the path of the host to read it, undefined when it does not exist
+     * @param file
+     */
+    lstat(file: string): Promise<{
+        stats: Stats;
+        path: string;
+    } | undefined>;
+    /**
+     * The names of the entries of a directory, sorted
+     * @param directory
+     */
+    readdir(directory: string): Promise<string[]>;
+}
+/**
+ * A file system of a directory of the host (/proc/<pid>/root: the one of a running container, its mounts with it)
+ */
+export declare class DirectoryTree implements FileTree {
+    protected readonly root: string;
+    constructor(root: string);
+    resolve(file: string): Promise<string>;
+    lstat(file: string): Promise<{
+        stats: Stats;
+        path: string;
+    } | undefined>;
+    readdir(directory: string): Promise<string[]>;
+}
+/**
+ * A file system of the layers of a snapshot (the directories of overlay, the top one first): the deletions of the upper
+ * layers (their whiteouts) hide the entries of the lower ones
+ */
+export declare class LayersTree implements FileTree {
+    protected readonly layers: string[];
+    constructor(layers: string[]);
+    resolve(file: string): Promise<string>;
+    protected stat(file: string): Promise<Stats | undefined>;
+    lstat(file: string): Promise<{
+        stats: Stats;
+        path: string;
+    } | undefined>;
+    readdir(directory: string): Promise<string[]>;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * A rule of a profile of seccomp (OCI)
+ */
+export type SeccompSyscall = {
+    names: string[];
+    action: string;
+    errnoRet?: number;
+    args?: {
+        index: number;
+        value: number;
+        valueTwo?: number;
+        op: string;
+    }[];
+};
+/**
+ * A profile of seccomp (the linux.seccomp of the specification of OCI)
+ */
+export type SeccompProfile = {
+    defaultAction: string;
+    defaultErrnoRet?: number;
+    architectures?: string[];
+    flags?: string[];
+    syscalls?: SeccompSyscall[];
+};
+/**
+ * Whether the kernel filters the system calls (the Seccomp field of the status of the processes)
+ * @param status the status of a process
+ */
+export declare function seccompSupported(status?: string): boolean;
+/**
+ * The default profile of seccomp of a container, by its capabilities (its bounding set)
+ * @param capabilities
+ * @param arch the architecture of the machine, as Node.js names it
+ * @param kernel the release of its kernel
+ */
+export declare function defaultSeccompProfile(capabilities: string[], arch?: string, kernel?: string): SeccompProfile;