DEV Community: pathvector-dev

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.

Validation State Doesn't Act By Itself

pathvector-dev — Sun, 26 Jul 2026 16:00:19 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-05/ — 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 with inputs, state, and branches — actual code you can read and run. The whole series lives here: github.com/pathvector-studio/protocol-in-code. If you're newer to this material and want a more hands-on, guided on-ramp first, start with the companion Protocol Lab series and come back.

Today's module is from the BGP track, Session 05. The source file is src/protocol_in_code/bgp/policy.py, and it builds directly on the origin-validation logic from Session 04.

The question to keep in your head

Here's the one thing to turn over as you read:

What happens after origin validation returns valid, invalid, or not_found — and why does the result still need routing policy before anything happens to the route?

There's a piece of folk knowledge that says "RPKI invalid means the router rejects the route." It's the kind of statement that sounds like a rule of the protocol. It isn't. It's one possible policy decision built on top of a validation result. The whole point of this session is to separate those two things in your head, and the code makes the seam impossible to miss.

Two layers, not one

Validation answers a factual question: does this route's origin AS match what the ROAs say it should be? That's Session 04's job, and its output is a ValidationState.

Policy answers a completely different question: given that fact, what do we do? Drop the route? Keep it but make it less preferred? Accept it normally? That's a local decision — different operators configure it differently, and the same validation result can lead to different actions on different routers.

The file models the second layer with three small pieces. First, the set of actions the router can take:

class PolicyAction(str, Enum):
    ACCEPT = "accept"
    DEPRIORITIZE = "deprioritize"
    REJECT = "reject"

Notice there are three outcomes, not two. Reject is real, but so is "keep it, just prefer it less." That middle option is exactly what gets lost when people compress the whole thing to "invalid → drop."

Then the knobs — the local configuration that decides how those actions get chosen:

@dataclass(frozen=True)
class ValidationPolicy:
    reject_invalid: bool = False
    deprioritize_not_found: bool = False

Two booleans, both defaulting to False. Read the defaults carefully, because they're a statement in themselves: out of the box, this policy neither rejects invalid routes nor treats not-found routes with suspicion. The safe-sounding "invalid gets dropped" behavior is opt-in via reject_invalid, not the default.

Reading the decision

Everything comes together in one function. Read it top to bottom — the control flow is the specification:

def decide_route_policy(
    validation_state: ValidationState,
    policy: ValidationPolicy,
) -> PolicyAction:
    if validation_state is ValidationState.INVALID:
        if policy.reject_invalid:
            return PolicyAction.REJECT
        return PolicyAction.DEPRIORITIZE

    if validation_state is ValidationState.NOT_FOUND and policy.deprioritize_not_found:
        return PolicyAction.DEPRIORITIZE

    return PolicyAction.ACCEPT

Trace the branches as inputs, not as prose.

INVALID is handled first, and it never falls through to ACCEPT. Once the state is invalid, the only two reachable returns are REJECT and DEPRIORITIZE. Which one you get depends entirely on the reject_invalid knob:

reject_invalid=True → PolicyAction.REJECT — the route is dropped.
reject_invalid=False → PolicyAction.DEPRIORITIZE — the route stays in the table, just less preferred.

That inner if/else is the entire "reject vs. deprioritize" debate rendered as two lines. An invalid route does not disappear on its own; a human's configuration decided its fate.

NOT_FOUND only does something if you asked it to. The second branch fires only when the state is NOT_FOUND and deprioritize_not_found is set. Given how much of the routing table is still not covered by ROAs, "not found" is the common case, and the default here is to let it through:

deprioritize_not_found=True → PolicyAction.DEPRIORITIZE
deprioritize_not_found=False → falls through to the final return PolicyAction.ACCEPT

Everything else accepts. VALID, and any NOT_FOUND you didn't ask to deprioritize, land on the last line. There is no branch that turns a valid result into anything other than ACCEPT — validation success buys you normal treatment, nothing more.

Note: The absence of a branch is as informative as its presence. There's no path from VALID to REJECT, and no path from INVALID to ACCEPT. The reachable outcomes for each state are baked into the structure of the ifs — you can read the whole policy space just by asking which return each state can reach.

The reading move

The habit this session is trying to build is small but load-bearing. Stop saying:

"RPKI invalid means the router rejects the route."

Start asking three questions instead:

What validation state came back?
What local policy is configured?
What concrete action follows from that policy?

The answer to question 1 alone never determines the outcome. It's always 1 and 2, resolved by decide_route_policy, that produce question 3's answer.

This is the same shape you'll see over and over in the series once you start looking for it: a lookup or check produces a state, and a separate, locally-configured policy decides what that state means for behavior. It's the same split as a DNS resolver distinguishing "the record didn't validate" from "what do I serve the client," or a TLS stack distinguishing certificate-verification failure from the application's decision to proceed anyway. Validation is a fact. Policy is a choice. Keeping them in different functions is what lets one operator reject invalids while the next merely frowns at them.

Run it and watch the combinations

The walkthrough prints several combinations of validation result and local policy and shows the resulting action, so you can check your reading against the actual output:

PYTHONPATH=src python3 examples/bgp/session_05_walkthrough.py

