DEV Community: pathvector-dev

Which router wins the segment? Read the election, not the docs

pathvector-dev — Thu, 06 Aug 2026 00:00:09 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-ospf-03/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. Every module points at one real Python file and walks its control flow. The source lives at pathvector-studio/protocol-in-code. If you're earlier in the journey and want to touch the protocols first — capture packets, poke at daemons, break things on purpose — start with the companion Protocol Lab series instead, then come back here.

The question

If several routers share one broadcast segment, how does the code pick DR and BDR?

Hold onto that as you read. Not "what is a DR" — you can get that from any certification slide deck. The question is how a deterministic function turns a bag of interface states into exactly one designated router and at most one backup, with no coordination beyond what every router can already see.

The file we're reading is src/protocol_in_code/ospf/dr_election.py. It is under sixty lines. Almost all of the interesting behavior lives in two of them.

Where this comes from

Session 02 left us with a loose end. On a broadcast segment, some neighbors reach 2-Way and then simply stop — they never progress to full adjacency. That looks like a bug until you know what comes next. Those routers stopped because they aren't the DR or the BDR, and on a shared segment you only form full adjacencies with those two. So the "stuck at 2-Way" observation from last session is really a pointer to this session's branch: something has to decide who the DR and BDR are, and everyone else settles into 2-Way on purpose.

That's the shape worth carrying with you: an election exists to collapse an N×N mesh of adjacencies into a hub. Without it, ten routers on one Ethernet segment would form 45 adjacencies and flood 45 copies of everything.

Read it like code

The module gives a read order, and it's the right one: the candidate shape first, then the picker, then the election that uses both.

1. What a candidate is

@dataclass(frozen=True)
class InterfaceCandidate:
    router_id: str
    priority: int
    declared_dr: bool = False
    declared_bdr: bool = False

Four fields, and each one is doing a distinct job.

priority is the operator's thumb on the scale. router_id is the tie-break of last resort — it's guaranteed unique on the segment, so it's guaranteed to produce a total order. And then there's the interesting pair: declared_dr and declared_bdr. These are not "should this router be DR." They're "this router is currently claiming to be DR" — a self-report that arrives in the neighbor's Hello packet. That distinction is the whole reason OSPF elections are sticky rather than churning every time a better router shows up.

Note that the dataclass is frozen=True. Candidates are inputs to a pure function, not mutable state being edited in place. The election reads; it does not write.

2. The comparison

def _router_id_key(router_id: str) -> tuple[int, ...]:
    return tuple(int(part) for part in router_id.split("."))


def _pick_highest(candidates: list[InterfaceCandidate]) -> InterfaceCandidate | None:
    if not candidates:
        return None
    return max(candidates, key=lambda candidate: (candidate.priority, _router_id_key(candidate.router_id)))

The entire ranking rule of this election is one tuple: (priority, router_id_key). Python's tuple comparison does the rest — compare priority first, and only if priority ties does router_id get consulted. This is the "why does router ID still matter after priority" answer, sitting right there in the key function.

_router_id_key deserves a second look, because it's the kind of thing that's easy to get wrong and never notice. A router ID looks like an IPv4 address, but it's a string. Compare "10.0.0.2" and "10.0.0.10" as strings and "10.0.0.2" wins, because "2" > "1" lexicographically. Splitting on . and mapping to int gives you (10, 0, 0, 2) vs (10, 0, 0, 10), and now the numeric order is correct. The election is deterministic either way — every router would agree on the wrong answer consistently — but it wouldn't match what a real OSPF implementation picks.

Note: The if not candidates: return None guard is not decoration. max() on an empty sequence raises ValueError, and an empty candidate list is a completely legitimate state — a segment where every router is configured with priority 0. The None return is what lets the caller express "no DR on this segment" as a value rather than an exception.

3. The election

def elect_dr_bdr(candidates: tuple[InterfaceCandidate, ...]) -> ElectionResult:
    eligible = [candidate for candidate in candidates if candidate.priority > 0]
    declared_dr = [candidate for candidate in eligible if candidate.declared_dr]
    designated = _pick_highest(declared_dr) or _pick_highest(eligible)

    remaining = [candidate for candidate in eligible if designated is None or candidate.router_id != designated.router_id]
    declared_bdr = [candidate for candidate in remaining if candidate.declared_bdr]
    backup = _pick_highest(declared_bdr) or _pick_highest(remaining)
    # ...

Read it as three filters and two picks.

The eligibility filter. priority > 0 is the first line, and it's absolute. A router with priority 0 doesn't lose the election — it never enters it. It's gone from eligible, which means it's gone from declared_dr, gone from remaining, gone from declared_bdr, and gone from eligible_routers in the result. Priority 0 is not "lowest priority," it's opt-out. If you've ever wondered why the OSPF docs describe priority 0 as "ineligible" rather than "last in line," this list comprehension is the reason: there is no code path that can reach a zero-priority router after line one.

The declared-role preference. This is the line to slow down on:

    designated = _pick_highest(declared_dr) or _pick_highest(eligible)

or short-circuits on truthiness. If anyone on the segment is already claiming to be DR, declared_dr is non-empty, _pick_highest returns a candidate, and the second _pick_highest(eligible) never runs. The general field is only consulted when nobody is already claiming the role.

That single or is the seed of non-preemption. A brand-new router with priority 255 boots onto a segment where a priority-1 router is already declaring itself DR. It does not win. It isn't in declared_dr, so it's never compared against the incumbent at all. Priority only decides who becomes DR, not who stays DR — and the code makes that structural rather than conditional. There's no if incumbent_exists branch; the preference falls out of which list gets passed to max() first.

The exclusion, then the same pattern again. BDR selection is the DR logic run a second time over a smaller set:

    remaining = [candidate for candidate in eligible if designated is None or candidate.router_id != designated.router_id]

The filter excludes the winner by router ID, not by object identity. Since router_id is unique on a segment, that's the correct key — and it's more robust than is, which would break the moment a candidate was reconstructed rather than passed through. The designated is None clause keeps remaining equal to eligible when there was no DR to exclude, though in practice if _pick_highest(eligible) returned None then eligible was empty and remaining will be too.

Then declared_bdr filtered from remaining, _pick_highest(...) or _pick_highest(...) again. Same shape, one level down. Note what this doesn't do: the current DR is excluded from BDR consideration, but there's no promotion logic — if the DR disappears, this function just re-runs and the old BDR, still carrying declared_bdr=True, wins the declared_dr check... except it doesn't, because it declared BDR, not DR. Sit with that one; it's a real gap between this model and the RFC, and we'll come back to it.

4. The result

    return ElectionResult(
        designated_router=designated.router_id if designated else None,
        backup_designated_router=backup.router_id if backup else None,
        eligible_routers=tuple(candidate.router_id for candidate in sorted(eligible, key=lambda item: _router_id_key(item.router_id))),
    )

Two Optional[str] slots and a sorted tuple. None for designated_router is a first-class outcome, not an error — an all-priority-0 segment genuinely has no DR.

eligible_routers is sorted by the same _router_id_key, which makes the result stable and comparable across runs regardless of the input ordering. That's a small thing that matters a lot: an election whose output representation depends on input order is an election you can't diff, snapshot, or test reliably.

Same shape, different protocol

Once you've read this election as filter → prefer-incumbent → max → tie-break, you start seeing it everywhere.

The _pick_highest(declared) or _pick_highest(all) pattern — prefer whoever is already holding the role, fall back to the best available — is structurally the same as a BGP route-selection tie-break chain, where the oldest established path wins among otherwise-equal candidates specifically to stop routes from flapping. Different protocol, different fields, identical motivation: stability is worth more than optimality once you're already converged.

And the priority == 0 filter is the same move as a DNS nameserver marked unreachable, or a TCP connection with cwnd collapsed to the point of exclusion — a participant removing itself from consideration entirely rather than competing badly. Filtering before ranking is cheaper and safer than ranking with a special-case loser.

Run it

The walkthrough is executable. From the repo root:

PYTHONPATH=src python3 examples/ospf/session_03_walkthrough.py

Read the script at examples/ospf/session_03_walkthrough.py, then change the inputs. The instructive experiments:

Build a candidate set where the highest-priority router has declared_dr=False and a low-priority router has declared_dr=True. Confirm the low-priority router wins.
Set every priority to 0 and check what comes back in all three fields of ElectionResult.
Give two routers the same priority and different router IDs, one of them 10.0.0.9 and the other 10.0.0.10. Verify which wins, and convince yourself it's _router_id_key doing it.

Toy model boundary

This is a teaching model, and being clear about the gap is the point.

It's a snapshot, not a state machine. The real election in RFC 2328 §9.4 runs as an eight-step algorithm inside the interface state machine, and it runs twice — the second pass exists precisely so that a router that just made itself DR can then correctly select a BDR from the updated set. elect_dr_bdr() is a single pure pass over immutable inputs. There is no re-invocation, no convergence loop.

Non-preemption is only half-modeled. The declared_dr preference captures the spirit of non-preemption, but the real rules are more specific: a router that is already DR does not give up the role, and a router that becomes BDR is promoted to DR when the DR fails. This model has no promotion path — a former BDR carries declared_bdr=True, which does nothing for it in the declared_dr filter. Re-running the election after a DR failure gives you a plausible answer, but not the RFC's answer.

No Wait Timer. Real OSPF interfaces sit in Waiting state for RouterDeadInterval before electing anything, specifically to avoid a router electing itself DR just because it booted first and hasn't heard anyone else yet. There's no time in this model at all.

No Hello packet, no priority advertisement. InterfaceCandidate is handed to us pre-assembled. In reality every field here is learned from Hello packets on the segment, and the declared_dr/declared_bdr values are literally the Designated Router and Backup Designated Router fields of those packets — which means they can be stale, inconsistent between routers, or briefly contradictory during convergence. This model assumes every router sees the same candidate tuple.

No interface types. DR/BDR election applies to broadcast and NBMA networks. Point-to-point links don't elect anything. The model has no concept of network type, so it will happily elect a DR for a segment that shouldn't have one.

Check yourself

Don't answer these from memory — answer them by pointing at a line in dr_election.py.

A router configured with priority 0 sends a Hello with declared_dr=True. Trace it through elect_dr_bdr(): at which exact line does it stop mattering, and what does eligible_routers contain?
Two routers on the segment both have declared_dr=True — a genuinely possible state during convergence. Which one becomes DR, and which comparison in _pick_highest decides it? Can the loser end up as BDR?
The current DR fails and drops off the segment. You re-run elect_dr_bdr() with the surviving candidates, one of which has declared_bdr=True. Does that router become the new DR? Read the filters and follow the or, then say what the RFC would have done instead.

Done when you can explain, without looking, why priority 0 disappears from the candidate set entirely rather than losing, and why router_id still decides the outcome after priority has had its say.

A Hello does not make a neighbor Full — the code says so in two stages

pathvector-dev — Wed, 05 Aug 2026 00:00:11 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-ospf-02/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. The source lives at github.com/pathvector-studio/protocol-in-code, and every article quotes directly from a small Python module you can read end to end in one sitting. If you're earlier on the path and want to do things with protocols before dissecting them, start with the hands-on companion series, Protocol Lab.

The question

How does a received Hello turn into Init, 2-Way, or Full?

That question contains a trap, and the trap is the whole point of this session. Read enough vendor documentation and you absorb a mental model where a Hello packet arrives, some negotiation happens, and the neighbor "comes up" — one continuous process with Full at the end of it. Then you hit a network where two routers sit at 2-Way forever and it looks like a failure, or a pair stuck in ExStart where Hellos are clearly flowing fine.

The code we're reading this session is src/protocol_in_code/ospf/neighbor.py. It answers the question by refusing to answer it as asked: a Hello can produce Init, 2-Way, or ExStart, and that's the end of what a Hello can do. Full comes from somewhere else entirely.

Session 01 left us with two booleans: whether a Hello is acceptable, and whether the peer already lists us in its neighbor set. This session picks up exactly there, turns those booleans into a state, and then — separately — brings in the database-exchange inputs.

Read the file in this order: NeighborState, then AdjacencyInputs, then advance_neighbor_state().

The state space, and what it's hiding

class NeighborState(str, Enum):
    DOWN = "Down"
    INIT = "Init"
    TWO_WAY = "2-Way"
    EXSTART = "ExStart"
    EXCHANGE = "Exchange"
    LOADING = "Loading"
    FULL = "Full"

Seven states, in the order OSPF traverses them. Nothing surprising yet — but notice there's a seam in this list even though the enum doesn't mark it. DOWN, INIT, and TWO_WAY are outcomes of looking at Hello packets. EXCHANGE, LOADING, and FULL are outcomes of exchanging link-state databases. EXSTART is the hinge: it's where the Hello phase hands off to the database phase.

The input struct makes that seam explicit:

@dataclass(frozen=True)
class AdjacencyInputs:
    hello_accepted: bool
    saw_self: bool
    should_form_full_adjacency: bool
    database_description_ok: bool = True
    request_list_empty: bool = True
    retransmissions_cleared: bool = True

Six booleans, and they split cleanly into two groups. The first three come from Hello processing. The last three come from the database exchange, and they all default to True — which is a small design decision worth pausing on, because it means an AdjacencyInputs constructed with only the Hello fields describes a neighbor whose database exchange has already gone perfectly. That's a convenience for tests, not a claim about reality; the helper that builds inputs from a real Hello result flips those defaults the other way:

def inputs_from_hello(
    hello: HelloCheckResult,
    *,
    should_form_full_adjacency: bool,
    database_description_ok: bool = False,
    request_list_empty: bool = False,
    retransmissions_cleared: bool = False,
) -> AdjacencyInputs:
    # ...

Same three fields, defaults inverted. When all you have is a Hello, you have no evidence about the database at all, so the honest default is "not yet."

Note: should_form_full_adjacency is an input, not a computed result. In real OSPF it's the output of DR/BDR election on a broadcast segment, plus network-type rules — a router on an Ethernet segment forms full adjacencies with the DR and BDR and stops at 2-Way with everyone else. This model takes that decision as given so the state machine stays readable. Where that boolean comes from is its own problem; what it does is what we're reading here.

Stage one: what a Hello can decide

advance_on_hello() is a chain of guard clauses, and reading it top to bottom is reading a priority order:

def advance_on_hello(
    current: NeighborState,
    hello_accepted: bool,
    saw_self: bool,
    should_form_full_adjacency: bool,
) -> NeighborState:
    if not hello_accepted:
        return NeighborState.DOWN

    if not saw_self:
        return NeighborState.INIT

    if not should_form_full_adjacency:
        return NeighborState.TWO_WAY

    if current in {NeighborState.DOWN, NeighborState.INIT, NeighborState.TWO_WAY}:
        return NeighborState.EXSTART

    return current

Four branches, and each one answers a different question.

hello_accepted is a hard floor. A Hello that fails the Session 01 checks — mismatched area, hello/dead interval disagreement, authentication failure, wrong netmask — doesn't leave the neighbor where it was. It drops it to DOWN. There is no partial credit and no memory of how far the relationship had progressed. This is worth internalizing because it explains a class of production symptom: a neighbor that was Full for months collapsing all the way to DOWN after someone changes a timer on one side. The code has no branch for "was Full, so be lenient."

