Developer Guide

This part is for people who change the code. It describes the Etemenanki workspace (the kernel crates and the standalone app) and katana, down to individual state machines, buffers and locks.

The code base at a glance

Crate or program	Role
etemenanki-concepts	The sans-I/O proxy model: server cores, client codecs, the per-connection runtimes, links and connectors. It contains no protocol code.
etemenanki-environment	Host-side networking: TCP and UDP dialers (plus an optional QUIC dialer) sharing one socket policy, and the route model.
etemenanki-protocols	Every protocol and transport: SOCKS, HTTP, Shadowsocks, Trojan, VLESS, VMess, Hysteria 2, WireGuard and TUN; TCP, TLS, WebSocket and gRPC; mux.cool and XUDP; DNS; sniffing.
etemenanki-app	The standalone proxy: configuration, inbound and outbound construction, router composition, generations and hot reload.
katana	The panel node agent, built on the first three crates: panel clients, node lifecycle, admission, traffic accounting, rate limiting and audit.

Dependencies point one way, from the programs down to the concepts:

flowchart BT
  concepts["etemenanki-concepts"]
  environment["etemenanki-environment"]
  protocols["etemenanki-protocols"]
  app["etemenanki-app"]
  katana["katana"]
  environment --> concepts
  protocols --> environment
  app --> protocols
  katana --> protocols

Each arrow is a direct dependency; every crate also uses the ones further down directly. katana is a separate repository and takes the three library crates from a registry at a pinned version; the app is built together with them in one workspace.

Map of this guide

ArchitectureThe workspace, the life of one connection from accept to close, and the design principles.

conceptsServer cores, the per-connection runtime, client codecs, links and net types.

environmentDialers, the socket policy and the route model.

protocolsShared foundations, sniffing, DNS, transports, mux and every protocol.

appFrom TOML to a running pipeline, serving, outbounds, reload and limits.

katanaPanel clients, the node manager, admission, accounting and metering.

TestingHow the code is tested and what a change needs.

ContributingValidation gates, review rules and the release order.

How the pages are written

Every page follows the same outline, as far as its subject allows:

1. Responsibilities: what the component does, and what it deliberately leaves to others.
2. Key types: the traits, structs and functions you will meet in the code, with their signatures.
3. Data flow: how bytes, events or requests move through it, usually drawn as a Mermaid diagram.
4. Invariants: what must always hold, and which mechanism guarantees it.
5. Failure paths: errors, cancellation and shutdown.
6. Limits: buffer sizes, timeouts and caps.
7. Tests: which tests pin the behaviour down.

Source references

The repositories are private, so these pages do not link into them. Code is named by repository-relative path and symbol, for example concepts/src/core.rs → ProxyCoreDecode. Line numbers are avoided because they move.

Under each page title, Source files lists the files the page describes and the revision they were last checked against. When any of those files changes after that revision, the page is re-checked.