@alchemy.run/docker 0.0.0-stage → 2.0.0-beta.84

package/lib/Container.d.ts

@@ -0,0 +1,352 @@
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import * as Redacted from "effect/Redacted";
+import { Docker } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+export interface ContainerProps {
+    /** Image reference or Docker image resource. */
+    image: Container.Image;
+    /** Docker context name or context resource. */
+    context?: Docker.ContextRef;
+    /**
+     * Container name.
+     *
+     * @default Generated from stack, stage, logical id, and instance id.
+     */
+    name?: string;
+    /** Command to run in the container. */
+    command?: string[];
+    /** Container environment variables. Use Redacted for secrets. */
+    environment?: Record<string, string | Redacted.Redacted<string>>;
+    /**
+     * Paths to Docker env files, forwarded in the declared order as repeated
+     * `--env-file` options. Explicit `environment` values are forwarded after
+     * these files and take precedence in Docker. Editing a file's contents
+     * replaces the container on the next deploy. Only a digest of the contents
+     * is kept, on the container's own label; neither contents nor digest are
+     * written to Alchemy state. Docker itself exposes the resolved values
+     * through `docker inspect`, so treat env files as secrets.
+     */
+    envFiles?: string[];
+    /** Host/container port mappings. */
+    ports?: Container.PortMapping[];
+    /** Volume or bind mounts. */
+    volumes?: Container.VolumeMapping[];
+    /** Restart policy. */
+    restart?: "no" | "always" | "on-failure" | "unless-stopped";
+    /**
+     * Container labels. Alchemy's internal ownership labels are added
+     * automatically.
+     */
+    labels?: Record<string, string>;
+    /**
+     * Grace period before Docker forcefully kills the container after stopping
+     * it.
+     */
+    stopTimeout?: Duration.Input;
+    /** Networks to connect after create. */
+    networks?: Container.NetworkMapping[];
+    /** Network namespace. Use `{ container: id }` to share another container's namespace. */
+    networkMode?: Container.NetworkMode;
+    /** Linux capabilities to add, for example `SYS_ADMIN`. */
+    capAdd?: string[];
+    /** Host devices to expose to the container. */
+    devices?: Container.DeviceMapping[];
+    /**
+     * Extra `/etc/hosts` entries, each `hostname:address`. Docker's
+     * `host-gateway` alias resolves to the host machine, so
+     * `"host.docker.internal:host-gateway"` reaches services listening on the
+     * developer's machine from inside the container.
+     *
+     * On Linux `host-gateway` is the bridge gateway address, so those packets
+     * traverse the host's `INPUT` chain — under a default-deny firewall the
+     * name resolves and the connection then times out. See the Host Access
+     * examples.
+     */
+    extraHosts?: string[];
+    /** Remove the container when it exits. @default false */
+    removeOnExit?: boolean;
+    /** Start the container after creation/reconciliation. @default false */
+    start?: boolean;
+    /** Docker healthcheck configuration. */
+    healthcheck?: Container.Healthcheck;
+}
+export declare namespace Container {
+    type Status = "created" | "running" | "paused" | "restarting" | "removing" | "exited" | "dead";
+    type Image = string | {
+        imageRef: string;
+        imageId?: string;
+    };
+    interface PortMapping {
+        /** External port on the host. */
+        external: number | string;
+        /** Internal port inside the container. */
+        internal: number | string;
+        /** Protocol used for the mapping. @default "tcp" */
+        protocol?: "tcp" | "udp";
+    }
+    interface VolumeMapping {
+        /** Host path or named volume source. */
+        hostPath: string;
+        /** Container path. */
+        containerPath: string;
+        /** Mount read-only. @default false */
+        readOnly?: boolean;
+    }
+    interface NetworkMapping {
+        /** Network name or ID. */
+        name: string;
+        /** Network aliases for the container. */
+        aliases?: string[];
+    }
+    type NetworkMode = string | {
+        container: string;
+    };
+    interface DeviceMapping {
+        /** Host device path. */
+        hostPath: string;
+        /** Container device path. */
+        containerPath: string;
+        /** Cgroup permissions. @default "rwm" */
+        permissions?: string;
+    }
+    interface Healthcheck {
+        /**
+         * Command to run for health checks. A string runs in the container's
+         * shell. An array follows Docker's healthcheck `Test` form:
+         * `["CMD-SHELL", "pg_isready -U app"]`, `["CMD", "pg_isready", "-U", "app"]`,
+         * or `["NONE"]` to disable the image's healthcheck.
+         */
+        cmd: string[] | string;
+        /** Time between checks. */
+        interval?: Duration.Input;
+        /** Maximum time a check may run. */
+        timeout?: Duration.Input;
+        /** Consecutive failures before unhealthy. */
+        retries?: number;
+        /** Startup grace period. */
+        startPeriod?: Duration.Input;
+        /** Check interval during startup. Requires Docker API 1.44+. */
+        startInterval?: Duration.Input;
+    }
+}
+export interface Container extends Resource<"Docker.Container", ContainerProps, {
+    /** Docker container id. */
+    id: string;
+    /** Docker container name. */
+    name: string;
+    /** Docker container state. */
+    status: Container.Status;
+    /** Creation timestamp in milliseconds since epoch. */
+    createdAt: number;
+    /** Image reference used to create the container. */
+    imageRef: string;
+    /**
+     * Map of internal container ports to their bound host ports.
+     * Format: `"80/tcp" -> 8080`.
+     */
+    ports: Record<string, number>;
+    /** Configured network namespace, when reported by Docker. */
+    networkMode?: string;
+    /** Added Linux capabilities, when reported by Docker. */
+    capAdd?: string[];
+    /** Configured host devices, when reported by Docker. */
+    devices?: Container.DeviceMapping[];
+}, never, Providers> {
+}
+/**
+ * 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:** 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 declare const Container: import("alchemy/Resource").ResourceClass<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 declare const inspectContainer: (name: string, context?: Docker.ContextRef) => Effect.Effect<Container["Attributes"], PlatformError, Docker>;
+export declare const ContainerProvider: () => import("effect/Layer").Layer<Provider.Provider<Container>, never, Docker | FileSystem.FileSystem | Path.Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage>;
+declare const InvalidContainerOptions_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidContainerOptions";
+} & Readonly<A>;
+/**
+ * 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 declare class InvalidContainerOptions extends InvalidContainerOptions_base<{
+    readonly message: string;
+}> {
+}
+export {};
+//# sourceMappingURL=Container.d.ts.map

package/lib/Container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.d.ts","sourceRoot":"","sources":["../src/Container.ts"],"names":[],"mappings":"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"}