@lark-apaas/nestjs-http-forwarder 0.1.1-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,192 @@
+import { DynamicModule } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+/**
+ * service.forward() 入参。
+ */
+interface ForwardRequestDto {
+    /** HTTP method，由 fetch 自身校验合法性 */
+    method: string;
+    /** Target URL on the customer internal network. Must be http:// or https:// */
+    targetUrl: string;
+    /** Headers to forward (host will be overridden to targetUrl.host) */
+    headers?: Record<string, string>;
+    /** Body to forward */
+    body?: string | null;
+}
+/**
+ * service.forward() 出参（透传上游 status / headers / body）。
+ */
+interface ForwardResponseDto {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * HttpForwarderModule.forRoot() 选项
+ */
+interface HttpForwarderModuleOptions {
+    /** 单次请求超时（ms），默认 30000 */
+    requestTimeoutMs?: number;
+    /** 上游响应体最大字节数，默认 10MB；超阈值返回 502 RESPONSE_TOO_LARGE */
+    maxResponseBytes?: number;
+}
+
+/**
+ * HttpForwarderModule
+ *
+ * 自动注册：
+ *   - `HttpForwarderController` —— 通用内网转发 endpoint `ALL /anycross/forward?targetUrl=...`
+ *     支持所有 HTTP method，headers / body 自动透传，上游响应直接投射到客户端。
+ *   - `HttpForwarderService`（可注入到自定义 controller，编排特殊场景）
+ *
+ * **不内置鉴权**——消费方在 AppModule 层面给路由加 guard（如全局 NeedLoginGuard）。
+ *
+ * 使用示例：
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     HttpForwarderModule.forRoot({
+ *       requestTimeoutMs: 30_000,
+ *       maxResponseBytes: 10 * 1024 * 1024,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * 前端调用：
+ * ```ts
+ * axiosForBackend.get('/anycross/forward', { params: { targetUrl: 'http://api.corp.com/v1/users' } });
+ * axiosForBackend.post('/anycross/forward', body, { params: { targetUrl: 'http://api.corp.com/v1/orders' } });
+ * ```
+ *
+ * **注**：实际代理 / 鉴权 / 隧道由部署环境处理（如沙箱内的 mihomo 透明代理 +
+ * iptables 拦截）。SDK 不感知 anycross / proxy_group_id / jwtToken。
+ */
+declare class HttpForwarderModule {
+    static forRoot(options?: HttpForwarderModuleOptions): DynamicModule;
+}
+
+/**
+ * forRoot 入参经过默认值合并后的形态。SDK 内部统一使用此类型。
+ */
+interface HttpForwarderOptionsResolved extends Required<HttpForwarderModuleOptions> {
+}
+/**
+ * 校验并补默认值。配置错误（非法字段值）在模块装配时抛出，启动期 fail-fast。
+ */
+declare function resolveOptions(options: HttpForwarderModuleOptions | undefined): HttpForwarderOptionsResolved;
+
+/**
+ * 反向 HTTP 转发器：把入站请求"原样"转发到目标 URL。
+ *
+ * 用途：把请求的出口从浏览器变成 node。客户内网访问的代理 / 鉴权 / 隧道由
+ * 部署环境（如沙箱内的 mihomo 透明代理 + iptables 拦截）负责，SDK 不感知。
+ *
+ * 只做 5 件核心事：
+ *   1. 协议白名单（仅 http/https，防 SSRF）
+ *   2. host 重写 + content-length 剥离（语义正确性，单点处理）
+ *   3. 单次请求超时（AbortController，默认 30s）
+ *   4. 响应体大小上限（流式累计字节，防 OOM，默认 10MB）
+ *   5. 错误码映射（给调用方稳定的 error contract）
+ */
+declare class HttpForwarderService {
+    private readonly options;
+    constructor(options: HttpForwarderOptionsResolved);
+    forward(payload: ForwardRequestDto): Promise<ForwardResponseDto>;
+    /**
+     * URL 解析 + 协议白名单。其他入参校验交给 fetch 自身。
+     */
+    private assertValidTargetUrl;
+    /**
+     * host / content-length 的**单点处理点**：
+     *   - host：强制覆盖为 targetUrl.host（防上游误识别，无论调用方传什么）
+     *   - content-length：剥离（fetch 会按真实 body 自算）
+     *
+     * 其他 hop-by-hop / accept-encoding 等由 controller 已剥离，service 信任入参。
+     */
+    private buildOutgoingHeaders;
+    /**
+     * 流式读取响应体并累计字节数，超 `maxResponseBytes` 即 abort + 抛 502。
+     */
+    private readBoundedBody;
+    /**
+     * 把 fetch 抛错 / 超时统一映射为 HttpException。
+     *
+     *   1. HttpException → 直接透传（含 INVALID_TARGET_PROTOCOL / RESPONSE_TOO_LARGE）
+     *   2. controller.signal.aborted → UPSTREAM_TIMEOUT 504
+     *   3. TypeError → INVALID_REQUEST 400（fetch 对配置错统一抛 TypeError）
+     *   4. 兜底 → UPSTREAM_UNREACHABLE 502
+     */
+    private mapNetworkError;
+}
+
+/**
+ * 通用内网转发 controller。
+ *
+ * 路径：`/anycross/forward`（硬编码，所有消费方一致）。
+ *
+ * 接受所有 HTTP method（GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS）。
+ *   - method：直接取自入站请求自身
+ *   - targetUrl：取自 query `?targetUrl=...`
+ *   - headers：透传入站请求 headers（剔除 hop-by-hop / accept-encoding；
+ *             host / content-length 由 service 单点处理）
+ *   - body：透传入站请求 body（已经过 express body-parser，按情况序列化为字符串）
+ *
+ * 响应：上游 status / headers / body **直接投射到 HTTP response**，让前端 axios
+ * 看到的就是真实上游响应（而非 wrap 的 JSON）。
+ *
+ * **SDK 不内置鉴权**——消费方在 AppModule 层面给本路由加 guard（如全局 NeedLoginGuard）。
+ */
+declare class HttpForwarderController {
+    private readonly svc;
+    constructor(svc: HttpForwarderService);
+    forward(req: Request, res: Response): Promise<void>;
+    /**
+     * 从入站请求 headers 选出可透传给上游的字段。剔除 hop-by-hop / accept-encoding。
+     * 保留 cookie / authorization / x-* 等业务头。
+     * host / content-length 不在此处剥离——由 service.buildOutgoingHeaders 单点处理。
+     */
+    static pickIncomingHeaders(incoming: Request['headers']): Record<string, string>;
+    /**
+     * 把 express 已解析的 body 序列化回字符串供 service 透传。
+     */
+    static serializeIncomingBody(req: Request): string | null;
+}
+
+/** HttpForwarder module options injection token */
+declare const HTTP_FORWARDER_MODULE_OPTIONS: unique symbol;
+/** Controller route prefix (硬编码，不可配置以保持调用方式统一) */
+declare const CONTROLLER_ROUTE = "anycross/forward";
+/** Default request timeout in milliseconds */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Default maximum response body size in bytes (10 MB) */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/** Allowed target URL protocols */
+declare const ALLOWED_PROTOCOLS: readonly ["http:", "https:"];
+/**
+ * 入站 headers 中不能透传给上游的 hop-by-hop / transport / encoding 字段。
+ * RFC 7230 §6.1 hop-by-hop + accept-encoding（由 fetch / undici 接管）。
+ *
+ * 注：host / content-length 由 service.buildOutgoingHeaders 在写入 fetch 入参时
+ * 单点处理（host 重写为 targetUrl.host；content-length 让 fetch 自算），此处不重复。
+ */
+declare const HEADERS_NOT_FORWARDED_TO_UPSTREAM: Set<string>;
+/**
+ * 上游响应 headers 中不应回写到下游 response 的字段。
+ * - content-encoding：fetch 已解压，原 encoding 不再适用
+ * - content-length：node http 会根据真实 body 重算
+ * - transfer-encoding / connection / keep-alive：hop-by-hop
+ */
+declare const HEADERS_NOT_RETURNED_TO_CLIENT: Set<string>;
+/** Error codes returned to callers */
+declare const ERROR_CODES: {
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly INVALID_TARGET_PROTOCOL: "INVALID_TARGET_PROTOCOL";
+    readonly UPSTREAM_UNREACHABLE: "UPSTREAM_UNREACHABLE";
+    readonly UPSTREAM_TIMEOUT: "UPSTREAM_TIMEOUT";
+    readonly RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+};
+
+export { ALLOWED_PROTOCOLS, CONTROLLER_ROUTE, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_REQUEST_TIMEOUT_MS, ERROR_CODES, type ForwardRequestDto, type ForwardResponseDto, HEADERS_NOT_FORWARDED_TO_UPSTREAM, HEADERS_NOT_RETURNED_TO_CLIENT, HTTP_FORWARDER_MODULE_OPTIONS, HttpForwarderController, HttpForwarderModule, type HttpForwarderModuleOptions, type HttpForwarderOptionsResolved, HttpForwarderService, resolveOptions };

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import { DynamicModule } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+/**
+ * service.forward() 入参。
+ */
+interface ForwardRequestDto {
+    /** HTTP method，由 fetch 自身校验合法性 */
+    method: string;
+    /** Target URL on the customer internal network. Must be http:// or https:// */
+    targetUrl: string;
+    /** Headers to forward (host will be overridden to targetUrl.host) */
+    headers?: Record<string, string>;
+    /** Body to forward */
+    body?: string | null;
+}
+/**
+ * service.forward() 出参（透传上游 status / headers / body）。
+ */
+interface ForwardResponseDto {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * HttpForwarderModule.forRoot() 选项
+ */
+interface HttpForwarderModuleOptions {
+    /** 单次请求超时（ms），默认 30000 */
+    requestTimeoutMs?: number;
+    /** 上游响应体最大字节数，默认 10MB；超阈值返回 502 RESPONSE_TOO_LARGE */
+    maxResponseBytes?: number;
+}
+
+/**
+ * HttpForwarderModule
+ *
+ * 自动注册：
+ *   - `HttpForwarderController` —— 通用内网转发 endpoint `ALL /anycross/forward?targetUrl=...`
+ *     支持所有 HTTP method，headers / body 自动透传，上游响应直接投射到客户端。
+ *   - `HttpForwarderService`（可注入到自定义 controller，编排特殊场景）
+ *
+ * **不内置鉴权**——消费方在 AppModule 层面给路由加 guard（如全局 NeedLoginGuard）。
+ *
+ * 使用示例：
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     HttpForwarderModule.forRoot({
+ *       requestTimeoutMs: 30_000,
+ *       maxResponseBytes: 10 * 1024 * 1024,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * 前端调用：
+ * ```ts
+ * axiosForBackend.get('/anycross/forward', { params: { targetUrl: 'http://api.corp.com/v1/users' } });
+ * axiosForBackend.post('/anycross/forward', body, { params: { targetUrl: 'http://api.corp.com/v1/orders' } });
+ * ```
+ *
+ * **注**：实际代理 / 鉴权 / 隧道由部署环境处理（如沙箱内的 mihomo 透明代理 +
+ * iptables 拦截）。SDK 不感知 anycross / proxy_group_id / jwtToken。
+ */
+declare class HttpForwarderModule {
+    static forRoot(options?: HttpForwarderModuleOptions): DynamicModule;
+}
+
+/**
+ * forRoot 入参经过默认值合并后的形态。SDK 内部统一使用此类型。
+ */
+interface HttpForwarderOptionsResolved extends Required<HttpForwarderModuleOptions> {
+}
+/**
+ * 校验并补默认值。配置错误（非法字段值）在模块装配时抛出，启动期 fail-fast。
+ */
+declare function resolveOptions(options: HttpForwarderModuleOptions | undefined): HttpForwarderOptionsResolved;
+
+/**
+ * 反向 HTTP 转发器：把入站请求"原样"转发到目标 URL。
+ *
+ * 用途：把请求的出口从浏览器变成 node。客户内网访问的代理 / 鉴权 / 隧道由
+ * 部署环境（如沙箱内的 mihomo 透明代理 + iptables 拦截）负责，SDK 不感知。
+ *
+ * 只做 5 件核心事：
+ *   1. 协议白名单（仅 http/https，防 SSRF）
+ *   2. host 重写 + content-length 剥离（语义正确性，单点处理）
+ *   3. 单次请求超时（AbortController，默认 30s）
+ *   4. 响应体大小上限（流式累计字节，防 OOM，默认 10MB）
+ *   5. 错误码映射（给调用方稳定的 error contract）
+ */
+declare class HttpForwarderService {
+    private readonly options;
+    constructor(options: HttpForwarderOptionsResolved);
+    forward(payload: ForwardRequestDto): Promise<ForwardResponseDto>;
+    /**
+     * URL 解析 + 协议白名单。其他入参校验交给 fetch 自身。
+     */
+    private assertValidTargetUrl;
+    /**
+     * host / content-length 的**单点处理点**：
+     *   - host：强制覆盖为 targetUrl.host（防上游误识别，无论调用方传什么）
+     *   - content-length：剥离（fetch 会按真实 body 自算）
+     *
+     * 其他 hop-by-hop / accept-encoding 等由 controller 已剥离，service 信任入参。
+     */
+    private buildOutgoingHeaders;
+    /**
+     * 流式读取响应体并累计字节数，超 `maxResponseBytes` 即 abort + 抛 502。
+     */
+    private readBoundedBody;
+    /**
+     * 把 fetch 抛错 / 超时统一映射为 HttpException。
+     *
+     *   1. HttpException → 直接透传（含 INVALID_TARGET_PROTOCOL / RESPONSE_TOO_LARGE）
+     *   2. controller.signal.aborted → UPSTREAM_TIMEOUT 504
+     *   3. TypeError → INVALID_REQUEST 400（fetch 对配置错统一抛 TypeError）
+     *   4. 兜底 → UPSTREAM_UNREACHABLE 502
+     */
+    private mapNetworkError;
+}
+
+/**
+ * 通用内网转发 controller。
+ *
+ * 路径：`/anycross/forward`（硬编码，所有消费方一致）。
+ *
+ * 接受所有 HTTP method（GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS）。
+ *   - method：直接取自入站请求自身
+ *   - targetUrl：取自 query `?targetUrl=...`
+ *   - headers：透传入站请求 headers（剔除 hop-by-hop / accept-encoding；
+ *             host / content-length 由 service 单点处理）
+ *   - body：透传入站请求 body（已经过 express body-parser，按情况序列化为字符串）
+ *
+ * 响应：上游 status / headers / body **直接投射到 HTTP response**，让前端 axios
+ * 看到的就是真实上游响应（而非 wrap 的 JSON）。
+ *
+ * **SDK 不内置鉴权**——消费方在 AppModule 层面给本路由加 guard（如全局 NeedLoginGuard）。
+ */
+declare class HttpForwarderController {
+    private readonly svc;
+    constructor(svc: HttpForwarderService);
+    forward(req: Request, res: Response): Promise<void>;
+    /**
+     * 从入站请求 headers 选出可透传给上游的字段。剔除 hop-by-hop / accept-encoding。
+     * 保留 cookie / authorization / x-* 等业务头。
+     * host / content-length 不在此处剥离——由 service.buildOutgoingHeaders 单点处理。
+     */
+    static pickIncomingHeaders(incoming: Request['headers']): Record<string, string>;
+    /**
+     * 把 express 已解析的 body 序列化回字符串供 service 透传。
+     */
+    static serializeIncomingBody(req: Request): string | null;
+}
+
+/** HttpForwarder module options injection token */
+declare const HTTP_FORWARDER_MODULE_OPTIONS: unique symbol;
+/** Controller route prefix (硬编码，不可配置以保持调用方式统一) */
+declare const CONTROLLER_ROUTE = "anycross/forward";
+/** Default request timeout in milliseconds */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Default maximum response body size in bytes (10 MB) */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/** Allowed target URL protocols */
+declare const ALLOWED_PROTOCOLS: readonly ["http:", "https:"];
+/**
+ * 入站 headers 中不能透传给上游的 hop-by-hop / transport / encoding 字段。
+ * RFC 7230 §6.1 hop-by-hop + accept-encoding（由 fetch / undici 接管）。
+ *
+ * 注：host / content-length 由 service.buildOutgoingHeaders 在写入 fetch 入参时
+ * 单点处理（host 重写为 targetUrl.host；content-length 让 fetch 自算），此处不重复。
+ */
+declare const HEADERS_NOT_FORWARDED_TO_UPSTREAM: Set<string>;
+/**
+ * 上游响应 headers 中不应回写到下游 response 的字段。
+ * - content-encoding：fetch 已解压，原 encoding 不再适用
+ * - content-length：node http 会根据真实 body 重算
+ * - transfer-encoding / connection / keep-alive：hop-by-hop
+ */
+declare const HEADERS_NOT_RETURNED_TO_CLIENT: Set<string>;
+/** Error codes returned to callers */
+declare const ERROR_CODES: {
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly INVALID_TARGET_PROTOCOL: "INVALID_TARGET_PROTOCOL";
+    readonly UPSTREAM_UNREACHABLE: "UPSTREAM_UNREACHABLE";
+    readonly UPSTREAM_TIMEOUT: "UPSTREAM_TIMEOUT";
+    readonly RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
+};
+
+export { ALLOWED_PROTOCOLS, CONTROLLER_ROUTE, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_REQUEST_TIMEOUT_MS, ERROR_CODES, type ForwardRequestDto, type ForwardResponseDto, HEADERS_NOT_FORWARDED_TO_UPSTREAM, HEADERS_NOT_RETURNED_TO_CLIENT, HTTP_FORWARDER_MODULE_OPTIONS, HttpForwarderController, HttpForwarderModule, type HttpForwarderModuleOptions, type HttpForwarderOptionsResolved, HttpForwarderService, resolveOptions };