sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ nextjs/ aws.ts

import type * as NodeChildProcessModule from "node:child_process";
import { createRequire } from "node:module";
import type * as NodeNet from "node:net";
import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import * as ChildProcess from "effect/process/ChildProcess";
import type * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import { makeChildOutput } from "../core/ChildOutput.ts";
import { logChildOutput } from "../core/ChildOutput.ts";
/**
 * `@alchemy.run/frontend-frameworks/nextjs/aws` — Next.js on AWS Lambda via
 * `@opennextjs/aws`.
 *
 * Unlike the Cloudflare Next.js integration (`./index.ts`, a
 * `Layer<Framework>` over the `@opennextjs/cloudflare` pipeline), this module
 * exports the standalone framework-module contract alchemy's
 * `AWS.Website.Server` resource drives directly: `make(options)` resolves to
 * `{ build, dev }`.
 *
 * - **`build`** drives the `@opennextjs/aws` build CLI (resolved from the
 *   *project's* dependency tree) in a disposable child process — the pipeline
 *   mutates cwd-coupled module state, spawns `next build`, and can
 *   `process.exit(1)`, so it must never run in the calling process. When the
 *   project has no `open-next.config.ts`, a minimal default is generated with
 *   the `aws-lambda-streaming` wrapper so the emitted handler streams on a
 *   Lambda Function URL (`invokeMode: RESPONSE_STREAM`). After the build, the
 *   authoritative `.open-next/open-next.output.json` manifest is read to
 *   verify the default origin is a streaming function.
 * - **`dev`** runs the real `next dev` through Next's documented custom-server
 *   API (`next({ dev: true })` + `prepare()` + `getRequestHandler()` on an
 *   http server we own) — plain Node, which is already the AWS Lambda
 *   programming model. Scoped: closing the Scope stops the app and the server.
 *
 * The OpenNext output topology the alchemy composite (`AWS.Website.Nextjs`)
 * deploys from `.open-next/`:
 *
 * - `server-functions/default/` — the SSR server Lambda (`index.handler`)
 * - `image-optimization-function/` — the image optimizer Lambda (sharp, arm64)
 * - `revalidation-function/` — the ISR revalidation consumer Lambda
 * - `assets/` — static assets for the CDN (`_next/static`, `public/`, BUILD_ID)
 * - `cache/` — the ISR/fetch cache seed (uploaded under the cache prefix)
 * - `dynamodb-provider/` — the tag-cache table seed function
 */
import * as FrameworkCore from "../core/index.ts";
import { buildStandalone } from "./standalone.ts";

const fail = (message: string) => (cause: unknown) =>
  new FrameworkCore.FrameworkError({ framework: "nextjs", message, cause });

/** Options for the Next.js AWS framework module. */
export interface NextjsAwsOptions {
  /** Project root. Defaults to the process working directory. */
  readonly root?: string | undefined;
  /**
   * The deploy target module specifier the caller resolved this module as.
   * This module IS the AWS target — the option is accepted (the
   * `AWS.Website.Server` resource always passes it) and ignored.
   */
  readonly target?: string | undefined;
  /**
   * Path of the OpenNext config, relative to the project root. When the file
   * does not exist, a minimal default with the `aws-lambda-streaming` wrapper
   * is generated ({@link DEFAULT_OPEN_NEXT_CONFIG}).
   * @default "open-next.config.ts"
   */
  readonly configPath?: string | undefined;
  /**
   * Extra CLI arguments appended to `open-next build` (e.g.
   * `["--dangerously-use-unsupported-next-version"]`).
   */
  readonly buildArgs?: ReadonlyArray<string> | undefined;
  /**
   * What runs the server. `"web-function"` builds Next's own standalone
   * server for a Lambda Web Function, with no OpenNext (see
   * `./standalone.ts`). `"function"` builds the OpenNext topology with a
   * streaming Lambda handler for a Function URL.
   * @default "function"
   */
  readonly server?: "web-function" | "function" | undefined;
}

