Build a TCP Proxy

Build a TCP Proxy

In 1998, HAProxy's author Willy Tarreau wrote the first proxy server capable of handling tens of thousands of concurrent TCP connections in C, on a machine with 256MB of RAM. His core design philosophy fit in a single sentence: "A proxy is just copying bytes from one socket to another."

That description is remarkably concise—concise enough to make you wonder if there's hidden complexity lurking beneath. There is.

A TCP proxy looks simple, but reaching production grade—correctly handling half-close, connection timeouts, backpressure, and error propagation—requires a deep understanding of TCP's subtleties. And Go's goroutines and io.Copy provide a toolkit that fits this problem almost perfectly.

This chapter starts from the use cases for TCP proxies, dives into the byte-level details of bidirectional data copying, builds a complete production-grade TCP proxy, and then explores advanced techniques like SNI routing and traffic mirroring.

Level 1 · What You Need to Know

TCP Proxy Use Cases

A TCP proxy operates at the transport layer (OSI Layer 4). It doesn't parse application-layer protocols—it only forwards the TCP byte stream. This gives it remarkable versatility:

Load Balancing: Distributing incoming client connections across multiple backend server instances. The simplest strategy is Round-Robin; more sophisticated strategies include Least Connections, Weighted Round-Robin, and IP Hash. TCP-level load balancing requires no understanding of application-layer protocols, making it applicable to HTTP, MySQL, Redis, SMTP, and any other TCP-based application.

SSL Termination: Clients connect to the proxy over TLS; the proxy connects to backends over plaintext (or with different TLS certificates). This frees backend services from managing TLS certificates and centralizes the complexity of certificate renewal. Nginx and HAProxy as SSL termination proxies is one of the most common architectural patterns.

Protocol Inspection: Without fully decoding an application-layer protocol, you can identify the protocol type by inspecting just the first few bytes. A TLS connection's first byte is 0x16 (TLS ClientHello); an HTTP/1.1 connection starts with a method name (GET, POST...); an SSH connection starts with SSH-. Based on protocol detection, the proxy can route connections of different protocol types to different backends.

Traffic Shaping: Rate limiting (bandwidth throttling), injecting latency (simulating network jitter), packet dropping (chaos engineering). These capabilities are extremely valuable in test environments. In Go, traffic shaping requires only inserting a rate-limiting Reader/Writer into the io.Copy path.

Transparent Proxying and NAT Traversal: In some network architectures, the proxy is completely transparent to the client—the client believes it's connecting directly to the backend, but all traffic passes through the proxy. This requires OS-level iptables/nftables rules.

The TCP Connection Lifecycle

To understand TCP proxying, you must first have a precise understanding of a complete TCP connection's lifecycle:

Client                   Proxy                   Backend
  |                       |                       |
  |---SYN--------------->|                       |
  |<--SYN+ACK------------|                       |
  |---ACK---------------->|                       |
  |   (handshake done)    |---SYN--------------->|
  |                       |<--SYN+ACK------------|
  |                       |---ACK---------------->|
  |                       |   (proxy-backend handshake done)
  |                       |                       |
  |===data forward========>|===data forward========>|
  |<==================data back===================<|
  |                       |                       |
  |---FIN---------------->|                       |  ← client closes write
  |<--ACK-----------------|                       |
  |                       |---FIN---------------->|  ← proxy propagates close
  |                       |<--ACK-----------------|
  |                       |<--FIN-----------------|  ← backend closes write
  |<--FIN-----------------|                       |  ← proxy propagates close
  |---ACK---------------->|                       |

The proxy actually establishes two independent TCP connections, then forwards the byte stream between them. This means the proxy must handle each connection's closure events independently—this is the origin of the "half-close problem."

Half-Close: The Overlooked Complexity

TCP connections are full-duplex: data can flow in both directions simultaneously. TCP allows either direction to be closed independently:

• Calling conn.CloseWrite() (or sending a FIN) closes the write direction while keeping the read direction open
• The peer can still send data to us until it closes its write direction as well

Many proxy implementations ignore half-close: when one side closes, they close the entire connection. This is fine in most cases, but for certain protocols (such as some FTP data transfer modes), it causes data truncation.

The correct half-close handling pattern:

When Client → Backend direction closes:
  Propagate the close to Backend (send FIN to Backend)
  But keep the Backend → Client direction transferring data

