akanjs 2.2.11 → 2.2.13-rc.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # akanjs
 
+## 2.2.12
+
+### Patch Changes
+
+- 666e46c: Improve SSR hydration payload handling, redirect status propagation, and restore dev HMR incremental refresh behavior.
+- 666e46c: Align RSC not-found responses with HTTP 404 semantics and add request-scoped policy tracking for future cache decisions.
+
 ## 2.2.11
 
 ### Patch Changes

package/client/cookie.ts

@@ -1,7 +1,7 @@
 import { getEnv } from "akanjs/base";
 import { decodeJwtPayload, Logger } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { requestStorage } from "akanjs/fetch";
+import { cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
 import { loadCapacitorCore } from "./capacitor";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
@@ -30,11 +30,7 @@ function parseCookieHeader(cookieHeader: string): Map<string, { name: string; va
 }
 
 export const cookies = (): Map<string, { name: string; value: string }> => {
-  if (getEnv().side === "server") {
-    const req = requestStorage?.getStore();
-    if (!req) return new Map();
-    return parseCookieHeader(req.headers.get("cookie") ?? "");
-  }
+  if (getEnv().side === "server") return serverCookies();
   return parseCookieHeader(document.cookie);
 };
 
@@ -75,13 +71,7 @@ export const removeCookie = (key: string, options: { path: string } = { path: "/
 };
 export const headers = (): Map<string, string> => {
   if (getEnv().side !== "server") return new Map();
-  const req = requestStorage?.getStore();
-  if (!req) return new Map();
-  const map = new Map<string, string>();
-  req.headers.forEach((value, key) => {
-    map.set(key, value);
-  });
-  return map;
+  return serverHeaders();
 };
 
 export const getHeader = (key: string): string | undefined => {

package/client/router.ts

@@ -35,12 +35,18 @@ interface CSRClientRouterOption extends RouterOptions {
   router: RouterInstance;
 }
 export type RedirectMethod = "replace" | "push";
+export type RedirectStatus = 303 | 307 | 308;
+export interface RedirectOptions {
+  method?: RedirectMethod;
+  status?: RedirectStatus;
+}
 
 export class AkanRedirectError extends Error {
   readonly digest = "AKAN_REDIRECT";
   constructor(
     readonly location: string,
     readonly method: RedirectMethod = "replace",
+    readonly status: RedirectStatus = 307,
   ) {
     super(`Redirect to ${location}`);
     this.name = "AkanRedirectError";
@@ -246,7 +252,9 @@ class Router {
     this.#instance.refresh();
     return undefined as never;
   }
-  redirect(href: string): never {
+  redirect(href: string, options: RedirectOptions = {}): never {
+    const method = options.method ?? "replace";
+    const status = options.status ?? 307;
     if (getEnv().side === "server") {
       const { getRequest, headers: requestHeaders } = getServerRequestContext();
       const h = requestHeaders();
@@ -257,9 +265,9 @@ class Router {
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
       const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");
       Logger.log(`redirect to:${pathname}`);
-      throw new AkanRedirectError(fullHref, "replace");
+      throw new AkanRedirectError(fullHref, method, status);
     } else {
-      this.#instance.replace(href);
+      this.#instance[method](href);
     }
     return undefined as never;
   }

package/fetch/requestStorage.ts

@@ -1,15 +1,35 @@
-export interface RequestStorage {
-  run<T>(store: Request, callback: () => T): T;
-  getStore(): Request | undefined;
+export type AkanTheme = "css" | "system" | (string & {});
+
+export interface AkanRequestPolicy {
+  routeId?: string;
+  rscCache?: "public" | false;
+  rscCacheTtl?: number;
+  cacheable?: boolean;
+  revalidate?: number | false;
+  tags: Set<string>;
 }
 
-export type AkanTheme = "css" | "system" | (string & {});
+export interface AkanDynamicUsage {
+  headers: boolean;
+  cookies: boolean;
+}
+
+export interface AkanRequestStore {
+  request: Request;
+  theme?: AkanTheme;
+  queryCache: Map<string, Promise<unknown>>;
+  policy: AkanRequestPolicy;
+  dynamicUsage: AkanDynamicUsage;
+}
+
+export interface RequestStorage {
+  run<T>(store: Request | AkanRequestStore, callback: () => T): T;
+  getStore(): AkanRequestStore | undefined;
+}
 
 declare global {
   var __AKAN_REQUEST_STORAGE__: RequestStorage | undefined;
-  var __AKAN_REQUEST_THEME__: WeakMap<Request, AkanTheme> | undefined;
-  var __AKAN_REQUEST_QUERY_CACHE__: WeakMap<Request, Map<string, Promise<unknown>>> | undefined;
-  var __AKAN_REQUEST_FALLBACK_STACK__: Request[] | undefined;
+  var __AKAN_REQUEST_FALLBACK_STACK__: AkanRequestStore[] | undefined;
 }
 
 let _requestStorage: RequestStorage | null = null;
@@ -17,74 +37,120 @@ if (typeof window === "undefined") {
   try {
 
     const { AsyncLocalStorage } = require("node:async_hooks") as typeof import("node:async_hooks");
-    globalThis.__AKAN_REQUEST_STORAGE__ ??= new AsyncLocalStorage() as RequestStorage;
+    const als = new AsyncLocalStorage<AkanRequestStore>();
+    globalThis.__AKAN_REQUEST_STORAGE__ ??= {
+      run<T>(store: Request | AkanRequestStore, callback: () => T): T {
+        return als.run(normalizeRequestStore(store), callback);
+      },
+      getStore(): AkanRequestStore | undefined {
+        return als.getStore();
+      },
+    };
     _requestStorage = globalThis.__AKAN_REQUEST_STORAGE__;
   } catch {}
 }
 
 export const requestStorage: RequestStorage | null = _requestStorage;
 
-function requestThemeMap(): WeakMap<Request, AkanTheme> {
-  globalThis.__AKAN_REQUEST_THEME__ ??= new WeakMap<Request, AkanTheme>();
-  return globalThis.__AKAN_REQUEST_THEME__;
+function createRequestPolicy(): AkanRequestPolicy {
+  return { tags: new Set() };
+}
+
+export function createRequestStore(
+  request: Request,
+  policy: Partial<Omit<AkanRequestPolicy, "tags">> = {},
+): AkanRequestStore {
+  return {
+    request,
+    queryCache: new Map(),
+    policy: { ...createRequestPolicy(), ...policy },
+    dynamicUsage: { headers: false, cookies: false },
+  };
+}
+
+function isRequestStore(store: Request | AkanRequestStore | undefined): store is AkanRequestStore {
+  return Boolean(store && typeof store === "object" && "request" in store && store.request instanceof Request);
+}
+
+function normalizeRequestStore(store: Request | AkanRequestStore): AkanRequestStore {
+  return isRequestStore(store) ? store : createRequestStore(store);
 }
 
-function requestQueryCacheMap(): WeakMap<Request, Map<string, Promise<unknown>>> {
-  globalThis.__AKAN_REQUEST_QUERY_CACHE__ ??= new WeakMap<Request, Map<string, Promise<unknown>>>();
-  return globalThis.__AKAN_REQUEST_QUERY_CACHE__;
+function getActiveRequestStore(): AkanRequestStore | undefined {
+  const store = requestStorage?.getStore() as Request | AkanRequestStore | undefined;
+  if (store) return isRequestStore(store) ? store : createRequestStore(store);
+  return globalThis.__AKAN_REQUEST_FALLBACK_STACK__?.at(-1);
 }
 
 /** Stores theme preference on the active request when server rendering. */
 export function setRequestTheme(theme: AkanTheme | undefined): void {
-  const req = getRequest();
-  if (!req || theme === undefined) return;
-  requestThemeMap().set(req, theme);
+  const store = getRequestStore();
+  if (!store || theme === undefined) return;
+  store.theme = theme;
 }
 
 export function getRequestTheme(): AkanTheme | undefined {
-  const req = getRequest();
-  if (!req) return undefined;
-  return requestThemeMap().get(req);
+  return getRequestStore()?.theme;
 }
 
 export function pushRequestFallback(req: Request): () => void {
   globalThis.__AKAN_REQUEST_FALLBACK_STACK__ ??= [];
   const stack = globalThis.__AKAN_REQUEST_FALLBACK_STACK__;
-  stack.push(req);
+  const store = createRequestStore(req);
+  stack.push(store);
   return () => {
-    const index = stack.lastIndexOf(req);
+    const index = stack.lastIndexOf(store);
     if (index >= 0) stack.splice(index, 1);
   };
 }
 
+/** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
+export function getRequestStore(): AkanRequestStore | undefined {
+  return getActiveRequestStore();
+}
+
 /** Returns the active server request from AsyncLocalStorage or the fallback stack. */
 export function getRequest(): Request | undefined {
-  return requestStorage?.getStore() ?? globalThis.__AKAN_REQUEST_FALLBACK_STACK__?.at(-1);
+  return getRequestStore()?.request;
+}
+
+export function getRequestPolicy(): AkanRequestPolicy | undefined {
+  return getRequestStore()?.policy;
+}
+
+export function updateRequestPolicy(
+  patch: Partial<Omit<AkanRequestPolicy, "tags">> & { tags?: Iterable<string> },
+): AkanRequestPolicy | undefined {
+  const policy = getRequestPolicy();
+  if (!policy) return undefined;
+  const { tags, ...rest } = patch;
+  Object.assign(policy, rest);
+  if (tags) for (const tag of tags) policy.tags.add(tag);
+  return policy;
+}
+
+export function getRequestDynamicUsage(): AkanDynamicUsage | undefined {
+  return getRequestStore()?.dynamicUsage;
 }
 
 /** Deduplicates a promise-producing query within the active request. */
 export function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T> {
-  const req = getRequest();
-  if (!req) return factory();
-  const cacheMap = requestQueryCacheMap();
-  let cache = cacheMap.get(req);
-  if (!cache) {
-    cache = new Map<string, Promise<unknown>>();
-    cacheMap.set(req, cache);
-  }
-  const existing = cache.get(key);
+  const store = getRequestStore();
+  if (!store) return factory();
+  const existing = store.queryCache.get(key);
   if (existing) return existing as Promise<T>;
   const promise = factory();
-  cache.set(key, promise);
+  store.queryCache.set(key, promise);
   return promise;
 }
 
 /** Returns current request headers as a Map, or an empty Map outside a request. */
 export function headers(): Map<string, string> {
-  const req = getRequest();
+  const store = getRequestStore();
   const map = new Map<string, string>();
-  if (!req) return map;
-  req.headers.forEach((value, key) => {
+  if (!store) return map;
+  store.dynamicUsage.headers = true;
+  store.request.headers.forEach((value, key) => {
     map.set(key, value);
   });
   return map;
@@ -121,7 +187,8 @@ export function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry
 
 /** Returns parsed cookies from the current request, or an empty Map outside a request. */
 export function cookies(): Map<string, CookieEntry> {
-  const req = getRequest();
-  if (!req) return new Map();
-  return parseCookieHeader(req.headers.get("cookie") ?? "");
+  const store = getRequestStore();
+  if (!store) return new Map();
+  store.dynamicUsage.cookies = true;
+  return parseCookieHeader(store.request.headers.get("cookie") ?? "");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.11",
+  "version": "2.2.13-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -84,6 +84,8 @@ export class AkanApp {
   #logWriter: RotatingLogWriter | null = null;
   #removeLogSink: (() => void) | null = null;
   readonly #childOutputBuffers = new Map<string, string>();
+  readonly #childStderrBlockBuffers = new Map<string, string[]>();
+  readonly #childStderrBlockTimers = new Map<string, ReturnType<typeof setTimeout>>();
   static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
   #gatewayMetrics: AkanMetricsReport = {};
   #proxyHopCount = 0;
@@ -1004,6 +1006,7 @@ export class AkanApp {
       if (remaining) this.#writeChildOutput(idx, role, type, bufferKey, remaining);
     } finally {
       this.#flushChildOutput(idx, role, type, bufferKey);
+      if (type === "stderr") this.#flushChildStderrBlock(idx, role, AkanApp.#childStderrBlockKey(idx, role));
     }
   }
 
@@ -1028,11 +1031,63 @@ export class AkanApp {
   }
 
   #writeChildOutputLine(idx: number, role: AkanChildRole, type: "stdout" | "stderr", line: string) {
+    if (type === "stderr" && this.#bufferChildStderrLine(idx, role, line)) return;
+    this.#writeChildOutputLineRaw(idx, role, type, line);
+  }
+
+  #writeChildOutputLineRaw(idx: number, role: AkanChildRole, type: "stdout" | "stderr", line: string) {
     const prefixedLine = `[child:${idx} ${role}] [${type}] ${line}`;
     process[type].write(prefixedLine);
     this.#logWriter?.write(`${idx}-${role}`, AkanApp.#stripAnsi(prefixedLine));
   }
 
+  #bufferChildStderrLine(idx: number, role: AkanChildRole, line: string): boolean {
+    const key = AkanApp.#childStderrBlockKey(idx, role);
+    const block = this.#childStderrBlockBuffers.get(key) ?? [];
+    block.push(line);
+    this.#childStderrBlockBuffers.set(key, block);
+
+    const existingTimer = this.#childStderrBlockTimers.get(key);
+    if (existingTimer) clearTimeout(existingTimer);
+
+    if (line.trim() === "" || block.length >= 64) {
+      this.#flushChildStderrBlock(idx, role, key);
+      return true;
+    }
+
+    this.#childStderrBlockTimers.set(
+      key,
+      setTimeout(() => this.#flushChildStderrBlock(idx, role, key), 50),
+    );
+    return true;
+  }
+
+  #flushChildStderrBlock(idx: number, role: AkanChildRole, key: string) {
+    const timer = this.#childStderrBlockTimers.get(key);
+    if (timer) clearTimeout(timer);
+    this.#childStderrBlockTimers.delete(key);
+
+    const block = this.#childStderrBlockBuffers.get(key);
+    if (!block?.length) return;
+    this.#childStderrBlockBuffers.delete(key);
+
+    const text = block.join("");
+    if (AkanApp.#isBenignRsdwConnectionClosedBlock(text)) return;
+    for (const blockLine of block) this.#writeChildOutputLineRaw(idx, role, "stderr", blockLine);
+  }
+
+  static #childStderrBlockKey(idx: number, role: AkanChildRole): string {
+    return `${idx}:${role}:stderr`;
+  }
+
+  static #isBenignRsdwConnectionClosedBlock(text: string): boolean {
+    return (
+      text.includes('reportGlobalError(weakResponse, Error("Connection closed."))') &&
+      text.includes("error: Connection closed.") &&
+      text.includes("react-server-dom-webpack")
+    );
+  }
+
   static #stripAnsi(msg: string) {
     return msg.replace(AkanApp.#ansiPattern, "");
   }

package/server/hmr/clientScript.ts

@@ -45,11 +45,11 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         return;
       }
       if (msg.type === "rsc-refresh") {
-        reloadForHmr(msg);
+        refreshRsc(msg);
         return;
       }
       if (msg.type === "client-refresh") {
-        reloadForHmr(msg);
+        refreshClient(msg);
         return;
       }
       if (msg.type === "css-update") {
@@ -73,12 +73,6 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     setTimeout(connect, delay);
   }
 
-  function reloadForHmr(msg){
-    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
-    if (msg && msg.buildId != null) lastBuildId = msg.buildId;
-    location.reload();
-  }
-
   function ensureOverlay(){
     if (overlayEl && overlayLabelEl) return overlayEl;
     if (!overlayStyleEl) {

package/server/rscClient.tsx

@@ -1,11 +1,14 @@
 import { createElement, type ReactNode, startTransition, use, useLayoutEffect, useState } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+import { isRscPayloadResponse } from "./rscHttp";
+
+type InlineRscChunk = [1, string] | [3, string];
 
 declare global {
-  var __RSC_CHUNKS__: string[] | undefined;
+  var __RSC_CHUNKS__: InlineRscChunk[] | undefined;
   var __RSC_CLOSED__: boolean | undefined;
-  var __RSC_PUSH__: ((b64: string) => void) | undefined;
+  var __RSC_PUSH__: ((type: InlineRscChunk[0], data: string) => void) | undefined;
   var __RSC_CLOSE__: (() => void) | undefined;
   var __AKAN_RSC_NAVIGATE__:
     | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
@@ -21,15 +24,20 @@ function decodeBase64(b64: string): Uint8Array {
   return bytes;
 }
 
+function decodeInlineRscChunk([type, data]: InlineRscChunk): Uint8Array {
+  if (type === 1) return new TextEncoder().encode(data);
+  return decodeBase64(data);
+}
+
 type RscThenable = Promise<ReactNode>;
-type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected" };
+type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected"; status?: number };
 const MAX_RSC_CACHE_ENTRIES = 32;
 
 function createInitialRscStream(): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
     start(controller) {
       const queued = globalThis.__RSC_CHUNKS__ ?? [];
-      for (const b64 of queued) controller.enqueue(decodeBase64(b64));
+      for (const chunk of queued) controller.enqueue(decodeInlineRscChunk(chunk));
       globalThis.__RSC_CHUNKS__ = [];
 
       if (globalThis.__RSC_CLOSED__) {
@@ -37,7 +45,7 @@ function createInitialRscStream(): ReadableStream<Uint8Array> {
         return;
       }
 
-      globalThis.__RSC_PUSH__ = (b64: string) => controller.enqueue(decodeBase64(b64));
+      globalThis.__RSC_PUSH__ = (type, data) => controller.enqueue(decodeInlineRscChunk([type, data]));
       globalThis.__RSC_CLOSE__ = () => controller.close();
     },
   });
@@ -63,10 +71,12 @@ async function fetchRsc(href: string, options: { buildId?: number } = {}): Promi
   const redirect = res.headers.get("X-Akan-Redirect");
   if (redirect) {
     const method = res.headers.get("X-Akan-Redirect-Method");
+    const statusHeader = res.headers.get("X-Akan-Redirect-Status");
+    const status = statusHeader ? Number(statusHeader) : undefined;
     await globalThis.__AKAN_RSC_NAVIGATE__?.(redirect, { replace: method !== "push", scrollToTop: true });
-    return { type: "redirected" };
+    return { type: "redirected", status };
   }
-  if (!res.ok || !res.body) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
+  if (!isRscPayloadResponse(res)) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
 
   const buffer = await res.arrayBuffer();
   const completeStream = new ReadableStream<Uint8Array>({

package/server/rscHttp.ts

@@ -0,0 +1,7 @@
+export const RSC_CONTENT_TYPE = "text/x-component; charset=utf-8";
+
+export function isRscPayloadResponse(res: Response): boolean {
+  if (!res.body) return false;
+  if (res.ok) return true;
+  return res.status === 404 && (res.headers.get("Content-Type") ?? "").toLowerCase().startsWith("text/x-component");
+}