alchemy 2.0.0-beta.59 → 2.0.0-beta.60

package/src/Docker/RemoteImage.ts

@@ -0,0 +1,215 @@
+import * as Effect from "effect/Effect";
+import { isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { Docker } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+import {
+  type ImageRegistry,
+  parseCreatedAt,
+  parseRepoDigest,
+  repositoryFromImageRef,
+  withRegistryHost,
+} from "./Registry.ts";
+
+export interface RemoteImageProps {
+  /** Docker image name to pull, without tag. */
+  name: string;
+  /** Docker image tag to pull. @default "latest" */
+  tag?: string;
+  /** Pull for this platform. */
+  platform?: string;
+  /**
+   * Pull even when an image with the same reference already exists locally.
+   *
+   * @default true
+   */
+  alwaysPull?: boolean;
+  /**
+   * Re-tag the pulled image under this repository/name. When omitted the pulled
+   * `name` is kept.
+   */
+  targetName?: string;
+  /**
+   * Tag applied to the re-tagged image.
+   *
+   * @default The pulled `tag`.
+   */
+  targetTag?: string;
+  /** Registry credentials. When set, the (re-tagged) image is pushed. */
+  registry?: ImageRegistry;
+  /**
+   * Skip registry push even when `registry` is set.
+   *
+   * @default false
+   */
+  skipPush?: boolean;
+}
+
+export interface RemoteImage extends Resource<
+  "Docker.RemoteImage",
+  RemoteImageProps,
+  {
+    /** Final image reference. Includes the registry host when pushed there. */
+    imageRef: string;
+    /** Local image id after pull. */
+    imageId: string;
+    /** Pull timestamp in milliseconds since epoch. */
+    createdAt: number;
+    /** Final image repository/name. */
+    name: string;
+    /** Final image tag. */
+    tag: string;
+    /** Registry digest after push when available. */
+    repoDigest?: string;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * Pulls a remote Docker image through the active Docker context, optionally
+ * re-tagging it and pushing it to a registry.
+ *
+ * The image is available to other Docker resources by `imageRef`. Use
+ * `alwaysPull: false` when you want to reuse an existing tag in the configured
+ * Docker daemon instead of pulling on every deploy. Set `targetName`/`targetTag`
+ * to re-tag the pulled image, and `registry` to push it (mirroring it from a
+ * source registry into your own, for example).
+ *
+ * @resource
+ *
+ * @section Pulling Images
+ * @example Pull nginx
+ * ```typescript
+ * const nginx = yield* Docker.RemoteImage("nginx", {
+ *   name: "nginx",
+ *   tag: "alpine",
+ * });
+ * ```
+ *
+ * @example Reuse an existing daemon tag
+ * ```typescript
+ * const postgres = yield* Docker.RemoteImage("postgres", {
+ *   name: "postgres",
+ *   tag: "18-alpine",
+ *   alwaysPull: false,
+ * });
+ * ```
+ *
+ * @section Re-tagging and Pushing
+ * @example Mirror a public image into your registry
+ * ```typescript
+ * const mirrored = yield* Docker.RemoteImage("nginx-mirror", {
+ *   name: "nginx",
+ *   tag: "alpine",
+ *   targetName: "acme/nginx",
+ *   targetTag: "alpine",
+ *   registry: {
+ *     server: "ghcr.io",
+ *     username: "octocat",
+ *     password: Config.redacted("GITHUB_TOKEN"),
+ *   },
+ * });
+ * ```
+ */
+export const RemoteImage = Resource<RemoteImage>("Docker.RemoteImage");
+
+export const RemoteImageProvider = () =>
+  Provider.effect(
+    RemoteImage,
+    Effect.gen(function* () {
+      const docker = yield* Docker;
+
+      return RemoteImage.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds, output }) {
+          const ref = output?.imageRef ?? targetImageRef(olds);
+          return yield* docker.image.inspect(ref).pipe(
+            Effect.map((image) => ({
+              imageRef: ref,
+              imageId: image.Id,
+              createdAt: output?.createdAt ?? parseCreatedAt(image.Created),
+              name: output?.name ?? repositoryFromImageRef(ref),
+              tag: output?.tag ?? targetTag(olds),
+              repoDigest: output?.repoDigest,
+            })),
+            Effect.catchReason(
+              "PlatformError",
+              "NotFound",
+              () => Effect.undefined,
+            ),
+          );
+        }),
+        diff: Effect.fn(function* ({ output, news }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            !output ||
+            news.alwaysPull !== false ||
+            output.imageRef !== targetImageRef(news)
+          ) {
+            return { action: "update" };
+          }
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const sourceRef = remoteImageRef(news);
+          yield* session.note(`Pulling Docker image: ${sourceRef}`);
+          yield* docker.image.pull(sourceRef, news.platform);
+
+          const finalRef = targetImageRef(news);
+          if (finalRef !== sourceRef) {
+            yield* session.note(
+              `Tagging Docker image: ${sourceRef} -> ${finalRef}`,
+            );
+            yield* docker.image.tag(sourceRef, finalRef);
+          }
+
+          let repoDigest: string | undefined;
+          if (news.registry && !news.skipPush) {
+            yield* session.note(
+              `Pushing image to registry "${news.registry.server}"`,
+            );
+            repoDigest = yield* docker.image
+              .push(finalRef, news.registry)
+              .pipe(
+                Effect.map((result) =>
+                  parseRepoDigest(finalRef, result.stdout),
+                ),
+              );
+          }
+
+          const inspected = yield* docker.image.inspect(finalRef);
+          return {
+            imageRef: finalRef,
+            imageId: inspected.Id,
+            createdAt: parseCreatedAt(inspected.Created),
+            name: repositoryFromImageRef(finalRef),
+            tag: targetTag(news),
+            repoDigest,
+          };
+        }),
+        delete: Effect.fn(function* () {
+          // Remote images are not removed on destroy because tags may be shared by
+          // unrelated local stacks or developer workflows.
+        }),
+      });
+    }),
+  );
+
+/** The reference the image is pulled from. */
+const remoteImageRef = (props: RemoteImageProps): string =>
+  `${props.name}:${props.tag ?? "latest"}`;
+
+const targetTag = (props: RemoteImageProps): string =>
+  props.targetTag ?? props.tag ?? "latest";
+
+/**
+ * The final reference after re-tagging and registry-host prefixing. Equals the
+ * pulled reference when no re-tag/registry is configured.
+ */
+const targetImageRef = (props: RemoteImageProps): string => {
+  const local = `${props.targetName ?? props.name}:${targetTag(props)}`;
+  return props.registry && !props.skipPush
+    ? withRegistryHost(local, props.registry)
+    : local;
+};

