> For the complete documentation index, see [llms.txt](https://litedb.gitbook.io/litedb-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://litedb.gitbook.io/litedb-docs/architecture_and_design/network_protocol/overview.md).

# 总览

LiteDB 当前实现的是一套运行在 TCP 之上的二进制请求—响应协议。协议版本为 `1`：每个通信单元都是一个完整帧，由固定 32 字节帧头和可变长 Payload 组成；客户端建立 TCP 连接后必须先完成 `Hello` 握手，才能发送 SQL、Ping、Cancel 或 Close 请求。

本节描述的是当前代码已经实现的协议，不包含未来兼容方案。帧格式与消息类型均按 v1 直接解释，不兼容旧版 16 字节消息头。

## 分层与职责

```mermaid
flowchart LR
    Client["Client：请求状态与结果转换"] --> Protocol["Protocol：帧格式与消息 Schema"]
    Protocol --> Net["Net：TCP 分段读写"]
    Net --> Server["Server：连接状态与 Session"]
    Server --> Engine["DatabaseEngine / Session"]
```

当前实现将职责分为四层：

* `core/io` 提供大端整数、浮点数和长度前缀字符串的字节读写，以及读取预算限制；
* `protocol` 定义固定帧头、消息类型、Payload DTO、编解码和字段校验；
* `net` 只负责在 TCP 字节流上读满帧头、再读满 Payload，或把编码后的整帧写完；
* `client` / `server` 负责握手、请求—响应关联、连接关闭、错误边界和执行结果转换。

因此，TCP 层不解释 SQL 结果，协议层也不拥有套接字或数据库会话。

## 一次连接的状态

```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: TCP connect
    C->>S: HelloRequest(min=1, max=1)
    S-->>C: HelloResponse(selected=1)
    loop 串行请求—响应
        C->>S: ExecuteSqlRequest / PingRequest
        S-->>C: ExecuteSqlResponse / PongResponse / ErrorResponse
    end
    C->>S: CloseRequest
    Note over C,S: 服务端关闭连接，不返回 CloseResponse
```

服务端为每个 TCP 连接创建独立的 `Session`，并在一个循环中逐帧处理。第一帧必须是 `HelloRequest`；版本范围必须包含 v1。握手完成后，同一连接可以重复执行 SQL 或 Ping。当前官方客户端的 `roundtrip` 会先写一个请求，再读取一个响应，并校验响应的 `Request ID`，所以单连接上的使用方式是串行 RPC，不进行流水线或并发多路复用。

`CloseRequest` 是单向关闭通知。客户端写出该帧后直接关闭套接字；服务端收到后结束连接，不发送关闭确认。

## 请求、响应与错误

当前协议包含以下功能：

* 连接管理：`HelloRequest`、`HelloResponse`、`CloseRequest`；
* SQL 执行：`ExecuteSqlRequest`、`ExecuteSqlResponse`；
* 连通性检测：`PingRequest`、`PongResponse`；
* 错误返回：`ErrorResponse`；
* 取消占位：`CancelRequest` 已分配消息类型，但服务端固定返回“不支持”。

正常响应复用请求帧的 `Request ID`。SQL 执行错误会编码成合法的 `ErrorResponse`，连接通常仍可继续使用；帧头非法、TCP 读写失败、握手失败或无法可靠继续解析连接时，服务端会结束连接。错误帧只携带 16 位编码和消息文本，不传输本地错误上下文或 cause 链。

## 数据与资源边界

协议的硬上限是单帧 16 MiB，且该上限包含 32 字节帧头。SQL、普通字符串、列数、行数、每行值数和向量元素数还各自受解码限制约束。SQL 结果会完整编码进一个响应 Payload；当前没有结果分页、分片或边解码边消费的应用层流式协议。

具体内容见：

* [传输协议](/litedb-docs/architecture_and_design/network_protocol/transport_protocol.md)：TCP 定帧、32 字节帧头、分阶段读取和连接终止条件；
* [消息协议](/litedb-docs/architecture_and_design/network_protocol/message_protocol.md)：消息编号、Payload Schema、值编码、错误编码和默认限制。

## 当前未实现的能力

* TLS / mTLS、认证和权限协商；
* DNS 主机名解析；当前客户端和服务端地址由 `asio::ip::make_address` 解析；
* 压缩、校验和、分片和流式结果集；
* 单连接请求流水线、多路复用和乱序响应；
* 请求超时、空闲超时、自动重试和服务端心跳定时器；
* SQL 执行取消；`CancelRequest` 目前仅返回 `UnsupportedMessage`。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://litedb.gitbook.io/litedb-docs/architecture_and_design/network_protocol/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.