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