saw_self is the one-way/two-way test. We received a valid Hello, so we know they're transmitting and we can hear them. What we don't know is whether they can hear us. The only evidence for that is our own Router ID appearing in the neighbor list of the Hello they sent. Without it, INIT — the state that means "I hear you, unconfirmed whether you hear me." This is the classic unidirectional-link signature, and it's why INIT exists as a distinct state rather than being folded into DOWN.

should_form_full_adjacency is the terminal branch that isn't a failure. Bidirectional communication is confirmed, and if the answer here is "no," the function returns TWO_WAY — and that's the final answer. Not a stop on the way somewhere; the destination. Two routers on a broadcast segment that are both DROTHERs will sit at 2-Way indefinitely, exchanging Hellos, never exchanging databases, and that is the protocol working correctly. They don't need a full adjacency with each other because they'll both get the same LSAs through the DR.

The last two lines are the interesting ones. Once we've decided a full adjacency is wanted, the function checks where we currently are:

    if current in {NeighborState.DOWN, NeighborState.INIT, NeighborState.TWO_WAY}:
        return NeighborState.EXSTART

    return current

If the neighbor is still in a Hello-phase state, we promote it to EXSTART — the handoff point. But if it's already past that (EXCHANGE, LOADING, FULL), we return current unchanged. A valid Hello arriving at an established neighbor does not restart the database exchange. That bare return current is the entire mechanism that makes OSPF adjacencies stable under ordinary Hello traffic: every 10 seconds a Hello comes in, gets validated, and lands on a line that says "change nothing."

Stage two: what the database exchange decides

advance_neighbor_state() composes the two phases:

def advance_neighbor_state(
    current: NeighborState,
    inputs: AdjacencyInputs,
) -> NeighborState:
    current = advance_on_hello(
        current,
        hello_accepted=inputs.hello_accepted,
        saw_self=inputs.saw_self,
        should_form_full_adjacency=inputs.should_form_full_adjacency,
    )

    if current in {NeighborState.DOWN, NeighborState.INIT, NeighborState.TWO_WAY}:
        return current
    # ...

Hello phase runs first, unconditionally. Then a gate: if the Hello phase landed on DOWN, INIT, or TWO_WAY, we return immediately and the database-exchange inputs are never consulted. They're present in the struct, they may be fully populated, and the function ignores them completely.

This is the structural answer to the question we opened with. hello_accepted=True, saw_self=True, should_form_full_adjacency=False returns TWO_WAY no matter what the other three booleans say. There is no path from a Hello to Full that skips this gate.

Past the gate, we're in database territory:

    if not inputs.database_description_ok:
        return NeighborState.EXSTART

    current = NeighborState.EXCHANGE
    if not inputs.request_list_empty:
        return NeighborState.LOADING
    if not inputs.retransmissions_cleared:
        return NeighborState.LOADING

    return NeighborState.FULL

database_description_ok covers master/slave negotiation and DD packet agreement — MTU match, sequence number sync, options compatibility. Fail it and you stay at EXSTART. Note that this branch pins you there rather than dropping you to DOWN: the Hellos are fine, bidirectional communication is fine, and the peer is still very much a neighbor. What's broken is one layer up. A pair of routers stuck at ExStart with healthy Hello traffic is exactly this branch firing repeatedly, and the classic cause — an MTU mismatch — is one you'll never find by looking at Hello packets.

Past that, current is assigned EXCHANGE and then two conditions can knock it down to LOADING. request_list_empty asks whether we still have LSAs we've requested but not received. retransmissions_cleared asks whether we have LSAs we sent that haven't been acknowledged. Either one non-empty means the databases aren't synchronized yet, in either direction, and LOADING is the state for "still reconciling."

Only when all six booleans line up does the function return FULL. Read the branches as a conjunction and FULL is the absence of every objection — not a positive achievement, but the state you fall through to when nothing is left to complain about.

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/ospf/session_02_walkthrough.py

Read it, then start changing inputs. The most useful experiment is constructing an AdjacencyInputs with every database field True and should_form_full_adjacency=False, and confirming that the result is TWO_WAY. Then set should_form_full_adjacency=True with database_description_ok=False and watch it pin at EXSTART. Two calls, and the two-stage structure stops being an abstraction.

The other experiment worth doing: call advance_neighbor_state() with current=NeighborState.FULL and a perfectly good set of inputs, then with current=NeighborState.FULL and hello_accepted=False. The second one collapses to DOWN in a single call.

Toy model boundary

This model is deliberately smaller than the real state machine, and the gaps matter:

There are no events. RFC 2328 defines the neighbor state machine in terms of events — HelloReceived, Start, 2-WayReceived, NegotiationDone, ExchangeDone, LoadingDone, AdjOK?, SeqNumberMismatch, BadLSReq, KillNbr, InactivityTimer, 1-WayReceived — each with a defined action and a defined resulting state. This code has no event type at all. It takes a snapshot of six booleans and computes a state from scratch. That means it can express where a neighbor should be given current conditions, but it cannot express what happens on a specific trigger, and it has no place to hang the side effects the real machine specifies (start the inactivity timer, clear the LSA lists, send a DD packet).

Timers are absent. No dead interval, no inactivity timer, no retransmit interval, no RouterDeadInterval expiry path. In real OSPF, a neighbor goes DOWN because Hellos stopped arriving for dead-interval seconds — an absence of input over time. This model can only express hello_accepted=False, a Hello that arrived and failed. The most common cause of a neighbor going down in production is the one the model structurally cannot represent.

EXCHANGE is a pass-through, not a real state. Look closely: current = NeighborState.EXCHANGE is assigned and then immediately either overwritten by LOADING or fallen through to FULL. The function can never return EXCHANGE. In real OSPF, Exchange is where DD packets are actually traded and it can persist for a meaningful stretch. Here it's a line of code that exists to name the phase.

The DR/BDR election is a boolean. should_form_full_adjacency compresses network type, priority comparison, DR/BDR election, and the wait timer into one input. That's a substantial subsystem reduced to True/False.

Nothing is per-interface or per-LSA. No interface state machine (Waiting, DR, BDR, DROther), no LSA-level detail behind request_list_empty and retransmissions_cleared, no graceful restart, no AdjOK? re-evaluation when a DR changes under an established adjacency.

What the model does preserve, and preserves precisely, is the two-phase structure and the guard ordering. That's the thing worth carrying to real routers.

Same shape, different protocol

Once you see the shape here — reachability confirmed, then capability negotiated, then state synchronized, with separate gates and separate failure modes at each — you start finding it everywhere.

BGP is the closest match. TCP connects (Connect), OPEN messages are exchanged and validated (OpenSent → OpenConfirm), and only then does the session reach Established and begin exchanging routes. A BGP session stuck in OpenSent is the same class of problem as OSPF stuck in ExStart: the transport is fine, the parameter negotiation isn't. And just as a bad Hello drops OSPF to DOWN regardless of prior state, a NOTIFICATION drops BGP to Idle from anywhere.

TCP's own handshake is advance_on_hello() in miniature. SYN received means "I hear you" — the INIT equivalent. SYN-ACK carrying an acknowledgment of your sequence number is the saw_self check: proof the peer heard you, not just that you heard the peer. A half-open connection is INIT.

TLS splits the same way at a different layer. The handshake establishes that both sides can talk and agree on parameters; only after Finished verifies both transcripts does application data flow. A handshake failure at parameter negotiation — no shared cipher suite — is database_description_ok=False in a different costume: connectivity proven, compatibility not.

The recurring lesson is that "connected" and "usable" are always separate states, and the states in between exist to name which of them failed.

Can you answer these from the code alone?

Don't look anything up. Go back to neighbor.py and trace the branches:

Two routers exchange valid Hellos, each sees the other's Router ID in the neighbor list, and both stay at 2-Way indefinitely. Which single line in advance_on_hello() produced that, and which input would you have to change to move them forward?
A neighbor has been FULL for a week. One Hello arrives with a mismatched hello interval. What does advance_neighbor_state() return, and how many lines of the function does it execute before returning?
advance_neighbor_state() is called with should_form_full_adjacency=True, database_description_ok=True, request_list_empty=True, and retransmissions_cleared=False. What comes back, and what does that result tell you about which direction of the database exchange is incomplete?

You're done with this session when you can explain why some neighbors stop at 2-Way — and why that's not a bug — and what still blocks Full after a neighbor reaches ExStart.

An OSPF Hello has to match before it can mean anything

pathvector-dev — Tue, 04 Aug 2026 00:00:13 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-ospf-01/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, branches — rather than as configuration examples. The full source lives at github.com/pathvector-studio/protocol-in-code, and every module is backed by a small Python file you can read end to end in a sitting. If you're earlier in the journey and want hands-on packet-level exercises first, start with the companion Protocol Lab series and come back here.

The question

What has to match before an OSPF Hello can even start a neighbor relationship?

That's the whole module. Not "how does SPF work," not "what's in an LSA" — just the gate that runs before any of that is on the table. Most OSPF material introduces the Hello packet as a keepalive: routers shout on the wire every 10 seconds, and if you stop hearing one for 40 seconds you tear the neighbor down. That's true, and it's also the least interesting thing about Hello.

The interesting thing is that Hello is a filter. Before OSPF will consider two routers to be on speaking terms, a set of fields in the received packet has to agree with the local interface's configuration. If they don't, nothing happens — no adjacency, no database exchange, no error to the sender, usually no log line you'll notice. The relationship simply never begins.

If you've ever stared at two routers that are unmistakably on the same broadcast segment, both configured for OSPF, both sending Hellos, and neither one forming an adjacency — you've been on the wrong side of this filter. The code below is where that lives.

The source

The file this module reads is src/protocol_in_code/ospf/hello.py. It's short enough that you can hold all of it in your head, which is the point. Read it in this order:

InterfaceHelloConfig — what the local interface believes about itself
OSPFHelloPacket — what arrived on the wire
evaluate_hello() — top to bottom, no skipping

Two sides of a comparison

Start with the two dataclasses, because the shape of the check is already visible in their fields.

@dataclass(frozen=True)
class InterfaceHelloConfig:
    local_router_id: str
    area_id: str
    netmask: str
    hello_interval: int
    dead_interval: int

That's the local side: five values, all of them things you configured (directly or by inheritance from an interface or process). Note what is not here — no neighbor list, no state, no timers. This is a config snapshot, frozen.

@dataclass(frozen=True)
class OSPFHelloPacket:
    source_router_id: str
    area_id: str
    netmask: str
    hello_interval: int
    dead_interval: int
    priority: int
    designated_router: str | None
    backup_designated_router: str | None
    neighbors: tuple[str, ...] = ()

The packet side is a superset. Four fields — area_id, netmask, hello_interval, dead_interval — line up name-for-name with the config. That alignment is not cosmetic; it's the check, written out in the type layout before any function runs. When two structs share a field name in a protocol implementation, ask what compares them.

The remaining fields (priority, designated_router, backup_designated_router, neighbors) are the ones OSPF uses after the gate opens — DR election and neighbor-state tracking. This module deliberately doesn't own those. It only touches neighbors, and only for one specific reason, which we'll get to.

The gate, one branch at a time

Here's evaluate_hello() in full. It is worth reading as a single continuous piece of logic rather than five separate rules:

def evaluate_hello(
    config: InterfaceHelloConfig,
    packet: OSPFHelloPacket,
) -> HelloCheckResult:
    reasons: list[str] = []

    if packet.source_router_id == config.local_router_id:
        reasons.append("router_id_loop")
    if packet.area_id != config.area_id:
        reasons.append("area_mismatch")
    if packet.netmask != config.netmask:
        reasons.append("netmask_mismatch")
    if packet.hello_interval != config.hello_interval:
        reasons.append("hello_interval_mismatch")
    if packet.dead_interval != config.dead_interval:
        reasons.append("dead_interval_mismatch")

    if reasons:
        return HelloCheckResult(
            accepted=False,
            saw_self=False,
            reasons=tuple(reasons),
        )

    saw_self = config.local_router_id in packet.neighbors
    return HelloCheckResult(
        accepted=True,
        saw_self=saw_self,
        reasons=(),
    )

Three structural facts jump out.

First: the checks accumulate rather than short-circuit. Each if appends to reasons and falls through to the next. A packet with both a wrong area and a wrong netmask comes back with both strings, not just the first one. This is a deliberate choice about diagnostics — when you're debugging a non-forming adjacency, "area_mismatch" alone might send you chasing one problem while a second one waits behind it. Real implementations vary here; many bail on the first failure and log a single reason. The accumulating form is more honest about the fact that misconfiguration is rarely singular.

Second: the first check isn't a mismatch at all.

if packet.source_router_id == config.local_router_id:
    reasons.append("router_id_loop")

Every other branch is !=. This one is ==. If the Hello claims to come from your own router ID, something is wrong — either you're seeing your own packet reflected back (a bridging loop, a misconfigured switch, a hairpin), or someone else on the segment is configured with the same router ID. Both are pathological, and neither should produce a neighbor. The reason string, router_id_loop, names the more common cause.

Note: OSPF router IDs are dotted-quad-shaped but are not addresses. They're identifiers, and nothing on the wire enforces uniqueness. Duplicate router IDs are a configuration error that the protocol can only detect by symptom — and this branch is one of the symptoms.

Third: saw_self is computed only after acceptance.

if reasons:
    return HelloCheckResult(
        accepted=False,
        saw_self=False,
        reasons=tuple(reasons),
    )

saw_self = config.local_router_id in packet.neighbors

The early return hardcodes saw_self=False. Not "unknown," not None — False. That's a statement about meaning: if the packet failed the gate, the question "did they list me as a neighbor?" isn't merely unanswered, it's not askable. A packet from the wrong area doesn't get to tell you anything about your adjacency state, even if your router ID happens to appear in its neighbor list.

This is the sort of thing that reads as a small implementation detail and is actually a security and correctness boundary. Untrusted input doesn't get to influence state until it's been validated as belonging on this link.

Why `saw_self` is the interesting output

accepted is the obvious result. saw_self is the one that matters more.

OSPF's adjacency state machine walks through Down → Init → 2-Way → ExStart → Exchange → Loading → Full. The transition from Init to 2-Way is precisely this: I have received a Hello from a neighbor, and that Hello contains my own router ID in its neighbor list. That's the moment bidirectional reachability is confirmed. Until then, you know they can reach you (you got their packet), but you don't know that you can reach them.

So evaluate_hello() produces two facts and stops:

accepted — this packet belongs on this link
saw_self — bidirectional communication is confirmed

Everything downstream (DR election, database description exchange, LSA flooding) is fed by those two bits and doesn't appear in this module at all. The function's job is to turn a packet into an input for a state machine it doesn't own.

Same shape, different protocol: the "I only trust this relationship once I've seen my own identity reflected back" pattern is not OSPF-specific. It's the same shape as the TCP three-way handshake — SYN proves they can reach you, SYN-ACK carrying your sequence number proves you can reach them. BGP does it too, with the OPEN/KEEPALIVE exchange before the session is Established. Once you've seen the shape in one protocol, the others stop looking like arbitrary ceremony.

Run it

The module ships a walkthrough:

PYTHONPATH=src python3 examples/ospf/session_01_walkthrough.py

You're looking for two things in the output: one accepted Hello and one rejected Hello. Read the reasons tuple on the rejected one and trace it back to the specific if that produced it.

The genuinely useful exercise is to edit the walkthrough's inputs. Flip dead_interval and confirm you get dead_interval_mismatch. Then flip area_id as well and confirm you get both strings in the tuple, in source order — that accumulate-don't-short-circuit behavior is easy to nod along to and easy to get wrong when you predict it. Then set source_router_id equal to local_router_id while everything else matches, and watch a packet that agrees on every configured field still get rejected.

