After wrapping each net.Conn in a session recorder, an SSH bastion's throughput collapsed. What did the wrapper break?

## What the wrapper did The recorder looks harmless: ```go type recordConn struct { net.Conn log io.Writer } func (c *recordConn) Read(b []byte) (int, error) { n, err := c.Conn.Read(b) c.log.Write(b[:n]) return n, err } ``` Embedding promotes every `net.Conn` method, so `*recordConn` satisfies `net.Conn` and every call site keeps compiling. What changed is invisible in the type system: the value now flowing through the program has the method set of `*recordConn`, which is `net.Conn`'s methods and nothing more. Every method the *concrete* connection had beyond that — and every optional interface built on those methods — is gone from the outside world's view. ## Why throughput collapses A bastion is two connections and a copy in each direction, typically `io.Copy(dst, src)`. `io.Copy` probes: source for `io.WriterTo`, then destination for `io.ReaderFrom`. Unwrapped, one of those probes hits the concrete TCP connection, which on Linux implements `ReadFrom` in terms of the kernel's splice/sendfile machinery: bytes move between two file descriptors without ever entering your address space. That is one syscall per large chunk, no user-space buffer, and no allocation. With the wrapper, both probes fail. `io.Copy` allocates a 32 KiB buffer and runs the generic loop: `read` syscall into the buffer, copy of the bytes into your process, `write` syscall out. For a bastion pushing bulk data, that is a large multiple of the syscalls and a fresh copy of every byte, and it shows up as CPU time in the proxy process and as a throughput ceiling for the session. ## Why nobody noticed at build time This is the defining property of optional capability probing: **the failure is silent**. There is no compile error — the wrapper satisfies the declared interface. There is no run-time error — a failed probe is a normal outcome and simply selects the fallback. There is no vet diagnostic, because forwarding an optional interface is a design obligation, not a language rule. The only signal is performance, and only if someone measures. ## Diagnosing it The honest diagnostic here is an end-to-end throughput measurement, taken twice: push a large, known payload through the bastion with the recorder enabled and with it disabled, on the same hosts and the same path, and compare bytes per second and CPU seconds per gigabyte. A wrapper that removed a kernel path shows a step change in both, and the step is proportional to bytes moved, which distinguishes it from a per-connection or per-request regression. Confirm the mechanism rather than guessing: a CPU profile of the proxy will show time in the copy loop and in memory moves that were not there before, and a syscall count per megabyte will have jumped. ## The correctness half, which is worse than the speed half Speed is the visible symptom; the dangerous loss is behavioural. `*net.TCPConn` has `CloseWrite() error`, and forwarding proxies probe for it — usually with an inline `interface{ CloseWrite() error }` — to half-close one direction when the other side sends EOF. Wrapped, the probe fails, the proxy falls back to a full `Close` or to nothing at all, and sessions either truncate or hang until a timeout. The same applies to `SyscallConn`, used by code that needs the raw descriptor. Losing an optimisation costs money; losing half-close costs correctness. ## Fixes, in order of preference 1. **Wrap narrowly.** Record only the direction you must record. The other direction keeps its raw connection and its kernel path. Most session recording only needs one side captured in full. 2. **Forward the capability.** Give the wrapper the methods it hides, delegating to the embedded value: ```go func (c *recordConn) CloseWrite() error { if cw, ok := c.Conn.(interface{ CloseWrite() error }); ok { return cw.CloseWrite() } return c.Conn.Close() } ``` Note the shape: the wrapper probes what it holds, so a wrapper around a connection that never had the capability still behaves sanely. 3. **Expose what you hold.** Add an `Unwrap()` accessor and document it, so a caller that needs the underlying value can walk to it. This is the only fix that survives capabilities invented after your wrapper was written, since you cannot forward a method you have never heard of. ## The tension you must state out loud You cannot both observe every byte and let the kernel move them without you. For the direction you genuinely record, the fast path is unrecoverable by definition, and the right answer is to say so and to scope the recording as tightly as the requirement allows. The mistake in the incident was not recording; it was wrapping *both* directions, and every connection, when the requirement covered one.