@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.10 → 3.9.0-ultramodern.11

package/docs/en/guides/basic-features/render/ssr-cache.mdx

@@ -35,7 +35,7 @@ export interface CacheControl {
 }
 ```
 
-Here, `customKey` is the custom cache key. By default, Modern.js uses the request `pathname` as the cache key, but developers can define it when necessary.
+Here, `customKey` is the custom cache key. By default, the cache key is derived from the request's origin, normalized pathname (trailing slash removed), and query string. When `customKey` is set, it fully replaces the default key: the `customKey` callback receives the normalized pathname (not the `CacheOptionProvider`'s `req`) and is responsible for the whole partition (e.g. by tenant, host, or query) — it must not embed raw cookies or other credentials into the returned key.
 
 **Function Type**
 
@@ -106,6 +106,19 @@ export const cacheOption: CacheOption = {
 
 The above `/home` and `/about` are patterns, meaning `/home/abc` will also match. You can use regex in these patterns, such as `/home/.+`.
 
+### Cache Policy
+
+The following policy is enforced automatically and cannot be overridden by the returned `CacheControl`:
+
+- Only `GET` requests are cached.
+- A request carrying a `Cookie` or `Authorization` header skips the cache unless `customKey` is set, since a custom key is treated as an explicit partitioning contract.
+- A request with `Cache-Control: private`, `no-cache`, or `no-store` skips the cache.
+- A response is only stored when it is `200`, has no `private`/`no-cache`/`no-store` in `Cache-Control`, has no `Set-Cookie`, and has no nonempty `Vary` header; otherwise any existing cache entry for that key is deleted instead of being written.
+- If a `stale` revalidation produces a response that is no longer cacheable (for example, it became per-user), that already-served stale response is unaffected, but the cache entry is evicted so subsequent requests no longer hit it.
+- A `CacheOptionProvider` returning `false` still disables caching entirely for that request, independent of the policy above.
+
+Cache keys are namespaced (`__ssr__cache:v2:...`). Older un-namespaced entries — including ones already stored in a custom `Container` — are never read back; they simply age out under the container's own eviction/TTL. There is no global cache flush.
+
 ### Cache Container
 
 By default, the server uses memory for caching. Typically, services are deployed in a Serverless container, creating a new process for each access, making it impossible to use the previous cache.

package/docs/zh/guides/basic-features/render/ssr-cache.mdx

@@ -39,7 +39,7 @@ export interface CacheControl {
 }
 ```
 
-其中 `customKey` 为自定义缓存 key。默认情况下 Modern.js 将会把请求 `pathname` 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
+其中 `customKey` 为自定义缓存 key。默认情况下，缓存 key 由请求的 origin、归一化后的 pathname（去除末尾斜杠）以及 query 组成。当设置了 `customKey` 后，它会完全替代默认 key：`customKey` 回调函数接收的是归一化后的 pathname（而非 `CacheOptionProvider` 的 `req`），并需要自行负责整个分区（例如按租户、host 或 query 区分）——不能将原始 cookie 或其他凭证嵌入返回的 key 中。
 
 **Function 类型**
 
@@ -111,6 +111,19 @@ export const cacheOption: CacheOption = {
 
 上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。同时，你也可以在其中编写正则语法：`/home/.+`
 
+### 缓存策略
+
+以下策略由框架自动执行，返回的 `CacheControl` 无法覆盖：
+
+- 只有 `GET` 请求会被缓存。
+- 请求携带 `Cookie` 或 `Authorization` 请求头时会跳过缓存，除非设置了 `customKey`（自定义 key 被视为一份明确的分区约定）。
+- 请求的 `Cache-Control` 为 `private`、`no-cache` 或 `no-store` 时会跳过缓存。
+- 只有当响应为 `200`、`Cache-Control` 中不含 `private`/`no-cache`/`no-store`、不含 `Set-Cookie`、也不含非空的 `Vary` 头时才会被写入缓存；否则会删除该 key 已有的缓存条目，而不是写入新的。
+- 当 `stale` 状态触发的重新渲染结果不再可缓存时（例如变为按用户区分），本次已返回的 stale 响应不受影响，但缓存条目会被清除，后续请求将不再命中该缓存。
+- `CacheOptionProvider` 返回 `false` 依然会完全禁用该请求的缓存，不受上述策略影响。
+
+缓存 key 带有命名空间（`__ssr__cache:v2:...`）。旧版本未加命名空间的缓存条目（包括自定义 `Container` 中已存储的条目）不会再被读取，只会依据容器自身的淘汰/TTL 机制自然过期；不存在全局缓存清空操作。
+
 ### 缓存容器
 
 默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 Serverless 容器上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存。

package/package.json

@@ -19,13 +19,13 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.9.0-ultramodern.10",
+  "version": "3.9.0-ultramodern.11",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.10",
-    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.10",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.11",
+    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.11",
     "mermaid": "^11.17.2"
   },
   "devDependencies": {