@dsh-plus/web-cache-headers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agguy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+declare const Config: z<Schemastery.ObjectS<{
+  enabled: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+  enabled: z<boolean, boolean>;
+}>>;
+type WebCacheHeadersConfig = Schemastery.TypeT<typeof Config>;
+//#endregion
+//#region src/ns.d.ts
+/**
+ * settings 命名空间字面量（纯常量，零依赖）。
+ * 服务端以字面量注册 settings section（用户层配置落 $DSH_HOME/settings.yaml，
+ * 热生效）；与行级 cordis Config 共用同一份 schemastery schema（config.ts）。
+ * @module @dsh-plus/web-cache-headers/ns
+ */
+declare const SETTINGS_NS = "dsh-plus-web-cache-headers";
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-plus-web-cache-headers";
+/**
+ * 装配补丁并接线配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）
+ * 优先，缺席/detach 回落 cordis 行级 config。enabled 翻转即时装/卸补丁，
+ * 无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+ * @param ctx - 宿主上下文（settings 可选）。
+ * @param config - 行级 config（settings 缺席时的默认值来源）。
+ */
+declare function apply(ctx: Context, config: WebCacheHeadersConfig): void;
+//#endregion
+export { Config, SETTINGS_NS, type WebCacheHeadersConfig, apply, name };

package/lib/index.js