package/src/Docker/Volume.ts

@@ -0,0 +1,187 @@
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import { Unowned } from "../AdoptPolicy.ts";
+import { isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import {
+  createInternalTags,
+  hasAlchemyTags,
+  stripInternalTags,
+} from "../Tags.ts";
+import { Docker, dockerPhysicalName } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface VolumeLabel {
+  /** Label name. */
+  name: string;
+  /** Label value. */
+  value: string;
+}
+
+export interface VolumeProps {
+  /**
+   * Docker volume name.
+   *
+   * @default Generated from stack, stage, logical id, and instance id.
+   */
+  name?: string;
+  /** Volume driver. @default "local" */
+  driver?: string;
+  /** Driver-specific options. */
+  driverOpts?: Record<string, string>;
+  /** Custom metadata labels. */
+  labels?: Record<string, string>;
+}
+
+export interface Volume extends Resource<
+  "Docker.Volume",
+  VolumeProps,
+  {
+    /** Docker volume name. */
+    id: string;
+    /** Docker volume name. */
+    name: string;
+    /** Volume driver. */
+    driver: string;
+    /** Driver-specific options reported by Docker. */
+    driverOpts: Record<string, string>;
+    /** Labels reported by Docker. */
+    labels: Record<string, string>;
+    /** Host mountpoint path. */
+    mountpoint?: string;
+    /** Creation timestamp in milliseconds since epoch. */
+    createdAt: number;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A Docker volume managed through the active Docker context.
+ *
+ * Pre-existing same-name volumes are treated as foreign until the engine is
+ * allowed to adopt them with `--adopt` or `adopt(true)`.
+ *
+ * @resource
+ *
+ * @section Creating Volumes
+ * @example Basic volume
+ * ```typescript
+ * const data = yield* Docker.Volume("data", {
+ *   name: "app-data",
+ * });
+ * ```
+ *
+ * @example PostgreSQL data volume
+ * ```typescript
+ * const data = yield* Docker.Volume("postgres-data");
+ * ```
+ *
+ * @example Driver options and labels
+ * ```typescript
+ * const data = yield* Docker.Volume("db-data", {
+ *   driver: "local",
+ *   driverOpts: {
+ *     type: "nfs",
+ *     o: "addr=10.0.0.1,rw",
+ *     device: ":/path/to/dir",
+ *   },
+ *   labels: {
+ *     "com.example.usage": "database",
+ *   },
+ * });
+ * ```
+ */
+export const Volume = Resource<Volume>("Docker.Volume");
+
+export const VolumeProvider = () =>
+  Provider.effect(
+    Volume,
+    Effect.gen(function* () {
+      const docker = yield* Docker;
+
+      return Volume.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+          const name = yield* dockerPhysicalName(id, olds, instanceId);
+          const info = yield* docker.volume
+            .inspect(name)
+            .pipe(
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.undefined,
+              ),
+            );
+          if (!info) return undefined;
+          const attrs = toVolumeAttributes(info);
+          if (output) return attrs;
+          // Without prior state, only adopt a volume that carries our branding;
+          // anything else is foreign and gated behind `--adopt`.
+          const owned = yield* hasAlchemyTags(id, info.Labels ?? undefined);
+          return owned ? attrs : Unowned(attrs);
+        }),
+        diff: Effect.fn(function* ({ id, instanceId, output, news }) {
+          if (!isResolved(news)) return undefined;
+          const args = yield* makeVolumeArgs(id, news, instanceId);
+          if (
+            output?.name !== args.name ||
+            output?.driver !== args.driver ||
+            !Equal.equals(output?.driverOpts ?? {}, args.opt ?? {}) ||
+            // Compare only user labels; internal `alchemy::*` branding lives on
+            // the observed volume but must not drive replacement.
+            !Equal.equals(stripInternalTags(output?.labels), args.label ?? {})
+          ) {
+            return { action: "replace" as const, deleteFirst: true };
+          }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news }) {
+          const args = yield* makeVolumeArgs(id, news, instanceId);
+          const internalTags = yield* createInternalTags(id);
+          const result = yield* docker.volume.create({
+            ...args,
+            label: { ...internalTags, ...args.label },
+          });
+          return toVolumeAttributes(
+            yield* docker.volume.inspect(result.stdout),
+          );
+        }),
+        delete: Effect.fn(({ output }) =>
+          docker.volume
+            .remove(output.name)
+            .pipe(
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.void,
+              ),
+            ),
+        ),
+      });
+    }),
+  );
+
+const makeVolumeArgs = (id: string, props: VolumeProps, instanceId: string) =>
+  dockerPhysicalName(id, props, instanceId).pipe(
+    Effect.map(
+      (name): Parameters<Docker["Service"]["volume"]["create"]>[0] => ({
+        name,
+        driver: props.driver ?? "local",
+        opt: props.driverOpts,
+        label: props.labels,
+      }),
+    ),
+  );
+
+export const toVolumeAttributes = (
+  info: Docker.Volume,
+): Volume["Attributes"] => ({
+  id: info.Name,
+  name: info.Name,
+  driver: info.Driver,
+  driverOpts: info.Options ?? {},
+  labels: info.Labels ?? {},
+  mountpoint: info.Mountpoint,
+  createdAt: Date.parse(info.CreatedAt) || Date.now(),
+});

