# Edge & Traffic Policy

> This document describes the authority boundaries at the network edge: where routing and policy decisions are made, where congestion is enforced, and what happens when an adaptive component fails.

Status: active · Kind: reference · Last verified: 2026-07-20 · Date: 2025-12-15

This document describes the authority boundaries at the network edge: where
routing and policy decisions are made, where congestion is enforced, and what
happens when an adaptive component fails.

The goal is consistent latency and predictable behavior under load, not maximum
aggregate throughput.

> Design principles: see **[Lab Philosophy](/homelab/philosophy)**.

---

## Authority Model

The edge is intentionally split across two roles:

```text
LAN → router classifier / firewall / NAT / route selection → inline bridge shaper / CAKE → WAN
```

The router owns:

- WAN termination and route selection
- VLAN gateways and inter-VLAN policy
- firewalling and NAT
- host, device, service, and connection-aware traffic classification
- normalized DSCP marking and explicit steering eligibility

The inline bridge shaper owns:

- rejection of untrusted carrier markings
- restoration of locally assigned classes on reply traffic
- CAKE tin scheduling, active queue management, and shaping rates
- adaptive rate control at each WAN bottleneck

This is not duplicate QoS on two systems. The router decides traffic intent
while the bridge enforces that intent at the physical bottleneck.

---

## WAN Routing and Failover

Two independent WAN circuits provide a preferred path and a lower-capacity
alternate path. Normal routing preference and hard-outage failover remain
router-side responsibilities.

Congestion steering is separate from failover and separate from queue priority.
When enabled, steering is bounded to explicitly eligible **new** connections.
Established connections retain their original route and NAT affinity, while
bulk traffic remains on its normal path.

Adaptive congestion state is not sufficient authority to replace whole-network
routing. Active route mutation remains guarded while the existing outage
mechanism owns default-route failover. A degraded primary circuit must not, by
itself, move the entire network onto the alternate circuit.

---

## Traffic Classification Contract

The router emits a small normalized set of standards-based classes:

| Intent | Marking | CAKE treatment |
|---|---|---|
| Realtime or critical | EF | Voice |
| Interactive or video | AF31 | Video |
| Normal | CS0 | Best effort |
| Sustained or scavenger | CS1 | Bulk |

The bridge trusts those markings only on the router-facing side. Carrier-facing
traffic is washed before locally learned class state is restored, preventing an
upstream network from selecting privileged CAKE tins.

Unclassified traffic stays best effort. Fast-path behavior must not bypass the
classification boundary unless equivalence has been mechanically demonstrated.

---

## Trust Zones and Firewall Posture

The router enforces explicit trust boundaries:

- inbound WAN traffic is denied unless intentionally published
- management traffic is tightly scoped and has no general WAN requirement
- trusted clients and servers receive normal WAN access with controlled
  inter-zone reachability
- IoT WAN access is default-deny with explicit per-device exceptions
- camera devices have no WAN access and may reach only the required recorder
  path

VLANs express trust boundaries. They do not move routing, firewalling, or
classification into the switching fabric.

---

## Failure and Safety Boundaries

The design prefers loss of optimization over uncontrolled mutation:

- loss of adaptive rate control leaves a known routing path rather than granting
  it route ownership
- the bridge watchdog can place a still-powered inline pair into bypass during
  software failure, preserving raw connectivity while removing shaping
- internal powered bypass does not protect against complete shaper-host power
  loss
- loss of classification leaves unknown traffic in best effort rather than a
  privileged class
- steering changes affect new eligible connections only and must remain
  observable and reversible

These safeguards reduce blast radius; they do not make the edge highly
available. The router, switching core, and physical circuits remain explicit
failure domains.

---

## Operational Invariants

- Queue priority and WAN steering remain separate decisions.
- The router remains authoritative for identity-aware policy and routing.
- The bridge remains authoritative for bottleneck enforcement.
- Switches transport VLAN and DSCP state without inventing policy.
- Dynamic control must expose health and retained state and must fail toward a
  stable configuration.
- Network mutation requires a separate attended rollout and rollback plan.

---

## Related Documentation

- [Switching & VLAN Fabric](/homelab/network/switching-and-vlan-fabric) — Layer 2 transport and QoS contract preservation
- [wanctl Control Plane](/homelab/network/wanctl-control-plane) — Adaptive rate control and bounded steering
- [Network Monitoring Intent](/homelab/network/monitoring-and-observability) — Evidence and failure questions