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

package/lib/ImageSource.d.ts

@@ -0,0 +1,288 @@
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import * as Bundle from "alchemy/Bundle/Bundle";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type * as Redacted from "effect/Redacted";
+import type * as rolldown from "rolldown";
+import { Docker, type RegistryCredentials } from "./Docker.ts";
+import { type InlineDockerfile } from "./Dockerfile.ts";
+/**
+ * INTERNAL — registry-agnostic container image-source machinery shared by
+ * the container platforms (`AWS.ECS.*`, `AWS.EKS.*` via ECR, and
+ * `Kubernetes.*` workloads pushing to any registry).
+ *
+ * NOT exported from any barrel. Consumers import the module path directly.
+ *
+ * A platform's props separate the ENVIRONMENT (what the container is) from
+ * the PROGRAM (`main` — "and run my bundled Effect program in it"):
+ *
+ * - environment (at most one): `image` (registry ref) | `context` +
+ *   `dockerfile`-as-path (docker build) | inline `dockerfile` content
+ *   (`Dockerfile.inline`) | the default bun base when `main` stands alone.
+ * - `main` present → the bundle is injected into the environment (COPY +
+ *   ENTRYPOINT) and pushed as a derived image. `main` absent → the
+ *   environment runs verbatim: `image` is mirrored (docker pull → tag →
+ *   push, content-addressed on the ref), a Dockerfile builds as-is.
+ *
+ * Where images land is an {@link ImageRegistryTarget}: ECR supplies one that
+ * auto-creates a private repository; a plain registry (a local `registry`
+ * container, GHCR, Docker Hub, …) supplies one that pushes to
+ * `<server>/<name>`.
+ */
+/**
+ * Bundle an Effect program into a generated image. Alchemy bundles `main`
+ * with rolldown and bakes it into a Dockerfile generated from the
+ * environment (`image`, `dockerfile`, or the default bun base).
+ */
+export interface BundledImageSource {
+    /**
+     * Module entrypoint for the bundled program. This should typically be
+     * `import.meta.url` from an inline Effect program.
+     */
+    main: string;
+    /**
+     * Environment image: used as the generated Dockerfile's `FROM`. Any
+     * registry ref works (private non-ECR registries require docker
+     * credentials on the build machine); the image must be able to run the
+     * bun runtime. Exclusive with {@link dockerfile} / {@link context}.
+     * @default "oven/bun:1"
+     */
+    image?: string;
+    /**
+     * Environment Dockerfile: a string is a PATH (built in {@link context},
+     * then the bundle is layered on top in a second stage); an
+     * {@link InlineDockerfile} is inline content used as the environment
+     * preamble (built with no context — its own `COPY`s are unsupported).
+     * The resulting environment must be able to run the bun runtime.
+     * Exclusive with {@link image}.
+     */
+    dockerfile?: string | InlineDockerfile;
+    /**
+     * Build context for a path {@link dockerfile} environment. Exclusive
+     * with {@link image} and inline dockerfiles.
+     */
+    context?: string;
+    /**
+     * Named export to load from `main`.
+     * @default "default"
+     */
+    handler?: string;
+    /**
+     * Bundler configuration for the entrypoint. Unused code is tree-shaken.
+     * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
+     * parts prune more aggressively. List extra packages with
+     * `pure.packages`, or disable with `pure: false`.
+     */
+    build?: Bundle.BundleConfig;
+}
+/**
+ * Build arguments and BuildKit secrets for an image built from the user's
+ * own Dockerfile (`context` / `dockerfile`).
+ */
+export interface DockerfileBuild {
+    /**
+     * Docker build arguments (`--build-arg`), read by `ARG` instructions.
+     * They are part of the image's content hash, so changing one rebuilds the
+     * image. Never pass secrets here: build args are visible in the image
+     * history. Use {@link secrets} instead.
+     */
+    args?: Record<string, string>;
+    /**
+     * BuildKit secrets, keyed by id. Mount one in a `RUN` step with
+     * `--mount=type=secret,id=<id>` and read it from `/run/secrets/<id>`, or
+     * add `env=<NAME>` to expose it as an environment variable for that step.
+     *
+     * A secret never enters the image, its build history, or `docker`'s argv.
+     * Secrets are left out of the image's content hash, so rotating one does
+     * not rebuild the image.
+     */
+    secrets?: Record<string, Redacted.Redacted<string>>;
+}
+/** The `build` prop of a source built from the user's own Dockerfile. */
+export interface DockerfileBuildOptions {
+    /** Build arguments and BuildKit secrets for the Dockerfile build. */
+    build?: DockerfileBuild;
+}
+/**
+ * Build the image from the user's own Dockerfile and build context — no
+ * Effect program is bundled.
+ */
+export interface DockerfileImageSource extends DockerfileBuildOptions {
+    /**
+     * Docker build context directory. Optional when {@link dockerfile} is
+     * inline content (which builds with an empty context).
+     */
+    context?: string;
+    /**
+     * Path to the Dockerfile relative to the cwd (NOT the context), or
+     * {@link InlineDockerfile} content. The Dockerfile must define its own
+     * `CMD`/`ENTRYPOINT` (no program is injected).
+     * @default `${context}/Dockerfile`
+     */
+    dockerfile?: string | InlineDockerfile;
+}
+/**
+ * Run a pre-built registry image. Registry-backed platforms may mirror it
+ * into their own registry (ECR: docker pull → tag → push).
+ */
+export interface RegistryImageSource {
+    /**
+     * A pre-built image reference, e.g.
+     * `public.ecr.aws/docker/library/busybox:stable`.
+     */
+    image: string;
+}
+/**
+ * The image-source union. Discriminated by presence: exactly one of
+ * `main`, `context`, or `image`.
+ */
+export type ImageSourceProps = BundledImageSource | DockerfileImageSource | RegistryImageSource;
+/** Loose bag shape used to sniff which source variant a props object is. */
+export interface ImageSourceLike {
+    main?: string;
+    handler?: string;
+    /** Bundler config for `main`; Docker build args and secrets for `context`. */
+    build?: Bundle.BundleConfig & DockerfileBuild;
+    context?: string;
+    dockerfile?: string | InlineDockerfile;
+    image?: string;
+}
+export type ImageSourceKind = "main" | "context" | "image";
+/**
+ * Which image source a props bag declares. `main` always wins (the other
+ * fields then describe its ENVIRONMENT); without `main`, `image` is the
+ * mirrored-verbatim source and any `context`/`dockerfile` (path or inline)
+ * is an external docker build.
+ */
+export declare const imageSourceKind: (source: ImageSourceLike) => ImageSourceKind | undefined;
+declare const DockerfileBuildConflict_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: "DockerfileBuildConflict";
+} & Readonly<A>;
+/**
+ * `build.args` or `build.secrets` set on an image that is not built from the
+ * user's own Dockerfile: a `main` program or a pre-built `image`.
+ */
+export declare class DockerfileBuildConflict extends DockerfileBuildConflict_base<{
+    readonly id: string;
+    readonly source: "main" | "image";
+}> {
+    get message(): string;
+}
+/**
+ * Dies with {@link DockerfileBuildConflict} when `build.args` or
+ * `build.secrets` are set alongside `main` or `image`.
+ */
+export declare const validateDockerfileBuild: (id: string, source: {
+    main?: string;
+    image?: string;
+    build?: DockerfileBuild;
+}) => Effect.Effect<void>;
+/**
+ * Validate environment-source exclusivity. Dies (plan-time defect) on
+ * `image`+`dockerfile`, `image`+`context`, inline-`dockerfile`+`context`, or
+ * build args/secrets without a Dockerfile build.
+ */
+export declare const validateImageSource: (id: string, source: ImageSourceLike) => Effect.Effect<void>;
+/**
+ * Where a resolved image is pushed. Each field is an Effect so a target can
+ * create resources lazily (ECR creates the repository on first use).
+ */
+export interface ImageRegistryTarget<R = never> {
+    /** The repository URI images are tagged into (`<repositoryUri>:<hash>`). */
+    readonly repositoryUri: Effect.Effect<string, any, R>;
+    /**
+     * Whether the content-addressed tag is already in the registry. `true`
+     * skips the build and push entirely.
+     */
+    readonly hasTag: (tag: string) => Effect.Effect<boolean, any, R>;
+    /**
+     * Push credentials. `undefined` pushes with the build machine's own
+     * Docker configuration (`docker login`, credential helpers).
+     */
+    readonly credentials: Effect.Effect<RegistryCredentials | undefined, any, R>;
+}
+export interface ResolveContainerImageOptions {
+    /** Logical resource id — keys the stable build-context directory. */
+    id: string;
+    /**
+     * The props bag carrying the image source fields (`main` / `context` /
+     * `image` plus their modifiers).
+     */
+    source: ImageSourceLike;
+    /**
+     * Target image platform.
+     * @default "linux/amd64"
+     */
+    platform?: string;
+    /**
+     * Port the generated Dockerfile should `ENV PORT=` + `EXPOSE`
+     * (`main` source only).
+     */
+    port?: number;
+    /**
+     * True when the resource was declared without an inline Effect impl —
+     * `main` is then bundled as-is without the virtual-entry bootstrap.
+     */
+    isExternal?: boolean;
+    /**
+     * The virtual-entry bootstrap wrapped around `main` for Effect-native
+     * programs: receives the resolved entry import path and returns the
+     * generated entry module source.
+     */
+    bootstrap: (importPath: string) => string;
+    /** Plan-status session used to emit build/push progress notes. */
+    session: {
+        note: (message: string) => Effect.Effect<void>;
+    };
+}
+/**
+ * Content hash for the sources whose identity is computable WITHOUT running
+ * a bundler:
+ *
+ * - `context` — hash of the build-context directory + Dockerfile content +
+ *   platform.
+ * - `image` — hash of the image reference + platform (re-mirror only when
+ *   the ref changes).
+ * - `main` — `undefined`: the hash comes from the bundle output, so it is
+ *   only known inside `resolve`.
+ *
+ * Providers use this in `diff` to surface content drift (files changed under
+ * an unchanged `context` path) as an update.
+ */
+export declare const computeStaticSourceHash: (source: ImageSourceLike, platform?: string | undefined) => Effect.Effect<string | undefined, import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Init-time constructor for the image-source resolver. Resolves the services
+ * that are only available at provider-layer construction (Docker, the
+ * `.alchemy` directory, the rolldown virtual-entry plugin) and returns
+ * `resolve` (build/mirror + push to an {@link ImageRegistryTarget}), `hash`,
+ * and `watchMain`.
+ */
+export declare const makeContainerImageSource: Effect.Effect<{
+    resolve: <R>(options: ResolveContainerImageOptions, target: ImageRegistryTarget<R>) => Effect.Effect<{
+        imageUri: string;
+        repositoryUri: string;
+        codeHash: string;
+    }, any, R | FileSystem.FileSystem | Path.Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage>;
+    hash: (options: {
+        source: ImageSourceLike;
+        platform?: string;
+        port?: number;
+        isExternal?: boolean;
+        bootstrap: (importPath: string) => string;
+    }) => Effect.Effect<string | undefined, Bundle.BundleError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+    watchMain: (options: {
+        source: BundledImageSource;
+        isExternal?: boolean;
+        bootstrap: (importPath: string) => string;
+    }) => Effect.Effect<{
+        inputOptions: rolldown.InputOptions;
+        outputOptions: rolldown.OutputOptions;
+        extra: Bundle.BundleConfig | undefined;
+    }, import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+}, never, AlchemyContext | Docker | Path.Path>;
+/** The resolver service returned by {@link makeContainerImageSource}. */
+export interface ContainerImageSource extends Effect.Success<typeof makeContainerImageSource> {
+}
+export {};
+//# sourceMappingURL=ImageSource.d.ts.map

package/lib/ImageSource.d.ts.map

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