Before you run it, try to predict each line. Pick a ValidationState, pick the two booleans, and walk the branches yourself. Then confirm. The goal isn't to memorize the output — it's to get to where the output holds no surprises because you already ran the function in your head.

Toy Model Boundary

This model is deliberately small, and it's worth being precise about what it leaves out, because the gap between this and a production router is large.

Only three actions exist here. Real BGP policy does far more than accept / deprioritize / reject. "Deprioritize" in the wild means concrete knobs — lowering LOCAL_PREF, prepending to the AS path, tagging communities — and the ranking interacts with the full best-path selection algorithm. This model collapses all of that into a single enum value.
Validation state is the only input. A real policy also weighs prefix length, neighbor, communities, AS-path contents, max-prefix limits, and more. Here, decide_route_policy sees exactly one signal.
Two boolean knobs stand in for a policy language. Production route policy is written in expressive, vendor-specific configuration (route-maps, RPL, routing-policy blocks) with ordering and match/set semantics. reject_invalid and deprioritize_not_found are a teaching-sized caricature of that surface.
No time, no churn, no state machine. There's no notion of ROA updates arriving, routes being re-evaluated, or the RPKI-to-Router protocol feeding fresh data. The function is a pure input-to-output decision, evaluated once.
The valid state gets no special treatment. RFC 6811 leaves room for policy that actively prefers valid routes; here, valid just means "accept normally," identical to an un-deprioritized not_found.

None of this makes the model wrong — it makes it readable. But when you move to real gear, expect the two-layer split to survive and everything downstream of it to get much larger.

Check yourself

Don't take my walkthrough as the answer. Open policy.py and see if you can answer these purely by reading the code — no running required:

What happens to an invalid route when reject_invalid is False? What about when it's True? Which line makes each true?
Can any configuration of ValidationPolicy turn a not_found route into a REJECT? Trace the branches and be sure.
Why is policy kept in a separate function and separate layer from validation at all — what would you lose if decide_route_policy had to do the validation itself?

If you can answer all three by pointing at specific lines, you've got the session.

Origin validation is a separate decision from best path

pathvector-dev — Sun, 26 Jul 2026 16:00:12 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-04/ — 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 full source, walkthroughs, and site lessons live in the repo: pathvector-studio/protocol-in-code. If you're newer to this and want to build the protocols hands-on before dissecting them, start with the companion Protocol Lab series instead.

Today we're on the BGP track, session 04, reading a single small file: src/protocol_in_code/bgp/validation.py. It's about 40 lines. The idea inside it is one that trips up a lot of engineers who've been running BGP for years.

The question to keep in your head

BGP's best path selection already ran. It compared local preference, AS_PATH length, MED, and the rest of the tiebreak ladder, and it picked a winner. So here's the question this module wants you turning over:

Core question: How do we decide whether the origin AS is authorized — even after BGP has already selected this route as the best path?

The trap is the sentence "it was the best path, so it must be fine." Best and authorized are two different words, and in the code they are two different decisions made by two different pieces of data. Best path selection asks which of these routes do I prefer? Origin validation asks is the AS at the end of this path actually allowed to originate this prefix? A route can win selection and still be a hijack.

RPKI origin validation is the mechanism that answers the second question, and the file we're reading is a toy model of exactly that.

Two kinds of information

The first thing to read isn't a function — it's the two dataclasses, because the whole session is really about keeping them apart.

@dataclass(frozen=True)
class BGPRoute:
    prefix: str
    origin_as: int


@dataclass(frozen=True)
class VRP:
    prefix: str
    max_length: int
    origin_as: int

BGPRoute is the BGP-side information — what a router learned from a neighbor. A prefix, and the AS that claims to originate it. That origin_as is the claim we're going to check.

VRP is the other side: a Validated ROA Payload. This is the authorization side, derived from RPKI. It says "this prefix range may be originated by this AS, down to this maximum length." A VRP is not a route. Nobody is forwarding traffic based on a VRP. It's an assertion about who is allowed to originate, published by the address holder and cryptographically validated upstream — by the time it reaches this code, it's just data: a prefix, a max_length, and an authorized origin_as.

Notice the asymmetry. The route has no max_length; the VRP does. That field is the whole reason coverage isn't just "is one prefix inside the other."

Coverage: is this route even in scope?

Before we can say valid or invalid, we have to ask whether any VRP even talks about this route. That's vrp_covers_route:

def vrp_covers_route(route: BGPRoute, vrp: VRP) -> bool:
    route_net = _route_network(route)
    vrp_net = _vrp_network(vrp)
    return route_net.subnet_of(vrp_net) and route_net.prefixlen <= vrp.max_length

Two conditions, both required. First, the route's prefix must be a subnet of the VRP's prefix — 192.0.2.0/24 is covered by 192.0.2.0/22, but 198.51.100.0/24 is not covered by either. Standard containment.

Second — and this is the part that surprises people — the route's prefix length must be less than or equal to the VRP's max_length. A VRP for 192.0.2.0/22 with max_length = 22 authorizes only the /22 itself. If someone originates 192.0.2.0/24, that /24 is geographically inside the /22 but its prefixlen (24) exceeds max_length (22), so subnet_of is true but the length check is false, and this VRP does not cover it.

