@alchemy.run/docker 0.0.0 → 2.0.0-beta.85

package/lib/Container.js

@@ -0,0 +1,745 @@
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
+import { toSeconds } from "alchemy/Util/Duration";
+import { sha256, sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.js";
+import { healthcheckCommand, isHealthcheckDisabled } from "./HealthcheckCommand.js";
+const CREATE_CONFIG_HASH_LABEL = "alchemy::container-config";
+/**
+ * A Docker container managed through the active Docker context.
+ *
+ * This resource creates, starts, stops, inspects, and removes containers through
+ * the Docker CLI. It is not interchangeable with `Cloudflare.Container`, which
+ * manages Cloudflare's container platform; use pushed image references to bridge
+ * Docker-built images into cloud container runtimes.
+ *
+ *
+ * ### Running Containers
+ * **Example:** Nginx with a published port
+ * ```typescript
+ * const nginx = yield* Docker.Container("nginx", {
+ *   image: "nginx:alpine",
+ *   ports: [{ external: 8080, internal: 80 }],
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Secret Environment
+ * **Example:** Redacted env var
+ * ```typescript
+ * const password = yield* Config.Redacted("POSTGRES_PASSWORD");
+ * const db = yield* Docker.Container("postgres", {
+ *   image: "postgres:18-alpine",
+ *   environment: {
+ *     POSTGRES_PASSWORD: password,
+ *   },
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Environment Files
+ * **Example:** Layered Docker env files
+ * ```typescript
+ * const app = yield* Docker.Container("app", {
+ *   image: "ghcr.io/acme/app:latest",
+ *   envFiles: ["./config/base.env", "./config/production.env"],
+ *   // Explicit values are passed after env files and take precedence.
+ *   environment: { LOG_LEVEL: "info" },
+ * });
+ * ```
+ *
+ * Editing an env file replaces the container on the next deploy, as does
+ * adopting a container that uses env files (once, so later edits are tracked).
+ * Alchemy reads
+ * the files at plan time but keeps only a digest of their contents, on the
+ * container's own label; neither the values nor the digest are written to
+ * Alchemy state. Docker exposes the resolved values through `docker inspect`,
+ * so treat env files as secrets.
+ *
+ * ### Networks and Volumes
+ * **Example:** PostgreSQL with persistent storage
+ * ```typescript
+ * const network = yield* Docker.Network("app-network");
+ * const data = yield* Docker.Volume("postgres-data");
+ * const postgresName = "app-postgres";
+ * yield* Docker.Container("postgres", {
+ *   name: postgresName,
+ *   image: "postgres:18-alpine",
+ *   ports: [{ external: 15432, internal: 5432 }],
+ *   volumes: [{ hostPath: data.name, containerPath: "/var/lib/postgresql/data" }],
+ *   networks: [{ name: network.name, aliases: ["postgres"] }],
+ *   start: true,
+ * });
+ * const runtime = yield* Docker.inspectContainer(postgresName);
+ * ```
+ *
+ * ### Host Access
+ * `extraHosts` writes lines into the container's `/etc/hosts`; it changes name
+ * resolution and nothing else. Docker's `host-gateway` alias resolves to the
+ * host machine, which is how a container reaches a service on the developer's
+ * loopback.
+ *
+ * On Linux `host-gateway` is the Docker bridge gateway (typically
+ * `172.17.0.1`), so a container's packets to it arrive on the host's `INPUT`
+ * chain. Under a default-deny firewall — ufw ships
+ * `DEFAULT_INPUT_POLICY="DROP"` — the hostname resolves correctly and the
+ * connection then times out, which reads like an application bug rather than a
+ * firewall one. Allow the bridge subnet to fix it:
+ * `sudo ufw allow from 172.16.0.0/12`.
+ *
+ * **Example:** Reach a service on the developer's machine
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // `host-gateway` resolves to the host machine, so a database listening
+ *   // on the developer's loopback is reachable from inside the container.
+ *   extraHosts: ["host.docker.internal:host-gateway"],
+ *   environment: {
+ *     DATABASE_URL: "postgres://postgres@host.docker.internal:5432/app",
+ *   },
+ *   start: true,
+ * });
+ * ```
+ *
+ * **Example:** Pin a hostname to a fixed address
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // Any `hostname:address` pair — host access is just the common case.
+ *   extraHosts: ["service.example:192.0.2.10"],
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Runtime Options
+ * **Example:** Contain a background worker
+ * ```typescript
+ * const worker = yield* Docker.Container("worker", {
+ *   image: "oven/bun:1",
+ *   memory: "512m",
+ *   memorySwap: "512m",
+ *   memoryReservation: "256m",
+ *   cpus: 0.5,
+ *   pidsLimit: 128,
+ *   readOnlyRootFilesystem: true,
+ *   capDrop: ["ALL"],
+ *   noNewPrivileges: true,
+ *   init: true,
+ *   user: "1000:1000",
+ *   tmpfs: [{ path: "/tmp", size: "32m", mode: 0o1777 }],
+ * });
+ * ```
+ *
+ * **Example:** Customize confinement, process limits, and log rotation
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   seccompProfile: "./security/api-seccomp.json", // client-side JSON; edits roll the container
+ *   appArmorProfile: "my-loaded-profile",          // must already be loaded on the host
+ *   groupAdd: ["1000"],
+ *   ulimits: { nofile: { soft: 1024, hard: 4096 } },
+ *   logDriver: "local",
+ *   logOptions: { "max-size": "10m", "max-file": "3" },
+ *   oomScoreAdjustment: 200,
+ *   stopSignal: "SIGTERM",
+ * });
+ * ```
+ *
+ * **Example:** Share a donor container's network namespace
+ * ```typescript
+ * const donor = yield* Docker.Container("donor", { image: "redis:alpine" });
+ * const sidecar = yield* Docker.Container("sidecar", {
+ *   image: "busybox:latest",
+ *   networkMode: { container: donor.id },
+ * });
+ * ```
+ *
+ * **Example:** Add capabilities and devices
+ * ```typescript
+ * const worker = yield* Docker.Container("worker", {
+ *   image: "ubuntu:latest",
+ *   capAdd: ["SYS_ADMIN"],
+ *   devices: [{ hostPath: "/dev/fuse", containerPath: "/dev/fuse" }],
+ * });
+ * ```
+ *
+ * **Example:** Publish on any free host port
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // `external: 0` lets Docker choose; the assigned port is reported back.
+ *   ports: [{ external: 0, internal: 3000 }],
+ *   start: true,
+ * });
+ * const hostPort = api.ports["3000/tcp"];
+ * ```
+ *
+ * ### Traefik
+ * **Example:** Route a container through Traefik
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   networks: [{ name: "traefik" }],
+ *   labels: {
+ *     "traefik.enable": "true",
+ *     "traefik.http.routers.api.rule": "Host(`api.example.com`)",
+ *     "traefik.http.services.api.loadbalancer.server.port": "3000",
+ *   },
+ *   stopTimeout: "30 seconds",
+ *   start: true,
+ * });
+ * ```
+ *
+ * **Example:** Use a Docker.Context resource
+ * ```typescript
+ * const remote = yield* Docker.Context("remote", {
+ *   name: "remote-build",
+ *   docker: "host=ssh://docker@example.com",
+ * });
+ *
+ * const api = yield* Docker.Container("api", {
+ *   image: "nginx:alpine",
+ *   context: remote,
+ * });
+ * ```
+ *
+ * @resource
+ * @product Container
+ */
+export const Container = Resource("Docker.Container");
+/**
+ * Inspect a Docker container by name and return normalized runtime details.
+ *
+ * This is a small public wrapper around Docker's raw inspect output. It returns
+ * the stable data Alchemy callers typically need, including bound host ports.
+ */
+export const inspectContainer = (name, context) => Docker.pipe(Effect.flatMap((docker) => docker.container.inspect(name, dockerContextName(context))), Effect.map((container) => toContainerAttributes(container, container.Config.Image)));
+export const ContainerProvider = () => Provider.effect(Container, Effect.gen(function* () {
+    const docker = yield* Docker;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    // Env files are read so editing one rolls the container, but only a
+    // digest of their bytes enters the config hash, which lives solely in
+    // the container's own label (where `docker inspect` already exposes
+    // the resolved values). Neither contents nor digest reach alchemy state.
+    const envFilesDigest = Effect.fn(function* (envFiles) {
+        if (!envFiles?.length)
+            return undefined;
+        const digests = yield* Effect.forEach(envFiles, (file) => fs.readFile(path.resolve(file)).pipe(Effect.flatMap(sha256), Effect.map((digest) => `${file}\0${digest}`)));
+        return yield* sha256(digests.join("\n"));
+    });
+    // Docker CLI loads seccomp profiles from client-side files at create
+    // time. Hash the contents as well as the path so policy edits are never
+    // silently ignored on subsequent deploys.
+    const seccompProfileDigest = Effect.fn(function* (profile) {
+        if (!isCustomSeccompProfile(profile))
+            return undefined;
+        return yield* fs.readFile(path.resolve(profile)).pipe(Effect.flatMap(sha256));
+    });
+    // Without env files the hash input is unchanged from before they were
+    // supported, so existing containers keep their label and are not rolled.
+    const desiredConfigHash = Effect.fn(function* (args, news) {
+        const envFiles = yield* envFilesDigest(news.envFiles);
+        const seccompProfile = yield* seccompProfileDigest(news.seccompProfile);
+        return yield* sha256Object({
+            ...args,
+            imageId: normalizeImageId(news.image),
+            ...(envFiles === undefined ? {} : { envFiles }),
+            ...(seccompProfile === undefined ? {} : { seccompProfile }),
+        });
+    });
+    const reconcileNetworks = Effect.fn(function* (live, news, olds) {
+        const context = dockerContextName(news.context);
+        const connect = new Map();
+        const disconnect = new Set();
+        for (const network of news.networks ?? []) {
+            const entry = live.NetworkSettings.Networks?.[network.name];
+            if (!entry) {
+                connect.set(network.name, network);
+            }
+            else if (!Equal.equals(entry.Aliases ?? [], network.aliases ?? [])) {
+                connect.set(network.name, network);
+                disconnect.add(network.name);
+            }
+        }
+        // Only networks alchemy itself attached are alchemy's to detach, and
+        // `olds.networks` is the sole record of which those are — the live
+        // container cannot say who connected a network. Sweeping every live
+        // network instead tore off the default `bridge` and anything a user,
+        // compose file, or another tool had attached out of band (#1386).
+        const desired = new Set((news.networks ?? []).map((n) => n.name));
+        for (const network of olds?.networks ?? []) {
+            if (!desired.has(network.name) && live.NetworkSettings.Networks?.[network.name]) {
+                disconnect.add(network.name);
+            }
+        }
+        yield* Effect.forEach(disconnect, (network) => docker.network.disconnect({ network, container: live.Id, context }), { concurrency: "unbounded" });
+        yield* Effect.forEach(connect.values(), (network) => docker.network.connect({
+            network: network.name,
+            container: live.Id,
+            alias: network.aliases,
+            context,
+        }), { concurrency: "unbounded" });
+    });
+    const inspect = (name, context) => docker.container
+        .inspect(name, context)
+        .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
+    const remove = (name, context) => docker.container.stop(name, context).pipe(Effect.andThen(docker.container.remove(name, true, context)), Effect.catchReason("PlatformError", "NotFound", () => Effect.void));
+    return Container.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+            const context = dockerContextName(olds.context);
+            const name = yield* dockerPhysicalName(id, olds, instanceId);
+            const info = yield* inspect(name, context);
+            if (!info)
+                return undefined;
+            // `olds.image` may be `undefined` when a `creating` row was
+            // persisted before upstream Outputs resolved — fall back to the
+            // live container's actual image.
+            const attrs = toContainerAttributes(info, olds.image !== undefined ? normalizeImageRef(olds.image) : info.Config.Image);
+            if (output)
+                return attrs;
+            // Without prior state, only adopt a container that carries our
+            // branding; anything else is foreign and gated behind `--adopt`.
+            const owned = yield* hasAlchemyTags(id, info.Config.Labels ?? undefined);
+            return owned ? attrs : Unowned(attrs);
+        }),
+        diff: Effect.fn(function* ({ id, instanceId, news, olds }) {
+            if (!isResolved(news))
+                return undefined;
+            // An Output-valued `image` doesn't survive a `creating`-state
+            // round-trip (it deserializes as `undefined`) — without comparable
+            // prior create args, let the engine apply its default update logic.
+            if (olds.image === undefined)
+                return undefined;
+            if (dockerContextName(olds.context) !== dockerContextName(news.context)) {
+                return { action: "replace", deleteFirst: true };
+            }
+            const oldArgs = yield* makeCreateArgs(id, olds, instanceId);
+            const newArgs = yield* makeCreateArgs(id, news, instanceId);
+            if (!Equal.equals(oldArgs, newArgs)) {
+                return { action: "replace", deleteFirst: true };
+            }
+            if (!Equal.equals(olds.networks ?? [], news.networks ?? []) ||
+                (olds.start ?? false) !== (news.start ?? false)) {
+                return { action: "update" };
+            }
+            // File-backed inputs can change without changing their paths.
+            // Compare their digests against the live config hash.
+            if (news.envFiles?.length || isCustomSeccompProfile(news.seccompProfile)) {
+                const live = yield* inspect(newArgs.name, dockerContextName(news.context));
+                const applied = live?.Config.Labels?.[CREATE_CONFIG_HASH_LABEL];
+                if (applied !== undefined && applied !== (yield* desiredConfigHash(newArgs, news))) {
+                    return { action: "update" };
+                }
+            }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news, olds, output }) {
+            const context = dockerContextName(news.context);
+            const args = yield* makeCreateArgs(id, news, instanceId);
+            const configHash = yield* desiredConfigHash(args, news);
+            // Adoption has output but no olds. In that case the observed
+            // container already lives in the desired context.
+            const oldContext = olds ? dockerContextName(olds.context) : context;
+            const desiredLive = yield* inspect(args.name, context);
+            const previous = output && (output.name !== args.name || oldContext !== context)
+                ? yield* inspect(output.name, oldContext)
+                : undefined;
+            if (previous) {
+                yield* remove(previous.Id, oldContext);
+            }
+            const live = desiredLive?.Id === previous?.Id ? undefined : desiredLive;
+            const oldArgs = live?.Config.Labels?.[CREATE_CONFIG_HASH_LABEL] === undefined && olds !== undefined
+                ? yield* makeCreateArgs(id, {
+                    ...olds,
+                    image: olds.image ?? output?.imageRef ?? news.image,
+                }, instanceId)
+                : undefined;
+            const recreate = live !== undefined &&
+                (live.Config.Labels?.[CREATE_CONFIG_HASH_LABEL] === undefined
+                    ? (oldArgs !== undefined && !Equal.equals(oldArgs, args)) ||
+                        normalizeImageId(olds?.image) !== normalizeImageId(news.image) ||
+                        !matchesLegacyConfig(live, args, news.image) ||
+                        // Env file contents can't be compared without a label (e.g. an
+                        // adopted container); recreate once so later edits are tracked.
+                        (news.envFiles?.length ?? 0) > 0 ||
+                        isCustomSeccompProfile(news.seccompProfile) ||
+                        // A legacy/adopted container has no stamped config hash.
+                        // Do not retain it without proof that the requested security
+                        // restrictions were applied.
+                        hasHardeningOptions(news)
+                    : live.Config.Labels[CREATE_CONFIG_HASH_LABEL] !== configHash);
+            if (recreate) {
+                yield* remove(live.Id, context);
+            }
+            const current = recreate ? undefined : live;
+            if (!current) {
+                const internalTags = yield* createInternalTags(id);
+                const { stdout: containerId } = yield* docker.container.create({
+                    ...args,
+                    context,
+                    label: {
+                        ...args.label,
+                        ...internalTags,
+                        [CREATE_CONFIG_HASH_LABEL]: configHash,
+                    },
+                });
+                yield* Effect.forEach(news.networks ?? [], (network) => docker.network.connect({
+                    network: network.name,
+                    container: containerId,
+                    alias: network.aliases,
+                    context,
+                }), { concurrency: "unbounded" });
+                if (news.start) {
+                    yield* docker.container.start(containerId, context);
+                }
+                const info = yield* docker.container.inspect(containerId, context);
+                return toContainerAttributes(info, args.image);
+            }
+            yield* reconcileNetworks(current, news, olds);
+            if (news.start && current.State.Status !== "running") {
+                yield* docker.container.start(current.Id, context);
+            }
+            else if (!news.start && current.State.Status === "running") {
+                yield* docker.container.stop(current.Id, context);
+            }
+            return yield* docker.container
+                .inspect(current.Id, context)
+                .pipe(Effect.map((info) => toContainerAttributes(info, args.image)));
+        }),
+        delete: Effect.fn(({ olds, output }) => remove(output.name, dockerContextName(olds.context))),
+    });
+}));
+const normalizeImageRef = (image) => typeof image === "string" ? image : image.imageRef;
+const normalizeImageId = (image) => typeof image === "string" ? undefined : image?.imageId;
+// Containers created before config hashes were introduced are compared using
+// the fields Docker reports without image-default normalization. A subsequent
+// create stamps the complete resolved configuration hash.
+const matchesLegacyConfig = (live, desired, image) => (normalizeImageId(image)
+    ? live.Image === normalizeImageId(image)
+    : live.Config.Image === desired.image) &&
+    (desired.command === undefined || Equal.equals(live.Config.Cmd, desired.command)) &&
+    Object.entries(desired.env ?? {}).every(([key, value]) => live.Config.Env?.includes(`${key}=${value}`));
+const makeCreateArgs = (id, news, instanceId) => dockerPhysicalName(id, news, instanceId).pipe(Effect.tap(() => validateContainerOptions(news)), Effect.map((name) => ({
+    name,
+    image: normalizeImageRef(news.image),
+    command: news.command,
+    env: normalizeEnvironment(news.environment),
+    "env-file": news.envFiles?.length ? news.envFiles : undefined,
+    volume: news.volumes?.map((v) => `${v.hostPath}:${v.containerPath}${v.readOnly ? ":ro" : ""}`),
+    p: news.ports?.map((port) => {
+        const target = `${port.internal}/${port.protocol ?? "tcp"}`;
+        // `external: 0` means "any free host port". Docker spells that as a
+        // bare container port (`-p 80/tcp`); `-p 0:80/tcp` instead asks for
+        // host port 0 literally, which the daemon accepts and then reports
+        // back as 0.
+        return isRandomHostPort(port.external) ? target : `${port.external}:${target}`;
+    }),
+    "add-host": news.extraHosts,
+    network: normalizeNetworkMode(news.networkMode),
+    "cap-add": normalizeCapabilities(news.capAdd),
+    ...(news.capDrop?.length ? { "cap-drop": normalizeCapabilities(news.capDrop) } : {}),
+    ...(news.memory !== undefined ? { memory: news.memory } : {}),
+    ...(news.memorySwap !== undefined ? { "memory-swap": news.memorySwap } : {}),
+    ...(news.memoryReservation !== undefined
+        ? { "memory-reservation": news.memoryReservation }
+        : {}),
+    ...(news.cpus !== undefined ? { cpus: news.cpus } : {}),
+    ...(news.pidsLimit !== undefined ? { "pids-limit": news.pidsLimit } : {}),
+    ...(news.readOnlyRootFilesystem ? { "read-only": true } : {}),
+    ...(normalizeSecurityOptions(news) ? { "security-opt": normalizeSecurityOptions(news) } : {}),
+    ...(news.userNamespace !== undefined ? { userns: news.userNamespace } : {}),
+    ...(news.groupAdd?.length ? { "group-add": normalizeGroups(news.groupAdd) } : {}),
+    ...(Object.keys(news.ulimits ?? {}).length ? { ulimit: normalizeUlimits(news.ulimits) } : {}),
+    ...(news.logDriver !== undefined ? { "log-driver": news.logDriver } : {}),
+    ...(Object.keys(news.logOptions ?? {}).length
+        ? { "log-opt": normalizeLogOptions(news.logOptions) }
+        : {}),
+    ...(news.oomScoreAdjustment !== undefined
+        ? { "oom-score-adj": news.oomScoreAdjustment }
+        : {}),
+    ...(news.stopSignal !== undefined ? { "stop-signal": news.stopSignal } : {}),
+    ...(news.init ? { init: true } : {}),
+    ...(news.user !== undefined ? { user: news.user } : {}),
+    ...(news.tmpfs?.length ? { tmpfs: normalizeTmpfs(news.tmpfs) } : {}),
+    device: normalizeDevices(news.devices),
+    restart: news.restart ?? "no",
+    label: news.labels,
+    "stop-timeout": toSeconds(news.stopTimeout)?.toString(),
+    rm: news.removeOnExit ?? false,
+    ...(news.healthcheck
+        ? {
+            "health-cmd": healthcheckCommand(news.healthcheck.cmd),
+            // Only when set: an always-present key would change every
+            // container's config hash and recreate it on upgrade.
+            ...(isHealthcheckDisabled(news.healthcheck.cmd) ? { "no-healthcheck": true } : {}),
+            "health-interval": normalizeDuration(news.healthcheck.interval),
+            "health-timeout": normalizeDuration(news.healthcheck.timeout),
+            "health-retries": news.healthcheck.retries ?? 0,
+            "health-start-period": normalizeDuration(news.healthcheck.startPeriod),
+            "health-start-interval": normalizeDuration(news.healthcheck.startInterval),
+        }
+        : {
+            "health-cmd": undefined,
+            "health-interval": undefined,
+            "health-timeout": undefined,
+            "health-retries": undefined,
+            "health-start-period": undefined,
+            "health-start-interval": undefined,
+        }),
+})));
+const toContainerAttributes = (info, imageRef) => ({
+    id: info.Id,
+    name: typeof info.Name === "string" ? info.Name.replace(/^\//, "") : info.Id,
+    status: info.State.Status,
+    createdAt: Date.parse(info.Created) || Date.now(),
+    imageRef,
+    ports: toPortAttributes(info),
+    networkMode: info.HostConfig.NetworkMode,
+    capAdd: info.HostConfig.CapAdd ?? undefined,
+    devices: info.HostConfig.Devices?.map((device) => ({
+        hostPath: device.PathOnHost,
+        containerPath: device.PathInContainer,
+        permissions: device.CgroupPermissions,
+    })),
+});
+const normalizeNetworkMode = (mode) => mode === undefined ? undefined : typeof mode === "string" ? mode : `container:${mode.container}`;
+const normalizeCapabilities = (capAdd) => {
+    if (!capAdd?.length)
+        return undefined;
+    return [...new Set(capAdd.map((capability) => capability.trim()).filter(Boolean))].sort();
+};
+const isCustomSeccompProfile = (profile) => profile !== undefined && profile !== "builtin" && profile !== "unconfined";
+const normalizeSecurityOptions = (props) => {
+    const options = [
+        ...(props.noNewPrivileges ? ["no-new-privileges"] : []),
+        ...(props.seccompProfile ? [`seccomp=${props.seccompProfile}`] : []),
+        ...(props.appArmorProfile ? [`apparmor=${props.appArmorProfile}`] : []),
+    ];
+    return options.length ? options : undefined;
+};
+const normalizeGroups = (groups) => [...new Set(groups.map((group) => group.trim()))].sort();
+const normalizeUlimits = (limits) => Object.entries(limits ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, { soft, hard }]) => `${name}=${soft}:${hard}`);
+const normalizeLogOptions = (options) => Object.entries(options ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `${name}=${value}`);
+const normalizeTmpfs = (mounts) => [...mounts]
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map(({ path, size, mode }) => {
+    const options = [
+        ...(size !== undefined ? [`size=${size}`] : []),
+        ...(mode !== undefined ? [`mode=${mode.toString(8)}`] : []),
+    ];
+    return options.length > 0 ? `${path}:${options.join(",")}` : path;
+});
+const hasHardeningOptions = (props) => (props.capDrop?.length ?? 0) > 0 ||
+    props.memory !== undefined ||
+    props.memorySwap !== undefined ||
+    props.memoryReservation !== undefined ||
+    props.cpus !== undefined ||
+    props.pidsLimit !== undefined ||
+    props.readOnlyRootFilesystem === true ||
+    props.noNewPrivileges === true ||
+    props.seccompProfile !== undefined ||
+    props.appArmorProfile !== undefined ||
+    props.userNamespace !== undefined ||
+    (props.groupAdd?.length ?? 0) > 0 ||
+    Object.keys(props.ulimits ?? {}).length > 0 ||
+    props.logDriver !== undefined ||
+    Object.keys(props.logOptions ?? {}).length > 0 ||
+    props.oomScoreAdjustment !== undefined ||
+    props.stopSignal !== undefined ||
+    props.init === true ||
+    props.user !== undefined ||
+    (props.tmpfs?.length ?? 0) > 0;
+const normalizeDevices = (devices) => {
+    if (!devices?.length)
+        return undefined;
+    const normalized = devices.map((device) => `${device.hostPath}:${device.containerPath}:${device.permissions ?? "rwm"}`);
+    return [...new Set(normalized)].sort();
+};
+/**
+ * Raised before Docker is called when a container's options cannot be
+ * combined, e.g. sharing another container's network namespace while
+ * publishing ports.
+ */
+export class InvalidContainerOptions extends Data.TaggedError("InvalidContainerOptions") {
+}
+const validateContainerOptions = (news) => {
+    // The CLI formatter omits empty strings. Reject them instead of silently
+    // dropping user-specified resource and security restrictions.
+    for (const option of [
+        "memory",
+        "memorySwap",
+        "memoryReservation",
+        "user",
+        "seccompProfile",
+        "appArmorProfile",
+        "userNamespace",
+        "logDriver",
+        "stopSignal",
+    ]) {
+        if (news[option] !== undefined && news[option].trim().length === 0) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container ${option} cannot be empty`,
+            }));
+        }
+    }
+    if (news.capDrop?.some((capability) => capability.trim().length === 0)) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container capDrop cannot contain empty capabilities",
+        }));
+    }
+    if (news.groupAdd?.some((group) => group.trim().length === 0)) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container groupAdd cannot contain empty groups",
+        }));
+    }
+    for (const [name, limit] of Object.entries(news.ulimits ?? {})) {
+        if (!/^[a-z][a-z0-9_-]*$/.test(name) ||
+            !Number.isSafeInteger(limit.soft) ||
+            !Number.isSafeInteger(limit.hard) ||
+            limit.soft < -1 ||
+            limit.hard < -1 ||
+            (limit.hard !== -1 && (limit.soft === -1 || limit.soft > limit.hard))) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container ulimits contains an invalid soft/hard limit for ${name}`,
+            }));
+        }
+    }
+    for (const [name, value] of Object.entries(news.logOptions ?? {})) {
+        if (!name.trim() || name.includes("=") || !value.trim()) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container logOptions contains an invalid option: ${name}`,
+            }));
+        }
+    }
+    if (news.oomScoreAdjustment !== undefined &&
+        (!Number.isInteger(news.oomScoreAdjustment) ||
+            news.oomScoreAdjustment < -1000 ||
+            news.oomScoreAdjustment > 1000)) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container oomScoreAdjustment must be an integer from -1000 to 1000",
+        }));
+    }
+    if (news.memorySwap !== undefined && news.memory === undefined) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container memorySwap requires memory to be set",
+        }));
+    }
+    if (news.cpus !== undefined && (!Number.isFinite(news.cpus) || news.cpus <= 0)) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container cpus must be a finite, positive number",
+        }));
+    }
+    if (news.pidsLimit !== undefined &&
+        (!Number.isInteger(news.pidsLimit) || (news.pidsLimit <= 0 && news.pidsLimit !== -1))) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container pidsLimit must be a positive integer or -1 (unlimited)",
+        }));
+    }
+    if (isContainerNetworkMode(news.networkMode) &&
+        ((news.ports?.length ?? 0) > 0 || (news.networks?.length ?? 0) > 0)) {
+        return Effect.fail(new InvalidContainerOptions({
+            message: "Docker.Container networkMode.container cannot be combined with ports or networks",
+        }));
+    }
+    const targets = new Set();
+    for (const device of news.devices ?? []) {
+        if (targets.has(device.containerPath)) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container devices contain conflicting target path ${device.containerPath}`,
+            }));
+        }
+        targets.add(device.containerPath);
+    }
+    const tmpfsTargets = new Set();
+    for (const mount of news.tmpfs ?? []) {
+        if (mount.size !== undefined && mount.size.trim().length === 0) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container tmpfs size cannot be empty for ${mount.path}`,
+            }));
+        }
+        if (!mount.path.startsWith("/") || mount.path.includes(":") || mount.path.includes(",")) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container tmpfs target must be an absolute path: ${mount.path}`,
+            }));
+        }
+        if (tmpfsTargets.has(mount.path)) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container tmpfs contains duplicate target ${mount.path}`,
+            }));
+        }
+        if (mount.mode !== undefined &&
+            (!Number.isInteger(mount.mode) || mount.mode < 0 || mount.mode > 0o7777)) {
+            return Effect.fail(new InvalidContainerOptions({
+                message: `Docker.Container tmpfs mode is not a valid POSIX mode for ${mount.path}`,
+            }));
+        }
+        tmpfsTargets.add(mount.path);
+    }
+    return Effect.void;
+};
+const isContainerNetworkMode = (mode) => typeof mode === "string" ? mode.startsWith("container:") : mode !== undefined;
+/** First binding that carries a real (non-zero) host port. */
+const boundHostPort = (bindings) => {
+    for (const binding of bindings ?? []) {
+        if (!binding.HostPort)
+            continue;
+        const port = Number.parseInt(binding.HostPort, 10);
+        if (Number.isInteger(port) && port > 0)
+            return port;
+    }
+    return undefined;
+};
+/**
+ * `HostConfig.PortBindings` is what was *requested*, `NetworkSettings.Ports`
+ * what Docker actually *assigned* — so the assignment wins wherever both
+ * exist. A container published with `external: 0` (or any random-publish
+ * mapping) has no requested host port at all, and reading the request over
+ * the assignment reported 0 instead of the port the container is reachable
+ * on. The request is still the fallback: a created-but-not-yet-started
+ * container has empty `NetworkSettings.Ports`.
+ */
+const toPortAttributes = (info) => {
+    const ports = {};
+    for (const [internal, bindings] of Object.entries(info.HostConfig.PortBindings ?? {})) {
+        const port = boundHostPort(bindings);
+        if (port !== undefined)
+            ports[internal] = port;
+    }
+    for (const [internal, bindings] of Object.entries(info.NetworkSettings.Ports ?? {})) {
+        const port = boundHostPort(bindings);
+        if (port !== undefined)
+            ports[internal] = port;
+    }
+    return ports;
+};
+/** `external: 0` / `"0"` asks Docker to pick any free host port. */
+const isRandomHostPort = (external) => Number.parseInt(String(external), 10) === 0;
+const normalizeEnvironment = (environment) => Object.fromEntries(Object.entries(environment ?? {}).map(([key, value]) => [
+    key,
+    Redacted.isRedacted(value) ? Redacted.value(value) : value,
+]));
+const normalizeDuration = (input) => {
+    if (!input)
+        return undefined;
+    const duration = Duration.fromInputUnsafe(input);
+    // Docker parses `--health-*` durations with Go's `time.ParseDuration`, which
+    // requires a unit suffix — a bare nanosecond count is rejected with "missing
+    // unit in duration". `ns` is the lossless Go-duration rendering of the nanos.
+    return `${Duration.toNanosUnsafe(duration).toString()}ns`;
+};
+//# sourceMappingURL=Container.js.map