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

package/src/MachineContainers.ts

@@ -0,0 +1,152 @@
+import type { FlyContainerConfig, FlyMachineConfig } from "@distilled.cloud/fly-io/machines";
+import { deepEqual } from "alchemy/Diff";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import type { MachineContainer, MachineProps } from "./Machine.ts";
+
+export class InvalidMachineContainers extends Data.TaggedError("Fly.InvalidMachineContainers")<{
+  message: string;
+}> {}
+
+/** Validate resolved inputs before any Machine or Volume is changed. */
+export const validateMachineContainers = (
+  props: Pick<MachineProps, "image" | "containers" | "init">,
+) => {
+  const image = "image" in props ? props.image : undefined;
+  const containers = "containers" in props ? props.containers : undefined;
+  if ((image !== undefined) === (containers !== undefined))
+    return Effect.fail(
+      new InvalidMachineContainers({
+        message: "Fly.Machine requires exactly one of image or containers.",
+      }),
+    );
+  if (image !== undefined)
+    return typeof image === "string" && image.trim().length > 0
+      ? Effect.void
+      : Effect.fail(new InvalidMachineContainers({ message: "image must be nonempty." }));
+  if (!Array.isArray(containers) || containers.length === 0)
+    return Effect.fail(
+      new InvalidMachineContainers({
+        message: "containers must be a nonempty array.",
+      }),
+    );
+  if (props.init !== undefined)
+    return Effect.fail(
+      new InvalidMachineContainers({
+        message: "init is only supported with image.",
+      }),
+    );
+  const names = new Set<string>();
+  for (const container of containers) {
+    if (
+      container == null ||
+      typeof container.name !== "string" ||
+      !container.name.trim() ||
+      typeof container.image !== "string" ||
+      !container.image.trim()
+    )
+      return Effect.fail(
+        new InvalidMachineContainers({
+          message: "Every container needs a nonempty name and image.",
+        }),
+      );
+    if ("exec" in container && container.exec !== undefined)
+      return Effect.fail(
+        new InvalidMachineContainers({
+          message: `Container ${container.name}: use cmd and entrypoint; native container exec overrides are not supported.`,
+        }),
+      );
+    if (names.has(container.name))
+      return Effect.fail(
+        new InvalidMachineContainers({
+          message: `Duplicate container name: ${container.name}.`,
+        }),
+      );
+    names.add(container.name);
+  }
+  for (const container of containers)
+    for (const dependency of container.dependsOn ?? [])
+      if (dependency == null || typeof dependency.name !== "string" || !names.has(dependency.name))
+        return Effect.fail(
+          new InvalidMachineContainers({
+            message: `Container ${container.name} depends on an undeclared container.`,
+          }),
+        );
+  return Effect.void;
+};
+
+export const toFlyContainers = (containers: MachineContainer[]): FlyContainerConfig[] =>
+  containers.map((container) => ({
+    name: container.name,
+    image: container.image,
+    cmd: container.cmd,
+    entrypoint: container.entrypoint,
+    env: container.env,
+    depends_on: container.dependsOn?.map(({ name, condition }) => ({
+      name,
+      condition,
+    })),
+    healthchecks: container.healthChecks?.map((check) => ({
+      name: check.name,
+      kind: check.kind,
+      interval: check.interval,
+      timeout: check.timeout,
+      grace_period: check.gracePeriod,
+      success_threshold: check.successThreshold,
+      failure_threshold: check.failureThreshold,
+      http: check.http && {
+        port: check.http.port,
+        path: check.http.path,
+        method: check.http.method,
+        scheme: check.http.scheme,
+        headers: check.http.headers,
+        tls_server_name: check.http.tlsServerName,
+        tls_skip_verify: check.http.tlsSkipVerify,
+      },
+      tcp: check.tcp,
+      exec: check.exec,
+    })),
+  }));
+
+/** Canonical semantic config shared by drift detection and generation identity. */
+export const canonicalContainers = (containers: FlyContainerConfig[] | undefined) =>
+  (containers ?? [])
+    .map((container) => ({
+      name: container.name,
+      image: container.image,
+      cmd: container.cmd,
+      entrypoint: container.entrypoint,
+      env: Object.fromEntries(
+        Object.entries(container.env ?? {}).filter(([, value]) => value !== undefined),
+      ),
+      depends_on: [...(container.depends_on ?? [])]
+        .map(({ name, condition }) => ({ name, condition }))
+        .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? "")),
+      healthchecks: (container.healthchecks ?? []).map((check) => ({
+        name: check.name,
+        kind: check.kind,
+        interval: check.interval,
+        timeout: check.timeout,
+        grace_period: check.grace_period,
+        success_threshold: check.success_threshold,
+        failure_threshold: check.failure_threshold,
+        http: check.http,
+        tcp: check.tcp,
+        exec: check.exec,
+      })),
+    }))
+    .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+
+export const sameContainers = (
+  observed: FlyContainerConfig[] | undefined,
+  desired: FlyContainerConfig[] | undefined,
+) =>
+  deepEqual(canonicalContainers(observed), canonicalContainers(desired), {
+    stripNullish: true,
+  });
+
+/** Fly may synthesize a top-level image from the first container on readback. */
+export const sameContainerWorkload = (
+  observed: FlyMachineConfig | undefined,
+  desired: FlyContainerConfig[],
+) => sameContainers(observed?.containers, desired);

