WaterWall gives you nodes and tunnels instead of a fixed proxy protocol

A networking core, with the protocol left to you

WaterWall is described as a simple networking core for tunneling or direct client and server connections. The key phrase in the overview is the last one: the core provides the connection, and the protocol on top of it is yours to define.

The stated design is built on high-performance, fully customizable nodes, and the claim is that this lets you create a wide range of protocols without writing low-level implementation code. The part you write is the logic of your protocol; the part the library handles is the socket handling, the node lifecycle, and the plumbing between them.

The overview also contains an unusually candid aside, in parentheses, that it might make things feel more complex depending on how you use it. That is worth taking seriously when you are choosing a networking library, because it tells you the author knows the abstraction does not pay off in every case.

The framing of the problem is what distinguishes this from a proxy. A proxy implements a protocol that clients already know how to speak. WaterWall is for the case where you have a protocol that no client speaks yet, or where you need the connection semantics to be yours, and what you want from a library is the boring half of the work.

The audience is therefore a systems programmer, not an administrator. The project is written in C, which fits: a networking core that sits under your own protocol wants to be close to the socket.

The build is two commands and a CMake preset

The build instructions are unusually complete for a project of this kind, and they assume a fresh machine.

On a fresh Ubuntu, or most Debian-based systems, the documented first step installs the toolchain and a modern CMake:

apt-get purge -y cmake; apt-get update; apt-get install -y snapd build-essential ninja-build ccache; snap install cmake --classic

The purge of the distribution cmake matters. The documentation explains that the first command ensures a modern version of CMake via snap, which is required for the preset-based build system. So the project depends on CMake presets, and the CMakePresets.json file at the repository root is where those are defined.

The second command does the fetch and the compile in one line:

git clone https://github.com/radkesvat/WaterWall && cd WaterWall && cmake --preset linux-gcc-x64 && cmake --build --preset linux-gcc-x64

The configure step selects a preset named linux-gcc-x64 and the build step uses the same preset name. The presence of ccache in the dependency list tells you the author expects rebuilds during development, and Ninja as the generator is the modern alternative to Make for CMake projects.

The build tools in the repository root are the C toolchain version of the usual set. There is a .clang-format, a .clang-tidy, and a .clangd, which is the trio that gives you formatting, linting and IDE integration all reading the same configuration. There is also an AGENTS.md file, which typically documents conventions for automated contributors, and a .gitattributes file.

One thing the build does not do is install anything for you. There is no package step described, no systemd unit, no configuration file format and no release artefact. You get a compiled binary and a set of nodes you have to wire up yourself.

The core, the tunnels and the ww binary

The top-level repository entries are short and they describe the architecture directly: core/, tunnels/, ww/, tests/, CMakeLists.txt, CMakePresets.json and LICENSE.txt.

The three source directories map onto three roles. core/ is the reusable part, the networking core that everything else is built on. tunnels/ holds the tunnel implementations, the things that actually move bytes for a given purpose. ww/ is the executable, the thing you run.

That structure is the whole point of the project in one listing. A tunnel is composed from nodes, and the nodes come from the core, and the program that wires them together is ww. If you are writing your own protocol, your work lives in tunnels/ and possibly in new node types, and the core is the part you do not rewrite.

The presence of a tests/ directory at the top level tells you the project is tested as a whole rather than only per tunnel. That matters more for a networking core than for most libraries, because the bugs you care about are in the interactions between nodes rather than in any single node.

The per-tunnel documentation convention is described in the readme, and it is unusual enough to be worth understanding. Each tunnel also includes a description.md file, and changes to those files are reflected in the published docs. The website is the recommended documentation source for everyone.

So the tunnel descriptions live with the code, get edited as part of a change, and are then published to the site. That is a better arrangement than writing documentation separately and letting it drift, and it explains why the readme itself is thin.

Documentation that lives in a second repository

The readme is short, and the reason is stated at the top of the getting started section: to begin, read the documentation at the WaterWall-Docs site.

