@alchemy.run/fly 2.0.0-beta.85 → 2.0.0-beta.86

package/src/Sprite.ts

@@ -5,7 +5,7 @@ import * as Bundle from "alchemy/Bundle/Bundle";
 import { isResolved } from "alchemy/Diff";
 import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
 import * as Provider from "alchemy/Provider";
-import type { Resource, ResourceBinding } from "alchemy/Resource";
+import type { LookupMethod, Resource, ResourceBinding } from "alchemy/Resource";
 import type { ServerHost } from "alchemy/Runtime/Process";
 import { Stack } from "alchemy/Stack";
 import { createInternalTags } from "alchemy/Tags";
@@ -119,9 +119,19 @@ export type Sprite = Resource<
     };
   },
   SpriteBinding,
-  Providers
+  Providers,
+  SpriteLookup
 >;
 
+/**
+ * Props for {@link Sprite.lookup}: find a Sprite this stack doesn't
+ * manage by its name.
+ */
+export interface SpriteLookup {
+  /** Sprite name (unique per org). */
+  name: string;
+}
+
 export const isSprite = (value: unknown): value is Sprite =>
   typeof value === "object" && value !== null && (value as { Type?: string }).Type === "Fly.Sprite";
 
@@ -307,15 +317,24 @@ export type SpriteRuntimeContext = FlyHostRuntimeContext;
  * ) {}
  * ```
  *
+ * ### Looking up an existing Sprite
+ * `Sprite.lookup` references a Sprite Alchemy doesn't manage (created with
+ * `sprite create` or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted. `code.hash` is empty: the Sprite's
+ * program isn't Alchemy's.
+ *
+ * **Example:** Reference an existing Sprite
+ * ```typescript
+ * const box = Fly.Sprite.lookup({ name: "my-box" });
+ * ```
+ *
  * @resource
  * @product Sprite
  */
-export const Sprite: Platform<Sprite, SpriteServices, SpriteShape, SpriteRuntimeContext> = Platform(
-  "Fly.Sprite",
-  {
-    createRuntimeContext: createFlyHostRuntimeContext("Fly.Sprite"),
-  },
-);
+export const Sprite: Platform<Sprite, SpriteServices, SpriteShape, SpriteRuntimeContext> &
+  LookupMethod<Sprite> = Platform("Fly.Sprite", {
+  createRuntimeContext: createFlyHostRuntimeContext("Fly.Sprite"),
+});
 
 export class SpriteNotCreated extends Data.TaggedError("Fly.SpriteNotCreated")<{
   resourceName: string;
@@ -575,6 +594,13 @@ export const SpriteProvider = () =>
           return undefined;
         }),
 
+        lookup: Effect.fn(function* ({ name }) {
+          const found = yield* getByName(name).pipe(
+            Effect.catchTag("SpritesNotEnabled", () => Effect.undefined),
+          );
+          return found === undefined ? undefined : toAttrs(found, name, "");
+        }),
+
         read: Effect.fn(function* ({ id, olds, output }) {
           const name = yield* resolveSpriteName(id, olds?.name, output?.name);
           const found = yield* (

package/src/Volume.ts

@@ -116,6 +116,11 @@ export const createVolume = Effect.fn(function* (input: {
   disk: DiskSpec;
 }) {
   const sizeGb = Math.max(input.disk.sizeGb, MIN_SIZE_GB);
+  // The volumes this group held before the create: a storage host that fails
+  // with an unknown outcome may still have made one.
+  const before = new Set(
+    (yield* listVolumeGroup(input.appName, input.name, input.region)).map((volume) => volume.id),
+  );
   const created = yield* machines
     .createVolume({
       app_name: input.appName,
@@ -130,7 +135,26 @@ export const createVolume = Effect.fn(function* (input: {
       source_volume_id: input.disk.sourceVolumeId,
       require_unique_zone: input.disk.requireUniqueZone,
     })
-    .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
+    .pipe(
+      Effect.catchTags({
+        Conflict: () => Effect.undefined,
+        StorageHostCapacity: (error) =>
+          Effect.gen(function* () {
+            // Its outcome is unknown: a single new volume in the group is the
+            // one this call made. Otherwise create again after a pause.
+            yield* Effect.sleep(Duration.seconds(5));
+            const fresh = (yield* listVolumeGroup(input.appName, input.name, input.region)).filter(
+              (volume) => volume.id !== undefined && !before.has(volume.id),
+            );
+            return fresh.length === 1 ? fresh[0] : yield* error;
+          }),
+      }),
+      Effect.retry({
+        while: (error) => error._tag === "StorageHostCapacity",
+        schedule: Schedule.spaced(Duration.seconds(5)),
+        times: 6,
+      }),
+    );
   if (created?.id !== undefined && created.id.length > 0) {
     return (yield* waitUntilVolumeReady(input.appName, created.id)) ?? created;
   }

package/src/VolumeSnapshot.ts

@@ -56,9 +56,23 @@ export type VolumeSnapshot = Resource<
     createdAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  VolumeSnapshotLookup
 >;
 
+/**
+ * Props for {@link VolumeSnapshot.lookup}: find a snapshot this stack
+ * doesn't manage by its App, Volume and id.
+ */
+export interface VolumeSnapshotLookup {
+  /** Fly App name the Volume belongs to. */
+  appName: string;
+  /** Fly Volume id (`vol_…`). */
+  volumeId: string;
+  /** Fly snapshot id (`vs_…`). */
+  snapshotId: string;
+}
+
 /**
  * A Fly.VolumeSnapshot is an on-demand snapshot of a mounted disk.
  *
@@ -127,6 +141,25 @@ export type VolumeSnapshot = Resource<
  * ) {}
  * ```
  *
+ * ### Looking up an existing snapshot
+ * `VolumeSnapshot.lookup` references a snapshot Alchemy doesn't manage
+ * (taken by Fly's daily schedule or by another stack). It is read during
+ * plan/deploy and never created or deleted.
+ *
+ * **Example:** Restore a disk from an existing snapshot
+ * ```typescript
+ * const snapshot = Fly.VolumeSnapshot.lookup({
+ *   appName: "my-app",
+ *   volumeId: "vol_123",
+ *   snapshotId: "vs_456",
+ * });
+ * const disk = yield* Fly.MountVolume({
+ *   path: "/data",
+ *   sizeGb: 1,
+ *   snapshotId: snapshot.snapshotId,
+ * });
+ * ```
+ *
  * @resource
  * @product Volume
  */
@@ -235,6 +268,11 @@ export const VolumeSnapshotProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, volumeId, snapshotId }) {
+      const found = yield* findById(appName, volumeId, snapshotId);
+      return found === undefined ? undefined : toAttrs(appName, volumeId, found);
+    }),
+
     read: Effect.fn(function* ({ olds, output }) {
       const appName = output?.appName ?? appNameOf(olds?.app);
       const volumeId = output?.volumeId ?? volumeIdOf(olds?.volumeId);

package/src/bluegreen.ts

@@ -444,7 +444,10 @@ export const reconcileBlueGreen = Effect.fn(function* (
           .pipe(
             Retry.none,
             Effect.timeout("30 seconds"),
-            Effect.catchTag(["Conflict", "GatewayTimeout", "TimeoutError"], () => readback),
+            Effect.catchTag(
+              ["Conflict", "GatewayTimeout", "TimeoutError", "StorageHostCapacity"],
+              () => readback,
+            ),
             Effect.catchReason("HttpClientError", "TransportError", () => readback),
           );
       }

package/src/hosted.ts

@@ -9,9 +9,12 @@ import {
   type PackageInstall,
 } from "alchemy/Bundle/InstalledPackages";
 import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
+import { hashDirectory } from "alchemy/Command/Memo";
 import { safeHttpEffect } from "alchemy/Http";
+import * as Output from "alchemy/Output";
 import type { ResourceBinding } from "alchemy/Resource";
 import { createContainerRuntimeContext, type HostRuntimeContext } from "alchemy/Runtime/Process";
+import { packEnvValueKeepRedacted } from "alchemy/RuntimeContext";
 import {
   copyExtraFiles,
   contextRootOf,
@@ -30,6 +33,7 @@ import * as Path from "effect/Path";
 import * as Redacted from "effect/Redacted";
 import * as Schedule from "effect/Schedule";
 import type * as rolldown from "rolldown";
+import { flyHostBundle, flyOidcToken } from "./internal/Oidc.ts";
 import { buildOnRemoteBuilder } from "./internal/RemoteBuilder.ts";
 import type { BoundTarget, DiskSpec, ServiceBinding } from "./MountVolume.ts";
 import { rpcMethodsOf, serveFlyRpc } from "./rpc.ts";
@@ -59,7 +63,20 @@ export const createFlyHostRuntimeContext =
         boots ? { shape: { ...shape, fetch: shape?.fetch ?? wrapped } } : options,
       ) as Effect.Effect<void, never, any>;
     };
-    return Object.assign(base, { serve });
+    // Keep the `Redacted` wrapper outside the packed string so the Service
+    // reconcile can store those values as App secrets instead of Machine env.
+    const set: HostRuntimeContext["set"] = (bindingId, output) =>
+      Effect.sync(() => {
+        const key = bindingId.replaceAll(/[^a-zA-Z0-9]/g, "_");
+        base.env[key] = output.pipe(Output.map(packEnvValueKeepRedacted));
+        return key;
+      });
+    // A Service runs on Fly Machines, which mint OIDC tokens for their
+    // bindings to exchange with AWS and GCP (see `internal/Oidc.ts`).
+    return Object.assign(
+      base,
+      type === "Fly.Service" ? { serve, set, oidcToken: flyOidcToken } : { serve, set },
+    );
   };
 
 export const FLY_REGISTRY = "registry.fly.io";
@@ -189,10 +206,14 @@ export const collectBindingState = (bindings: readonly ResourceBinding<ServiceBi
   const active = bindings.filter(
     (binding: ResourceBinding<ServiceBinding> & { action?: string }) => binding.action !== "delete",
   );
-  const env = toEnvRecord(
-    active
-      .map((binding) => binding?.data?.env)
-      .reduce<Record<string, any>>((acc, value) => ({ ...acc, ...value }), {}),
+  const merged = active
+    .map((binding) => binding?.data?.env)
+    .reduce<Record<string, any>>((acc, value) => ({ ...acc, ...value }), {});
+  const env = toEnvRecord(merged);
+  // Names of bound `Config` values and Redacted outputs. Only the names:
+  // the values stay in `env` until the Service moves them into App secrets.
+  const secretNames = Object.keys(toEnvRecord(merged)).filter((key) =>
+    Redacted.isRedacted(merged[key]),
   );
   const mounts: DiskSpec[] = [];
   const seen = new Set<string>();
@@ -200,9 +221,12 @@ export const collectBindingState = (bindings: readonly ResourceBinding<ServiceBi
   const buckets: { name: string; id?: string; values?: Record<string, string> }[] = [];
   const postgres: { clusterId: string; variableName?: string }[] = [];
   const targets: BoundTarget[] = [];
+  const callers = new Set<string>();
   for (const binding of active) {
     const target = binding?.data?.target;
     if (target !== undefined) targets.push(target);
+    const caller = coerceBindingName(binding?.data?.caller?.appName);
+    if (caller !== undefined) callers.add(caller);
     for (const mount of binding?.data?.mounts ?? []) {
       if (seen.has(mount.path)) continue;
       seen.add(mount.path);
@@ -256,7 +280,16 @@ export const collectBindingState = (bindings: readonly ResourceBinding<ServiceBi
       });
     }
   }
-  return { env, mounts, redis, buckets, postgres, targets };
+  return {
+    env,
+    secretNames,
+    mounts,
+    redis,
+    buckets,
+    postgres,
+    targets,
+    callers: [...callers].sort(),
+  };
 };
 
 /**
@@ -377,7 +410,7 @@ export const createFlyHostedSupport = ({
       plugins?: rolldown.RolldownPluginOption,
     ) {
       return yield* Bundle.build(
-        {
+        flyHostBundle({
           ...props.build?.input,
           input: entry,
           cwd,
@@ -394,7 +427,7 @@ export const createFlyHostedSupport = ({
             ...props.build?.input?.resolve,
           },
           plugins: [props.build?.input?.plugins, plugins],
-        },
+        }),
         {
           ...props.build?.output,
           format: "esm",
@@ -539,10 +572,10 @@ export const createFlyHostedSupport = ({
         );
         const entryRel = posixRelUnder(root, realMain, path) ?? path.basename(realMain);
         const dest = path.join(contextDir, entryRel);
-        if (!(yield* fs.exists(dest).pipe(Effect.orElseSucceed(() => false)))) {
-          yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
-          yield* fs.copy(realMain, dest, { overwrite: true });
-        }
+        // The context directory is reused across deploys: always copy the
+        // entry, or a changed entry ships the previous deploy's copy.
+        yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
+        yield* fs.copy(realMain, dest, { overwrite: true });
       }
       return contextDir;
     });
@@ -583,7 +616,79 @@ export const createFlyHostedSupport = ({
     return codeHash;
   });
 
-  return { alchemyEnv, bundleProgram, computeCodeHash, resolveImage, hash };
+  /** A Docker build context's content hash: its image changes when any file in it does. */
+  const contextHash = Effect.fn(function* (context: string) {
+    return (yield* hashDirectory({ cwd: context })).slice(0, 16);
+  });
+
+  /**
+   * Build the image a `context` directory's `Dockerfile` describes, as it
+   * is, and push it to `registry.fly.io/{appName}:{logicalId}-{hash}`.
+   * When `previousHash` matches, skip build and push.
+   */
+  const resolveContextImage = Effect.fn(function* (input: {
+    id: string;
+    appName: string;
+    context: string;
+    remote: boolean | undefined;
+    previousHash?: string;
+    session?: { note: (message: string) => Effect.Effect<void> };
+  }) {
+    const note = input.session?.note ?? ((_message: string) => Effect.void);
+    const codeHash = yield* contextHash(input.context);
+    const imageRef = `${FLY_REGISTRY}/${input.appName}:${sanitizeImageRepo(input.id)}-${codeHash}`;
+    if (input.previousHash === codeHash) return { imageRef, codeHash };
+
+    const minted = yield* machines.createAppDeployToken({ app_name: input.appName });
+    const token =
+      minted.token === undefined || Redacted.isRedacted(minted.token)
+        ? minted.token
+        : Redacted.make(minted.token);
+    if (token === undefined || Redacted.value(token).length === 0) {
+      return yield* new DeployTokenMissing({ appName: input.appName });
+    }
+    const registry = { server: FLY_REGISTRY, username: "x", password: token };
+
+    if (input.remote !== false) {
+      yield* note(`Building ${imageRef} on a Fly remote builder...`);
+      yield* buildOnRemoteBuilder({
+        docker,
+        appName: input.appName,
+        contextDir: input.context,
+        imageRef,
+        platform: MACHINE_PLATFORM,
+        registry,
+        note,
+      });
+      yield* note(`Pushed ${imageRef}`);
+      return { imageRef, codeHash };
+    }
+
+    if (!(yield* imageExists(imageRef))) {
+      yield* note(`Building container image ${imageRef}...`);
+      yield* docker.image.build({
+        context: input.context,
+        tag: imageRef,
+        platform: MACHINE_PLATFORM,
+      });
+    }
+    yield* note(`Pushing ${imageRef}...`);
+    yield* docker.image
+      .push(imageRef, registry)
+      .pipe(Effect.retry({ times: 3, schedule: pushBackoff }));
+    yield* note(`Pushed ${imageRef}`);
+    return { imageRef, codeHash };
+  });
+
+  return {
+    alchemyEnv,
+    bundleProgram,
+    computeCodeHash,
+    resolveImage,
+    hash,
+    contextHash,
+    resolveContextImage,
+  };
 };
 
 /**

package/src/internal/Oidc.ts

@@ -0,0 +1,99 @@
+import * as http from "node:http";
+import { OidcTokenError } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type * as rolldown from "rolldown";
+
+/**
+ * Fly Machine OIDC tokens. Every Machine serves part of the Machines API on
+ * the `/.fly/api` socket, authenticated as that Machine, so a process can
+ * mint a token without holding one. A token is signed by
+ * `https://oidc.fly.io/<org>`, lives 10 minutes, and names its caller as
+ * `sub = <org>:<app>:<machine>`. AWS and GCP trust it through an OIDC
+ * provider, so a Fly host reaches them without a key Alchemy created.
+ *
+ * See https://fly.io/docs/security/openid-connect/.
+ */
+
+/** The socket a Machine serves its Machines API on. */
+const FLY_API_SOCKET = "/.fly/api";
+
+/** Fly's OIDC issuer for an organization. */
+export const flyOidcIssuer = (orgSlug: string) => `https://oidc.fly.io/${orgSlug}`;
+
+/**
+ * Bundle options for a Fly Service: defines `__ALCHEMY_HOST_IDENTITY__` as
+ * `"Fly.OIDC"` so bindings keep only the code that exchanges the Machine's
+ * OIDC token, and drop the created-key path.
+ */
+export const flyHostBundle = (input: rolldown.InputOptions): rolldown.InputOptions => ({
+  ...input,
+  transform: {
+    ...input.transform,
+    define: {
+      ...input.transform?.define,
+      "globalThis.__ALCHEMY_HOST_IDENTITY__": JSON.stringify("Fly.OIDC"),
+    },
+  },
+});
+
+/** Mint an OIDC token for `audience` from the Machine's `/.fly/api` socket. */
+export const flyOidcToken = (
+  audience: string,
+): Effect.Effect<Redacted.Redacted<string>, OidcTokenError> =>
+  Effect.callback<Redacted.Redacted<string>, OidcTokenError>((resume) => {
+    const body = JSON.stringify({ aud: audience });
+    const request = http.request(
+      {
+        socketPath: FLY_API_SOCKET,
+        path: "/v1/tokens/oidc",
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(body),
+        },
+      },
+      (response) => {
+        let text = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk: string) => {
+          text += chunk;
+        });
+        response.on("end", () => {
+          if (response.statusCode === 200 && text.trim().length > 0) {
+            resume(Effect.succeed(Redacted.make(text.trim())));
+          } else {
+            resume(
+              Effect.fail(
+                new OidcTokenError({
+                  message: `${FLY_API_SOCKET} returned HTTP ${response.statusCode} for an OIDC token: ${text.slice(0, 200)}`,
+                }),
+              ),
+            );
+          }
+        });
+        response.on("error", (cause) =>
+          resume(
+            Effect.fail(
+              new OidcTokenError({
+                message: `Reading the OIDC token from ${FLY_API_SOCKET}`,
+                cause,
+              }),
+            ),
+          ),
+        );
+      },
+    );
+    request.on("error", (cause) =>
+      resume(
+        Effect.fail(
+          new OidcTokenError({
+            message: `Cannot reach ${FLY_API_SOCKET} for an OIDC token. It is served only on Fly Machines, to root.`,
+            cause,
+          }),
+        ),
+      ),
+    );
+    request.end(body);
+    return Effect.sync(() => request.destroy());
+  });