That's deliberate. max_length is how an address holder says "I authorize this block, but not arbitrarily deaggregated announcements of it." Without that field, an attacker could announce a more-specific of your authorized prefix and ride your ROA. With it, a more-specific that exceeds max_length simply isn't covered by that VRP — and, as we're about to see, "not covered" has consequences.

The decision: three answers, not two

Here's the core of the session, validate_origin, and it's worth reading as three sequential branches rather than one function:

def validate_origin(route: BGPRoute, vrps: list[VRP]) -> ValidationState:
    covering_vrps = [vrp for vrp in vrps if vrp_covers_route(route, vrp)]
    if not covering_vrps:
        return ValidationState.NOT_FOUND

    if any(vrp.origin_as == route.origin_as for vrp in covering_vrps):
        return ValidationState.VALID

    return ValidationState.INVALID

Read it as a funnel.

First branch — is anything covering this route at all? Filter the VRP set down to the ones that cover the route. If that list is empty, we return NOT_FOUND and stop. We never even look at the origin AS. There is no VRP that has anything to say about this prefix, so we can't judge it.

Second branch — does a covering VRP authorize this origin? Among the covering VRPs, if any one has an origin_as equal to the route's origin_as, the route is VALID. The address holder authorized this AS to originate this prefix, and that's exactly who originated it.

Third branch — covered but not authorized. We fall through to INVALID. This only happens when the funnel got past the first branch: at least one VRP does cover this prefix, but none of the covering VRPs name this route's origin AS. Someone is originating a prefix that RPKI says belongs to a different AS.

The critical distinction is between NOT_FOUND and INVALID, and the branch order is what encodes it:

Note: not_found is not a weaker invalid. not_found means no covering VRP existed — we have no authorization data about this prefix, so we're not claiming anything. invalid means a covering VRP did exist and the origin AS contradicted it — we have data, and the route lost. One is silence; the other is a conflict. Real routers treat them very differently: not_found routes are commonly still accepted (much of the internet has no ROA yet), while invalid routes are increasingly dropped.

Three states, encoded as an enum so the caller has to handle them by name rather than juggling booleans:

class ValidationState(str, Enum):
    VALID = "valid"
    INVALID = "invalid"
    NOT_FOUND = "not_found"

Same shape, different protocol

The move this session is training — stop trusting the winner of one decision to answer a second, independent question — is not unique to BGP. It's a recurring shape.

The design of this module deliberately teaches origin validation as a separate concept, after best-path selection, so you learn to split "best" from "authorized." In production implementations the two can be wired together — validation state can feed route policy, adjust local preference, or gate installation — and a later session in this track uses one such toy integration on purpose. But the reason to read them apart first is that they are apart: selection ranks, validation authorizes, and conflating them is how a preferred hijack gets installed.

If you've read the DNS track, this is the same shape as validating a signed answer versus simply receiving one: getting an A record back doesn't mean it was authenticated. Winning the race to answer is not the same as being authorized to answer.

Run it and watch the branches fire

The walkthrough is runnable. It constructs routes and VRPs that land in each of the three states, plus the max_length edge case, and prints why each one resolved the way it did:

PYTHONPATH=src python3 examples/bgp/session_04_walkthrough.py

Watch specifically for the max_length scenario — a route that's a clean subnet of a VRP's prefix but comes back NOT_FOUND because its prefixlen overshot max_length. If you can predict that result before you run it, you've read vrp_covers_route correctly.

Toy model boundary

This is a teaching model, and it's honest to be precise about what it leaves out — because those omissions are exactly where the real complexity lives.

No cryptography. A real VRP is the output of validating a ROA: an RPKI-signed object, verified up a chain of resource certificates to a trust anchor. Here, VRP is a plain dataclass you hand-construct. All the signature checking, certificate path validation, and trust-anchor management that produces a validated payload happens before this code would ever run.
No RTR transport. In production, routers don't parse RPKI themselves; a relying-party validator does, and ships VRPs to the router over the RTR protocol (RFC 8210) with sessions, serial numbers, and incremental updates. Our vrps is just a Python list passed in.
IPv4 only. _route_network and _vrp_network call ip_network and the model assumes IPv4Network. Real validation is address-family agnostic and ROAs cover IPv6 too.
Origin only — never the path. This is the big one. validate_origin checks the origin AS: the last AS in the AS_PATH, the one claiming to originate the prefix. It says nothing about whether the intermediate hops in the path are legitimate, whether the announcement respects business relationships, or whether the path was forged after a valid origin. That's the domain of BGPsec and ASPA, and it's entirely outside this file. A route can be RPKI-origin-VALID and still be a path manipulation.
No caching, no staleness, no overlapping-VRP policy nuance beyond the plain "any covering VRP matches" rule shown here.

None of these are bugs in the model. They're the seam between "understand the decision" and "operate the system," and this session is deliberately on the first side of that seam.

Self-check

Don't take my summary for it — go read validation.py and answer these from the code alone:

A route arrives whose prefix no VRP covers. What does validate_origin return, and — trace the branches — does it ever look at the origin AS?
A route is covered by a VRP, but that VRP names a different origin_as. Which state comes back, and why is that state stronger than the one in question 1?
Why does this function, even when it returns VALID, still not tell you the AS_PATH is trustworthy?

