@xiao-ying/miniapp-proxy 1.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+Shanghai Plum Technology Ltd. Software License Agreement
+
+This License Agreement ("Agreement") is a legal agreement between you (either an individual or a single entity, hereafter "Licensee") and Shanghai Plum Technology Ltd. ("Plum") for the software product accompanying this Agreement, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("Software").
+
+BY INSTALLING, COPYING, OR OTHERWISE USING THE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT INSTALL OR USE THE SOFTWARE.
+
+1. Grant of License. Plum grants Licensee a non-exclusive, non-transferable, limited license to use the Software solely for Licensee's internal business purposes, subject to the terms and conditions of this Agreement. THIS LICENSE IS GRANTED ONLY TO ENTITIES OR INDIVIDUALS WHO HAVE OBTAINED AN OFFICIAL SERVICE AGREEMENT OR WRITTEN AUTHORIZATION FROM PLUM.
+
+2. Ownership. The Software is owned and copyrighted by Plum or its suppliers. Your license confers no title or ownership in the Software and is not a sale of any rights in the Software. All rights not expressly granted to you are reserved by Plum.
+
+3. Restrictions. You may not:
+    * Reverse engineer, decompile, or disassemble the Software, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.
+    * Modify, translate, or create derivative works based on the Software.
+    * Rent, lease, lend, or provide commercial hosting services with the Software.
+    * Transfer the Software or this license to any third party.
+    * Remove or alter any copyright notices or other proprietary markings on or in the Software.
+    * Use the software in any way that violates applicable laws or regulations.
+
+4. Termination. Without prejudice to any other rights, Plum may terminate this Agreement if you fail to comply with any of the terms and conditions of this Agreement. In such event, you must destroy all copies of the Software and all of its component parts.
+
+5. Limited Warranty. Plum warrants that the media on which the Software is distributed (if any) will be free from defects in materials and workmanship for a period of thirty (30) days from the date of delivery. Plum's entire liability and your exclusive remedy for any breach of this limited warranty shall be, at Plum's option, either (a) return of the price paid, or (b) replacement of the defective media.
+
+6. Disclaimer of Warranties. EXCEPT AS PROVIDED ABOVE, THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. PLUM DISCLAIMS ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+7. Limitation of Liability. IN NO EVENT SHALL PLUM BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFIT, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF PLUM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+8. Governing Law. This Agreement shall be governed by and construed in accordance with the laws of the People's Republic of China, without regard to its conflict of law principles.
+
+9. Entire Agreement. This Agreement constitutes the entire agreement between the parties with respect to the subject matter hereof and supersedes all prior or contemporaneous communications and proposals, whether oral or written.
+
+10. Severability. If any provision of this Agreement is held to be invalid or unenforceable, the remaining provisions of this Agreement will remain in full force and effect.
+
+Shanghai Plum Technology Ltd.
+Address: Shanghai, China.
+Email: liplum@liplum.net

package/README.md

