sailfork / t3code-github / .repos/ alchemy-effect/ packages/ fly/ src/ Sprite.ts

import type { SpriteResponse as FlySprite } from "@distilled.cloud/fly-io/sprites";
import * as sprites from "@distilled.cloud/fly-io/sprites";
import { Unowned } from "alchemy/AdoptPolicy";
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 { ServerHost } from "alchemy/Runtime/Process";
import { Stack } from "alchemy/Stack";
import { createInternalTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import {
  createFlyHostRuntimeContext,
  createSpriteHostedSupport,
  DEFAULT_PORT,
  type FlyHostRuntimeContext,
  type HostedProgramProps,
} from "./hosted.ts";
import {
  createFlyResourceName,
  matchesAlchemyPhysicalName,
  sanitizeFlyAppName,
} from "./Metadata.ts";
import type { Providers } from "./Providers.ts";

const DEFAULT_URL_AUTH: UrlAuth = "public";
const APP_DIR = "/home/sprite/alchemy";
const BUN_BIN = "/home/sprite/.bun/bin/bun";
const SERVICE_NAME = "alchemy";
const OWNER_LABEL = "alchemy.type=Fly.Sprite";

const backoff = Schedule.min([
  Schedule.exponential(Duration.millis(500), 1.5),
  Schedule.spaced(Duration.seconds(5)),
]);

export type UrlAuth = "public" | "sprite";

export type SpriteStatus = "cold" | "warm" | "running";

export interface SpriteProps extends PlatformProps {
  /**
   * Module entrypoint bundled with rolldown and written onto the Sprite.
   * Typically `import.meta.url`. A content-hash change updates in place.
   */
  main: string;
  /**
   * Sprite name. Unique per organization. If omitted, a unique name is
   * generated from the stack, stage and logical ID. Changing it replaces
   * the Sprite.
   */
  name?: string;
  /**
   * Who can hit {@link Sprite} `url`. `public` is open. `sprite` requires
   * Sprites auth.
   *
   * @default "public"
   */
  urlAuth?: UrlAuth;
  /**
   * Port the hosted HTTP server listens on. Written to `PORT` and used
   * as the Sprite service `http_port`.
   *
   * @default 3000
   */
  port?: number;
  /**
   * Named export to load from `main`.
   *
   * @default "default"
   */
  handler?: string;
  /**
   * Additional environment variables for the hosted process. Merged
   * after binding-injected `env`.
   */
  env?: Record<string, any>;
  /**
   * Bundler configuration for `main`: rolldown `input`/`output`
   * overrides plus pure-annotation options (`pure`).
   */
  build?: Bundle.BundleConfig;
}

/**
 * Binding contract accepted by {@link Sprite} for injected env.
 */
export interface SpriteBinding {
  env?: Record<string, any>;
}

export type Sprite = Resource<
  "Fly.Sprite",
  SpriteProps,
  {
    /** Fly Sprite id. */
    spriteId: string;
    /** Physical Sprite name (unique per org). */
    name: string;
    /**
     * Public Sprite URL (`https://{name}-….sprites.app`).
     */
    url: string;
    /** Observed runtime status. Hibernates to `cold` when idle. */
    status: SpriteStatus;
    /** Observed URL auth setting. */
    urlAuth: UrlAuth;
    /** Organization slug, if the API returned one. */
    orgSlug: string | undefined;
    /** Content hash of the bundled program. */
    code: {
      hash: string;
    };
  },
  SpriteBinding,
  Providers
>;

export const isSprite = (value: unknown): value is Sprite =>
  typeof value === "object" && value !== null && (value as { Type?: string }).Type === "Fly.Sprite";

export type SpriteServices = ServerHost;

export type SpriteShape = Main<SpriteServices>;

export type SpriteRuntimeContext = FlyHostRuntimeContext;

/**
 * A Sprite is an Effect program running in a Fly.io Sprite. Sprites
 * are org-scoped Linux sandboxes. They hibernate when idle and wake
 * on demand. There is no parent {@link App}. Unlike a {@link Service},
 * Alchemy does not build a Docker image.
 *
 * @see https://sprites.dev/api/sprites
 *
 * ### Declare a Sprite
 * A Sprite is a class. Props describe the sandbox. The Effect is the
 * program that runs on it. There is no parent App.
 *
 * `main: import.meta.url` is the bundle entrypoint. Alchemy bundles
 * this file with Rolldown, writes it onto the Sprite, and runs it as
 * a Sprite service on {@link port}. Auth is `FLY_API_TOKEN`.
 *
 * **Example:** Class + main
 * ```typescript
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     return {};
 *   }),
 * ) {}
 * ```
 *
 * ### Serve HTTP with fetch
 * Return `fetch` from the init Effect to boot an HTTP server. The
 * Sprite URL proxies to {@link port}.
 *
 * **Example:** Hello
 * ```typescript
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### The public URL
 * Yield the Sprite in the Stack. `box.url` is
 * `https://{name}-….sprites.app`.
 *
 * **Example:** Stack output
 * ```typescript
 * export default Alchemy.Stack(
 *   "MyApp",
 *   { providers: Fly.providers(), state: Alchemy.localState() },
 *   Effect.gen(function* () {
 *     const box = yield* Box;
 *     return { url: box.url };
 *   }),
 * );
 * ```
 *
 * ### URL auth
 * `urlAuth` is `public` or `sprite`. Default is `public` so `url`
 * answers without a Sprites token.
 *
 * **Example:** Sprite-auth URL
 * ```typescript
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url, urlAuth: "sprite" },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * :::note[Default is public]
 * Fly's API default is `sprite`. Alchemy defaults to `public` so a
 * `fetch` handler is reachable.
 * :::
 *
 * ### Config
 * Yield `Config` in init. Alchemy reads the value from the env of
 * whoever deploys and writes it onto the Sprite. Do not pass
 * `env: { ... }` on a Sprite.
 *
 * Yield `FileSystem.FileSystem` in init, never inside `fetch`.
 *
 * **Example:** Config.Redacted
 * ```typescript
 * import * as Config from "effect/Config";
 * import * as FileSystem from "effect/FileSystem";
 * import * as Redacted from "effect/Redacted";
 *
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const apiKey = yield* Config.Redacted("API_KEY");
 *     const fs = yield* FileSystem.FileSystem;
 *     yield* fs.makeDirectory("/tmp", { recursive: true });
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const token = Redacted.value(apiKey);
 *         return HttpServerResponse.text("ok");
 *       }),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Exec
 * {@link Exec} runs a command on the Sprite. Provide {@link ExecHttp}.
 *
 * **Example:** ls
 * ```typescript
 * const exec = yield* Fly.Exec(Box);
 * const result = yield* exec({ cmd: ["ls", "-la"] });
 * ```
 *
 * ### Checkpoint
 * {@link Checkpoint} snapshots and restores the Sprite disk. Provide
 * {@link CheckpointHttp}.
 *
 * **Example:** Create and restore
 * ```typescript
 * const checkpoint = yield* Fly.Checkpoint(Box);
 * yield* checkpoint.create({ comment: "before" });
 * yield* checkpoint.restore("v1");
 * ```
 *
 * :::caution[Restore is destructive]
 * The disk rewinds. Later writes are gone.
 * :::
 *
 * ### A stable name
 * Omit `name` and Alchemy generates one from the stack, stage, and
 * logical ID.
 *
 * **Example:** Explicit name
 * ```typescript
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url, name: "box" },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * :::caution[Changing `name` replaces the Sprite]
 * Fly cannot rename a Sprite. Alchemy creates the new name, then
 * deletes the old one.
 * :::
 *
 * ### Named export
 * `handler` is the named export to load from `main`. Default is
 * `"default"`.
 *
 * **Example:** Custom handler
 * ```typescript
 * export default class Box extends Fly.Sprite<Box>()(
 *   "Box",
 *   { main: import.meta.url, handler: "box" },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * @resource
 * @product Sprite
 */
export const Sprite: Platform<Sprite, SpriteServices, SpriteShape, SpriteRuntimeContext> = Platform(
  "Fly.Sprite",
  {
    createRuntimeContext: createFlyHostRuntimeContext("Fly.Sprite"),
  },
);

export class SpriteNotCreated extends Data.TaggedError("Fly.SpriteNotCreated")<{
  resourceName: string;
}> {}

export class SpriteExecFailed extends Data.TaggedError("Fly.SpriteExecFailed")<{
  resourceName: string;
  cmd: string;
  exitCode: number | undefined;
  stderr: string | undefined;
}> {}

class SpritePending extends Data.TaggedError("Fly.SpritePending")<{
  resourceName: string;
}> {}

const toStatus = (status: string | undefined): SpriteStatus =>
  status === "warm" || status === "running" || status === "cold" ? status : "cold";

const toUrlAuth = (auth: string | undefined): UrlAuth => (auth === "sprite" ? "sprite" : "public");

const toAttrs = (sprite: FlySprite, name: string, codeHash: string): Sprite["Attributes"] => ({
  spriteId: sprite.id ?? name,
  name: sprite.name ?? name,
  url: sprite.url ?? `https://${name}.sprites.app`,
  status: toStatus(sprite.status),
  urlAuth: toUrlAuth(sprite.url_settings?.auth),
  orgSlug: sprite.organization,
  code: { hash: codeHash },
});

const isOwnedSprite = (sprite: FlySprite): boolean => {
  const labels = sprite.labels ?? [];
  if (labels.includes(OWNER_LABEL)) return true;
  if (labels.some((label) => label.startsWith("alchemy.type="))) return true;
  return matchesAlchemyPhysicalName(sprite.name);
};

const resolveSpriteName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (name !== undefined) return sanitizeFlyAppName(name);
    if (existing !== undefined) return existing;
    return yield* createFlyResourceName(id);
  });

