@dsh-plus/web-cache-headers 0.1.0 → 0.1.1

package/lib/index.d.ts

@@ -1,12 +1,16 @@
+import { UnwrapVolatile } from "@dsh-plus/shared";
 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>;
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  enabled: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  enabled: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+type WebCacheHeadersConfigFields = Schemastery.TypeT<typeof Config>;
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+type WebCacheHeadersConfig = UnwrapVolatile<WebCacheHeadersConfigFields>;
 //#endregion
 //#region src/ns.d.ts
 /**
@@ -20,12 +24,12 @@ declare const SETTINGS_NS = "dsh-plus-web-cache-headers";
 //#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 缺席时的默认值来源）。
+ * 装配补丁并接线配置源：0.1.7 起配置为 loader 解析的 volatile 活动字段
+ * （用户层 override 并入行级 config，写入原位提交），enabled 翻转即时装/卸
+ * 补丁，无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+ * @param ctx - 宿主上下文。
+ * @param config - 活动字段形态的行级 config（测试可传平面值）。
  */
-declare function apply(ctx: Context, config: WebCacheHeadersConfig): void;
+declare function apply(ctx: Context, config: WebCacheHeadersConfig | WebCacheHeadersConfigFields): void;
 //#endregion
 export { Config, SETTINGS_NS, type WebCacheHeadersConfig, apply, name };

package/lib/index.js

@@ -1,25 +1,6 @@
-import z from "@deepseek-ai/schemastery";
+import { unwrapVolatile } from "@dsh-plus/shared";
 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
+import z from "@deepseek-ai/schemastery";
 //#region src/decision.ts
 /**
 * 缓存头决策（纯函数，零 IO）：给定请求方法、URL、响应状态与「响应是否已带
@@ -102,14 +83,34 @@ function uninstallImmutableAssetsPatch() {
 	originalWriteHead = void 0;
 }
 //#endregion
+//#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).volatile() });
+//#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/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 缺席时的默认值来源）。
+* 装配补丁并接线配置源：0.1.7 起配置为 loader 解析的 volatile 活动字段
+* （用户层 override 并入行级 config，写入原位提交），enabled 翻转即时装/卸
+* 补丁，无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+* @param ctx - 宿主上下文。
+* @param config - 活动字段形态的行级 config（测试可传平面值）。
 */
 function apply(ctx, config) {
 	const logger = ctx.logger("web-cache-headers");
@@ -125,17 +126,8 @@ function apply(ctx, config) {
 		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);
-			}
-		});
-	});
+	const current = () => unwrapVolatile(config);
+	ctx.events.on("loader/volatile-update", () => sync(current().enabled));
 	sync(current().enabled);
 	ctx.effect(() => () => sync(false), "web-cache-headers: dispose 卸下补丁");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/web-cache-headers",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "dsh-plus service plugin: GUI 静态资源长缓存——为内容哈希的 /assets/* 响应补 `Cache-Control: immutable`（/plugins 官方已自带），消除每次刷新重复传输 ~1.4MB JS/CSS；进程级 writeHead 增量拦截，零路由注册、零 dsh 服务耦合，已有缓存头优先保证未来共存",
   "type": "module",
   "main": "lib/index.js",
@@ -17,15 +17,18 @@
     "lib",
     "src"
   ],
+  "dependencies": {
+    "@dsh-plus/shared": "0.1.22"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-settings": "^0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-settings": "0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "3.18.2"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-settings": "0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.4"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -7,14 +7,21 @@
  * @module @dsh-plus/web-cache-headers/config
  */
 import z from '@deepseek-ai/schemastery'
+import type { UnwrapVolatile } from '@dsh-plus/shared'
 
+// 0.1.7：`.volatile()` 使条目进入 settings describe 视图（卡片可读写）并让
+// loader 以活动引用原位提交热更新。
 export const Config = z.object({
   enabled: z
     .boolean()
     .description(
       '总开关（false = 卸下补丁，响应头恢复 dsh 原生行为）；development 环境恒禁用以保护 dev/HMR',
     )
-    .default(true),
+    .default(true)
+    .volatile(),
 })
 
-export type WebCacheHeadersConfig = Schemastery.TypeT<typeof Config>
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+export type WebCacheHeadersConfigFields = Schemastery.TypeT<typeof Config>
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+export type WebCacheHeadersConfig = UnwrapVolatile<WebCacheHeadersConfigFields>

package/src/index.ts

@@ -23,26 +23,30 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-settings'
+import { unwrapVolatile } from '@dsh-plus/shared'
 
-import { Config, type WebCacheHeadersConfig } from './config.ts'
-import { SETTINGS_NS } from './ns.ts'
+import type { WebCacheHeadersConfig, WebCacheHeadersConfigFields } from './config.ts'
 import { installImmutableAssetsPatch, uninstallImmutableAssetsPatch } from './patch.ts'
 
 export const name = 'dsh-plus-web-cache-headers'
 
 /** 无硬 inject：见模块头「结构守卫」。 */
 
+export { Config } from './config.ts'
+export { SETTINGS_NS } from './ns.ts'
 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 缺席时的默认值来源）。
+ * 装配补丁并接线配置源：0.1.7 起配置为 loader 解析的 volatile 活动字段
+ * （用户层 override 并入行级 config，写入原位提交），enabled 翻转即时装/卸
+ * 补丁，无需 /reload；插件 dispose（profile 卸载 / live reload）保证卸下。
+ * @param ctx - 宿主上下文。
+ * @param config - 活动字段形态的行级 config（测试可传平面值）。
  */
-export function apply(ctx: Context, config: WebCacheHeadersConfig): void {
+export function apply(
+  ctx: Context,
+  config: WebCacheHeadersConfig | WebCacheHeadersConfigFields,
+): void {
   const logger = ctx.logger('web-cache-headers')
   if (process.env.NODE_ENV === 'development') {
     logger.info('development 环境：自动禁用（保护 dev/HMR 同 URL 热更新）')
@@ -60,17 +64,10 @@ export function apply(ctx: Context, config: WebCacheHeadersConfig): void {
     )
   }
 
-  let current: () => WebCacheHeadersConfig = () => config
-  ctx.inject(['settings'], (settingsCtx) => {
-    settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, config, {
-      setSource: (source) => {
-        current = source
-      },
-      onChange: () => {
-        sync(current().enabled)
-      },
-    })
-  })
+  // 活动引用原位提交（替代 0.1.6 setSource/onChange）：每次读现取平面快照，
+  // volatile 提交事件驱动 enabled 翻转装卸。
+  const current = (): WebCacheHeadersConfig => unwrapVolatile(config)
+  ctx.events.on('loader/volatile-update', () => sync(current().enabled))
 
   sync(current().enabled)
   ctx.effect(() => () => sync(false), 'web-cache-headers: dispose 卸下补丁')