@@ -0,0 +1,131 @@
+# @xiao-ying/miniapp-proxy
+
+独立的动态代理服务与 Vite 插件，可在开发时把浏览器请求转发到任意 http/https 或 ws/wss 目标。
+
+## 开发态跨域与 dynamicProxyPlugin（快速使用）
+
+1) 安装（仅 dev）：
+
+```bash
+pnpm add -D @xiao-ying/miniapp-proxy
+```
+
+2) 在 `vite.config.ts` 启用（建议用 `loadEnv` 传入 token 等）：
+
+```ts
+import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+import { dynamicProxyPlugin } from '@xiao-ying/miniapp-proxy'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), 'VITE_')
+  const proxyPrefix = env.VITE_XY_PROXY_PREFIX ?? '/dev-proxy/'
+  const allowTarget = (url: URL) => url.hostname.endsWith('.example.com')
+
+  return {
+    plugins: [
+      react(),
+      dynamicProxyPlugin({
+        prefix: proxyPrefix, // 默认 /dev-proxy
+        token: env.VITE_XIAOYING_TOKEN,
+        tokenTargets: env.VITE_XIAOYING_TOKEN_TARGETS,
+        allowTarget, // 可选：拒绝不允许的目标
+        secure: false // 允许自签名证书
+      })
+    ]
+  }
+})
+```
+
+3) 运行时开启代理（浏览器分支会自动重写请求 URL）：
+
+```ts
+const prefix = import.meta.env.VITE_XY_PROXY_PREFIX ?? '/dev-proxy/'
+window.__XY_CONFIG__ = {
+  runtime: 'browser',
+  devProxy: { enable: true, prefix }
+}
+```
+
+4) 发起请求：
+
+```ts
+const target = 'https://api.example.com'
+fetch(`${prefix}${encodeURIComponent(target)}/v1/foo`, { method: 'GET' })
+```
+
+## WebSocket 代理
+
+同样使用 `/dev-proxy/<encodeURIComponent(target)>` 形式即可：
+
+```ts
+const prefix = import.meta.env.VITE_XY_PROXY_PREFIX ?? '/dev-proxy/'
+const wsTarget = 'wss://ws.example.com/socket'
+const ws = new WebSocket(`${prefix}${encodeURIComponent(wsTarget)}`)
+```
+
+说明：
+
+- WS 仅允许 `ws://` / `wss://` 目标，HTTP 仍仅允许 `http://` / `https://`。
+- 代理会移除 `Origin/Referer/Host` 头，避免跨域检查干扰。
+
+## 独立进程用法
+
+```ts
+import { startProxy } from '@xiao-ying/miniapp-proxy'
+
+startProxy({
+  port: 9000,
+  prefix: '/dev-proxy'
+})
+```
+
+## 作为中间件使用
+
+需要自行接入到任意 Node HTTP 框架时，可直接使用 `createProxyMiddleware`：
+
+```ts
+import express from 'express'
+import { createProxyMiddleware } from '@xiao-ying/miniapp-proxy'
+
+const app = express()
+app.use(createProxyMiddleware({ prefix: '/dev-proxy' }))
+```
+
+## 请求体预览（bodyPreview）
+
+已默认开启请求体预览，会在日志打印请求体前 N 字节（默认 2048），便于快速核对参数：
+
+```ts
+dynamicProxyPlugin({
+  bodyPreview: { maxBytes: 4096 }, // 关闭可传 false
+})
+```
+
+预览仅在有请求体的场景（非 GET/HEAD/OPTIONS）生效，实际转发仍使用完整请求体。
+
+## 开发者凭证注入
+
+如需在调试时自动为指定目标追加 `XIAOYING-TOKEN` 请求头，推荐在 `vite.config.ts` 里用 `loadEnv` 读取并通过插件参数传入（见上例）。同时仍兼容直接使用环境变量：
+
+- `VITE_XIAOYING_TOKEN`（优先）/ `XIAOYING_TOKEN`（回退）：要注入的 token（为空则不注入）。
+- `VITE_XIAOYING_TOKEN_TARGETS`（优先）/ `XIAOYING_TOKEN_TARGETS`（回退）：逗号分隔的 host/port 通配符，默认值为 `xiaoying.life,*.xiaoying.life,*.xiaoying.xyz:44`。示例：  
+  `VITE_XIAOYING_TOKEN_TARGETS="*.internal.example.com:8080,api.example.com"`
+
+仅当目标 URL 匹配这些规则时才会附加 `XIAOYING-TOKEN`，其余目标保持原样转发。
+
+## 约定与可选项
+
+- `prefix`: 代理前缀，带/不带尾斜杠皆可，默认 `/dev-proxy`。  
+- `allowTarget(url: URL)`: 可选白名单钩子，返回 `false` 则拒绝转发。  
+- `secure`: 是否验证上游 HTTPS 证书，默认 `false`（允许自签名）。  
+- `bodyPreview`: `boolean | { enabled?: boolean; maxBytes?: number }`，日志打印请求体前若干字节，默认开启（2048 字节）；仅在有请求体时生效，可传 `false` 关闭。  
+- HTTP 仅转发 http/https；WS 仅转发 ws/wss，其他协议会被拒绝。
+- 默认 `changeOrigin: true`，`secure: false`（允许自签名证书）。
+- 可以通过 `allowTarget` 添加额外白名单校验；通过 `log` 接管日志输出。
+- `proxyOptions` 可透传给 `http-proxy-middleware`，满足高级定制需求。
+
+## 其他形态
+
+- 需要独立进程时，可用同包的 `startProxy` 启动本地服务，再由 Vite `server.proxy` 转发。  
+- 不希望在 Vite 中内置开放代理时，可改用 Nginx/公司网关等方案，但需显式验证白名单以避免滥用。

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createProxyMiddleware, startProxy, type ProxyOptions, type StartProxyOptions, type ProxyRequestHandler, type BodyPreviewOptions } from './proxy.js';
+export { dynamicProxyPlugin, type DynamicProxyPluginOptions } from './vite.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createProxyMiddleware, startProxy } from './proxy.js';
+export { dynamicProxyPlugin } from './vite.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,UAAU,EAKX,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,kBAAkB,EAAkC,MAAM,WAAW,CAAA"}

