Inspiration
Every time we tried to prototype a new network protocol, we ended up rewriting the same boilerplate: hand-crafted TCP/UDP sockets, ad-hoc state machines, and print statements to guess whether packets arrived in the right order. Debugging real protocol bugs (out-of-order delivery, retransmits, malformed headers) meant staring at Wireshark captures and hoping we spotted the anomaly. We wanted a way to describe a protocol the same way we would describe it in a spec document, and then immediately run it, break it, and watch it happen.
What it does
tcpform lets you write send/recv/ack/wait/close steps as a declarative DSL and turns that description into a runnable protocol. A single .tcpf file can be simulated in memory, replayed over real TCP/UDP/TLS/QUIC/WebSocket/Unix sockets, or sent as raw Ethernet frames. On top of that foundation we added finite-state model checking to catch invariant violations before you ever open a socket, a state-aware fuzzer for robustness testing, PCAP/Kaitai/TTCN-3/ASN.1 import and export so tcpform speaks the same language as existing tooling, and a browser-based visualizer that animates every packet exchange, diffs traces, and lets you set breakpoints on a decoded header field.
How we built it
The core engine and CLI are written in Rust for deterministic, low-overhead packet handling, including AF_PACKET raw sockets on Linux and a WASM build that runs the same execution engine directly in the browser. The DSL has its own parser, dependency-graph validator, and Language Server (completion, diagnostics, rename, hover) plus a VS Code extension. Two Docker-based labs (a raw packet exchange and a live dashboard) demonstrate real communication between isolated, non-root containers, and a SQLite-backed dashboard tracks historical runs, flaky tests, and regressions across branches.
Challenges we ran into
Getting raw packet crafting to behave safely was the hardest part: dropping root privileges right after opening AF_PACKET, filtering out kernel-generated RST noise on ports we do not own, and keeping checksums and sequence numbers correct while still allowing intentionally malformed test packets. Reconciling two independent monotonic clocks (client and server) into one causally ordered timeline for the visualizer, and building a deterministic virtual clock so timer-heavy tests run instantly and reproducibly, both took several redesigns.
Accomplishments that we're proud of
Going from describing a TCP handshake in a few lines to a full pipeline that covers model checking, fuzzing, conformance testing, interop comparison across implementations, and CI-ready reports (JUnit, SARIF, OTLP) all driven by the same DSL file. We are also proud of the isolated Docker lab that proves the raw packet path works end-to-end without ever needing host privileges.
What we learned
We learned a lot about the gap between it working in a demo and it being safe to run automatically. Safety limits, permission drops, and loopback-only defaults turned out to be as important as the protocol logic itself.
What's next for tcpform
Expanding the template registry so teams can share and verify protocol building blocks, deeper eBPF and OpenTelemetry correlation for production debugging, and more built-in protocol templates such as MQTT and gRPC contributed by the community.
Log in or sign up for Devpost to join the conversation.