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

package/src/Machine.ts

@@ -33,6 +33,7 @@ import type { Providers } from "./Providers.ts";
 import {
   deleteReplicaSet,
   listReplicaSets,
+  lookupReplicaSet,
   observeReplicaSet,
   reconcileReplicas,
   resolveCount,
@@ -379,9 +380,25 @@ export type Machine = Resource<
     replicas: Replica[];
   },
   ServiceBinding,
-  Providers
+  Providers,
+  MachineLookup
 >;
 
+/**
+ * Props for {@link Machine.lookup}: find Machines this stack doesn't
+ * manage by their App and name.
+ */
+export interface MachineLookup {
+  /** Fly App name the Machines run in. */
+  appName: string;
+  /**
+   * Machine name (unique per App). Replicas named `{name}-{N}` are
+   * found with it, as are the replicas of an Alchemy Machine whose base
+   * name it is.
+   */
+  name: string;
+}
+
 /**
  * A Fly.Machine is a Firecracker VM running one image or a named container group.
  *
@@ -838,6 +855,17 @@ export type Machine = Resource<
  * discovers unfinished owned generations.
  * See the [deployment guide](/fly/compute/deployments) for recovery and limits.
  *
+ * ### Looking up existing Machines
+ * `Machine.lookup` references Machines Alchemy doesn't manage (started with
+ * `fly machine run` or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted.
+ *
+ * **Example:** Reference an existing Machine
+ * ```typescript
+ * const worker = Fly.Machine.lookup({ appName: "my-app", name: "worker" });
+ * const address = worker.privateIp;
+ * ```
+ *
  * @resource
  * @product Machine
  */