/** The default server-module name of the server's Lambda entry (the actual
 * name is derived from `open-next.output.json` after the build). */
export const SERVER_ENTRY_NAME = "server-functions/default/index.mjs";

/**
 * Derive the entry-module name (relative to `.open-next/`) from the output
 * manifest's default origin: `bundle` (e.g. `.open-next/server-functions/
 * default`) plus the file half of `handler` (`index.handler` → `index.mjs`).
 */
export const deriveServerEntryName = (origin: {
  readonly handler?: string;
  readonly bundle?: string;
}): string => {
  const bundle = (origin.bundle ?? ".open-next/server-functions/default")
    .replace(/^\.open-next\//, "")
    .replace(/\/+$/, "");
  const handler = origin.handler ?? "index.handler";
  const file = handler.split(".").slice(0, -1).join(".") || "index";
  return `${bundle}/${file}.mjs`;
};

/** First line of every config this module generates. */
const GENERATED_CONFIG_HEADER = "// Generated by @alchemy.run/frontend-frameworks/nextjs/aws.";

/**
 * The minimal `open-next.config.ts` generated when the project has none:
 * the default (and only) server uses the `aws-lambda-streaming` wrapper so
 * the emitted handler wraps `awslambda.streamifyResponse` and expects a
 * Function URL with `invokeMode: RESPONSE_STREAM`.
 */
export const DEFAULT_OPEN_NEXT_CONFIG = `${GENERATED_CONFIG_HEADER}
// The default OpenNext config for the AWS topology alchemy deploys: the
// server streams its response on a Lambda Function URL. Edit freely, but
// keep the streaming wrapper — the Function URL is created with
// invokeMode: RESPONSE_STREAM.
const config = {
  default: {
    override: {
      wrapper: "aws-lambda-streaming",
    },
  },
};

export default config;
`;

/** The structural slice of `open-next.output.json` this module reads. */
interface OpenNextOutputManifest {
  readonly origins?: {
    readonly default?: {
      readonly type?: string;
      readonly handler?: string;
      readonly bundle?: string;
      readonly streaming?: boolean;
    };
  };
}

/**
 * Resolve the `@opennextjs/aws` CLI entry (`dist/index.js`, the `open-next`
 * bin) from the *project's* dependency tree. The package's exports map has
 * only a `"./*" -> "./dist/*"` pattern (no `"."` and no `./package.json`
 * subpath), so the `index.js` subpath is the one stable resolvable path.
 */
const resolveOpenNextCli = (root: string) =>
  Effect.try({
    try: () => {
      const require = createRequire(`${root.replace(/\/+$/, "")}/package.json`);
      return require.resolve("@opennextjs/aws/index.js");
    },
    catch: fail(
      `Failed to resolve "@opennextjs/aws" from ${root}. ` +
        "It must be installed in your project (it drives the Next.js build).",
    ),
  });

/**
 * Run `open-next build` in a disposable node child process with the project
 * root as cwd. Output is piped and re-emitted through the parent's own
 * stdout/stderr JS streams (NOT `stdio: "inherit"`) so in-process capture —
 * a test runner's log file — sees the build output.
 */
const runOpenNextBuild = (options: {
  readonly root: string;
  readonly cli: string;
  readonly configPath: string;
  readonly extraArgs: ReadonlyArray<string>;
  readonly env: Record<string, string> | undefined;
}) =>
  Effect.scoped(
    Effect.gen(function* () {
      // Always plain `node` (never bun/`process.execPath`): the OpenNext CLI
      // mutates its own process.env (NEXT_PRIVATE_STANDALONE,
      // NEXT_PRIVATE_OUTPUT_TRACE_ROOT) before exec'ing `next build`, and
      // those mutations do not reliably reach execSync children under bun.
      // `next build` must run as production, like `nextjs/node.ts` and
      // `BuildChild`: an inherited NODE_ENV (left by an in-process dev server
      // in the same long-lived process) breaks prerendering `/_global-error`
      // ("Cannot read properties of null (reading 'useContext')").
      const env = yield* Effect.sync(() => ({
        ...process.env,
        NODE_ENV: "production",
        ...options.env,
      }));
      const child = yield* ChildProcess.make(
        "node",
        [options.cli, "build", "--config-path", options.configPath, ...options.extraArgs],
        {
          cwd: options.root,
          stdin: "ignore",
          stdout: "pipe",
          stderr: "pipe",
          env,
        },
      ).pipe(
        Effect.mapError(fail("Failed to spawn the @opennextjs/aws build CLI (is `node` on PATH?)")),
      );
      // Build output becomes log records, so the process that renders logs
      // shows it and in-process capture (a test runner's log file) sees it.
      const forward = (
        stream: Stream.Stream<Uint8Array, PlatformError>,
        name: "stdout" | "stderr",
      ) =>
        stream.pipe(
          Stream.decodeText,
          Stream.splitLines,
          Stream.runForEach((line) => logChildOutput(line, name)),
        );
      const { exitCode } = yield* Effect.all(
        {
          exitCode: child.exitCode,
          stdout: forward(child.stdout, "stdout"),
          stderr: forward(child.stderr, "stderr"),
        },
        { concurrency: "unbounded" },
      ).pipe(Effect.mapError(fail("Failed reading the OpenNext build's output")));
      if (exitCode !== 0) {
        return yield* fail(`The OpenNext build exited with code ${exitCode}`)(undefined);
      }
    }),
  );

// ---------------------------------------------------------------------------
// dev — the real `next dev` CLI in a child process
// ---------------------------------------------------------------------------

/**
 * Resolve the *project's* `next` CLI entry (`next/dist/bin/next`). The
 * app's installed copy is the one driven, never a hoisted sibling.
 */
const resolveNextCli = (root: string) =>
  Effect.try({
    try: () => {
      const require = createRequire(`${root.replace(/\/+$/, "")}/package.json`);
      return require.resolve("next/dist/bin/next");
    },
    catch: fail(
      `Failed to resolve "next" from ${root}. ` + "It must be installed in your project.",
    ),
  });

/** Bind an ephemeral port and release it, returning the port number. */
const pickEphemeralPort: Effect.Effect<number, FrameworkCore.FrameworkError> = Effect.callback(
  (resume) => {
    const net = createRequire(import.meta.url)("net") as typeof NodeNet;
    const server = net.createServer();
    server.once("error", (cause) =>
      resume(Effect.fail(fail("Failed to allocate an ephemeral port")(cause))),
    );
    server.listen(0, "127.0.0.1", () => {
      const address = server.address();
      if (address === null || typeof address === "string") {
        server.close();
        resume(Effect.fail(fail("No TCP address for the port probe")(null)));
        return;
      }
      const port = address.port;
      server.close(() => resume(Effect.succeed(port)));
    });
  },
);

interface NextDevChild {
  readonly exited: () => boolean;
  readonly output: () => string;
}

/**
 * Spawn `node <next CLI> dev -p <port>` with the project root as cwd,
 * scoped: closing the Scope kills the process tree (SIGTERM, then SIGKILL).
 * Always plain `node` — the AWS Lambda programming model.
 */
const spawnNextDev = (options: {
  readonly root: string;
  readonly cli: string;
  readonly port: number;
  readonly host?: string | undefined;
}): Effect.Effect<NextDevChild, FrameworkCore.FrameworkError, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.flatMap(makeChildOutput, (childOutput) =>
      Effect.try({
        try: () => {
          const cp = createRequire(import.meta.url)(
            "child_process",
          ) as typeof NodeChildProcessModule;
          const child = cp.spawn(
            "node",
            [
              options.cli,
              "dev",
              "-p",
              String(options.port),
              ...(options.host !== undefined ? ["-H", options.host] : []),
            ],
            {
              cwd: options.root,
              stdio: ["ignore", "pipe", "pipe"],
              detached: false,
            },
          );
          let exited = false;
          let output = "";
          const capture = (chunk: unknown) => {
            output += String(chunk);
            if (output.length > 65536) output = output.slice(-32768);
          };
          child.stdout?.on("data", (chunk: unknown) => {
            capture(chunk);
            childOutput.stdout.push(String(chunk));
          });
          child.stderr?.on("data", (chunk: unknown) => {
            capture(chunk);
            childOutput.stderr.push(String(chunk));
          });
          // Output without a trailing newline is still a line once the
          // streams close.
          child.once("close", () => {
            childOutput.stdout.flush();
            childOutput.stderr.flush();
          });
          child.once("exit", () => {
            exited = true;
          });
          return {
            child,
            handle: {
              exited: () => exited,
              output: () => output,
            } satisfies NextDevChild,
          };
        },
        catch: fail("Failed to spawn the next dev CLI (is `node` on PATH?)"),
      }),
    ),
    ({ child }) =>
      Effect.callback<void>((resume) => {
        if (child.exitCode !== null) {
          resume(Effect.void);
          return;
        }
        const killTimer = setTimeout(() => child.kill("SIGKILL"), 3000);
        child.once("exit", () => {
          clearTimeout(killTimer);
          resume(Effect.void);
        });
        child.kill("SIGTERM");
      }),
  ).pipe(Effect.map(({ handle }) => handle));

