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

import * as NodeNet from "node:net";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Equal from "effect/Equal";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import { hashDirectory, type MemoOptions } from "../Command/Memo.ts";
import { havePropsChanged, isResolved } from "../Diff.ts";
import * as LocalProvider from "../Local/LocalProvider.ts";
import * as ProviderLayer from "../Local/ProviderLayer.ts";
import * as Provider from "../Provider.ts";
import { Resource } from "../Resource.ts";
import { initialCwd, moduleExtension } from "../Util/Node.ts";
import { sha256Object } from "../Util/sha256.ts";

/**
 * The structural slice of a framework-integration module
 * (`@alchemy.run/frontend-frameworks/nuxt`, `@alchemy.run/frontend-frameworks/astro`, ...) this resource
 * drives. Typed structurally so alchemy carries no dependency on
 * `@distilled.cloud/framework-core` — the *project's* install is always the
 * one loaded. Requirement channels are erased (the module is loaded
 * dynamically, so its effects are typed post-hoc): `build` is
 * requirement-free and `dev` runs in the caller's ambient Scope.
 */
interface FrameworkModule {
  readonly make: (options: Record<string, unknown>) => Effect.Effect<
    {
      readonly build: (options?: {
        readonly root?: string;
        readonly env?: Record<string, string>;
      }) => Effect.Effect<FrameworkBuildOutputSlice, unknown>;
      readonly dev: (options?: {
        readonly root?: string;
        readonly port?: number;
        readonly host?: string;
      }) => Effect.Effect<{ readonly url: string }, unknown>;
    },
    unknown,
    FileSystem.FileSystem | Path.Path
  >;
}

/** The structural slice of framework-core's `BuildOutput` this resource reads. */
interface FrameworkBuildOutputSlice {
  readonly distDirectory?: string | undefined;
  readonly clientDirectory: string | undefined;
  readonly serverModules: Array<{ readonly name: string }> | undefined;
}

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

/** Drops `undefined`-valued entries from {@link ServerProps.env}. */
const definedEnv = (
  env: Record<string, string | undefined> | undefined,
): Record<string, string> | undefined =>
  env === undefined
    ? undefined
    : Object.fromEntries(
        Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
      );

/**
 * Options for the local dev server that runs a framework site under
 * `alchemy dev`.
 *
 * Use `{ mode: "external" }` to skip starting a dev server entirely —
 * useful when an external dev server (e.g. one you run yourself in
 * another terminal) is serving the site instead.
 */
export type ServerDevProps =
  | {
      /**
       * Run the framework's own dev server locally (the default).
       * @default "server"
       */
      mode?: "server";
      /**
       * Host the dev server binds to. Defaults to the framework's own
       * choice (localhost).
       */
      host?: string;
      /**
       * Preferred port for the dev server. Defaults to an ephemeral port.
       * If the port is unavailable, the next free port is used unless
       * {@link strictPort} is `true`.
       */
      port?: number;
      /**
       * When `true`, fail instead of falling back to another port if
       * {@link port} is already in use.
       * @default false
       */
      strictPort?: boolean;
    }
  | {
      /**
       * Don't start a dev server; an external dev server is running instead.
       */
      mode: "external";
      /**
       * URL the external dev server is reachable at, if applicable.
       * This will be returned as the `url` attribute of the Server resource.
       */
      url?: string;
    };

export interface ServerProps {
  /**
   * Module specifier of the framework-integration package that implements
   * the build and dev server (e.g. `"@alchemy.run/frontend-frameworks/nuxt"`). Must be
   * installed in your project — it is loaded dynamically at deploy time and
   * drives your project's own framework toolchain.
   */
  framework: string;
  /**
   * Project root directory (the directory containing the framework config),
   * relative to the process working directory.
   * @default "."
   */
  root?: string;
  /**
   * The deploy target the build is produced for: a module specifier
   * resolved from your project's `node_modules`
   * (e.g. `"@alchemy.run/frontend-frameworks/nuxt/aws"`).
   */
  target: string;
  /**
   * Framework-integration options forwarded to the module's `make()`
   * (e.g. `{ nuxt: { ... } }` config overrides). Must be JSON-serializable —
   * the value participates in the memo hash and is persisted in state.
   */
  options?: Record<string, unknown>;
  /**
   * Options for the local dev server that runs this site under
   * `alchemy dev`. See {@link ServerDevProps}.
   */
  dev?: ServerDevProps;
  /**
   * Environment variables for the framework server. On deploy the
   * composite sets these on the Lambda; during `alchemy dev` they are
   * applied to the dev server's process environment (the dev sidecar and
   * any child it spawns) so server code reads the same values in both
   * modes. Changing a value restarts the dev server.
   *
   * Entries whose value is `undefined` are dropped — this lets website
   * composites forward optional values (e.g. an `Output` service URL that
   * resolves to `undefined`) without filtering first.
   */
  env?: Record<string, string | undefined>;
  /**
   * Controls which files are hashed to decide whether the build should
   * re-run. By default every non-gitignored file in the root is hashed,
   * plus the nearest lockfile. Set `false` to rebuild on every deploy.
   * @default true
   */
  memo?: MemoOptions | boolean;
}

export interface Server extends Resource<
  "Website.Server",
  ServerProps,
  {
    /**
     * Root output directory of the build (e.g. `.output`), relative to the
     * process's initial working directory. `undefined` in dev mode (no
     * production build runs).
     */
    distDir: string | undefined;
    /**
     * Static-assets directory of the build (prerendered pages included),
     * relative to the initial working directory. `undefined` when the build
     * produced no client assets, and in dev mode.
     */
    clientDir: string | undefined;
    /**
     * The server entry module on disk (e.g. `.output/server/index.mjs`),
     * relative to the initial working directory. `undefined` for
     * assets-only builds, and in dev mode.
     */
    serverEntry: string | undefined;
    /**
     * The framework dev server's local URL (e.g. `http://localhost:3000`)
     * during `alchemy dev`. `undefined` on deploys.
     */
    url: string | undefined;
    hash: {
      /**
       * Hash of the input files (plus framework/target/options) that
       * produced this build. `undefined` in dev mode.
       */
      input: string | undefined;
      /**
       * Hash of the build output files. `undefined` in dev mode.
       */
      output: string | undefined;
    };
  }
> {}

/**
 * The framework toolchain half of a website: on `alchemy deploy` it
 * runs the framework's production build with a platform deploy target and
 * tracks the on-disk output in state; on `alchemy dev` it runs the
 * framework's OWN dev server (native HMR via the framework's kit) in the
 * dev sidecar and exposes its local URL. Shared by AWS, Fly, Hetzner, and
 * Railway website composites.
 *
 * The framework package and the target module are loaded from *your*
 * project's `node_modules`, so your project's framework version drives the
 * build. Build inputs are content-hashed so an unchanged project skips the
 * rebuild entirely.
 *
 * ### Building Frameworks
 * **Example:** Nuxt For AWS Lambda
 * ```typescript
 * const server = yield* Server("Server", {
 *   framework: "@alchemy.run/frontend-frameworks/nuxt",
 *   target: "@alchemy.run/frontend-frameworks/nuxt/aws",
 *   root: "./app",
 * });
 * // deploy: server.serverEntry -> .output/server/index.mjs (Lambda handler)
 * //         server.clientDir   -> .output/public (static assets for the CDN)
 * // dev:    server.url         -> http://localhost:<port> (framework HMR server)
 * ```
 *
 * @resource
 */
export const Server = Resource<Server>("Website.Server", {
  aliases: ["AWS.Website.Server", "AWS.Website.FrameworkBuild"],
});

const importFrameworkModule = (specifier: string) =>
  Effect.tryPromise({
    try: () => import(specifier) as Promise<Partial<FrameworkModule>>,
    catch: (cause) =>
      new FrameworkServerError({
        framework: specifier,
        message:
          `Failed to import the framework integration "${specifier}". ` +
          "It must be installed in your project (it is loaded dynamically at deploy time).",
        cause,
      }),
  }).pipe(
    Effect.flatMap((module_) =>
      typeof module_.make === "function"
        ? Effect.succeed(module_ as FrameworkModule)
        : Effect.fail(
            new FrameworkServerError({
              framework: specifier,
              message: `"${specifier}" does not export the framework-integration contract (a "make" function)`,
            }),
          ),
    ),
  );

const makeFramework = (props: ServerProps, root: string) =>
  importFrameworkModule(props.framework).pipe(
    Effect.flatMap((module_) =>
      Effect.mapError(
        module_.make({
          ...props.options,
          root,
          target: props.target,
        }),
        (cause) =>
          new FrameworkServerError({
            framework: props.framework,
            message: "Failed to initialize the framework integration",
            cause,
          }),
      ),
    ),
  );

export const ServerProvider = () =>
  ProviderLayer.dual(Server, {
    live: ServerProviderLive,
    local: ServerProviderLocal,
  });

