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

package/src/DeploymentState.ts

@@ -0,0 +1,104 @@
+import type { FlyMachineConfig } from "@distilled.cloud/fly-io/machines";
+import { pinsFromConfig, sameImageSet, validObservedImageSet } from "./DeploymentImages.ts";
+import { alchemyMetadataKeys as keys } from "./Metadata.ts";
+
+type DeploymentState = { protocol: "legacy" | "1" | "2" } | { protocol: "invalid"; reason: string };
+
+/** Observation and reconciliation must agree before treating a Machine as legacy. */
+export const classifyDeploymentState = (machine: {
+  config?: FlyMachineConfig;
+}): DeploymentState => {
+  const metadata = machine.config?.metadata;
+  const protocol = metadata?.[keys.protocol];
+  if (protocol !== undefined && protocol !== "1" && protocol !== "2")
+    return {
+      protocol: "invalid",
+      reason: `Unknown deployment protocol ${protocol}.`,
+    };
+  if (protocol !== "2" && metadata?.[keys.containerImageSet] !== undefined)
+    return {
+      protocol: "invalid",
+      reason: "Container image metadata requires deployment protocol 2.",
+    };
+  if (protocol === "2")
+    return validProtocol2RecoveryMetadata(machine)
+      ? { protocol }
+      : {
+          protocol: "invalid",
+          reason: "Invalid protocol-2 image set or recovery metadata.",
+        };
+  if (protocol === "1") {
+    const replica = metadata?.[keys.replica] ?? "";
+    if (
+      !/^(0|[1-9]\d*)$/.test(replica) ||
+      !Number.isSafeInteger(Number(replica)) ||
+      !["candidate", "promoting", "validating", "active", "retiring"].includes(
+        metadata?.[keys.phase] ?? "",
+      )
+    )
+      return {
+        protocol: "invalid",
+        reason: "Invalid protocol-1 replica index or deployment phase.",
+      };
+    return { protocol };
+  }
+  return { protocol: "legacy" };
+};
+
+/** Required recovery fields for a complete protocol-2 generation member. */
+const validProtocol2RecoveryMetadata = (machine: { config?: FlyMachineConfig }): boolean => {
+  if (!validObservedImageSet(machine)) return false;
+  const recorded = machine.config?.metadata;
+  const countText = recorded?.[keys.count] ?? "";
+  const sequenceText = recorded?.[keys.sequence] ?? "";
+  const replicaText = recorded?.[keys.replica] ?? "";
+  const count = Number(countText);
+  const index = Number(replicaText);
+  const roles = (recorded?.[keys.roles] ?? "").split(",");
+  return (
+    Boolean(recorded?.[keys.generation]?.trim()) &&
+    Boolean(recorded?.[keys.workload]?.trim()) &&
+    /^[1-9]\d*$/.test(countText) &&
+    Number.isSafeInteger(count) &&
+    /^[1-9]\d*$/.test(sequenceText) &&
+    Number.isSafeInteger(Number(sequenceText)) &&
+    /^(0|[1-9]\d*)$/.test(replicaText) &&
+    Number.isSafeInteger(index) &&
+    index < count &&
+    roles.length === count &&
+    roles.includes("run") &&
+    roles.every((role) => role === "run" || role === "idle") &&
+    recorded?.[keys.role] === roles[index] &&
+    ["candidate", "promoting", "validating", "active", "retiring"].includes(
+      recorded?.[keys.phase] ?? "",
+    ) &&
+    ["true", "false"].includes(recorded?.[keys.restored] ?? "")
+  );
+};
+
+/** A partial protocol-2 generation is valid only when every member agrees on its identity. */
+export const validProtocol2Generation = (
+  group: readonly { config?: FlyMachineConfig }[],
+): boolean => {
+  const first = group[0]?.config?.metadata;
+  if (!first || group.length === 0) return false;
+  const indices = new Set<string>();
+  for (const machine of group) {
+    const metadata = machine.config?.metadata;
+    const replica = metadata?.[keys.replica];
+    if (
+      !validProtocol2RecoveryMetadata(machine) ||
+      metadata?.[keys.generation] !== first[keys.generation] ||
+      metadata?.[keys.count] !== first[keys.count] ||
+      metadata?.[keys.sequence] !== first[keys.sequence] ||
+      metadata?.[keys.workload] !== first[keys.workload] ||
+      metadata?.[keys.roles] !== first[keys.roles] ||
+      replica === undefined ||
+      indices.has(replica) ||
+      !sameImageSet(pinsFromConfig(machine.config), pinsFromConfig(group[0]?.config))
+    )
+      return false;
+    indices.add(replica);
+  }
+  return true;
+};