package/src/leases.ts

@@ -17,6 +17,7 @@ import * as FetchHttpClient from "effect/http/FetchHttpClient";
 import * as HttpClient from "effect/http/HttpClient";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import * as Option from "effect/Option";
+import * as Random from "effect/Random";
 import * as Schedule from "effect/Schedule";
 
 const TTL_SECONDS = 120;
@@ -37,14 +38,20 @@ const retrySchedule = <E>(): Schedule.Schedule<Duration.Duration, E> =>
       ),
     ),
     Schedule.addDelay<Duration.Duration, E>(() =>
-      Effect.sync(() => Duration.millis(Math.random() * 50)),
+      Effect.map(Random.next, (random) => Duration.millis(random * 50)),
     ),
   );
 
 export class MachineLeaseBusy extends Data.TaggedError("Fly.MachineLeaseBusy")<{
   appName: string;
   machineId: string;
-}> {}
+  /** Fly's conflict message: the lease holder and its expiry. */
+  reason?: string;
+}> {
+  get message() {
+    return `Machine lease for ${this.appName}/${this.machineId} is held by another operation${this.reason ? `: ${this.reason}` : ""}`;
+  }
+}
 
 export class MachineLeaseLost extends Data.TaggedError("Fly.MachineLeaseLost")<{
   appName: string;
@@ -71,6 +78,9 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
   const scope = yield* Effect.scope;
   const held = new Map<string, HeldLease>();
   const deleting = new Set<string>();
+  // Machines this lease set deleted; a later snapshot of the same operation
+  // must not wait for them to accept a lease.
+  const removed = new Set<string>();
   const renewals = new Set<Fiber.Fiber<void, never>>();
   const uncertain = new Set<string>();
   const lost = yield* Deferred.make<never, MachineLeaseLost>();
@@ -131,8 +141,10 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
                     while: (error) => error._tag === "Conflict" || error._tag === "TooManyRequests",
                   }),
                   Effect.timeout("30 seconds"),