@@ -1154,6 +1182,11 @@ export const MachineProvider = () =>
       return output.rolloutPending ? { action: "update" as const } : undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, name }) {
+      const found = yield* lookupReplicaSet({ appName, name });
+      return found === undefined ? undefined : toAttrs(found);
+    }),
+
     read: Effect.fn(function* ({ id, fqn, instanceId, olds, output }) {
       const appName = appNameOf(olds?.app) ?? output?.appName;
       const name = yield* resolveMachineName(id, olds?.name, output?.baseName ?? output?.name);

package/src/MountVolume.ts

@@ -116,6 +116,11 @@ export interface ServiceBinding {
    * published.
    */
   target?: BoundTarget;
+  /**
+   * A Service that calls this one, recorded on the target by
+   * `Fly.bindService`. Only the Apps recorded here may call its methods.
+   */
+  caller?: { appName: string };
 }
 
 /** A Service bound by `Fly.bindService` or `Fly.bindEndpoint`. */
@@ -128,8 +133,6 @@ export interface BoundTarget {
   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`. */

package/src/Postgres.ts

@@ -93,6 +93,13 @@ export interface PostgresProps {
    * is reachable on the org private network; deploy-time apply needs a
    * route to that network (a WireGuard peer, `fly mpg proxy`, or a
    * machine already on 6PN).
+   *
+   * History is forward-only and linear. A new file must sort after every
+   * applied one, or the deploy fails with `NonLinearMigrationHistoryError`;
+   * an edited or deleted applied file fails with
+   * `RewrittenMigrationHistoryError`. Renaming an applied file without
+   * changing its contents keeps it applied. See
+   * [Migrations](https://alchemy.run/sql/effect-sql/migrations#change-migration-history-safely).
    */
   migrations?: MigrationsInput;
   /**
@@ -143,9 +150,24 @@ export type Postgres = Resource<
     importHashes: Record<string, string>;
   },
   never,
-  Providers
+  Providers,
+  PostgresLookup
 >;
 
+/**
+ * Props for {@link Postgres.lookup}: find a Managed Postgres cluster
+ * this stack doesn't manage by its name.
+ */
+export interface PostgresLookup {
+  /** Cluster name (unique in the org). */
+  name: string;
+  /**
+   * Organization slug.
+   * @default the current token's org
+   */
+  orgSlug?: string;
+}
+
 /**
  * A Fly.Postgres is a Managed Postgres (MPG) cluster. It is billed.
  * Do not wrap unmanaged `fly postgres`.
@@ -280,6 +302,18 @@ export type Postgres = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing cluster
+ * `Postgres.lookup` references a cluster Alchemy doesn't manage (created
+ * with `fly mpg create` or by another stack). It is read during
+ * plan/deploy, never created, updated or deleted, and its connection URIs
+ * come from Fly like a declared cluster's.
+ *
+ * **Example:** Connect to an existing cluster
+ * ```typescript
+ * const db = Fly.Postgres.lookup({ name: "my-db" });
+ * const sql = yield* Fly.ConnectPostgres(db);
+ * ```
+ *
  * @resource
  * @product Postgres
  */
@@ -602,6 +636,14 @@ export const PostgresProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ name, orgSlug }) {
+      const org = orgSlug ?? (yield* resolveOrgSlug());
+      const found = yield* findByName(org, name);
+      if (found === undefined) return undefined;
+      const hydrated = found.id !== undefined ? yield* getClusterResponse(found.id) : undefined;
+      return toAttrs(hydrated?.data ?? found, { name, orgSlug: org }, hydrated?.credentials);
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const found =
         output?.clusterId !== undefined && output.clusterId.length > 0

package/src/Redis.ts

@@ -31,6 +31,10 @@ export {
   CommandError as RedisCommandError,
   UrlMissing as RedisUrlMissing,
 } from "@alchemy.run/redis/Errors";
+// Clients' runtime effects require redis's `RuntimeContext` twin, so it shows
+// up in users' inferred types. Exporting it here lets TypeScript name it
+// through this package without users depending on @alchemy.run/redis.
+export type { RuntimeContext as RedisRuntimeContext } from "@alchemy.run/redis/RuntimeContext";
 
 export interface RedisProps {
   /**
@@ -108,9 +112,19 @@ export type Redis = Resource<
     url: Redacted.Redacted<string> | undefined;
   },
   never,
-  Providers
+  Providers,
+  RedisLookup
 >;
 
+/**
+ * Props for {@link Redis.lookup}: find an Upstash Redis this stack
+ * doesn't manage by its name.
+ */
+export interface RedisLookup {
+  /** Upstash Redis name. */
+  name: string;
+}
+
 /**
  * Managed Upstash Redis in a Fly org. Bind {@link ReadRedis},
  * {@link WriteRedis}, or {@link ReadWriteRedis} on a {@link Service}.
@@ -219,6 +233,17 @@ export type Redis = Resource<
  * need a specific size.
  * :::
  *
+ * ### Looking up an existing Redis
+ * `Redis.lookup` references a Redis Alchemy doesn't manage (created with
+ * `fly redis create` or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted. Bind it like a declared Redis.
+ *
+ * **Example:** Read an existing Redis
+ * ```typescript
+ * const cache = Fly.Redis.lookup({ name: "my-cache" });
+ * const redis = yield* Fly.ReadRedis(cache);
+ * ```
+ *
  * @resource
  * @product Redis
  */
@@ -654,6 +679,23 @@ export const RedisProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ name }) {
+      const found = yield* findRedisAddOn({ name });
+      if (found === undefined) return undefined;
+      let url = unwrapSensitive(found.publicUrl);
+      if ((url === undefined || url.length === 0) && found.id !== undefined) {
+        const detail = yield* addons
+          .addOn({ id: found.id })
+          .pipe(Effect.catchTag("FlyIoParseError", () => Effect.undefined));
+        url = unwrapSensitive(detail?.publicUrl);
+      }
+      return toAttrs(found, {
+        name,
+        primaryRegion: DEFAULT_REDIS_REGION,
+        url: url === undefined || url.length === 0 ? undefined : Redacted.make(url),
+      });
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const name = yield* resolveName(id, olds?.name, output?.name);
       const found =

package/src/Secret.ts

@@ -54,9 +54,21 @@ export type Secret = Resource<
     updatedAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  SecretLookup
 >;
 
+/**
+ * Props for {@link Secret.lookup}: find a secret this stack doesn't
+ * manage by its App and name.
+ */
+export interface SecretLookup {
+  /** Fly App name the secret belongs to. */
+  appName: string;
+  /** Secret name (case-sensitive). */
+  name: string;
+}
+
 const resolveSecretProps = (
   props: SecretProps | Effect.Effect<SecretProps, never, Providers>,
 ): Effect.Effect<SecretProps, never, Providers> =>
@@ -196,6 +208,17 @@ const SecretResource = Resource<Secret>("Fly.Secret");
  * );
  * ```
  *
+ * ### Looking up an existing secret
+ * `Secret.lookup` references a secret Alchemy doesn't manage (set with
+ * `fly secrets set` or by another stack). It is read during plan/deploy,
+ * never set or unset. Its value is never read; `digest` changes when the
+ * value does.
+ *
+ * **Example:** Reference an existing secret
+ * ```typescript
+ * const token = Fly.Secret.lookup({ appName: "my-site", name: "API_TOKEN" });
+ * ```
+ *
  * @resource
  * @product Secret
  */
@@ -295,6 +318,11 @@ export const SecretProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, name }) {
+      const found = yield* getByName(appName, name);
+      return found === undefined ? undefined : toAttrs(appName, found, name);
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const appName = output?.appName ?? (olds !== undefined ? appNameOf(olds.app) : undefined);
       if (appName === undefined) return undefined;

package/src/SecretKey.ts

@@ -64,9 +64,21 @@ export type SecretKey = Resource<
     updatedAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  SecretKeyLookup
 >;
 
+/**
+ * Props for {@link SecretKey.lookup}: find a secret key this stack
+ * doesn't manage by its App and name.
+ */
+export interface SecretKeyLookup {
+  /** Fly App name the key belongs to. */
+  appName: string;
+  /** Secret key name. */
+  name: string;
+}
+
 const resolveSecretKeyProps = (
   props: SecretKeyProps | Effect.Effect<SecretKeyProps, never, Providers>,
 ): Effect.Effect<SecretKeyProps, never, Providers> =>
@@ -173,6 +185,17 @@ const SecretKeyResource = Resource<SecretKey>("Fly.SecretKey");
  * const { valid } = yield* verify({ plaintext, signature });
  * ```
  *
+ * ### Looking up an existing key
+ * `SecretKey.lookup` references a key Alchemy doesn't manage (created with
+ * `fly secrets keys` or by another stack). It is read during plan/deploy,
+ * never generated or deleted. Bind it like a declared key.
+ *
+ * **Example:** Verify with an existing key
+ * ```typescript
+ * const Signing = Fly.SecretKey.lookup({ appName: "my-site", name: "signing" });
+ * const verify = yield* Fly.Verify(Signing);
+ * ```
+ *
  * @resource
  * @product Secret Key
  */
@@ -285,6 +308,11 @@ export const SecretKeyProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, name }) {
+      const found = yield* getByName(appName, name);
+      return found === undefined ? undefined : toAttrs(appName, found, name);
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const appName = output?.appName ?? (olds !== undefined ? appNameOf(olds.app) : undefined);
       if (appName === undefined) return undefined;