package/src/Encrypt.ts

@@ -0,0 +1,60 @@
+import type { EncryptSecretKeyError } from "@distilled.cloud/fly-io/machines";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { SecretKey } from "./SecretKey.ts";
+
+export interface EncryptRequest {
+  /** Bytes to encrypt. */
+  plaintext: Uint8Array | ArrayLike<number>;
+  /** Optional AEAD associated data. */
+  associatedData?: Uint8Array | ArrayLike<number>;
+}
+
+export interface EncryptResult {
+  ciphertext: Uint8Array;
+}
+
+/**
+ * Encrypt with a Fly {@link SecretKey} (`nacl_box`, `nacl_secretbox`,
+ * `xaes256gcm`, …). The App and key name are fixed by `Encrypt(key)`.
+ *
+ *
+ * ### Encrypt a payload
+ * Provide {@link EncryptHttp} on the Action or Service Effect. Fly
+ * crypto ops need a KMS token. Org API tokens are typed `Forbidden`.
+ *
+ * **Example:** Encrypt
+ * ```typescript
+ * const encrypt = yield* Fly.Encrypt(Box);
+ * const { ciphertext } = yield* encrypt({
+ *   plaintext: new TextEncoder().encode("attack at dawn"),
+ * });
+ * ```
+ *
+ * ### Associated data
+ * `associatedData` is optional AEAD associated data. {@link Decrypt}
+ * must pass the same bytes.
+ *
+ * **Example:** AEAD
+ * ```typescript
+ * const { ciphertext } = yield* encrypt({
+ *   plaintext: bytes,
+ *   associatedData: nonce,
+ * });
+ * ```
+ *
+ * @binding
+ * @product Secret Key
+ */
+export interface Encrypt extends Binding.Service<
+  Encrypt,
+  "Fly.Encrypt",
+  (
+    key: SecretKey,
+  ) => Effect.Effect<
+    (request: EncryptRequest) => Effect.Effect<EncryptResult, EncryptSecretKeyError, RuntimeContext>
+  >
+> {}
+
+export const Encrypt = Binding.Service<Encrypt>("Fly.Encrypt");

package/src/EncryptHttp.ts