-                  Effect.catchTag("Conflict", () =>
-                    Effect.fail(new MachineLeaseBusy({ appName, machineId })),
+                  Effect.catchTag("Conflict", (error) =>
+                    Effect.fail(
+                      new MachineLeaseBusy({ appName, machineId, reason: error.message }),
+                    ),
                   ),
                   Effect.catchTag(["HttpClientError", "GatewayTimeout", "TimeoutError"], (error) =>
                     lose(machineId, `acquisition uncertain: ${error._tag}`),
@@ -274,7 +286,10 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
         Effect.asVoid,
         Effect.catch((error) =>
           Effect.gen(function* () {
-            if (error._tag === "NotFound") return yield* forget(machineId);
+            if (error._tag === "NotFound") {
+              removed.add(machineId);
+              return yield* forget(machineId);
+            }
             if (
               error._tag === "Fly.MachineMutationUncertain" ||
               error._tag === "InternalServerError" ||
@@ -282,12 +297,16 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
               error._tag === "ServiceUnavailable"
             ) {
               // Keep renewal aware of the removal until its exact target has been observed.
-              if (yield* confirmRemoved(machineId)) return;
+              if (yield* confirmRemoved(machineId)) {
+                removed.add(machineId);
+                return;
+              }
             }
             return yield* Effect.fail(error);
           }),
         ),
       );
+      removed.add(machineId);
       yield* forget(machineId);
     }).pipe(
       Effect.ensuring(
@@ -360,7 +379,14 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
       Effect.retry({
         times: 8,
         schedule: retrySchedule<machines.CreateMachineLeaseError | MachineLeaseLost>(),
-        while: (error) => error._tag === "TooManyRequests",
+        // A renewal re-sends the nonce we hold, so replaying it after a
+        // transient 5xx extends the same lease instead of taking a new one.
+        while: (error) =>
+          error._tag === "TooManyRequests" ||
+          error._tag === "InternalServerError" ||
+          error._tag === "BadGateway" ||
+          error._tag === "ServiceUnavailable" ||
+          error._tag === "GatewayTimeout",
       }),
       Effect.timeout("75 seconds"),
       Effect.catch((error) =>
@@ -407,6 +433,7 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
     Effect.forkScoped,
   );
   const checkTarget = (machineId: string) => nonce(machineId).pipe(Effect.asVoid);
+  const wasRemoved = (machineId: string) => removed.has(machineId);
   return {
     acquire,
     check,
@@ -416,6 +443,7 @@ export const makeMachineLeases = Effect.fn(function* (appName: string) {
     remove,
     forget,
     nonceIfHeld,
+    wasRemoved,
   };
 });