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

import type { Docker } from "@alchemy.run/docker/Docker";
import type { FlyMachineService } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import * as Bundle from "alchemy/Bundle/Bundle";
import {
  matchesPackageRoot,
  normalizeInstallTargets,
  resolvePackageInstallIdentity,
  type PackageInstall,
} from "alchemy/Bundle/InstalledPackages";
import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
import { safeHttpEffect } from "alchemy/Http";
import type { ResourceBinding } from "alchemy/Resource";
import { createContainerRuntimeContext, type HostRuntimeContext } from "alchemy/Runtime/Process";
import {
  copyExtraFiles,
  contextRootOf,
  extraFileDestination,
  hashExtraFiles,
  isContextRootDest,
  posixRelUnder,
  resolveExtraSource,
  type ExtraFile,
} from "alchemy/Util/extraFiles";
import { sha256, sha256Object } from "alchemy/Util/sha256";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
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 { buildOnRemoteBuilder } from "./internal/RemoteBuilder.ts";
import type { BoundTarget, DiskSpec, ServiceBinding } from "./MountVolume.ts";
import { rpcMethodsOf, serveFlyRpc } from "./rpc.ts";

export type FlyHostRuntimeContext = HostRuntimeContext;

/**
 * Container runtime context for Fly hosts. It also serves the program's RPC
 * methods to bound callers (see {@link serveFlyRpc}) and boots the HTTP
 * server for a program that exposes methods but no `fetch`.
 */
export const createFlyHostRuntimeContext =
  (type: string) =>
  (id: string): HostRuntimeContext => {
    const base = createContainerRuntimeContext(type)(id);
    const serveBase = base.serve;
    const serve: HostRuntimeContext["serve"] = (handler, options) => {
      const shape = options?.shape;
      const methods = rpcMethodsOf(shape);
      // `safeHttpEffect` also resolves a `fetch` given as an Effect that
      // builds the handler.
      const wrapped = serveFlyRpc(methods, safeHttpEffect(handler));
      const boots =
        shape === undefined || shape.fetch !== undefined || Object.keys(methods).length > 0;
      return serveBase(
        wrapped,
        boots ? { shape: { ...shape, fetch: shape?.fetch ?? wrapped } } : options,
      ) as Effect.Effect<void, never, any>;
    };
    return Object.assign(base, { serve });
  };

export const FLY_REGISTRY = "registry.fly.io";
export const DEFAULT_BASE_IMAGE = "node:26-slim";
export const DEFAULT_PORT = 3000;
export const MACHINE_PLATFORM = "linux/amd64";

export interface FlyBuildOptions extends Bundle.BundleConfig {
  /**
   * Native or Node-only packages to install into the Machine image with
   * `npm install` instead of bundling them. Same `build.install` shape as
   * Lambda.
   *
   * @example
   * ```typescript
   * build: { install: ["sharp"] }
   * ```
   */
  readonly install?: PackageInstall;
  /**
   * Build the image on Fly's remote builders (Depot), as `fly deploy` does,
   * instead of with the local Docker engine. Only the build context is
   * uploaded; the builder pulls the base image and pushes the result to
   * `registry.fly.io` next to it. Set `false` to build and push locally.
   * Either way, the local `docker buildx` client drives the build.
   *
   * @default true
   */
  readonly remote?: boolean;
}

export type { ExtraFile };

export interface HostedProgramProps {
  main: string;
  handler?: string;
  port?: number;
  image?: string;
  env?: Record<string, any>;
  isExternal?: boolean;
  build?: FlyBuildOptions;
  /**
   * Extra host directories baked into the image (framework client
   * assets, Next.js `.next`, …). Hashed into `code.hash` so asset
   * changes rebuild the image.
   */
  extraFiles?: ReadonlyArray<ExtraFile>;
}

export { extraFileDestination };

const matchesConfiguredExternal = (
  external: rolldown.InputOptions["external"],
  moduleId: string,
  parentId: string | undefined,
  isResolved: boolean,
): boolean => {
  if (external === undefined) return false;
  if (typeof external === "function") {
    return external(moduleId, parentId, isResolved) === true;
  }
  const matchers = Array.isArray(external) ? external : [external];
  return matchers.some((matcher) =>
    typeof matcher === "string" ? matcher === moduleId : matcher.test(moduleId),
  );
};

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