@@ -0,0 +1,48 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import { Encrypt, type EncryptRequest } from "./Encrypt.ts";
+import { base64ToBytes, bytesToBase64, makeHttpSecretKeyBinding } from "./SecretKeyHttp.ts";
+
+/**
+ * HTTP implementation of {@link Encrypt}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const encrypt = yield* Fly.Encrypt(Box);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.EncryptHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret Key
+ * @provides Fly.Encrypt
+ */
+export const EncryptHttp = Layer.effect(
+  Encrypt,
+  Effect.suspend(() =>
+    makeHttpSecretKeyBinding({
+      makeClient: (auth, appName, secretName) =>
+        Effect.fn("Fly.Encrypt")(function* (request: EncryptRequest) {
+          const res = yield* auth.authorize(
+            machines.encryptSecretKey({
+              app_name: yield* appName,
+              secret_name: yield* secretName,
+              plaintext: bytesToBase64(request.plaintext),
+              associated_data:
+                request.associatedData === undefined
+                  ? undefined
+                  : bytesToBase64(request.associatedData),
+            }),
+          );
+          return { ciphertext: base64ToBytes(res.ciphertext) };
+        }),
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));

package/src/Environment.ts

@@ -0,0 +1,81 @@
+import type { Config } from "@distilled.cloud/fly-io";
+import { Credentials } from "@distilled.cloud/fly-io";
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+
+export class FlyOrgNotFound extends Data.TaggedError("Fly.OrgNotFound")<{
+  message: string;
+}> {}
+
+/**
+ * Fully-resolved Fly.io environment for a stack.
+ *
+ * `{ apiKey, apiBaseUrl }` comes from distilled `Credentials`. `orgSlug` is
+ * the current token's organization (`getCurrentToken` → `tokens[0].org_slug`),
+ * cached for the process. Resolve it inside lifecycle operations with
+ * `FlyEnvironment.current`.
+ */
+export type FlyEnvironmentShape = Config & {
+  readonly orgSlug: string;
+};
+
+export class FlyEnvironment extends Context.Service<
+  FlyEnvironment,
+  Effect.Effect<FlyEnvironmentShape>
+>()("Fly::Environment") {
+  static current = FlyEnvironment.use((env) => env);
+  readonly kind = "Environment" as const;
+}
+
+/**
+ * Discover the current token's organization slug via `getCurrentToken`.
+ * Used by {@link fromCredentials} and by {@link Catalog.currentOrgSlug}.
+ */
+export const resolveOrgSlug = Effect.fn(function* () {
+  const info = yield* machines.getCurrentToken({});
+  const orgSlug = info.tokens?.[0]?.org_slug;
+  if (orgSlug === undefined || orgSlug.length === 0) {
+    return yield* new FlyOrgNotFound({
+      message: "Fly current token did not include an organization slug.",
+    });
+  }
+  return orgSlug;
+});
+
+/**
+ * Build a `FlyEnvironment` layer from the distilled `Credentials`
+ * service. Provide this after `Credentials.fromAuthProvider()`.
+ *
+ * `orgSlug` is resolved from `getCurrentToken` and cached so App.list /
+ * Catalog do not re-hit `/tokens/current` on every call.
+ */
+export const fromCredentials = () =>
+  Layer.effect(
+    FlyEnvironment,
+    Effect.gen(function* () {
+      const creds = yield* Credentials;
+      const http = yield* HttpClient.HttpClient;
+      return yield* creds.pipe(
+        Effect.flatMap((resolved) =>
+          resolveOrgSlug().pipe(
+            Effect.provide(
+              Layer.mergeAll(
+                Layer.succeed(Credentials, creds),
+                Layer.succeed(HttpClient.HttpClient, http),
+              ),
+            ),
+            Effect.map((orgSlug) => ({
+              ...resolved,
+              orgSlug,
+            })),
+          ),
+        ),
+        Effect.orDie,
+        Effect.cached,
+      );
+    }),
+  );

package/src/Errors.ts

@@ -0,0 +1,14 @@
+import * as Data from "effect/Data";
+
+/**
+ * A {@link Bucket}'s Tigris credentials could not be resolved when a
+ * bound S3 operation ran.
+ *
+ * Tigris hands out the access key pair once, at add-on creation. If the
+ * Bucket attributes reaching the binding carry no key pair — an adopted
+ * bucket, or one whose create-only secrets were never persisted — the
+ * operation fails with this instead of signing an anonymous request.
+ */
+export class TigrisCredentialsMissing extends Data.TaggedError("Fly.TigrisCredentialsMissing")<{
+  name: string;
+}> {}

package/src/Exec.ts

@@ -0,0 +1,50 @@
+import type { ExecCommandError, ExecResult } from "@distilled.cloud/fly-io/sprites";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Sprite } from "./Sprite.ts";
+
+export interface ExecRequest {
+  /** Command and args. */
+  cmd: string[];
+  /** Explicit path to the executable. */
+  path?: string;
+  /** Read stdin from {@link body}. */
+  stdin?: boolean;
+  /** Environment variables as `KEY=VALUE`. */
+  env?: string[];
+  /** Working directory. */
+  dir?: string;
+  /** Stdin bytes when {@link stdin} is true. */
+  body?: Uint8Array | string;
+}
+
+/**
+ * Run a command on a {@link Sprite} via `POST /sprites/{name}/exec`.
+ *
+ *
+ * ### Exec a command
+ * Bind the client in init. Provide {@link ExecHttp}. The Sprite name
+ * is fixed by `Exec(box)`. Alchemy transports that name and the
+ * deployment's org token to the caller automatically.
+ *
+ * **Example:** List files
+ * ```typescript
+ * const exec = yield* Fly.Exec(Box);
+ * const result = yield* exec({ cmd: ["ls", "-la"] });
+ * ```
+ *
+ * @binding
+ * @product Sprite
+ */
+export interface Exec extends Binding.Service<
+  Exec,
+  "Fly.Exec",
+  (
+    sprite: Sprite,
+  ) => Effect.Effect<
+    (request: ExecRequest) => Effect.Effect<ExecResult, ExecCommandError, RuntimeContext>
+  >
+> {}
+
+export const Exec = Binding.Service<Exec>("Fly.Exec");

package/src/ExecHttp.ts

@@ -0,0 +1,47 @@
+import * as sprites from "@distilled.cloud/fly-io/sprites";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import { Exec, type ExecRequest } from "./Exec.ts";
+import { makeHttpSpriteBinding } from "./SpriteHttp.ts";
+
+/**
+ * HTTP implementation of {@link Exec}. Provide it on the
+ * {@link Sprite}, {@link Service}, or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Sprite
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const exec = yield* Fly.Exec(Box);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.ExecHttp))
+ * ```
+ *
+ * @layer
+ * @product Sprite
+ * @provides Fly.Exec
+ */
+export const ExecHttp = Layer.effect(
+  Exec,
+  Effect.suspend(() =>
+    makeHttpSpriteBinding({
+      makeClient: (auth, spriteName) =>
+        Effect.fn("Fly.Exec")(function* (request: ExecRequest) {
+          return yield* auth.authorize(
+            sprites.execCommand({
+              name: yield* spriteName,
+              cmd: request.cmd,
+              path: request.path,
+              stdin: request.stdin,
+              env: request.env,
+              dir: request.dir,
+              body: request.body,
+            }),
+          );
+        }),
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));

package/src/GetObject.ts

@@ -0,0 +1,48 @@
+import type * as S3 from "@distilled.cloud/aws/s3";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Bucket } from "./Bucket.ts";
+import type { TigrisCredentialsMissing } from "./Errors.ts";
+
+export interface GetObjectRequest extends Omit<S3.GetObjectRequest, "Bucket"> {}
+
+/**
+ * Runtime binding for Tigris `GetObject` over the S3 API.
+ *
+ * Bind this operation to a {@link Bucket} in Service init. Provide
+ * {@link GetObjectHttp}.
+ *
+ *
+ * ### Reading Objects
+ * **Example:** Read an Object and Decode Its Body
+ * ```typescript
+ * const getObject = yield* Fly.GetObject(Data);
+ *
+ * const text = yield* getObject({ Key: "hello.txt" }).pipe(
+ *   Effect.flatMap((result) =>
+ *     Stream.mkString(Stream.decodeText(result.Body!)),
+ *   ),
+ * );
+ * ```
+ *
+ * @binding
+ * @product Bucket
+ */
+export interface GetObject extends Binding.Service<
+  GetObject,
+  "Fly.GetObject",
+  (
+    bucket: Bucket,
+  ) => Effect.Effect<
+    (
+      request: GetObjectRequest,
+    ) => Effect.Effect<
+      S3.GetObjectOutput,
+      S3.GetObjectError | TigrisCredentialsMissing,
+      RuntimeContext
+    >
+  >
+> {}
+
+export const GetObject = Binding.Service<GetObject>("Fly.GetObject");

package/src/GetObjectHttp.ts

@@ -0,0 +1,20 @@
+import * as S3 from "@distilled.cloud/aws/s3";
+import * as Layer from "effect/Layer";
+import { makeTigrisS3Binding } from "./BucketBinding.ts";
+import { GetObject } from "./GetObject.ts";
+
+/**
+ * HTTP implementation of {@link GetObject}. Calls distilled S3
+ * `getObject` against the Tigris endpoint with the bucket's credentials.
+ *
+ * @layer
+ * @product Bucket
+ * @provides Fly.GetObject
+ */
+export const GetObjectHttp = Layer.effect(
+  GetObject,
+  makeTigrisS3Binding({
+    tag: "Fly.GetObject",
+    operation: S3.getObject,
+  }),
+);

package/src/GetSecret.ts

@@ -0,0 +1,48 @@
+import type { AppSecret, GetSecretError } from "@distilled.cloud/fly-io/machines";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Secret } from "./Secret.ts";
+
+/**
+ * Fetch one Fly.io App secret. The App and name are fixed by
+ * `GetSecret(secret)`. Calls take no `app_name`.
+ *
+ *
+ * ### Read a secret
+ * Bind the client in init. Call it from `fetch` or an Action body.
+ * Provide {@link GetSecretHttp}. Alchemy transports the bound App name,
+ * secret name, and deployment's org token automatically. There is no
+ * need to configure `FLY_SECRET_*` environment variables.
+ *
+ * Fly only returns plaintext from a Machine in the same App. From a
+ * deploy-time Action you get metadata (name, digest, timestamps).
+ *
+ * **Example:** GetSecret
+ * ```typescript
+ * export default class Api extends Fly.Service<Api>()(
+ *   "Api",
+ *   { app: Site, main: import.meta.url, port: 3000 },
+ *   Effect.gen(function* () {
+ *     const get = yield* Fly.GetSecret(ApiToken);
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const got = yield* get().pipe(Effect.orDie);
+ *         return HttpServerResponse.json({ name: got.name });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Fly.GetSecretHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Secret
+ */
+export interface GetSecret extends Binding.Service<
+  GetSecret,
+  "Fly.GetSecret",
+  (secret: Secret) => Effect.Effect<() => Effect.Effect<AppSecret, GetSecretError, RuntimeContext>>
+> {}
+
+export const GetSecret = Binding.Service<GetSecret>("Fly.GetSecret");

package/src/GetSecretHttp.ts

@@ -0,0 +1,60 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import { GetSecret } from "./GetSecret.ts";
+import { makeHttpSecretBinding } from "./SecretHttp.ts";
+
+/**
+ * HTTP implementation of {@link GetSecret}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const get = yield* Fly.GetSecret(ApiToken);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.GetSecretHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret
+ * @provides Fly.GetSecret
+ */
+export const GetSecretHttp = Layer.effect(
+  GetSecret,
+  Effect.suspend(() =>
+    makeHttpSecretBinding({
+      makeClient: (auth, appName, secretName) =>
+        Effect.fn("Fly.GetSecret")(function* () {
+          const name = yield* secretName;
+          if (globalThis.__ALCHEMY_RUNTIME__) {
+            // Fly injects App secrets as env vars on the Machine. Prefer
+            // that over getSecret — org tokens still cannot read plaintext
+            // from outside the App, and the env is already the source of
+            // truth once the secret exists.
+            const fromEnv = yield* Config.Redacted(name).pipe(
+              Effect.map((value) => ({
+                name,
+                value: Redacted.value(value),
+              })),
+              Effect.orElseSucceed(() => undefined),
+            );
+            if (fromEnv !== undefined) return fromEnv;
+          }
+          return yield* auth.authorize(
+            machines.getSecret({
+              app_name: yield* appName,
+              secret_name: name,
+              show_secrets: globalThis.__ALCHEMY_RUNTIME__ === true,
+            }),
+          );
+        }),
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));

package/src/HeadObject.ts

@@ -0,0 +1,43 @@
+import type * as S3 from "@distilled.cloud/aws/s3";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Bucket } from "./Bucket.ts";
+import type { TigrisCredentialsMissing } from "./Errors.ts";
+
+export interface HeadObjectRequest extends Omit<S3.HeadObjectRequest, "Bucket"> {}
+
+/**
+ * Runtime binding for Tigris `HeadObject` over the S3 API.
+ *
+ * Bind this operation to a {@link Bucket} in Service init. Provide
+ * {@link HeadObjectHttp}.
+ *
+ *
+ * ### Inspecting Objects
+ * **Example:** Check an Object's Metadata
+ * ```typescript
+ * const headObject = yield* Fly.HeadObject(Data);
+ * const head = yield* headObject({ Key: "hello.txt" });
+ * ```
+ *
+ * @binding
+ * @product Bucket
+ */
+export interface HeadObject extends Binding.Service<
+  HeadObject,
+  "Fly.HeadObject",
+  (
+    bucket: Bucket,
+  ) => Effect.Effect<
+    (
+      request: HeadObjectRequest,
+    ) => Effect.Effect<
+      S3.HeadObjectOutput,
+      S3.HeadObjectError | TigrisCredentialsMissing,
+      RuntimeContext
+    >
+  >
+> {}
+
+export const HeadObject = Binding.Service<HeadObject>("Fly.HeadObject");

package/src/HeadObjectHttp.ts

@@ -0,0 +1,20 @@
+import * as S3 from "@distilled.cloud/aws/s3";
+import * as Layer from "effect/Layer";
+import { makeTigrisS3Binding } from "./BucketBinding.ts";
+import { HeadObject } from "./HeadObject.ts";
+
+/**
+ * HTTP implementation of {@link HeadObject}. Calls distilled S3
+ * `headObject` against the Tigris endpoint with the bucket's credentials.
+ *
+ * @layer
+ * @product Bucket
+ * @provides Fly.HeadObject
+ */
+export const HeadObjectHttp = Layer.effect(
+  HeadObject,
+  makeTigrisS3Binding({
+    tag: "Fly.HeadObject",
+    operation: S3.headObject,
+  }),
+);