experimental: unstable_after (#65038)

Implements `unstable_after`, which lets the user schedule work to be
executed after the response is finished.

### Implementation notes

- `unstable_after()` is a dynamic function (bypassable only with `export
dynamic = "force-static"`)
- Usable in: server components (including `generateMetadata`), actions,
route handlers, middleware
- It is meant to run its callbacks even if a response didn't complete
successfully (thrown error) or called `notFound()`/`redirect()`
- Currently gated behind a `experimental.after` feature flag, because it
touches many runtime bits (including a React monkeypatch...)
- The state for `unstable_after()` in a given request lives in
`requestAsyncStorage` (added via `RequestAsyncStorageWrapper`)

- the implementation is based around two functions that we inject via
`renderOpts`:
- `waitUntil(promise)` - keep a function invocation alive until a
promise settles. it is provided as a platform primitive in serverless
contexts, and a noop in `next start`
- for serverless (nodejs), Next.js will attempt to get `waitUntil` from
`globalThis[Symbol.for('@next/request-context')].get().waitUntil`. This
should be considered unstable for now. See
`packages/next/src/server/after/wait-until-builtin.ts` for details.
- `onClose(callback)` **[NEW]** - run something when a response is done.
basically `res.on('close', callback)`, but also implemented for Web APIs
- unfortunately, for Web, this requires some potentially expensive
tricks - see `packages/next/src/server/web/web-on-close.ts`

packages/next-swc/crates/next-core/src/next_config.rs

@@ -526,6 +526,7 @@ pub struct ExperimentalConfig {
     // ---
     adjust_font_fallbacks: Option<bool>,
     adjust_font_fallbacks_with_size_adjust: Option<bool>,
+    after: Option<bool>,
     amp: Option<serde_json::Value>,
     app_document_preloading: Option<bool>,
     case_sensitive_routes: Option<bool>,

packages/next-swc/crates/next-core/src/next_shared/transforms/next_cjs_optimizer.rs

@@ -45,6 +45,7 @@ pub fn get_next_cjs_optimizer_rule(enable_mdx_rs: bool) -> ModuleRule {
                         "userAgent".into(),
                         "next/dist/server/web/spec-extension/user-agent".into(),
                     ),
+                    ("unstable_after".into(), "next/dist/server/after".into()),
                 ]),
             },
         )]),

packages/next-swc/crates/next-custom-transforms/src/transforms/react_server_components.rs

@@ -472,8 +472,9 @@ struct ReactServerComponentValidator {
     filepath: String,
     app_dir: Option<PathBuf>,
     invalid_server_imports: Vec<JsWord>,
-    invalid_client_imports: Vec<JsWord>,
     invalid_server_lib_apis_mapping: HashMap<&'static str, Vec<&'static str>>,
+    invalid_client_imports: Vec<JsWord>,
+    invalid_client_lib_apis_mapping: HashMap<&'static str, Vec<&'static str>>,
     pub directive_import_collection: Option<(bool, bool, Vec<ModuleImports>, Vec<String>)>,
 }
 
@@ -540,7 +541,10 @@ impl ReactServerComponentValidator {
                 JsWord::from("react-dom/server"),
                 JsWord::from("next/router"),
             ],
+
             invalid_client_imports: vec![JsWord::from("server-only"), JsWord::from("next/headers")],
+
+            invalid_client_lib_apis_mapping: [("next/server", vec!["unstable_after"])].into(),
         }
     }
 
@@ -627,14 +631,31 @@ impl ReactServerComponentValidator {
             return;
         }
         for import in imports {
-            let source = import.source.0.clone();
-            if self.invalid_client_imports.contains(&source) {
+            let source = &import.source.0;
+
+            if self.invalid_client_imports.contains(source) {
                 report_error(
                     &self.app_dir,
                     &self.filepath,
                     RSCErrorKind::NextRscErrClientImport((source.to_string(), import.source.1)),
                 );
             }
+
+            let invalid_apis = self.invalid_client_lib_apis_mapping.get(source.as_str());
+            if let Some(invalid_apis) = invalid_apis {
+                for specifier in &import.specifiers {
+                    if invalid_apis.contains(&specifier.0.as_str()) {
+                        report_error(
+                            &self.app_dir,
+                            &self.filepath,
+                            RSCErrorKind::NextRscErrClientImport((
+                                specifier.0.to_string(),
+                                specifier.1,
+                            )),
+                        );
+                    }
+                }
+            }
         }
     }
 

packages/next/server.d.ts

@@ -13,3 +13,4 @@ export { userAgent } from 'next/dist/server/web/spec-extension/user-agent'
 export { URLPattern } from 'next/dist/compiled/@edge-runtime/primitives/url'
 export { ImageResponse } from 'next/dist/server/web/spec-extension/image-response'
 export type { ImageResponseOptions } from 'next/dist/compiled/@vercel/og/types'
+export { unstable_after } from 'next/dist/server/after'

packages/next/server.js

@@ -11,6 +11,7 @@ const serverExports = {
     .userAgent,
   URLPattern: require('next/dist/server/web/spec-extension/url-pattern')
     .URLPattern,
+  unstable_after: require('next/dist/server/after').unstable_after,
 }
 
 // https://nodejs.org/api/esm.html#commonjs-namespaces
@@ -24,3 +25,4 @@ exports.ImageResponse = serverExports.ImageResponse
 exports.userAgentFromString = serverExports.userAgentFromString
 exports.userAgent = serverExports.userAgent
 exports.URLPattern = serverExports.URLPattern
+exports.unstable_after = serverExports.unstable_after

packages/next/src/build/utils.ts