/**
 * Poll the dev server URL until it answers any HTTP response. Fails fast
 * when the child exits before becoming ready.
 */
const awaitNextDevReady = (options: {
  readonly url: string;
  readonly child: NextDevChild;
}): Effect.Effect<void, FrameworkCore.FrameworkError> =>
  Effect.gen(function* () {
    for (let attempt = 0; attempt < 240; attempt++) {
      if (options.child.exited()) {
        return yield* fail(
          `The next dev CLI exited before becoming ready:\n${options.child.output().slice(-4000)}`,
        )(undefined);
      }
      const ready = yield* Effect.tryPromise({
        try: async () => {
          const response = await fetch(options.url, {
            signal: AbortSignal.timeout(2000),
          });
          return response.status < 600;
        },
        catch: () => "not-ready" as const,
      }).pipe(Effect.orElseSucceed(() => false));
      if (ready) return;
      yield* Effect.sleep(500);
    }
    return yield* fail(`Timed out waiting for the next dev server at ${options.url}`)(undefined);
  });

/** The service shape {@link make} resolves to (the framework-module contract
 * `AWS.Website.Server` drives; `serverModules` carries names only — the AWS
 * deploy ships the OpenNext bundles from disk, never in-memory). */
export interface NextjsAwsService {
  readonly build: (options?: FrameworkCore.FrameworkBuildOptions) => Effect.Effect<
    {
      readonly distDirectory: string;
      readonly clientDirectory: string;
      readonly serverModules: Array<{ readonly name: string }>;
    },
    FrameworkCore.FrameworkError
  >;
  readonly dev: (
    options?: FrameworkCore.FrameworkDevOptions,
  ) => Effect.Effect<FrameworkCore.FrameworkDevServer, FrameworkCore.FrameworkError, Scope.Scope>;
}