If you can answer all three by pointing at lines rather than recalling this post, you've got it: best path selection and origin validation are separate decisions, not_found is silence rather than a verdict, and origin validation checks the origin — not the path.

How a BGP UPDATE Changes State: Reading Withdrawal and Announcement as Code

pathvector-dev — Sat, 25 Jul 2026 16:00:18 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-02/ — 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 you can step through. If you'd rather read the whole thing yourself, the source lives at github.com/pathvector-studio/protocol-in-code.

New to this? If you can run commands but haven't yet built up hands-on intuition for how these protocols behave, start with the companion Protocol Lab series first: github.com/pathvector-studio/protocol-lab. It gets your hands dirty before you start reading the internals as code.

The question to hold in your head

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

How does a BGP UPDATE change routing state, and why is route withdrawal different from session failure?

Most explanations of BGP UPDATE treat it as a packet format — here are the withdrawn routes, here are the NLRI, here are the path attributes, memorize the byte layout. That framing tells you what an UPDATE contains. It doesn't tell you what an UPDATE does.

The move in this session is to stop asking "how do I decode this packet?" and start asking:

What disappeared?
What appeared?
Which attributes arrived with the new path?
Did the route leave because of a withdrawal, or because the session itself died?

Those last two are the ones people conflate, and the code makes the difference impossible to fudge. Let's read it.

The shape of an UPDATE

The toy model for this session is a single file: src/protocol_in_code/bgp/update.py. Start with the data.

A path attribute set is exactly what travels with an advertised route:

@dataclass(frozen=True)
class PathAttributes:
    next_hop: str
    as_path: tuple[int, ...]
    origin: str
    local_pref: int = 100

next_hop, as_path, origin, local_pref — this is the policy and path context. Note that it's frozen=True: an announcement carries an immutable description of how to reach a prefix. Hold onto that; it's the reason announcements and withdrawals turn out to be structurally different operations.

Now the message itself:

@dataclass(frozen=True)
class BGPUpdate:
    nlri: tuple[str, ...] = ()
    withdrawn_routes: tuple[str, ...] = ()
    path_attributes: PathAttributes | None = None

Three fields, and they tell you everything the incoming message can contain:

withdrawn_routes — prefixes that should disappear from the table.
nlri — Network Layer Reachability Information, the prefixes being announced.
path_attributes — the context that goes with the announcement. Optional, and its optionality is doing real work, which we'll get to.

The first thing to notice: all three default to empty/None. A valid UPDATE can carry only withdrawals, only announcements, or both at once. That's not an accident of the toy model — it's true of real BGP, and it's the crux of the whole session.

The state that changes

Everything above is input. Here's the thing that actually mutates:

@dataclass
class RoutingTable:
    paths_by_prefix: dict[str, list[PathAttributes]] = field(default_factory=dict)

    def apply_update(self, prefix: str, attributes: PathAttributes) -> None:
        self.paths_by_prefix.setdefault(prefix, []).append(attributes)

    def withdraw(self, prefix: str) -> None:
        self.paths_by_prefix.pop(prefix, None)

paths_by_prefix is the current routing state after each mutation. And now look closely at the two methods, because this is where withdrawal and announcement reveal themselves as different kinds of work:

apply_update() adds. It appends a PathAttributes to the list for a prefix, creating the list if it doesn't exist. Announcing is additive and it requires attributes — you cannot announce a prefix without saying how to reach it.
withdraw() removes. It pops the prefix entirely, and — this matters — pop(prefix, None) never raises. Withdrawing a prefix that isn't there is a no-op, not an error.

These are not two flavors of the same operation. One needs a full PathAttributes payload; the other needs nothing but a prefix name. That asymmetry is the answer to "why is route withdrawal different from session failure" hiding in plain sight — but let's watch them combine first.

One message, two kinds of work

Here is the whole session in one function:

def apply_update_message(table: RoutingTable, update: BGPUpdate) -> RoutingTable:
    """Apply withdrawals first, then announcements from a single UPDATE."""
    for prefix in update.withdrawn_routes:
        table.withdraw(prefix)

    if update.path_attributes is None:
        return table

    for prefix in update.nlri:
        table.apply_update(prefix, update.path_attributes)

    return table

Read it as a sequence of decisions, not as a parser:

Withdrawals go first. Every prefix in withdrawn_routes is popped before anything is added. Order is deliberate — a single UPDATE that both withdraws and re-announces a prefix ends with the announcement winning, because the removal happens first and the append happens after.
No attributes, no announcement. The guard if update.path_attributes is None: return table is the enforcement of that asymmetry from earlier. An UPDATE that carries only withdrawals has no path_attributes, so the function returns right there — the nlri loop never runs. This is also why an announcement can't sneak through without a path: the attributes are the ticket of entry.
Announcements attach the path. Each prefix in nlri gets update.path_attributes appended. The same attribute set travels with every prefix in this UPDATE, which is exactly why path attributes are a message-level field and not a per-prefix one.

So a single UPDATE can both remove and add routes, in that order, and the shape of the message decides which loops execute.

You can watch this happen. The walkthrough is runnable:

PYTHONPATH=src python3 examples/bgp/session_02_walkthrough.py

