orionplace-react 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-react",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Next.js 16 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",

package/src/project-readme.mjs

@@ -89,7 +89,7 @@ and Next.js configuration are preserved.
 | \`../${base}app/_storefront/\` | Route controllers that connect components, navigation and API actions. |
 | \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
 | \`../${base}app/ps3/blog/[...orionplace]/route.ts\` | The route handler serving guarded blog images and videos under \`/ps3/blog/...\`. |
-| \`../${base}proxy.ts\` | Marks personalized pages private and varies them by storefront domain. |
+| \`../${base}proxy.ts\` | Marks personalized pages private and answers HTTP 503 when Application Load fails. |
 | \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
 | \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
 
@@ -311,9 +311,12 @@ Failures also survive hydration and navigation. They never open a login modal or
 trigger an automatic retry on every route. The supplied shell shows
 \`StorefrontErrorPage\` and keeps the header, route content and footer unmounted
 until initialization succeeds. Retry reloads the page; an unknown address keeps
-the 404 page. App Router components cannot set the response status, so this
-error page is sent with HTTP 200. Feature components should check
-\`selectIsReady\` before using required data.
+the 404 page. App Router pages cannot change their status once they stream, so
+\`${base}proxy.ts\` starts Application Load for a full page load and hands it
+to the render (still one request): when it fails, the error page is sent with
+HTTP 503. A project that keeps its own \`proxy.ts\` sends it with HTTP 200 unless
+it does the same. Feature components should check \`selectIsReady\` before using
+required data.
 
 Page responses use \`private, no-store\` through \`${base}proxy.ts\`. Do not put
 personalized HTML in shared caches or persist the snapshot in localStorage. The

package/templates/lib/orionplace/appLoadServer.ts

@@ -31,8 +31,25 @@ const FORWARDED                   = [
   'x-tz',
 ];
 
-async function buildRequest(signal: AbortSignal): Promise<Request> {
-  const incoming = await headers();
+/** Header the proxy sets on a page request whose Application Load it started. */
+export const APP_LOAD_HANDOFF_HEADER = 'x-orionplace-appload';
+/** How long a started Application Load waits for the layout to take it. */
+const HANDOFF_TTL                    = 60_000;
+const HANDOFF_KEY                    = Symbol.for('orionplace.appLoadHandoff');
+
+/**
+ * Started loads by id. Kept on `globalThis`: the proxy and the page render run
+ * in the same Node process but in separate bundles.
+ */
+function handoffs(): Map<string, Promise<ServerAppLoad>> {
+  const scope = globalThis as typeof globalThis & {
+    [HANDOFF_KEY]?: Map<string, Promise<ServerAppLoad>>;
+  };
+  scope[HANDOFF_KEY] ??= new Map();
+  return scope[HANDOFF_KEY];
+}
+
+function buildRequest(incoming: Headers, signal: AbortSignal): Request {
   const host     =
     incoming.get('x-forwarded-host') || incoming.get('host') || 'localhost';
   const protocol =
@@ -74,12 +91,14 @@ async function buildRequest(signal: AbortSignal): Promise<Request> {
  */
 export async function requestAppLoad(
   signal?: AbortSignal,
+  incoming?: Headers,
 ): Promise<ServerAppLoad> {
   const timeout     = AbortSignal.timeout(35_000);
   const combined    = signal ? AbortSignal.any([signal, timeout]) : timeout;
   let response: Response;
   try {
-    response = await forwardMarketplace(await buildRequest(combined), {
+    const request = buildRequest(incoming ?? new Headers(await headers()), combined);
+    response      = await forwardMarketplace(request, {
       mimicFrontDomain: process.env.MIMIC_FRONT_DOMAIN ?? '',
     });
   } catch {
@@ -107,11 +126,37 @@ export async function requestAppLoad(
   };
 }
 
+/**
+ * Starts Application Load for a page request in `proxy.ts`, before the page
+ * renders, so a failure can answer HTTP 503 (a page cannot change its status
+ * once it streams). Returns the id to pass in `APP_LOAD_HANDOFF_HEADER`; the
+ * render takes the same result, so the page still costs one request.
+ */
+export function startAppLoad(incoming: Headers): {
+  id: string;
+  load: Promise<ServerAppLoad>;
+} {
+  const id    = crypto.randomUUID();
+  const load  = requestAppLoad(undefined, incoming);
+  const store = handoffs();
+  store.set(id, load);
+  setTimeout(() => store.delete(id), HANDOFF_TTL).unref?.();
+  return { id, load };
+}
+
 /**
  * One request per server render, shared by the layout and any server component
  * that awaits it. Reading it in a layout initializes the marketplace before the
- * page renders; it never opens an authentication prompt.
+ * page renders; it never opens an authentication prompt. A load the proxy
+ * started for this request is taken once; otherwise the render requests it.
  */
-export const getOrionplaceAppLoad = cache((): Promise<ServerAppLoad> =>
-  requestAppLoad(),
-);
+export const getOrionplaceAppLoad = cache(async (): Promise<ServerAppLoad> => {
+  const incoming = await headers();
+  const id       = incoming.get(APP_LOAD_HANDOFF_HEADER);
+  const started  = id ? handoffs().get(id) : undefined;
+  if (id && started) {
+    handoffs().delete(id);
+    return started;
+  }
+  return requestAppLoad(undefined, new Headers(incoming));
+});

package/templates/proxy.ts

@@ -1,17 +1,51 @@
 import { NextResponse, type NextRequest } from 'next/server';
+import {
+  APP_LOAD_HANDOFF_HEADER,
+  startAppLoad,
+} from '@/lib/orionplace/appLoadServer';
+
+/**
+ * A full page load: not an in-app navigation (`RSC`), a prefetch or a public
+ * file such as an image.
+ */
+function pageLoad(request: NextRequest) {
+  const accept = request.headers.get('accept') ?? '';
+  return (
+    request.method === 'GET' &&
+    !request.headers.has('rsc') &&
+    !request.headers.has('next-router-prefetch') &&
+    !/\.[a-z0-9]+$/i.test(request.nextUrl.pathname) &&
+    (!accept || accept.includes('text/html') || accept.includes('*/*'))
+  );
+}
 
 /**
  * Personalized pages are never shared between visitors or storefront domains.
  * Next.js manages its own `Vary` header for pages; the API gateway sets the
  * storefront-domain `Vary` on its own responses.
+ *
+ * A full page load starts Application Load here and hands it to the render:
+ * when it fails, the error page answers HTTP 503 like the Nuxt and SvelteKit
+ * starters (an unknown address keeps its 404).
  */
-export function proxy(request: NextRequest) {
+export async function proxy(request: NextRequest) {
   const forwarded = new Headers(request.headers);
+  // Only this proxy names a started load; a visitor cannot pick one.
+  forwarded.delete(APP_LOAD_HANDOFF_HEADER);
   forwarded.set(
     'x-orionplace-page-url',
     request.nextUrl.pathname + request.nextUrl.search,
   );
-  const response  = NextResponse.next({ request: { headers: forwarded } });
+  let unavailable = false;
+  if (pageLoad(request)) {
+    const { id, load } = startAppLoad(forwarded);
+    forwarded.set(APP_LOAD_HANDOFF_HEADER, id);
+    unavailable        = Boolean((await load).failure);
+  }
+  const response  = NextResponse.next({
+    request: { headers: forwarded },
+    ...(unavailable ? { status: 503 } : {}),
+  });
   response.headers.set('Cache-Control', 'private, no-store');
   return response;
 }