@nsnanocat/preference-panes 0.4.1 → 0.5.0

package/dist/preference-panes.request.js

@@ -1295,6 +1295,304 @@
 	    });
 	}
 
+	/**
+	 * 统一请求参数。
+	 * Unified request payload.
+	 *
+	 * @typedef {object} FetchRequest
+	 * @property {string} url 请求地址 / Request URL.
+	 * @property {string} [method] 请求方法 / HTTP method.
+	 * @property {Record<string, any>} [headers] 请求头 / Request headers.
+	 * @property {string|ArrayBuffer|ArrayBufferView|object} [body] 请求体 / Request body.
+	 * @property {ArrayBuffer} [bodyBytes] 二进制请求体 / Binary request body.
+	 * @property {number|string} [timeout] 超时（秒或毫秒）/ Timeout (seconds or milliseconds).
+	 * @property {string} [policy] 指定策略 / Preferred policy.
+	 * @property {boolean} [redirection] 是否跟随重定向 / Whether to follow redirects.
+	 * @property {boolean} ["auto-redirect"] 平台重定向字段 / Platform redirect flag.
+	 * @property {boolean|number|string} ["auto-cookie"] Worker / Node.js Cookie 开关 / Worker / Node.js Cookie toggle.
+	 * @property {Record<string, any>} [opts] 平台扩展字段 / Platform extension fields.
+	 */
+
+	/**
+	 * 统一响应结构。
+	 * Unified response payload.
+	 *
+	 * @typedef {object} FetchResponse
+	 * @property {boolean} ok 请求是否成功 / Whether request is successful.
+	 * @property {number} status 状态码 / HTTP status code.
+	 * @property {number} [statusCode] 状态码别名 / Status code alias.
+	 * @property {string} [statusText] 状态文本 / HTTP status text.
+	 * @property {Record<string, any>} [headers] 响应头 / Response headers.
+	 * @property {string|ArrayBuffer} [body] 响应体 / Response body.
+	 * @property {ArrayBuffer} [bodyBytes] 二进制响应体 / Binary response body.
+	 */
+
+	/**
+	 * 跨平台 `fetch` 适配层。
+	 * Cross-platform `fetch` adapter.
+	 *
+	 * 设计目标:
+	 * Design goal:
+	 * - 仿照 Web API `fetch`（`Window.fetch`）接口设计
+	 * - Modeled after Web API `fetch` (`Window.fetch`)
+	 * - 统一 VPN App、Worker 与 Node.js 环境中的请求调用
+	 * - Unify request calls across VPN apps, Worker, and Node.js
+	 *
+	 * 功能:
+	 * Features:
+	 * - 统一 Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Worker / Node.js 请求接口
+	 * - Normalize request APIs across Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Worker / Node.js
+	 * - 统一返回体字段（`ok/status/statusText/body/bodyBytes`）
+	 * - Normalize response fields (`ok/status/statusText/body/bodyBytes`)
+	 *
+	 * 与 Web `fetch` 的已知差异:
+	 * Known differences from Web `fetch`:
+	 * - 支持 `policy`、`auto-redirect` 等平台扩展字段
+	 * - Supports platform extension fields like `policy` and `auto-redirect`
+	 * - Worker / Node.js 共享基于 `fetch` 的请求分支
+	 * - Worker / Node.js share the `fetch`-based request branch
+	 * - Node.js ESM 的 `auto-cookie` 由 `fetch.node.mjs` 处理，本文件只使用宿主 `fetch`
+	 * - Node.js ESM `auto-cookie` is handled by `fetch.node.mjs`; this module only uses the host `fetch`
+	 * - 非浏览器平台通过 `$httpClient/$task` 实现，不是原生 Fetch 实现
+	 * - Non-browser platforms use `$httpClient/$task` instead of native Fetch engine
+	 * - 返回结构包含 `statusCode/bodyBytes` 等兼容字段
+	 * - Response includes compatibility fields like `statusCode/bodyBytes`
+	 *
+	 * @link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
+	 * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Window/fetch
+	 * @async
+	 * @param {FetchRequest|string} resource 请求对象或 URL / Request object or URL string.
+	 * @param {Partial<FetchRequest>} [options={}] 追加参数 / Extra options.
+	 * @returns {Promise<FetchResponse>}
+	 */
+	async function fetch(resource, options = {}) {
+		// 初始化参数。
+		// Initialize request input.
+		switch (typeof resource) {
+			case "object":
+				resource = { ...options, ...resource };
+				break;
+			case "string":
+				resource = { ...options, url: resource };
+				break;
+			case "undefined":
+			default:
+				throw new TypeError(`${Function.name}: 参数类型错误, resource 必须为对象或字符串`);
+		}
+		// 自动判断请求方法。
+		// Infer the HTTP method automatically.
+		if (!resource.method) {
+			resource.method = "GET";
+			if (resource.body ?? resource.bodyBytes) resource.method = "POST";
+		}
+		// 移除需要由底层实现自动生成的请求头。
+		// Remove headers that should be generated by the underlying runtime.
+		delete resource.headers?.Host;
+		delete resource.headers?.[":authority"];
+		delete resource.headers?.["Content-Length"];
+		delete resource.headers?.["content-length"];
+		// 统一请求方法为小写，方便后续索引平台 API。
+		// Normalize the method to lowercase for platform API lookups.
+		const method = resource.method.toLocaleLowerCase();
+		// 默认请求超时时间为 5 秒。
+		// Default request timeout to 5 seconds.
+		if (!resource.timeout) resource.timeout = 5;
+		if (resource.timeout) {
+			resource.timeout = Number.parseInt(resource.timeout, 10);
+			// 统一先转换为秒，大于 500 视为毫秒输入。
+			// Convert to seconds first and treat values above 500 as milliseconds.
+			if (resource.timeout > 500) resource.timeout = Math.round(resource.timeout / 1000);
+		}
+		if (resource.timeout) {
+			switch ($app) {
+				case "Loon":
+				case "Quantumult X":
+				case "Worker":
+				case "Node.js":
+					// 这些平台要求毫秒，因此把秒重新换算为毫秒。
+					// These platforms expect milliseconds, so convert seconds back to milliseconds.
+					resource.timeout = resource.timeout * 1000;
+					break;
+			}
+		}
+		// 根据当前平台选择请求实现。
+		// Select the request engine for the current platform.
+		switch ($app) {
+			case "Loon":
+			case "Surge":
+			case "Stash":
+			case "Egern":
+			case "Shadowrocket":
+				// 转换通用请求参数到 `$httpClient` 语义。
+				// Map shared request fields to `$httpClient` semantics.
+				if (resource.policy) {
+					switch ($app) {
+						case "Loon":
+							resource.node = resource.policy;
+							break;
+						case "Stash":
+							Lodash.set(resource, "headers.X-Stash-Selected-Proxy", encodeURI(resource.policy));
+							break;
+						case "Shadowrocket":
+							Lodash.set(resource, "headers.X-Surge-Proxy", resource.policy);
+							break;
+					}
+				}
+				if (typeof resource.redirection === "boolean") resource["auto-redirect"] = resource.redirection;
+				// 优先把 `bodyBytes` 映射回 `$httpClient` 能接受的 `body`。
+				// Prefer mapping `bodyBytes` back to the `body` field expected by `$httpClient`.
+				if (resource.bodyBytes && !resource.body) {
+					resource.body = resource.bodyBytes;
+					resource.bodyBytes = undefined;
+				}
+				// 根据 `Accept` 推断是否需要二进制响应体。
+				// Infer whether the response should be treated as binary from `Accept`.
+				switch ((resource.headers?.Accept || resource.headers?.accept)?.split(";")?.[0]) {
+					case "application/protobuf":
+					case "application/x-protobuf":
+					case "application/vnd.google.protobuf":
+					case "application/vnd.apple.flatbuffer":
+					case "application/grpc":
+					case "application/grpc-web":
+					case "application/grpc+proto":
+					case "application/octet-stream":
+						resource["binary-mode"] = true;
+						break;
+				}
+				// 发送 `$httpClient` 请求并归一化返回结构。
+				// Send the `$httpClient` request and normalize the response payload.
+				return new Promise((resolve, reject) => {
+					globalThis.$httpClient[method](resource, (error, response, body) => {
+						if (error) reject(error);
+						else {
+							response.ok = /^2\d\d$/.test(response.status);
+							response.statusCode = response.status;
+							response.statusText = StatusTexts[response.status];
+							if (body) {
+								response.body = body;
+								if (resource["binary-mode"] == true) response.bodyBytes = body;
+							}
+							resolve(response);
+						}
+					});
+				});
+			case "Quantumult X":
+				// 转换 Quantumult X 专有请求参数。
+				// Map request fields to Quantumult X specific options.
+				if (resource.policy) Lodash.set(resource, "opts.policy", resource.policy);
+				if (typeof resource["auto-redirect"] === "boolean") Lodash.set(resource, "opts.redirection", resource["auto-redirect"]);
+				// Quantumult X 使用 `bodyBytes` 传输二进制请求体。
+				// Quantumult X uses `bodyBytes` for binary request payloads.
+				if (resource.body instanceof ArrayBuffer) {
+					resource.bodyBytes = resource.body;
+					resource.body = undefined;
+				} else if (ArrayBuffer.isView(resource.body)) {
+					resource.bodyBytes = resource.body.buffer.slice(resource.body.byteOffset, resource.body.byteLength + resource.body.byteOffset);
+					resource.body = undefined;
+				} else if (resource.body) resource.bodyBytes = undefined;
+				// 发送请求，并用 `Promise.race` 提供统一超时保护。
+				// Send the request and enforce timeout with `Promise.race`.
+				return Promise.race([
+					globalThis.$task.fetch(resource).then(
+						response => {
+							response.ok = /^2\d\d$/.test(response.statusCode);
+							response.status = response.statusCode;
+							response.statusText = StatusTexts[response.status];
+							switch ((response.headers?.["Content-Type"] ?? response.headers?.["content-type"])?.split(";")?.[0]) {
+								case "application/protobuf":
+								case "application/x-protobuf":
+								case "application/vnd.google.protobuf":
+								case "application/vnd.apple.flatbuffer":
+								case "application/grpc":
+								case "application/grpc-web":
+								case "application/grpc+proto":
+								case "application/octet-stream":
+									response.body = response.bodyBytes;
+									break;
+							}
+							response.bodyBytes = undefined;
+							return response;
+						},
+						reason => Promise.reject(reason.error),
+					),
+					new Promise((resolve, reject) => {
+						setTimeout(() => {
+							reject(new Error(`${Function.name}: 请求超时, 请检查网络后重试`));
+						}, resource.timeout);
+					}),
+				]);
+			case "Worker":
+			case "Node.js":
+			default: {
+				let request;
+				let timeout;
+				let shouldWrapError = false;
+				switch ($app) {
+					case "Worker":
+					case "Node.js":
+						switch (typeof globalThis.fetch) {
+							case "function":
+								break;
+							default:
+								throw new Error(`${Function.name}: 当前运行环境不支持 Fetch API`);
+						}
+						// 将通用字段映射到 Worker / Node.js Fetch 语义。
+						// Map shared fields to Worker / Node.js Fetch semantics.
+						resource.redirect = resource.redirection ? "follow" : "manual";
+						request = resource;
+						timeout = resource.timeout;
+						shouldWrapError = true;
+						break;
+					default: {
+						// 未识别宿主也可使用完整标准 Fetch API；不将能力推断为宿主类型。
+						// An unrecognized host may still use the complete standard Fetch API; capability does not imply a host type.
+						if (typeof globalThis.fetch !== "function" || typeof globalThis.Headers !== "function" || typeof globalThis.Request !== "function" || typeof globalThis.Response !== "function") {
+							throw new Error(`${Function.name}: 当前运行环境不支持 Fetch API`);
+						}
+						const { url, bodyBytes, redirection, timeout: _timeout, policy: _policy, "auto-redirect": _autoRedirect, "auto-cookie": _autoCookie, opts: _opts, ...fetchOptions } = resource;
+						if (bodyBytes !== undefined && fetchOptions.body === undefined) fetchOptions.body = bodyBytes;
+						fetchOptions.redirect = redirection ? "follow" : "manual";
+						request = { url, ...fetchOptions };
+						timeout = resource.timeout * 1000;
+						break;
+					}
+				}
+				const { url, ...options } = request;
+				// 发起请求并归一化响应头、文本与二进制响应体。
+				// Send the request and normalize headers, text, and binary response data.
+				const responsePromise = globalThis.fetch(url, options).then(async response => {
+					const bodyBytes = await response.arrayBuffer();
+					let headers;
+					try {
+						headers = response.headers.raw();
+					} catch {
+						headers = Array.from(response.headers.entries()).reduce((acc, [key, value]) => {
+							acc[key] = acc[key] ? [...acc[key], value] : [value];
+							return acc;
+						}, {});
+					}
+					return {
+						ok: response.ok ?? /^2\d\d$/.test(response.status),
+						status: response.status,
+						statusCode: response.status,
+						statusText: response.statusText,
+						body: new TextDecoder("utf-8").decode(bodyBytes),
+						bodyBytes: bodyBytes,
+						headers: Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, key.toLowerCase() !== "set-cookie" ? value.toString() : value])),
+					};
+				});
+				return Promise.race([
+					shouldWrapError ? responsePromise.catch(error => Promise.reject(error.message)) : responsePromise,
+					new Promise((_resolve, reject) => {
+						setTimeout(() => {
+							reject(new Error(`${Function.name}: 请求超时, 请检查网络后重试`));
+						}, timeout);
+					}),
+				]);
+			}
+		}
+	}
+
 	/**
 	 * 跨平台持久化存储适配器。
 	 * Cross-platform persistent storage adapter.
@@ -1746,15 +2044,63 @@
 	}
 
 	/**
-	 * 读取代理参数、执行处理器并将响应交给宿主 done。
-	 * Read proxy arguments, execute the handler and pass the response to the host's done function.
-	 * @returns {Promise<void>} 代理脚本执行结束 / Proxy script execution completion.
+	 * 统一处理存储 API 和无原生 Mock 平台的静态资源请求。
+	 * Handle storage APIs and static resources on hosts without native Mock support.
 	 */