const ownershipLabels = (id: string) =>
  Effect.gen(function* () {
    const tags = yield* createInternalTags(id);
    return [...Object.entries(tags).map(([key, value]) => `${key}=${value}`), OWNER_LABEL];
  });

const getByName = (name: string) =>
  sprites.getSprite({ name }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const waitForSprite = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((found) =>
      found !== undefined
        ? Effect.succeed(found)
        : Effect.fail(new SpritePending({ resourceName: name })),
    ),
    Effect.retry({
      while: (e) => e._tag === "Fly.SpritePending",
      times: 8,
      schedule: backoff,
    }),
  );

const isTransient = (e: { readonly _tag: string }) =>
  e._tag === "NotFound" ||
  e._tag === "TooManyRequests" ||
  e._tag === "ServiceUnavailable" ||
  e._tag === "BadGateway" ||
  e._tag === "GatewayTimeout";

const retryTransient = <A, E extends { readonly _tag: string }, R>(
  effect: Effect.Effect<A, E, R>,
) =>
  effect.pipe(
    Effect.retry({
      while: isTransient,
      times: 8,
      schedule: backoff,
    }),
  );

const toEnv = (env: Record<string, any> | undefined): Record<string, string> =>
  Object.fromEntries(
    Object.entries(env ?? {}).flatMap(([key, value]) => {
      if (value === undefined || value === null) return [];
      const raw = Redacted.isRedacted(value) ? Redacted.value(value) : value;
      return [[key, String(raw)]];
    }),
  );

const collectBindingEnv = (bindings: readonly ResourceBinding<SpriteBinding>[]) => {
  const active = bindings.filter(
    (binding: ResourceBinding<SpriteBinding> & { action?: string }) => binding.action !== "delete",
  );
  return active
    .map((binding) => binding?.data?.env)
    .reduce<Record<string, any>>((acc, value) => ({ ...acc, ...value }), {});
};

const desiredEnv = (
  props: SpriteProps,
  bindingEnv: Record<string, any>,
  alchemyEnv: Record<string, string>,
  port: number,
): Record<string, string> => ({
  ...toEnv(bindingEnv),
  ...alchemyEnv,
  PORT: String(port),
  ...toEnv(props.env),
});

const renderEnvFile = (env: Record<string, string>) =>
  `${Object.entries(env)
    .sort(([left], [right]) => left.localeCompare(right))
    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
    .join("\n")}\n`;

const writeRemoteFile = (input: { name: string; path: string; body: Uint8Array }) =>
  retryTransient(
    sprites.writeFile({
      name: input.name,
      path: input.path,
      workingDir: "/",
      mkdir: true,
      body: input.body,
    }),
  );

const runExec = (input: { name: string; cmd: string[]; env?: string[] }) =>
  Effect.gen(function* () {
    const result = yield* retryTransient(
      sprites.execCommand({
        name: input.name,
        cmd: input.cmd,
        env: input.env,
      }),
    );
    if ((result.exit_code ?? 0) !== 0) {
      return yield* new SpriteExecFailed({
        resourceName: input.name,
        cmd: input.cmd.join(" "),
        exitCode: result.exit_code,
        stderr: result.stderr,
      });
    }
    return result;
  });