What this toy model leaves out

This file models the first teaching gate and nothing else. Being specific about the gap is the point:

No packet parsing. OSPFHelloPacket arrives as a Python dataclass with typed fields. Real OSPF Hellos are bytes inside an OSPF header inside an IP packet with protocol number 89. Header version, packet length, checksum, and authentication are all validated before anything in this file would run, and each of those is its own rejection path.
No timers. hello_interval and dead_interval are compared as integers and never used as durations. The actual protocol behavior — send a Hello every hello_interval, declare the neighbor down after dead_interval of silence — requires a clock and a scheduler, neither of which exists here. dead_interval in this model is purely a value that must agree.
No adjacency state machine. The module stops at accepted and saw_self. There is no Down, no Init, no 2-Way. The function computes an input; something else consumes it.
No DR/BDR election. priority, designated_router, and backup_designated_router are carried on the packet and never read by evaluate_hello(). They're present so the dataclass is honest about what a Hello contains, not because this module uses them.
An incomplete match list. Real OSPF also requires agreement on the area type (stub/NSSA options bits in the E-bit and N-bit), authentication type and credentials, and MTU during the subsequent Database Description exchange. The netmask check itself doesn't apply on point-to-point links. Five fields is the teaching set, not the specification.
No wire behavior on rejection. In this model a rejected Hello returns a result object. On a real link it is silently discarded, sometimes with a counter increment. The sender learns nothing.

None of these omissions change the answer to the core question. They change how much of the real failure surface you've seen.

Check yourself

Close this page and answer these from the source file alone:

A packet arrives with a matching area, netmask, and both intervals — and source_router_id equal to your local_router_id. Does the function ever look at packet.neighbors? Trace the exact path through evaluate_hello() that decides this.
Two routers on the same segment disagree only on hello_interval. Which one detects the problem, and what does the other one learn about it? What does the code say about who gets told?
Why is saw_self hardcoded to False in the rejection branch rather than computed and returned alongside the reasons? Construct the concrete case where computing it anyway would be actively wrong.

Don't take my word for any of it — the file is under 60 lines.

You'll know you've got this module when you can name, without looking, the fields that must match before adjacency can continue, and explain why seeing your own router ID in a neighbor's list changes the next input to the adjacency state machine.

A BGP speaker is just state plus three event handlers

pathvector-dev — Mon, 03 Aug 2026 00:00:09 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-15/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. The source lives at pathvector-studio/protocol-in-code, and every article quotes from a Python file you can open and run yourself. If you're earlier in your networking journey and want to type commands and watch packets before you read code, start with the hands-on companion series Protocol Lab instead.

The question

What does the smallest readable BGP speaker look like when all the previous sessions are connected?

That's the question this module turns over. Not "how do I configure a BGP daemon," and not "what does a production speaker do" — but something narrower and, I think, more useful: if you've already written the session gate, the export refresh, the per-event branches, and the policy-aware best-path selection as separate functions, what's actually left to write?

The answer is smaller than most people expect. The file we're reading, src/protocol_in_code/bgp/speaker.py, is about 120 lines, and roughly half of them are argument lists.

Everything that came before

The speaker isn't inventing anything. It's assembling:

Session 11 gave us the session gate — the check that decides whether a peer is even in a state where its announcements count.
Session 12 gave us export refresh — recomputing what we advertise outward when the local RIB changes.
Session 13 gave us event-specific branches — process_announce_event, process_withdraw_event, process_peer_down_event, each with its own shape.
Session 14 gave us prefix-wide, policy-aware best-path selection.

This session wraps those event branches as methods on a single object. That's the whole move.

Note: This is the same pattern you'll see in the TCP track when the congestion-control functions get wrapped into a connection object, and in the DNS track when the cache and the resolver loop get joined. A protocol implementation is almost always pure decision functions plus a mutable bag of state that calls them in order. Once you see that shape, the "which daemon should I read next" question gets a lot less intimidating.

Read the speaker as a bag of state

Start at the dataclass. Don't read it as a class definition — read it as an inventory of everything a BGP speaker has to remember:

@dataclass
class ToyBGPSpeaker:
    vrps: list[VRP]
    policies: PipelinePolicies
    adj_rib_in: AdjRIBIn = field(default_factory=AdjRIBIn)
    loc_rib: LocRIB = field(default_factory=LocRIB)
    adj_rib_out: AdjRIBOut = field(default_factory=AdjRIBOut)
    peers: dict[str, PeerSession] = field(default_factory=dict)
    export_targets: dict[str, ExportTarget] = field(default_factory=dict)

Seven fields, and every one of them maps to something you'd point at on a whiteboard:

adj_rib_in — what peers told us, before we judged it.
loc_rib — what we decided to believe.
adj_rib_out — what we're telling other peers.
peers — session state per neighbor (this is where the Session 11 gate reads from).
export_targets — who we advertise to, and under what outbound policy.
vrps and policies — the validation and policy inputs that the pipeline consults.

The three-RIB split is the part worth sitting with. It's not an implementation detail; it's the reason BGP can be policy-driven at all. If there were one table, "what I heard," "what I chose," and "what I say" would be the same thing, and there'd be nowhere to put a policy decision. The Adj-RIB-In → Loc-RIB → Adj-RIB-Out chain exists precisely so that each arrow can have a filter on it.

Note also what has no default: vrps and policies are required constructor arguments. You cannot build this speaker without deciding what you validate against and what your policies are. That's a deliberate bit of API design — in the toy model, an unpolicied speaker isn't a thing you can accidentally create.

The three-line rhythm

Now read one of the event handlers. Here's receive_announce() in full:

    def receive_announce(
        self,
        peer_id: str,
        prefix: str,
        attributes: PathAttributes,
    ) -> SpeakerStep:
        result = process_announce_event(
            AnnounceEvent(peer_id=peer_id, prefix=prefix, attributes=attributes),
            self.peers,
            self.adj_rib_in,
            self.loc_rib,
            self.adj_rib_out,
            self._all_export_targets(),
            self.vrps,
            self.policies,
        )
        return self._step_from_event("announce", result)

Strip the argument list and it's two statements:

result = process_announce_event(...)
return self._step_from_event("announce", result)

Build an event object. Hand it to the pure function from Session 13 along with all the state. Turn the result into a report. That rhythm — event in, decision function, step out — is the entire course in miniature, and it repeats verbatim in the other two handlers.

receive_withdraw() is the same shape with one fewer argument:

    def receive_withdraw(self, peer_id: str, prefix: str) -> SpeakerStep:
        result = process_withdraw_event(
            WithdrawEvent(peer_id=peer_id, prefix=prefix),
            self.adj_rib_in,
            self.loc_rib,
            self.adj_rib_out,
            self._all_export_targets(),
            self.vrps,
            self.policies,
        )
        return self._step_from_event("withdraw", result)

Spot the difference before you read on: self.peers isn't passed. Announce and peer-down both take it; withdraw doesn't. That asymmetry is not an oversight, and it's the single best thing to reason about in this file. A withdraw doesn't need the session gate, because a withdraw is a removal — there's nothing to validate, no attributes to run through policy, no decision about whether the peer is allowed to say this. Announce needs the gate because accepting a path is a judgment call. Peer-down needs the peers dict because it mutates it — the session state gets downgraded as part of the event.

Read the argument lists as a statement about what each event is allowed to touch. That's a habit worth carrying into real codebases.

The result type

Every handler returns the same thing:

@dataclass(frozen=True)
class SpeakerStep:
    event: str
    accepted: bool
    prefixes: tuple[str, ...]
    installed_paths: dict[str, PathCandidate | None]
    export_changes: tuple[ExportChange, ...]

And the conversion is mechanical:

    def _step_from_event(self, event: str, result: EventResult) -> SpeakerStep:
        return SpeakerStep(
            event=event,
            accepted=result.accepted,
            prefixes=result.touched_prefixes,
            installed_paths=result.best_paths,
            export_changes=result.export_changes,
        )

This looks like pointless indirection until you ask what it's for. EventResult is the internal vocabulary of the event layer; SpeakerStep is the speaker's public answer to "what just happened?" Keeping them separate means the event functions can grow new internal fields without changing what callers see, and it gives you one uniform shape to log or assert against regardless of which event fired.

The field types carry information too. installed_paths is dict[str, PathCandidate | None] — the None is load-bearing. A prefix mapping to None means "this prefix was touched and now has no best path," which is a genuinely different outcome from the prefix not appearing in the dict at all. accepted being a single bool, meanwhile, tells you these events are all-or-nothing at the speaker level: an announce either got through the gate and the pipeline or it didn't.

export_changes is where the Session 12 work surfaces. A single announce can ripple into multiple outbound advertisements — one per export target whose view of the prefix changed — which is why it's a tuple rather than a single value.

Wiring and running it

Two small setup methods complete the object:

    def add_neighbor(self, peer_id: str, config: BGPSessionConfig) -> None:
        self.peers[peer_id] = open_peer_session(peer_id, config)

    def add_export_target(self, target: ExportTarget) -> None:
        self.export_targets[target.peer_id] = target

    def _all_export_targets(self) -> tuple[ExportTarget, ...]:
        return tuple(self.export_targets.values())

Both are dict inserts keyed by peer_id, and _all_export_targets() freezes the values into a tuple on every call — the event functions receive a snapshot they can't mutate, which keeps the "pure function" contract honest even though the speaker itself is mutable.

The walkthrough is runnable:

PYTHONPATH=src python3 examples/bgp/session_15_walkthrough.py

Watch for five things as it steps through:

The first announce installing one path — installed_paths goes from nothing to a PathCandidate.
The second announce either keeping or changing the best path — this is Session 14's comparison logic firing.
A withdraw moving the prefix to the remaining peer — the Loc-RIB re-selects from what's left in Adj-RIB-In.
Peer-down removing the last remaining path and downgrading the peer's session state — one event mutating two kinds of state.
Outbound advertisements changing as each of the above happens — export_changes should be non-empty exactly when the Loc-RIB decision actually changed.

That last one is the interesting audit. If you see a Loc-RIB change with no corresponding export change, either a policy filtered it or you've found a bug. Both are worth chasing.

Toy model boundary

This is a teaching model, and being precise about what it isn't matters more here than in earlier sessions — because "a BGP speaker" sounds like a complete thing, and this isn't one.

What's absent:

No timers. No hold timer, no keepalive, no MRAI (Minimum Route Advertisement Interval). Real speakers damp their advertisement rate; this one advertises the instant a decision changes. A significant fraction of real BGP behavior — including a good chunk of convergence dynamics — lives in those timers.
No packet parsing. receive_announce() takes a PathAttributes object, not bytes. There is no wire format here, no TLV walking, no length validation, none of the malformed-attribute error handling that RFC 4271 spends real pages on.
No capability negotiation. No OPEN message, no capability exchange, no AFI/SAFI negotiation. add_neighbor() just constructs a session and puts it in a dict.
No UPDATE encoding. export_changes describes decisions, not messages. Nothing here would go on a socket.
No FSM. Real BGP has a six-state finite state machine (Idle, Connect, Active, OpenSent, OpenConfirm, Established). The toy model has a session gate and a peer_down() that downgrades state.
No transport. No TCP connection, no port 179, no MD5 or TCP-AO.

What this model does show is the control-plane loop shape: an event arrives, state is consulted, a decision function runs, RIBs move, and outbound state is recomputed. That shape is real, and it's the part that stays the same across implementations. Everything in the list above is a layer wrapped around it.

Same shape, different protocol

Once you can see ToyBGPSpeaker as mutable state + pure event functions + a uniform result type, you'll find the pattern everywhere. A TCP connection object is a bag of state (cwnd, ssthresh, sequence numbers, retransmission queue) with event handlers for ACK-received, timeout-fired, and data-queued — each one consulting state, running a decision function, and returning what changed. A DNS resolver is a cache plus handlers for query-received and response-received.

The Adj-RIB-In / Loc-RIB / Adj-RIB-Out split has its own echoes: it's the same "raw input, decided truth, published view" separation you see in a TLS session cache holding tickets separately from the live parameters actually negotiated, or in conntrack keeping the observed tuple separate from the translated one it emits.

Different protocol, different field names, same three moving parts.

Check yourself

Before you close the file, see whether you can answer these from the source alone — no running required:

receive_withdraw() doesn't receive self.peers, but receive_announce() and peer_down() do. What breaks — and what correctly doesn't break — if a withdraw arrives from a peer whose session has gone down?
_all_export_targets() builds a fresh tuple on every event. If an export target were added mid-event by some other code path, would the in-flight event see it? Does the answer differ for peers, which is passed as the live dict?
installed_paths is dict[str, PathCandidate | None]. Trace which event can produce a None value, and which can produce a prefix in prefixes that has no entry in installed_paths at all. Are those the same situation?

Don't take my word for any of it — the file is short enough to hold in your head, which is the entire point of a toy model.

Done when

You can explain the speaker as one object holding state plus three event handlers, and you can see how Sessions 01–14 collapse into a single readable control-plane loop. If someone asks you "what does a BGP speaker do?", the answer you reach for should now be structural rather than a list of features.

One prefix stops being one route: reading BGP's decision set as code

pathvector-dev — Sun, 02 Aug 2026 00:00:11 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-14/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. The code we read here lives in pathvector-studio/protocol-in-code. If you're earlier in your journey and want to do things with protocols before dissecting them, start with the hands-on Protocol Lab series instead — it builds the muscle memory this series assumes.

The question

How do multiple received paths for one prefix become a policy-aware set of installable candidates?

That question sounds small until you notice what it costs. Session 03 of this track taught pure best-path selection: hand it a list of candidates, get back the winner. It's a clean, total function. But best-path selection is only correct when every candidate handed to it is a legitimate thing to install. The moment you introduce RPKI validation and routing policy, that assumption evaporates. Some candidates shouldn't be installed at all. Others should be installed but with rewritten attributes that change who wins.

So the shape of the problem changes. One prefix is no longer one route. One prefix is a decision per peer, and the decisions have to be made before comparison can mean anything.

The file that does this is src/protocol_in_code/bgp/decision_process.py, with src/protocol_in_code/bgp/pipeline.py as its companion. It's short enough to read in one sitting, which is the point — the entire argument fits in two functions.

Read the record before you read the loop

Start at the dataclass, not the function. What a piece of code chooses to keep tells you what it thinks a decision is:

@dataclass(frozen=True)
class CandidateDecision:
    peer_id: str
    validation_state: ValidationState
    action: PolicyAction
    installed_candidate: PathCandidate | None

Four fields, and every one of them is load-bearing.

validation_state and action are deliberately separate. Sessions 04 and 05 spent their time on exactly this split: what RPKI says about a route (ValidationState) is not the same thing as what your router does about it (PolicyAction). An INVALID state doesn't mechanically mean "drop." It means an input to a policy that you wrote, and that policy might drop, might deprioritize, might log and accept. Collapsing the two into a single "verdict" field is the most common modelling mistake in this area, and it's the one this dataclass refuses to make. The state and the action ride together, both visible, neither derived from the other after the fact.

installed_candidate is PathCandidate | None, and the None is the whole story. A decision that produced no installable candidate is still a decision — it's a record that this peer offered this prefix and policy said no. You keep the row. You don't silently drop it from the list.

And then peer_id, which is the sneaky one.