-	(async () => {
+	class PreferencesHandler extends SettingsHandler {
+		#origin;
+		#resources;
+		/**
+		 * 根据安装 JSON 配置资源映射，不执行项目自定义代码。
+		 * Configure resource mappings from installation JSON without project-specific code.
+		 * @param {import("./index.js").PreferencesHandlerOptions} options 安装映射 / Installation mapping.
+		 */
+		constructor(options) {
+			super(options);
+			this.#origin = new URL(options.origin).origin;
+			this.#resources = options.resources.map(({ pattern, source, contentType }) => {
+				const url = new URL(source);
+				if (url.protocol !== "https:") throw new TypeError("Resource sources must use HTTPS");
+				if (typeof contentType !== "string" || /[\r\n]/.test(contentType)) throw new TypeError("Invalid resource content type");
+				return { pattern: new RegExp(pattern), source: url.href, contentType };
+			});
+		}
+		/**
+		 * API 先交给存储桥接，只有资源路由才发出下载请求。
+		 * Dispatch APIs to storage first; only resource routes perform downloads.
+		 * @param {import("./index.js").SettingsRequest} request 宿主请求 / Host request.
+		 * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 响应或非接管请求 / Response or unhandled request.
+		 */
+		async handle(request) {
+			const api = await super.handle(request);
+			if (api) return api;
+			const url = new URL(request.url);
+			if (url.origin !== this.#origin) return;
+			const resource = this.#resources.find(resource => resource.pattern.test(url.pathname));
+			if (!resource) return;
+			switch (request.method) {
+				case "GET":
+				case "HEAD": {
+					const response = await fetch({ url: resource.source, method: "GET", headers: { "Cache-Control": "no-cache" }, timeout: 5000 });
+					return { status: response.status, headers: { "Content-Type": `${resource.contentType}; charset=utf-8`, "Cache-Control": "no-store" }, body: request.method === "HEAD" ? "" : response.body };
+				}
+				default:
+					return { status: 405, headers: { Allow: "HEAD, GET" }, body: "" };
+			}
+		}
+	}
+
+	/**
+	 * 执行独立代理脚本；安装映射由托管站点生成，或由宿主参数提供。
+	 * Run a standalone proxy script with a site-generated installation mapping or host arguments.
+	 * @param {import("../index.js").PreferencesHandlerOptions} [options] 安装映射 / Installation mapping.
+	 * @returns {Promise<void>} 已交给宿主的响应 / Response delivered to the proxy host.
+	 */
+	async function runPreferences(options) {
 		let response;
 		try {
-			const { origin, storageKey, module } = qs.parse(globalThis.$argument);
-			const handler = new SettingsHandler({ origin, storageKey, module });
+			const config = options ?? qs.parse(globalThis.$argument);
+			const handler = new PreferencesHandler({ ...config, resources: config.resources ?? [] });
 			response = await handler.handle(globalThis.$request);
 		} catch (error) {
 			console.error(`PreferencePanes: ${error.message}`);
@@ -1769,6 +2115,10 @@
 			return;
 		}
 		done($app === "Quantumult X" ? response : { response });
-	})();
+	}
+
+	// 直接安装时读取宿主参数；站点生成的脚本使用同一执行入口并传入安装映射。
+	// Direct installs read host arguments; site-generated scripts call the same entry with a mapping.
+	runPreferences();
 
 })();