/**
 * Build the Next.js-on-AWS framework service. See the module doc for the
 * `build`/`dev` semantics.
 */
export const make: (
  options?: NextjsAwsOptions,
) => Effect.Effect<NextjsAwsService, never, FileSystem.FileSystem | Path.Path> = Effect.fnUntraced(
  function* (options?: NextjsAwsOptions) {
    const fs = yield* FileSystem.FileSystem;
    const path = yield* Path.Path;

    const spawnerLayer = NodeChildProcessSpawner.layer.pipe(
      Layer.provide(
        Layer.merge(Layer.succeed(FileSystem.FileSystem)(fs), Layer.succeed(Path.Path)(path)),
      ),
    );

    const standaloneLayer = Layer.mergeAll(
      spawnerLayer,
      Layer.succeed(FileSystem.FileSystem)(fs),
      Layer.succeed(Path.Path)(path),
    );

    const resolveRoot = (override: string | undefined) =>
      Effect.sync(() => path.resolve(override ?? options?.root ?? process.cwd()));

    const build: NextjsAwsService["build"] = Effect.fn(function* (
      buildOptions?: FrameworkCore.FrameworkBuildOptions,
    ) {
      const root = yield* resolveRoot(buildOptions?.root);
      if (options?.server === "web-function") {
        return yield* buildStandalone({
          root,
          cli: yield* resolveNextCli(root),
          env: buildOptions?.env,
        }).pipe(Effect.provide(standaloneLayer));
      }
      const configPath = options?.configPath ?? "open-next.config.ts";

      // Generate the minimal streaming config when the project has none. The
      // file lands in the project root (OpenNext resolves the config relative
      // to its cwd) and is left in place so subsequent builds — and the memo
      // input hash — see a stable tree.
      const absoluteConfigPath = path.resolve(root, configPath);
      const hasConfig = yield* fs
        .exists(absoluteConfigPath)
        .pipe(Effect.orElseSucceed(() => false));
      if (!hasConfig) {
        yield* fs
          .writeFileString(absoluteConfigPath, DEFAULT_OPEN_NEXT_CONFIG)
          .pipe(
            Effect.mapError(
              fail(`Failed to write the default OpenNext config at ${absoluteConfigPath}`),
            ),
          );
      }

      const cli = yield* resolveOpenNextCli(root);
      yield* runOpenNextBuild({
        root,
        cli,
        configPath,
        extraArgs: options?.buildArgs ?? [],
        env: buildOptions?.env,
      }).pipe(Effect.provide(spawnerLayer));

      const distDirectory = path.join(root, ".open-next");
      const clientDirectory = path.join(distDirectory, "assets");

      // The authoritative manifest: verify the topology the composite deploys
      // (a streaming default server function) actually came out of the build.
      const manifestPath = path.join(distDirectory, "open-next.output.json");
      const manifestRaw = yield* fs
        .readFileString(manifestPath)
        .pipe(Effect.mapError(fail(`The build produced no ${manifestPath}`)));
      const manifest = yield* Effect.try({
        try: () => JSON.parse(manifestRaw) as OpenNextOutputManifest,
        catch: fail(`Failed to parse ${manifestPath}`),
      });
      const defaultOrigin = manifest.origins?.default;
      if (defaultOrigin?.type !== "function") {
        return yield* fail(
          `The OpenNext build's default origin is "${defaultOrigin?.type}", not a Lambda function. ` +
            "The AWS deploy target only supports the function topology (no generateDockerfile).",
        )(undefined);
      }
      if (defaultOrigin.streaming !== true) {
        return yield* fail(
          "The OpenNext build's default server does not stream. The Lambda Function URL is " +
            "created with invokeMode: RESPONSE_STREAM, so open-next.config.ts must keep the streaming wrapper: " +
            '`default: { override: { wrapper: "aws-lambda-streaming" } }`.',
        )(undefined);
      }

      const entryName = deriveServerEntryName(defaultOrigin);
      const entryPath = path.join(distDirectory, entryName);
      if (!(yield* fs.exists(entryPath).pipe(Effect.orElseSucceed(() => false)))) {
        return yield* fail(`The build produced no server entry at ${entryPath}`)(undefined);
      }

      return {
        distDirectory,
        clientDirectory,
        serverModules: [{ name: entryName }],
      };
    });

    const dev: NextjsAwsService["dev"] = Effect.fn(function* (
      devOptions?: FrameworkCore.FrameworkDevOptions,
    ) {
      const root = yield* resolveRoot(devOptions?.root);
      const port = devOptions?.port ?? (yield* pickEphemeralPort);
      const cli = yield* resolveNextCli(root);
      const host = devOptions?.host;
      const child = yield* spawnNextDev({ root, cli, port, host });
      const url = `http://${host ?? "localhost"}:${port}`;
      yield* awaitNextDevReady({ url, child });
      return { url };
    });

    return { build, dev };
  },
);

export default make;