Expose request scoped AsyncLocalStorage API

[Jussinevavuori]

Goals

1. Allow for sharing and updating values in the request context, such that they do not leak into other requests
2. Work in every context (RSCs, server actions, API routes...)
3. Allow for non-primitive values

Non-Goals

1. Expose the request: Request to the developer

Background

I am working on an authorization framework, which would allow for setting a request scoped "onPermissionDenied" handler, such that any component or function that fails an auth check has access to that function.

// e.g. on an authed page
AuthFramework.onPermissionDenied(() => {
  redirect("/");
})

// e.g. in a server action
AuthFramework.onPermissionDenied(() => {
  throw new Error("Unauthorized")
})

I initially implemented this as follows:

const handlerCache = React.cache(() => ({ current: defaultHandler }))

const AuthFramework = {
  onPermissionDenied(handler) {
    handlerCache().current = handler;
  },
  getPermissionDeniedHandler() {
    return handlerCache().current
  }
}

This was a hack and not the intended use for React.cache, however I have seen a lot of people do this to share context across a request.

This does not work in server actions and API routes, as they are outside of the react rendering lifecycle. (For now, I am using a combination of React.cache and wrapping server actions in AsyncLocalStorage in an ugly manner to overcome this limitation).

Since Next.js exposes so many execution contexts, having a single API to share values across a request in each context would eradicate all hacks using React.cache(() => ({ current })) with an even stronger primitive.

Proposal

API for creating a new request scoped shared value.

// More concise naming highly appreciated
import { createRequestScopedValue } from "next/proposed-request-scoped-values-api";

// Initialize a request-scoped shared value with a default value.
const store = createRequestScopedValue<() => void>(() => {
  console.log("Hello world");
})

API for calling from RSC

// /app/page.tsx
async function Component() {
  // Get current value (defaults to initial value unless `.set()` called)
  const value = store.get();
  
  // Set new value (will not be exposed outside of current request scope)
  store.set(() => console.log("New message"))
 
  return <div>...</div>
}

Equivalent API for calling from server action.

// /app/actions.ts
"use server"

async function myServerAction() {
  // Get current value (defaults to initial value unless `.set()` called)
  const value = store.get();
  
  // Set new value (will not be exposed outside of current request scope)
  store.set(() => console.log("New message"))
}

Equivalent API for calling from route handler.

// /src/app/api/example/route.ts
export async function GET(request: Request) {
  // Get current value (defaults to initial value unless `.set()` called)
  const value = store.get();
  
  // Set new value (will not be exposed outside of current request scope)
  store.set(() => console.log("New message"))
  
  return new Response();
}

For implementation, I believe using AsyncLocalStorage (similarly as for cookies() and headers()) should be achievable. The store could have the shape of a mutable Map<string /* store ID */, unknown /* store current value */>, where each store gets its own unique ID at creation. The AsyncLocalStorage context is then provided to each Next.js request in every execution context.

[sergey-hippo]

For my use case (tracking external API errors for logging) I would also like to make this storage visible to Express middleware in case when Next.js runs in an Express server.
The problem with using AsyncLocalStorage directly through Express middleware is that it's not visible at all in Next.js server components, see: #67305