package/dist/settings/index.html

@@ -5,11 +5,11 @@
   <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
   <meta name="color-scheme" content="light dark">
   <title>Preferences</title>
-  <link rel="stylesheet" href="/settings/assets/panel.css?v=0.4.1">
-  <link rel="stylesheet" href="/settings/assets/home.css?v=0.4.1">
+  <link rel="stylesheet" href="/settings/assets/panel.css?v=0.5.0">
+  <link rel="stylesheet" href="/settings/assets/home.css?v=0.5.0">
 </head>
 <body>
   <main id="preferences"></main>
-  <script type="module" src="/settings/assets/app.mjs?v=0.4.1"></script>
+  <script type="module" src="/settings/assets/app.mjs?v=0.5.0"></script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nsnanocat/preference-panes",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Shared settings API runtime for JavaScript proxy modules",
 	"author": "VirgilClyne <Virgil@nanocat.me>",
 	"homepage": "https://NSNanoCat.github.io/preference-panes",
@@ -29,6 +29,7 @@
 		"./browser/panel.css": "./src/browser/panel.css",
 		"./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
 		"./dist/preference-panes.request.js": "./dist/preference-panes.request.js",
+		"./dist/preference-panes.proxy.js": "./dist/preference-panes.proxy.js",
 		"./dist/settings/*": "./dist/settings/*"
 	},
 	"types": "src/index.d.ts",

