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

package/dist/cjs/client/Spec.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_CAPABILITIES = exports.DEFAULT_CAPABILITIES = void 0;
+exports.parseDeviceCgroupRule = parseDeviceCgroupRule;
+exports.containerCapabilities = containerCapabilities;
+exports.generateSpec = generateSpec;
+exports.execProcessSpec = execProcessSpec;
+/**
+ * The capabilities of the containers by default (the ones of containerd, Docker and nerdctl)
+ */
+exports.DEFAULT_CAPABILITIES = [
+    'CAP_CHOWN',
+    'CAP_DAC_OVERRIDE',
+    'CAP_FSETID',
+    'CAP_FOWNER',
+    'CAP_MKNOD',
+    'CAP_NET_RAW',
+    'CAP_SETGID',
+    'CAP_SETUID',
+    'CAP_SETFCAP',
+    'CAP_SETPCAP',
+    'CAP_NET_BIND_SERVICE',
+    'CAP_SYS_CHROOT',
+    'CAP_KILL',
+    'CAP_AUDIT_WRITE'
+];
+/**
+ * All the capabilities of Linux (the privileged containers)
+ */
+exports.ALL_CAPABILITIES = [
+    'CAP_CHOWN', 'CAP_DAC_OVERRIDE', 'CAP_DAC_READ_SEARCH', 'CAP_FOWNER', 'CAP_FSETID', 'CAP_KILL', 'CAP_SETGID',
+    'CAP_SETUID', 'CAP_SETPCAP', 'CAP_LINUX_IMMUTABLE', 'CAP_NET_BIND_SERVICE', 'CAP_NET_BROADCAST', 'CAP_NET_ADMIN',
+    'CAP_NET_RAW', 'CAP_IPC_LOCK', 'CAP_IPC_OWNER', 'CAP_SYS_MODULE', 'CAP_SYS_RAWIO', 'CAP_SYS_CHROOT', 'CAP_SYS_PTRACE',
+    'CAP_SYS_PACCT', 'CAP_SYS_ADMIN', 'CAP_SYS_BOOT', 'CAP_SYS_NICE', 'CAP_SYS_RESOURCE', 'CAP_SYS_TIME',
+    'CAP_SYS_TTY_CONFIG', 'CAP_MKNOD', 'CAP_LEASE', 'CAP_AUDIT_WRITE', 'CAP_AUDIT_CONTROL', 'CAP_SETFCAP',
+    'CAP_MAC_OVERRIDE', 'CAP_MAC_ADMIN', 'CAP_SYSLOG', 'CAP_WAKE_ALARM', 'CAP_BLOCK_SUSPEND', 'CAP_AUDIT_READ',
+    'CAP_PERFMON', 'CAP_BPF', 'CAP_CHECKPOINT_RESTORE'
+];
+/**
+ * The paths masked in the containers (not privileged)
+ */
+const MASKED_PATHS = [
+    '/proc/acpi', '/proc/asound', '/proc/kcore', '/proc/keys', '/proc/latency_stats', '/proc/timer_list',
+    '/proc/timer_stats', '/proc/sched_debug', '/proc/scsi', '/sys/firmware', '/sys/devices/virtual/powercap'
+];
+/**
+ * The paths read only in the containers (not privileged)
+ */
+const READONLY_PATHS = ['/proc/bus', '/proc/fs', '/proc/irq', '/proc/sys', '/proc/sysrq-trigger'];
+/**
+ * The devices of the containers allowed by default (the ones of runc: null, zero, full, tty, random, urandom, the
+ * pseudo terminals)
+ */
+const DEFAULT_DEVICE_RULES = [
+    { allow: false, access: 'rwm' },
+    { allow: true, type: 'c', major: 1, minor: 3, access: 'rwm' },
+    { allow: true, type: 'c', major: 1, minor: 8, access: 'rwm' },
+    { allow: true, type: 'c', major: 1, minor: 7, access: 'rwm' },
+    { allow: true, type: 'c', major: 5, minor: 0, access: 'rwm' },
+    { allow: true, type: 'c', major: 1, minor: 5, access: 'rwm' },
+    { allow: true, type: 'c', major: 1, minor: 9, access: 'rwm' },
+    { allow: true, type: 'c', major: 5, minor: 2, access: 'rwm' },
+    { allow: true, type: 'c', major: 136, access: 'rwm' }
+];
+/**
+ * Parse a rule of the devices of a cgroup as Docker writes it: "c 188:* rwm", "b 8:16 r", "a *:* rwm"
+ * @param rule
+ */
+function parseDeviceCgroupRule(rule) {
+    const match = rule.trim().match(/^([acb]) (\*|\d+):(\*|\d+) ([rwm]{1,3})$/);
+    if (!match || new Set(match[4]).size !== match[4].length)
+        throw new Error(`The rule of the devices "${rule}" is not valid ("c 188:* rwm": a type a, c or b, the major and the minor numbers or *, the access of r, w and m)`);
+    return {
+        type: match[1],
+        ...match[2] === '*' ? {} : { major: Number(match[2]) },
+        ...match[3] === '*' ? {} : { minor: Number(match[3]) },
+        access: match[4]
+    };
+}
+/**
+ * The capability of a name (NET_ADMIN, CAP_NET_ADMIN)
+ * @param name
+ */
+function normalizeCapability(name) {
+    const upper = name.trim().toUpperCase();
+    return upper.startsWith('CAP_') ? upper : `CAP_${upper}`;
+}
+/**
+ * The capabilities of a container: the ones by default (all for the privileged containers), the ones added, without
+ * the ones dropped (ALL drops all)
+ * @param options
+ */
+function containerCapabilities(options) {
+    let capabilities = new Set(options.privileged ? exports.ALL_CAPABILITIES : exports.DEFAULT_CAPABILITIES);
+    const drop = (options.capDrop ?? []).map(normalizeCapability);
+    if (drop.includes('CAP_ALL'))
+        capabilities = new Set();
+    else
+        drop.forEach((capability) => capabilities.delete(capability));
+    const add = (options.capAdd ?? []).map(normalizeCapability);
+    if (add.includes('CAP_ALL'))
+        exports.ALL_CAPABILITIES.forEach((capability) => capabilities.add(capability));
+    else
+        add.forEach((capability) => capabilities.add(capability));
+    return [...capabilities];
+}
+/**
+ * The specification of the runtime (OCI) of a container on Linux, as containerd and nerdctl generate it
+ * @param options
+ */
+function generateSpec(options) {
+    const capabilities = containerCapabilities(options);
+    const namespaces = [{ type: 'mount' }, { type: 'uts' }];
+    if (!options.pidHost)
+        namespaces.push({ type: 'pid' });
+    if (!options.ipcHost)
+        namespaces.push({ type: 'ipc' });
+    if (options.cgroupNamespace)
+        namespaces.push({ type: 'cgroup' });
+    if (options.network.mode === 'none' || options.network.mode === 'cni')
+        namespaces.push({ type: 'network' });
+    if (options.network.mode === 'path')
+        namespaces.push({ type: 'network', path: options.network.path });
+    const mounts = [
+        { destination: '/proc', type: 'proc', source: 'proc', options: ['nosuid', 'noexec', 'nodev'] },
+        { destination: '/dev', type: 'tmpfs', source: 'tmpfs', options: ['nosuid', 'strictatime', 'mode=755', 'size=65536k'] },
+        { destination: '/dev/pts', type: 'devpts', source: 'devpts', options: ['nosuid', 'noexec', 'newinstance', 'ptmxmode=0666', 'mode=0620', 'gid=5'] },
+        { destination: '/dev/shm', type: 'tmpfs', source: 'shm', options: ['nosuid', 'noexec', 'nodev', 'mode=1777', `size=${options.shmSize ?? 64 * 1024 * 1024}`] },
+        { destination: '/dev/mqueue', type: 'mqueue', source: 'mqueue', options: ['nosuid', 'noexec', 'nodev'] },
+        { destination: '/sys', type: 'sysfs', source: 'sysfs', options: ['nosuid', 'noexec', 'nodev', options.privileged ? 'rw' : 'ro'] },
+        { destination: '/sys/fs/cgroup', type: 'cgroup', source: 'cgroup', options: ['nosuid', 'noexec', 'nodev', 'relatime', options.privileged ? 'rw' : 'ro'] }
+    ];
+    for (const mount of options.mounts ?? []) {
+        //A mount given replaces the one of its destination
+        const index = mounts.findIndex((existing) => existing.destination === mount.destination);
+        if (index >= 0)
+            mounts.splice(index, 1);
+        mounts.push({ type: mount.type ?? 'bind', source: mount.source, destination: mount.destination, options: mount.options ?? ['rbind', 'rprivate'] });
+    }
+    const devices = options.devices ?? [];
+    const resources = {
+        devices: options.privileged ? [{ allow: true, access: 'rwm' }] : [
+            ...DEFAULT_DEVICE_RULES,
+            ...devices.map((device) => ({ allow: true, type: device.type, major: device.major, minor: device.minor, access: device.permissions })),
+            ...(options.deviceCgroupRules ?? []).map((rule) => ({ allow: true, ...rule }))
+        ]
+    };
+    if (options.memory || options.oomKillDisable) {
+        resources.memory = {};
+        if (options.memory)
+            resources.memory.limit = options.memory;
+        if (options.memorySwap)
+            resources.memory.swap = options.memorySwap;
+        if (options.oomKillDisable)
+            resources.memory.disableOOMKiller = true;
+    }
+    if (options.cpuQuota || options.cpuShares || options.cpuset) {
+        resources.cpu = {};
+        if (options.cpuQuota) {
+            resources.cpu.quota = options.cpuQuota;
+            resources.cpu.period = options.cpuPeriod ?? 100000;
+        }
+        if (options.cpuShares)
+            resources.cpu.shares = options.cpuShares;
+        if (options.cpuset)
+            resources.cpu.cpus = options.cpuset;
+    }
+    if (options.pidsLimit)
+        resources.pids = { limit: options.pidsLimit };
+    return {
+        ociVersion: '1.0.2-dev',
+        process: {
+            terminal: !!options.terminal,
+            user: { uid: options.uid, gid: options.gid, ...options.additionalGids.length ? { additionalGids: options.additionalGids } : {} },
+            args: options.args,
+            env: options.env,
+            cwd: options.cwd || '/',
+            capabilities: { bounding: capabilities, effective: capabilities, permitted: capabilities },
+            rlimits: options.rlimits ?? [{ type: 'RLIMIT_NOFILE', hard: 1024, soft: 1024 }],
+            noNewPrivileges: !options.privileged
+        },
+        root: { path: 'rootfs', readonly: !!options.readonlyRootfs },
+        hostname: options.hostname,
+        mounts: mounts,
+        ...options.hooks ? { hooks: options.hooks } : {},
+        annotations: options.annotations ?? {},
+        linux: {
+            resources: resources,
+            cgroupsPath: options.cgroupsPath,
+            namespaces: namespaces,
+            devices: devices.map((device) => ({
+                path: device.containerPath,
+                type: device.type,
+                major: device.major,
+                minor: device.minor,
+                fileMode: device.fileMode ?? 0o666,
+                uid: device.uid ?? 0,
+                gid: device.gid ?? 0
+            })),
+            ...options.sysctls && Object.keys(options.sysctls).length ? { sysctl: options.sysctls } : {},
+            ...options.seccomp ? { seccomp: options.seccomp } : {},
+            ...options.privileged ? {} : { maskedPaths: [...MASKED_PATHS], readonlyPaths: [...READONLY_PATHS] }
+        }
+    };
+}
+/**
+ * The specification of a process executed in a container (exec): the one of the container, its arguments, its
+ * environment, its directory, its user and its terminal changed
+ * @param spec the specification of the container
+ * @param options
+ */
+function execProcessSpec(spec, options) {
+    const process = structuredClone(spec.process ?? {});
+    process.args = options.args;
+    process.terminal = !!options.terminal;
+    if (options.env?.length) {
+        const env = new Map((process.env ?? []).map((entry) => [entry.split('=')[0], entry]));
+        for (const entry of options.env)
+            env.set(entry.split('=')[0], entry);
+        process.env = [...env.values()];
+    }
+    if (options.cwd)
+        process.cwd = options.cwd;
+    if (options.uid !== undefined)
+        process.user = { uid: options.uid, gid: options.gid ?? 0, ...options.additionalGids?.length ? { additionalGids: options.additionalGids } : {} };
+    return process;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * A named volume: a directory of the data root mounted in the containers
+ */
+export type Volume = {
+    name: string;
+    /**
+     * Its directory of the host (mounted in the containers)
+     */
+    mountpoint: string;
+    labels: Record<string, string>;
+    createdAt: Date;
+};
+/**
+ * The named volumes of a namespace: <data root>/volumes/<namespace>/<name>/_data, their information in volume.json
+ */
+export declare class VolumeStore {
+    readonly directory: string;
+    constructor(directory: string);
+    /**
+     * Whether a name is the one of a volume
+     * @param name
+     */
+    static ValidName(name: string): boolean;
+    protected path(name: string): string;
+    /**
+     * A volume, undefined when it does not exist
+     * @param name
+     */
+    get(name: string): Promise<Volume | undefined>;
+    list(): Promise<Volume[]>;
+    /**
+     * Create a volume (the existing one is given when it exists, as Docker does)
+     * @param name
+     * @param labels
+     */
+    create(name: string, labels?: Record<string, string>): Promise<Volume>;
+    /**
+     * Remove a volume and its data
+     * @param name
+     */
+    remove(name: string): Promise<void>;
+}

package/dist/cjs/client/Volumes.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VolumeStore = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * The named volumes of a namespace: <data root>/volumes/<namespace>/<name>/_data, their information in volume.json
+ */
+class VolumeStore {
+    constructor(directory) {
+        this.directory = directory;
+    }
+    /**
+     * Whether a name is the one of a volume
+     * @param name
+     */
+    static ValidName(name) {
+        return /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name);
+    }
+    path(name) {
+        if (!VolumeStore.ValidName(name))
+            throw new Error(`The name of a volume "${name}" is not valid ([a-zA-Z0-9][a-zA-Z0-9_.-]*)`);
+        return node_path_1.default.join(this.directory, name);
+    }
+    /**
+     * A volume, undefined when it does not exist
+     * @param name
+     */
+    async get(name) {
+        const directory = this.path(name);
+        try {
+            const info = JSON.parse(await (0, promises_1.readFile)(node_path_1.default.join(directory, 'volume.json'), 'utf8'));
+            return { name: name, mountpoint: node_path_1.default.join(directory, '_data'), labels: info.labels ?? {}, createdAt: new Date(info.createdAt ?? (await (0, promises_1.stat)(directory)).birthtime) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async list() {
+        let names;
+        try {
+            names = (await (0, promises_1.readdir)(this.directory)).filter(VolumeStore.ValidName).sort();
+        }
+        catch {
+            return [];
+        }
+        const volumes = [];
+        for (const name of names) {
+            const volume = await this.get(name);
+            if (volume)
+                volumes.push(volume);
+        }
+        return volumes;
+    }
+    /**
+     * Create a volume (the existing one is given when it exists, as Docker does)
+     * @param name
+     * @param labels
+     */
+    async create(name, labels = {}) {
+        const existing = await this.get(name);
+        if (existing)
+            return existing;
+        const directory = this.path(name);
+        await (0, promises_1.mkdir)(node_path_1.default.join(directory, '_data'), { recursive: true });
+        await (0, promises_1.writeFile)(node_path_1.default.join(directory, 'volume.json'), JSON.stringify({ name: name, labels: labels, createdAt: new Date().toISOString() }));
+        return (await this.get(name));
+    }
+    /**
+     * Remove a volume and its data
+     * @param name
+     */
+    async remove(name) {
+        await (0, promises_1.rm)(this.path(name), { recursive: true, force: true });
+    }
+}
+exports.VolumeStore = VolumeStore;