# API Map
本章按模块列出重要 public API。`pub(crate)` runtime 细节不列为用户 API。
## crate root
- `pipeline()`：创建 TCP stream typed pipeline builder。
- `datagram_pipeline()`：创建 UDP datagram typed pipeline builder。
- `TcpServer` / `TcpClient`：TCP server/client builder。
- `UdpServer` / `UdpClient`：UDP server/client builder。
- `Channel` / `DatagramChannel`：cloneable external write/flush/close handle。
- `Context` / `DatagramContext`：final handler 中的写入和连接/socket 操作 context。
- `InboundContext` / `BusinessContext` / `OutboundContext`：transform stage 的只读 identity context。启用 `tls` feature 时，TCP stream context 可通过 `tls()` 暴露协商后的 TLS metadata。
- `Life` / `NoLife` / `CloseReason`：lifecycle hook API。
- `Error` / `Result`：框架错误类型和结果别名。
- `Flow`：stage 继续或停止当前消息的结果。
- `handler`：`macros` feature 下 re-export 的 attribute macro。
- `TlsContextBuilder` / `ServerTlsContext` / `ClientTlsContext` / `TlsInfo`：`tls` feature 下的 TLS context 和 metadata API。
## `traits`
- `Flow<T>`：`Next(T)` 继续 pipeline，`Stop` 消费消息。
- `Inbound<I>`：入站转换 stage，输出 `Flow<Out>`。
- `Business<I>`：业务转换 stage，位于 inbound 和 final handler 之间。
- `Handler<I>`：TCP final inbound handler，定义 `type Write`。
- `DatagramHandler<I>`：UDP final inbound handler，定义 `type Write`。
- `Outbound<I>`：出站转换 stage，把 handler write 类型转成 codec 可编码类型。
## `codec`
- `Decoder`：TCP byte stream decoder，返回 `Option<Item>`。
- `Encoder<I>`：TCP byte stream encoder。
- `DatagramDecoder`：UDP datagram decoder。
- `DatagramEncoder<I>`：UDP datagram encoder。
- `LineCodec`：UTF-8 newline-delimited stream codec。
- `ByteArrayDecoder`：把当前 stream buffer drain 成 `Bytes`，并可 encode `Bytes`。
- `ByteArrayEncoder`：pass-through `Bytes` encoder。
- `FixedLengthFrameDecoder`：固定长度 binary frame codec。
- `DelimiterBasedFrameDecoder`：delimiter-terminated binary frame codec。
- `LengthFieldBasedFrameDecoder`：length-field frame decoder，也可 encode zero-offset/zero-adjustment `Bytes`。
- `LengthFieldPrepender`：只负责 prepend length field 的 `Bytes` encoder。
- `ByteOrder`：length-field codec 使用的 endian 设置。
- `Utf8DatagramCodec`：UTF-8 datagram codec。
- `BytesDatagramCodec`：raw bytes datagram codec。
- `JsonDecode<T>`：`json` feature 下的 inbound JSON stage。
- `JsonEncode<T>`：`json` feature 下的 outbound JSON stage。
- `HttpCodec`：最小 HTTP/1.1 request/response server codec。
- `HttpRequest`：HTTP request view，提供 method/target/version/header/body/trailers 查询。
- `HttpResponse`：HTTP response builder，支持 status/reason/header/body。
- `MqttCodec`：MQTT 5 packet stream codec。
- `MqttPacket`：MQTT control packet enum。
- `QoS`：MQTT QoS enum。
- `ConnectPacket` / `ConnAckPacket` / `PublishPacket` / `AckPacket`：常用 MQTT packet struct。
- `SubscribePacket` / `SubAckPacket` / `UnsubscribePacket` / `UnsubAckPacket`：MQTT subscribe/unsubscribe packet struct。
- `DisconnectPacket` / `AuthPacket` / `Will` / `MqttProperty`：MQTT 辅助 packet/property 类型。
- `WebSocketCodec`：`websocket` feature 下的 server-side WebSocket codec。
- `HttpWsCodec`：`websocket` feature 下的 HTTP + WebSocket shared-port codec。
- `WebSocketInbound` / `WebSocketOutbound` / `WebSocketMessage`：WebSocket message enums。
- `HttpWsInbound` / `HttpWsOutbound`：shared HTTP/WebSocket codec 的 message enums。
- `WebSocketHandshake` / `WebSocketHandshakeResponse` / `WebSocketClose`：WebSocket handshake 和 close 类型。
- `HttpService` / `WebSocketService`：`HttpWsRouter` 使用的 static service traits。
- `HttpWsRouter<H, W>`：把 HTTP service 和 WebSocket service 组合成一个 `Handler<HttpWsInbound>`。
## `context`
- `ConnInfo`：TCP connection id、peer addr、local addr；启用 `tls` feature 时也包含协商后的 TLS metadata。
- `DatagramInfo`：UDP socket id、当前 peer addr、local addr；启用 `tls` feature 时，TCP stream transform context 可携带 TCP-derived TLS metadata。
- `ConnectionStats`：TCP connection counter snapshot handle。
- `Context<W>`：TCP handler context，支持 `write`、`flush`、`write_and_flush`、`close`、`channel`、`stats`；启用 `tls` feature 时支持 `tls`。
- `DatagramContext<W>`：UDP handler context，支持 current-peer 和 explicit-peer write/flush/close。
- `InboundContext`：inbound stage identity context；TLS TCP connection 中包含 `tls`。
- `BusinessContext`：business stage identity context；TLS TCP connection 中包含 `tls`。
- `OutboundContext`：outbound stage identity context；TLS TCP connection 中包含 `tls`。
## `channel`
- `Channel<W>`：TCP external handle，支持 identity、queue capacity、stats、write/flush/write_and_flush/close。
- `DatagramChannel<W>`：UDP external handle，支持 socket identity、queue capacity、write_to/flush/write_to_and_flush/close。
## `life`
- `CloseReason`：TCP connection 关闭原因。
- `NoLife`：默认 no-op lifecycle hooks。
- `Life`：server、connection 和 UDP socket lifecycle hook trait。
## `tls`
- `TlsContextBuilder::for_server()`：创建 server TLS context builder。
- `TlsContextBuilder::for_client()`：创建 `NoTrust` 状态的 typestate client TLS context builder。
- `ServerTlsContextBuilder`：接收 certificate chain、private key、required 或 optional client-auth roots、ALPN protocols、SNI-specific identities，构建 `ServerTlsContext`。
- `ClientTlsContextBuilder<NoTrust>`：可设置 server name 和 trust strategy，但没有 `build`。
- `ClientTlsContextBuilder<HasTrust>`：选择 roots 或 verifier 后构建 `ClientTlsContext`，可通过 `client_identity_pem` / `client_identity_der` 配置 mTLS client identity，也可发布 ALPN protocols。
- `TlsInfo`：TCP `Context::tls`、stream stage context 和 `ConnInfo::tls` 可访问的 TLS metadata，包含 peer certificates、selected ALPN，以及连接使用的 client/server name。
- `client_auth_required_pem` / `client_auth_required_der`：要求 client certificate 由 trusted roots 签发。
- `client_auth_optional_pem` / `client_auth_optional_der`：允许 client 不提供 certificate；如果提供 certificate，则仍会验证。
- `alpn_protocols`：配置 client 或 server context 发布的 ALPN protocols。协议名不能为空，且最长 255 bytes。
- `sni_certificate_pem` / `sni_certificate_der`：添加 SNI-specific server certificate identities。也可以通过 `certificate_chain_*` 加 `private_key_*` 配置 default fallback certificate。
- `native_roots`、`webpki_roots`、`danger_accept_invalid_certs` 分别由 `tls-native-roots`、`tls-webpki-roots`、`tls-dangerous` feature 控制。
## `pipeline::stream`
- `builder::pipeline()`：TCP builder 起点。
- `builder::PipelineBuilder<...>`：携带阶段状态和消息类型的 TCP builder。
- `builder::IntoStreamPipeline`：把 ready builder 转成 runtime stream pipeline。
- `builder::IntoPipeline`：stream pipeline 兼容转换 trait。
- `runtime::StreamPipeline<...>`：TCP runtime pipeline 类型，通常不直接命名。
- `runtime::Pipeline<...>`：`StreamPipeline` 的兼容 type alias。
- `runtime::StreamRuntimePipeline`：TCP transport 运行 typed pipeline 所需的 public bound。
- `runtime::RuntimePipeline`：`StreamRuntimePipeline` 的兼容 alias trait。
## `pipeline::datagram`
- `builder::datagram_pipeline()`：UDP builder 起点。
- `builder::DatagramPipelineBuilder<...>`：携带阶段状态和消息类型的 UDP builder。
- `builder::IntoDatagramPipeline`：把 ready builder 转成 runtime datagram pipeline。
- `runtime::DatagramPipeline<...>`：UDP runtime pipeline 类型，通常不直接命名。
- `runtime::DatagramRuntimePipeline`：UDP transport 运行 typed pipeline 所需的 public bound。
## `pipeline::core`
- `Identity`：空 stage pipe，实现原样通过。
- `Then<A, B>`：静态组合两个 stage pipe。
- `PipeStep<T, F>`：runtime 优化用的 ready/future stage step。
- `InboundPipe<I>` / `BusinessPipe<I>` / `OutboundPipe<I>`：内部 stage 链处理 trait，但因 builder/runtime bounds 公开。
- `Start` / `InboundPhase` / `BusinessPhase` / `Ready`：builder state marker。
## `transport::tcp`
- `TcpConnectionConfig`：TCP 连接配置。
- `TcpServerConfig` / `ServerConfig`：`TcpConnectionConfig` type alias。
- `TcpClientConfig`：`TcpConnectionConfig` type alias。
- `TcpServer<F, L>`：TCP server builder。
- `TcpServer::tls`：`tls` feature 下启用 server-side TLS。
- `TcpServerHandle`：server shutdown/wait handle。
- `TcpClient<F, L>`：TCP client builder。
- `TcpClient::tls`：`tls` feature 下启用 client-side TLS。
- `TcpClientHandle<W>`：active TCP client handle。
- `PipelineFactory<F>`：client reusable pipeline factory wrapper。
- `PipelineInstance<B>`：client single-use pipeline wrapper。
## `transport::udp`
- `UdpSocketConfig`：UDP socket 配置。
- `UdpServerConfig` / `UdpClientConfig`：`UdpSocketConfig` type alias。
- `UdpServer<F, L>`：UDP server socket builder。
- `UdpServerHandle`：UDP server shutdown/wait handle。
- `UdpClient<F, L>`：UDP client socket builder。
- `UdpClientHandle<W>`：active UDP client handle。
## `client` And `server`
- `client::TcpClient` / `client::TcpClientHandle` / `client::TcpClientConfig`：client 模块下的 TCP re-export。
- `client::UdpClient` / `client::UdpClientHandle` / `client::UdpClientConfig`：client 模块下的 UDP re-export。
- `server::TcpServer` / `server::TcpServerHandle` / `server::TcpServerConfig` / `server::ServerConfig`：server 模块下的 TCP re-export。
- `server::UdpServer` / `server::UdpServerHandle` / `server::UdpServerConfig`：server 模块下的 UDP re-export。