It prints a sequence of UPDATEs and shows how paths_by_prefix changes after each one. Run it, then predict the table state before each line prints — that's the whole exercise.

Why a withdrawal is not a dead session

Now we can answer the core question directly, and it's worth being precise because operators mix these up constantly.

withdraw() removes one prefix. That's a routing decision the peer made: "I no longer have a path to 10.0.0.0/24, stop using me for it." The BGP session between you and that peer is perfectly healthy. Other prefixes it advertised are untouched.

A session dying is a different event entirely. When the TCP connection underneath BGP drops — hold timer expires, the peer crashes, the link fails — everything that peer ever told you has to be reconsidered at once. That's not one withdraw() call; it's the invalidation of a whole peer's worth of state.

The toy model draws the line but doesn't yet model the second case, which brings us to the honest part.

Toy Model Boundary

This is a deliberately simplified UPDATE model, and the simplification is specific: it is prefix-wide.

RoutingTable.withdraw() removes the entire prefix entry — paths_by_prefix.pop(prefix, None). In real BGP, that's too blunt. A prefix can be advertised to you by several peers at once, and each peer keeps its own Adj-RIB-In. Withdrawing a prefix should remove one peer's path for it, leaving other peers' paths intact so the best-path selection can fall back to an alternative.

That's why paths_by_prefix maps to a list of PathAttributes — the structure anticipates multiple paths per prefix — but this session's withdraw() doesn't yet key removal by peer. Later sessions refine it into per-peer Adj-RIB-In state, where one peer can disappear while another peer's path for the same prefix survives. Until then, treat "withdraw = drop the whole prefix" as a scaffold, not the real semantics.

Everything else here — withdrawals-before-announcements ordering, attributes as the gate on announcement, one message doing two jobs — is faithful to RFC 4271. The single-path-per-prefix table is the one place the model is knowingly ahead of itself.

The same shape elsewhere

Once you've read this, the pattern is recognizable across the series: a message that carries both "forget this" and "learn this" in a single unit, applied in a fixed order. BGP calls them withdrawn routes and NLRI. But the shape — invalidate first, then install, with state that outlives any single message — is the same one you'll meet again in DNS zone transfers and in any protocol that syncs incremental changes to a table rather than resending it whole. Reading BGP's UPDATE at the code level is really reading incremental state reconciliation, and that's transferable.

Check yourself

Don't take my walkthrough as the answer. Open update.py and see if you can answer these purely by reading the code:

What happens if withdrawn_routes contains a prefix that already exists in the table — and what happens if it contains one that doesn't?
What happens if path_attributes is None but nlri is non-empty? Which line decides the outcome?
If a single UPDATE contains both withdrawals and NLRI for the same prefix, what's in the table when the function returns — and why does the docstring's "withdrawals first" matter here?

If you can trace each of those to a specific line without running anything, you've read the session. If you can't, run the walkthrough and come back to the source.

What a BGP Neighbor Needs — Reading Session Setup as Code

pathvector-dev — Sat, 25 Jul 2026 16:00:11 +0000

Originally published at https://blog.pathvector.dev/protocol-in-code-bgp-01/ — 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 you can step through. The full course and every source file it reads live in the repo: github.com/pathvector-studio/protocol-in-code. If you're newer to this and want to build the muscle by doing rather than reading, start with the hands-on companion series, Protocol Lab, then come back here.

Here's the question to keep turning over while you read:

What inputs are required to form a BGP neighbor, and where does the session stop when one of them is missing?

That second half is the interesting part. Most people can recite that BGP needs a peer IP and an AS number. Far fewer can tell you which state a session lands in when TCP is fine but the OPEN negotiation fails — versus when TCP itself never came up. Those are different failures, and they stop the machine in different places. The only way to know the difference cold is to read the branches.

The inputs: what even goes into a session

Before you can reason about failure, you need to know the full surface of inputs. In the toy model that's a single dataclass, and reading it is the fastest way to see what a BGP session actually depends on:

@dataclass(frozen=True)
class BGPSessionConfig:
    peer_ip: str
    peer_as: int
    local_as: int
    tcp_reachable: bool
    hold_time: int = 180
    keepalive_time: int = 60
    capabilities: tuple[BGPCapability, ...] = field(default_factory=tuple)
    open_message_ok: bool = True
    keepalive_received: bool = True

Read that as a checklist of everything a neighbor needs, and why:

peer_ip — without a destination, TCP can't even start. No IP, no dial tone.
peer_as and local_as — you need a remote identity to validate against and a local identity to announce in your OPEN message. A BGP speaker introduces itself by AS number.
tcp_reachable — this is the one people skip past. BGP is an application riding on top of TCP. Before a single BGP message is exchanged, a TCP connection has to succeed.
hold_time / keepalive_time — a session isn't just created, it's maintained under timer rules.
capabilities — the two peers have to agree on what they're even able to talk about.
open_message_ok — OPEN negotiation can fail on its own terms, even when TCP is perfectly healthy.
keepalive_received — the session isn't fully established until a KEEPALIVE has actually come back.

Notice that peer_ip alone is nowhere near enough. It gets you a destination and nothing else. Everything after it is another gate the session has to pass through.

The states it can stop at

The second thing to read is the enum. It's the vocabulary the code uses for "how far did we get":

