Architecture¶

The complete current architecture is documented in the main repository ARCHITECTURE.md.

The ownership problem¶

Congestion control belongs to the kernel that owns a TCP socket. In a constrained VPS/container, the tenant may be unable to load BBR or change the provider-controlled kernel's TCP policy.

Changing nginx or another application cannot change the congestion control of a public socket still owned by that outer kernel.

tcpcc therefore moves ownership of the public TCP endpoint into a hosted upstream Linux network stack.

Two TCP connections¶

The most important architectural fact is that tcpcc has two distinct TCP legs.

                         public TCP connection

remote client
    |
    | packets to public LISTEN endpoint
    v
outer host/container
    |
    | PREROUTING DNAT + conntrack
    v
TUN
    |
    | raw IPv4 / IPv6 packets
    v
hosted upstream Linux
    |
    | public TCP listener
    | TCP_CONGESTION = --cc
    v
accepted byte stream
    |
    | bridge
    v
ordinary host socket
    |
    v
127.0.0.1 backend

                         local backend TCP connection

The public connection terminates in hosted Linux. Accepted sockets inherit the listener's ordinary upstream Linux TCP state.

The bridge then opens a separate outer-host TCP socket to the loopback backend. The backend connection is not the public connection, and --cc does not redefine the outer host's loopback TCP policy.

Runtime components¶

Native supervisor¶

The native C supervisor owns host lifecycle:

• parse CLI/TOML configuration;
• check prerequisites;
• create/configure one nonpersistent TUN queue;
• install exact-match DNAT resources;
• start the hosted Linux executable;
• pass the TUN fd and control channel;
• configure the hosted L3 endpoint/listeners;
• set and read back TCP_CONGESTION;
• handle shutdown and resource cleanup.

Hosted Linux¶

The hosted kernel owns the Internet-facing TCP state machine and runs the upstream networking code for:

• CUBIC / BBR;
• delivery-rate sampling;
• loss recovery;
• fq pacing;
• TCP socket lifecycle.

Byte-stream bridge¶

After hosted Linux accepts the public connection, tcpcc relays application bytes to a separate 127.0.0.1 connection.

Design boundary¶

tcpcc deliberately avoids reimplementing BBR, CUBIC, recovery, or fq. Project-specific code is concentrated around the userspace architecture, host runtime, control API, packet device, and compatibility boundary.