@@ -0,0 +1,143 @@
+import z from "@deepseek-ai/schemastery";
+import http from "node:http";
+//#region src/config.ts
+/**
+* 插件配置（schemastery）：可调参数一律外部化，不在逻辑里硬编码。
+*
+* 与仓库既有约定一致：Config 由 cordis 行级 config 解析，部署方可在
+* profile 的 cordis.patch.yml 覆盖；同时经 settings namespace 暴露到
+* $DSH_HOME/settings.yaml 用户层，修改热生效（无需 /reload）。
+* @module @dsh-plus/web-cache-headers/config
+*/
+const Config = z.object({ enabled: z.boolean().description("总开关（false = 卸下补丁，响应头恢复 dsh 原生行为）；development 环境恒禁用以保护 dev/HMR").default(true) });
+//#endregion
+//#region src/ns.ts
+/**
+* settings 命名空间字面量（纯常量，零依赖）。
+* 服务端以字面量注册 settings section（用户层配置落 $DSH_HOME/settings.yaml，
+* 热生效）；与行级 cordis Config 共用同一份 schemastery schema（config.ts）。
+* @module @dsh-plus/web-cache-headers/ns
+*/
+const SETTINGS_NS = "dsh-plus-web-cache-headers";
+//#endregion
+//#region src/decision.ts
+/**
+* 缓存头决策（纯函数，零 IO）：给定请求方法、URL、响应状态与「响应是否已带
+* cache-control」，决定是否补 immutable 长缓存头。
+*
+* 命中条件（全部满足，缺一即不干预）：
+* - 方法为 GET/HEAD（静态资源读取语义；写操作永不缓存）；
+* - 响应状态恰为 200（错误/重定向/未修改一律不加，避免缓存污染）；
+* - 路径以 `/assets/` 前缀（带段边界：`/assets` 根与 `/assetsX` 均不命中）；
+* - 调用方（含 core 未来版本自带的策略）未设置过 cache-control —— 纯增量，
+*   已有策略永远优先。
+*
+* 为什么只认 `/assets/`：dsh 前端 dist（Vite 产物）全部文件内容哈希命名
+* （JS/CSS/字体/语言包已逐一核实），URL 即内容地址，immutable 安全；
+* `/plugins/*` 由 core 自带 `public, max-age=31536000, immutable`
+* （dsh-client-modules 的 IMMUTABLE_CACHE），不在此重复；index.html /
+* favicon / manifest 保持 dsh 原生行为（不缓存），确保插件清单与 rev 每次最新。
+* @module @dsh-plus/web-cache-headers/decision
+*/
+/** 与 dsh-client-modules 的 IMMUTABLE_CACHE 保持逐字节一致。 */
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** dsh 前端 dist 挂载点（段边界即末尾斜杠：排除 `/assetsX` 与 `/assets` 根）。 */
+const HASHED_ASSETS_PREFIX = "/assets/";
+/** 取 origin-form URL 的路径部分（剥查询串；HTTP 请求行不含 hash）。 */
+function pathnameOf(url) {
+	const queryAt = url.indexOf("?");
+	return queryAt === -1 ? url : url.slice(0, queryAt);
+}
+/**
+* 决策一个响应是否补 immutable 缓存头。
+* @param method - 请求方法（HTTP 方法大写敏感，按请求行原样传入）。
+* @param url - 请求 URL（origin-form，可带查询串）。
+* @param statusCode - 待写入的响应状态码。
+* @param hasCacheControl - 响应是否已带 cache-control（setHeader 或 writeHead 头对象任一）。
+* @returns 应写入的缓存头值；不干预时返回 undefined。
+*/
+function decideCacheControl(method, url, statusCode, hasCacheControl) {
+	if (hasCacheControl) return void 0;
+	if (method !== "GET" && method !== "HEAD") return void 0;
+	if (statusCode !== 200) return void 0;
+	if (!pathnameOf(url).startsWith(HASHED_ASSETS_PREFIX)) return void 0;
+	return IMMUTABLE_CACHE_CONTROL;
+}
+//#endregion
+//#region src/patch.ts
+let originalWriteHead;
+let installs = 0;
+/** 取 writeHead 可变参末位的头对象（不存在则 undefined；数组形态不支持也返回 undefined）。 */
+function headersObjectOf(args) {
+	if (args.length < 2) return void 0;
+	const last = args[args.length - 1];
+	if (last !== null && typeof last === "object" && !Array.isArray(last)) return last;
+}
+/** 头对象内是否已声明 cache-control（HTTP 头名大小写不敏感）。 */
+function objectHasCacheControl(headers) {
+	if (headers === void 0) return false;
+	return Object.keys(headers).some((name) => name.toLowerCase() === "cache-control");
+}
+/** 安装补丁（幂等，引用计数叠加）。 */
+function installImmutableAssetsPatch() {
+	installs += 1;
+	if (originalWriteHead !== void 0) return;
+	originalWriteHead = http.ServerResponse.prototype.writeHead;
+	const original = originalWriteHead;
+	const patched = function(...args) {
+		try {
+			const statusCode = typeof args[0] === "number" ? args[0] : 0;
+			const header = decideCacheControl(this.req?.method ?? "", this.req?.url ?? "", statusCode, this.getHeader("cache-control") !== void 0 || objectHasCacheControl(headersObjectOf(args)));
+			if (header !== void 0) this.setHeader("cache-control", header);
+		} catch {}
+		return original.apply(this, args);
+	};
+	http.ServerResponse.prototype.writeHead = patched;
+}
+/** 卸下补丁（引用计数归零才还原原型；超额调用安全）。 */
+function uninstallImmutableAssetsPatch() {
+	if (installs > 0) installs -= 1;
+	if (installs > 0 || originalWriteHead === void 0) return;
+	http.ServerResponse.prototype.writeHead = originalWriteHead;
+	originalWriteHead = void 0;
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-plus-web-cache-headers";
+/**
+* 装配补丁并接线配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）
+* 优先，缺席/detach 回落 cordis 行级 config。enabled 翻转即时装/卸补丁，
+* 无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+* @param ctx - 宿主上下文（settings 可选）。
+* @param config - 行级 config（settings 缺席时的默认值来源）。
+*/
+function apply(ctx, config) {
+	const logger = ctx.logger("web-cache-headers");
+	if (process.env.NODE_ENV === "development") {
+		logger.info("development 环境：自动禁用（保护 dev/HMR 同 URL 热更新）");
+		return;
+	}
+	let installed = false;
+	const sync = (enabled) => {
+		if (enabled === installed) return;
+		if (enabled) installImmutableAssetsPatch();
+		else uninstallImmutableAssetsPatch();
+		installed = enabled;
+		logger.info(enabled ? "已装配 /assets immutable 缓存头补丁" : "已卸下缓存头补丁（恢复 dsh 原生行为）");
+	};
+	let current = () => config;
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, config, {
+			setSource: (source) => {
+				current = source;
+			},
+			onChange: () => {
+				sync(current().enabled);
+			}
+		});
+	});
+	sync(current().enabled);
+	ctx.effect(() => () => sync(false), "web-cache-headers: dispose 卸下补丁");
+}
+//#endregion
+export { Config, SETTINGS_NS, apply, name };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dsh-plus/web-cache-headers",
+  "version": "0.1.0",
+  "description": "dsh-plus service plugin: GUI 静态资源长缓存——为内容哈希的 /assets/* 响应补 `Cache-Control: immutable`（/plugins 官方已自带），消除每次刷新重复传输 ~1.4MB JS/CSS；进程级 writeHead 增量拦截，零路由注册、零 dsh 服务耦合，已有缓存头优先保证未来共存",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-settings": "0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A-G-guy/dsh-plus.git",
+    "directory": "packages/web-cache-headers"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts -d lib --format esm --dts --no-fixed-extension"
+  }
+}