class SessionState(str, Enum):
    IDLE = "Idle"
    CONNECT = "Connect"
    ACTIVE = "Active"
    OPEN_SENT = "OpenSent"
    OPEN_CONFIRM = "OpenConfirm"
    ESTABLISHED = "Established"

The canonical happy path runs straight through these:

Idle -> Connect -> Active -> OpenSent -> OpenConfirm -> Established

But the enum isn't just a list of milestones you pass through on success. Each of these is also a place a failed session can come to rest. That's the mental shift this session is asking for. Established is not a config line you set — it's the label you earn only after every check upstream has passed.

Reading the machine

Now the main event. The whole state machine is one function, and it's worth reading top to bottom as a sequence of early returns — because each early return is a different way the session can stall:

def establish_neighbor(config: BGPSessionConfig) -> SessionState:
    """Walk a minimal BGP session state machine."""
    state = SessionState.IDLE

    if not config.peer_ip:
        return state

    state = SessionState.CONNECT
    if not config.tcp_reachable:
        return SessionState.ACTIVE

    state = SessionState.OPEN_SENT
    if config.peer_as <= 0 or config.local_as <= 0:
        return state
    if not config.open_message_ok:
        return state

    state = SessionState.OPEN_CONFIRM
    if not config.keepalive_received:
        return state

    return SessionState.ESTABLISHED

Walk the gates in order:

Leaving Idle. We start at IDLE. The very first check is if not config.peer_ip. No peer IP means we never even try to dial, so we return Idle unchanged. This is the "you haven't given me anywhere to go" failure.

Connect, and the fallback to Active. Once we have an IP we move to CONNECT — meaning "attempting the TCP connection." Then:

    state = SessionState.CONNECT
    if not config.tcp_reachable:
        return SessionState.ACTIVE

If TCP isn't reachable, we don't sit in Connect — we fall back to Active. This is the detail that trips people up. In real BGP, Active doesn't mean "up and doing things"; it means the speaker tried to connect, failed, and is now waiting to retry. It's arguably the most badly named state in all of networking. The code makes the semantics unambiguous: reaching Active here means TCP did not come up.

OpenSent, and the two ways to be stuck there. If TCP succeeded, we advance to OPEN_SENT — the OPEN message is on the wire and we're waiting on the peer. Two separate checks can pin us here:

    state = SessionState.OPEN_SENT
    if config.peer_as <= 0 or config.local_as <= 0:
        return state
    if not config.open_message_ok:
        return state

Invalid AS numbers (either side ≤ 0) stop us in OpenSent. So does a failed OPEN negotiation. Both return the same state, but they're distinct causes — one is "your identities don't validate," the other is "the OPEN exchange itself was rejected." The key takeaway: an OPEN failure and a TCP failure stop the session in different places — OpenSent versus Active. If someone hands you a stuck session and says "it's in OpenSent," you already know TCP is fine and the problem is up in the BGP layer.

OpenConfirm, waiting on KEEPALIVE. Pass the OPEN checks and we move to OPEN_CONFIRM, which means "OPEN was accepted, now I need to hear a KEEPALIVE back":

    state = SessionState.OPEN_CONFIRM
    if not config.keepalive_received:
        return state

No KEEPALIVE, and we rest at OpenConfirm. Only when that final gate passes do we return Established.

That last line is the whole point of the session. Established isn't a setting — it's the result of clearing every check above it, in order.

Run it and watch the states

The reading is the work, but the walkthrough lets you confirm your mental model against real output. It runs several BGPSessionConfig scenarios and prints which state each one reaches:

PYTHONPATH=src python3 examples/bgp/session_01_walkthrough.py

Before you run it, try to predict each scenario's landing state from the source alone. If your prediction and the printout disagree, that gap is exactly the thing to go re-read.

Toy Model Boundary

This is a deliberately minimal model, and being honest about what it isn't is the point.

The dataclass exposes hold_time, keepalive_time, and capabilities because they're part of a realistic BGP session's surface — you should know they exist. But establish_neighbor() does not actually negotiate or enforce them yet. In this session, the branches that really fire depend only on peer_ip, tcp_reachable, valid AS numbers, open_message_ok, and keepalive_received. The timers and capabilities are along for the ride as structure, not behavior.

A few more things the real protocol does that this model collapses:

Timing is boolean here. tcp_reachable, open_message_ok, and keepalive_received are pre-decided flags. Real BGP discovers each of these over time, with retries, backoff, and the ConnectRetry, Hold, and Keepalive timers governing the pace. Here, Active is a terminal return value; in the real FSM it's a state you loop back out of on the next connection attempt.
No collision detection, no passive/active roles. Real speakers can both initiate, detect the collision, and tear one connection down. This model has a single directional walk.
OPEN is a boolean, not a negotiation. open_message_ok hides the actual content — version, AS, hold time, BGP Identifier, and the capability optional parameters that capabilities is standing in for. Capability mismatch handling doesn't exist here.

None of that makes the model wrong — it makes it a lens. The FSM's shape (each input is a gate; each failure has a resting state) is exactly right, and that shape is what carries over to the real thing.

The same shape, elsewhere