const ensureBun = (name: string) =>
  runExec({
    name,
    cmd: [
      "bash",
      "-lc",
      [
        "set -euo pipefail",
        "export HOME=/home/sprite",
        "export BUN_INSTALL=/home/sprite/.bun",
        'export PATH="$BUN_INSTALL/bin:$PATH"',
        'if [ ! -x "$BUN_INSTALL/bin/bun" ]; then',
        "  curl -fsSL https://bun.sh/install | bash",
        "fi",
        `test -x ${BUN_BIN}`,
      ].join("\n"),
    ],
  });

const putAlchemyService = (input: { name: string; port: number }) =>
  retryTransient(
    sprites.putService({
      name: input.name,
      service_name: SERVICE_NAME,
      cmd: "bash",
      args: [
        "-lc",
        `set -a; [ -f ${APP_DIR}/env ] && . ${APP_DIR}/env; set +a; exec ${BUN_BIN} --no-install ${APP_DIR}/index.mjs`,
      ],
      dir: APP_DIR,
      http_port: input.port,
    }),
  ).pipe(Effect.catchTag("NotFound", () => Effect.void));

const deployProgram = Effect.fn(function* (input: {
  name: string;
  files: ReadonlyArray<{ path: string; content: Uint8Array }>;
  env: Record<string, string>;
  port: number;
  session?: { note: (message: string) => Effect.Effect<void> };
}) {
  const note = input.session?.note ?? ((_message: string) => Effect.void);
  yield* note(`Writing ${input.name} program onto the Sprite...`);
  for (const file of input.files) {
    const rel = file.path.replace(/^\/+/, "");
    yield* writeRemoteFile({
      name: input.name,
      path: `${APP_DIR}/${rel}`,
      body: file.content,
    });
  }
  yield* writeRemoteFile({
    name: input.name,
    path: `${APP_DIR}/env`,
    body: new TextEncoder().encode(renderEnvFile(input.env)),
  });
  yield* note(`Installing bun on ${input.name}...`);
  yield* ensureBun(input.name);
  yield* note(`Starting ${input.name} service...`);
  yield* putAlchemyService({ name: input.name, port: input.port });
});

