Proxyfan networking.instructions.md

Networking and proxy-pipeline rules

The proxy engine is the highest-throughput, lowest-latency surface in the codebase. Bugs here corrupt user traffic, leak memory at line rate, or stall every captured connection. Every change in Framework.Networking or Domain.Proxy is reviewed against this file.

Performance budget

The end-to-end overhead added by the proxy must remain under 1 ms per request (excluding rule evaluation and throttling). To stay inside that budget:

• Build on System.IO.Pipelines for byte-stream I/O. Do not allocate a per-frame byte[]; use ArrayPool<byte>.Shared or the pipe's own buffer.
• Use Span<T> / ReadOnlySpan<T> for parsing. Avoid materialising a string from a header line until the rule pipeline actually inspects it.
• Use ValueTask for hot async paths that frequently complete synchronously (header parsing, frame reads, throttle waits).
• Pool large buffers (MemoryPool<byte>) for body relay; never allocate the full response body up front.

CancellationToken propagation

• Every async method in Framework.Networking accepts a CancellationToken as the last parameter (ATXTA008). The token from the proxy listener flows all the way down to socket reads, TLS handshakes, and HPACK parsing.
• Never create a fresh CancellationToken inside a handler — link to the caller's token with CancellationTokenSource.CreateLinkedTokenSource if a local timeout is needed.
• Tokens never carry default values (ATXCS005).

Sync-over-async is banned

.Result, .Wait(), .GetAwaiter().GetResult() on a Task are forbidden in the proxy pipeline. They will deadlock under the synchronisation context of the connection dispatcher and stall every captured connection on that listener.

async void is banned

The only legitimate async void is an Avalonia event handler in Presentation code-behind. Networking code is never UI code; use async Task and propagate exceptions through the result type.

Connection dispatch