The move this session trains — stop asking "did the config look correct?" and start asking "which field was missing, which condition failed, which state was the last successful one?" — is not specific to BGP. It's the reading lens for every stateful protocol handshake. A TLS handshake stalling at a specific message, a TCP connection stuck in SYN_SENT versus SYN_RECEIVED: same idea. The state you're stuck in is the diagnosis, because it tells you which gate you cleared and which one you didn't. Learn to read one FSM this way and you can read all of them.

Self-check: can you answer these from the source alone?

Don't run anything for these — answer them by reading establish_neighbor(), then verify. The point is to prove the state machine lives in your head, not your notes:

If peer_ip is empty, what state comes back — and why is it that one rather than Connect?
If TCP is unreachable, why does the session land in Active instead of simply staying in Connect?
Invalid AS numbers and a failed OPEN both return the same state — which one, and how would you tell those two failures apart if all you had was the returned state?

If you can answer all three cold, you've got the session: BGP doesn't start at OPEN — it starts after TCP reachability, OPEN failure and TCP failure stop in different places, and Established is the result of passing several checks, not a single setting.

Split-Horizon DNS: One Name, Two Answers, and the Server Decides by Who's Asking

pathvector-dev — Fri, 24 Jul 2026 16:00:59 +0000

Originally published at https://blog.pathvector.dev/protocol-lab-dns-views-42-split-horizon/ — part of the free Protocol Lab series.

This post is part of Protocol Lab, a free, hands-on series for learning networking protocols by building and breaking them in a container lab. All the lab material — topologies, configs, and scripts — lives in the repo: github.com/pathvector-studio/protocol-lab.

In Lab #41, round-robin DNS rotated the order of one name's records. Split-horizon DNS pulls a more radical trick: it changes the answer itself based on who is asking. An authoritative server keeps several views of the same zone and picks one by the client's source address.

Reading guide: rfc-notes/split-horizon-dns.md

Prerequisite: DNS Lab 05: Resolving a Name Through the Hierarchy

Expected time: 35–50 minutes.

The Goal

One name (app.lab.) is served through two views:

an internal view (match-clients { 10.0.1.0/24; }) answers with the private address 10.0.0.5,
an external view (match-clients { any; }) answers with the public address 203.0.113.5,
two clients on different networks resolve the same app.lab. and get different addresses — the basis of split-brain DNS, used to give insiders a private path and outsiders a public one.

By the end, you should be able to explain this table:

client (source)	`app.lab.` resolves to
internal (10.0.1.0/24)	10.0.0.5 (private)
external (any other)	203.0.113.5 (public)

What You Will Learn

What a BIND view is and how match-clients selects one by source address.
Why view order matters (specific first, any last).
How the same name resolves to different records per view.
Where split-horizon is used (internal vs. public paths, hiding topology).
The caveats: caching across boundaries and keeping two zone copies consistent.

This lab does not cover:

Recursive resolvers and cache separation in depth.
TSIG-key-based view selection or EDNS Client Subnet.
Automated zone-data generation for multiple views.

Where to Read in the RFCs

Reference	What to focus on
RFC 8499	The terminology for "view" / split DNS
RFC 1034	The basics of authoritative servers and zones
RFC 6950	Caveats of scoped (audience-dependent) responses
RFC 5737 / RFC 1918	Confirming the addresses used here are local/documentation-only

The Big Picture

The DNS server sits between two faces, internal and external. A client on each side asks for the same name.

 internal-client (10.0.1.10) --- eth1 [ dns (views) ] eth2 --- external-client (203.0.113.10)
                             10.0.1.2                203.0.113.2
   internal: app.lab -> 10.0.0.5     external: app.lab -> 203.0.113.5

flowchart TD
  I["internal-client<br/>src 10.0.1.10"] -->|dig app.lab| D["dns<br/>view match by source"]
  E["external-client<br/>src 203.0.113.10"] -->|dig app.lab| D
  D -->|"internal view<br/>(10.0.1.0/24)"| RI["A 10.0.0.5 (private)"]
  D -->|"external view<br/>(any)"| RE["A 203.0.113.5 (public)"]

10.0.1.0/24 is the internal link; 203.0.113.0/24 (RFC 5737) is the external link.

Note: Everything here uses local/documentation address space (RFC 1918 / RFC 5737), so nothing in this lab touches the real internet.

What You Need

Recommended environment:

Linux / WSL2 / a Linux VM
Docker
containerlab

Images used:

protocol-lab/bind9:9.20 — built from the Dockerfile by run.sh.
nicolaka/netshoot:latest — the clients, providing dig.

Running the Lab

The quick path, which deploys, verifies, and tears down for you:

./scripts/labctl.sh run dns-views-42

Or step through it manually:

1. Move into the working directory

cd protocol-lab/examples/dns-views-42

2. Build the image and deploy

docker build -t protocol-lab/bind9:9.20 .
sudo containerlab deploy -t dns-views-42.clab.yml

3. Resolve the same name from inside and outside

docker exec clab-dns-views-42-internal-client dig +short app.lab @10.0.1.2      # 10.0.0.5
docker exec clab-dns-views-42-external-client dig +short app.lab @203.0.113.2   # 203.0.113.5

The same app.lab resolves to a different address depending on the source.

Expected Output