package/src/config.ts

@@ -0,0 +1,20 @@
+/**
+ * 插件配置（schemastery）：可调参数一律外部化，不在逻辑里硬编码。
+ *
+ * 与仓库既有约定一致：Config 由 cordis 行级 config 解析，部署方可在
+ * profile 的 cordis.patch.yml 覆盖；同时经 settings namespace 暴露到
+ * $DSH_HOME/settings.yaml 用户层，修改热生效（无需 /reload）。
+ * @module @dsh-plus/web-cache-headers/config
+ */
+import z from '@deepseek-ai/schemastery'
+
+export const Config = z.object({
+  enabled: z
+    .boolean()
+    .description(
+      '总开关（false = 卸下补丁，响应头恢复 dsh 原生行为）；development 环境恒禁用以保护 dev/HMR',
+    )
+    .default(true),
+})
+
+export type WebCacheHeadersConfig = Schemastery.TypeT<typeof Config>

package/src/decision.ts

@@ -0,0 +1,51 @@
+/**
+ * 缓存头决策（纯函数，零 IO）：给定请求方法、URL、响应状态与「响应是否已带
+ * cache-control」，决定是否补 immutable 长缓存头。
+ *
+ * 命中条件（全部满足，缺一即不干预）：
+ * - 方法为 GET/HEAD（静态资源读取语义；写操作永不缓存）；
+ * - 响应状态恰为 200（错误/重定向/未修改一律不加，避免缓存污染）；
+ * - 路径以 `/assets/` 前缀（带段边界：`/assets` 根与 `/assetsX` 均不命中）；
+ * - 调用方（含 core 未来版本自带的策略）未设置过 cache-control —— 纯增量，
+ *   已有策略永远优先。
+ *
+ * 为什么只认 `/assets/`：dsh 前端 dist（Vite 产物）全部文件内容哈希命名
+ * （JS/CSS/字体/语言包已逐一核实），URL 即内容地址，immutable 安全；
+ * `/plugins/*` 由 core 自带 `public, max-age=31536000, immutable`
+ * （dsh-client-modules 的 IMMUTABLE_CACHE），不在此重复；index.html /
+ * favicon / manifest 保持 dsh 原生行为（不缓存），确保插件清单与 rev 每次最新。
+ * @module @dsh-plus/web-cache-headers/decision
+ */
+
+/** 与 dsh-client-modules 的 IMMUTABLE_CACHE 保持逐字节一致。 */
+export const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+
+/** dsh 前端 dist 挂载点（段边界即末尾斜杠：排除 `/assetsX` 与 `/assets` 根）。 */
+const HASHED_ASSETS_PREFIX = '/assets/'
+
+/** 取 origin-form URL 的路径部分（剥查询串；HTTP 请求行不含 hash）。 */
+export function pathnameOf(url: string): string {
+  const queryAt = url.indexOf('?')
+  return queryAt === -1 ? url : url.slice(0, queryAt)
+}
+
+/**
+ * 决策一个响应是否补 immutable 缓存头。
+ * @param method - 请求方法（HTTP 方法大写敏感，按请求行原样传入）。
+ * @param url - 请求 URL（origin-form，可带查询串）。
+ * @param statusCode - 待写入的响应状态码。
+ * @param hasCacheControl - 响应是否已带 cache-control（setHeader 或 writeHead 头对象任一）。
+ * @returns 应写入的缓存头值；不干预时返回 undefined。
+ */
+export function decideCacheControl(
+  method: string,
+  url: string,
+  statusCode: number,
+  hasCacheControl: boolean,
+): string | undefined {
+  if (hasCacheControl) return undefined
+  if (method !== 'GET' && method !== 'HEAD') return undefined
+  if (statusCode !== 200) return undefined
+  if (!pathnameOf(url).startsWith(HASHED_ASSETS_PREFIX)) return undefined
+  return IMMUTABLE_CACHE_CONTROL
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * dsh 插件：GUI 静态资源长缓存（web-cache-headers）。
+ *
+ * 问题：dsh 前端 dist（`dsh-host-frontend-static` 经 fallback 服务）的响应只有
+ * content-type，无 Cache-Control/ETag——浏览器每次刷新都全量重下 ~1.4MB
+ * （gzip 后约 500KB）JS/CSS。而 dist 文件全部内容哈希命名，本可安全 immutable。
+ * `/plugins/*` 官方已自带 immutable 缓存头（dsh-client-modules），不在范围。
+ *
+ * 本插件只做一件事：进程级拦截 ServerResponse.writeHead，对内容寻址的
+ * `/assets/*` 200 响应补 `Cache-Control: public, max-age=31536000, immutable`。
+ * 纯增量、已有缓存头优先——dsh 升级自带策略时自动共存；唯一的关闭路径是
+ * settings 的 enabled=false（热生效），立刻恢复 dsh 原生行为。
+ *
+ * 明确不做：
+ * - 不注册任何路由（避免与 core 未来路由撞车）；
+ * - 不缓存 index.html / favicon / manifest（保持每次最新，插件 rev 清单不走缓存）；
+ * - 不触碰 `/plugins`（官方已 immutable）与任何插件 API 路由；
+ * - development 环境自动禁用，保护 dev/HMR 的 same-URL 热更新语义。
+ *
+ * 结构守卫（fail-safe）：inject 为空，不依赖任何 dsh 服务；宿主形态任何变更
+ * 都不影响本插件，反之本插件异常也绝不拖垮 boot（加头逻辑被隔离在 try 中）。
+ * @module @dsh-plus/web-cache-headers
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-settings'
+
+import { Config, type WebCacheHeadersConfig } from './config.ts'
+import { SETTINGS_NS } from './ns.ts'
+import { installImmutableAssetsPatch, uninstallImmutableAssetsPatch } from './patch.ts'
+
+export const name = 'dsh-plus-web-cache-headers'
+
+/** 无硬 inject：见模块头「结构守卫」。 */
+
+export type { WebCacheHeadersConfig }
+export { Config, SETTINGS_NS }
+
+/**
+ * 装配补丁并接线配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）
+ * 优先，缺席/detach 回落 cordis 行级 config。enabled 翻转即时装/卸补丁，
+ * 无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+ * @param ctx - 宿主上下文（settings 可选）。
+ * @param config - 行级 config（settings 缺席时的默认值来源）。
+ */
+export function apply(ctx: Context, config: WebCacheHeadersConfig): void {
+  const logger = ctx.logger('web-cache-headers')
+  if (process.env.NODE_ENV === 'development') {
+    logger.info('development 环境：自动禁用（保护 dev/HMR 同 URL 热更新）')
+    return
+  }
+
+  let installed = false
+  const sync = (enabled: boolean): void => {
+    if (enabled === installed) return
+    if (enabled) installImmutableAssetsPatch()
+    else uninstallImmutableAssetsPatch()
+    installed = enabled
+    logger.info(
+      enabled ? '已装配 /assets immutable 缓存头补丁' : '已卸下缓存头补丁（恢复 dsh 原生行为）',
+    )
+  }
+
+  let current: () => WebCacheHeadersConfig = () => config
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, config, {
+      setSource: (source) => {
+        current = source
+      },
+      onChange: () => {
+        sync(current().enabled)
+      },
+    })
+  })
+
+  sync(current().enabled)
+  ctx.effect(() => () => sync(false), 'web-cache-headers: dispose 卸下补丁')
+}