package/src/Metadata.ts

@@ -0,0 +1,195 @@
+import { createPhysicalName } from "alchemy/PhysicalName";
+import { createInternalTags, diffTags, hasTags, type Tags } from "alchemy/Tags";
+import * as Effect from "effect/Effect";
+
+/**
+ * Fly App has no labels. Ownership is stamped onto Machine
+ * `config.metadata` (and encoded into Volume/Secret names) as
+ * `alchemy.stack` / `alchemy.stage` / `alchemy.id`.
+ *
+ * Names here are Fly-prefixed so `export *` from this module does not
+ * collide with Hetzner Labels or `alchemy/src/Ref.ts`.
+ */
+export const ALCHEMY_METADATA_PREFIX = "alchemy.";
+
+export const alchemyMetadataKeys = {
+  stack: "alchemy.stack",
+  stage: "alchemy.stage",
+  id: "alchemy.id",
+  type: "alchemy.type",
+  replica: "alchemy.replica",
+  instance: "alchemy.instance",
+  fqn: "alchemy.fqn",
+  baseName: "alchemy.base-name",
+  generation: "alchemy.generation",
+  workload: "alchemy.workload",
+  sequence: "alchemy.sequence",
+  count: "alchemy.count",
+  image: "alchemy.image",
+  containerImageSet: "alchemy.container-image-set",
+  phase: "alchemy.phase",
+  protocol: "alchemy.deployment-protocol",
+  roles: "alchemy.readiness-roles",
+  role: "alchemy.readiness-role",
+  predecessors: "alchemy.predecessors",
+  restored: "alchemy.idle-policy-restored",
+  checkedInstance: "alchemy.checked-instance",
+  secretsVersion: "alchemy.min-secrets-version",
+} as const;
+
+export type FlyAlchemyType = "Fly.Machine" | "Fly.Service";
+
+const TAG_PREFIX = "alchemy::";
+
+export const toMetadataKey = (tagKey: string): string =>
+  tagKey.startsWith(TAG_PREFIX)
+    ? `${ALCHEMY_METADATA_PREFIX}${tagKey.slice(TAG_PREFIX.length)}`
+    : tagKey;
+
+export const toTagKeyFromMetadata = (metadataKey: string): string =>
+  metadataKey.startsWith(ALCHEMY_METADATA_PREFIX)
+    ? `${TAG_PREFIX}${metadataKey.slice(ALCHEMY_METADATA_PREFIX.length)}`
+    : metadataKey;
+
+export const toMachineMetadata = (
+  tags: Record<string, string> | null | undefined,
+): Record<string, string> =>
+  Object.fromEntries(Object.entries(tags ?? {}).map(([key, value]) => [toMetadataKey(key), value]));
+
+export const fromMachineMetadata = (
+  metadata: Record<string, string> | null | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(metadata ?? {}).map(([key, value]) => [toTagKeyFromMetadata(key), value]),
+  );
+
+export const createInternalMetadata = Effect.fn(function* (id: string) {
+  return toMachineMetadata(yield* createInternalTags(id));
+});
+
+/**
+ * Stamp alchemy ownership plus `alchemy.type` onto Machine config.metadata.
+ */
+export const createMachineMetadata = Effect.fn(function* (id: string, type: FlyAlchemyType) {
+  return {
+    ...(yield* createInternalMetadata(id)),
+    [alchemyMetadataKeys.type]: type,
+  };
+});
+
+export const stripInternalMetadata = (
+  metadata: Record<string, string> | null | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(metadata ?? {}).filter(([key]) => !key.startsWith(ALCHEMY_METADATA_PREFIX)),
+  );
+
+export const hasAlchemyMetadata = Effect.fn(function* (id: string, metadata: Tags | undefined) {
+  const expected = yield* createInternalMetadata(id);
+  return hasTags(expected, metadata);
+});
+
+/** True when observed Machine metadata was stamped by Alchemy. */
+export const isAlchemyOwnedMetadata = (
+  metadata: Record<string, string | undefined> | null | undefined,
+): boolean => {
+  const stack = metadata?.[alchemyMetadataKeys.stack];
+  return stack !== undefined && stack.length > 0;
+};
+
+/**
+ * Diff observed Machine metadata against desired. Always pass **observed**
+ * cloud metadata as `oldMetadata` — never `olds.metadata` or
+ * `output.metadata` — so adoption converges.
+ */
+export const diffMachineMetadata = diffTags;
+
+/**
+ * Fly App names: `createPhysicalName({ lowercase: true, maxLength: 30 })`,
+ * then force a leading letter (`f` prefix if needed). Globally unique.
+ */
+export const createFlyAppName = Effect.fn(function* (id: string) {
+  const raw = yield* createPhysicalName({
+    id,
+    lowercase: true,
+    maxLength: 30,
+  });
+  return /^[a-z]/.test(raw) ? raw : `f${raw}`.slice(0, 30);
+});
+
+/**
+ * Volume / Secret / SecretKey physical names use the same shape as App
+ * names so `list()` can recognize alchemy-owned rows without labels.
+ *
+ * Fly Volume names reject hyphens (`[a-z0-9_]`, max 30). Use
+ * {@link createFlyVolumeName} for Volumes.
+ */
+export const createFlyResourceName = createFlyAppName;
+
+/**
+ * Fly Volume names: same physical-name shape as App, but underscore
+ * delimited. Fly rejects hyphens (`[a-z0-9_]`, max 30).
+ */
+export const createFlyVolumeName = Effect.fn(function* (id: string) {
+  const raw = yield* createPhysicalName({
+    id,
+    lowercase: true,
+    maxLength: 30,
+    delimiter: "_",
+  });
+  // createPhysicalName keeps hyphens in the stack/stage prefix; Fly
+  // Volume names only allow [a-z0-9_].
+  return sanitizeFlyVolumeName(raw);
+});
+
+/**
+ * Sanitize a user-supplied Fly App / Volume / Secret name: lowercase,
+ * DNS-compatible (`[a-z0-9-]`), force a leading letter, max 30 chars.
+ */
+export const sanitizeFlyAppName = (name: string): string => {
+  const lowered = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const clipped = lowered.length > 30 ? lowered.slice(0, 30).replace(/-+$/g, "") : lowered;
+  const raw = clipped.length === 0 ? "f" : clipped;
+  return /^[a-z]/.test(raw) ? raw : `f${raw}`.slice(0, 30);
+};
+
+/**
+ * Sanitize a user-supplied Fly Volume name: lowercase alphanumeric and
+ * underscores only, force a leading letter, max 30 chars.
+ */
+export const sanitizeFlyVolumeName = (name: string): string => {
+  const lowered = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  const clipped = lowered.length > 30 ? lowered.slice(0, 30).replace(/_+$/g, "") : lowered;
+  const raw = clipped.length === 0 ? "f" : clipped;
+  return /^[a-z]/.test(raw) ? raw : `f${raw}`.slice(0, 30);
+};
+
+/**
+ * True when `name` matches the `createPhysicalName` + leading-letter shape
+ * used for alchemy-owned Fly Apps / Volumes / Secrets / SecretKeys.
+ *
+ * Untruncated names end with a hyphen (App) or underscore (Volume) plus
+ * an 8–16 char RFC4648 base32 instance suffix. Truncated 30-char names
+ * keep that suffix (the human prefix is what gets cut).
+ */
+export const matchesAlchemyPhysicalName = (name: string | undefined): boolean => {
+  if (name === undefined || name.length === 0 || name.length > 30) {
+    return false;
+  }
+  if (!/^[a-z][a-z0-9_-]*$/.test(name)) return false;
+  const parts = name.split(/[-_]/);
+  const last = parts.at(-1) ?? "";
+  if (parts.length >= 2 && last.length >= 8 && last.length <= 16 && /^[a-z2-7]+$/.test(last)) {
+    return true;
+  }
+  const compact = name.replaceAll("-", "").replaceAll("_", "");
+  return name.length === 30 && /[a-z2-7]{16}$/.test(compact);
+};