internal-client: app.lab → 10.0.0.5 (private).
external-client: app.lab → 203.0.113.5 (public).
The two answers differ — split-horizon is working.

Why It Works

Split-horizon DNS is "one authoritative name, multiple sets of answers, chosen by who's asking."

Views. A view is a named container with its own zone definitions (files). The server can hold the same zone separately in multiple views.
Selection by match-clients. The server compares the query's source address against each view's match-clients list, top to bottom, and answers from the zone of the first view that matches. In this lab, the order is internal (10.0.1.0/24) → external (any). The internal client (10.0.1.10) matches the internal view → 10.0.0.5. The external client (203.0.113.10) doesn't match internal, falls through to external (any) → 203.0.113.5.
Order is everything. Put specific views first and any last. Reverse them and everyone lands in the first view.
Why it's useful. Internal users get the private IP (a direct in-house path); external users get the public IP (the published route). Private addresses and internal-only hosts stay invisible to the outside (topology hiding), and users keep using the same name (URL) everywhere.
The caveats. Responses get cached by resolvers — if you don't separate internal and external resolvers, answers from different views can get mixed. Each view keeps its own copy of the zone, so a missed update leaves inside and outside out of sync. And selection is based on source address, so NAT or VPN can shift a client into an unintended view.

The key insight: select the view by source address, and the same name resolves to the right face for wherever the client sits. Unlike round-robin (which shuffles order), split-horizon changes the answer itself based on who asks.

Common Pitfalls

Confusing it with round-robin. RR (Lab 41) changes the order of records; views change the answer itself.
View ordering. Matching goes top-down and the first hit wins. Put any first and everyone falls into it.
Assuming one zone file is enough. Each view holds its own copy of the zone; you need an operational story for keeping them in sync.
Caching. Without separate internal and external resolvers, answers get mixed across the boundary.
Trusting the source address too much. NAT, VPNs, and spoofing can all change the apparent source. Design your ACLs carefully.
Recursion. This lab queries the authoritative server directly. Put a recursive resolver in between, and view selection is decided by the resolver's source address, not the end client's.

Cleanup

sudo containerlab destroy -t dns-views-42.clab.yml --cleanup

If you used labctl.sh run dns-views-42, the script runs destroy for you at the end.

Check Your Understanding

What is a BIND view? What does match-clients use to select one?
How does the view matching order matter? What happens if any comes first?
In this lab, why do the internal and external clients get different addresses for the same name?
How does split-horizon differ from round-robin (Lab 41)?
Name two operational caveats of split-horizon (think caching and consistency).
How do NAT or VPN affect view selection?

References

Verified Run Log (2026-07-08)

This lab has been confirmed reproducible on real hardware.

Environment:

Ubuntu 26.04 LTS (kernel 7.0.0-27-generic, x86_64)
Docker 29.1.3
containerlab 0.77.0
dns: protocol-lab/bind9:9.20 (built from the Dockerfile by run.sh)
internal-client / external-client: nicolaka/netshoot:latest (dig)

Running PATH="/tmp/pl-shim:$PATH" ./scripts/labctl.sh run dns-views-42 performed build → deploy → verify → destroy, and verification.json returned "status": "verified".

The same name, a different answer per source

internal: 10.0.0.5
external: 203.0.113.5

internal-client (source 10.0.1.10, matching 10.0.1.0/24) landed in the internal view: app.lab → 10.0.0.5 (the private address).
external-client (source 203.0.113.10) didn't match internal and fell through to the external (any) view: the same app.lab → 203.0.113.5 (the public address).
One authoritative name resolved to different records per source, via match-clients view selection — private to the inside, public to the outside. Split-horizon confirmed.

Cleanup

containerlab destroy -t dns-views-42.clab.yml --cleanup

That's split-horizon DNS: keep multiple views of one zone, match on the source address, and the same name quietly resolves to the right answer for each audience.

Explore the full Protocol Lab series here: github.com/pathvector-studio/protocol-lab. If these labs are useful to you, please ⭐ star the repo on GitHub — it genuinely helps others find the project.

Next up, we'll keep pushing on DNS behavior — how resolvers, caches, and trust boundaries shape the answers you actually see.

DEV Community: pathvector-dev

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

The question

Read the file in three moves

1. What a peer actually is

2. The gate, stated as one question

3. Where the if sits

Same shape, different protocol

Toy model boundary

Run it

Check yourself

Further reading

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

The core question

The shape, before the details

Two dataclasses that do the structural work

Bridging two sessions with one function

Where a route lives or dies

The full chain

Same shape, different protocol

Run it

Toy model boundary

Check yourself

Further reading

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

The question

Where this sits

Read it like code

The loop that makes it plural

Same shape, elsewhere

Run it

Toy model boundary

Check yourself

Further reading

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

The question

The file

Two peer types, because export isn't uniform

The policy is data, not behavior

Reading prepare_export()

The deny check comes first

Next-hop rewrite is a state divergence

The eBGP branch transforms the path

Same shape, different protocol

Run it

Toy model boundary

Check yourself

Further reading

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

The question

Read the code

What this does to best-path

Same shape, different protocol

Run it

Toy model boundary

Check yourself

Further reading

3. Where the `if` sits

Reading `prepare_export()`