package/src/proxy/handler.mjs

@@ -0,0 +1,31 @@
+import { $app } from "@nsnanocat/util/lib/app.mjs";
+import { done } from "@nsnanocat/util/lib/done.mjs";
+import { qs } from "@nsnanocat/util/polyfill/qs.mjs";
+import { PreferencesHandler } from "../PreferencesHandler.mjs";
+
+/**
+ * 执行独立代理脚本；安装映射由托管站点生成，或由宿主参数提供。
+ * Run a standalone proxy script with a site-generated installation mapping or host arguments.
+ * @param {import("../index.js").PreferencesHandlerOptions} [options] 安装映射 / Installation mapping.
+ * @returns {Promise<void>} 已交给宿主的响应 / Response delivered to the proxy host.
+ */
+export async function runPreferences(options) {
+	let response;
+	try {
+		const config = options ?? qs.parse(globalThis.$argument);
+		const handler = new PreferencesHandler({ ...config, resources: config.resources ?? [] });
+		response = await handler.handle(globalThis.$request);
+	} catch (error) {
+		console.error(`PreferencePanes: ${error.message}`);
+		response = {
+			status: 500,
+			headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
+			body: globalThis.$request.method === "HEAD" ? "" : JSON.stringify({ error: "Settings execution failed" }),
+		};
+	}
+	if (!response) {
+		done({});
+		return;
+	}
+	done($app === "Quantumult X" ? response : { response });
+}

