import type { Request as ExpressRequest } from "express";
import type { VextRequest } from "../../types/request.js";
import type { VextApp } from "../../types/app.js";
/**
 * Express Request → VextRequest 转换
 *
 * 将 Express 的 Request 对象转换为 vext 框架的统一请求接口。
 * 所有底层框架特有的 API 在此处适配，后续代码只与 VextRequest 交互。
 *
 * 转换要点：
 *   - query: Express 已解析好 query 对象，直接使用（转为 Record<string, string>）
 *   - body: 由 body-parser 中间件后续填充（初始 undefined）
 *   - params: Express 已解析好 params 对象，直接使用
 *   - headers: Express 的 req.headers 是 Node.js 原生 headers 对象（key 全小写）
 *   - requestId: 由 requestId 中间件后续填充（初始空字符串）
 *   - ip: 根据 trustProxy 配置决定从 X-Forwarded-For 或 socket 读取
 *   - protocol: 根据 trustProxy 配置决定从 X-Forwarded-Proto 或默认值读取
 *   - onClose: 注册请求关闭钩子，连接断开时触发（通过 req.on('close')）
 *   - valid: 获取 validate 中间件校验后的数据
 *   - _getRawBody: 从请求流中读取原始请求体文本，供 vext body-parser 中间件使用
 *
 * 与 Hono / Fastify Adapter 的差异：
 *   - Hono 通过 c.req.text() 读取 Web Request body（ReadableStream）
 *   - Fastify 通过 removeAllContentTypeParsers + addContentTypeParser('*', parseAs: 'buffer')
 *     将原始 body 作为 Buffer 传入 request.body
 *   - Express: 禁用 Express 内置 body-parser，通过监听 req 的 'data'/'end' 事件
 *     手动收集原始 body 为 Buffer（在 adapter 层完成），存入 (req as any)._vextRawBody
 *   - 三者最终都通过 req._getRawBody() 返回 string 供 vext body-parser 使用
 *
 * @param expressReq Express Request 对象
 * @param app        VextApp 实例
 * @param rawBody    预收集的原始请求体 Buffer（由 adapter 层在路由 handler 前收集）
 * @returns VextRequest 实例（含 _getRawBody 内部方法供 body-parser 使用）
 *
 * @see adapters/hono/request.ts（Hono Adapter 对应实现）
 * @see adapters/fastify/request.ts（Fastify Adapter 对应实现）
 */
export declare function createVextRequest(expressReq: ExpressRequest, app: VextApp, rawBody?: Buffer): VextRequest;