package/src/Docker/index.ts

@@ -0,0 +1,8 @@
+export * from "./Container.ts";
+export * from "./Docker.ts";
+export * from "./Image.ts";
+export * from "./Network.ts";
+export * from "./Providers.ts";
+export type { ImageRegistry } from "./Registry.ts";
+export * from "./RemoteImage.ts";
+export * from "./Volume.ts";

package/src/Local/ProviderLayer.ts

@@ -1,3 +1,5 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+
 import * as Layer from "effect/Layer";
 import { AlchemyContext } from "../AlchemyContext.ts";
 

package/src/Neon/Branch.ts

@@ -135,6 +135,11 @@ export type Branch = Resource<
      * when fronting Neon with another pooler like Hyperdrive.
      */
     origin: PostgresOrigin;
+    /**
+     * Parsed pooled connection components. Useful as a Hyperdrive `dev`
+     * origin when local workers bypass Hyperdrive and connect directly.
+     */
+    pooledOrigin: PostgresOrigin;
     migrationsDir: string | undefined;
     migrationsTable: string | undefined;
     migrationsHashes: Record<string, string>;
@@ -270,6 +275,9 @@ export const BranchProvider = () =>
             protected: branch.protected,
             default: branch.default,
             expiresAt: branch.expires_at,
+            pooledOrigin:
+              output.pooledOrigin ??
+              parsePostgresOrigin(output.pooledConnectionUri),
           })),
           Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
         );
@@ -311,6 +319,7 @@ export const BranchProvider = () =>
         connectionUri: conn.uri,
         pooledConnectionUri: conn.pooled,
         origin: parsePostgresOrigin(conn.uri),
+        pooledOrigin: parsePostgresOrigin(conn.pooled),
         migrationsDir: olds?.migrationsDir,
         migrationsTable: olds?.migrationsTable,
         migrationsHashes: {},
