# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Test
```bash
# Build the library
cargo build
# Run all tests (none currently defined; add under tests/ or inline with #[cfg(test)])
cargo test
# Run a single test
cargo test <test_name>
# Check compilation without producing artifacts
cargo check
# Format and lint
cargo fmt
cargo clippy
```
The README example requires nightly Rust (`#![feature(async_closure)]`), but the library itself builds on stable Rust ≥ 1.75.
## Architecture
This is a single-file crate (`src/lib.rs`) providing an async TCP client built on the [`aqueue`](https://crates.io/crates/aqueue) actor model. All public API surface is in that one file.
**Core types:**
- **`TcpClient<T>`** — owns the write half of a split Tokio stream, with a `disconnect` flag. `T` is the underlying stream type (typically `TcpStream` or a TLS wrapper). Methods `send`, `send_all`, `flush`, `disconnect` are called directly on the inner value — they are **not** exposed publicly on `TcpClient` directly.
- **`Arc<Actor<TcpClient<T>>>`** — the public handle. The `aqueue::Actor` wraps `TcpClient` and serializes access via message-passing (actors process one message at a time). All public operations go through the actor.
- **`SocketClientTrait`** — the trait implemented on `Arc<Actor<TcpClient<T>>>` that defines the public async API: `send`, `send_all`, `send_ref`, `send_all_ref`, `flush`, `disconnect`. The `_ref` variants take `&[u8]` and assert non-empty; the owned-buffer variants take `B: Deref<Target=[u8]>`.
**Connection flow:**
1. `TcpClient::connect(addr, input_fn, token)` resolves the address, opens a `TcpStream`, splits it into read/write halves, creates the actor, and spawns a Tokio task for the reader.
2. The `input_fn` closure receives `(token, Arc<Actor<TcpClient<T>>>, ReadHalf)` and runs the read loop. It returns `Result<bool>` — `Ok(true)` triggers disconnect on exit, `Ok(false)` means the reader closed gracefully.
3. For non-plain-TCP streams (e.g., TLS), use `TcpClient::connect_stream_type()` which accepts an additional `stream_init` closure to upgrade the raw `TcpStream` before splitting.
**Key dependency:** `aqueue` v1.3 provides the `Actor` type. Its `inner_call` method takes an async closure, runs it with `&mut` access to the inner value, and returns the result — this is how `SocketClientTrait` methods serialize access to the write half.
## README.md
Add bilingual instructions in English and Chinese, referring to: https://github.com/luyikk/rust_netx/blob/master/README.md