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

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

@@ -0,0 +1,244 @@
+import { GRPCConnection, GRPCError, type CallOptions, type Message, type Schema } from '@lakutata/grpc';
+/**
+ * A descriptor of content (OCI)
+ */
+export type ContentDescriptor = {
+    mediaType: string;
+    digest: string;
+    size: number;
+    annotations?: Record<string, string>;
+    platform?: {
+        os: string;
+        architecture: string;
+        variant?: string;
+    };
+};
+/**
+ * A mount of a snapshot
+ */
+export type SnapshotMount = {
+    type: string;
+    source: string;
+    target?: string;
+    options: string[];
+};
+/**
+ * An event of containerd, as {@link Containerd.events} streams it: its topic (`/tasks/exit`), its type
+ * (`containerd.events.TaskExit`) and its decoded fields.
+ */
+export type ContainerdEvent = {
+    /**
+     * When containerd published the event.
+     */
+    timestamp: Date;
+    /**
+     * The namespace the event happened in (the component's).
+     */
+    namespace: string;
+    /**
+     * The event's topic: `/tasks/create`, `/tasks/start`, `/tasks/exit`, `/tasks/delete`, `/tasks/oom`,
+     * `/tasks/paused`, `/tasks/resumed`, `/tasks/exec-added`, `/tasks/exec-started`, `/containers/create`,
+     * `/containers/update`, `/containers/delete`, `/images/create`, `/images/update`, `/images/delete`,
+     * `/snapshot/prepare`, `/snapshot/commit`, `/snapshot/remove`…
+     */
+    topic: string;
+    /**
+     * The type of the event's payload (`containerd.events.TaskExit`).
+     */
+    type: string;
+    /**
+     * The event's fields, decoded for the task, container, image and snapshot events (`{containerId, pid, exitStatus,
+     * exitedAt}` for `/tasks/exit`, `{name}` for `/images/delete`); an empty object for the other events.
+     */
+    event: Message;
+};
+/**
+ * The type URL of the specifications of the containers and of their processes (OCI runtime spec, JSON)
+ */
+export declare const SPEC_TYPE_URL: string;
+export declare const PROCESS_TYPE_URL: string;
+export declare const RESOURCES_TYPE_URL: string;
+/**
+ * A date of a Timestamp
+ * @param timestamp
+ */
+export declare function timestampDate(timestamp: Message | undefined): Date | undefined;
+/**
+ * Whether an error is the one of a call of a code
+ * @param error
+ * @param code
+ */
+export declare function isGRPCError(error: unknown, code: number): error is GRPCError;
+/**
+ * The client of the API of containerd (its services of the version 1), in a namespace: its calls are the ones of
+ * ctr and nerdctl
+ */
+export declare class ContainerdClient {
+    readonly namespace: string;
+    readonly grpc: GRPCConnection;
+    constructor(socketPath: string, namespace: string);
+    /**
+     * The options of a call: its namespace, its lease (the content and the snapshots it creates are kept by it until
+     * they are referenced)
+     * @param lease
+     * @param signal
+     */
+    protected options(lease?: string, signal?: AbortSignal): CallOptions;
+    /**
+     * Call a method of a service
+     * @param service its name and its version (images.v1.Images)
+     * @param method
+     * @param requestSchema
+     * @param request
+     * @param responseSchema
+     * @param lease
+     * @param signal
+     */
+    protected call(service: string, method: string, requestSchema: Schema, request: Message, responseSchema?: Schema, lease?: string, signal?: AbortSignal): Promise<Message>;
+    /**
+     * Call a method, undefined when what it reads does not exist
+     * @param promise
+     */
+    protected orUndefined<T>(promise: Promise<T>): Promise<T | undefined>;
+    version(): Promise<{
+        version: string;
+        revision: string;
+    }>;
+    /**
+     * Create the namespace of the client, when it does not exist
+     */
+    ensureNamespace(): Promise<void>;
+    /**
+     * Create a lease, which keeps what is created under it until it is deleted (or expired)
+     * @param expireSeconds
+     */
+    createLease(expireSeconds?: number): Promise<string>;
+    deleteLease(id: string): Promise<void>;
+    getImage(name: string): Promise<Message | undefined>;
+    listImages(filters?: string[]): Promise<Message[]>;
+    /**
+     * Create an image, or update it when it exists (its target and its labels)
+     * @param image
+     * @param lease
+     */
+    putImage(image: Message, lease?: string): Promise<Message>;
+    deleteImage(name: string, sync?: boolean): Promise<void>;
+    contentInfo(digest: string): Promise<Message | undefined>;
+    /**
+     * Set labels of a content
+     * @param digest
+     * @param labels
+     */
+    labelContent(digest: string, labels: Record<string, string>): Promise<void>;
+    /**
+     * Read a content, by its chunks
+     * @param digest
+     * @param signal
+     */
+    readContent(digest: string, signal?: AbortSignal): AsyncGenerator<Buffer>;
+    /**
+     * Read a content whole
+     * @param digest
+     */
+    readAll(digest: string): Promise<Buffer>;
+    /**
+     * Write a content, checked by its digest (a content which exists is kept), its labels set
+     * @param descriptor its digest and its size
+     * @param data its bytes, or their chunks
+     * @param lease
+     * @param labels
+     * @param signal
+     */
+    writeContent(descriptor: {
+        digest: string;
+        size: number;
+    }, data: Uint8Array | AsyncIterable<Uint8Array>, lease: string, labels?: Record<string, string>, signal?: AbortSignal): Promise<void>;
+    deleteContent(digest: string): Promise<void>;
+    prepareSnapshot(snapshotter: string, key: string, parent: string, labels?: Record<string, string>, lease?: string): Promise<SnapshotMount[]>;
+    snapshotMounts(snapshotter: string, key: string): Promise<SnapshotMount[]>;
+    commitSnapshot(snapshotter: string, name: string, key: string, labels?: Record<string, string>, lease?: string): Promise<void>;
+    viewSnapshot(snapshotter: string, key: string, parent: string, lease?: string): Promise<SnapshotMount[]>;
+    /**
+     * The layer of the changes of a snapshot from another one (tar+gzip), written into the content store
+     * @param left the older one
+     * @param right the newer one
+     * @param lease
+     */
+    diff(left: SnapshotMount[], right: SnapshotMount[], lease?: string): Promise<ContentDescriptor>;
+    /**
+     * The metrics of the cgroup of a task: their type (io.containerd.cgroups.v1.Metrics, …v2.Metrics) and their bytes
+     * @param containerId
+     */
+    metrics(containerId: string): Promise<Message | undefined>;
+    removeSnapshot(snapshotter: string, key: string): Promise<void>;
+    statSnapshot(snapshotter: string, key: string): Promise<Message | undefined>;
+    snapshotUsage(snapshotter: string, key: string): Promise<{
+        size: number;
+        inodes: number;
+    }>;
+    /**
+     * Apply a layer (its content) to the mounts of a snapshot
+     * @param layer
+     * @param mounts
+     * @param lease
+     */
+    applyLayer(layer: ContentDescriptor, mounts: SnapshotMount[], lease?: string): Promise<ContentDescriptor>;
+    getContainer(id: string): Promise<Message | undefined>;
+    listContainers(filters?: string[]): Promise<Message[]>;
+    createContainer(container: Message, lease?: string): Promise<Message>;
+    updateContainer(container: Message, paths: string[]): Promise<Message>;
+    deleteContainer(id: string): Promise<void>;
+    createTask(request: Message): Promise<number>;
+    startTask(containerId: string, execId?: string): Promise<number>;
+    deleteTask(containerId: string): Promise<Message | undefined>;
+    deleteProcess(containerId: string, execId: string): Promise<Message | undefined>;
+    getTask(containerId: string, execId?: string): Promise<Message | undefined>;
+    listTasks(): Promise<Message[]>;
+    kill(containerId: string, signal: number, options?: {
+        execId?: string;
+        all?: boolean;
+    }): Promise<void>;
+    exec(request: Message): Promise<void>;
+    resizePty(containerId: string, execId: string, width: number, height: number): Promise<void>;
+    closeIO(containerId: string, execId: string): Promise<void>;
+    pause(containerId: string): Promise<void>;
+    resume(containerId: string): Promise<void>;
+    listPids(containerId: string): Promise<number[]>;
+    /**
+     * Wait for a process to exit (the task, an exec)
+     * @param containerId
+     * @param execId
+     * @param signal
+     */
+    wait(containerId: string, execId?: string, signal?: AbortSignal): Promise<{
+        exitStatus: number;
+        exitedAt?: Date;
+    }>;
+    /**
+     * Update the resources of a task (OCI LinuxResources)
+     * @param containerId
+     * @param resources
+     */
+    updateTask(containerId: string, resources: object): Promise<void>;
+    /**
+     * The events of containerd, their fields decoded (the ones of the tasks, the containers and the images)
+     * @param filters the filters of containerd (topic~="/tasks/", namespace==default)
+     * @param signal its end
+     */
+    subscribe(filters?: string[], signal?: AbortSignal): AsyncGenerator<ContainerdEvent>;
+    /**
+     * An Any of JSON (the specifications of OCI)
+     * @param typeUrl
+     * @param value
+     */
+    static Json(typeUrl: string, value: object): Message;
+    /**
+     * The value of an Any of JSON
+     * @param any
+     */
+    static FromJson<T = any>(any: Message | undefined): T | undefined;
+    /**
+     * Close the connection
+     */
+    close(): void;
+}