@@ -1391,6 +1391,9 @@ export async function buildAppStaticPaths({
         incrementalCache,
         supportsDynamicHTML: true,
         isRevalidate: false,
+        experimental: {
+          after: false,
+        },
       },
     },
     async () => {

packages/next/src/build/webpack/loaders/next-edge-ssr-loader/render.ts

@@ -158,12 +158,19 @@ export function getRender({
     event?: NextFetchEvent
   ) {
     const extendedReq = new WebNextRequest(request)
-    const extendedRes = new WebNextResponse()
+    const extendedRes = new WebNextResponse(
+      undefined,
+      // tracking onClose adds overhead, so only do it if `experimental.after` is on.
+      !!process.env.__NEXT_AFTER
+    )
 
     handler(extendedReq, extendedRes)
     const result = await extendedRes.toResponse()
 
     if (event?.waitUntil) {
+      // TODO(after):
+      // remove `internal_runWithWaitUntil` and the `internal-edge-wait-until` module
+      // when consumers switch to `unstable_after`.
       const waitUntilPromise = internal_getCurrentFunctionWaitUntil()
       if (waitUntilPromise) {
         event.waitUntil(waitUntilPromise)

packages/next/src/build/webpack/plugins/define-env-plugin.ts

@@ -170,6 +170,7 @@ export function getDefineEnv({
         : '',
     'process.env.NEXT_MINIMAL': '',
     'process.env.__NEXT_PPR': checkIsAppPPREnabled(config.experimental.ppr),
+    'process.env.__NEXT_AFTER': config.experimental.after ?? false,
     'process.env.NEXT_DEPLOYMENT_ID': config.deploymentId || false,
     'process.env.__NEXT_FETCH_CACHE_KEY_PREFIX': fetchCacheKeyPrefix ?? '',
     'process.env.__NEXT_MIDDLEWARE_MATCHERS': middlewareMatchers ?? [],

packages/next/src/client/components/request-async-storage.external.ts

@@ -7,6 +7,7 @@ import type { ReadonlyRequestCookies } from '../../server/web/spec-extension/ada
 // Share the instance module in the next-shared layer
 import { requestAsyncStorage } from './request-async-storage-instance' with { 'turbopack-transition': 'next-shared' }
 import type { DeepReadonly } from '../../shared/lib/deep-readonly'
+import type { AfterContext } from '../../server/after/after-context'
 
 export interface RequestStore {
   readonly headers: ReadonlyHeaders
@@ -17,6 +18,7 @@ export interface RequestStore {
     Record<string, { files: string[] }>
   >
   readonly assetPrefix: string
+  readonly afterContext: AfterContext | undefined
 }
 
 export type RequestAsyncStorage = AsyncLocalStorage<RequestStore>

packages/next/src/export/index.ts

@@ -422,6 +422,7 @@ export async function exportAppImpl(
       isAppPPREnabled: checkIsAppPPREnabled(nextConfig.experimental.ppr),
       clientTraceMetadata: nextConfig.experimental.clientTraceMetadata,
       swrDelta: nextConfig.experimental.swrDelta,
+      after: nextConfig.experimental.after ?? false,
     },
   }
 

packages/next/src/export/routes/app-route.ts

@@ -23,6 +23,7 @@ import type {
 import { isDynamicUsageError } from '../helpers/is-dynamic-usage-error'
 import { SERVER_DIRECTORY } from '../../shared/lib/constants'
 import { hasNextSupport } from '../../telemetry/ci-info'
+import type { ExperimentalConfig } from '../../server/config-shared'
 
 export const enum ExportedAppRouteFiles {
   BODY = 'BODY',
@@ -37,7 +38,8 @@ export async function exportAppRoute(
   incrementalCache: IncrementalCache | undefined,
   distDir: string,
   htmlFilepath: string,
-  fileWriter: FileWriter
+  fileWriter: FileWriter,
+  experimental: Required<Pick<ExperimentalConfig, 'after'>>
 ): Promise<ExportRouteResult> {
   // Ensure that the URL is absolute.
   req.url = `http://localhost:3000${req.url}`
@@ -64,10 +66,13 @@ export async function exportAppRoute(
       notFoundRoutes: [],
     },
     renderOpts: {
+      experimental: experimental,
       originalPathname: page,
       nextExport: true,
       supportsDynamicHTML: false,
       incrementalCache,
+      waitUntil: undefined,
+      onClose: undefined,
     },
   }
 

packages/next/src/export/types.ts

@@ -8,7 +8,10 @@ import type { FontConfig } from '../server/font-utils'
 import type { ExportPathMap, NextConfigComplete } from '../server/config-shared'
 import type { Span } from '../trace'
 import type { Revalidate } from '../server/lib/revalidate'
-import type { NextEnabledDirectories } from '../server/base-server'
+import type {
+  NextEnabledDirectories,
+  RequestLifecycleOpts,
+} from '../server/base-server'
 import type {
   SerializableTurborepoAccessTraceResult,
   TurborepoAccessTraceResult,
@@ -97,6 +100,7 @@ export type WorkerRenderOptsPartial = PagesRenderOptsPartial &
   AppRenderOptsPartial
 
 export type WorkerRenderOpts = WorkerRenderOptsPartial &
+  RequestLifecycleOpts &
   LoadComponentsReturnType
 
 export type ExportWorker = (

packages/next/src/export/worker.ts

@@ -248,7 +248,8 @@ async function exportPageImpl(
         incrementalCache,
         distDir,
         htmlFilepath,
-        fileWriter
+        fileWriter,
+        input.renderOpts.experimental
       )
     }
 
@@ -274,6 +275,8 @@ async function exportPageImpl(
         ...input.renderOpts.experimental,
         isRoutePPREnabled,
       },
+      waitUntil: undefined,
+      onClose: undefined,
     }
 
     if (hasNextSupport) {