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

import { AlchemyContext } from "alchemy/AlchemyContext";
import type { MemoOptions } from "alchemy/Command/Memo";
import * as DNS from "alchemy/DNS/Adapter";
import type { Input } from "alchemy/Input";
import * as Namespace from "alchemy/Namespace";
import * as Output from "alchemy/Output";
import { ProviderModePolicy } from "alchemy/ProviderMode";
import { initialCwd } from "alchemy/Util/Node";
import {
  staticConfigFromAssets,
  type WebsiteAssetsProps,
  type WebsiteNotFoundHandling,
} from "alchemy/Website/assets";
import { packSiteExtraFiles } from "alchemy/Website/packExtraFiles";
import { Server as FrameworkServer, type ServerDevProps } from "alchemy/Website/Server";
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 { App } from "../App.ts";
import { Bucket } from "../Bucket.ts";
import { Certificate, type CertificateDnsRequirements } from "../Certificate.ts";
import { IpAssignment } from "../IpAssignment.ts";
import type { Providers } from "../Providers.ts";
import { Service, type ServiceProps } from "../Service.ts";
import { AssetDeployment } from "./AssetDeployment.ts";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* App(...)` and `App(...)` both type-check).
 */
export type Ref<T> = T | Effect.Effect<T, never, Providers>;

export type { ServerDevProps, WebsiteAssetsProps, WebsiteNotFoundHandling };
export { staticConfigFromAssets };

/**
 * Custom hostname of a Fly website: the hostname itself, or
 * `{ name, dns }` to also publish its DNS records.
 */
export type WebsiteDomain =
  | string
  | {
      /** Hostname, e.g. `www.example.com`. */
      name: string;
      /**
       * DNS host that publishes the hostname's records (see
       * [DNS Adapters](/infrastructure-as-code/dns-adapters)), e.g.
       * `Cloudflare.DNS.Adapter()`: the ACME challenge `CNAME` Fly lists in
       * the Certificate's `dnsRequirements`, and `A` / `AAAA` records at
       * the site's addresses. Omitted: publish the records yourself.
       */
      dns?: DNS.DnsConfig;
    };

/** The hostname of a {@link WebsiteDomain}. */
export const websiteDomainName = (domain: WebsiteDomain | undefined): string | undefined =>
  domain === undefined || typeof domain === "string" ? domain : domain.name;

const acmeChallengeRecords = (
  hostname: string,
  requirements: CertificateDnsRequirements | undefined,
): DNS.DnsRecord[] => {
  const challenge = requirements?.acmeChallenge;
  if (challenge?.target === undefined || challenge.target.length === 0) {
    return [];
  }
  const expected = `_acme-challenge.${hostname}`;
  const name =
    challenge.name !== undefined &&
    DNS.normalizeDnsName(challenge.name).endsWith(DNS.normalizeDnsName(hostname))
      ? challenge.name
      : expected;
  return [{ name, type: "CNAME", value: challenge.target }];
};

/**
 * Publish a Fly website's records through `domain.dns`: the Certificate's
 * ACME challenge `CNAME` (`CertificateValidation`) and `A` / `AAAA`
 * records at the site's shared IPv4 plus any IPv6 Fly lists for the
 * hostname (`Domain`). No-op for a plain hostname or an object without
 * `dns`.
 */
export const publishWebsiteDomainDns = Effect.fn("Fly.Website.publishDomainDns")(function* (args: {
  readonly domain: WebsiteDomain;
  readonly certificate: Certificate;
  readonly ip: IpAssignment;
}) {
  if (typeof args.domain === "string" || args.domain.dns === undefined) {
    return;
  }
  const dns = yield* DNS.resolve(args.domain.dns);
  const name = args.domain.name;
  yield* dns.records("CertificateValidation", {
    records: Output.map(args.certificate.dnsRequirements, (requirements) =>
      acmeChallengeRecords(name, requirements),
    ) as unknown as Input<DNS.DnsRecord[]>,
  });
  yield* dns.alias("Domain", {
    name,
    target: {
      ipv4: Output.map(args.ip.ip, (ip) => [ip]) as unknown as Input<string[]>,
      ipv6: Output.map(
        args.certificate.dnsRequirements,
        (requirements) => requirements?.aaaa ?? [],
      ) as unknown as Input<string[]>,
    },
  });
});

/**
 * Props shared by every Fly framework website composite.
 */
export interface FrameworkSiteProps {
  /** Deployment strategy forwarded to the hosted Fly Service. */
  deploy?: ServiceProps["deploy"];
  /** Process shutdown policy. The framework server must handle the signal. */
  shutdown?: ServiceProps["shutdown"];
  /** Named Machine readiness checks. */
  checks?: ServiceProps["checks"];
  /** Override proxy services and their routing health checks. */
  services?: ServiceProps["services"];
  /**
   * Project root directory (the directory containing `package.json`).
   * @default "."
   */
  rootDir?: string;
  /**
   * Controls which files are hashed to decide whether the build re-runs.
   * @default true
   */
  memo?: MemoOptions | boolean;
  /**
   * Parent Fly App. Accepts a `Fly.App` or an Effect that produces one.
   * When omitted, a `Fly.App` is created under this site's namespace.
   */
  app?: Ref<App>;
  /**
   * Process environment for the hosted server. Not Cloudflare Worker
   * bindings — values become Machine env vars. Accepts `Output`s
   * (e.g. `VITE_API_URL: api.url`).
   */
  env?: Record<string, string | Redacted.Redacted<string> | Output.Output<string | undefined>>;
  /**
   * Static-asset routing (`notFoundHandling`, `htmlHandling`). Hashed
   * client files are uploaded to Tigris regardless of this bag.
   */
  assets?: WebsiteAssetsProps;
  /**
   * Options for the local dev server that runs this site under
   * `alchemy dev`.
   */
  dev?: ServerDevProps;
  /**
   * Optional custom hostname. Requests ACME (`Fly.Certificate`) on the
   * App and `url` becomes `https://<domain>`.
   *
   * A string (or `{ name }`) leaves DNS to you. Set `dns` (e.g.
   * `{ name: "www.example.com", dns: Cloudflare.DNS.Adapter() }`) to
   * publish the ACME challenge `CNAME` and the `A` / `AAAA` records
   * through that DNS host. See
   * [DNS Adapters](/infrastructure-as-code/dns-adapters).
   */
  domain?: WebsiteDomain;
  /**
   * User-defined tags. Accepted for API parity; Fly Services do not
   * surface resource tags.
   */
  tags?: Record<string, string>;
}

