import type { VextAdapter } from "../../types/adapter.js";
import type { VextApp } from "../../types/app.js";
/**
 * Koa Adapter 选项
 *
 * 用户通过 koaAdapter(options) 工厂函数传入，
 * 控制 Koa 实例的初始化行为。
 *
 * 所有选项均可选，默认值已为 vext 场景优化。
 */
export interface KoaAdapterOptions {
    /**
     * 请求体大小限制（字符串格式，如 '1mb'）
     * 仅在预收集 rawBody 时用作参考上限。
     * 实际的 body 大小限制由 vext body-parser 中间件控制。
     *
     * @default '1mb'
     */
    bodyLimit?: string;
}
/**
 * createKoaAdapter — 创建基于 Koa 的 VextAdapter 实例
 *
 * 将 Koa 作为底层 HTTP 框架，实现 VextAdapter 接口。
 * 这是 VextAdapter 的第四个实现（Hono → Fastify → Express → Koa），
 * 用于验证 Adapter 抽象层的完备性和通用性。
 *
 * 架构说明：
 *   - Koa 不内置路由功能，adapter 使用 @koa/router 承载宿主生态路由
 *   - 不使用 Koa 自带的中间件机制（ctx.body / ctx.status 赋值模式）
 *   - 中间件链执行由 vext 自己的 executeChain 实现（洋葱模型）
 *   - 请求 / 响应对象在 Koa middleware 内转换为 VextRequest / VextResponse
 *   - 全局中间件通过 registerMiddleware() 收集，在每个路由执行时拼接到链头
 *   - 所有响应通过 ctx.res（Node.js 原生 ServerResponse）直接操作，
 *     绕过 Koa 的 ctx.body / ctx.status 赋值模式
 *
 * 与其他 Adapter 的核心差异：
 *   - Koa 不内置路由（Express 有 app.get/post/...，Fastify 有 fastify.get/post/...），
 *     通过 @koa/router 提供 Koa 生态路由能力
 *   - Koa 的响应模型是赋值式（ctx.body = ..., ctx.status = ...），
 *     而非 Express/Fastify 的命令式（res.send/reply.send）。
 *     为保持跨 Adapter 一致性，vext 使用 ctx.res（Node.js 原生 ServerResponse）
 *     的 .statusCode / .setHeader / .end() API 直接操作
 *   - Body 解析：不注册任何 Koa body-parser，通过手动收集 ctx.req stream 为 Buffer，
 *     传给 createVextRequest 的 rawBody 参数，由 vext body-parser 中间件统一处理
 *   - buildHandler：Koa app.callback() 返回 (req, res) => void 函数，
 *     可直接作为 Node.js requestListener
 *
 * HTTP 服务器：
 *   - Koa 不内置 HTTP server 创建（与 Fastify 不同），
 *     adapter 使用 Node.js 原生 http.createServer(app.callback())
 *   - listen() 创建 http.createServer 并调用 server.listen()
 *   - close() 调用 server.close()
 *   - buildHandler() 返回 Koa app.callback() 作为 Node.js handler，
 *     用于 dev 模式热重载的 HotSwappableHandler 原子替换
 *
 * @param options Koa 适配器配置选项
 * @param vextApp VextApp 实例（用于传递给 createVextRequest 的 app 引用）
 * @returns VextAdapter 实例
 *
 * @see adapters/hono/adapter.ts（Hono Adapter 对应实现）
 * @see adapters/fastify/adapter.ts（Fastify Adapter 对应实现）
 * @see adapters/express/adapter.ts（Express Adapter 对应实现）
 */
export declare function createKoaAdapter(options: KoaAdapterOptions, vextApp: VextApp): VextAdapter;