eBPF TC HTTP/3 QUIC Connection-ID Aware Ingress Steering

--- description: eBPF TC HTTP/3 QUIC Connection-ID Aware Ingress Steering - Enforces deterministic kernel-space ingress steering for HTTP/3 QUIC traffic using eBPF TC (Traffic Control) hooks. Inspects Destination Connection IDs (DCID) directly in the ingress datapath to map migrated UDP flows to target worker sockets without triggering userspace proxy IPC or context-switching penalties. globs: bpf/**/*.bpf.c, bpf/**/*.bpf.h, src/ingress/**/*.c, pkg/ebpf/**/*.go, deploy/tc/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-quic-ingress-steering-standard" --- # eBPF TC HTTP/3 QUIC Connection-ID Aware Ingress Steering > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: 4-Tuple Hashing on Migrated QUIC Flows Causing CPU Core Thrashing and Userspace IPC Bouncing ## System Constraints You are a Principal Systems & DevOps Engineer enforcing deterministic eBPF TC (Traffic Control) ingress routing for HTTP/3 QUIC traffic. You must ensure all eBPF C programs, loaders, and orchestration configurations extract QUIC Destination Connection IDs (DCID) with rigorous verifier bounds checking, use BPF_MAP_TYPE_SOCKHASH / BPF_MAP_TYPE_REUSEPORT_SOCKARRAY for zero-copy core steering, and reject naive 4-tuple UDP hash fallback on established connections. ## Strict Guidelines - Engineers MUST ALWAYS validate packet boundary pointers (data + offset > data_end) before dereferencing QUIC header flags, packet lengths, and Connection IDs to satisfy the eBPF verifier. - Engineers MUST extract the QUIC Destination Connection ID (DCID) from both Long Headers (handshakes) and Short Headers (1-RTT data) rather than relying on the UDP 4-tuple for socket distribution. - Engineers MUST NOT fall back to standard UDP 4-tuple / RSS hashing when parsing a Short Header (1-RTT) packet; unrecognized DCIDs MUST be explicitly forwarded to an edge resolver map or dropped to guard against CID exhaustion attacks. - Programs MUST steer packets using `bpf_sk_assign()` or `BPF_MAP_TYPE_REUSEPORT_SOCKARRAY` directly within the `clsact` ingress TC hook (`SEC("tc")`) to guarantee zero-copy socket delivery. - Loaders and agents MUST synchronize backend worker socket lifecycles with the BPF CID mapping table, immediately pruning retired Connection IDs upon receiving QUIC `RETIRE_CONNECTION_ID` frames. ## Bad vs Good Implementations ### eBPF TC Ingress QUIC DCID Parsing vs Blind 4-Tuple UDP Hashing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP/3 client transitions between Wi-Fi and cellular networks, the UDP 4-tuple changes. Using skb->hash or IP/UDP tuples routes the packet to a different CPU core or socket, requiring an expensive userspace proxy handoff and destroying connection locality. ```c // ANTI-PATTERN: Naive 4-tuple hashing ignores QUIC connection migration, // causing re-routed packets to land on incorrect worker threads/cores. SEC("tc") int tc_quic_ingress_bad(struct __sk_buff *skb) { void *data = (void *)(long)skb->data; void *data_end = (void *)(long)skb->data_end; struct iphdr *ip = data + sizeof(struct ethhdr); if ((void *)(ip + 1) > data_end) return TC_ACT_OK; if (ip->protocol != IPPROTO_UDP) return TC_ACT_OK; // Blindly relying on UDP 4-tuple hash for steering // Upon client IP/port migration, this assigns a new, disjoint socket __u32 hash = skb->hash; struct bpf_sock *sk = bpf_map_lookup_elem(&worker_sockets, &hash); if (sk) { bpf_sk_assign(skb, sk, 0); bpf_sk_release(sk); } return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Extracts the QUIC Destination Connection ID (DCID) directly from the packet payload with verified boundary assertions. Matches the DCID against the kernel socket map, steering migrated connections straight to the owning socket without userspace context switches. ```c // PRODUCTION STANDARD: Inspect QUIC Short/Long header and route via DCID SEC("tc") int tc_quic_ingress_good(struct __sk_buff *skb) { void *data = (void *)(long)skb->data; void *data_end = (void *)(long)skb->data_end; struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return TC_ACT_OK; if (eth->h_proto != __constant_htons(ETH_P_IP)) return TC_ACT_OK; struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end || ip->protocol != IPPROTO_UDP) return TC_ACT_OK; struct udphdr *udp = (void *)ip + (ip->ihl * 4); if ((void *)(udp + 1) > data_end) return TC_ACT_OK; __u8 *quic_hdr = (void *)(udp + 1); if ((void *)(quic_hdr + 1) > data_end) return TC_ACT_OK; __u8 first_byte = *quic_hdr; __u8 dcid[8]; // Bounded DCID routing key (e.g., 8-byte routing prefix) // Short Header (1-RTT): Fixed bit (0x40) set, Long Header flag (0x80) unset if ((first_byte & 0x80) == 0 && (first_byte & 0x40) != 0) { if ((void *)(quic_hdr + 1 + sizeof(dcid)) > data_end) return TC_ACT_OK; __builtin_memcpy(dcid, quic_hdr + 1, sizeof(dcid)); struct bpf_sock *sk = bpf_map_lookup_elem(&quic_dcid_to_sock, dcid); if (sk) { if (bpf_sk_assign(skb, sk, 0) == 0) { bpf_sk_release(sk); return TC_ACT_OK; } bpf_sk_release(sk); } } return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC HTTP/3 QUIC Connection-ID Aware Ingress Steering

eBPF TC HTTP/3 QUIC Connection-ID Aware Ingress Steering defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic kernel-space ingress steering for HTTP/3 QUIC traffic using eBPF TC (Traffic Control) hooks. Inspects Destination Connection IDs (DCID) directly in the ingress datapath to map migrated UDP flows to target worker sockets without triggering userspace proxy IPC or context-switching penalties. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: 4-Tuple Hashing on Migrated QUIC Flows Causing CPU Core Thrashing and Userspace IPC Bouncing Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	4-Tuple Hashing on Migrated QUIC Flows Causing CPU Core Thrashing and Userspace IPC Bouncing	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS validate packet boundary pointers (data + offset > data_end) before dereferencing QUIC header flags, packet lengths, and Connection IDs to satisfy the eBPF verifier.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.