package/dist/proxy.d.ts

@@ -0,0 +1,55 @@
+import http from 'http';
+import type { Duplex } from 'stream';
+import type { Options as HttpProxyMiddlewareOptions } from 'http-proxy-middleware';
+export type ProxyUpgradeHandler = (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void;
+export type ProxyRequestHandler = ((req: http.IncomingMessage, res: http.ServerResponse, next?: (err?: any) => void) => void) & {
+    upgrade?: ProxyUpgradeHandler;
+};
+/** 代理配置。 */
+export interface ProxyOptions {
+    /** 路由前缀，形如 /dev-proxy */
+    prefix?: string;
+    /** 明确传入要注入的 token（优先级最高） */
+    token?: string;
+    /** 明确传入 token 目标匹配串，逗号分隔（优先级最高） */
+    tokenTargets?: string;
+    /** http-proxy changeOrigin 开关，默认 true */
+    changeOrigin?: boolean;
+    /** 是否允许自签名证书，默认 false */
+    secure?: boolean;
+    /** 可选的白名单钩子，返回 false 则拒绝转发 */
+    allowTarget?: (target: URL) => boolean;
+    /** 自定义日志输出 */
+    log?: (message: string) => void;
+    /** 透传给 http-proxy-middleware 的额外配置 */
+    proxyOptions?: HttpProxyMiddlewareOptions;
+    /** 是否在日志中输出请求体预览，默认开启（max 2048 bytes） */
+    bodyPreview?: boolean | BodyPreviewOptions;
+}
+/** startProxy 的配置项。 */
+export interface StartProxyOptions extends ProxyOptions {
+    /** 监听端口，默认 9000 */
+    port?: number;
+}
+/** 请求体预览配置。 */
+export interface BodyPreviewOptions {
+    /** 开启后打印请求体的前若干字节 */
+    enabled?: boolean;
+    /** 预览的最大字节数，默认 2048 */
+    maxBytes?: number;
+}
+/**
+ * 创建可挂载到任意 HTTP 框架的代理中间件。
+ *
+ * @example
+ * app.use(createProxyMiddleware({ prefix: '/dev-proxy' }))
+ */
+export declare const createProxyMiddleware: (options?: ProxyOptions) => ProxyRequestHandler;
+/**
+ * 启动独立代理服务。
+ *
+ * @example
+ * startProxy({ port: 9000, prefix: '/dev-proxy' })
+ */
+export declare const startProxy: (options?: StartProxyOptions | number) => http.Server;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,OAAO,IAAI,0BAA0B,EAAkB,MAAM,uBAAuB,CAAA;AAIlG,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAEnG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CACjC,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,KACvB,IAAI,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAE9C,YAAY;AACZ,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yBAAyB;IACzB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAA;IACtC,cAAc;IACd,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,sCAAsC;IACtC,YAAY,CAAC,EAAE,0BAA0B,CAAA;IACzC,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAA;CAC3C;AAED,uBAAuB;AACvB,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,mBAAmB;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,eAAe;AACf,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAmPD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAS,YAAiB,KAAG,mBA4PlE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,UAAS,iBAAiB,GAAG,MAAW,KAAG,IAAI,CAAC,MAa1E,CAAA"}

package/dist/proxy.js

@@ -0,0 +1,401 @@
+import http from 'http';
+import { createProxyMiddleware as createHttpProxyMiddleware } from 'http-proxy-middleware';
+const defaultLogger = (message) => console.log(message);
+const isHttpProtocol = (protocol) => protocol === 'http:' || protocol === 'https:';
+const isWsProtocol = (protocol) => protocol === 'ws:' || protocol === 'wss:';
+const toProxyOrigin = (url) => {
+    if (url.protocol === 'ws:') {
+        return `http://${url.host}`;
+    }
+    if (url.protocol === 'wss:') {
+        return `https://${url.host}`;
+    }
+    return url.origin;
+};
+const normalizePrefix = (prefix) => {
+    const withLeading = prefix.startsWith('/') ? prefix : `/${prefix}`;
+    const normalized = withLeading.replace(/\/+$/, '') || '/';
+    const matchPrefix = normalized === '/' ? '/' : `${normalized}/`;
+    return { normalized, matchPrefix };
+};
+const writeTextResponse = (res, status, message) => {
+    if (res.writableEnded)
+        return;
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/plain');
+    res.end(message);
+};
+const stripBrowserHeaders = (req) => {
+    delete req.headers.host;
+    delete req.headers.referer;
+    delete req.headers.origin;
+    delete req.headers['xy-proxy-target'];
+};
+const writeSocketResponse = (socket, status, message) => {
+    if (socket.destroyed)
+        return;
+    const statusText = http.STATUS_CODES[status] ?? 'Error';
+    const response = `HTTP/1.1 ${status} ${statusText}\r\nConnection: close\r\nContent-Type: text/plain\r\n\r\n${message}`;
+    try {
+        socket.write(response);
+    }
+    catch {
+        // ignore write failure
+    }
+    socket.destroy();
+};
+const headerIncludesToken = (value, token) => {
+    if (!value)
+        return false;
+    if (Array.isArray(value)) {
+        return value.some((item) => item.toLowerCase().split(',').some((part) => part.trim() === token));
+    }
+    return value.toLowerCase().split(',').some((part) => part.trim() === token);
+};
+const isWebSocketUpgrade = (req) => {
+    const connectionOk = headerIncludesToken(req.headers.connection, 'upgrade');
+    const upgradeOk = headerIncludesToken(req.headers.upgrade, 'websocket');
+    return connectionOk && upgradeOk;
+};
+const isRedirectStatus = (status) => typeof status === 'number' && status >= 300 && status < 400;
+const defaultTargetPatterns = ['xiaoying.life', '*.xiaoying.life', '*.xiaoying.xyz:44'];
+const toHostRegex = (pattern) => {
+    // Escape regex metacharacters except the wildcard `*`, then expand `*` to `.*`
+    const escaped = pattern.replace(/[-/\\^$+?.()|[\]{}]/g, '\\$&');
+    const regex = '^' + escaped.replace(/\*/g, '.*') + '$';
+    return new RegExp(regex, 'i');
+};
+const parsePattern = (pattern) => {
+    const [hostPart, port] = pattern.split(':', 2);
+    return { hostRegex: toHostRegex(hostPart), port };
+};
+const loadTargetPatterns = (rawFromEnv) => {
+    const raw = (rawFromEnv && rawFromEnv.trim().length > 0 ? rawFromEnv : undefined) ??
+        process.env.VITE_XIAOYING_TOKEN_TARGETS?.trim() ??
+        process.env.XIAOYING_TOKEN_TARGETS?.trim() ??
+        '';
+    const list = raw.length > 0 ? raw.split(',') : defaultTargetPatterns;
+    return list
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map(parsePattern);
+};
+const normalizePort = (url) => {
+    if (url.port)
+        return url.port;
+    if (url.protocol === 'http:')
+        return '80';
+    if (url.protocol === 'https:')
+        return '443';
+    if (url.protocol === 'ws:')
+        return '80';
+    if (url.protocol === 'wss:')
+        return '443';
+    return '';
+};
+const shouldInjectToken = (url, patterns) => {
+    const port = normalizePort(url);
+    return patterns.some((pattern) => {
+        const hostOk = pattern.hostRegex.test(url.hostname);
+        const portOk = !pattern.port || pattern.port === port;
+        return hostOk && portOk;
+    });
+};
+const resolveBodyPreview = (bodyPreview) => {
+    if (typeof bodyPreview === 'boolean') {
+        return { enabled: bodyPreview, maxBytes: 2048 };
+    }
+    const enabled = bodyPreview?.enabled ?? true;
+    const maxBytes = bodyPreview?.maxBytes ?? 2048;
+    return { enabled, maxBytes };
+};
+const shouldCaptureBody = (req) => {
+    const method = (req.method ?? 'GET').toUpperCase();
+    if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS')
+        return false;
+    return true;
+};
+const collectRequestBody = (req, maxPreviewBytes) => {
+    if (!shouldCaptureBody(req))
+        return Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        const bodyChunks = [];
+        const previewChunks = [];
+        let previewCollected = 0;
+        req.on('data', (chunk) => {
+            bodyChunks.push(chunk);
+            if (previewCollected < maxPreviewBytes) {
+                const remaining = maxPreviewBytes - previewCollected;
+                const slice = remaining >= chunk.length ? chunk : chunk.slice(0, remaining);
+                previewChunks.push(slice);
+                previewCollected += slice.length;
+            }
+        });
+        req.on('end', () => {
+            const buffer = Buffer.concat(bodyChunks);
+            const preview = Buffer.concat(previewChunks);
+            const truncated = buffer.length > preview.length;
+            resolve({ buffer, preview, truncated, totalBytes: buffer.length });
+        });
+        req.on('error', (err) => reject(err));
+    });
+};
+const looksText = (buffer) => {
+    // simple heuristic: allow common whitespace and printable ASCII
+    return buffer.every((byte) => (byte >= 0x20 && byte <= 0x7e) || byte === 0x0a || byte === 0x0d || byte === 0x09);
+};
+const formatBodyPreview = (capture, headers) => {
+    const { preview, truncated, totalBytes } = capture;
+    if (preview.length === 0)
+        return '(empty body)';
+    const contentType = headers?.['content-type']?.toString().toLowerCase() ?? '';
+    const forceText = contentType.includes('application/json') || contentType.startsWith('text/');
+    const printable = forceText || looksText(preview);
+    const content = printable ? preview.toString('utf8') : preview.toString('base64');
+    const encodingLabel = printable ? 'utf8' : 'base64';
+    const truncatedLabel = truncated ? ', truncated' : '';
+    return `(${preview.length}/${totalBytes} bytes${truncatedLabel}, ${encodingLabel}): ${content}`;
+};
+const resolveProxyTarget = (req, matchPrefix, guard, allowProtocol) => {
+    const url = req.url ?? '';
+    const matchesPrefix = url === matchPrefix.slice(0, -1) || url.startsWith(matchPrefix);
+    if (!matchesPrefix) {
+        return { status: 'skip' };
+    }
+    const encodedPart = url.startsWith(matchPrefix) ? url.slice(matchPrefix.length) : '';
+    if (!encodedPart) {
+        return { status: 'error', statusCode: 400, message: 'Proxy Error: Missing target' };
+    }
+    let decoded = '';
+    try {
+        decoded = decodeURIComponent(encodedPart);
+    }
+    catch {
+        return { status: 'error', statusCode: 400, message: 'Proxy Error: Invalid encoding' };
+    }
+    let fullUrl;
+    try {
+        fullUrl = new URL(decoded);
+    }
+    catch {
+        return { status: 'error', statusCode: 400, message: 'Proxy Error: Invalid URL' };
+    }
+    if (!allowProtocol(fullUrl.protocol)) {
+        return { status: 'error', statusCode: 400, message: 'Proxy Error: Unsupported protocol' };
+    }
+    if (!guard(fullUrl)) {
+        return { status: 'error', statusCode: 403, message: 'Proxy Error: Target blocked' };
+    }
+    return { status: 'ok', targetUrl: fullUrl, pathAndSearch: fullUrl.pathname + fullUrl.search };
+};
+/**
+ * 创建可挂载到任意 HTTP 框架的代理中间件。
+ *
+ * @example
+ * app.use(createProxyMiddleware({ prefix: '/dev-proxy' }))
+ */
+export const createProxyMiddleware = (options = {}) => {
+    const { prefix = '/dev-proxy', token: tokenFromOptions, tokenTargets: tokenTargetsFromOptions, changeOrigin = true, secure = false, allowTarget, log = defaultLogger, proxyOptions = {}, bodyPreview } = options;
+    const bodyPreviewConfig = resolveBodyPreview(bodyPreview);
+    const { matchPrefix } = normalizePrefix(prefix);
+    const token = tokenFromOptions?.trim() ??
+        process.env.VITE_XIAOYING_TOKEN?.trim() ??
+        process.env.XIAOYING_TOKEN?.trim();
+    const tokenTargetRaw = tokenTargetsFromOptions?.trim() ??
+        process.env.VITE_XIAOYING_TOKEN_TARGETS?.trim() ??
+        process.env.XIAOYING_TOKEN_TARGETS?.trim() ??
+        '';
+    const tokenTargetPatterns = loadTargetPatterns(tokenTargetRaw);
+    const tokenSource = tokenFromOptions
+        ? 'options.token'
+        : process.env.VITE_XIAOYING_TOKEN
+            ? 'VITE_XIAOYING_TOKEN'
+            : process.env.XIAOYING_TOKEN
+                ? 'XIAOYING_TOKEN (fallback)'
+                : 'none';
+    const maskedToken = token
+        ? token.length <= 8
+            ? '***'
+            : `${token.slice(0, 4)}...${token.slice(-4)}`
+        : 'missing';
+    log(`[dev-proxy] env token (${tokenSource}): ${maskedToken}`);
+    const targetsSource = tokenTargetsFromOptions
+        ? 'options.tokenTargets'
+        : process.env.VITE_XIAOYING_TOKEN_TARGETS
+            ? 'VITE_XIAOYING_TOKEN_TARGETS'
+            : process.env.XIAOYING_TOKEN_TARGETS
+                ? 'XIAOYING_TOKEN_TARGETS (fallback)'
+                : 'defaults';
+    log(`[dev-proxy] env token targets (${targetsSource}): ${tokenTargetRaw || '(using defaults)'}`);
+    log(`[dev-proxy] token target patterns loaded: ${tokenTargetPatterns.length}`);
+    log(`[dev-proxy] body preview: ${bodyPreviewConfig.enabled
+        ? `enabled (max ${bodyPreviewConfig.maxBytes} bytes)`
+        : 'disabled'}`);
+    const guard = allowTarget ?? (() => true);
+    const userEvents = (proxyOptions.on ?? {});
+    const resolvedProxyOptions = {
+        ...proxyOptions,
+        ws: typeof proxyOptions.ws === 'boolean' ? proxyOptions.ws : true
+    };
+    const injectTokenHeader = (targetOrigin, setHeader) => {
+        if (token) {
+            if (targetOrigin) {
+                try {
+                    const url = new URL(targetOrigin);
+                    if (shouldInjectToken(url, tokenTargetPatterns)) {
+                        setHeader('XIAOYING-TOKEN', token);
+                        log(`[dev-proxy] injected XIAOYING-TOKEN for ${url.hostname}:${normalizePort(url)}`);
+                    }
+                    else {
+                        log(`[dev-proxy] skip token injection: target ${url.hostname}:${normalizePort(url)} not in patterns`);
+                    }
+                }
+                catch {
+                    // ignore parse errors; no injection
+                }
+            }
+            else {
+                log('[dev-proxy] skip token injection: missing target origin (options.token/VITE_XIAOYING_TOKEN/XIAOYING_TOKEN)');
+            }
+        }
+        else {
+            log('[dev-proxy] skip token injection: token missing (options.token/VITE_XIAOYING_TOKEN/XIAOYING_TOKEN)');
+        }
+    };
+    const proxy = createHttpProxyMiddleware({
+        ...resolvedProxyOptions,
+        target: 'http://dev-proxy.placeholder', // will be overridden by router
+        changeOrigin,
+        secure,
+        router: (req) => req.__xyTargetOrigin ?? 'http://dev-proxy.placeholder',
+        on: {
+            ...userEvents,
+            error: (error, req, res, target) => {
+                log(`[dev-proxy] proxy error: ${error.message}`);
+                if (res instanceof http.ServerResponse) {
+                    writeTextResponse(res, 502, 'Proxy Error');
+                }
+                userEvents.error?.(error, req, res, target);
+            },
+            proxyRes: (proxyRes, req, res) => {
+                userEvents.proxyRes?.(proxyRes, req, res);
+                if (!isRedirectStatus(proxyRes.statusCode))
+                    return;
+                const location = proxyRes.headers?.location;
+                if (!location)
+                    return;
+                const targetOrigin = req.__xyTargetOrigin;
+                const proxyPrefix = req.__xyMatchPrefix;
+                if (!proxyPrefix)
+                    return;
+                try {
+                    const absoluteLocation = new URL(location, targetOrigin).toString();
+                    // 将重定向跳转改写为经过代理的地址，避免浏览器直接访问目标源
+                    proxyRes.headers.location = `${proxyPrefix}${encodeURIComponent(absoluteLocation)}`;
+                }
+                catch {
+                    // 如果地址解析失败，保持原样
+                }
+            },
+            proxyReq: (proxyReq, req, res, options) => {
+                // 透传开发 token
+                injectTokenHeader(req.__xyTargetOrigin, (key, value) => proxyReq.setHeader(key, value));
+                // 写入已捕获的请求体
+                const bodyCapture = req.__xyBodyCapture;
+                if (bodyCapture && bodyCapture.buffer.length > 0) {
+                    proxyReq.setHeader('content-length', String(bodyCapture.buffer.length));
+                    proxyReq.removeHeader?.('transfer-encoding');
+                    proxyReq.write(bodyCapture.buffer);
+                }
+                userEvents.proxyReq?.(proxyReq, req, res, options);
+            },
+            proxyReqWs: (proxyReq, req, socket, options, head) => {
+                injectTokenHeader(req.__xyTargetOrigin, (key, value) => proxyReq.setHeader(key, value));
+                userEvents.proxyReqWs?.(proxyReq, req, socket, options, head);
+            }
+        }
+    });
+    const handler = ((req, res, next) => {
+        const resolution = resolveProxyTarget(req, matchPrefix, guard, isHttpProtocol);
+        if (resolution.status === 'skip') {
+            if (next)
+                return next();
+            return writeTextResponse(res, 404, 'Not Found');
+        }
+        if (resolution.status === 'error') {
+            return writeTextResponse(res, resolution.statusCode, resolution.message);
+        }
+        const { targetUrl, pathAndSearch } = resolution;
+        const method = req.method ?? 'UNKNOWN';
+        log(`[dev-proxy] incoming request -> method: ${method}, url: ${req.url ?? ''}`);
+        log(`[dev-proxy] target: ${method} ${targetUrl.toString()}`);
+        log(`[dev-proxy] headers: ${JSON.stringify(req.headers, null, 2)}`);
+        req.url = pathAndSearch;
+        log(`[dev-proxy] ${targetUrl.origin}${req.url}`);
+        req.__xyTargetOrigin = targetUrl.origin;
+        req.__xyMatchPrefix = matchPrefix;
+        stripBrowserHeaders(req);
+        const forward = () => proxy(req, res, next ?? (() => undefined));
+        if (!bodyPreviewConfig.enabled || !shouldCaptureBody(req)) {
+            return forward();
+        }
+        collectRequestBody(req, bodyPreviewConfig.maxBytes)
+            .then((capture) => {
+            if (capture) {
+                ;
+                req.__xyBodyCapture = capture;
+                log(`[dev-proxy] body preview ${formatBodyPreview(capture, req.headers)}`);
+            }
+            forward();
+        })
+            .catch((error) => {
+            log(`[dev-proxy] body preview failed: ${error instanceof Error ? error.message : error}`);
+            forward();
+        });
+    });
+    handler.upgrade = (req, socket, head) => {
+        if (!isWebSocketUpgrade(req))
+            return;
+        const resolution = resolveProxyTarget(req, matchPrefix, guard, isWsProtocol);
+        if (resolution.status === 'skip')
+            return;
+        if (resolution.status === 'error') {
+            return writeSocketResponse(socket, resolution.statusCode, resolution.message);
+        }
+        const { targetUrl, pathAndSearch } = resolution;
+        log(`[dev-proxy] incoming upgrade -> url: ${req.url ?? ''}`);
+        log(`[dev-proxy] target: WS ${targetUrl.toString()}`);
+        log(`[dev-proxy] headers: ${JSON.stringify(req.headers, null, 2)}`);
+        req.url = pathAndSearch;
+        log(`[dev-proxy] ${targetUrl.origin}${req.url}`);
+        req.__xyTargetOrigin = toProxyOrigin(targetUrl);
+        req.__xyMatchPrefix = matchPrefix;
+        stripBrowserHeaders(req);
+        const upgrader = proxy.upgrade;
+        if (typeof upgrader !== 'function') {
+            return writeSocketResponse(socket, 502, 'Proxy Error');
+        }
+        return upgrader(req, socket, head);
+    };
+    return handler;
+};
+/**
+ * 启动独立代理服务。
+ *
+ * @example
+ * startProxy({ port: 9000, prefix: '/dev-proxy' })
+ */
+export const startProxy = (options = {}) => {
+    const normalizedOptions = typeof options === 'number' ? { port: options } : options ?? {};
+    const { port = 9000, log = defaultLogger } = normalizedOptions;
+    const handler = createProxyMiddleware(normalizedOptions);
+    const server = http.createServer((req, res) => handler(req, res));
+    if (handler.upgrade) {
+        server.on('upgrade', (req, socket, head) => handler.upgrade?.(req, socket, head));
+    }
+    server.listen(port, () => {
+        log(`> Dev proxy running at http://localhost:${port}`);
+    });
+    return server;
+};
+//# sourceMappingURL=proxy.js.map