/** Per-framework wiring for {@link makeFrameworkSite}. */
export interface FrameworkSiteConfig {
  /** Display name used in error messages (e.g. `"SvelteKit"`). */
  name: string;
  /** Framework-integration module specifier. */
  framework: string;
  /** Node deploy-target module specifier. */
  target: string;
  /**
   * Framework-specific build options forwarded to the integration (e.g.
   * `{ kit }`, `{ nuxt }`, `{ astro }`). Must be JSON-serializable.
   */
  options?: Record<string, unknown> | undefined;
  /**
   * Assets-only routing forwarded to the Node target (Vite SPA fallback).
   * `spa` also publishes client files to Tigris at `/`.
   */
  static?: { spa?: boolean; errorPage?: string } | undefined;
  /**
   * Vocs/Waku: serve `about/index.html` at `/about`.
   * @default "none"
   */
  htmlHandling?: "none" | "drop-trailing-slash";
  /**
   * Packages installed into the Machine image with `npm install` instead
   * of bundling (Next.js needs `next`).
   */
  install?: string[] | undefined;
  /**
   * Skip baking `clientDirectory` at `/app/dist`. Next.js serves `.next`
   * from the image root instead.
   */
  skipClientAssets?: boolean | undefined;
}

export interface FrameworkSite {
  /**
   * Public site URL. Local framework URL under `alchemy dev`;
   * `https://{app}.fly.dev` (or `https://{domain}`) on deploy.
   */
  url: string | Output.Output<string | undefined> | undefined;
  /** Parent Fly App. `undefined` during `alchemy dev`. */
  app: App | undefined;
  /** Hosted Fly Service. `undefined` during `alchemy dev`. */
  service: Service | undefined;
  /** Shared Anycast IPv4 so `{app}.fly.dev` answers. */
  ip: IpAssignment | undefined;
  /** ACME certificate when {@link FrameworkSiteProps.domain} is set. */
  certificate: Certificate | undefined;
}