Note: PathCandidate intentionally doesn't carry peer_id. Pure best-path comparison doesn't need to know where a route came from — it compares LOCAL_PREF, AS_PATH length, origin, and so on, and none of those depend on peer identity. So earlier sessions dropped it. Here the course puts it back, because policy-aware decision making is inherently about who told you. This is a real design tension in protocol modelling: the minimal type for one operation is the wrong type for the next one.

The loop that turns a prefix into a set

Here's the function the whole session points at:

def evaluate_prefix_candidates(
    adj_rib_in: AdjRIBIn,
    prefix: str,
    vrps: list[VRP],
    policies: PipelinePolicies,
) -> list[CandidateDecision]:
    decisions: list[CandidateDecision] = []
    for peer_id, attributes in received_attributes_for_prefix(adj_rib_in, prefix):
        validation_state, action, installed = evaluate_candidate(prefix, attributes, vrps, policies)
        decisions.append(
            CandidateDecision(
                peer_id=peer_id,
                validation_state=validation_state,
                action=action,
                installed_candidate=installed,
            )
        )
    return decisions

Read the signature first. It takes one prefix and the entire Adj-RIB-In — the table of what every neighbor sent you, before any local processing. It returns a list. That type signature is the session's thesis: one prefix in, many decisions out.

The loop body is a single call. received_attributes_for_prefix(adj_rib_in, prefix) yields (peer_id, attributes) pairs — every peer that currently advertises this prefix. Then evaluate_candidate() — the per-route pipeline that Session 10 assembled — runs unchanged for each one. Session 10 did validation-then-policy for one incoming route. This session does nothing new to that logic; it just runs it across the fan-in.

That's worth sitting with. The interesting code here isn't clever. It's a for loop and an append. The intelligence is in the shape — in deciding that "evaluate one route" and "evaluate a prefix" are different operations with different return types, and that the second is a fan-out over the first rather than a bigger version of it.

Note also what the loop preserves: decisions where installed came back None still get appended. evaluate_prefix_candidates() is a reporting function. It tells you what happened to every path, including the ones that died. If you want to know why traffic for a prefix is going somewhere surprising, this list is the answer, and it would be useless if it only contained survivors.

Selection happens last, and only on survivors

def select_best_installable_for_prefix(
    adj_rib_in: AdjRIBIn,
    prefix: str,
    vrps: list[VRP],
    policies: PipelinePolicies,
) -> PathCandidate | None:
    decisions = evaluate_prefix_candidates(adj_rib_in, prefix, vrps, policies)
    installable = [decision.installed_candidate for decision in decisions if decision.installed_candidate is not None]
    if not installable:
        return None
    return select_best_path(installable)

Four statements, and the ordering of them is the answer to the session's question.

Evaluate everything. Filter to what survived. Bail if nothing did. Then compare.

select_best_path() — the pure function from Session 03 — is called exactly once, on the last line, against a list that has already been filtered and, crucially, already been rewritten. The candidates in installable are not the attributes that arrived on the wire. They're whatever evaluate_candidate() produced after policy ran. If a policy knocked LOCAL_PREF down on a route from an INVALID-validating peer, the candidate in this list carries the lowered value, and best-path compares against that.

This is why "just run best-path" is not enough once validation and policy exist. Best-path is a comparison over a set; it has no opinion about set membership and no opinion about the values it's comparing. Both of those are decided upstream. Run best-path on raw received attributes and you'll faithfully select a route that policy would have rejected.

The if not installable: return None line deserves a beat too. Every path for this prefix can be filtered out, and that's a legitimate outcome — the prefix simply has no route. It's not an error and it's not an empty-list crash in select_best_path(). The None return type makes "no route for this prefix" a first-class value that callers have to handle.

Same shape, different protocol

Once you've seen this ordering, you start recognizing it elsewhere in the series.

Within BGP itself the lineage is explicit: Session 03 gave pure comparison, Sessions 04 and 05 split validation state from policy action, Session 10 wired them together for a single route, and this session fans that out prefix-wide. Nothing was rewritten along the way — each layer wraps the previous one and adds exactly one concern.

The broader pattern is validate → transform → filter → select, and it isn't BGP-specific. A DNS resolver validating RRSIGs before it will serve an answer from cache is doing the same thing: cryptographic verification produces a state, local policy decides whether that state is fatal, and only then does the resolver pick which record set to hand back. A TLS stack evaluating a certificate chain does it too — the chain either validates or it doesn't, and separately your trust policy decides whether a validation failure aborts the handshake or gets pinned around. Same shape, different protocol. The mistake in all three is the same one: fusing the verification result and the local decision into one boolean, and then having nowhere to put the case where you want to accept something you know is broken.

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/bgp/session_14_walkthrough.py

Three things to watch for in the output:

One peer whose route is deprioritized by policy — same prefix, still installable, but its attributes came out of the pipeline different from how they went in.
One peer whose route stays installable without change — the untouched control case.
The final best path being chosen after that rewrite, not before it.

If you can trace the third bullet back to the four-line body of select_best_installable_for_prefix(), you've got the session.

Toy model boundary

This is a teaching model, and it simplifies aggressively. Being specific about where:

Best path here is one function call over a flat list. Real BGP best-path selection is the tie-breaker cascade from RFC 4271 §9.1 — weight, LOCAL_PREF, locally originated, AS_PATH length, origin type, MED (with all its comparison-scope subtleties), eBGP over iBGP, IGP metric to next hop, and router-ID as the final coin flip. It also requires next-hop reachability, which this model never checks at all. A candidate here is installable if policy says so; a real router additionally demands a resolvable next hop.

Everything is recomputed from scratch. select_best_installable_for_prefix() reads the whole Adj-RIB-In for a prefix and re-evaluates every peer's path on every call. Real implementations are incremental and event-driven: an UPDATE arrives, and only the affected prefixes are re-run, usually behind a scheduler with route-refresh handling, timers, and damping. There's no notion of time in this model — no MRAI, no convergence behavior, no churn.

There is exactly one best path. No ECMP, no multipath, no add-path. Real deployments routinely install several next hops for one prefix, and the function's PathCandidate | None return type structurally forbids that.

RPKI is a list of VRPs passed in as an argument. No RTR session, no cache staleness, no partial-coverage semantics beyond whatever ValidationState models. Real ROV has to reason about a validator that may be down, stale, or disagreeing with a peer's.

Adj-RIB-Out and advertisement are absent. This model stops at "which path do I install." What you re-advertise to which neighbors, with what attribute modifications, is a whole separate policy stage that isn't here.

No withdrawals, no state transitions. The Adj-RIB-In is a static snapshot. Nothing in this file handles a peer going down, a path being withdrawn, or the difference between "no route" and "route just disappeared" — which is precisely the distinction that makes real routing hard to debug.

None of these omissions change the argument the session is making. They're the reason it fits in forty lines.

Check yourself

Close the walkthrough output and answer these from the source alone:

A peer's route validates as INVALID but the resulting CandidateDecision still has a non-None installed_candidate. Reading evaluate_prefix_candidates() and CandidateDecision, is that a bug — and which field would you inspect to find out what actually happened?
select_best_installable_for_prefix() returns a PathCandidate whose attributes don't match anything you can find in the Adj-RIB-In for that prefix. Where in the four-statement body did the values change, and why is that the correct place for it?
Every peer advertises the prefix, and the function returns None. Which line produced that, and what does the returned value fail to tell you that evaluate_prefix_candidates() would have?

Don't take my word for any of it — the file is short, and the answers are all in it.

Announce, withdraw, and peer down are three different code paths

pathvector-dev — Sat, 01 Aug 2026 00:00:13 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-13/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. Every module points at a real Python file you can open, read, and run; the source lives at github.com/pathvector-studio/protocol-in-code. If you're newer to this and want to build up hands-on first, start with the companion Protocol Lab series, which is the practical, run-it-yourself track.

The question

When a BGP speaker receives news from the outside world, that news arrives in a few distinct flavors. A peer announces a prefix. A peer withdraws a prefix. A peer's session drops entirely. It's tempting to model all three as "an update happened, go recompute" — one generic entry point with a flag or two.

So here's the question to hold onto while you read:

Core question: What function decides which control-plane path to run for announce, withdraw, and peer-down events?

And its sharper follow-up: why are these three separate functions instead of one? The answer is not stylistic. Each event enters the control plane at a different point, and one of them can touch an unbounded number of prefixes.

The file is src/protocol_in_code/bgp/events.py.

Three triggers, not one

Start at the top of the file. The events are declared as three separate frozen dataclasses, and the shape of each one already tells you something:

@dataclass(frozen=True)
class AnnounceEvent:
    peer_id: str
    prefix: str
    attributes: PathAttributes


@dataclass(frozen=True)
class WithdrawEvent:
    peer_id: str
    prefix: str


@dataclass(frozen=True)
class PeerDownEvent:
    peer_id: str

Read them as a narrowing sequence. An announce carries the full payload: who, what prefix, and what path attributes came with it. A withdraw carries who and what prefix — there are no attributes, because you're removing a path, not describing one. A peer-down carries only who. It doesn't name a prefix at all, and that omission is the whole reason the third branch has to be written differently: the set of affected prefixes isn't in the event, it has to be discovered from state.

All three converge on one return type:

@dataclass(frozen=True)
class EventResult:
    accepted: bool
    touched_prefixes: tuple[str, ...]
    best_paths: dict[str, PathCandidate | None]
    export_changes: tuple[ExportChange, ...]

Note touched_prefixes is a tuple and best_paths is a dict keyed by prefix. The return type was designed for the many-prefix case even though two of the three branches will only ever fill it with one entry.

The shape of the dispatch

Before walking through the real code, here's the shape in pseudocode. This is the lesson; the actual functions are longer, but they don't deviate from it:

if announce:
    gate peer
    recompute prefix
    refresh exports
elif withdraw:
    remove received path
    recompute prefix
    refresh exports
elif peer_down:
    remove whole peer table
    recompute affected prefixes
    refresh exports

Three things stand out. Only the announce branch has a gate. Every branch ends in the same two steps — recompute, then refresh exports. And only the last branch has a loop.

Announce: gate first, then recompute

process_announce_event() starts with the session gate that Session 11 made explicit:

    peer = peers[event.peer_id]
    accepted = receive_update_if_established(adj_rib_in, peer, event.prefix, event.attributes)
    if not accepted:
        return EventResult(
            accepted=False,
            touched_prefixes=(event.prefix,),
            best_paths={event.prefix: loc_rib.best_paths.get(event.prefix)},
            export_changes=(),
        )

An announce from a peer that isn't in ESTABLISHED doesn't get to write into the Adj-RIB-In at all. Look carefully at the early return: it doesn't just bail with a flag. It reports touched_prefixes containing the prefix, and it reports the current best path from loc_rib.best_paths.get(event.prefix) — the one that was already there. export_changes is empty. The rejected announce is visible in the result, but it changed nothing.

That's a deliberate distinction worth internalizing: "we looked at this prefix" and "this prefix changed" are different claims, and the result type keeps them separate.

If the gate passes, the rest is two calls:

    best = _recompute_prefix(adj_rib_in, loc_rib, event.prefix, vrps, policies)
    changes = refresh_exports_for_prefix(event.prefix, loc_rib, adj_rib_out, export_targets)

_recompute_prefix() is where the event layer hands off all the prefix-level decision work:

def _recompute_prefix(
    adj_rib_in: AdjRIBIn,
    loc_rib: LocRIB,
    prefix: str,
    vrps: list[VRP],
    policies: PipelinePolicies,
) -> PathCandidate | None:
    best = select_best_installable_for_prefix(adj_rib_in, prefix, vrps, policies)
    if best is None:
        remove_best_path(loc_rib, prefix)
        return None

    install_best_path(loc_rib, best)
    return best

This helper is the reason the three branches stay short. Every hard question — which candidate wins the decision process, whether RPKI validation rejects it, what the policies say — lives behind select_best_installable_for_prefix(). The event layer only cares about the binary outcome: there's a best path (install it) or there isn't (remove whatever was installed). Session 14 goes deeper into that decision logic, but the dispatch shape you're reading here doesn't change.

Withdraw: no gate, and it starts by deleting

Now compare process_withdraw_event():

def process_withdraw_event(
    event: WithdrawEvent,
    adj_rib_in: AdjRIBIn,
    loc_rib: LocRIB,
    adj_rib_out: AdjRIBOut,
    export_targets: tuple[ExportTarget, ...],
    vrps: list[VRP],
    policies: PipelinePolicies,
) -> EventResult:
    withdraw_received_path(adj_rib_in, event.peer_id, event.prefix)
    best = _recompute_prefix(adj_rib_in, loc_rib, event.prefix, vrps, policies)
    changes = refresh_exports_for_prefix(event.prefix, loc_rib, adj_rib_out, export_targets)

Two differences from announce, and both are in the signature and the first line.

First, look at the parameter list: there's no peers argument. The withdraw path doesn't have access to the session table, which means it structurally cannot gate on session state. That's not an omission — it's the design being enforced by the type signature.

Second, the first statement is a removal, not a validation. There is no accepted check and the function always returns accepted=True. Withdrawing state you may or may not have is safe; adding state you shouldn't have is not. Removal is idempotent in a way that installation isn't, so the asymmetry is justified rather than sloppy.

After that first line, the two branches are identical: recompute, refresh. The withdrawal might not even change the best path — if the withdrawing peer wasn't the winner, select_best_installable_for_prefix() will return the same candidate it did before, and refresh_exports_for_prefix() will produce no changes. The code doesn't special-case that. It recomputes unconditionally and lets the export refresh decide whether anything is actually different.

Peer down: one event, many prefixes

process_peer_down_event() is where the shape breaks:

    lost_prefixes = tuple(adj_rib_in.paths_by_peer.get(event.peer_id, {}).keys())
    adj_rib_in.paths_by_peer.pop(event.peer_id, None)
    peer = peers.get(event.peer_id)
    if peer is not None:
        peers[event.peer_id] = PeerSession(peer_id=peer.peer_id, config=peer.config, state=SessionState.ACTIVE)

The first line is the crux of this whole module. Because PeerDownEvent carries no prefix, the affected set has to be read out of state before that state is destroyed. Order matters: snapshot the keys, then pop the peer's table. Reverse those two lines and you lose the list of prefixes you were about to fix up.

Note also .get(event.peer_id, {}) and .pop(event.peer_id, None) — a peer-down for a peer with no received paths, or no entry at all, is a no-op rather than a KeyError. Session teardown races are exactly the situation where you get duplicate or spurious down events.

The session state moves to ACTIVE, not IDLE. That's the FSM's "trying to connect" state, which is where a peer that just dropped should sit. And because PeerSession is frozen, the update is a replacement of the dict entry, not a mutation.

Then comes the loop that no other branch has:

    lost: dict[str, PathCandidate | None] = {}
    changes: list[ExportChange] = []
    for prefix in lost_prefixes:
        lost[prefix] = _recompute_prefix(adj_rib_in, loc_rib, prefix, vrps, policies)
        changes.extend(refresh_exports_for_prefix(prefix, loc_rib, adj_rib_out, export_targets))

    return EventResult(
        accepted=True,
        touched_prefixes=tuple(lost.keys()),
        best_paths=lost,
        export_changes=tuple(changes),
    )