Two facts about that documentation are worth recording. It is complete in both English and Persian, and both languages are maintained as first-class documentation. For a project by a Persian developer with an international audience, committing to two equally maintained translations is a real cost and a real signal about the project's priorities.

The second fact is that the website is the recommended source, and that changes to the per-tunnel description.md files are reflected in the published docs. The practical consequence for an adopter is that the repository you clone does not contain the documentation you need, and the documentation lives behind a website that could in principle change independently of the code.

The readme also carries a link to a Telegram group for questions, networking, programming in general, and suggestions, and thanks for support. Both of those are commented out in the current readme, so the visible version of the file does not point at them, but they show what the project's community channel was meant to be.

For someone evaluating the project, the practical instruction is to read the docs site before writing any code, and to expect to keep it open while you work. The library is small enough to read, but the composition model is the part that has to be understood, and the composition model is documented outside the source tree.

MPL-2.0, and what that means for a networking core

The licence is MPL-2.0, with the LICENSE.txt file at the repository root, and it is a deliberate choice for this kind of project.

MPL-2.0 is a file-level copyleft licence. If you modify a file of the library, your modified version of that file has to be made available under the same licence. If you merely link against the library, your own files stay under whatever licence you want. For a C library where you might vendor a node implementation or patch the core, that is a workable middle ground, and it is more permissive than the GPL for a commercial product that links the library without changing it.

The practical question to ask is whether your work will touch files in the library. If your protocol is entirely new code in your own tunnels/ directory, linking is the only relationship and MPL-2.0 asks little of you. If you plan to modify core/ directly and keep the changes private, the licence is in the way and you would need to publish the modified files.

This is not legal advice, only a note on the shape of the obligation, because the interesting case is the middle one where a company links the library and also contributes patches upstream. Contributing a patch upstream is the straightforward answer there.

The licence is also why the version numbers look unusual. The releases are v1.46.96, v1.46.94 and v1.46.93, with the last push on 2026-10-20 and the most recent tag on 2026-10-04. A patch number in the high nineties under a 1.46 minor version is what a project with a lot of active small fixes looks like.

Where this is the wrong tool

The clearest wrong-tool case is a request for a working proxy.

If what you need is a SOCKS5 or HTTP proxy that clients already know how to configure, WaterWall is the wrong level of abstraction. The design assumes you are defining a protocol and composing nodes to implement it, and the documentation points you at that work rather than handing you a configured proxy. A conventional proxy server is a solved problem with existing, well-documented implementations, and choosing a protocol framework for it adds a layer without removing one.

The second wrong-tool case is a project that needs the whole thing to be self-contained in one repository. You would be reading the documentation on a website, and the per-tunnel description files that the publish process consumes are not in the tree you clone.

The third is anyone who finds the composability itself unwelcome. The author's own aside says it might make things feel more complex depending on how you use it, and node-based protocol design is genuinely a different way of thinking from writing a server that handles connections directly. If you are more comfortable with an event loop and a handler function, the abstraction will cost you rather than save you.

What the project does offer, and what the CI configuration backs, is a serious piece of infrastructure. The repository carries a continuous integration workflow and a separate Clang Static Analyzer workflow, and the C toolchain configuration in .clang-format, .clang-tidy and .clangd shows a project where the code is expected to be held to a consistent standard. That is the profile of a project whose value is in the foundation it gives you, and whose cost is that you must supply the protocol.

Editorial conclusion

WaterWall suits a C developer who needs a transport layer for a protocol of their own design and wants node composition rather than a fixed proxy implementation, and who is prepared to read a separate documentation site. It is the wrong choice if you want a ready-to-use SOCKS or HTTP proxy, because the documentation explicitly points you at writing the protocol yourself, and the wrong choice if you want the whole thing to be self-documenting, since the per-tunnel description.md files live outside the repository you clone. Before adopting it, read the WaterWall-Docs site in full, run the two-command CMake preset build on a scratch machine to confirm it compiles on your distribution, and pick a single tunnel to implement first, because the author notes the design can feel more complex depending on how you use it.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. radkesvat/WaterWall on GitHub
4. README
5. Releases