/**
 * The generated entry for `Fly.Service` / `Fly.Sprite` machines: a shim
 * importing only `@alchemy.run/fly/Bootstrap` plus the user's `main` —
 * see that module for why the entry never imports alchemy's own
 * dependencies. The runtime flag is raised BEFORE the user's module is
 * evaluated (hence the dynamic import) so its module-scope code sees it.
 */
const makeBunBootstrap =
  (handler: string) =>
  (importPath: string): string =>
    `
import { bootstrap } from "@alchemy.run/fly/Bootstrap";

globalThis.__ALCHEMY_RUNTIME__ = true;
const { ${handler}: entrypoint } = await import(${JSON.stringify(importPath)});

await bootstrap(entrypoint);
`;

/** Unwrap env inputs while preserving serialized RuntimeContext markers. */
export const plainEnvValue = (value: unknown): string | undefined => {
  if (value === undefined || value === null) return undefined;
  if (Redacted.isRedacted(value)) return value.pipe(Redacted.value, plainEnvValue);
  if (typeof value === "string") {
    return value.length > 0 ? value : undefined;
  }
  if (typeof value === "number" || typeof value === "boolean") {
    return String(value);
  }
  return undefined;
};

export const toEnvRecord = (env: Record<string, any> | undefined): Record<string, string> =>
  Object.fromEntries(
    Object.entries(env ?? {}).flatMap(([key, value]) => {
      const raw = plainEnvValue(value);
      return raw === undefined ? [] : [[key, raw]];
    }),
  );

const coerceBindingName = (value: unknown): string | undefined => {
  const direct = plainEnvValue(value);
  if (direct !== undefined) return direct;
  if (value != null && typeof value === "object") {
    const record = value as { name?: unknown; id?: unknown; addOnId?: unknown };
    return (
      coerceBindingName(record.name) ??
      coerceBindingName(record.id) ??
      coerceBindingName(record.addOnId)
    );
  }
  return undefined;
};

export const collectBindingState = (bindings: readonly ResourceBinding<ServiceBinding>[]) => {
  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 mounts: DiskSpec[] = [];
  const seen = new Set<string>();
  const redis: { name: string; id?: string }[] = [];
  const buckets: { name: string; id?: string; values?: Record<string, string> }[] = [];
  const postgres: { clusterId: string; variableName?: string }[] = [];
  const targets: BoundTarget[] = [];
  for (const binding of active) {
    const target = binding?.data?.target;
    if (target !== undefined) targets.push(target);
    for (const mount of binding?.data?.mounts ?? []) {
      if (seen.has(mount.path)) continue;
      seen.add(mount.path);
      mounts.push(mount);
    }
    const attached = binding?.data?.redis;
    const redisName = coerceBindingName(attached?.name);
    const redisId = coerceBindingName(attached?.id);
    if (redisName !== undefined || redisId !== undefined) {
      redis.push({ name: redisName ?? "", id: redisId });
    }
    const bucket = binding?.data?.bucket as
      | {
          name?: unknown;
          id?: unknown;
          addOnId?: unknown;
          bucketName?: unknown;
          accessKeyId?: unknown;
          secretAccessKey?: unknown;
          endpoint?: unknown;
          region?: unknown;
        }
      | undefined;
    const bucketName = coerceBindingName(bucket?.name);
    const bucketId = coerceBindingName(bucket?.id) ?? coerceBindingName(bucket?.addOnId);
    if (bucketName !== undefined || bucketId !== undefined) {
      // The bound Bucket's attributes carry the create-time Tigris
      // credentials, which Fly's add-on lookup often returns empty.
      const values: Record<string, string> = {};
      for (const [key, value] of [
        ["BUCKET_NAME", bucket?.bucketName],
        ["AWS_ACCESS_KEY_ID", bucket?.accessKeyId],
        ["AWS_SECRET_ACCESS_KEY", bucket?.secretAccessKey],
        ["AWS_ENDPOINT_URL_S3", bucket?.endpoint],
        ["AWS_REGION", bucket?.region],
      ] as const) {
        const plain = plainEnvValue(value);
        if (plain !== undefined) values[key] = plain;
      }
      buckets.push({ name: bucketName ?? "", id: bucketId, values });
    }
    const pg = binding?.data?.postgres;
    const clusterId = coerceBindingName(pg?.clusterId);
    if (clusterId !== undefined) {
      postgres.push({
        clusterId,
        variableName:
          typeof pg?.variableName === "string" && pg.variableName.length > 0
            ? pg.variableName
            : undefined,
      });
    }
  }
  return { env, mounts, redis, buckets, postgres, targets };
};