This is the same two-step body as announce and withdraw — _recompute_prefix() then refresh_exports_for_prefix() — wrapped in a for. And note what it does not do: it doesn't blanket-withdraw every prefix the peer had announced. For each lost prefix it re-runs the decision process against what's left in the Adj-RIB-In. If another peer was also announcing that prefix, _recompute_prefix() finds it and installs it, and the export refresh emits a change to the new next hop rather than a withdrawal. Only prefixes where the downed peer was the sole source collapse to None.

That's the practical answer to the "which branch touches many prefixes" question, and it's why a single generic update function would have been awkward: two of the three branches know their prefix up front, and one has to go find it.

Note: Recomputing per prefix in a loop is also where real BGP implementations spend serious engineering effort. A peer down on a full-table session means several hundred thousand recomputations. Real implementations batch, defer, and prioritize; this toy model just loops.

Reading lens: the same shape shows up elsewhere

The pattern here — the event doesn't name its own blast radius, so you snapshot state before destroying it — isn't BGP-specific. It's the same shape as conntrack entry expiry, where a single timeout has to enumerate the flows it invalidates before dropping the table entry. It's the same shape as a DNS resolver flushing everything under a zone when the zone's delegation changes. In each case the trigger is small and singular, and the cleanup has to derive its own scope from state that's about to go away.

Once you've seen the announce/withdraw/peer-down split, you'll notice that most protocol event loops have exactly this trio: a gated additive event, an ungated removal, and a teardown that fans out.

Run it

The walkthrough for this session is runnable:

PYTHONPATH=src python3 examples/bgp/session_13_walkthrough.py

Watch for four things in the output, in order:

one announce producing a best path
one withdraw removing that best path
a second announce restoring it
one peer-down withdrawing all affected exports

The last one is the payoff. Compare the length of touched_prefixes in that final result against the three before it.

Toy model boundary

This is a teaching model, and it simplifies in ways that matter if you carry the mental model into production:

Events are synchronous and serialized. Each process_*_event() call runs to completion before the next event exists. Real BGP speakers process a stream of UPDATE messages off a TCP socket, with input queues, read batching, and no guarantee that a peer-down is observed before or after the updates that were in flight when the session dropped.
A real UPDATE message carries both announcements and withdrawals. RFC 4271's UPDATE has a Withdrawn Routes field and an NLRI field in the same message. Splitting them into AnnounceEvent and WithdrawEvent is a modeling choice that makes the branches legible; a real parser has to handle both in one message and get the ordering right.
No timers. There's no MRAI (Minimum Route Advertisement Interval), no route flap damping, no graceful restart. In this model, peer-down means the paths are gone immediately. Real BGP with graceful restart keeps stale routes marked and installed while it waits for the session to come back.
The recompute is exhaustive, not incremental. _recompute_prefix() re-runs the full selection for a prefix every time. Production implementations track which candidate is currently best and short-circuit most updates without a full re-scan.
export_changes is a return value, not I/O. Nothing is transmitted. There are no OPEN/KEEPALIVE/NOTIFICATION messages, no hold timer, no actual peers.
peers[event.peer_id] in the announce path will KeyError on an unknown peer. That's fine for a model where you control the inputs; a real speaker never trusts the peer identifier that far.

Check yourself

Try to answer these by reading events.py alone, without running anything. If you can't, that's the signal for where to look:

Why is process_withdraw_event() missing the peers parameter that the other two branches take, and what would change if you added a session gate to it?
In process_peer_down_event(), what breaks if you swap the order of the lost_prefixes assignment and the paths_by_peer.pop() call?
An announce arrives from a peer in OPEN_CONFIRM. Trace the return value: what is accepted, what is in touched_prefixes, and what is in best_paths?

Once you have answers, go verify them against the source rather than against your memory of this post.

Done when

You can explain why announce, withdraw, and peer down are three branches instead of one generic update function — and you can say, without looking, which branch touches exactly one prefix and which one can touch many.

When Loc-RIB changes, every peer needs a different answer

pathvector-dev — Fri, 31 Jul 2026 00:00:09 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-12/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. The source lives at pathvector-studio/protocol-in-code, and every module points at a real Python file you can open, read, and run. If you're earlier in the journey and want hands-on packet-level exercises first, start with the companion Protocol Lab series and come back here.

Today's module is BGP Session 12: export refresh after recompute.

The question

When Loc-RIB changes, how do outbound advertisements get refreshed per peer?

Hold that question while you read. It sounds like plumbing, but it's the question that separates two things people often collapse into one: what this router believes is the best path, and what this router tells each neighbor. Those are different pieces of state, updated at different times, by different code.

Two earlier sessions set this up. Session 08 showed how a single installed route becomes a single exported route — the policy pass that turns "I use this path" into "here is what I'll say about it." Session 09 showed how Loc-RIB can change after a session goes down and best-path selection reruns. Session 12 is the seam between them: recompute already happened, Loc-RIB already moved, and now something has to walk the peers and fix up Adj-RIB-Out.

The file to open is src/protocol_in_code/bgp/export_refresh.py, with export_policy.py as the companion it leans on.

Export is peer-specific, and the types say so

Start with the data, not the function. The first thing worth noticing is that there is no such thing as "the export" of a prefix:

@dataclass(frozen=True)
class ExportTarget:
    peer_id: str
    peer_type: PeerType
    policy: ExportPolicy

An ExportTarget bundles three things: who the peer is, what kind of peer it is (customer, upstream, and so on), and which policy applies. Nothing about the route is in here. That asymmetry is the design statement: the route is global to the router, the export decision is local to the peer.

The output type mirrors it:

class ExportChangeKind(str, Enum):
    ADVERTISE = "advertise"
    WITHDRAW = "withdraw"


@dataclass(frozen=True)
class ExportChange:
    peer_id: str
    prefix: str
    kind: ExportChangeKind
    path: PathCandidate | None

Two kinds of change, and path is None for one of them. A withdrawal carries no path — you're not telling the peer about a route, you're telling it to forget one. The type makes that impossible to get wrong.

Note: ExportChangeKind subclasses str as well as Enum. That's a small ergonomic choice — it means the value compares equal to "advertise" and serializes cleanly — not a protocol fact. Don't read anything into it.

Three values, one peer

Now the function. The whole module is one loop, and the loop body juggles exactly three values per peer. Get those three straight and you've got the session.

def refresh_exports_for_prefix(
    prefix: str,
    loc_rib: LocRIB,
    adj_rib_out: AdjRIBOut,
    targets: tuple[ExportTarget, ...],
) -> list[ExportChange]:
    installed = loc_rib.best_paths.get(prefix)
    changes: list[ExportChange] = []

installed is read once, before the loop. That's the "what this router believes" value, and it's the same for every peer — that's the whole point of Loc-RIB. Note the .get(): if recompute removed the prefix entirely, installed is None, and the loop below still runs. A prefix disappearing is not a special case here; it's the same code path with a different input.

Then, per peer:

    for target in targets:
        current_by_prefix = adj_rib_out.advertisements_by_peer.setdefault(target.peer_id, {})
        current = current_by_prefix.get(prefix)
        desired = None
        if installed is not None:
            desired = prepare_export(installed, target.peer_type, target.policy)

installed — what Loc-RIB says the router uses. One value, shared.
current — what this peer has already been told. Read out of Adj-RIB-Out, per peer.
desired — what this peer should be told. installed run through prepare_export() with this peer's type and policy.

desired starts at None and only becomes a path if installed exists. And even when installed exists, prepare_export() may return None — that's policy denying the export. Both roads lead to the same place, which is why the next branch doesn't care which one you took.

The branch that matters

Here's the reconciliation:

        if desired is None:
            if current is not None:
                current_by_prefix.pop(prefix, None)
                changes.append(
                    ExportChange(
                        peer_id=target.peer_id,
                        prefix=prefix,
                        kind=ExportChangeKind.WITHDRAW,
                        path=None,
                    )
                )
            continue

        if current != desired:
            current_by_prefix[prefix] = desired
            changes.append(
                ExportChange(
                    peer_id=target.peer_id,
                    prefix=prefix,
                    kind=ExportChangeKind.ADVERTISE,
                    path=desired,
                )
            )

Read it as a two-by-two table of current against desired:

`current`	`desired`	outcome
`None`	`None`	nothing — peer never knew, still doesn't
set	`None`	withdraw, and drop the entry from `Adj-RIB-Out`
`None`	set	advertise
set	set, equal	nothing — no wire churn
set	set, different	advertise the new value

The two "nothing" rows are the ones worth pausing on. The inner if current is not None guard means you don't emit a withdrawal for a route the peer was never told about — BGP has no way to un-say something you never said. And if current != desired means an unchanged export produces no ExportChange at all. That second one is why this is called a refresh and not a resend: recompute might touch a prefix and, after policy, produce byte-identical output for a peer. That peer hears nothing.

The desired is None branch is where withdrawal is born. Nothing upstream decided "send a withdraw" — it's an emergent consequence of Adj-RIB-Out holding a value that policy no longer justifies. Notice too that both the state mutation and the change record happen together in each branch: Adj-RIB-Out is the durable state, the returned list[ExportChange] is the delta. They never diverge because they're written in the same two lines.

That structure also answers the "why a separate pass?" part of the session. Best-path selection produces one answer per prefix. Export produces N answers per prefix, one per peer, and each one depends on peer-local state (current) that best-path selection has no business knowing about. Fusing them would mean best-path selection carrying a peer loop inside it. Splitting them means recompute can run, settle, and then hand a stable Loc-RIB to a pass whose only job is per-peer reconciliation.

Run it

The module ships a runnable walkthrough:

PYTHONPATH=src python3 examples/bgp/session_12_walkthrough.py

Three things to look for in the output:

An advertisement to the customer peer. installed exists, policy permits, current was empty → ADVERTISE.
No advertisement to the denied upstream peer. installed exists, but prepare_export() returns None. desired is None, current is None, so the continue fires and nothing is emitted. Silence, not a withdraw.
A withdrawal when the installed path disappears. loc_rib.best_paths.get(prefix) returns None, so desired is None for every peer — but only the peers with a non-None current get a WITHDRAW.

Case 2 and case 3 both hit desired is None. Only one of them produces output. That difference is entirely current, and it's the single most useful thing to internalize from this file.

Toy model boundary

This is a toy model, and being precise about what it isn't is the point of this section.

It refreshes one prefix at a time. refresh_exports_for_prefix() takes a single prefix. A real implementation after a session teardown has thousands to tens of thousands of prefixes to reconsider, and the interesting engineering is entirely in how you batch, prioritize, and pace that work — not in the per-prefix decision.

It does not build UPDATE messages. There is no packet here. No path attribute encoding, no NLRI packing, no grouping of prefixes that share an attribute set into one UPDATE — which is the main reason real BGP UPDATEs are efficient at all. The function returns a list[ExportChange], a description of what should be true, and stops. Turning that list into wire bytes is a separate problem this module deliberately doesn't touch.

No timing. Real BGP spaces out advertisements with MRAI (Minimum Route Advertisement Interval) timers, precisely so that a flapping route doesn't turn into a flood of UPDATEs. There is no clock in this file. Every change is emitted immediately.

No withdrawal suppression or route damping. Nothing here notices that a prefix has advertised and withdrawn ten times in a minute.

Comparison by !=. if current != desired relies on PathCandidate equality. Real implementations compare over attribute sets with rules about which attributes are transitive, which are optional, and which get rewritten on export.

What the module does model faithfully is the decision itself: given what Loc-RIB holds, what Adj-RIB-Out holds, and this peer's policy, should this peer see an advertise, a withdraw, or nothing? That decision is real. Everything around it is stripped.

The same shape shows up elsewhere

Once you've seen current vs. desired reconciled against per-consumer state, you start seeing it in tracks that have nothing to do with BGP.

It's a reconciliation loop: read the intended state, read the observed state, emit the minimal set of changes to close the gap — and emit nothing when they already agree. That last property is what makes the operation safe to run repeatedly, which is the same property Kubernetes controllers are built on.

It also rhymes with cache invalidation across the series. A DNS resolver holding a record that the authoritative zone has since changed is in the same position as a peer holding a stale entry in Adj-RIB-Out: some pass has to notice the divergence and push a correction. The difference is direction — DNS pulls on TTL expiry, BGP pushes on recompute — but the state comparison at the center is identical.

Check yourself

Close the article and open the file. Can you answer these from the code alone?

A peer's export policy is edited so a prefix that was permitted is now denied, but Loc-RIB is unchanged. Walk refresh_exports_for_prefix() for that peer — which branch fires, and what ends up in the returned list?
refresh_exports_for_prefix() is called twice in a row with identical inputs. What does the second call return, and what in the code guarantees it?
A peer has never been advertised a prefix, and best-path selection removes that prefix from Loc-RIB. Does that peer get a WITHDRAW? Which line decides, and why is that the correct protocol behavior rather than an optimization?

You're done with this session when you can explain why export refresh is a separate pass after recompute, and when you can look at current and desired for a peer and say — without running anything — whether that peer sees an advertise, a withdraw, or silence.

Established is not a status label — it's a write permission

pathvector-dev — Thu, 30 Jul 2026 00:00:09 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-11/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols not as configuration examples but as logic — inputs, state, and branches. Every session points at a small Python file and asks you to read it the way you'd read any other program. The source lives at github.com/pathvector-studio/protocol-in-code.

Note: If you're earlier in the journey and want hands-on packet-level exercises before diving into implementation logic, start with the Protocol Lab series instead. This series assumes you're comfortable reading Python and want to know why the branch is where it is.

The question

Here's the one to keep turning over as you read:

What has to be true before the control plane should accept an UPDATE from a neighbor?

That question sounds like it should have a long answer. Route validity, attribute well-formedness, policy, next-hop reachability, max-prefix limits — a real BGP implementation checks all of it. But before any of that, there's a gate so simple it's easy to skip past entirely, and it's the one this session isolates.

The previous session built an integrated pipeline: an UPDATE arrives, gets stored, gets compared, gets selected. It worked. But it quietly assumed something — that the route arriving at the front of the pipeline had already earned the right to be there. This session makes that assumption explicit and gives it a name.

Read the file in three moves

The file is src/protocol_in_code/bgp/peer_state.py, with src/protocol_in_code/bgp/session.py as its companion. It's short enough that you could read it top to bottom in thirty seconds and learn nothing. Read it in this order instead.

1. What a peer actually is

@dataclass(frozen=True)
class PeerSession:
    peer_id: str
    config: BGPSessionConfig
    state: SessionState


def open_peer_session(peer_id: str, config: BGPSessionConfig) -> PeerSession:
    return PeerSession(peer_id=peer_id, config=config, state=establish_neighbor(config))

open_peer_session() does almost nothing. It takes an identifier and a config, calls establish_neighbor() from session.py, and staples the resulting state onto a frozen dataclass. That's the whole constructor.

The thing worth noticing is what it doesn't do. It doesn't retry. It doesn't leave the state mutable so a later step can nudge a peer into Established because the operator wants the route. The dataclass is frozen=True: whatever establish_neighbor() decided, that's the peer's state for the lifetime of this object. The session outcome is an input to everything downstream, not something downstream code negotiates with.

So PeerSession isn't really a connection object. It's a decision, packaged.

2. The gate, stated as one question

def session_accepts_updates(peer: PeerSession) -> bool:
    return peer.state is SessionState.ESTABLISHED

One line. One comparison. No or, no fallback, no "well, OpenConfirm is close enough."

The function name is doing real work here — it could have been called is_established(), which would describe the state. Instead it's named for the consequence: does this session accept updates? That naming is the whole point of the session. Established isn't a label you read off a show bgp summary output to feel good about. It's the answer to a permission question that gets asked on every inbound UPDATE.

Note the is rather than ==. SessionState is an enum, and identity comparison means there's exactly one object that satisfies this check. There's no clever coercion, no truthy near-miss. Either the peer holds that exact enum member or it doesn't.

3. Where the `if` sits

def receive_update_if_established(
    adj_rib_in: AdjRIBIn,
    peer: PeerSession,
    prefix: str,
    attributes: PathAttributes,
) -> bool:
    if not session_accepts_updates(peer):
        return False

    store_received_path(adj_rib_in, peer.peer_id, prefix, attributes)
    return True

This is the entire lesson, and it's four lines of body.

The important thing is not the amount of code. It is the placement of the if.

Look at what's on each side of the early return. Above it: nothing has happened. Below it: a write into Adj-RIB-In. There is no path through this function where a route lands in the RIB without first passing session_accepts_updates(). Not "gets stored and then filtered later." Not "gets stored with a flag." The write is structurally downstream of the check.

Compare that to the alternative you've probably seen in real codebases:

# NOT what this module does — the shape to avoid
store_received_path(adj_rib_in, peer.peer_id, prefix, attributes)
if not session_accepts_updates(peer):
    mark_as_pending(adj_rib_in, peer.peer_id, prefix)  # ...

Same information, same check, completely different guarantee. In that version, Adj-RIB-In contains routes from peers that never reached Established, and correctness depends on every reader downstream remembering to filter. In the version the module actually implements, Adj-RIB-In has an invariant: everything in it came from an established session. Downstream code doesn't have to re-check, because the shape of the function made the bad state unrepresentable.

That's why the return type is bool and not None. The caller gets told whether the write happened. A silent no-op would be a worse API — the caller couldn't distinguish "stored" from "dropped at the gate."

Note: The store_received_path() call takes peer.peer_id as the key, not the prefix alone. Adj-RIB-In is per-peer by construction — which is exactly why the gate can be per-peer too. If the RIB were flat, the gate would have to live somewhere messier.

Same shape, different protocol

This gate is worth recognizing because you've already met it under other names.

A TLS session that hasn't completed the handshake can carry bytes — the TCP connection is up, the socket is writable — but application data sent before Finished isn't protected by the negotiated keys, and a correct implementation refuses to hand it to the application. Same shape: transport reachability is not the same thing as protocol readiness, and the code has to enforce the difference with a branch, not a comment.

Or take conntrack: a packet matching an existing flow tuple gets fast-pathed, but only if the state machine says the flow is ESTABLISHED. A packet arriving for a SYN_SENT entry takes a different branch entirely. Again: the state isn't decoration, it's the gate on which code path runs.

In all three cases the mistake looks identical — treating "the pipe is open" as "the protocol is ready." BGP is just the clearest place to see it, because the state has a name printed in every operator's terminal, and it's easy to read that name as a status indicator rather than as a precondition.

Toy model boundary

This is where the series stays honest with you.

This lesson isolates only the session-state gate. Established is the first gate in this toy model — it is not the only gate a real implementation uses, and reading it as such will mislead you.

Specifically, what's missing:

Address-family activation. A real BGP session negotiates which AFI/SAFI pairs are active. A peer can be perfectly Established for IPv4 unicast and still have no business sending you IPv6 or VPNv4 routes. The toy model has one implicit address family and no per-family gate.
Negotiated capability checks. Multiprotocol extensions, route refresh, add-path, 4-byte ASN handling — all negotiated during OPEN, all things that change what an UPDATE is even allowed to contain. None of that exists here.
The rest of the state machine. establish_neighbor() collapses what RFC 4271 models as Idle → Connect → Active → OpenSent → OpenConfirm → Established into a single call with a single outcome. There are no hold timers, no keepalives, no transitions out of Established. In a real implementation, a peer can be established at the moment an UPDATE arrives and gone by the time it's processed.
Inbound policy. Passing the session gate gets a route into Adj-RIB-In. In a real router, inbound route-maps, prefix lists, and max-prefix limits all sit between the wire and that store.

The reason the toy model cuts all of it is that each of those gates has the same structural shape as the one you just read — a boolean question placed before a write. Once you can see the shape clearly in four lines, the real implementation's dozen gates read as variations rather than as new material.

Run it

The walkthrough is runnable:

PYTHONPATH=src python3 examples/bgp/session_11_walkthrough.py

Three things to watch for in the output:

One peer whose TCP reachability never gets it to Established. The transport is fine. The session isn't. Watch what session_accepts_updates() returns for it.
One peer whose UPDATE is accepted. Trace it through receive_update_if_established() and confirm it takes the path past the early return.
Only the established peer appearing in Adj-RIB-In. This is the invariant made visible. The rejected peer left no trace — no partial entry, no pending flag, nothing to clean up later.

That third point is the one to sit with. The absence in the RIB is the whole result.

Check yourself

Answer these by reading the source, not by reasoning from what you know about BGP. If you have to guess, go back to the file.

A peer's TCP connection is established and packets are flowing, but session_accepts_updates() returns False. Where exactly in peer_state.py does an inbound route get stopped, and what is left behind in Adj-RIB-In afterward?
Suppose you moved the store_received_path() call above the if and returned False afterward anyway. What invariant about Adj-RIB-In would break, and which downstream reader would notice first?
PeerSession is frozen=True. If a peer's session dropped out of Established after open_peer_session() returned, what in this file would detect it — and what does your answer tell you about which parts of the state machine this toy model doesn't have?

You're done with this session when you can explain why Established is a write permission rather than a status label, and point at the exact if that keeps a route out of Adj-RIB-In.

One route, one function chain: reading a BGP pipeline as code

pathvector-dev — Wed, 29 Jul 2026 00:00:18 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-10/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic rather than configuration — inputs, state, branches, and the functions that connect them. The full source lives at pathvector-studio/protocol-in-code, and every module reads one real Python file you can open alongside the article. If you're newer to this and want to build up hands-on muscle first, start with the companion Protocol Lab series, then come back here.

This is Session 10 of the BGP track, and it's the integration lesson. Sessions 01 through 09 taught the pieces in isolation: attributes, validation, import policy, best-path selection, RIB storage, export. Each one made sense on its own. None of them told you what actually happens to a route.

The core question

If you trace one received route end to end, which functions touch it before it becomes an advertisement or disappears?

That's the question to keep turning over while you read. Not "what does best-path do" — you already know that. The question is about the chain: what order, what state changes where, and which step is responsible for each decision.

The file is src/protocol_in_code/bgp/pipeline.py. It's short. That's the point — the integration should be small enough to hold in your head all at once.

The shape, before the details

Strip the pipeline down to its skeleton and it looks like this:

store_received_path(adj_rib_in, peer_id, prefix, attributes)
for _, received_attributes in received_attributes_for_prefix(adj_rib_in, prefix):
    validation_state, action, installable = evaluate_candidate(prefix, received_attributes, vrps, policies)
best = select_best_path(installable_candidates)
install_best_path(loc_rib, best)
exported = prepare_export(best, export_peer_type, policies.export_policy)

Five lines, five phases: store, evaluate, select, install, export. Everything else in the file is either a data structure that keeps those phases from bleeding into each other, or a branch handling the case where a phase produces nothing.

Read it in this order and it unfolds cleanly:

PipelinePolicies
PipelineResult
evaluate_candidate()
apply_policy_action()
process_single_route()

Two dataclasses that do the structural work

Start with the inputs and outputs, because they tell you what the pipeline thinks its own boundaries are.

@dataclass(frozen=True)
class PipelinePolicies:
    import_policy: ImportPolicy
    validation_policy: ValidationPolicy
    export_policy: ExportPolicy

Three separate policy objects, not one blob of configuration. Import policy decides whether a route enters at all. Validation policy decides what an RPKI outcome means for this operator. Export policy decides what leaves. In a real speaker these live in different config sections for good reason, and the toy keeps that separation visible in the type.

@dataclass(frozen=True)
class PipelineResult:
    prefix: str
    received_validation_state: ValidationState
    received_action: PolicyAction
    candidate_count: int
    selected_path: PathCandidate | None
    selected_exported_path: PathCandidate | None

This one is worth staring at. Notice that it reports two different things about the same call:

received_validation_state and received_action describe the route that just arrived.
selected_path and selected_exported_path describe whatever won for the prefix.

Those are not the same route. A perfectly valid route can arrive, pass validation, pass import policy, survive policy action — and still lose best-path to an incumbent. candidate_count is the tell: it exists so you can see that the pipeline compared N survivors, not that it rubber-stamped the one route you happened to feed it.

Note: Most toy pipelines you'll find online collapse this into a single "did the route get installed" boolean. That collapse is exactly what makes them useless as a mental model — it hides the fact that arrival and selection are separate events with separate outcomes.

Bridging two sessions with one function

def origin_as_from_attributes(attributes: PathAttributes) -> int:
    if not attributes.as_path:
        return 0
    return attributes.as_path[-1]

Four lines, and they're the seam between Session 02 (attributes) and Session 04 (validation). Validation wants a BGPRoute with an origin_as. What actually arrived on the wire was a PathAttributes with an AS_PATH. Something has to convert one into the other, and in this pipeline it's this function.

It takes the rightmost AS in the path. Hold onto that — we'll come back to it when we talk about what this model leaves out.

Where a route lives or dies

evaluate_candidate() is the heart of the file:

def evaluate_candidate(
    prefix: str,
    attributes: PathAttributes,
    vrps: list[VRP],
    policies: PipelinePolicies,
) -> tuple[ValidationState, PolicyAction, PathCandidate | None]:
    route = BGPRoute(prefix=prefix, origin_as=origin_as_from_attributes(attributes))
    validation_state = validate_origin(route, vrps)
    raw_candidate = candidate_from_attributes(prefix, attributes)
    imported = apply_import_policy(raw_candidate, validation_state, policies.import_policy)
    if imported is None:
        return validation_state, PolicyAction.REJECT, None

    action = decide_route_policy(validation_state, policies.validation_policy)
    installed = apply_policy_action(imported, action)
    return validation_state, action, installed

Read the order carefully, because the order is the lesson.

Validation runs first, and it produces a ValidationState — Valid, Invalid, NotFound. It does not reject anything. It just labels.

Then apply_import_policy() gets both the candidate and that label. This is the first place a route can vanish: if import policy returns None, the function short-circuits and reports PolicyAction.REJECT. The route never reaches best-path.

If it survives import, decide_route_policy() translates the validation state into a PolicyAction under the operator's validation policy. And that is a separate decision from the label itself. An RPKI-invalid route doesn't have to be dropped; the operator decides.

The action is then applied:

def apply_policy_action(
    candidate: PathCandidate,
    action: PolicyAction,
) -> PathCandidate | None:
    if action is PolicyAction.REJECT:
        return None
    if action is PolicyAction.DEPRIORITIZE:
        lowered = max(0, candidate.local_pref - 50)
        return replace(candidate, local_pref=lowered)
    return candidate

Three branches, three outcomes. REJECT removes the candidate. DEPRIORITIZE keeps it but knocks 50 off local_pref, floored at zero — the route stays eligible, it just loses ties it would otherwise win. Anything else passes through untouched.

This is the distinction that survives all the way into the full pipeline: a validation result is not a decision. ValidationState is a fact about the route. PolicyAction is what this operator has chosen to do about that fact. Two separate values, computed by two separate functions, both reported separately in PipelineResult.

The full chain

Now process_single_route(), which is where the state actually moves:

    store_received_path(adj_rib_in, peer_id, prefix, attributes)

    validation_state, action, _ = evaluate_candidate(prefix, attributes, vrps, policies)

    installable_candidates: list[PathCandidate] = []
    for _, received_attributes in received_attributes_for_prefix(adj_rib_in, prefix):
        _, _, installable = evaluate_candidate(prefix, received_attributes, vrps, policies)
        if installable is not None:
            installable_candidates.append(installable)

The first line stores the raw received path in Adj-RIB-In — before any policy, before any validation, before any selection. That ordering matters and it isn't an accident: Adj-RIB-In holds what the peer said, not what you decided about it.

Then two evaluations happen, and they look redundant until you notice the discard. The first call's result is kept for reporting (validation_state, action) with the candidate thrown away via _. The loop then re-evaluates every stored path for the prefix, including the one that just arrived, and collects the survivors. That's the difference between "what did this update do" and "what does the prefix look like now."

The empty case comes next, and it's the branch most toy models skip entirely:

    if not installable_candidates:
        remove_best_path(loc_rib, prefix)
        withdraw_staged_advertisement(adj_rib_out, export_peer_id, prefix)
        return PipelineResult(
            prefix=prefix,
            received_validation_state=validation_state,
            received_action=action,
            candidate_count=0,
            selected_path=None,
            selected_exported_path=None,
        )

If nothing survives, stale state has to go. Loc-RIB loses its entry, Adj-RIB-Out loses its staged advertisement. A pipeline that only handles the happy path leaves a withdrawn route advertised forever — which is a real bug class, not a hypothetical.

Otherwise:

    best = select_best_path(installable_candidates)
    install_best_path(loc_rib, best)
    exported = prepare_export(best, export_peer_type, policies.export_policy)
    if exported is not None:
        stage_advertisement(adj_rib_out, export_peer_id, exported)
    else:
        withdraw_staged_advertisement(adj_rib_out, export_peer_id, prefix)

select_best_path() compares all survivors — this is the only place multiple candidates meet. install_best_path() writes to Loc-RIB. prepare_export() transforms the winner for the outbound peer, and can still return None, in which case the advertisement gets withdrawn rather than staged.

Three RIBs, three different moments:

RIB	Holds	Changes at
Adj-RIB-In	raw received attributes, per peer	the very first line, before anything is decided
Loc-RIB	the selected `PathCandidate`	after best-path selection
Adj-RIB-Out	the export-transformed candidate	after export policy, per outbound peer

They hold different objects and they change at different points. That's the sentence to be able to say without notes.

Same shape, different protocol

The structure here — store what arrived, label it, decide what the label means, select among survivors, transform for output — is not BGP-specific. It's the shape of every control plane that accepts untrusted input and has to publish a decision.

DNS resolvers do it: the cache holds what the authoritative server said (Adj-RIB-In), DNSSEC validation labels it (ValidationState), local policy decides whether a bogus answer is served or SERVFAIL'd (PolicyAction), and the answer that goes back to the client is a transformed view of the stored record (Adj-RIB-Out). The names differ; the branches are the same.

Once you can see that shape, reading a new protocol's control plane becomes a matter of finding where each stage lives rather than learning it from scratch.

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/bgp/session_10_walkthrough.py

It seeds one existing candidate first, then introduces a second valid route and recomputes the whole prefix through import policy, validation, policy action, best-path, Loc-RIB installation, and eBGP export. The printed PipelineResult distinguishes the received route's validation state and action from the selected route that actually won for the prefix — which is precisely the distinction that's easy to nod along to on the page and easy to get wrong in your head.

Watch candidate_count in the output. If it's ever 1 when you expected 2, you've learned something about where a route disappeared.

Toy model boundary

This is a pipeline, not a BGP speaker. Being specific about the gap:

No session layer. There's no peer state machine, no OPEN/KEEPALIVE/NOTIFICATION handling, no hold timers. process_single_route() assumes a route arrived from a peer that exists and is established. Real speakers spend most of their code on the part this file assumes away.

