@saws/docker-service 2.0.0-beta.3 → 2.0.0-beta.4

package/dist/DockerService.js

@@ -0,0 +1,577 @@
+import { createHash } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ServiceDefinition, } from "@saws/core";
+import { runLocal } from "@saws/core/utils/run-local";
+import { shellQuote } from "@saws/core/utils/shell-quote";
+export class DockerService extends ServiceDefinition {
+    host;
+    appDirectory;
+    network;
+    registry;
+    auth;
+    image;
+    dockerfile;
+    buildContext;
+    volumes;
+    ports;
+    command;
+    labels;
+    restart;
+    healthCheck;
+    serviceType = "docker";
+    devProcess;
+    devEnvironmentFile;
+    localRunAbortController = new AbortController();
+    activeEphemeralContainers = new Set();
+    localRegistryAuthenticated = false;
+    remoteRegistryAuthenticated = false;
+    constructor(config) {
+        super(config);
+        const hasImage = "image" in config && config.image != null;
+        const hasDockerfile = "dockerfile" in config && config.dockerfile != null;
+        if (hasImage && hasDockerfile) {
+            throw new Error(`Docker service "${config.name}" cannot configure both image and dockerfile`);
+        }
+        const buildsDockerfile = !hasImage;
+        if (buildsDockerfile &&
+            config.registry != null &&
+            config.registry.replace(/\/+$/, "").length === 0) {
+            throw new Error(`Docker service "${config.name}" registry cannot be empty`);
+        }
+        if (buildsDockerfile && config.auth != null && config.auth.username.trim().length === 0) {
+            throw new Error(`Docker service "${config.name}" registry auth username cannot be empty`);
+        }
+        this.host = config.host;
+        this.appDirectory = config.appDirectory ?? "/opt/saws";
+        this.network = config.network ?? "saws";
+        this.registry = config.registry?.replace(/\/+$/, "");
+        this.auth = config.auth;
+        if (hasImage) {
+            this.image = config.image;
+        }
+        else {
+            this.dockerfile = hasDockerfile ? config.dockerfile : path.join(config.name, "Dockerfile");
+            this.buildContext = hasDockerfile ? config.buildContext : config.name;
+        }
+        this.volumes = config.volumes ?? [];
+        this.ports = config.ports ?? [];
+        this.command = config.command ?? [];
+        this.labels = config.labels ?? {};
+        this.restart = config.restart;
+        this.healthCheck = config.healthCheck;
+    }
+    async dev() {
+        await super.dev();
+        const stage = "local";
+        await this.buildDockerfileImage(stage, false);
+        const config = await this.getDockerRunConfig(stage, false);
+        try {
+            this.devEnvironmentFile = await this.writeLocalEnvironmentFile(stage, config);
+            this.devProcess = await this.startLocalContainer(config);
+            this.observeDevProcess(this.devProcess);
+        }
+        catch (error) {
+            await this.removeDevEnvironmentFile();
+            throw error;
+        }
+        await this.onContainerStarted(stage);
+    }
+    async deploy(stage) {
+        await super.deploy(stage);
+        await this.buildDockerfileImage(stage, true);
+        await this.pushDockerfileImage(stage);
+        const config = await this.getDockerRunConfig(stage, true);
+        config.configHash = this.getContainerConfigHash(config);
+        if (this.host == null) {
+            await this.runLocalDetachedContainer(stage, config);
+            await this.onContainerStarted(stage);
+            return;
+        }
+        await this.assertRemoteHostReady();
+        let environmentFile;
+        try {
+            environmentFile = await this.writeRemoteEnvironmentFile(stage, config);
+            await this.runRemoteContainer(stage, config);
+        }
+        finally {
+            if (environmentFile != null) {
+                await this.removeRemoteRuntimeFile(environmentFile);
+            }
+        }
+        await this.onContainerStarted(stage);
+    }
+    exit() {
+        super.exit();
+        this.localRunAbortController.abort();
+        this.devProcess?.kill();
+        this.devProcess = undefined;
+        this.removeActiveEphemeralContainers();
+        void this.removeDevEnvironmentFile();
+    }
+    getContainerName(stage) {
+        return `${stage}-${this.name}`.replaceAll("_", "-").toLowerCase();
+    }
+    async getContainerEnvironment(stage) {
+        return {
+            ...(await this.getDependenciesEnvironmentVariables(stage)),
+            ...(await this.getStageEnvironmentVariables(stage)),
+        };
+    }
+    async getDockerRunConfig(stage, deploy) {
+        return {
+            name: this.getContainerName(stage),
+            image: this.getImage(stage, deploy),
+            pull: this.dockerfile == null || deploy,
+            network: this.getNetwork(stage),
+            env: await this.getContainerEnvironment(stage),
+            volumes: this.volumes,
+            ports: this.ports,
+            command: this.command,
+            restart: this.restart,
+            healthCheck: this.healthCheck,
+            labels: {
+                ...this.labels,
+                "saws.service": this.name,
+                "saws.serviceType": this.serviceType,
+                "saws.stage": stage,
+            },
+        };
+    }
+    async onContainerStarted(_stage) { }
+    getImage(stage, deploy) {
+        if (this.image != null)
+            return this.image;
+        return this.getBuiltImageName(stage, deploy);
+    }
+    async buildDockerfileImage(stage, deploy) {
+        if (this.dockerfile == null)
+            return;
+        await this.buildImage(this.getImage(stage, deploy), deploy && this.host != null ? this.host.platform : undefined);
+    }
+    async pushDockerfileImage(stage) {
+        if (this.dockerfile == null || this.host == null)
+            return;
+        await this.pushImage(stage, this.getImage(stage, true));
+    }
+    getNetwork(stage) {
+        return `${this.network}-${stage}`;
+    }
+    getAppDirectory(stage) {
+        return path.posix.join(this.appDirectory, stage);
+    }
+    getBuiltImageName(stage, deploy) {
+        const repository = `${stage}-${this.name}`
+            .toLowerCase()
+            .replace(/[^a-z0-9._-]+/g, "-")
+            .replace(/^[._-]+|[._-]+$/g, "");
+        if (repository.length === 0) {
+            throw new Error(`Cannot derive a Docker image name for service "${this.name}"`);
+        }
+        if (deploy && this.host != null) {
+            if (this.registry == null) {
+                throw new Error(`Docker service "${this.name}" uses a Dockerfile and remote deploy, but no registry is configured`);
+            }
+            return `${this.registry}/${repository}:latest`;
+        }
+        return `saws-${repository}:latest`;
+    }
+    async buildImage(image, platform) {
+        const dockerfile = path.resolve(this.dockerfile);
+        const buildContext = path.resolve(this.buildContext ?? path.dirname(this.dockerfile));
+        await runLocal([
+            "docker build",
+            ...(platform == null ? [] : [`--platform ${shellQuote(platform)}`]),
+            `-f ${shellQuote(dockerfile)}`,
+            `-t ${shellQuote(image)}`,
+            shellQuote(buildContext),
+        ].join(" "), this.getLocalRunOptions());
+    }
+    async pushImage(stage, image) {
+        await this.authenticateLocalRegistry(stage);
+        await runLocal(`docker push ${shellQuote(image)}`, this.getLocalRunOptions());
+    }
+    async authenticateLocalRegistry(stage) {
+        if (this.registry == null || this.auth == null || this.localRegistryAuthenticated)
+            return;
+        await runLocal([
+            "docker login",
+            shellQuote(this.getRegistryServer()),
+            `--username ${shellQuote(this.auth.username)}`,
+            "--password-stdin",
+        ].join(" "), this.getLocalRunOptions({ input: `${await this.resolveRegistryPassword(stage)}\n` }));
+        this.localRegistryAuthenticated = true;
+    }
+    async authenticateRemoteRegistry(stage) {
+        if (this.registry == null || this.auth == null || this.remoteRegistryAuthenticated)
+            return;
+        await this.host.exec([
+            "docker login",
+            shellQuote(this.getRegistryServer()),
+            `--username ${shellQuote(this.auth.username)}`,
+            "--password-stdin",
+        ].join(" "), { input: `${await this.resolveRegistryPassword(stage)}\n` });
+        this.remoteRegistryAuthenticated = true;
+    }
+    async resolveRegistryPassword(stage) {
+        return typeof this.auth.password === "string"
+            ? this.auth.password
+            : this.auth.password.resolve({ stage });
+    }
+    getRegistryServer() {
+        return this.registry.split("/", 1)[0];
+    }
+    async prepareLocalNetwork(network, options = {}) {
+        await runLocal(`docker network inspect ${shellQuote(network)} >/dev/null 2>&1 || docker network create ${shellQuote(network)}`, this.getLocalRunOptions(options));
+    }
+    async prepareRemote(stage, network, dryRun) {
+        if (!dryRun) {
+            await this.authenticateRemoteRegistry(stage);
+        }
+        await this.host.exec(`mkdir -p ${shellQuote(this.getAppDirectory(stage))}`, { dryRun });
+        await this.host.exec(`docker network inspect ${shellQuote(network)} >/dev/null 2>&1 || docker network create ${shellQuote(network)}`, { dryRun });
+    }
+    async assertRemoteHostReady(dryRun) {
+        await this.host.assertReady({ dryRun });
+    }
+    async runLocalDetachedContainer(stage, config) {
+        await this.prepareLocalNetwork(config.network);
+        if (config.pull !== false) {
+            await runLocal(`docker pull ${shellQuote(config.image)}`, this.getLocalRunOptions());
+        }
+        await this.withLocalEnvironmentFile(stage, config, async () => {
+            await runLocal(`docker rm -f ${shellQuote(config.name)} >/dev/null 2>&1 || true`, this.getLocalRunOptions());
+            await runLocal(this.getDockerRunCommand({
+                ...config,
+                labels: {
+                    ...config.labels,
+                    "saws.configHash": config.configHash ?? this.getContainerConfigHash(config),
+                },
+            }, true), this.getLocalRunOptions());
+        });
+    }
+    async runEphemeralContainer(stage, config, options = {}) {
+        if (stage === "local" || this.host == null) {
+            await this.prepareLocalNetwork(config.network, {
+                dryRun: options.dryRun,
+                serviceName: options.logServiceName,
+            });
+            if (config.pull !== false) {
+                await runLocal(`docker pull ${shellQuote(config.image)}`, this.getLocalRunOptions({
+                    dryRun: options.dryRun,
+                    serviceName: options.logServiceName,
+                }));
+            }
+            await this.withLocalEnvironmentFile(stage, config, async () => {
+                await runLocal(`docker rm -f ${shellQuote(config.name)} >/dev/null 2>&1 || true`, this.getLocalRunOptions({
+                    dryRun: options.dryRun,
+                    serviceName: options.logServiceName,
+                }));
+                if (!options.dryRun)
+                    this.activeEphemeralContainers.add(config.name);
+                try {
+                    await runLocal(this.getDockerRunCommand(config, false, { remove: true, includeRestart: false }), this.getLocalRunOptions({
+                        dryRun: options.dryRun,
+                        serviceName: options.logServiceName,
+                    }));
+                }
+                finally {
+                    this.activeEphemeralContainers.delete(config.name);
+                }
+            });
+            return;
+        }
+        await this.assertRemoteHostReady(options.dryRun);
+        await this.prepareRemote(stage, config.network, options.dryRun);
+        if (config.pull !== false) {
+            await this.host.exec(`docker pull ${shellQuote(config.image)}`, { dryRun: options.dryRun });
+        }
+        let environmentFile;
+        try {
+            environmentFile = await this.writeRemoteEnvironmentFile(stage, config, options.dryRun);
+            await this.host.exec(`docker rm -f ${shellQuote(config.name)} >/dev/null 2>&1 || true`, {
+                dryRun: options.dryRun,
+            });
+            await this.host.exec(this.getDockerRunCommand(config, false, { remove: true, includeRestart: false }), { dryRun: options.dryRun });
+        }
+        finally {
+            if (environmentFile != null) {
+                await this.removeRemoteRuntimeFile(environmentFile, options.dryRun);
+            }
+        }
+    }
+    async startLocalContainer(config) {
+        await this.prepareLocalNetwork(config.network);
+        if (config.pull !== false) {
+            await runLocal(`docker pull ${shellQuote(config.image)}`, this.getLocalRunOptions());
+        }
+        await runLocal(`docker rm -f ${shellQuote(config.name)} >/dev/null 2>&1 || true`, this.getLocalRunOptions());
+        const args = [
+            "run",
+            "--name",
+            config.name,
+            "--network",
+            config.network,
+            ...(config.env == null
+                ? []
+                : Object.entries(config.env).flatMap(([key, value]) => ["-e", `${key}=${value}`])),
+            ...(config.envFiles ?? []).flatMap((envFile) => ["--env-file", envFile]),
+            ...(config.volumes ?? []).flatMap((volume) => ["-v", volume]),
+            ...(config.ports ?? []).flatMap((port) => ["-p", port]),
+            ...Object.entries(config.labels ?? {}).flatMap(([key, value]) => [
+                "--label",
+                `${key}=${value}`,
+            ]),
+            ...this.getDockerHealthCheckArgs(config.healthCheck).flatMap((argument) => argument.flagOnly ? [argument.flag] : [argument.flag, argument.value]),
+            config.image,
+            ...(config.command ?? []),
+        ];
+        return spawn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+    }
+    getLocalRunOptions(options = {}) {
+        const { serviceName, ...runOptions } = options;
+        return {
+            ...runOptions,
+            logSink: this.getRuntimeLogSink(),
+            serviceName: serviceName ?? this.name,
+            signal: this.localRunAbortController.signal,
+        };
+    }
+    async runRemoteContainer(stage, config) {
+        await this.prepareRemote(stage, config.network);
+        if (config.pull !== false) {
+            await this.host.exec(`docker pull ${shellQuote(config.image)}`);
+        }
+        const configHash = config.configHash ?? this.getContainerConfigHash(config);
+        const containerName = shellQuote(config.name);
+        const image = shellQuote(config.image);
+        const currentHash = `$(docker inspect --format ${shellQuote('{{index .Config.Labels "saws.configHash"}}')} ${containerName} 2>/dev/null || true)`;
+        const currentImage = `$(docker inspect --format ${shellQuote("{{.Image}}")} ${containerName} 2>/dev/null || true)`;
+        const desiredImage = `$(docker image inspect --format ${shellQuote("{{.Id}}")} ${image})`;
+        const isRunning = `$(docker inspect --format ${shellQuote("{{.State.Running}}")} ${containerName} 2>/dev/null || true)`;
+        await this.host.exec([
+            `if [ "${currentHash}" = ${shellQuote(configHash)} ] && [ "${currentImage}" = "${desiredImage}" ]; then`,
+            `if [ "${isRunning}" = "true" ]; then`,
+            `echo ${shellQuote(`Container ${config.name} is unchanged`)}`,
+            "else",
+            `docker start ${containerName}`,
+            "fi",
+            "else",
+            `docker rm -f ${containerName} >/dev/null 2>&1 || true`,
+            this.getDockerRunCommand({
+                ...config,
+                labels: {
+                    ...config.labels,
+                    "saws.configHash": configHash,
+                },
+            }, true),
+            "fi",
+        ].join("\n"));
+    }
+    getDockerRunCommand(config, detached, options = {}) {
+        const envArgs = Object.entries(config.env ?? {})
+            .map(([key, value]) => `-e ${shellQuote(`${key}=${value}`)}`)
+            .join(" ");
+        const envFileArgs = (config.envFiles ?? [])
+            .map((envFile) => `--env-file ${shellQuote(envFile)}`)
+            .join(" ");
+        const volumeArgs = (config.volumes ?? []).map((volume) => `-v ${shellQuote(volume)}`).join(" ");
+        const portArgs = (config.ports ?? []).map((port) => `-p ${shellQuote(port)}`).join(" ");
+        const labelArgs = Object.entries(config.labels ?? {})
+            .map(([key, value]) => `--label ${shellQuote(`${key}=${value}`)}`)
+            .join(" ");
+        const healthCheckArgs = this.getDockerHealthCheckArgs(config.healthCheck)
+            .map((argument) => argument.flagOnly ? argument.flag : `${argument.flag} ${shellQuote(argument.value)}`)
+            .join(" ");
+        const command = (config.command ?? []).map((part) => shellQuote(part)).join(" ");
+        return [
+            "docker run",
+            options.remove ? "--rm" : "",
+            detached ? "-d" : "",
+            `--name ${shellQuote(config.name)}`,
+            `--network ${shellQuote(config.network)}`,
+            options.includeRestart === false
+                ? ""
+                : `--restart ${shellQuote(config.restart ?? "unless-stopped")}`,
+            envArgs,
+            envFileArgs,
+            volumeArgs,
+            portArgs,
+            labelArgs,
+            healthCheckArgs,
+            shellQuote(config.image),
+            command,
+        ]
+            .filter(Boolean)
+            .join(" ");
+    }
+    getDockerHealthCheckArgs(healthCheck) {
+        if (healthCheck == null)
+            return [];
+        if (healthCheck === false)
+            return [{ flag: "--no-healthcheck", flagOnly: true }];
+        if (healthCheck.command.length === 0) {
+            throw new Error("Docker health check command cannot be empty");
+        }
+        if (healthCheck.retries != null &&
+            (!Number.isInteger(healthCheck.retries) || healthCheck.retries < 1)) {
+            throw new Error("Docker health check retries must be a positive integer");
+        }
+        const args = [{ flag: "--health-cmd", flagOnly: false, value: healthCheck.command }];
+        for (const [flag, value] of [
+            ["--health-interval", healthCheck.interval],
+            ["--health-timeout", healthCheck.timeout],
+            ["--health-start-period", healthCheck.startPeriod],
+        ]) {
+            if (value == null)
+                continue;
+            if (!isDockerDuration(value)) {
+                throw new Error(`${flag.slice(2)} must be a positive Docker duration`);
+            }
+            args.push({ flag, flagOnly: false, value });
+        }
+        if (healthCheck.retries != null) {
+            args.push({ flag: "--health-retries", flagOnly: false, value: String(healthCheck.retries) });
+        }
+        return args;
+    }
+    getContainerConfigHash(config) {
+        const labels = { ...config.labels };
+        delete labels["saws.configHash"];
+        return createHash("sha256")
+            .update(JSON.stringify({
+            name: config.name,
+            image: config.image,
+            network: config.network,
+            environment: sortRecord(config.env),
+            envFiles: [...(config.envFiles ?? [])].sort(),
+            volumes: [...(config.volumes ?? [])].sort(),
+            ports: [...(config.ports ?? [])].sort(),
+            command: config.command ?? [],
+            labels: sortRecord(labels),
+            restart: config.restart ?? "unless-stopped",
+            healthCheck: config.healthCheck === false
+                ? false
+                : config.healthCheck == null
+                    ? null
+                    : {
+                        command: config.healthCheck.command,
+                        interval: config.healthCheck.interval,
+                        timeout: config.healthCheck.timeout,
+                        retries: config.healthCheck.retries,
+                        startPeriod: config.healthCheck.startPeriod,
+                    },
+        }))
+            .digest("hex");
+    }
+    async writeRemoteEnvironmentFile(stage, config, dryRun) {
+        const contents = serializeEnvironment(config.env);
+        if (contents == null)
+            return undefined;
+        const runtimeFile = await this.writeRemoteRuntimeFile(stage, `${this.name}/container.env`, contents, dryRun);
+        config.env = undefined;
+        config.envFiles = [...(config.envFiles ?? []), runtimeFile.remotePath];
+        return runtimeFile;
+    }
+    async writeLocalEnvironmentFile(stage, config) {
+        const contents = serializeEnvironment(config.env);
+        if (contents == null)
+            return undefined;
+        const localPath = await this.writeLocalRuntimeFile(stage, `${this.name}/container.env`, contents);
+        config.env = undefined;
+        config.envFiles = [...(config.envFiles ?? []), localPath];
+        return localPath;
+    }
+    async withLocalEnvironmentFile(stage, config, callback) {
+        const environmentFile = await this.writeLocalEnvironmentFile(stage, config);
+        try {
+            return await callback();
+        }
+        finally {
+            if (environmentFile != null) {
+                await rm(environmentFile, { force: true });
+            }
+        }
+    }
+    async writeRemoteRuntimeFile(stage, relativePath, contents, dryRun) {
+        const localDir = path.resolve(".saws", "hosts", this.host.name, stage);
+        await mkdir(localDir, { recursive: true });
+        const localPath = path.join(localDir, relativePath);
+        await mkdir(path.dirname(localPath), { recursive: true });
+        await writeFile(localPath, contents, { mode: 0o600 });
+        const remotePath = path.posix.join(this.getAppDirectory(stage), relativePath);
+        await this.host.exec(`mkdir -p ${shellQuote(path.posix.dirname(remotePath))}`, { dryRun });
+        await this.host.copyFile(localPath, remotePath, { dryRun });
+        return { localPath, remotePath };
+    }
+    async removeRemoteRuntimeFile(runtimeFile, dryRun) {
+        await rm(runtimeFile.localPath, { force: true });
+        await this.host.exec(`rm -f ${shellQuote(runtimeFile.remotePath)}`, { dryRun });
+    }
+    async writeLocalRuntimeFile(stage, relativePath, contents) {
+        const localPath = path.resolve(".saws", "local", stage, relativePath);
+        await mkdir(path.dirname(localPath), { recursive: true });
+        await writeFile(localPath, contents, { mode: 0o600 });
+        return localPath;
+    }
+    observeDevProcess(process) {
+        process.stdout?.on("data", (chunk) => {
+            this.writeRuntimeLog(chunk.toString("utf8"), "stdout");
+        });
+        process.stderr?.on("data", (chunk) => {
+            this.writeRuntimeLog(chunk.toString("utf8"), "stderr");
+        });
+        process.once("error", (error) => {
+            this.writeRuntimeLog(`${error.stack ?? error.message}\n`, "stderr");
+        });
+        process.once("exit", (code, signal) => {
+            if (this.devProcess === process)
+                this.devProcess = undefined;
+            if (code !== 0 && signal !== "SIGTERM" && signal !== "SIGINT") {
+                this.writeRuntimeLog(`Docker container exited with code ${code ?? "unknown"}${signal == null ? "" : ` (${signal})`}\n`, "stderr");
+            }
+        });
+    }
+    getStdOut() {
+        return null;
+    }
+    getStdErr() {
+        return null;
+    }
+    async removeDevEnvironmentFile() {
+        if (this.devEnvironmentFile == null)
+            return;
+        const localPath = this.devEnvironmentFile;
+        this.devEnvironmentFile = undefined;
+        await rm(localPath, { force: true });
+    }
+    removeActiveEphemeralContainers() {
+        for (const container of this.activeEphemeralContainers) {
+            spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+        }
+        this.activeEphemeralContainers.clear();
+    }
+}
+function serializeEnvironment(environment) {
+    const entries = Object.entries(environment ?? {});
+    if (entries.length === 0)
+        return undefined;
+    for (const [key, value] of entries) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new Error(`Invalid Docker environment variable name: ${key}`);
+        }
+        if (value.includes("\n") || value.includes("\r")) {
+            throw new Error(`Docker environment variable ${key} contains a newline`);
+        }
+    }
+    return `${entries.map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+}
+function sortRecord(record) {
+    return Object.fromEntries(Object.entries(record ?? {}).sort(([left], [right]) => left.localeCompare(right)));
+}
+function isDockerDuration(value) {
+    if (!/^(?:\d+(?:\.\d+)?(?:ns|us|µs|ms|s|m|h))+$/.test(value))
+        return false;
+    return [...value.matchAll(/(\d+(?:\.\d+)?)(?:ns|us|µs|ms|s|m|h)/g)].some((match) => Number(match[1]) > 0);
+}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./DockerService.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saws/docker-service",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.4",
   "description": "",
   "license": "ISC",
   "author": "",
@@ -13,6 +13,9 @@
     }
   },
   "dependencies": {
-    "@saws/core": "2.0.0-beta.3"
-  }
+    "@saws/core": "2.0.0-beta.4"
+  },
+  "files": [
+    "./dist"
+  ]
 }