export const SpriteProvider = () =>
  Provider.effect(
    Sprite,
    Effect.gen(function* () {
      const stack = yield* Stack;
      const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
      const hosted = createSpriteHostedSupport({
        stackName: stack.name,
        stage: stack.stage,
        virtualEntryPlugin,
      });

      return Sprite.Provider.of({
        stables: ["spriteId", "name"],

        diff: Effect.fn(function* ({ news, output }) {
          if (news === undefined || output === undefined) return undefined;
          if (isResolved(news)) {
            const desiredName =
              news.name !== undefined ? sanitizeFlyAppName(news.name) : output.name;
            if (desiredName !== output.name) {
              return { action: "replace" as const };
            }
            const desiredAuth = news.urlAuth ?? DEFAULT_URL_AUTH;
            if (desiredAuth !== output.urlAuth) {
              return { action: "update" as const };
            }
          }
          // The code hash depends only on statically-known props — never
          // gate it on the WHOLE props being resolved: an unresolved
          // reference elsewhere in props would make code-only changes
          // silently noop (see the same pattern in Service.ts). By diff
          // time the effect-config form has been evaluated, so the object
          // view is safe to read.
          const statics = news as Partial<Pick<SpriteProps, "main" | "port">>;
          if (isResolved({ main: statics.main, port: statics.port })) {
            const hash = yield* hosted.hash(news as HostedProgramProps);
            if (hash !== output.code.hash) {
              return { action: "update" as const };
            }
          }
          return undefined;
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = yield* resolveSpriteName(id, olds?.name, output?.name);
          const found = yield* (
            output?.name !== undefined ? getByName(output.name) : Effect.undefined
          ).pipe(
            Effect.flatMap((existing) =>
              existing !== undefined ? Effect.succeed(existing) : getByName(name),
            ),
            Effect.catchTag("SpritesNotEnabled", () => Effect.undefined),
          );
          if (found === undefined) return undefined;
          const attrs = toAttrs(found, name, output?.code.hash ?? "");
          if (output !== undefined) return attrs;
          return isOwnedSprite(found) ? attrs : Unowned(attrs);
        }),

        list: Effect.fn(function* () {
          const items = yield* sprites.listSprites.items({ max_results: 50 }).pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("SpritesNotEnabled", () => Effect.succeed([])),
          );
          return items
            .filter(isOwnedSprite)
            .map((sprite) => toAttrs(sprite, sprite.name ?? "", ""));
        }),

        reconcile: Effect.fn(function* ({ id, news, output, bindings, session }) {
          const props = news;
          const name = yield* resolveSpriteName(id, props.name, output?.name);
          const urlAuth = props.urlAuth ?? DEFAULT_URL_AUTH;
          const port = props.port ?? DEFAULT_PORT;
          const labels = yield* ownershipLabels(id);
          const boundEnv = collectBindingEnv(bindings ?? []);
          const env = desiredEnv(props, boundEnv, hosted.alchemyEnv, port);

          let current = output?.name !== undefined ? yield* getByName(output.name) : undefined;
          if (current === undefined && output?.name !== name) {
            current = yield* getByName(name);
          }

          if (current === undefined) {
            yield* sprites
              .createSprite({
                name,
                url_settings: { auth: urlAuth },
                labels,
              })
              .pipe(Effect.catchTag("Conflict", () => Effect.void));
            current = yield* waitForSprite(name).pipe(
              Effect.catchTag("Fly.SpritePending", () => getByName(name)),
            );
          }

          if (current === undefined) {
            return yield* new SpriteNotCreated({ resourceName: name });
          }
          // Narrowed once so the `NotFound` fallbacks below keep the
          // non-optional type instead of widening back to `| undefined`.
          let sprite = current;

          const observedAuth = toUrlAuth(sprite.url_settings?.auth);
          if (observedAuth !== urlAuth) {
            sprite = yield* sprites
              .updateSprite({
                name,
                url_settings: { auth: urlAuth },
              })
              .pipe(Effect.catchTag("NotFound", () => Effect.succeed(sprite)));
          }

          const codeHash = yield* hosted.hash(props);
          if (codeHash !== output?.code.hash) {
            const bundled = yield* hosted.bundleProgram(props);
            yield* deployProgram({
              name,
              files: bundled.files,
              env,
              port,
              session,
            });
            sprite = (yield* getByName(name)) ?? sprite;
          }

          return toAttrs(sprite, name, codeHash);
        }),

        delete: Effect.fn(function* ({ output }) {
          if (output.name.length === 0) return;
          yield* sprites
            .deleteSprite({ name: output.name })
            .pipe(Effect.catchTag(["NotFound", "SpritesNotEnabled"], () => Effect.void));
        }),
      });
    }),
  );