No event dispatch. A real speaker has an event loop: updates arrive, timers fire, sessions flap, and each event schedules work. Here you call a function and it runs to completion synchronously.

No export refresh after every recompute. The pipeline updates Adj-RIB-Out for the single export_peer_id passed in. A real speaker re-evaluates export for all peers whenever Loc-RIB changes, and handles route refresh requests. This model does one peer, one call.

Origin AS is a shortcut. origin_as_from_attributes() takes the rightmost AS in AS_PATH. That's a teaching simplification. Real origin determination has to deal with AS_SET segments, AS path prepending edge cases, confederations, and empty paths from iBGP-originated routes. The function returns 0 for an empty path, which is a sentinel, not a real AS.

The integration order is a choice. The course separated best-path, validation, and policy so each could be learned alone. Reconnecting them required picking an order, and this pipeline lets validation influence import and policy before local installation. Real implementations put those boundaries in different places — some run RPKI validation earlier, some fold it into import policy entirely. The order here is pedagogically clean, not canonical.

No withdrawal handling from peers. Stale state is cleaned up when nothing survives evaluation, but there's no path for a peer explicitly withdrawing a prefix.

None of these make the model wrong. They make it small — and small enough to read is the whole point. But don't carry the diagram in this file into a conversation about a production speaker without carrying these caveats too.

Check yourself

Close the article and answer these from the source alone. If you have to guess, open pipeline.py and trace it.

Which single step can drop a candidate before it ever reaches best-path — and what does the pipeline report as the action when that happens?
Which step lowers local preference without rejecting the route, and what's the floor?
Which step is the only one that compares multiple surviving candidates, and which step changes the outbound AS path?

They're not trick questions. Every answer is a specific function name in a 130-line file.

When a BGP peer disappears, one session loss becomes many route decisions

pathvector-dev — Wed, 29 Jul 2026 00:00:10 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-09/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. Every module points at one small Python file and asks you to read it the way you'd read any other piece of code. The source lives at github.com/pathvector-studio/protocol-in-code.

Note: If you're earlier on the path and want hands-on packet-level exercises before diving into implementation logic, start with the companion Protocol Lab series instead.

The question

What happens to Loc-RIB when one peer disappears and the best path came from that peer?

Hold onto that while you read. It sounds like a single question, but it hides at least four: how many routes are affected, which store changes first, what replaces the lost path, and what happens when nothing can.

The operational answer everyone knows is "the routes go away." That's true and useless. It doesn't tell you why some prefixes survive a peer loss with a brief reconvergence and others vanish entirely, or why a peer that advertised 500 prefixes generates 500 independent decisions rather than one.

The code answer is more precise, and it's about thirty lines long.

Where this sits

Session 06 introduced per-peer received state — the idea that Adj-RIB-In isn't one flat table but a mapping keyed by peer, with each peer's advertisements kept separately. That structure is what makes this session possible. If you'd stored all received paths in a single undifferentiated table, "which routes came from this peer?" would be a scan; with per-peer state it's a key lookup.

The file we're reading is src/protocol_in_code/bgp/recompute.py. Read it in this order:

recompute_best_path_for_prefix() — the single-prefix decision
handle_peer_loss() — the loop that applies it
How lost prefixes are collected from one peer
How each affected prefix is recomputed independently

Read it like code

Start with the smaller function, because the bigger one is just a loop around it:

def recompute_best_path_for_prefix(
    adj_rib_in: AdjRIBIn,
    loc_rib: LocRIB,
    prefix: str,
) -> PathCandidate | None:
    candidates = build_candidates(adj_rib_in, prefix)
    if not candidates:
        remove_best_path(loc_rib, prefix)
        return None

    best = select_best_path(candidates)
    install_best_path(loc_rib, best)
    return best

Four lines of logic and one branch. That branch is the whole story.

build_candidates(adj_rib_in, prefix) reads the current contents of Adj-RIB-In and assembles every path anyone is still advertising for this prefix. Note the tense: current. This function has no memory of what used to be there and no notion of "the peer that just went down." It sees state, not events.

Then the branch. If the candidate set is empty, there is nothing to install, so remove_best_path() deletes the Loc-RIB entry and the function returns None. If the set is non-empty, select_best_path() runs the decision process over the survivors and install_best_path() writes the winner into Loc-RIB.

Read that carefully and notice what isn't there: the function never asks "was the previous best path from the dead peer?" It doesn't compare old and new. It doesn't need to. It recomputes from scratch and overwrites. This is the difference between an event-driven and a state-driven design, and BGP implementations lean state-driven for exactly this reason — recomputing from current state is much harder to get wrong than incrementally patching a decision.

The loop that makes it plural

Now the outer function:

def handle_peer_loss(
    adj_rib_in: AdjRIBIn,
    loc_rib: LocRIB,
    peer_id: str,
) -> dict[str, PathCandidate | None]:
    lost_prefixes = tuple(adj_rib_in.paths_by_peer.get(peer_id, {}).keys())
    adj_rib_in.paths_by_peer.pop(peer_id, None)

    results: dict[str, PathCandidate | None] = {}
    for prefix in lost_prefixes:
        results[prefix] = recompute_best_path_for_prefix(adj_rib_in, loc_rib, prefix)
    return results

Three things happen, strictly in order, and the ordering is not incidental.

First, snapshot. lost_prefixes is materialized as a tuple before anything is mutated. That tuple(...) isn't stylistic — it copies the keys out of the dict so the subsequent pop doesn't invalidate what we're about to iterate over. This is the list of prefixes that were affected, captured at the moment of loss.

Second, delete. adj_rib_in.paths_by_peer.pop(peer_id, None) removes the entire per-peer subtree. Every path that peer ever advertised is gone from received state in one operation. The None default means calling this for an unknown peer is a no-op rather than a KeyError — losing a peer you weren't tracking should be harmless.

Third, recompute. Only after the deletion does the loop run. This ordering answers one of the questions you should be holding: Adj-RIB-In changes first, Loc-RIB second. It has to. recompute_best_path_for_prefix() calls build_candidates(), which reads Adj-RIB-In — if the dead peer's paths were still in there, build_candidates() would happily hand them back and the peer's paths could get reinstalled as best. The deletion isn't cleanup after the decision; it's the input to it.

The for loop is where "one session loss" becomes "many route decisions." One peer, N prefixes, N independent invocations of the decision process. There is no batching, no shared state between iterations, no notion of "the peer went down" inside the per-prefix function at all. Each prefix asks the same question in isolation: given who's still advertising, what's best now?

And each can get a different answer:

Situation	Outcome
Another peer also advertises this prefix	`build_candidates()` returns a non-empty set, `select_best_path()` picks a survivor, Loc-RIB gets a new best path
The dead peer was the only source	`build_candidates()` returns empty, `remove_best_path()` fires, prefix disappears from Loc-RIB
The dead peer wasn't best for this prefix anyway	Recomputation runs regardless and reinstalls the same winner

That third row is worth sitting with. The code doesn't optimize it away. It recomputes prefixes whose best path was never in danger, because checking "was this prefix's best path from the dead peer?" is itself a decision that can be wrong, while recomputing is unconditionally correct. Correctness first; a real implementation would add the optimization later, guarded carefully.

The return value — dict[str, PathCandidate | None] — is the outcome of every one of those decisions. A PathCandidate means a path survived or replaced; None means the prefix is gone. The | None in the type signature is the withdrawal case made explicit in the type system.

Same shape, elsewhere

The pattern here isn't BGP-specific: maintain per-source state, and when a source disappears, delete its contribution and re-derive the aggregate from what's left.

DNS resolvers do this when a nameserver stops responding — the cached RRsets attributed to it become unusable, and resolution falls back to re-deriving an answer from the remaining authoritative servers. Link-state protocols do it when an LSA ages out: remove the contribution, rerun SPF over the surviving topology. Even TCP's congestion state has the shape, one level down — a loss signal doesn't patch cwnd incrementally so much as re-derive it from the current state of the connection.

The alternative design — event-driven incremental patching, where "peer down" tries to surgically fix only the Loc-RIB entries it believes are affected — is faster and much easier to get subtly wrong. Every protocol that has tried it has accumulated a long tail of "stale entry" bugs. The recompute-from-current-state shape trades CPU for the guarantee that the output is always a function of the present input.

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/bgp/session_09_walkthrough.py

It installs a best path from one peer, simulates that peer going down, and shows the backup path taking over. Watch the transition specifically: the prefix stays in Loc-RIB but its best path changes identity. Then modify the script to remove the second peer's advertisement and run it again — now the same code path produces a disappearance instead of a substitution. Same function, same branch, different candidate set.

Toy model boundary

This module is a reading aid, not a BGP implementation. Be clear about what it leaves out:

No BGP session machinery. handle_peer_loss() is called by you, with a peer_id string. Real peer loss is detected by the FSM — hold timer expiry, TCP reset, NOTIFICATION received, an explicit administrative shutdown — and each of those has different timing characteristics. Hold-timer detection can take tens of seconds; a TCP RST is near-instant. The model has no timers at all.
No withdrawal propagation. In the real protocol, changes to Loc-RIB feed Adj-RIB-Out and generate UPDATE messages toward other peers, subject to export policy. Here, the function returns a dict and stops. Everything downstream of the local decision is absent.
No route flap damping, no MRAI. Real BGP deliberately slows reconvergence: the MinRouteAdvertisementInterval timer rate-limits how often a prefix's changes go out, and damping penalizes prefixes that flap. This model reconverges instantaneously and without hysteresis, which is precisely the behavior operators spend effort suppressing.
No graceful restart. RFC 4724 exists so that a peer going down doesn't immediately trigger this code path — routes are marked stale and retained while the peer restarts. The model has no stale-route concept and no restart signalling; loss is always immediate and total.
Delete-then-recompute is not atomic. The pop happens, then the loop runs. In between, Adj-RIB-In and Loc-RIB disagree. A single-threaded toy never observes that window, but real implementations have concurrent readers and need locking or versioning to keep anyone from reading the inconsistent middle state.
select_best_path() is simplified. The decision process here is a reduced version of the real tie-break ladder in RFC 4271 §9.1, and the model has no ADD-PATH, no multipath, no RIB failure states.
Cost is not modeled. N prefixes means N recomputations. With a full table that's ~1M invocations, and real implementations do a great deal of work — prefix indexing, batched walks, deferred best-path runs — to make peer loss survivable. The model's flat loop makes the logic obvious and the performance question invisible.

Check yourself

Can you answer these just by reading the source? Don't take my word for any of it — go verify against recompute.py.

Which store changes first, Adj-RIB-In or Loc-RIB — and what would break if you swapped the order? Trace what build_candidates() would return if pop ran after the loop instead of before it.
Under exactly what condition does a prefix disappear from Loc-RIB entirely? Find the single expression that decides it, and name the state that has to hold across all remaining peers.
Why is lost_prefixes built with tuple(...) rather than used directly as a dict view? What concretely goes wrong if you drop the tuple() call?

You've got this module when you can say, without notes: peer loss deletes Adj-RIB-In state for that peer first; then each affected prefix is recomputed independently; a backup path can become best; and if no backup exists, the Loc-RIB entry disappears.

Export policy decides what leaves: reading BGP outbound state as code

pathvector-dev — Mon, 27 Jul 2026 16:00:23 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-08/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. Each module points at one small Python file and asks you to read it the way you'd read any other code: what comes in, what gets mutated, where does it return early. The source lives at github.com/pathvector-studio/protocol-in-code.

Note: If you're earlier in the journey and want to do things with protocols before dissecting them, start with the hands-on Protocol Lab series instead — it builds the muscle memory this series assumes.

The question

Here's the thing that trips people up when they first look at a real BGP table: why is the route we advertise to a peer not always identical to the route we installed locally?

You run show ip bgp on a router, you see a prefix with a next-hop and an AS path. You run the equivalent command on the peer that received it from you, and the fields don't match. The next-hop changed. The AS path grew. Sometimes the prefix isn't there at all — even though it's clearly still installed on your side.

None of this is mysterious once you stop thinking of advertisement as "copying the table over the wire." It isn't a copy. It's a transform, and it lives in its own function with its own inputs. Session 06 already established that Adj-RIB-Out is a separate place where outbound state lives. This session gives that outbound state its own policy step.

The file

Everything in this module happens in src/protocol_in_code/bgp/export_policy.py. It's short enough to hold entirely in your head, which is the point.

Read it in this order: PeerType, then ExportPolicy, then prepare_export(). Inside prepare_export(), notice four things in sequence — the deny check, next_hop_self, the eBGP branch, and what the function actually returns.

Two peer types, because export isn't uniform

class PeerType(str, Enum):
    EBGP = "ebgp"
    IBGP = "ibgp"

That's the whole enum. It exists because the export path branches on it — eBGP export and iBGP export do not look the same, and the code makes that structural rather than incidental. If you've only ever configured BGP through a vendor CLI, this is worth pausing on: the peer type isn't a label on a neighbor statement, it's a branch condition in the outbound path.

The policy is data, not behavior

@dataclass(frozen=True)
class ExportPolicy:
    local_as: int
    next_hop_self: bool = False
    deny_prefixes: tuple[str, ...] = ()
    extra_prepend_count: int = 0

Four fields, each of which corresponds to something you've probably typed into a router config without thinking about it as a function parameter:

deny_prefixes — the set of prefixes that never leave, regardless of what's installed locally.
next_hop_self — whether outbound state gets a rewritten next-hop.
local_as — what gets prepended on eBGP export.
extra_prepend_count — deliberate path inflation, the traffic-engineering knob.

The dataclass is frozen=True, and that matters for how you read the next function. Policy is immutable input. The path is immutable input. Everything that happens in prepare_export() produces a new object.

Reading `prepare_export()`

Here's the function in full:

def prepare_export(
    path: PathCandidate,
    peer_type: PeerType,
    policy: ExportPolicy,
) -> PathCandidate | None:
    if path.prefix in policy.deny_prefixes:
        return None

    exported = path
    if policy.next_hop_self:
        exported = replace(exported, next_hop="self")

    if peer_type is PeerType.EBGP:
        prepend_count = 1 + policy.extra_prepend_count
        exported = replace(
            exported,
            as_path=((policy.local_as,) * prepend_count) + exported.as_path,
        )

    return exported

Look at the signature first. It takes a PathCandidate and returns PathCandidate | None. That None in the return type is doing a lot of conceptual work — it's the type system telling you that "there is a best path" and "the peer hears about it" are two separate propositions.

The deny check comes first

    if path.prefix in policy.deny_prefixes:
        return None

This is the first statement in the function, before any transformation happens, and it returns None rather than raising, logging, or removing anything.

Notice what it does not touch: path is unchanged, and nothing anywhere in this function reaches back into Loc-RIB. A denied prefix is still installed. It's still the best path. Your forwarding table still uses it. The peer simply never hears about it.

That asymmetry is the single most useful thing in this module. "The route isn't in my table" and "the route isn't in my neighbor's table" are different failures with different fixes, and this early return is where the difference is made concrete.

Next-hop rewrite is a state divergence

    exported = path
    if policy.next_hop_self:
        exported = replace(exported, next_hop="self")

exported = path starts the transform chain by aliasing the input, then every step uses dataclasses.replace to build a new frozen instance. Read this as an accumulator: exported is the outbound view under construction, and path stays pristine as the locally installed view.