/**
 * HTTP 80 → HTTPS redirect plus HTTPS 443 for public Services. Private
 * (Flycast-only) Services publish plain HTTP on 80: Fly issues no
 * certificate for `.flycast`, so a redirect to HTTPS would break callers.
 */
export const defaultHttpServices = (
  port: number,
  count = 1,
  isPublic = true,
): FlyMachineService[] => [
  {
    protocol: "tcp",
    internal_port: port,
    autostart: true,
    autostop: "off",
    min_machines_running: count,
    ports: isPublic
      ? [
          { port: 80, handlers: ["http"], force_https: true },
          { port: 443, handlers: ["tls", "http"] },
        ]
      : [{ port: 80, handlers: ["http"] }],
    // Wait until the process is listening before the proxy sends traffic.
    // Without this, fly.dev hangs (status 0) while Node is still booting.
    checks: [{ type: "tcp", port, interval: "10s", timeout: "2s", grace_period: "30s" }],
  },
];

const sanitizeImageRepo = (id: string): string => {
  const lowered = id
    .toLowerCase()
    .replace(/[^a-z0-9_.-]+/g, "-")
    .replace(/^-+|-+$/g, "");
  return lowered.length === 0 ? "service" : lowered;
};

const generateDockerfile = (
  props: HostedProgramProps,
  hasChunks: boolean,
  install?: Record<string, string>,
  entryRel?: string,
) => {
  const port = props.port ?? DEFAULT_PORT;
  const lines = [`FROM ${props.image ?? DEFAULT_BASE_IMAGE}`, `WORKDIR /app`];
  if (install !== undefined && Object.keys(install).length > 0) {
    lines.push(
      `COPY package.json /app/package.json`,
      `RUN npm install --omit=dev --no-fund --no-audit`,
    );
  }
  if (props.isExternal === true) {
    lines.push(`COPY . /app`);
    const entry = entryRel !== undefined && entryRel.length > 0 ? entryRel : "serve-node.mjs";
    lines.push(
      `ENV PORT=${String(port)}`,
      `ENV HOST=0.0.0.0`,
      `EXPOSE ${String(port)}`,
      `ENTRYPOINT ["node", ${JSON.stringify(`/app/${entry}`)}]`,
    );
    return `${lines.join("\n")}\n`;
  }
  lines.push(`COPY index.mjs /app/index.mjs`);
  if (hasChunks) {
    lines.push(`COPY *.js /app/`);
  }
  const seen = new Set<string>();
  for (const extra of props.extraFiles ?? []) {
    const dest = extraFileDestination(extra.dest);
    if (isContextRootDest(dest) || seen.has(dest)) continue;
    seen.add(dest);
    lines.push(`COPY ${dest} /app/${dest}`);
  }
  lines.push(
    `ENV PORT=${String(port)}`,
    `ENV HOST=0.0.0.0`,
    `EXPOSE ${String(port)}`,
    `ENTRYPOINT ["node", "/app/index.mjs"]`,
  );
  return `${lines.join("\n")}\n`;
};

const installManifest = (dependencies: Record<string, string>) =>
  `${JSON.stringify({ private: true, type: "module", dependencies }, null, 2)}\n`;

