TheFoxOverflow/network-protocol-skill / skills/network-protocol
network-protocol
UnverifiedUse whenever the user wants to design, implement, review, or debug a network protocol or client/server wire communication over TCP, UDP, QUIC, TLS, WebSockets, Unix domain, or raw sockets — framing, binary/wire formats, RPC, handshakes, message formats. Also use to capture and analyze protocol traffic on the wire (tcpdump, Wireshark/tshark, scapy, custom dissectors); to deploy or troubleshoot a protocol in cloud and orchestrated networks (AWS VPC, GCP networking, Kubernetes and CNI, load balancers, MTU, NAT); and as a study aid for networking certifications (CCNA, subnetting, OSI/TCP-IP, routing and switching). Trigger on debugging symptoms too: messages merged or split, partial reads/writes, hangs that never time out, intermittent corruption, works-on-localhost-fails-over-the-network, undetected connection drops, or memory blowups under load. Do NOT use it for pure HTTP-REST-API calls with an existing client library or front-end fetch(), where no custom protocol is involved.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.3 KB |
| assets/cross-language-notes.md | markdown | 13.0 KB |
| assets/framed_protocol.py | script | 37.0 KB |
| assets/k8s-deployment.yaml | config | 4.9 KB |
| assets/npro.lua | script | 4.6 KB |
| assets/pyproject.toml | manifest | 1.4 KB |
| assets/subnetting_practice.py | script | 8.6 KB |
| assets/test_protocol.py | script | 21.2 KB |
| references/cloud-and-orchestration.md | markdown | 11.1 KB |
| references/learning-mode.md | markdown | 7.3 KB |
| references/packet-analysis.md | markdown | 11.1 KB |
| references/pitfalls.md | markdown | 28.4 KB |
| references/production-readiness.md | markdown | 14.6 KB |
| references/protocol-design.md | markdown | 16.6 KB |
| references/review-checklist.md | markdown | 9.2 KB |
| references/security.md | markdown | 9.0 KB |
| references/testing.md | markdown | 10.7 KB |
| references/transport-and-io.md | markdown | 12.1 KB |
references/testing.md
View on GitHub# Testing network code by provoking the failures
Network bugs survive normal testing because the happy path doesn't exercise them. The
strategy here is to **deliberately provoke** partial I/O, weird chunk boundaries, loss,
reordering, hostile input, and slow peers — in deterministic tests — instead of hoping
production won't. Treat the failure modes in `references/pitfalls.md` as a test plan.
## Table of contents
1. [Test the parser independently of sockets](#1-test-the-parser-independently-of-sockets)
2. [Chunk-boundary tests (the highest-value tests)](#2-chunk-boundary-tests)
3. [Golden wire-format vectors](#3-golden-wire-format-vectors)
4. [Property-based testing](#4-property-based-testing)
5. [Fuzzing the parser](#5-fuzzing-the-parser)
6. [Fault injection with a fake transport](#6-fault-injection-with-a-fake-transport)
7. [Network condition simulation](#7-network-condition-simulation)
8. [Timeout, liveness & reconnection tests](#8-timeout-liveness--reconnection-tests)
9. [Concurrency & race tests](#9-concurrency--race-tests)
10. [Backpressure & DoS tests](#10-backpressure--dos-tests)
11. [Interop, soak & observability](#11-interop-soak--observability)
12. [Minimum test suite](#12-minimum-test-suite)
---
## 1. Test the parser independently of sockets
Most protocol *logic* bugs live in the parser and state machine, not in the socket calls.
Make both pure (bytes in → messages/actions out, no I/O) so you can test them exhaustively
without a network. The incremental `FrameReader` in `assets/framed_protocol.py` is written
exactly this way: you `feed(bytes)` and pull complete frames; tests drive it directly.
## 2. Chunk-boundary tests
These catch the #1 and #2 bug classes (framing and partial I/O, pitfalls §1–2) and are the
cheapest high-value tests you can write.
- **One byte at a time:** encode a message, then feed the parser the bytes **one at a time**.
After the last byte, exactly one complete message must appear; before it, none.
- **Two (or more) messages in one buffer:** concatenate several encoded messages and feed
them in a single chunk. The parser must yield each message correctly, in order.
- **Message split across two reads:** feed the first K bytes, assert nothing parses, feed the
rest, assert it parses.
- **Random split points:** for each test message, split it at every possible boundary (or
many random boundaries) and assert identical results. A property test (below) generalizes
this.
```python
def test_one_byte_at_a_time():
frame = encode_frame(MSG_DATA, b"hello world")
reader = FrameReader()
out = []
for b in frame: # feed single bytes
reader.feed(bytes([b]))
out += list(reader.read_frames())
assert len(out) == 1 and out[0][2] == b"hello world"
def test_two_in_one_buffer():
reader = FrameReader()
reader.feed(encode_frame(MSG_DATA, b"a") + encode_frame(MSG_DATA, b"bb"))
out = list(reader.read_frames())
assert [f[2] for f in out] == [b"a", b"bb"]
```
If these two tests pass for arbitrary inputs, you've eliminated the most common production
network bug before it ships.
## 3. Golden wire-format vectors
Pin the exact bytes so the wire format can't change silently (catches endianness,
self-referential length, and accidental layout changes — pitfalls §3, §4.3).
- Check in a handful of `(message, exact hex)` pairs. Encoding the message must produce the
hex; decoding the hex must produce the message.
- Include edge values: zero-length payload, max-length payload, integer `1` (proves
big-endian), all-bits-set fields.
- Run on every CI build. A diff here is a deliberate, reviewable protocol change.
```python
GOLDEN = [
(("DATA", b""), bytes.fromhex("4e50524f 01 02 0000 00000000")),
(("DATA", b"\x01"), bytes.fromhex("4e50524f 01 02 0000 00000001 01")),
] # magic 'NPRO', ver 01, type 02, flags 0000, len, payload
```
## 4. Property-based testing
Use a property-testing library (Hypothesis, proptest, QuickCheck, gopter) to assert
invariants over *generated* inputs:
- **Round-trip:** `parse(encode(m)) == m` for any valid message `m`.
- **No crash on arbitrary bytes:** `parse(arbitrary_bytes)` either returns a value or a
clean protocol error — it never panics, hangs, over-allocates, or reads out of bounds.
- **Chunk-invariance:** feeding `encode(m)` to the incremental parser in any chunking yields
the same single message.
- **Idempotence/canonicality:** `encode(parse(encode(m))) == encode(m)` (stable encoding).
## 5. Fuzzing the parser
Fuzzing finds the malformed inputs you didn't think of — the crashes, hangs, and giant
allocations from hostile data (pitfalls §4, §6.7, §10).
- Tools: libFuzzer/AFL++ (C/C++/Rust), `cargo fuzz`, Go native fuzzing (`go test -fuzz`),
Atheris (Python), Jazzer (JVM).
- Target the **pure parser** (bytes → message), which makes fuzzing fast and reproducible.
- Seed the corpus with real/golden messages; let the fuzzer mutate from there. **Structure-
aware** fuzzing (e.g. via Arbitrary) reaches deeper than random bytes.
- Detect both **crashes** and **hangs** (an infinite loop on malformed input is a DoS), and
watch memory (a length-driven huge allocation is a finding — pitfalls §4.1).
- Add any crashing input to a regression corpus.
## 6. Fault injection with a fake transport
Replace the real socket with a controllable stub so integration tests can reproduce
transport misbehavior deterministically. A good fake can:
- **short reads / short writes:** return/accept 1 byte (or a random small count) per call —
proves your loops handle partial I/O (pitfalls §2).
- **EOF mid-message:** close after delivering a partial frame — proves clean error, no hang.
- **delay / stall:** pause before delivering — exercises timeouts (§8).
- **drop / reorder / duplicate / truncate / corrupt:** for datagram protocols especially
(pitfalls §11), and for reliability layers built over UDP.
- **`EAGAIN`/`EINTR`:** for non-blocking/event-loop code paths (pitfalls §6.2, §7.2).
```python
class ShortReadSocket:
"""Wraps real bytes; recv returns at most 1 byte per call to provoke partial reads."""
def __init__(self, data): self.data = bytearray(data)
def recv(self, n):
if not self.data: return b"" # EOF
b, self.data = bytes(self.data[:1]), self.data[1:]
return b
# A protocol built on read_exactly/write_all must pass all tests through this socket.
```
## 7. Network condition simulation
Test against realistic adverse conditions, ideally on the loopback so it runs in CI:
- **Linux `tc`/`netem`:** inject latency, jitter, packet loss, reordering, duplication, and
corruption on an interface. The closest thing to "the real internet" in a test.
- **Toxiproxy:** a programmable TCP proxy that adds latency, bandwidth limits, slow-close,
and connection cuts — scriptable from tests, cross-platform.
- **`comcast` / clumsy (Windows):** convenience wrappers for similar effects.
- Run your full integration suite under: 1–5% loss, added latency, and reordering. Bugs
that only appear "over the real network" (pitfalls §11, §1) reproduce here.
## 8. Timeout, liveness & reconnection tests
- **Vanished peer:** `SIGSTOP` the peer process, or drop its packets with a firewall rule,
and assert your idle timeout/heartbeat fires within the expected window (pitfalls §5.1,
§8.1). A frozen peer is different from a closed one — test both.
- **Abrupt kill:** `SIGKILL` the peer mid-message; assert clean error and cleanup, not a
hang or `SIGPIPE` crash (pitfalls §7.1).
- **Reconnection/backoff:** take the server down and bring it back; assert the client
reconnects with exponential backoff + jitter and resumes correctly, without a retry storm
(pitfalls §8.3).
- **Half-open:** simulate a route blackhole (firewall DROP) so no FIN arrives; assert
detection via heartbeat.
## 9. Concurrency & race tests
- Run under a **race detector**: Go `-race`, C/C++/Rust **ThreadSanitizer**, Java's
concurrency tooling. Many socket-sharing and shared-state bugs (pitfalls §6.6) only show
up here.
- **Many concurrent connections:** hundreds/thousands simultaneously; assert no fd leak,
no memory growth, correct per-connection isolation.
- **Write–write deadlock probe:** have both sides bulk-send without reading and assert your
design/flow-control prevents the deadlock (pitfalls §6.5).
- **Leak checks:** track open fds and memory before/after a load run; they must return to
baseline.
## 10. Backpressure & DoS tests
Turn the security section into tests (`references/security.md` §7):
- **Slow consumer, fast producer:** assert outbound memory stays bounded (backpressure
works), not unbounded growth (pitfalls §9.2).
- **Giant length field:** send a frame claiming a huge payload; assert prompt rejection with
no large allocation (pitfalls §4.1).
- **Slowloris:** open many connections that trickle bytes; assert timeouts/limits reclaim
them.
- **Decompression bomb:** if you decompress, feed a bomb; assert the output-size cap stops
it.
- **Flood:** open connections/requests past your limits; assert graceful shedding with an
error, not a crash.
## 11. Interop, soak & observability
- **Interop / conformance:** test your implementation against an independent one (another
language, or a reference). Different implementations expose assumptions a single codebase
shares. Capture traffic with **Wireshark/tcpdump** to inspect actual bytes when something
disagrees.
- **Soak / long-running:** run for hours/days under steady load; watch for slow leaks
(buffers never trimmed — pitfalls §9.4), fd creep, and latency drift.
- **Load testing:** measure throughput and tail latency at target concurrency; verify
timeouts and limits behave under stress.
- **Observability for debugging:** log state-machine transitions, give each connection a
stable ID, expose metrics (active connections, queue depths, error rates), and keep a way
to capture packets. When a network bug is reported, the actual bytes + the state at the
time are what you need.
## 12. Minimum test suite
If you do nothing else, do these — they cover the highest-probability production failures:
1. **One-byte-at-a-time** parser test (framing + partial reads).
2. **Two-messages-in-one-buffer** parser test (framing).
3. **Short-write** delivery test through a 1-byte-per-call fake socket (partial writes).
4. **Golden hex vectors** for a few messages incl. edge sizes (wire-format stability,
endianness).
5. **Arbitrary-bytes-don't-crash** test, ideally fuzzed (hostile input, bounded allocation).
6. **Idle-timeout fires** when the peer is frozen (liveness, missing-timeout class).
Everything above (simulation, fault injection, concurrency, DoS, interop, soak) raises
confidence further, but these six catch the bugs that most often reach production.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |