Add ability to warm server function (#114)

Author: fwang

.changeset/six-donuts-give.md

@@ -0,0 +1,5 @@
+---
+"open-next": minor
+---
+
+Add ability to warm server function

README.md

@@ -36,6 +36,7 @@ OpenNext aims to support all Next.js 13 features. Some features are work in prog
 - [x] Image optimization
 - [x] [NextAuth.js](https://next-auth.js.org)
 - [x] [Running at edge](#running-at-edge)
+- [x] [No cold start](#warmer-function)
 
 ## How does OpenNext work?
 
@@ -55,6 +56,7 @@ my-next-app/
     assets/                        -> Static files to upload to an S3 Bucket
     server-function/               -> Handler code for server Lambda Function
     image-optimization-function/   -> Handler code for image optimization Lambda Function
+    warmer-function/               -> Cron job code to keep server function warm
 ```
 
 ## Deployment
@@ -210,6 +212,57 @@ To configure the CloudFront distribution:
 | `/api/*`          | API                 | set `x-forwarded-host`<br />[see why](#workaround-set-x-forwarded-host-header-aws-specific) | server function | -                                                                                                    |
 | `/*`              | catch all           | set `x-forwarded-host`<br />[see why](#workaround-set-x-forwarded-host-header-aws-specific) | server function | S3 bucket<br />[see why](#workaround-public-static-files-served-out-by-server-function-aws-specific) |
 
+#### Warmer function
+
+Server functions may experience performance issues due to Lambda cold starts. To mitigate this, the server function can be invoked periodically. Remmember, **Warming is optional** and is only required if you want to keep the server function warm.
+
+To set this up, create a Lambda function using the code in the `.open-next/warmer-function` folder with `index.mjs` as the handler. Ensure the function is configured as follows:
+
+- Set the `FUNCTION_NAME` environment variable with the value being the name of the server Lambda function.
+- Set the `CONCURRENCY` environment variable with the value being the number of server functions to warm.
+- Grant `lambda:InvokeFunction` permission to allow the warmer to invoke the server function.
+
+Also, create an EventBridge scheduled rule to invoke the warmer function every 5 minutes.
+
+Please note, warming is currently only supported when the server function is deployed to a single region (Lambda).
+
+**Prewarm**
+
+Each time you deploy, a new version of the Lambda function will be generated. All warmed server function instances will be turned off. And there won't be any warm instances until the warmer function runs again at the next 5-minute interval.
+
+To ensure the functions are prewarmed on deploy, create a [CloudFormation Custom Resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) to invoke the warmer function on deployment. The custom resource should be configured as follows:
+
+- Invoke the warmer function on resource `Create` and `Update`.
+- Include a timestamp value in the resource property to ensure the custom resource runs on every deployment.
+- Grant `lambda:InvokeFunction` permission to allow the custom resource to invoke the warmer function.
+
+**Cost**
+
+There are three components to the cost:
+
+1. EventBridge scheduler: $0.00864
+   ```
+   Requests cost — 8,640 invocations per month x $1/million = $0.00864
+   ```
+1. Warmer function: $0.145728288
+   ```
+   Requests cost — 8,640 invocations per month x $0.2/million = $0.001728
+   Duration cost — 8,640 invocations per month x 1GB memory x 1s duration x $0.0000166667/GB-second = $0.144000288
+   ```
+1. Server function: $0.0161280288 per warmed instance
+   ```
+   Requests cost — 8,640 invocations per month x $0.2/million = $0.001728
+   Duration cost — 8,640 invocations per month x 1GB memory x 100ms duration x $0.0000166667/GB-second = $0.0144000288
+   ```
+
+For example, keeping 50 instances of the server function warm will cost approximately **$0.96 per month**
+
+```
+$0.00864 + $0.145728288 + $0.0161280288 x 50 = $0.960769728
+```
+
+This cost estimate is based on the `us-east-1` region pricing and does not consider any free tier benefits.
+
 ## Limitations and workarounds
 
 #### WORKAROUND: `public/` static files served by the server function (AWS specific)

docs/public/architecture.png

@@ -20,6 +20,7 @@
   "keywords": [],
   "author": "",
   "dependencies": {
+    "@aws-sdk/client-lambda": "^3.234.0",
     "@aws-sdk/client-s3": "^3.234.0",
     "@node-minify/core": "^8.0.6",
     "@node-minify/terser": "^8.0.6",

packages/open-next/package.json

@@ -9,11 +9,12 @@ import type {
 } from "aws-lambda";
 // @ts-ignore
 import NextServer from "next/dist/server/next-server.js";
-import { loadConfig, setNodeEnv } from "./util.js";
+import { generateUniqueId, loadConfig, setNodeEnv } from "./util.js";
 import { isBinaryContentType } from "./binary.js";
 import { debug } from "./logger.js";
 import type { PublicFiles } from "../build.js";
 import { convertFrom, convertTo } from "./event-mapper.js";
+import { WarmerEvent, WarmerResponse } from "./warmer-function.js";
 
 setNodeEnv();
 setNextjsServerWorkingDirectory();
@@ -25,7 +26,8 @@ const publicAssets = loadPublicAssets();
 setNextjsPrebundledReact(config);
 debug({ nextDir });
 
-// Create a NextServer
+// Generate a 6 letter unique server ID
+const serverId = `server-${generateUniqueId()}`;
 const requestHandler = new NextServer.default({
   hostname: "localhost",
   port: Number(process.env.PORT) || 3000,
@@ -42,8 +44,17 @@ const requestHandler = new NextServer.default({
 /////////////
 
 export async function handler(
-  event: APIGatewayProxyEventV2 | CloudFrontRequestEvent | APIGatewayProxyEvent
+  event:
+    | APIGatewayProxyEventV2
+    | CloudFrontRequestEvent
+    | APIGatewayProxyEvent
+    | WarmerEvent
 ) {
+  // Handler warmer
+  if ("type" in event) {
+    return formatWarmerResponse(event);
+  }
+
   debug("event", event);
 
   // Parse Lambda event and create Next.js request
@@ -164,3 +175,12 @@ function formatAPIGatewayFailoverResponse() {
 function formatCloudFrontFailoverResponse(event: CloudFrontRequestEvent) {
   return event.Records[0].cf.request;
 }
+
+function formatWarmerResponse(event: WarmerEvent) {
+  console.log(event);
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve({ serverId } satisfies WarmerResponse);
+    }, event.delay);
+  });
+}

packages/open-next/src/adapters/server-adapter.ts

@@ -6,6 +6,10 @@ export function setNodeEnv() {
   process.env.NODE_ENV = process.env.NODE_ENV ?? "production";
 }
 
+export function generateUniqueId() {
+  return Math.random().toString(36).slice(2, 8);
+}
+
 export function loadConfig(nextDir: string) {
   const filePath = path.join(nextDir, "required-server-files.json");
   const json = fs.readFileSync(filePath, "utf-8");

packages/open-next/src/adapters/util.ts

@@ -0,0 +1,73 @@
+import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
+import type { Context } from "aws-lambda";
+import { generateUniqueId } from "./util.js";
+const lambda = new LambdaClient({});
+const FUNCTION_NAME = process.env.FUNCTION_NAME!;
+const CONCURRENCY = parseInt(process.env.CONCURRENCY!);
+
+export interface WarmerEvent {
+  type: "warmer";
+  warmerId: string;
+  index: number;
+  concurrency: number;
+  delay: number;
+}
+
+export interface WarmerResponse {
+  serverId: string;
+}
+
+export async function handler(_event: any, context: Context) {
+  const warmerId = `warmer-${generateUniqueId()}`;
+  console.log({
+    event: "warmer invoked",
+    functionName: FUNCTION_NAME,
+    concurrency: CONCURRENCY,
+    warmerId,
+  });
+
+  // Warm
+  const ret = await Promise.all(
+    Array.from({ length: CONCURRENCY }, (_v, i) => i).map((i) => {
+      try {
+        return lambda.send(
+          new InvokeCommand({
+            FunctionName: FUNCTION_NAME,
+            InvocationType: "RequestResponse",
+            Payload: Buffer.from(
+              JSON.stringify({
+                type: "warmer",
+                warmerId,
+                index: i,
+                concurrency: CONCURRENCY,
+                delay: 75,
+              } satisfies WarmerEvent)
+            ),
+          })
+        );
+      } catch (e) {
+        console.error(`failed to warm up #${i}`, e);
+        // ignore error
+      }
+    })
+  );
+
+  // Print status
+  const warmedServerIds: string[] = [];
+  ret.forEach((r, i) => {
+    if (r?.StatusCode !== 200 || !r?.Payload) {
+      console.error(`failed to warm up #${i}:`, r?.Payload?.toString());
+      return;
+    }
+    const payload = JSON.parse(
+      Buffer.from(r.Payload).toString()
+    ) as WarmerResponse;
+    warmedServerIds.push(payload.serverId);
+  });
+  console.log({
+    event: "warmer result",
+    sent: CONCURRENCY,
+    success: warmedServerIds.length,
+    uniqueServersWarmed: [...new Set(warmedServerIds)].length,
+  });
+}

packages/open-next/src/adapters/warmer-function.ts

@@ -29,9 +29,10 @@ export async function build() {
   // Generate deployable bundle
   printHeader("Generating bundle");
   initOutputDir();
+  createAssets();
   createServerBundle(monorepoRoot);
   createImageOptimizationBundle();
-  createAssets();
+  createWarmerBundle();
   if (process.env.OPEN_NEXT_MINIFY) {
     await minifyServerBundle();
   }
@@ -245,6 +246,32 @@ function createServerBundle(monorepoRoot: string) {
   injectMiddlewareGeolocation(outputPath, packagePath);
 }
 
+function createWarmerBundle() {
+  console.info(`Bundling warmer function...`);
+
+  // Create output folder
+  const outputPath = path.join(outputDir, "warmer-function");
+  fs.mkdirSync(outputPath, { recursive: true });
+
+  // Build Lambda code
+  // note: bundle in OpenNext package b/c the adatper relys on the
+  //       "serverless-http" package which is not a dependency in user's
+  //       Next.js app.
+  esbuildSync({
+    entryPoints: [path.join(__dirname, "adapters", "warmer-function.js")],
+    external: ["next"],
+    outfile: path.join(outputPath, "index.mjs"),
+    banner: {
+      js: [
+        "import { createRequire as topLevelCreateRequire } from 'module';",
+        "const require = topLevelCreateRequire(import.meta.url);",
+        "import bannerUrl from 'url';",
+        "const __dirname = bannerUrl.fileURLToPath(new URL('.', import.meta.url));",
+      ].join(""),
+    },
+  });
+}
+
 async function minifyServerBundle() {
   console.info(`Minimizing server function...`);
   await minifyAll(path.join(outputDir, "server-function"), {