@@ -349,6 +358,9 @@ export const BranchProvider = () =>
               connectionUri: output.connectionUri,
               pooledConnectionUri: output.pooledConnectionUri,
               origin: output.origin,
+              pooledOrigin:
+                output.pooledOrigin ??
+                parsePostgresOrigin(output.pooledConnectionUri),
             })),
           )
         : yield* Effect.gen(function* () {
@@ -403,6 +415,7 @@ export const BranchProvider = () =>
               connectionUri: conn.uri,
               pooledConnectionUri: conn.pooled,
               origin: parsePostgresOrigin(conn.uri),
+              pooledOrigin: parsePostgresOrigin(conn.pooled),
             };
           });
 
@@ -542,6 +555,7 @@ const hydrateBranch = (
       connectionUri: conn.uri,
       pooledConnectionUri: conn.pooled,
       origin: parsePostgresOrigin(conn.uri),
+      pooledOrigin: parsePostgresOrigin(conn.pooled),
       migrationsDir: undefined,
       migrationsTable: undefined,
       migrationsHashes: {},
@@ -578,7 +592,7 @@ const findBranchByName = (projectId: string, name: string) =>
   });
 
 const maybeResolveProjectId = (source: BranchSource): string | undefined => {
-  if ("projectId" in source && source.projectId) {
+  if (source && "projectId" in source && source.projectId) {
     return source.projectId as unknown as string;
   }
   return undefined;

package/src/Neon/Project.ts

@@ -147,6 +147,11 @@ export type Project = Resource<
      * when fronting Neon with another pooler like Hyperdrive.
      */
     origin: PostgresOrigin;
+    /**
+     * Parsed pooled connection components. Useful as a Hyperdrive `dev`
+     * origin when local workers bypass Hyperdrive and connect directly.
+     */
+    pooledOrigin: PostgresOrigin;
     historyRetentionSeconds: number;
     enableLogicalReplication: boolean;
     migrationsDir: string | undefined;
@@ -283,6 +288,9 @@ export const ProjectProvider = () =>
           Effect.map(({ project }) => ({
             ...output,
             projectName: project.name,
+            pooledOrigin:
+              output.pooledOrigin ??
+              parsePostgresOrigin(output.pooledConnectionUri),
             historyRetentionSeconds: project.history_retention_seconds,
             enableLogicalReplication:
               project.settings?.enable_logical_replication === true,
@@ -332,6 +340,9 @@ export const ProjectProvider = () =>
               connectionUri: output.connectionUri,
               pooledConnectionUri: output.pooledConnectionUri,
               origin: output.origin,
+              pooledOrigin:
+                output.pooledOrigin ??
+                parsePostgresOrigin(output.pooledConnectionUri),
               historyRetentionSeconds:
                 r.project.history_retention_seconds ??
                 output.historyRetentionSeconds,
@@ -381,6 +392,7 @@ export const ProjectProvider = () =>
               connectionUri: conn.uri,
               pooledConnectionUri: conn.pooled,
               origin: parsePostgresOrigin(conn.uri),
+              pooledOrigin: parsePostgresOrigin(conn.pooled),
               historyRetentionSeconds:
                 created.project.history_retention_seconds ?? 86400,
               enableLogicalReplication:
@@ -664,6 +676,7 @@ const hydrateProjectAttributes = (
       connectionUri: conn.uri,
       pooledConnectionUri: conn.pooled,
       origin: parsePostgresOrigin(conn.uri),
+      pooledOrigin: parsePostgresOrigin(conn.pooled),
       historyRetentionSeconds: project.history_retention_seconds ?? 86400,
       enableLogicalReplication:
         project.settings?.enable_logical_replication === true,

package/src/Plan.ts

@@ -1,3 +1,5 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+/** @effect-diagnostics missingEffectError:off */
 import * as Config from "effect/Config";
 import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
@@ -55,8 +57,8 @@ import {
   type UpdatedResourceState,
   type UpdatingReourceState,
 } from "./State/index.ts";
-import { hashInput } from "./Util/sha256.ts";
 import { findCycleMembers } from "./Util/scc.ts";
+import { hashInput } from "./Util/sha256.ts";
 
 export type PlanError = never;
 

package/src/Planetscale/Branch.ts

@@ -14,6 +14,7 @@ import { ensureMySQLProductionBranchClusterSize } from "./MySQL/MySQLClusterSize
 import {
   ensurePostgresProductionBranchClusterSize,
   toPostgresClusterSku,
+  waitForPendingPostgresChanges,
 } from "./Postgres/PostgresClusterSize.ts";
 import {
   DEFAULT_MIGRATIONS_TABLE,
@@ -105,6 +106,16 @@ export interface BaseBranchAttributes {
   migrationsHashes: Record<string, string>;
   /** Content hashes for the last applied import files. */
   importHashes: Record<string, string>;
+  /**
+   * Desired total replica count requested by the resource input, when known.
+   * PlanetScale's branch read API exposes only boolean HA state, so this is
+   * persisted from Alchemy state rather than observed from live provider data.
+   */
+  desiredReplicas: number | undefined;
+  /** Whether the branch currently has HA replicas. */
+  hasReplicas: boolean | undefined;
+  /** Whether the branch currently has read-only replicas. */
+  hasReadOnlyReplicas: boolean | undefined;
 }
 
 // Runtime-resolved Database/Branch references. `news.database` can be a
@@ -230,6 +241,9 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
                           migrationsTable: undefined,
                           migrationsHashes: {},
                           importHashes: {},
+                          desiredReplicas: undefined,
+                          hasReplicas: branch.has_replicas,
+                          hasReadOnlyReplicas: branch.has_read_only_replicas,
                         }) satisfies BaseBranchAttributes,
                     ),
                 ),
@@ -273,6 +287,20 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
         return { action: "replace" } as const;
       }
 
+      if (news.replicas !== undefined) {
+        if (output?.desiredReplicas !== news.replicas) {
+          return { action: "update" } as const;
+        }
+
+        const desiredHasReplicas = news.replicas > 0;
+        if (
+          output?.hasReplicas !== undefined &&
+          output.hasReplicas !== desiredHasReplicas
+        ) {
+          return { action: "update" } as const;
+        }
+      }
+
       if (news.migrationsDir) {
         const newHashes = yield* hashMigrations(news.migrationsDir);
         if (!recordsEqual(newHashes, output?.migrationsHashes ?? {})) {
@@ -336,6 +364,12 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
               migrationsTable: output?.migrationsTable ?? olds?.migrationsTable,
               migrationsHashes: output?.migrationsHashes ?? {},
               importHashes: output?.importHashes ?? {},
+              desiredReplicas:
+                output?.desiredReplicas ??
+                olds?.desiredReplicas ??
+                olds?.replicas,
+              hasReplicas: data.has_replicas,
+              hasReadOnlyReplicas: data.has_read_only_replicas,
             } satisfies BaseBranchAttributes;
 
             return output ? attrs : Unowned(attrs);
@@ -493,6 +527,39 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
         }
       }
 
+      if (opts.expectedKind === "postgresql" && news.replicas !== undefined) {
+        const desiredReplicas = news.replicas;
+        const desiredHasReplicas = desiredReplicas > 0;
+        const shouldApplyReplicaChange =
+          current.has_replicas !== desiredHasReplicas ||
+          (desiredHasReplicas && output?.desiredReplicas !== desiredReplicas);
+
+        if (shouldApplyReplicaChange) {
+          yield* waitForPendingPostgresChanges(
+            organization,
+            databaseName,
+            branchName,
+          );
+          const change = yield* planetscale.updateBranchChangeRequest({
+            organization,
+            database: databaseName,
+            branch: branchName,
+            replicas: desiredReplicas,
+          });
+          yield* waitForPendingPostgresChanges(
+            organization,
+            databaseName,
+            branchName,
+            change.id,
+          );
+          current = yield* planetscale.getBranch({
+            organization,
+            database: databaseName,
+            branch: branchName,
+          });
+        }
+      }
+
       // Sync clusterSize — only meaningful on production branches.
       if (news.clusterSize) {
         if (current.kind === "postgresql") {
@@ -559,6 +626,9 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
         migrationsTable: news.migrationsDir ? migrationsTable : undefined,
         migrationsHashes,
         importHashes,
+        desiredReplicas: news.replicas ?? output?.desiredReplicas,
+        hasReplicas: updated.has_replicas,
+        hasReadOnlyReplicas: updated.has_read_only_replicas,
       } satisfies BaseBranchAttributes;
     }),
 

package/src/Planetscale/Postgres/PostgresBranch.ts

@@ -28,6 +28,12 @@ export interface PostgresBranchProps extends BaseBranchProps {
    */
   clusterSize?: PostgresClusterSize;
 
+  /**
+   * Total number of replicas for the branch. `0` creates or converges the
+   * branch to non-HA/single-node; `2+` enables HA.
+   */
+  replicas?: number;
+
   /**
    * Parent branch — either a string name or another {@link PostgresBranch}.
    * @default "main"