package/src/ns.ts

@@ -0,0 +1,7 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖）。
+ * 服务端以字面量注册 settings section（用户层配置落 $DSH_HOME/settings.yaml，
+ * 热生效）；与行级 cordis Config 共用同一份 schemastery schema（config.ts）。
+ * @module @dsh-plus/web-cache-headers/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-web-cache-headers'

package/src/patch.ts

@@ -0,0 +1,79 @@
+/**
+ * 进程级 `http.ServerResponse.prototype.writeHead` 增量补丁。
+ *
+ * 选型理由（对比"注册 /assets 前缀路由自行服务文件"）：
+ * - 零路由注册 —— core 未来若注册同名路由不会撞车 throw；
+ * - 零文件服务/MIME/穿越防护/dist 路径知识 —— core 服务文件的任何改动无需同步；
+ * - 唯一耦合点是 `/assets/` 路径约定与 core 经 writeHead 写响应（node:http
+ *   全代码库统一用法），是跟随 dsh 更新维护成本最低的切面。
+ *
+ * 正确性约束：
+ * - 纯增量：仅当决策命中且响应未带 cache-control 时 setHeader 一个头，
+ *   绝不改写既有头、绝不改状态码/响应体；
+ * - writeHead 全重载形态兼容（statusCode | +headers | +statusMessage+headers），
+ *   头对象中的 cache-control（大小写不敏感）同样被尊重；
+ * - 决策异常被吞掉并原样委托 —— 补丁处于所有响应的关键路径，绝不能让
+ *   加头逻辑影响响应写入；
+ * - 模块级引用计数：多实例（多 profile / live reload 先装后卸）可叠加安装，
+ *   计数归零才还原原型。
+ * @module @dsh-plus/web-cache-headers/patch
+ */
+import type { ServerResponse } from 'node:http'
+import http from 'node:http'
+
+import { decideCacheControl } from './decision.ts'
+
+type WriteHeadFn = ServerResponse['writeHead']
+
+let originalWriteHead: WriteHeadFn | undefined
+let installs = 0
+
+/** 取 writeHead 可变参末位的头对象（不存在则 undefined；数组形态不支持也返回 undefined）。 */
+function headersObjectOf(args: unknown[]): Record<string, unknown> | undefined {
+  if (args.length < 2) return undefined
+  const last = args[args.length - 1]
+  if (last !== null && typeof last === 'object' && !Array.isArray(last)) {
+    return last as Record<string, unknown>
+  }
+  return undefined
+}
+
+/** 头对象内是否已声明 cache-control（HTTP 头名大小写不敏感）。 */
+function objectHasCacheControl(headers: Record<string, unknown> | undefined): boolean {
+  if (headers === undefined) return false
+  return Object.keys(headers).some((name) => name.toLowerCase() === 'cache-control')
+}
+
+/** 安装补丁（幂等，引用计数叠加）。 */
+export function installImmutableAssetsPatch(): void {
+  installs += 1
+  if (originalWriteHead !== undefined) return
+  originalWriteHead = http.ServerResponse.prototype.writeHead
+  const original = originalWriteHead
+
+  const patched = function (this: ServerResponse, ...args: unknown[]) {
+    try {
+      const statusCode = typeof args[0] === 'number' ? args[0] : 0
+      const method = this.req?.method ?? ''
+      const url = this.req?.url ?? ''
+      const hasCacheControl =
+        this.getHeader('cache-control') !== undefined ||
+        objectHasCacheControl(headersObjectOf(args))
+      const header = decideCacheControl(method, url, statusCode, hasCacheControl)
+      if (header !== undefined) this.setHeader('cache-control', header)
+    } catch {
+      // 决策失败绝不阻断响应写入（补丁位于所有 HTTP 响应的关键路径）。
+    }
+    return (original as unknown as (...inner: unknown[]) => unknown).apply(this, args)
+  }
+
+  http.ServerResponse.prototype.writeHead = patched as unknown as WriteHeadFn
+}
+
+/** 卸下补丁（引用计数归零才还原原型；超额调用安全）。 */
+export function uninstallImmutableAssetsPatch(): void {
+  if (installs > 0) installs -= 1
+  if (installs > 0 || originalWriteHead === undefined) return
+  http.ServerResponse.prototype.writeHead = originalWriteHead
+  originalWriteHead = undefined
+}