package/src/proxy/request.mjs

@@ -1,30 +1,5 @@
-import { $app } from "@nsnanocat/util/lib/app.mjs";
-import { done } from "@nsnanocat/util/lib/done.mjs";
-import { qs } from "@nsnanocat/util/polyfill/qs.mjs";
-import { SettingsHandler } from "../SettingsHandler.mjs";
+import { runPreferences } from "./handler.mjs";
 
-/**
- * 读取代理参数、执行处理器并将响应交给宿主 done。
- * Read proxy arguments, execute the handler and pass the response to the host's done function.
- * @returns {Promise<void>} 代理脚本执行结束 / Proxy script execution completion.
- */
-(async () => {
-	let response;
-	try {
-		const { origin, storageKey, module } = qs.parse(globalThis.$argument);
-		const handler = new SettingsHandler({ origin, storageKey, module });
-		response = await handler.handle(globalThis.$request);
-	} catch (error) {
-		console.error(`PreferencePanes: ${error.message}`);
-		response = {
-			status: 500,
-			headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
-			body: globalThis.$request.method === "HEAD" ? "" : JSON.stringify({ error: "Settings execution failed" }),
-		};
-	}
-	if (!response) {
-		done({});
-		return;
-	}
-	done($app === "Quantumult X" ? response : { response });
-})();
+// 直接安装时读取宿主参数；站点生成的脚本使用同一执行入口并传入安装映射。
+// Direct installs read host arguments; site-generated scripts call the same entry with a mapping.
+runPreferences();