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

package/dist/esm/client/Platforms.js

@@ -0,0 +1,156 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * The architectures of OCI of the ones of Node.js
+ */
+const ARCHITECTURES = {
+    x64: 'amd64',
+    arm64: 'arm64',
+    arm: 'arm',
+    ia32: '386',
+    ppc64: 'ppc64le',
+    s390x: 's390x',
+    riscv64: 'riscv64',
+    loong64: 'loong64',
+    mips64el: 'mips64le'
+};
+/**
+ * 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 function binfmtPlatforms(entry) {
+    if (!/^enabled$/m.test(entry))
+        return [];
+    const offset = entry.match(/^offset (\d+)$/m)?.[1];
+    const magic = entry.match(/^magic ([0-9a-f]+)$/m)?.[1];
+    if (!magic || (offset && offset !== '0'))
+        return [];
+    const bytes = Buffer.from(magic, 'hex');
+    if (bytes.length < 20 || bytes.readUInt32BE(0) !== 0x7f454c46)
+        return [];
+    const bits64 = bytes[4] === 2;
+    const little = bytes[5] === 1;
+    const machine = little ? bytes.readUInt16LE(18) : bytes.readUInt16BE(18);
+    const linux = (architecture, variant) => ({ os: 'linux', architecture: architecture, variant: variant });
+    switch (machine) {
+        case 0x3e:
+            return [linux('amd64')];
+        case 0x03:
+            return [linux('386')];
+        case 0xb7:
+            return [linux('arm64', 'v8')];
+        case 0x28:
+            return little ? [linux('arm', 'v7'), linux('arm', 'v6'), linux('arm', 'v5')] : [];
+        case 0xf3:
+            return bits64 ? [linux('riscv64')] : [];
+        case 0x15:
+            return bits64 ? [linux(little ? 'ppc64le' : 'ppc64')] : [];
+        case 0x16:
+            return [linux('s390x')];
+        case 0x08:
+            return [linux(bits64 ? (little ? 'mips64le' : 'mips64') : (little ? 'mipsle' : 'mips'))];
+        case 0x102:
+            return [linux('loong64')];
+        default:
+            return [];
+    }
+}
+/**
+ * A platform written as OCI writes it (linux/arm64/v8)
+ * @param platform
+ */
+export function formatPlatform(platform) {
+    return [platform.os, platform.architecture, platform.variant].filter(Boolean).join('/');
+}
+/**
+ * The variant of an architecture given without it: the one its images are matched to (arm64 is v8, arm v7)
+ * @param platform
+ */
+export function normalizePlatform(platform) {
+    const architecture = { x86_64: 'amd64', aarch64: 'arm64', armhf: 'arm', armel: 'arm', i386: '386' }[platform.architecture] ?? platform.architecture;
+    let variant = platform.variant || undefined;
+    if (architecture === 'arm64' && !variant)
+        variant = 'v8';
+    if (architecture === 'arm' && !variant)
+        variant = 'v7';
+    return { os: platform.os || 'linux', architecture: architecture, variant: variant };
+}
+/**
+ * Parse a platform: linux/arm64, linux/arm/v7, or an architecture (arm64), on Linux
+ * @param value
+ */
+export function parsePlatform(value) {
+    const parts = value.trim().toLowerCase().split('/').filter(Boolean);
+    if (!parts.length || parts.length > 3)
+        throw new Error(`The platform "${value}" is not valid (linux/arm64, linux/arm/v7)`);
+    const [os, architecture, variant] = parts.length === 1 ? ['linux', parts[0], undefined] : parts;
+    return normalizePlatform({ os: os, architecture: architecture, variant: variant });
+}
+/**
+ * The platform of the machine running Node.js
+ */
+export function hostPlatform() {
+    const architecture = ARCHITECTURES[process.arch] ?? process.arch;
+    const arm = process.config.variables.arm_version;
+    return normalizePlatform({ os: process.platform === 'win32' ? 'windows' : process.platform, architecture: architecture, variant: architecture === 'arm' && arm ? `v${arm}` : undefined });
+}
+/**
+ * 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 function matchPlatform(image, platform) {
+    const [a, b] = [normalizePlatform(image), normalizePlatform(platform)];
+    if (a.os !== b.os || a.architecture !== b.architecture)
+        return false;
+    if (a.architecture === 'arm')
+        return Number(a.variant?.slice(1) ?? 7) <= Number(b.variant?.slice(1) ?? 7);
+    return (a.variant ?? '') === (b.variant ?? '');
+}
+/**
+ * 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 function platformRank(image, platform) {
+    if (!matchPlatform(image, platform))
+        return undefined;
+    const [a, b] = [normalizePlatform(image), normalizePlatform(platform)];
+    return a.architecture === 'arm' ? Number(b.variant?.slice(1) ?? 7) - Number(a.variant?.slice(1) ?? 7) : 0;
+}
+/**
+ * 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 function supportedPlatforms(binfmt = '/proc/sys/fs/binfmt_misc') {
+    const platforms = [hostPlatform()];
+    //The machines of x64 run the ones of 386
+    if (platforms[0].architecture === 'amd64')
+        platforms.push({ os: 'linux', architecture: '386' });
+    let entries = [];
+    try {
+        entries = readdirSync(binfmt);
+    }
+    catch {
+        //No binfmt_misc
+    }
+    for (const entry of entries) {
+        if (entry === 'status' || entry === 'register')
+            continue;
+        let emulated;
+        try {
+            emulated = binfmtPlatforms(readFileSync(path.join(binfmt, entry), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        for (const platform of emulated)
+            if (!platforms.some((known) => formatPlatform(known) === formatPlatform(platform)))
+                platforms.push(platform);
+    }
+    return platforms;
+}

package/dist/esm/client/Reference.js

@@ -0,0 +1,66 @@
+/**
+ * The registry of the references without registry
+ */
+const DEFAULT_REGISTRY = 'docker.io';
+/**
+ * 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 function parseReference(reference) {
+    const raw = reference.trim();
+    if (!raw || /\s/.test(raw))
+        throw new Error(`The reference of an image "${reference}" is not valid`);
+    let rest = raw;
+    let digest;
+    const at = rest.indexOf('@');
+    if (at >= 0) {
+        digest = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+        if (!/^[a-z0-9]+(?:[.+_-][a-z0-9]+)*:[a-zA-Z0-9=_-]+$/.test(digest))
+            throw new Error(`The digest of the reference "${reference}" is not valid`);
+    }
+    let tag;
+    const colon = rest.lastIndexOf(':');
+    if (colon > rest.lastIndexOf('/')) {
+        tag = rest.slice(colon + 1);
+        rest = rest.slice(0, colon);
+        if (!/^[\w][\w.-]{0,127}$/.test(tag))
+            throw new Error(`The tag of the reference "${reference}" is not valid`);
+    }
+    const parts = rest.split('/');
+    let registry = DEFAULT_REGISTRY;
+    if (parts.length > 1 && (parts[0].includes('.') || parts[0].includes(':') || parts[0] === 'localhost'))
+        registry = parts.shift();
+    if (registry === 'index.docker.io' || registry === 'registry-1.docker.io')
+        registry = DEFAULT_REGISTRY;
+    let repository = parts.join('/');
+    if (registry === DEFAULT_REGISTRY && parts.length === 1)
+        repository = `library/${repository}`;
+    if (!/^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*$/.test(repository))
+        throw new Error(`The repository of the reference "${reference}" is not valid (lower case letters, digits, separators)`);
+    if (!tag && !digest)
+        tag = 'latest';
+    return {
+        registry: registry,
+        host: registry === DEFAULT_REGISTRY ? 'registry-1.docker.io' : registry,
+        repository: repository,
+        tag: tag,
+        digest: digest,
+        name: `${registry}/${repository}${tag ? `:${tag}` : ''}${digest ? `@${digest}` : ''}`
+    };
+}
+/**
+ * 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 function imageName(reference) {
+    try {
+        return parseReference(reference).name;
+    }
+    catch {
+        return reference;
+    }
+}

package/dist/esm/client/Registry.js

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto';
+/**
+ * The media types of the manifests and of the indexes (OCI, Docker)
+ */
+export const MediaTypes = {
+    OCI_INDEX: 'application/vnd.oci.image.index.v1+json',
+    OCI_MANIFEST: 'application/vnd.oci.image.manifest.v1+json',
+    OCI_CONFIG: 'application/vnd.oci.image.config.v1+json',
+    OCI_LAYER: 'application/vnd.oci.image.layer.v1.tar',
+    OCI_LAYER_GZIP: 'application/vnd.oci.image.layer.v1.tar+gzip',
+    DOCKER_LIST: 'application/vnd.docker.distribution.manifest.list.v2+json',
+    DOCKER_MANIFEST: 'application/vnd.docker.distribution.manifest.v2+json',
+    DOCKER_CONFIG: 'application/vnd.docker.container.image.v1+json',
+    DOCKER_LAYER: 'application/vnd.docker.image.rootfs.diff.tar',
+    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 function isIndex(mediaType) {
+    return mediaType === MediaTypes.OCI_INDEX || mediaType === MediaTypes.DOCKER_LIST;
+}
+/**
+ * Whether a media type is the one of a manifest (of an image of a platform)
+ * @param mediaType
+ */
+export function isManifest(mediaType) {
+    return mediaType === MediaTypes.OCI_MANIFEST || mediaType === MediaTypes.DOCKER_MANIFEST;
+}
+/**
+ * The digest of bytes
+ * @param data
+ */
+export function digestOf(data) {
+    return `sha256:${createHash('sha256').update(data).digest('hex')}`;
+}
+/**
+ * The parameters of a challenge of WWW-Authenticate (Bearer realm="…",service="…",scope="…")
+ * @param header
+ */
+function parseChallenge(header) {
+    const space = header.indexOf(' ');
+    const scheme = (space < 0 ? header : header.slice(0, space)).toLowerCase();
+    const params = {};
+    for (const match of header.slice(space + 1).matchAll(/(\w+)="([^"]*)"/g))
+        params[match[1].toLowerCase()] = match[2];
+    return { scheme: scheme, params: params };
+}
+/**
+ * The basic authorization of credentials
+ * @param credentials
+ */
+function basicAuthorization(credentials) {
+    return credentials?.username !== undefined ? `Basic ${Buffer.from(`${credentials.username}:${credentials.password ?? ''}`).toString('base64')}` : undefined;
+}
+/**
+ * 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 async function fetchRegistryToken(params, credentials, signal) {
+    const url = new URL(params.realm);
+    if (params.service)
+        url.searchParams.set('service', params.service);
+    for (const scope of params.scopes)
+        url.searchParams.append('scope', scope);
+    let response;
+    if (credentials?.identityToken) {
+        //The refresh token of the registries (Docker Hub, ECR…): OAuth2
+        response = await fetch(url.origin + url.pathname, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: credentials.identityToken, service: params.service ?? '', scope: params.scopes.join(' '), client_id: 'lakutata' }),
+            signal: signal
+        });
+    }
+    else {
+        const basic = basicAuthorization(credentials);
+        response = await fetch(url, { headers: basic ? { Authorization: basic } : {}, signal: signal });
+    }
+    if (!response.ok)
+        throw new RegistryError(`The registry ${url.host} refuses the authentication (${response.status}): ${(await response.text()).slice(0, 200)}`, response.status);
+    const body = await response.json();
+    const token = body.token ?? body.access_token;
+    if (!token)
+        return undefined;
+    const issued = body.issued_at ? Date.parse(body.issued_at) : NaN;
+    return { token: token, expiresIn: body.expires_in, issuedAt: Number.isNaN(issued) ? undefined : Math.floor(issued / 1000) };
+}
+/**
+ * An error of a registry
+ */
+export class RegistryError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'RegistryError';
+    }
+}
+/**
+ * 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 class RegistryClient {
+    #tokens = new Map();
+    constructor(reference, options = {}) {
+        this.reference = reference;
+        this.options = options;
+    }
+    /**
+     * The credentials of the registry (by its name or by its host)
+     */
+    credentials() {
+        const all = this.options.credentials ?? {};
+        return all[this.reference.registry] ?? all[this.reference.host] ?? (this.reference.registry === 'docker.io' ? all['https://index.docker.io/v1/'] ?? all['index.docker.io'] : undefined);
+    }
+    /**
+     * The base URL of the repository
+     */
+    base() {
+        const insecure = (this.options.insecure ?? []).some((host) => host === this.reference.registry || host === this.reference.host);
+        return `${insecure ? 'http' : 'https'}://${this.reference.host}/v2/${this.reference.repository}`;
+    }
+    /**
+     * The authorization of a challenge: a token of its realm (with the credentials when there are), or the credentials
+     * @param challenge
+     * @param scope
+     */
+    async authorize(challenge, scope) {
+        const { scheme, params } = parseChallenge(challenge);
+        const credentials = this.credentials();
+        if (scheme === 'basic')
+            return basicAuthorization(credentials);
+        if (scheme !== 'bearer' || !params.realm)
+            return undefined;
+        const token = await fetchRegistryToken({ realm: params.realm, service: params.service, scopes: [scope] }, credentials, this.options.signal);
+        return token ? `Bearer ${token.token}` : 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
+     */
+    async request(path, init = {}, actions = 'pull') {
+        const scope = `repository:${this.reference.repository}:${actions}`;
+        const url = /^https?:\/\//.test(path) ? path : `${this.base()}${path}`;
+        const send = (authorization) => fetch(url, {
+            ...init,
+            headers: { ...init.headers, ...authorization ? { Authorization: authorization } : {} },
+            signal: this.options.signal,
+            //The bodies of the streams (the blobs pushed)
+            ...init.body && typeof init.body.getReader === 'function' ? { duplex: 'half' } : {}
+        });
+        let response = await send(this.#tokens.get(scope));
+        if (response.status === 401) {
+            const challenge = response.headers.get('www-authenticate');
+            await response.body?.cancel();
+            const authorization = challenge ? await this.authorize(challenge, scope) : undefined;
+            if (!authorization)
+                throw new RegistryError(`The registry ${this.reference.registry} refuses the request of ${this.reference.repository} without authentication: give its credentials`, 401);
+            this.#tokens.set(scope, authorization);
+            response = await send(authorization);
+        }
+        return response;
+    }
+    /**
+     * Fail on an error response
+     * @param response
+     * @param what
+     */
+    async check(response, what) {
+        if (response.ok)
+            return response;
+        const text = await response.text().catch(() => '');
+        let message = text.slice(0, 300);
+        try {
+            const errors = JSON.parse(text).errors;
+            if (errors?.length)
+                message = errors.map(({ code, message }) => `${code}: ${message}`).join(', ');
+        }
+        catch {
+            //Not JSON
+        }
+        throw new RegistryError(`${what} of ${this.reference.registry}/${this.reference.repository} failed (${response.status}): ${message}`, response.status);
+    }
+    /**
+     * Resolve a reference (a tag or a digest): the descriptor of its manifest or of its index, and its bytes
+     * @param reference
+     */
+    async resolve(reference) {
+        const accept = [MediaTypes.OCI_INDEX, MediaTypes.DOCKER_LIST, MediaTypes.OCI_MANIFEST, MediaTypes.DOCKER_MANIFEST].join(', ');
+        const response = await this.check(await this.request(`/manifests/${reference}`, { headers: { Accept: accept } }), `The manifest ${reference}`);
+        const data = Buffer.from(await response.arrayBuffer());
+        const digest = digestOf(data);
+        if (reference.startsWith('sha256:') && reference !== digest)
+            throw new RegistryError(`The manifest ${reference} has the digest ${digest}`, 0);
+        const mediaType = response.headers.get('content-type')?.split(';')[0].trim() || JSON.parse(data.toString('utf8')).mediaType || MediaTypes.OCI_MANIFEST;
+        return { descriptor: { mediaType: mediaType, digest: digest, size: data.length }, data: data };
+    }
+    /**
+     * Fetch a manifest (or an index) by its descriptor, checked by its digest
+     * @param descriptor
+     */
+    async fetchManifest(descriptor) {
+        const response = await this.check(await this.request(`/manifests/${descriptor.digest}`, { headers: { Accept: descriptor.mediaType } }), `The manifest ${descriptor.digest}`);
+        const data = Buffer.from(await response.arrayBuffer());
+        if (digestOf(data) !== descriptor.digest)
+            throw new RegistryError(`The manifest ${descriptor.digest} has the digest ${digestOf(data)}`, 0);
+        return data;
+    }
+    /**
+     * Fetch a blob: its bytes streamed (the redirections of the registry to its storage followed)
+     * @param descriptor
+     */
+    async fetchBlob(descriptor) {
+        const response = await this.check(await this.request(`/blobs/${descriptor.digest}`), `The blob ${descriptor.digest}`);
+        if (!response.body)
+            throw new RegistryError(`The blob ${descriptor.digest} has no body`, response.status);
+        return response.body;
+    }
+    /**
+     * Whether the repository has a blob
+     * @param digest
+     */
+    async hasBlob(digest) {
+        const response = await this.request(`/blobs/${digest}`, { method: 'HEAD' }, 'push,pull');
+        await response.body?.cancel();
+        return response.ok;
+    }
+    /**
+     * Push a blob, unless the repository has it: uploaded at once
+     * @param descriptor
+     * @param data its bytes, or the function giving their stream
+     */
+    async pushBlob(descriptor, data) {
+        if (await this.hasBlob(descriptor.digest))
+            return;
+        const started = await this.check(await this.request('/blobs/uploads/', { method: 'POST', headers: { 'Content-Length': '0' } }, 'push,pull'), `The upload of ${descriptor.digest}`);
+        await started.body?.cancel();
+        const location = started.headers.get('location');
+        if (!location)
+            throw new RegistryError(`The upload of ${descriptor.digest} has no location`, started.status);
+        const url = new URL(location, this.base());
+        url.searchParams.set('digest', descriptor.digest);
+        const body = data instanceof Uint8Array ? data : ReadableStream.from(data());
+        const put = await this.check(await this.request(url.toString(), { method: 'PUT', headers: { 'Content-Type': 'application/octet-stream', 'Content-Length': String(descriptor.size) }, body: body }, 'push,pull'), `The upload of ${descriptor.digest}`);
+        await put.body?.cancel();
+    }
+    /**
+     * Push a manifest (or an index), by a tag or by its digest
+     * @param reference
+     * @param mediaType
+     * @param data
+     */
+    async pushManifest(reference, mediaType, data) {
+        const response = await this.check(await this.request(`/manifests/${reference}`, { method: 'PUT', headers: { 'Content-Type': mediaType }, body: data }, 'push,pull'), `The push of the manifest ${reference}`);
+        await response.body?.cancel();
+    }
+}