package/src/MountVolume.ts

@@ -0,0 +1,315 @@
+import * as Binding from "alchemy/Binding";
+import type { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+/**
+ * Spec for a per-replica Fly disk. Fly Volumes cannot be shared —
+ * `count` Machines get `count` Volumes in one name-group.
+ */
+export interface DiskSpec {
+  /**
+   * Absolute path inside the Machine the disk is mounted at
+   * (e.g. `/data`).
+   */
+  path: string;
+  /**
+   * Size in GB. Fly minimum is 1. Increasing size updates in place
+   * via `extendVolume`. Fly cannot shrink a Volume.
+   */
+  sizeGb: number;
+  /**
+   * Encrypt the Volume at rest. Create-only.
+   */
+  encrypted?: boolean;
+  /**
+   * Filesystem type (`ext4`, …). Create-only.
+   */
+  fstype?: string;
+  /**
+   * Enable scheduled automatic snapshots.
+   *
+   * @default true
+   */
+  autoBackupEnabled?: boolean;
+  /**
+   * Snapshot retention in days. Updated in place via `updateVolume`.
+   */
+  snapshotRetention?: number;
+  /**
+   * Restore from an existing snapshot. Create-only.
+   */
+  snapshotId?: string;
+  /**
+   * Fork from an existing volume. Create-only.
+   */
+  sourceVolumeId?: string;
+  /**
+   * Require the Volume to land in a unique zone. Create-only.
+   */
+  requireUniqueZone?: boolean;
+  /**
+   * Fly volume-group name. If omitted, a unique name is generated
+   * from the host's logical ID and {@link path}.
+   */
+  name?: string;
+}
+
+export interface MountVolumeOptions extends DiskSpec {}
+
+/**
+ * Runtime view of a disk mounted into a {@link Service}: the path
+ * inside the Machine.
+ */
+export interface MountedVolume {
+  /** Mount path inside the Machine (same value as {@link DiskSpec.path}). */
+  path: string;
+}
+
+/**
+ * Observed disk attached to a Machine / Service replica.
+ */
+export interface MountedDisk {
+  /** Mount path inside the Machine. */
+  path: string;
+  /** Fly Volume id. */
+  volumeId: string;
+  /** Size in GB. */
+  sizeGb: number;
+  /** Fly volume-group name. */
+  name: string;
+}
+
+const isBindHost = (value: unknown): value is Resource<string, any, any, ServiceBinding> =>
+  typeof value === "object" &&
+  value !== null &&
+  ((value as { Type?: string }).Type === "Fly.Service" ||
+    (value as { Type?: string }).Type === "Fly.Machine");
+
+/**
+ * Binding contract accepted by {@link Service} (and Machine) for mounted
+ * disks and injected env.
+ */
+export interface ServiceBinding {
+  env?: Record<string, any>;
+  mounts?: DiskSpec[];
+  /**
+   * Upstash Redis add-on to attach. Redis HTTP bindings write
+   * `REDIS_URL` as an App secret during Service reconcile.
+   */
+  redis?: { name: string; id?: string };
+  /**
+   * Tigris bucket to attach. Object HTTP bindings write `AWS_*` /
+   * `BUCKET_NAME` as App secrets during Service reconcile.
+   */
+  bucket?: { name: string; id?: string };
+  /**
+   * Managed Postgres cluster to attach. `Fly.ConnectPostgres` records
+   * the MPG attachment during Service reconcile. Connection URIs travel
+   * as Outputs (`yield* postgres.connectionUri`), not bind env.
+   */
+  postgres?: { clusterId: string; variableName?: string };
+  /**
+   * Another Service this one calls, recorded by `Fly.bindService` and
+   * `Fly.bindEndpoint`. Service reconcile checks the target is reachable
+   * from this Service's network and, for an endpoint, that the port is
+   * published.
+   */
+  target?: BoundTarget;
+}
+
+/** A Service bound by `Fly.bindService` or `Fly.bindEndpoint`. */
+export interface BoundTarget {
+  /** Logical id of the bound Service. */
+  service: string;
+  /** Fly App the bound Service runs in. */
+  appName: string;
+  /** Private network of that App. `undefined` for the default network. */
+  network: string | undefined;
+  /** The bound Service's private address; `undefined` when it publishes nothing. */
+  privateUrl: string | undefined;
+  /** The bound Service's caller token. */
+  rpcToken?: import("effect/Redacted").Redacted<string>;
+  /** Port `Fly.bindEndpoint` targets; the binding port for `bindService`. */
+  port?: number;
+  /** Ports the bound Service publishes, for `Fly.bindEndpoint`. */
+  endpoints?: Array<{ port: number; handlers: string[] }>;
+}
+
+/**
+ * Create a per-replica Fly Volume and mount it into a {@link Service}.
+ *
+ * There is no standalone Volume resource. From a {@link Machine}, pass
+ * `mounts: [{ path, sizeGb }]` instead.
+ *
+ *
+ * ### Mount into a Service
+ * Yield `MountVolume` inside init. App and region come from the
+ * parent Service. Provide {@link MountVolumeLive}. At runtime you get
+ * `disk.path`.
+ *
+ * A Volume attaches to one Machine. `count: 3` creates three Volumes
+ * in one name-group, one per replica.
+ *
+ * **Example:** Bind a path
+ * ```typescript
+ * export default class Api extends Fly.Service<Api>()(
+ *   "Api",
+ *   { app: Site, main: import.meta.url, region: "iad", count: 3, port: 3000 },
+ *   Effect.gen(function* () {
+ *     const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
+ *     const fs = yield* FileSystem.FileSystem;
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const text = yield* fs.readFileString(`${disk.path}/hello.txt`);
+ *         return HttpServerResponse.text(text);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Fly.MountVolumeLive)),
+ * ) {}
+ * ```
+ *
+ * ### Grow a disk
+ * `sizeGb` can grow in place via `extendVolume`. Fly cannot shrink a
+ * Volume. Minimum size is 1 GB.
+ *
+ * **Example:** 10 GB
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 10 });
+ * ```
+ *
+ * ### Encryption
+ * `encrypted` encrypts the Volume at rest.
+ *
+ * **Example:** Encrypted
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   encrypted: true,
+ * });
+ * ```
+ *
+ * :::note[Create-only]
+ * Flipping `encrypted` later is ignored.
+ * :::
+ *
+ * ### Filesystem
+ * `fstype` is the filesystem (`ext4`, …).
+ *
+ * **Example:** ext4
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   fstype: "ext4",
+ * });
+ * ```
+ *
+ * :::note[Create-only]
+ * Flipping `fstype` later is ignored.
+ * :::
+ *
+ * ### Scheduled snapshots
+ * Scheduled snapshots default on (`autoBackupEnabled`).
+ * `snapshotRetention` is days and updates in place. An on-demand
+ * snapshot is {@link VolumeSnapshot}.
+ *
+ * **Example:** Retention
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   autoBackupEnabled: true,
+ *   snapshotRetention: 5,
+ * });
+ * ```
+ *
+ * ### Restore from a snapshot
+ * `snapshotId` restores into a new disk.
+ *
+ * **Example:** snapshotId
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   snapshotId: Nightly.snapshotId,
+ * });
+ * ```
+ *
+ * :::note[Create-only]
+ * Changing `snapshotId` later is ignored.
+ * :::
+ *
+ * ### Fork a volume
+ * `sourceVolumeId` forks from an existing Volume.
+ *
+ * **Example:** sourceVolumeId
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   sourceVolumeId: box.mounts[0].volumeId,
+ * });
+ * ```
+ *
+ * :::note[Create-only]
+ * Changing `sourceVolumeId` later is ignored.
+ * :::
+ *
+ * ### Unique zone
+ * `requireUniqueZone` asks Fly to land the Volume in a unique zone.
+ *
+ * **Example:** Unique zone
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   requireUniqueZone: true,
+ * });
+ * ```
+ *
+ * :::note[Create-only]
+ * Flipping `requireUniqueZone` later is ignored.
+ * :::
+ *
+ * ### Volume name
+ * `name` is the Fly volume-group name. If omitted, a unique name is
+ * generated from the host's logical ID and `path`.
+ *
+ * **Example:** Named group
+ * ```typescript
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   name: "api_data",
+ * });
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface MountVolume extends Binding.Service<
+  MountVolume,
+  "Fly.MountVolume",
+  (options: MountVolumeOptions) => Effect.Effect<MountedVolume>
+> {}
+
+export const MountVolume = Binding.Service<MountVolume>("Fly.MountVolume");
+
+export const MountVolumeLive = Layer.effect(
+  MountVolume,
+  Effect.succeed(
+    Effect.fn(function* (options: MountVolumeOptions) {
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        const host = yield* Binding.Host;
+        if (isBindHost(host)) {
+          yield* host.bind`Fly.MountVolume(${options.path})`({
+            mounts: [options],
+          });
+        }
+      }
+      return { path: options.path };
+    }),
+  ),
+);