export const ServerProviderLive = () =>
  Provider.effect(
    Server,
    Effect.gen(function* () {
      const path = yield* Path.Path;
      const fs = yield* FileSystem.FileSystem;

      const runBuild = Effect.fn(function* (props: ServerProps) {
        const root = path.resolve(initialCwd, props.root ?? ".");
        const service = yield* makeFramework(props, root);
        return yield* Effect.mapError(
          service.build({ root, env: definedEnv(props.env) }),
          (cause) =>
            new FrameworkServerError({
              framework: props.framework,
              message: `The ${props.framework} build failed`,
              cause,
            }),
        );
      });

      const hashInput = (props: ServerProps, root: string) =>
        hashDirectory({
          cwd: root,
          memo:
            props.memo === true || props.memo === undefined || props.memo === false
              ? {}
              : props.memo,
        }).pipe(
          Effect.flatMap((files) =>
            sha256Object({
              files,
              framework: props.framework,
              target: props.target,
              options: props.options,
            }),
          ),
        );

      const hashOutput = (props: ServerProps, distDir: string) =>
        hashDirectory({
          cwd: distDir,
          memo: {
            // Next.js serves from its project root, not a dedicated output directory.
            exclude:
              path.resolve(distDir) === path.resolve(initialCwd, props.root ?? ".")
                ? ["**/node_modules/**", "**/.git/**", "**/.alchemy/**", ".next/cache/**"]
                : [],
            lockfile: false,
          },
        });

      const makeOutput = Effect.fn(function* (
        props: ServerProps,
        built: FrameworkBuildOutputSlice,
      ) {
        const root = path.resolve(initialCwd, props.root ?? ".");
        const distDir = built.distDirectory ?? path.join(root, "dist");
        if (!(yield* fs.exists(distDir))) {
          return yield* new FrameworkServerError({
            framework: props.framework,
            message: `The build produced no output directory at ${distDir}`,
          });
        }
        const entryName = built.serverModules?.[0]?.name;
        return {
          distDir: path.relative(initialCwd, distDir),
          clientDir:
            built.clientDirectory !== undefined
              ? path.relative(initialCwd, built.clientDirectory)
              : undefined,
          serverEntry:
            entryName !== undefined
              ? path.relative(initialCwd, path.join(distDir, entryName))
              : undefined,
          url: undefined,
          hash:
            props.memo === false
              ? { input: undefined, output: undefined }
              : yield* Effect.all(
                  {
                    input: hashInput(props, root),
                    output: hashOutput(props, distDir),
                  },
                  { concurrency: "unbounded" },
                ),
        };
      });

      return {
        list: () => Effect.succeed([]),
        diff: Effect.fn(function* ({ olds, news, output }) {
          if (!output || !isResolved(news)) return undefined;
          if (news.memo === false || !output.hash.input || !output.hash.output)
            return { action: "update" };
          if (havePropsChanged(olds, news)) return { action: "update" };
          const root = path.resolve(initialCwd, news.root ?? ".");
          // Cheap check: same inputs + output still on disk with the same
          // content hash -> noop without re-running the build.
          const input = yield* hashInput(news, root);
          if (input !== output.hash.input) return { action: "update" };
          if (output.distDir === undefined) return { action: "update" };
          const distDir = path.resolve(initialCwd, output.distDir);
          if (!(yield* fs.exists(distDir))) return { action: "update" };
          const outHash = yield* hashOutput(news, distDir);
          return {
            action: Equal.equals(outHash, output.hash.output) ? "noop" : "update",
          };
        }),
        reconcile: Effect.fn(function* ({ news }) {
          const built = yield* runBuild(news);
          return yield* makeOutput(news, built);
        }),
        delete: Effect.fn(function* ({ olds, output }) {
          if (output.distDir === undefined) return;
          const root = path.resolve(initialCwd, olds.root ?? ".");
          const distDir = path.resolve(initialCwd, output.distDir);
          if (!(yield* fs.exists(root)) || !(yield* fs.exists(distDir))) return;
          // Some frameworks (Next.js) serve from the project root itself.
          // Only dedicated output directories inside that root are disposable.
          // Canonical paths also protect roots reached through a symlink.
          const relative = path.relative(yield* fs.realPath(root), yield* fs.realPath(distDir));
          if (
            relative === "" ||
            relative === ".." ||
            relative.startsWith(`..${path.sep}`) ||
            path.isAbsolute(relative)
          )
            return;
          yield* fs.remove(distDir, { recursive: true });
        }),
      };
    }),
  );

/**
 * Try to bind `port` on `host`; resolves `true` when the port is free.
 * The listener is closed immediately — the port is only observed
 * available, not reserved, so the caller should bind promptly and the
 * framework still handles the (tiny) race window itself.
 */
const isPortFree = (port: number, host: string) =>
  Effect.callback<boolean>((resume) => {
    const server = NodeNet.createServer();
    server.unref();
    server.once("error", () => resume(Effect.succeed(false)));
    server.listen(port, host, () => {
      server.close(() => resume(Effect.succeed(true)));
    });
  });