next-hop-self is the canonical case where those two views diverge. The local route points at whatever next-hop it learned. The advertised route points at you. Same prefix, same best-path decision, different attribute on the wire.

Note: next_hop="self" here is a symbolic placeholder, not a literal forwarding address rewrite. The toy model is showing you that outbound state can differ from local state and where that divergence is implemented — not the address arithmetic a real implementation performs.

The eBGP branch transforms the path

    if peer_type is PeerType.EBGP:
        prepend_count = 1 + policy.extra_prepend_count
        exported = replace(
            exported,
            as_path=((policy.local_as,) * prepend_count) + exported.as_path,
        )

Two things are packed into prepend_count = 1 + policy.extra_prepend_count. The 1 is the baseline: crossing an AS boundary means your AS number goes on the front of the path. The extra_prepend_count is deliberate — you're making the path look longer than it is, because path length is an input to somebody else's best-path selection and you'd rather they picked a different entrance.

The tuple arithmetic makes the semantics unambiguous. (policy.local_as,) * prepend_count builds a run of repeated AS numbers, and + exported.as_path puts them at the front. AS path is read left to right as most-recent-first; prepending is how you get there.

And the iBGP case? There's no else. When peer_type is IBGP, this block is skipped entirely and as_path passes through untouched — which is exactly right, because no AS boundary was crossed. The absence of code is the protocol behavior here.

Same shape, different protocol

Once you've seen this structure, you start noticing it elsewhere. The pattern is: a local decision produces internal state, and a separate policy step decides what portion of that state is externally visible, in what form.

DNS does this with authoritative zone data versus what a resolver actually returns to a client. TLS does it with the full certificate chain a server holds versus what it chooses to present in a given handshake. In every case the mistake is the same — assuming the outbound view is a read of the internal view rather than a transform of it. Debugging gets much faster when you stop asking "why doesn't my peer see it?" and start asking "which function decides what my peer sees, and what are its inputs?"

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/bgp/session_08_walkthrough.py

It runs three cases against the same input path: eBGP export, iBGP export with next-hop-self enabled, and a deny case where the route stays local but never gets advertised. Watching the same PathCandidate come out three different ways — and once as None — is more convincing than reading about it.

Source: examples/bgp/session_08_walkthrough.py

Toy model boundary

This is a teaching model, and it's worth being precise about what it isn't.

next_hop="self" is symbolic. A real implementation rewrites the NEXT_HOP attribute to an actual address — typically a local interface or loopback address chosen per session. The string "self" here is a marker that a rewrite happened, not a representation of the value.

The eBGP branch compresses several behaviors into one. Real eBGP export does more than prepend the local AS. It handles NEXT_HOP semantics that vary by topology and session type, MED treatment across AS boundaries, LOCAL_PREF stripping (a well-known attribute that must not cross an eBGP boundary), community handling, and more. This module collapses all of that into a single visible transformation so the shape — outbound state is transformed, not copied — is unmissable. Don't read the single prepend as a claim of completeness.

next_hop_self is presented as a boolean knob. In production, NEXT_HOP behavior on export depends on peer type, whether the route was learned from an eBGP or iBGP peer, whether it's a directly connected route, route-reflector configuration, and per-vendor defaults. Treating it as one flag is a teaching simplification, not a claim about default behavior in every real eBGP export case.

There is no route-reflector logic here. iBGP export in real deployments involves reflection rules, cluster lists, and originator IDs. This model's iBGP path is simply "skip the prepend."

Policy is a single function with four fields. Real export policy is a chain of route-maps and filter lists with match/set clauses evaluated in sequence, capable of modifying essentially any attribute. prepare_export() is one function with fixed branches so you can see the control flow rather than a policy DSL.

The boundary is the point, not an apology for it. The model is deliberately small enough that the branching structure is visible, and once you've internalized that structure the real implementations read as elaborations rather than mysteries.

Check yourself

Go back to the source and answer these without looking anywhere else. If you can't, you haven't read it closely enough yet.

Which single condition causes prepare_export() to return None — and what does the function do to the locally installed path in that case?
Under what circumstances does next_hop become "self", and does the peer type affect that at all?
Trace the value of exported.as_path for an iBGP peer versus an eBGP peer with extra_prepend_count=2. Which line is responsible for the difference, and which line is responsible for the absence of a difference?

If you can articulate why "installed route" and "exported route" are different objects in practice — and point at the exact lines that make them different — the module has done its job.

Import policy rewrites the route before best-path ever sees it

pathvector-dev — Mon, 27 Jul 2026 16:00:15 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-07/ — part of the free Protocol Lab series.

This post is part of Protocol in Code, a free series that reads network protocols as logic — inputs, state, and branches — rather than as configuration examples. Every module points at one real Python file and asks you to read it the way you'd read any other code: what comes in, what mutates, where does control leave early. The source lives at github.com/pathvector-studio/protocol-in-code.

Note: If you're newer to this and want to run things before you read things, start with Protocol Lab — the hands-on companion series that builds the muscle memory this one assumes.

The question

How does local import policy change or reject a path before best-path selection runs?

That's the whole module in one line, and it hides a claim worth being suspicious of. Best-path selection in BGP is the famous part — the ordered tiebreaker list everyone half-remembers: highest weight, highest local_pref, shortest AS path, and so on. It's easy to treat that comparison as the decision point, as if routes arrive from peers and get ranked.

They don't arrive and get ranked. They arrive, get rewritten, and then get ranked. Import policy is a function that runs between the wire and the comparison, and it has two powers: it can change the values the comparison reads, and it can make the candidate not exist at all.

Which means the interesting question isn't "who won best-path" but "what did best-path actually receive."

Read the code

The file is src/protocol_in_code/bgp/import_policy.py. It's short enough to hold in your head all at once, which is the point — the shape is the lesson.

Start with the policy object:

@dataclass(frozen=True)
class ImportPolicy:
    local_pref_override: int | None = None
    weight: int = 0
    reject_next_hops: tuple[str, ...] = ()
    reject_invalid: bool = False

Four knobs, and notice they're not four of the same thing. Two of them (local_pref_override, weight) change a value. Two of them (reject_next_hops, reject_invalid) delete the route. A frozen dataclass, so the policy itself is immutable — the policy doesn't accumulate state across candidates, it's just a description of a transformation.

Also notice the default of local_pref_override: it's None, not 0 or 100. That's load-bearing. weight defaults to 0 because zero is a meaningful weight; local_pref_override needs a sentinel because there's no integer that means "don't touch this."

Now the function:

def apply_import_policy(
    candidate: PathCandidate,
    validation_state: ValidationState,
    policy: ImportPolicy,
) -> PathCandidate | None:

The return type tells you the story before you read a single line of the body: PathCandidate | None. This function is allowed to return nothing. A path goes in and possibly no path comes out — the candidate is gone before best-path selection has any opinion about it.

Read the body in the order it executes:

    if candidate.next_hop in policy.reject_next_hops:
        return None

    if validation_state is ValidationState.INVALID and policy.reject_invalid:
        return None

Rejection first, both times. These are early returns, and their position matters: nothing gets rewritten before it gets dropped. There's no point spending work on a candidate that's about to stop existing, and — more importantly for reading — it means you can answer "does this route survive?" without reading the second half of the function at all.

The two rejections are different in kind. The first is unconditional local intent: this next-hop is on the list, so no. The second is conditional on a value computed elsewhere — validation_state comes in as a parameter, decided by validation logic this file never sees. And it's gated by policy.reject_invalid. Read that conjunction carefully:

    if validation_state is ValidationState.INVALID and policy.reject_invalid:

INVALID alone doesn't drop the route. The local operator has to have opted in. This is the module's real point about validation: validation produces a result, and policy decides what that result does. A route can be known-invalid and still sail through to best-path selection if reject_invalid is False. That separation — result versus action — is the thing Session 05 set up, and here's where it gets consumed.

Then the rewrite half:

    updated = candidate
    if policy.local_pref_override is not None:
        updated = replace(updated, local_pref=policy.local_pref_override)
    if policy.weight != updated.weight:
        updated = replace(updated, weight=policy.weight)
    return updated

replace() is dataclasses.replace — it builds a new frozen PathCandidate with one field swapped. Nothing mutates. updated is rebound, never modified in place, and the original candidate the caller passed in is still intact afterward. If you've been reading this codebase in order, that pattern should be familiar by now: every stage returns a new value rather than editing the one it received, which is what makes it possible to reason about a pipeline stage in isolation.

The two conditions guarding the rewrites are worth comparing side by side, because they don't match:

if policy.local_pref_override is not None: — a sentinel check. Is an override configured at all?
if policy.weight != updated.weight: — a difference check. Is the configured weight already what the candidate has?

The second one is an optimization more than a semantic: with the default weight=0 and a candidate that also has weight=0, you skip building a new object for no change. But it also means weight has no "unset" state. Leaving weight alone in your policy isn't neutral — it's asserting 0. If a candidate arrived with a non-zero weight from somewhere upstream, a policy that never mentions weight will still flatten it back to 0. Whether that's a bug or the intended semantics is exactly the kind of thing worth deciding for yourself by reading it.

What this does to best-path

Here's the connection that makes the module worth the time. local_pref and weight are not arbitrary fields — they're the top two inputs to the best-path comparison. Import policy writes directly into the highest-priority tiebreakers before the tiebreakers run.

So the pipeline is:

A peer sends you a path with whatever attributes it chose.
Validation produces a ValidationState for it.
apply_import_policy either drops it or hands back a modified copy.
Best-path selection compares what survived.

Step 4 has no idea steps 1–3 happened. It sees a PathCandidate with a local_pref and a weight and compares them, and it cannot distinguish "the peer sent this" from "we wrote this a microsecond ago." That's the sentence to walk away with: the candidate entering best-path is not always the one the peer originally sent.

This is also why "the same route looks different on different routers" isn't a mystery. Two routers receiving the identical UPDATE can hand two different candidates to their comparison logic, because import policy is local. Nothing about it is negotiated with the peer. The peer doesn't know and can't tell.

Same shape, different protocol

Once you've seen this shape you'll notice it everywhere: a transform stage that sits in front of a decision stage and quietly rewrites the decision's inputs.

It's the same structure as a firewall's mangle table rewriting packet marks before the routing decision reads them — the routing table lookup doesn't know the mark was synthetic. It's the same structure as a DNS resolver's local overrides answering before recursion happens. It's the same structure as a TLS stack's cipher-suite preference list reordering what the handshake "sees" as offered.

In each case the decision logic is honest and deterministic, and the interesting behavior lives entirely in what got fed to it. When a protocol surprises you, the transform stage in front of the decision is usually a better place to look than the decision itself.

Run it

The walkthrough is executable:

PYTHONPATH=src python3 examples/bgp/session_07_walkthrough.py

It runs four candidates through apply_import_policy: one that gets its local_pref rewritten, one that picks up a local weight, one dropped by the next-hop rule, and one invalid path rejected before best-path ever sees it. Watch which ones come back as objects and which come back as None — that binary is the entire first half of the function, made visible.

Then change the policy and run it again. Set reject_invalid=False and watch the invalid path survive. Set local_pref_override without weight and see exactly one field move.

Toy model boundary

This is a toy model, and being precise about what it isn't is the point of this section.

Real import policy is a rule chain, not a single struct. Vendor implementations evaluate an ordered list of route-map or filter clauses, each with match conditions and set actions, with terminating and continue semantics. ImportPolicy here is one flat set of unconditional knobs applied to every candidate — there is no "match prefix 10.0.0.0/8 then set local-pref 200, else next clause." That ordering and matching is most of the complexity of real policy, and none of it is here.

Only two attributes are writable. Real policy can rewrite MED, prepend or replace the AS path, add, remove, and modify communities and large communities, set the next-hop, tag the route, and more. This model touches local_pref and weight because those are the two that most cleanly demonstrate "policy writes best-path's inputs."

Rejection is a return value, not a state. Here a dropped path simply ceases to exist. Real implementations distinguish between filtered-at-input routes that are discarded and routes retained in an Adj-RIB-In (soft reconfiguration) so policy can be re-applied without bouncing the session. There's no RIB in this file at all.

weight isn't a protocol field. local_pref is a real BGP path attribute carried in UPDATE messages within an AS. weight is a vendor-local, Cisco-originated concept that never leaves the router and never appears on the wire. Putting them adjacent in one dataclass is pedagogically useful and protocol-wise a bit of a lie — worth knowing before you go looking for weight in a packet capture.

No prefix matching, no peer scoping, no direction. Real policy is bound per-neighbor and per-address-family, and there's a symmetric export policy on the other side doing the same kind of rewriting outbound. This function takes one candidate with no notion of which peer it came from.

Validation state arrives from nowhere. validation_state is a parameter. In a real system it comes from RPKI-to-Router state that changes asynchronously as VRPs are added and withdrawn, which raises re-evaluation questions this model doesn't have to answer.

Check yourself

Don't look these up — answer them by reading import_policy.py and then confirm with the walkthrough.

Exactly which conditions cause apply_import_policy to return None? Can you state both, including what has to be true for the second one to fire?
If a policy sets only local_pref_override and leaves everything else at its default, what does the returned PathCandidate look like? Be specific about weight — is it untouched, or not?
Why is rewriting an input a fundamentally different operation from rejecting a path? Both change the outcome of best-path selection. What can the downstream comparison logic tell about which one happened to it?

You should be able to finish this module able to say, without notes: import policy runs before best-path; it can rewrite local_pref and weight; it can drop a path before comparison; and the candidate entering best-path is not always the one the peer sent.

DEV Community: pathvector-dev

Which router wins the segment? Read the election, not the docs

The question

Where this comes from

Read it like code

1. What a candidate is

2. The comparison

3. The election

4. The result

Same shape, different protocol

Run it

Toy model boundary

Check yourself

Further reading

A Hello does not make a neighbor Full — the code says so in two stages

The question

The state space, and what it's hiding

Stage one: what a Hello can decide

Stage two: what the database exchange decides

Run it

Toy model boundary

Same shape, different protocol

Can you answer these from the code alone?

Further reading

An OSPF Hello has to match before it can mean anything

The question

The source

Two sides of a comparison

The gate, one branch at a time

Why saw_self is the interesting output

Run it

What this toy model leaves out

Check yourself

Further reading

A BGP speaker is just state plus three event handlers

The question

Everything that came before

Read the speaker as a bag of state

The three-line rhythm

The result type

Wiring and running it

Toy model boundary

Same shape, different protocol

Check yourself

Done when

Further reading

One prefix stops being one route: reading BGP's decision set as code

The question

Read the record before you read the loop

The loop that turns a prefix into a set

Selection happens last, and only on survivors

Same shape, different protocol

Run it

Toy model boundary

Check yourself

Further reading

Announce, withdraw, and peer down are three different code paths

The question

Three triggers, not one

The shape of the dispatch

Announce: gate first, then recompute

Withdraw: no gate, and it starts by deleting

Peer down: one event, many prefixes

Reading lens: the same shape shows up elsewhere

Run it

Toy model boundary

Check yourself

Done when

Further reading

When Loc-RIB changes, every peer needs a different answer

The question

Export is peer-specific, and the types say so

Three values, one peer

The branch that matters

Run it

Toy model boundary

The same shape shows up elsewhere

Check yourself

Further reading

Established is not a status label — it's a write permission

Why `saw_self` is the interesting output

3. Where the `if` sits

Reading `prepare_export()`