export const createFlyHostedSupport = ({
  stackName,
  stage,
  virtualEntryPlugin,
  docker,
  dotAlchemy,
}: {
  stackName: string;
  stage: string;
  virtualEntryPlugin: (content: (importPath: string) => string) => rolldown.Plugin;
  docker: Docker["Service"];
  dotAlchemy: string;
}) => {
  const alchemyEnv = {
    ALCHEMY_STACK_NAME: stackName,
    ALCHEMY_STAGE: stage,
    ALCHEMY_PHASE: "runtime",
    HOST: "0.0.0.0",
  };

  const bundleProgram = Effect.fn(function* (props: HostedProgramProps) {
    const handler = props.handler ?? "default";
    const realMain = yield* resolveMainPath(props.main);
    const cwd = yield* findCwdForBundle(realMain);
    const bootstrap = makeBunBootstrap(handler);
    const requested = yield* normalizeInstallTargets(props.build?.install);
    const installRoots = new Set(Object.keys(requested));
    const configuredExternal = props.build?.input?.external;

    const buildBundle = Effect.fn(function* (
      entry: string,
      plugins?: rolldown.RolldownPluginOption,
    ) {
      return yield* Bundle.build(
        {
          ...props.build?.input,
          input: entry,
          cwd,
          platform: "node",
          external: (moduleId, parentId, isResolved) => {
            if (moduleId === "bun" || moduleId.startsWith("bun:")) return true;
            for (const root of installRoots) {
              if (matchesPackageRoot(moduleId, root)) return true;
            }
            return matchesConfiguredExternal(configuredExternal, moduleId, parentId, isResolved);
          },
          resolve: {
            conditionNames: [...Bundle.NODE_CONDITION_NAMES],
            ...props.build?.input?.resolve,
          },
          plugins: [props.build?.input?.plugins, plugins],
        },
        {
          ...props.build?.output,
          format: "esm",
          sourcemap: props.build?.output?.sourcemap ?? false,
          entryFileNames: "index.mjs",
          strictExecutionOrder: true,
          keepNames: true,
        },
        props.build,
      );
    });

    if (props.isExternal === true) {
      const fs = yield* FileSystem.FileSystem;
      const path = yield* Path.Path;
      const bytes = yield* fs.readFile(realMain);
      const hash = yield* sha256(bytes);
      return { files: [{ path: path.basename(realMain), content: bytes }], hash };
    }

    const bundleOutput = yield* buildBundle(realMain, virtualEntryPlugin(bootstrap));

    const files = bundleOutput.files.map((file) => ({
      path: file.path,
      content:
        typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content,
    }));

    return { files, hash: bundleOutput.hash };
  });

  const computeCodeHash = Effect.fn(function* (props: HostedProgramProps) {
    const bundled = yield* bundleProgram(props);
    const realMain = yield* resolveMainPath(props.main);
    const cwd = yield* findCwdForBundle(realMain);
    const path = yield* Path.Path;
    const requested = yield* normalizeInstallTargets(props.build?.install);
    const identity =
      Object.keys(requested).length > 0
        ? yield* resolvePackageInstallIdentity({ cwd, requested })
        : undefined;
    const install =
      identity !== undefined && Object.keys(identity.resolved).length > 0
        ? identity.resolved
        : undefined;
    const packageJson = install === undefined ? undefined : installManifest(install);
    const extras = (props.extraFiles ?? []).map((file) => ({
      source: file.source,
      dest: file.dest,
    }));
    const root = contextRootOf(realMain, extras, path, (source) =>
      resolveExtraSource(source, path),
    );
    const entryRel =
      props.isExternal === true
        ? (posixRelUnder(root, realMain, path) ?? path.basename(realMain))
        : undefined;
    const dockerfile = generateDockerfile(props, bundled.files.length > 1, install, entryRel);
    const extraFiles = yield* hashExtraFiles(props.extraFiles);
    const codeHash = (yield* sha256Object({
      bundleHash: bundled.hash,
      dockerfile,
      packageJson,
      extraFiles,
      extraFilesIncludesNodeModules: true,
    })).slice(0, 16);
    return { bundled, dockerfile, codeHash, packageJson, entryRel };
  });

  const imageExists = (imageRef: string) =>
    docker.image.inspect(imageRef).pipe(
      Effect.map(() => true),
      Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(false)),
    );

  const pushBackoff = Schedule.exponential("2 seconds");

  /**
   * Bundle `main`, content-hash the image, build it when missing, and
   * push to `registry.fly.io/{appName}:{logicalId}-{hash}` using an
   * app deploy token. When `previousHash` matches, skip build and push.
   *
   * Fly's registry is app-scoped (`/v2/{app}/...`). A nested
   * `{app}/{image}` repository 404s on blob upload.
   */
  const resolveImage = Effect.fn(function* (input: {
    id: string;
    appName: string;
    props: HostedProgramProps;
    previousHash?: string;
    session?: { note: (message: string) => Effect.Effect<void> };
  }) {
    const note = input.session?.note ?? ((_message: string) => Effect.void);
    yield* note(`Bundling ${input.id} program...`);
    const { bundled, dockerfile, codeHash, packageJson } = yield* computeCodeHash(input.props);
    yield* note(`Hashed ${input.id} (${codeHash})`);
    const repo = sanitizeImageRepo(input.id);
    const imageRef = `${FLY_REGISTRY}/${input.appName}:${repo}-${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 };

    const materialize = Effect.gen(function* () {
      const realMain = yield* resolveMainPath(input.props.main);
      const contextDir = yield* getStableContextDir(realMain, dotAlchemy, `${input.id}-image`);
      const fs = yield* FileSystem.FileSystem;
      const path = yield* Path.Path;
      const files =
        input.props.isExternal === true
          ? packageJson !== undefined
            ? [{ path: "package.json", content: new TextEncoder().encode(packageJson) }]
            : []
          : [
              ...bundled.files.map((file, index) => ({
                path: index === 0 ? "index.mjs" : file.path,
                content: file.content,
              })),
              ...(packageJson !== undefined
                ? [{ path: "package.json", content: new TextEncoder().encode(packageJson) }]
                : []),
            ];
      yield* docker.materialize({ context: contextDir, dockerfile, files });
      yield* copyExtraFiles(contextDir, input.props.extraFiles);
      if (input.props.isExternal === true) {
        const extras = (input.props.extraFiles ?? []).map((file) => ({
          source: file.source,
          dest: file.dest,
        }));
        const root = contextRootOf(realMain, extras, path, (source) =>
          resolveExtraSource(source, path),
        );
        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 });
        }
      }
      return contextDir;
    });

    if (input.props.build?.remote !== false) {
      const contextDir = yield* materialize;
      yield* note(`Building ${imageRef} on a Fly remote builder...`);
      yield* buildOnRemoteBuilder({
        docker,
        appName: input.appName,
        contextDir,
        imageRef,
        platform: MACHINE_PLATFORM,
        registry,
        note,
      });
      yield* note(`Pushed ${imageRef}`);
      return { imageRef, codeHash };
    }

    if (!(yield* imageExists(imageRef))) {
      const contextDir = yield* materialize;
      yield* note(`Building container image ${imageRef}...`);
      yield* docker.image.build({ context: contextDir, tag: imageRef, platform: MACHINE_PLATFORM });
      yield* note(`Built ${imageRef}`);
    }

    yield* note(`Pushing ${imageRef}...`);
    yield* docker.image
      .push(imageRef, registry)
      .pipe(Effect.retry({ times: 3, schedule: pushBackoff }));
    yield* note(`Pushed ${imageRef}`);
    return { imageRef, codeHash };
  });

  const hash = Effect.fn(function* (props: HostedProgramProps) {
    const { codeHash } = yield* computeCodeHash(props);
    return codeHash;
  });

  return { alchemyEnv, bundleProgram, computeCodeHash, resolveImage, hash };
};

/**
 * Bundle a Sprite program the same way {@link createFlyHostedSupport}
 * bundles a Service — rolldown + Node bootstrap — without building a
 * Docker image. The provider writes the files onto the Sprite.
 */
export const createSpriteHostedSupport = ({
  stackName,
  stage,
  virtualEntryPlugin,
}: {
  stackName: string;
  stage: string;
  virtualEntryPlugin: (content: (importPath: string) => string) => rolldown.Plugin;
}) => {
  const alchemyEnv = {
    ALCHEMY_STACK_NAME: stackName,
    ALCHEMY_STAGE: stage,
    ALCHEMY_PHASE: "runtime",
    HOST: "0.0.0.0",
  };

  const bundleProgram = Effect.fn(function* (props: HostedProgramProps) {
    const handler = props.handler ?? "default";
    const realMain = yield* resolveMainPath(props.main);
    const cwd = yield* findCwdForBundle(realMain);
    const bootstrap = makeBunBootstrap(handler);

    const buildBundle = Effect.fn(function* (
      entry: string,
      plugins?: rolldown.RolldownPluginOption,
    ) {
      return yield* Bundle.build(
        {
          ...props.build?.input,
          input: entry,
          cwd,
          platform: "node",
          external: [
            "bun",
            "bun:*",
            ...((props.build?.input?.external as string[] | undefined) ?? []),
          ],
          resolve: {
            conditionNames: [...Bundle.NODE_CONDITION_NAMES],
            ...props.build?.input?.resolve,
          },
          plugins: [props.build?.input?.plugins, plugins],
        },
        {
          ...props.build?.output,
          format: "esm",
          sourcemap: props.build?.output?.sourcemap ?? false,
          minify: props.build?.output?.minify ?? false,
          entryFileNames: "index.mjs",
        },
        props.build,
      );
    });

    const bundleOutput = props.isExternal
      ? yield* buildBundle(realMain)
      : yield* buildBundle(realMain, virtualEntryPlugin(bootstrap));

    const files = bundleOutput.files.map((file) => ({
      path: file.path,
      content:
        typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content,
    }));

    return { files, hash: bundleOutput.hash };
  });

  const hash = Effect.fn(function* (props: HostedProgramProps) {
    const bundled = yield* bundleProgram(props);
    return (yield* sha256Object({ bundleHash: bundled.hash })).slice(0, 16);
  });

  return { alchemyEnv, bundleProgram, hash };
};