The pipe between machines
You're writing a tool that needs to talk to a remote service. Maybe it's a chat client sending messages to a friend, or a CLI tool fetching data from an API. You type a command, hit enter, and wait for the server to reply. The connection is the pipe between your machine and the world.
Rust gives you that pipe through TcpStream. The name stands for Transmission Control Protocol stream. TCP is the reliable backbone of the internet. It guarantees that bytes arrive in the exact order you sent them, and it retries automatically if a packet gets lost. You don't have to build that reliability yourself. The operating system handles the handshake, the sequencing, and the retransmission. Your job is to open the pipe, push bytes in one end, and pull bytes out the other.
The catch is that raw network I/O is slow. Asking the operating system to send one byte at a time is like mailing a single letter for every word you want to say. The overhead of context switching and system calls destroys performance. You need buffers. A buffer is a local holding area in memory. You fill it up with data, then send the whole batch to the OS in one go. BufReader and BufWriter manage this buffering for you, turning slow, chunky network operations into fast, smooth streams.
A minimal synchronous client
Start with the standard library. std::net::TcpStream is all you need for a simple connection. The code below connects to a server, sends a message, and reads the response. It uses the ? operator to propagate errors, which is the idiomatic way to handle failures in Rust. If anything goes wrong, the error bubbles up to main and prints a message.
use std::io::{self, BufRead, BufReader, Write};
use std::net::TcpStream;
/// Connects to a server, sends a greeting, and prints the response.
fn main() -> io::Result<()> {
// Target address: localhost on port 8080
let addr = "127.0.0.1:8080";
// Establish the TCP connection. Blocks until connected or failed.
let stream = TcpStream::connect(addr)?;
// Clone the stream to get a separate handle for reading.
// This is necessary because BufWriter will take ownership of the original.
let mut reader = BufReader::new(stream.try_clone()?);
let mut writer = BufWriter::new(stream);
// Send a message to the server
let message = "Hello, server!\n";
writer.write_all(message.as_bytes())?;
// Force the buffered data out to the network immediately
writer.flush()?;
// Read the response line by line
let mut response = String::new();
reader.read_line(&mut response)?;
println!("Server responded: {}", response.trim());
Ok(())
}
The connect call blocks. Your program pauses until the server accepts the connection or the OS gives up. Once connected, you wrap the stream in BufReader and BufWriter. These wrappers sit between your code and the raw socket. When you call write_all, the data goes into the writer's internal buffer. It doesn't hit the network yet. You must call flush to push the buffer contents to the OS. When you call read_line, the reader pulls data from the network into its own buffer, then extracts a line for you.
Don't guess about flushing. Call flush explicitly, or your data sits in memory while the server waits forever.
Why you need two handles
Notice the try_clone() call. This is a classic Rust moment. TcpStream is not automatically clonable in the way a String is. If you pass the stream directly to BufWriter, the writer takes ownership. The stream moves into the writer. You can't read from it anymore because you no longer have a reference to it. The compiler rejects this with E0382 (use of moved value).
You need two handles to the same socket: one for reading, one for writing. try_clone() creates a new TcpStream that points to the exact same underlying connection. It's cheap. It doesn't copy data. It just bumps an internal reference count. The community convention is to call try_clone() on the stream before wrapping it, so you can hand the original to the writer and the clone to the reader.
If you forget to clone, you hit the borrow checker. The compiler tells you the value was moved. You can't move the same value twice. The fix is always the same: clone the handle first.
// BAD: stream moves into writer. You can't read from it later.
let mut writer = BufWriter::new(stream);
let mut reader = BufReader::new(stream); // E0382: use of moved value
// GOOD: Clone the stream to get a second handle.
let reader_stream = stream.try_clone()?;
let mut writer = BufWriter::new(stream);
let mut reader = BufReader::new(reader_stream);
try_clone returns an io::Result<TcpStream> because cloning can fail. It's rare, but it can happen if the socket is in a bad state. Always handle the result with ?.
Trust the borrow checker here. It's protecting you from using a stream after it's been consumed. Clone the handle, and you're free to read and write independently.
The buffering trap
Buffers are powerful, but they introduce a subtle timing issue. When you write to a BufWriter, the data stays in memory until the buffer fills up or you call flush. If you're implementing a line-based protocol (like HTTP or a chat protocol), the server expects a newline character to signal the end of a message. If you send the newline but don't flush, the server never sees it. It waits for more data. Your client waits for a response. Both sides hang. This is a deadlock.
The fix is to call flush after every logical message. In the example above, flush is called right after write_all. This ensures the data leaves your machine immediately.
Another pitfall is read_line. This method reads until it finds a newline character. If the server sends data without a newline, read_line blocks forever. It waits for the newline that never comes. If you're talking to a binary protocol, read_line is the wrong tool. Use read_exact to read a fixed number of bytes, or read to grab whatever is available.
// Read exactly 4 bytes (e.g., a length prefix)
let mut buffer = [0u8; 4];
stream.read_exact(&mut buffer)?;
// Read until newline (e.g., a text message)
let mut line = String::new();
reader.read_line(&mut line)?;
Match the read method to the protocol. Line-based protocols need read_line. Binary protocols need read_exact. Mixing them up causes hangs.
When blocking isn't enough
The synchronous approach works fine for simple scripts. It's easy to read and debug. But it has a hard limit: one connection per thread. If you're building a server that handles thousands of clients, or a UI app that needs to stay responsive while fetching data, blocking I/O is a bottleneck. When read_line blocks, the entire thread stops. Nothing else happens.
This is where async Rust comes in. The tokio runtime is the standard for high-performance network services. It allows you to write code that looks synchronous but runs concurrently. You can have thousands of connections on a single thread, switching between them whenever one is waiting for data.
The async version of a TCP client uses tokio::net::TcpStream. The API is similar, but every method returns a future that you must .await. You also need to split the stream differently. In async Rust, you use into_split to get a read half and a write half. This consumes the stream and returns two separate types that implement AsyncRead and AsyncWrite.
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::net::TcpStream;
/// Async client that connects, sends a message, and reads the response.
#[tokio::main]
async fn main() -> std::io::Result<()> {
// Connect asynchronously. Returns immediately with a future.
let stream = TcpStream::connect("127.0.0.1:8080").await?;
// Split the stream into read and write halves.
// This is the async equivalent of try_clone, but more efficient.
let (mut reader, mut writer) = stream.into_split();
let mut reader = BufReader::new(reader);
// Send a message
writer.write_all(b"Hello, async server!\n").await?;
writer.flush().await?;
// Read the response
let mut line = String::new();
reader.read_line(&mut line).await?;
println!("Response: {}", line);
Ok(())
}
into_split is the async convention. It's better than try_clone because it avoids the overhead of reference counting. The read half and write half are independent. You can hand them off to different tasks. The runtime manages the concurrency.
Add tokio = { version = "1", features = ["full"] } to your Cargo.toml to use this code. The full feature enables the runtime, the macros, and the I/O utilities.
Async isn't magic. It's just a smarter way to wait. Use it when you need to handle many connections or keep a UI responsive.
Decision: Sync vs Async vs Raw
Choose the right tool for your workload. The standard library is fast and simple. Tokio is scalable and flexible. Raw streams are for low-level control.
Use std::net::TcpStream when you're writing a simple script or a CLI tool that talks to one server at a time. The synchronous API is straightforward, and the overhead of a runtime isn't worth it for a single connection. Use std::net::TcpStream when you want zero dependencies. The standard library is always available, and the code is easy to read.
Use tokio::net::TcpStream when you're building a server that handles many clients, or a client that needs to talk to multiple servers concurrently. Use tokio::net::TcpStream when you need to integrate with other async libraries, like HTTP clients or database drivers. The async runtime handles the concurrency for you, letting you write clean, linear code.
Use BufReader and BufWriter when you're working with text or line-based protocols. The buffering improves performance by reducing system calls. Use raw read and write when you're implementing a binary protocol with fixed-length messages. Buffers can hide data boundaries, making it harder to parse binary formats.
Use try_clone when you need to read and write from the same stream in the synchronous standard library. Use into_split when you're working with async streams in Tokio. The split is more efficient and fits the async mental model.
Reach for the standard library first. Add async only when you hit a concurrency wall. Premature optimization with Tokio adds complexity that often isn't needed.