export class FrameworkSiteError extends Data.TaggedError("FrameworkSiteError")<{
  readonly framework: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

const DEFAULT_PORT = 3000;

const resolveRef = <T>(ref: Ref<T>): Effect.Effect<T, never, Providers> =>
  Effect.isEffect(ref) ? ref : Effect.succeed(ref);

const envRecord = (
  env:
    | Record<string, string | Redacted.Redacted<string> | Output.Output<string | undefined>>
    | undefined,
): Record<string, string | Output.Output<string | undefined>> | undefined => {
  if (env === undefined) return undefined;
  return Object.fromEntries(
    Object.entries(env).map(([key, value]) => [
      key,
      Redacted.isRedacted(value) ? Redacted.value(value) : value,
    ]),
  );
};

const runFrameworkSite = Effect.fn("Fly.Website.FrameworkSite")(function* (
  _id: string,
  props: FrameworkSiteProps,
  config: FrameworkSiteConfig,
) {
  const ctx = yield* AlchemyContext;
  const remoted = yield* ProviderModePolicy;
  const isLocal = ctx.dev && remoted !== true;
  const path = yield* Path.Path;
  const fs = yield* FileSystem.FileSystem;

  const build = yield* FrameworkServer("Build", {
    framework: config.framework,
    target: config.target,
    root: props.rootDir,
    env: envRecord(props.env),
    options: config.options,
    memo: props.memo,
    dev: props.dev,
  });

  if (isLocal) {
    return {
      url: build.url,
      app: undefined,
      service: undefined,
      ip: undefined,
      certificate: undefined,
    } satisfies FrameworkSite;
  }

  // The build runs at APPLY time (`Website.Server` is a resource), so its
  // attributes are Outputs here — derive every deploy input lazily and let
  // the engine resolve them once the build has produced real paths. Reading
  // `build.distDir` eagerly in the composite body would observe an Output
  // proxy, not a string.
  const buildOut = Output.mapEffect(
    ([serverEntry, distDir]: [string | undefined, string | undefined]) =>
      Effect.gen(function* () {
        if (serverEntry === undefined || distDir === undefined) {
          return yield* Effect.die(
            new FrameworkSiteError({
              framework: config.framework,
              message: `The ${config.name} build produced no Node serve entry (serverModules[0]). The Node deploy target should write serve-node.mjs.`,
            }),
          );
        }
        const main = path.resolve(initialCwd, serverEntry);
        if (!(yield* fs.exists(main).pipe(Effect.orElseSucceed(() => false)))) {
          return yield* Effect.die(
            new FrameworkSiteError({
              framework: config.framework,
              message: `The ${config.name} build produced no server entry at ${main}`,
            }),
          );
        }
        return { distDir: path.resolve(initialCwd, distDir), main };
      }),
  )(
    Output.all(
      build.serverEntry as unknown as Output.Output<string | undefined>,
      build.distDir as unknown as Output.Output<string | undefined>,
    ) as unknown as Output.Output<[string | undefined, string | undefined]>,
  );
  const main = Output.map(buildOut, (out) => out.main);

  const extraFiles = Output.mapEffect((out: { distDir: string; main: string }) =>
    packSiteExtraFiles(out.distDir, config.skipClientAssets === true ? "next" : "client"),
  )(buildOut);

  const app = props.app !== undefined ? yield* resolveRef(props.app) : yield* App("App");

  const ip = yield* IpAssignment("Shared", {
    app,
    type: "shared_v4",
  });

  // SPA: hashed `/assets` at Tigris. HTML and unknown paths stay on
  // origin (NodeServe `notFoundHandling: "spa"`). Intercepting `/` with
  // Tigris hangs SPA fallbacks — Fly does not rewrite `/counter/42` to
  // `index.html`.
  let statics:
    | Output.Output<
        | Array<{
            guestPath: string;
            urlPrefix: string;
            tigrisBucket?: string;
            indexDocument?: string;
          }>
        | undefined
      >
    | undefined;
  if (config.static?.spa === true) {
    const clientDir = Output.map(
      build.clientDir as unknown as Output.Output<string | undefined>,
      (dir) => {
        if (dir === undefined) {
          throw new FrameworkSiteError({
            framework: config.framework,
            message: `The ${config.name} build produced no client assets directory`,
          });
        }
        return path.resolve(initialCwd, dir);
      },
    );
    const bucket = yield* Bucket("Assets", { public: true });
    yield* AssetDeployment("Files", {
      bucket,
      sourcePath: clientDir as unknown as string,
      purge: true,
    });
    statics = Output.mapEffect(([clientDir, bucketName]: [string, string]) =>
      Effect.gen(function* () {
        const assetsDir = path.join(clientDir, "assets");
        const exists = yield* fs.exists(assetsDir).pipe(Effect.orElseSucceed(() => false));
        return exists
          ? [
              {
                guestPath: "/assets",
                urlPrefix: "/assets",
                tigrisBucket: bucketName,
              },
            ]
          : undefined;
      }),
    )(
      Output.all(
        clientDir,
        bucket.name as unknown as Output.Output<string>,
      ) as unknown as Output.Output<[string, string]>,
    );
  }

  const service = yield* Service("Service", {
    app,
    deploy: props.deploy,
    shutdown: props.shutdown,
    checks: props.checks,
    services: props.services,
    main: main as unknown as string,
    port: DEFAULT_PORT,
    // Node + nitro SSR needs more than the Machine default 256MB.
    guest: { memoryMb: 512 },
    isExternal: true,
    env: props.env,
    extraFiles: extraFiles as unknown as Array<{
      source: string;
      dest: string;
    }>,
    statics: statics as unknown as
      | Array<{
          guestPath: string;
          urlPrefix: string;
          tigrisBucket?: string;
          indexDocument?: string;
        }>
      | undefined,
    build:
      config.install !== undefined && config.install.length > 0
        ? { install: config.install }
        : undefined,
  });

  const domainName = websiteDomainName(props.domain);
  const certificate =
    domainName !== undefined
      ? yield* Certificate("Certificate", {
          app,
          hostname: domainName,
          kind: "acme",
        })
      : undefined;
  if (props.domain !== undefined && certificate !== undefined) {
    yield* publishWebsiteDomainDns({ domain: props.domain, certificate, ip });
  }

  const url = domainName !== undefined ? `https://${domainName}` : app.url;

  return { url, app, service, ip, certificate };
});

/**
 * Shared implementation behind the Fly framework website composites:
 * `Website.Server` runs the framework toolchain (dev sidecar / production
 * build), then a live deploy hosts `serve-node.mjs` on a Fly.Service.
 *
 * Callers pipe `Namespace.push(id)` themselves (the composites do).
 *
 * Composite-level tagged errors (`FrameworkSiteError`, filesystem) are
 * defects — `Alchemy.Stack` only admits `ConfigError` on the user
 * effect, same as Cloudflare/AWS Website composites.
 */
export const makeFrameworkSite = (
  id: string,
  props: FrameworkSiteProps,
  config: FrameworkSiteConfig,
) => runFrameworkSite(id, props, config).pipe(Effect.orDie);

/** Push {@link id} then run {@link makeFrameworkSite}. */
export const frameworkSite = (id: string, props: FrameworkSiteProps, config: FrameworkSiteConfig) =>
  makeFrameworkSite(id, props, config).pipe(Namespace.push(id));