When Backend → Client direction closes:
  Propagate the close to Client (send FIN to Client)
  But keep the Client → Backend direction open (if there's still data)

Level 2 · Principles and Mechanics

The Bidirectional io.Copy Pattern

The core of a TCP proxy is bidirectional data copying. The simplest implementation uses two goroutines, each responsible for one direction:

func proxy(client, backend net.Conn) {
    done := make(chan struct{}, 2)

    // client → backend
    go func() {
        io.Copy(backend, client)
        done <- struct{}{}
    }()

    // backend → client
    go func() {
        io.Copy(client, backend)
        done <- struct{}{}
    }()

    // Wait for either direction to finish
    <-done
    // When one side is done, close both connections
    client.Close()
    backend.Close()
    <-done // Wait for the other goroutine to exit too
}

This is the most concise implementation, but it has a problem: when data transfer in one direction ends (when io.Copy returns), it immediately closes both connections—including the other direction, which may still have data in flight. For most HTTP proxy scenarios this is fine, but for full-duplex protocols (WebSocket, gRPC streaming) it can cause data loss.

io.Copy internals: io.Copy reads from a Reader and writes to a Writer in a loop, until it encounters io.EOF or an error. It uses a default 32KB buffer (io.copyBuffer's default). When the Reader returns io.EOF, io.Copy returns nil; when it encounters other errors, it returns that error.

A TCP connection's Read returns io.EOF when the peer calls Close() or CloseWrite(), and returns a specific error on other network failures.

Connection Pool and Upstream Connection Reuse

If every incoming client connection maps to a new TCP connection to the backend, two problems emerge at high concurrency:

1. Connection establishment latency (TCP + potentially TLS handshake) adds to every request's response time
2. Large numbers of short-lived connections produce massive TIME_WAIT accumulation, consuming system file descriptors

The solution is a connection pool: pre-establish and maintain a set of persistent connections to backends; new proxy requests borrow a connection from the pool and return it when done.

type ConnPool struct {
    addr    string
    pool    chan net.Conn
    maxSize int
    dialer  net.Dialer
}

func NewConnPool(addr string, maxSize int) *ConnPool {
    return &ConnPool{
        addr:    addr,
        pool:    make(chan net.Conn, maxSize),
        maxSize: maxSize,
    }
}

func (p *ConnPool) Get(ctx context.Context) (net.Conn, error) {
    // Try to get from pool first
    select {
    case conn := <-p.pool:
        if isAlive(conn) {
            return conn, nil
        }
        conn.Close()
        // Connection is dead, fall through to create new one
    default:
        // Pool is empty, create new connection
    }

    return p.dialer.DialContext(ctx, "tcp", p.addr)
}

func (p *ConnPool) Put(conn net.Conn) {
    select {
    case p.pool <- conn:
        // Returned to pool
    default:
        // Pool is full, close the connection
        conn.Close()
    }
}

func isAlive(conn net.Conn) bool {
    // Try reading one byte with a tiny timeout
    // If the connection is closed, Read returns immediately with an error
    conn.SetReadDeadline(time.Now().Add(1 * time.Millisecond))
    defer conn.SetReadDeadline(time.Time{}) // Clear deadline
    _, err := conn.Read(make([]byte, 1))
    return err != nil && errors.Is(err, os.ErrDeadlineExceeded)
}

The isAlive function uses a trick: set a 1-millisecond read deadline, then attempt to read. If the connection is closed, Read returns immediately with an error (io.EOF or connection reset); if the connection is healthy, Read times out after 1ms and returns os.ErrDeadlineExceeded—confirming the connection is good (just has no data pending).

Deadline Management: Preventing Goroutines from Blocking Forever

Read and write operations on TCP connections have no timeout by default. If a backend service hangs (extremely slow response or no response at all), the proxy's goroutine will block forever in io.Copy, consuming memory and file descriptors, ultimately leading to resource exhaustion.

Go's net.Conn provides two Deadline settings:

conn.SetDeadline(time.Now().Add(30 * time.Second))      // both read and write timeout
conn.SetReadDeadline(time.Now().Add(30 * time.Second))  // read only
conn.SetWriteDeadline(time.Now().Add(30 * time.Second)) // write only

Deadlines are absolute times (time.Time), not durations (time.Duration). Once a Deadline is set, it does not auto-renew. You must manually update the Deadline after each successful read/write—otherwise the connection will time out after the initial deadline regardless of whether data transfer is ongoing.

The correct Deadline management pattern:

// Don't do this (Deadline doesn't renew on data transfer)
conn.SetDeadline(time.Now().Add(30 * time.Second))
io.Copy(dst, src) // if transfer takes more than 30 seconds, it times out

// Do this instead (custom Reader/Writer that renews deadline after each I/O)
type deadlineConn struct {
    net.Conn
    timeout time.Duration
}

func (c *deadlineConn) Read(b []byte) (n int, err error) {
    c.SetReadDeadline(time.Now().Add(c.timeout))
    return c.Conn.Read(b)
}

func (c *deadlineConn) Write(b []byte) (n int, err error) {
    c.SetWriteDeadline(time.Now().Add(c.timeout))
    return c.Conn.Write(b)
}

Level 3 · Code Practice

Building a Complete TCP Proxy

1. Core Proxy Logic

package main

import (
    "errors"
    "fmt"
    "io"
    "log/slog"
    "net"
    "time"
)

type Proxy struct {
    listen  string
    backend string
    logger  *slog.Logger
}

func NewProxy(listen, backend string, logger *slog.Logger) *Proxy {
    return &Proxy{listen: listen, backend: backend, logger: logger}
}

func (p *Proxy) ListenAndServe() error {
    ln, err := net.Listen("tcp", p.listen)
    if err != nil {
        return fmt.Errorf("listen %s: %w", p.listen, err)
    }
    defer ln.Close()

    p.logger.Info("proxy started", "listen", p.listen, "backend", p.backend)

    for {
        clientConn, err := ln.Accept()
        if err != nil {
            if errors.Is(err, net.ErrClosed) {
                return nil
            }
            p.logger.Error("accept error", "err", err)
            continue
        }
        go p.handleConn(clientConn)
    }
}

func (p *Proxy) handleConn(clientConn net.Conn) {
    defer clientConn.Close()

    clientAddr := clientConn.RemoteAddr().String()
    p.logger.Info("new connection", "client", clientAddr)

    backendConn, err := net.DialTimeout("tcp", p.backend, 10*time.Second)
    if err != nil {
        p.logger.Error("dial backend failed", "backend", p.backend, "err", err)
        return
    }
    defer backendConn.Close()

    errCh := make(chan error, 2)

    // client → backend
    go func() {
        _, err := io.Copy(backendConn, clientConn)
        // Propagate half-close: close write direction only
        if tc, ok := backendConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()

    // backend → client
    go func() {
        _, err := io.Copy(clientConn, backendConn)
        if tc, ok := clientConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()

    // Wait for both directions to complete
    for i := 0; i < 2; i++ {
        if err := <-errCh; err != nil && !isConnClosedErr(err) {
            p.logger.Warn("copy error", "client", clientAddr, "err", err)
        }
    }

    p.logger.Info("connection closed", "client", clientAddr)
}

func isConnClosedErr(err error) bool {
    if err == nil || errors.Is(err, io.EOF) {
        return true
    }
    var netErr *net.OpError
    if errors.As(err, &netErr) {
        return netErr.Err.Error() == "use of closed network connection"
    }
    return false
}

2. Protocol Detection: Distinguishing HTTP from TLS Traffic

Using bufio.Reader's Peek method, we can "sniff" the first few bytes without consuming them:

type Protocol int

const (
    ProtocolUnknown Protocol = iota
    ProtocolHTTP
    ProtocolTLS
    ProtocolSSH
)

func detectProtocol(conn net.Conn) (Protocol, net.Conn) {
    br := bufio.NewReader(conn)

    header, err := br.Peek(5)
    if err != nil {
        return ProtocolUnknown, conn
    }

    var proto Protocol
    switch {
    case header[0] == 0x16 && header[1] == 0x03:
        // TLS: ContentType=Handshake(0x16), Version=TLS(0x03.xx)
        proto = ProtocolTLS
    case string(header[:4]) == "GET " ||
        string(header[:5]) == "POST " ||
        string(header[:5]) == "HEAD " ||
        string(header[:4]) == "PUT ":
        proto = ProtocolHTTP
    case string(header[:4]) == "SSH-":
        proto = ProtocolSSH
    default:
        proto = ProtocolUnknown
    }

    // Return a wrapped conn that reads from the buffer first
    return proto, &bufferedConn{Conn: conn, reader: br}
}

type bufferedConn struct {
    net.Conn
    reader *bufio.Reader
}

func (c *bufferedConn) Read(b []byte) (int, error) {
    return c.reader.Read(b)
}

3. PROXY Protocol for Client IP Preservation

When a proxy sits between the client and backend, the backend sees the proxy's IP as the source, not the real client's. The PROXY protocol (invented by HAProxy) sends a special header line immediately after TCP connection establishment, carrying the real client IP:

PROXY TCP4 192.168.1.100 10.0.0.1 54321 80\r\n

Sending the PROXY protocol header:

func sendProxyProtocol(dst net.Conn, clientAddr, serverAddr net.Addr) error {
    clientTCP := clientAddr.(*net.TCPAddr)
    serverTCP := serverAddr.(*net.TCPAddr)

    network := "TCP4"
    if clientTCP.IP.To4() == nil {
        network = "TCP6"
    }

    header := fmt.Sprintf("PROXY %s %s %s %d %d\r\n",
        network,
        clientTCP.IP.String(),
        serverTCP.IP.String(),
        clientTCP.Port,
        serverTCP.Port,
    )

    _, err := fmt.Fprint(dst, header)
    return err
}

4. Full Multi-Backend Load Balancing Proxy

type Balancer struct {
    backends []*Backend
    current  uint64
}

type Backend struct {
    addr    string
    healthy atomic.Bool
}

func NewBalancer(addrs []string) *Balancer {
    backends := make([]*Backend, len(addrs))
    for i, addr := range addrs {
        b := &Backend{addr: addr}
        b.healthy.Store(true)
        backends[i] = b
    }
    return &Balancer{backends: backends}
}

func (b *Balancer) NextHealthy() (string, bool) {
    start := atomic.AddUint64(&b.current, 1)
    for i := 0; i < len(b.backends); i++ {
        idx := (start + uint64(i)) % uint64(len(b.backends))
        backend := b.backends[idx]
        if backend.healthy.Load() {
            return backend.addr, true
        }
    }
    return "", false
}

type LoadBalancedProxy struct {
    listen   string
    balancer *Balancer
    logger   *slog.Logger
    active   atomic.Int64
    total    atomic.Int64
}

func (p *LoadBalancedProxy) handleConn(clientConn net.Conn) {
    defer clientConn.Close()

    p.active.Add(1)
    p.total.Add(1)
    defer p.active.Add(-1)

    backendAddr, ok := p.balancer.NextHealthy()
    if !ok {
        p.logger.Error("no healthy backends available")
        return
    }

    backendConn, err := net.DialTimeout("tcp", backendAddr, 10*time.Second)
    if err != nil {
        p.logger.Error("dial backend", "addr", backendAddr, "err", err)
        return
    }
    defer backendConn.Close()

    // Send real client IP via PROXY protocol
    if err := sendProxyProtocol(backendConn, clientConn.RemoteAddr(), clientConn.LocalAddr()); err != nil {
        p.logger.Error("send proxy protocol", "err", err)
        return
    }

    errCh := make(chan error, 2)

    go func() {
        _, err := io.Copy(backendConn, clientConn)
        if tc, ok := backendConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()

    go func() {
        _, err := io.Copy(clientConn, backendConn)
        if tc, ok := clientConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()

    <-errCh
    <-errCh
}

5. Traffic Logging with a Tee Conn

Insert a middleware io.Writer to intercept all traffic for logging:

// TeeConn sends all read/written data to an io.Writer simultaneously
type TeeConn struct {
    net.Conn
    w io.Writer
}

func (c *TeeConn) Read(b []byte) (int, error) {
    n, err := c.Conn.Read(b)
    if n > 0 {
        c.w.Write(b[:n])
    }
    return n, err
}

func (c *TeeConn) Write(b []byte) (int, error) {
    n, err := c.Conn.Write(b)
    if n > 0 {
        c.w.Write(b[:n])
    }
    return n, err
}

// Usage:
logFile, _ := os.Create(fmt.Sprintf("traffic-%s.log", time.Now().Format("20060102-150405")))
teedClientConn := &TeeConn{Conn: clientConn, w: logFile}
// Use teedClientConn in place of clientConn for data copying

Level 4 · Advanced Topics and Edge Cases

HAProxy-Style Health Checking

Production load-balancing proxies need to periodically check whether backends are healthy and remove unhealthy backends from the rotation:

type HealthChecker struct {
    backends []*Backend
    interval time.Duration
    timeout  time.Duration
    logger   *slog.Logger
}

func (hc *HealthChecker) Start(ctx context.Context) {
    ticker := time.NewTicker(hc.interval)
    defer ticker.Stop()

    hc.checkAll() // check immediately on startup

    for {
        select {
        case <-ticker.C:
            hc.checkAll()
        case <-ctx.Done():
            return
        }
    }
}

func (hc *HealthChecker) checkAll() {
    for _, b := range hc.backends {
        go hc.checkOne(b)
    }
}

func (hc *HealthChecker) checkOne(b *Backend) {
    conn, err := net.DialTimeout("tcp", b.addr, hc.timeout)
    if err != nil {
        if b.healthy.CompareAndSwap(true, false) {
            hc.logger.Warn("backend unhealthy", "addr", b.addr, "err", err)
        }
        return
    }
    conn.Close()

    if b.healthy.CompareAndSwap(false, true) {
        hc.logger.Info("backend recovered", "addr", b.addr)
    }
}

CompareAndSwap (CAS) ensures that the log message "backend unhealthy" or "backend recovered" is emitted exactly once per state transition, not on every health check cycle.

Connection Limits and Backpressure

If client connections arrive faster than the backend can handle them, an unconstrained proxy will overload the backend. Two protection mechanisms:

Connection limit: Use a semaphore to cap concurrent connections:

type LimitedProxy struct {
    *Proxy
    sem chan struct{} // semaphore; capacity = max concurrent connections
}

func NewLimitedProxy(p *Proxy, maxConns int) *LimitedProxy {
    return &LimitedProxy{
        Proxy: p,
        sem:   make(chan struct{}, maxConns),
    }
}

func (lp *LimitedProxy) handleConn(clientConn net.Conn) {
    // Non-blocking attempt to acquire semaphore
    select {
    case lp.sem <- struct{}{}:
        defer func() { <-lp.sem }()
    default:
        // At max connections; reject
        lp.logger.Warn("max connections reached, rejecting",
            "client", clientConn.RemoteAddr(),
            "max", cap(lp.sem),
        )
        clientConn.Close()
        return
    }

    lp.Proxy.handleConn(clientConn)
}

Rate limiting: Insert a rate-limiting Reader into the copy path to throttle bandwidth:

import "golang.org/x/time/rate"

type RateLimitedReader struct {
    reader  io.Reader
    limiter *rate.Limiter
}

func (r *RateLimitedReader) Read(b []byte) (int, error) {
    n, err := r.reader.Read(b)
    if n > 0 {
        ctx := context.Background()
        if err2 := r.limiter.WaitN(ctx, n); err2 != nil {
            return n, err2
        }
    }
    return n, err
}

// Example: throttle to 1MB/s
limiter := rate.NewLimiter(rate.Limit(1<<20), 1<<20)
limitedReader := &RateLimitedReader{reader: clientConn, limiter: limiter}
io.Copy(backendConn, limitedReader)

Traffic Mirroring

Traffic mirroring copies data from each connection simultaneously to multiple targets—one primary and one or more mirrors. Common use cases:

• Shadow testing: Mirror production traffic to a test environment for real-load testing of a new version
• Security auditing: Mirror all traffic to a security analysis system
• Real-time backup: Mirror database write requests to a replica

type MirrorWriter struct {
    primary io.Writer
    mirrors []io.Writer
}

func (mw *MirrorWriter) Write(b []byte) (int, error) {
    // Primary write (on the critical path)
    n, err := mw.primary.Write(b)

    // Async mirror (does not block the primary path)
    for _, m := range mw.mirrors {
        mirror := m
        data := make([]byte, len(b))
        copy(data, b)
        go func() {
            if _, merr := mirror.Write(data); merr != nil {
                // Mirror write failure: log but don't affect primary
                log.Printf("mirror write error: %v", merr)
            }
        }()
    }

    return n, err
}

SNI Routing: TLS Routing Without Decryption

SNI (Server Name Indication) is a TLS extension in which the client sends the target domain name in the ClientHello message. A proxy can read the SNI field and route connections to different backends based on the domain name—without holding a TLS certificate or decrypting the traffic. This is Layer 4 routing, completely opaque to TLS content.

// parseSNI extracts the SNI from a TLS ClientHello by manually parsing
// the TLS record layer—no full TLS handshake required.
func parseSNI(r io.Reader) (sni string, firstBytes []byte, err error) {
    // TLS record layer format:
    //   ContentType (1 byte) = 0x16 (Handshake)
    //   ProtocolVersion (2 bytes)
    //   Length (2 bytes)
    //   Handshake message...

    hdr := make([]byte, 5)
    if _, err = io.ReadFull(r, hdr); err != nil {
        return "", nil, err
    }

    if hdr[0] != 0x16 {
        return "", hdr, nil // not TLS
    }

    recLen := int(hdr[3])<<8 | int(hdr[4])
    data := make([]byte, recLen)
    if _, err = io.ReadFull(r, data); err != nil {
        return "", nil, err
    }

    full := append(hdr, data...)
    // extractSNIFromClientHello parses the handshake bytes
    // (typically using golang.org/x/crypto/cryptobyte)
    sni = extractSNIFromClientHello(data)

    return sni, full, nil
}

// SNI routing proxy
type SNIProxy struct {
    routes map[string]string // domain → backend addr
    logger *slog.Logger
}

func (p *SNIProxy) handleConn(clientConn net.Conn) {
    defer clientConn.Close()

    sni, firstBytes, err := parseSNI(clientConn)
    if err != nil || sni == "" {
        p.logger.Warn("no SNI found, using default backend")
        sni = "default"
    }

    backendAddr, ok := p.routes[sni]
    if !ok {
        p.logger.Warn("no route for SNI", "sni", sni)
        return
    }

    backendConn, err := net.DialTimeout("tcp", backendAddr, 10*time.Second)
    if err != nil {
        p.logger.Error("dial backend", "err", err)
        return
    }
    defer backendConn.Close()

    // Re-send the already-read firstBytes to the backend
    // (the ClientHello must be forwarded intact—the backend needs the full handshake)
    if _, err := backendConn.Write(firstBytes); err != nil {
        p.logger.Error("write first bytes", "err", err)
        return
    }

    // Normal bidirectional copy for the rest
    errCh := make(chan error, 2)
    go func() {
        _, err := io.Copy(backendConn, clientConn)
        if tc, ok := backendConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()
    go func() {
        _, err := io.Copy(clientConn, backendConn)
        if tc, ok := clientConn.(*net.TCPConn); ok {
            tc.CloseWrite()
        }
        errCh <- err
    }()

    <-errCh
    <-errCh
}

Performance Benchmark: Go TCP Proxy vs Nginx

On an 8-core, 16GB machine, using iperf3 to measure throughput:

Go's basic TCP proxy approaches Nginx in performance. The gap comes primarily from:

1. Memory allocation: Every goroutine has its own stack, plus io.Copy's 32KB buffer. Nginx uses more granular memory management.
2. Syscall pattern: Go uses goroutines + netpoll (epoll/kqueue), similar to Nginx's event-driven model at the syscall level, but with different scheduling overhead.

Key optimizations to improve Go TCP proxy performance:

// 1. Use a larger io.Copy buffer
buf := make([]byte, 128*1024) // 128KB beats the default 32KB
io.CopyBuffer(dst, src, buf)

// 2. Enable TCP_NODELAY to reduce Nagle algorithm delays
if tc, ok := conn.(*net.TCPConn); ok {
    tc.SetNoDelay(true)
}

// 3. Tune TCP socket buffer sizes (OS level)
if tc, ok := conn.(*net.TCPConn); ok {
    tc.SetReadBuffer(256 * 1024)
    tc.SetWriteBuffer(256 * 1024)
}

Design Summary: Core Design Decisions for a Production TCP Proxy

Correctly handle half-close: When one side sends FIN, propagate with CloseWrite(), not a full Close(). This is critical for full-duplex protocols (WebSocket, gRPC streaming).

Deadlines, not timeouts: net.Conn has no "timeout" concept—only "Deadline." You must manually update the Deadline after each I/O operation, or wrap the Conn in a custom type that auto-renews.

Connection pooling for upstream: Avoid creating a new TCP connection to the backend for every proxied connection. Use a pool to amortize the handshake cost.

Health checking is mandatory: A load-balancing proxy without health checks keeps sending traffic to unhealthy backends during failures, producing a flood of failed requests for users.

Protocol-agnosticism is both a strength and a limitation: A TCP proxy doesn't understand application-layer protocols, making it universally applicable—but it also cannot do HTTP-path-based routing, rewrite HTTP headers, or similar operations. For those needs, use an HTTP reverse proxy (net/http/httputil.ReverseProxy).

SNI routing is a sweet spot: No decryption required, but domain-based routing is possible—one of the most valuable capabilities between pure TCP proxies and full HTTP proxies, especially for multi-tenant SaaS architectures where you need per-tenant traffic distribution.