/**
 * Resolve the dev server's port from the `dev` props: probe the preferred
 * port and either fail (`strictPort`) or walk forward to the next free
 * port when it is taken.
 */
const resolveDevPort = Effect.fn(function* (options: {
  readonly framework: string;
  readonly port: number;
  readonly host: string;
  readonly strictPort: boolean;
}) {
  const { framework, port, host, strictPort } = options;
  if (yield* isPortFree(port, host)) return port;
  if (strictPort) {
    return yield* new FrameworkServerError({
      framework,
      message: `Port ${port} is already in use and \`dev.strictPort\` is set`,
    });
  }
  for (let candidate = port + 1; candidate <= port + 100; candidate++) {
    if (yield* isPortFree(candidate, host)) return candidate;
  }
  return yield* new FrameworkServerError({
    framework,
    message: `No free port found between ${port} and ${port + 100}`,
  });
});

/**
 * A framework dev server may advertise its *bind* address — nuxt echoes the
 * host it was told to listen on, so a Router-attached site (which binds
 * `0.0.0.0` to be reachable from the emulator container) reports
 * `http://0.0.0.0:{port}/`. The unspecified address is not a connectable
 * host: normalize it to `localhost` for the `url` attribute (browser links,
 * Router dev routing, the emulated CloudFront edge dialing the origin). The
 * server itself still listens on every interface.
 */
const normalizeAdvertisedUrl = (url: string) =>
  url.replace(/^(https?:\/\/)(?:0\.0\.0\.0|\[::\]|\[0+(?::0+){7}\])(?=[:/]|$)/, "$1localhost");

/**
 * The `alchemy dev` variant: runs the framework's own dev server (native
 * HMR through the framework's kit — nuxt, astro, ...) inside the dev
 * sidecar, so it survives user-code hot reloads. Restarts when the
 * framework/target/root/options config changes.
 */
export const ServerProviderLocal = () =>
  LocalProvider.make(
    Server,
    import.meta.resolve(`./ServerLocal${moduleExtension(import.meta.url)}`, import.meta.url),
    Effect.gen(function* () {
      const path = yield* Path.Path;
      const fs = yield* FileSystem.FileSystem;
      return {
        start: Effect.fn(function* ({ news: props }) {
          // External mode: an external dev server (run out-of-band by the
          // user) serves the site — don't import the framework or spawn
          // anything, just surface the external URL as the attribute.
          if (props.dev?.mode === "external") {
            return {
              distDir: undefined,
              clientDir: undefined,
              serverEntry: undefined,
              url: props.dev.url,
              hash: { input: undefined, output: undefined },
            };
          }
          const dev = props.dev;
          const root = path.resolve(initialCwd, props.root ?? ".");
          // Dev/live env parity: the composite sets these on the Lambda on
          // deploy; in dev the framework server runs inside the sidecar
          // (or as its child — `next dev`), so the sidecar's process env
          // is what SSR code reads. `env` is part of the restart surface,
          // so a changed value restarts the dev server with the new
          // environment. Values are not unset on stop: sibling dev servers
          // share the process, so clearing could clobber their keys.
          if (props.env !== undefined) {
            yield* Effect.sync(() => {
              for (const [key, value] of Object.entries(props.env!)) {
                if (value === undefined) continue;
                process.env[key] = String(value);
              }
            });
          }
          const service = yield* makeFramework(props, root).pipe(
            Effect.provideService(FileSystem.FileSystem, fs),
            Effect.provideService(Path.Path, path),
          );
          // Resolve the port BEFORE handing off to the framework: probe
          // the preferred port, fail on `strictPort`, otherwise walk
          // forward to the next free port. Without a preferred port the
          // framework picks its own (ephemeral) port.
          const port =
            dev?.port !== undefined
              ? yield* resolveDevPort({
                  framework: props.framework,
                  port: dev.port,
                  host: dev.host ?? "127.0.0.1",
                  strictPort: dev.strictPort ?? false,
                })
              : undefined;
          // `dev` is scoped: the server lives in the instance scope the
          // LocalProvider helper provides and is torn down on
          // restart/delete. It resolves at readiness with the local URL.
          const { url } = yield* Effect.mapError(
            service.dev({ root, port, host: dev?.host }),
            (cause) =>
              new FrameworkServerError({
                framework: props.framework,
                message: `The ${props.framework} dev server failed to start`,
                cause,
              }),
          );
          return {
            distDir: undefined,
            clientDir: undefined,
            serverEntry: undefined,
            url: normalizeAdvertisedUrl(url),
            hash: { input: undefined, output: undefined },
          };
        }),
      } satisfies LocalProvider.LocalProviderSpec<Server>;
    }),
  );