fix(bgp): the ExaBGP api stage, and the panic it was hiding

The ExaBGP compatibility api stage goes 28/40 to 40/40. The encoding
stage stays 42/42.

Three cases exited 2 with an EMPTY stderr. Exit 2 is Go's status for an
unrecovered panic, and the trace reached nobody: crashlog.Init dup2s fd
2 onto a pipe a reader goroutine drains, the runtime writes the trace
and ends the process, so the reader is never scheduled. main called
flushCrashlog only on the ordinary return, which a panic skips. Every ze
binary was affected. main now ALSO defers it, so fd 2 is restored while
the panic unwinds; the ordinary call stays because os.Exit runs no
deferred function.

The trace it was hiding named the defect in one frame. WireUpdate.Attrs
answers (nil, nil) for a withdraw-only UPDATE, which carries no
attribute section, and the bridge's three overlays read it. Checking the
error alone is the nil a caller cannot tell from an answer.

The withdraw path never went through the bridge's renames: the announce
arm called exabgpNLRIObject and the del arm passed the object through,
so one route read as nlri/label/65000:1 outbound and
prefix/labels/0:65000:1 back. A withdraw also KEEPS its next hop in the
attribute object, where an announce drops it: ExaBGP reads
include_nexthop = bool(minus), because a withdraw has no announce key to
hang it under.

A Path Identifier of ZERO was dropped as if ADD-PATH were off. RFC 7911
Section 3 reserves no value, and appendIPv4PrefixesFromWire HELD the
negotiated flag and still wrote it only when the identifier was
non-zero. ParseINET had the same shape one layer down: it consumed the
four octets and threw the flag away, so an *INET could not say whether
it carried an identifier at all.

interface-set is named in both directions now. It was the fifth extended
community ze could encode and not read back; the config migration wrote
it as raw hex and said ze had no name for it. It is also the one place
the two vocabularies genuinely diverge rather than differ: the draft
defines the community twice, transitive and non-transitive, and ze
carries every extended community in one flat list, so its text is the
only place that bit can go. ExaBGP has a scope block, so it prints four
fields and puts transitivity in a JSON member, the only community it
writes that member for.

Three api fixtures stated peer 127.0.0.1 where their own ze config
declares 127.0.0.2. That config header records the move and RFC 4271
Section 5.1.3 as its reason, and says the expected frames are unchanged,
which held for the hex and not for the json lines. ExaBGP renders the
member from the CONFIGURED neighbor, not the socket.

Author: thomas-mangin

cmd/ze/crash_flush_test.go

@@ -0,0 +1,74 @@
+// Design: docs/architecture/diagnostics/crash-capture.md -- the stderr a panic reaches
+
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"testing"
+)
+
+// TestMainDefersTheCrashlogFlush reads main.go and asserts that main defers
+// flushCrashlog.
+//
+// VALIDATES: a panic that nothing recovers still prints its trace.
+// PREVENTS: exit status 2 with no output at all.
+//
+// crashlog.Init replaces fd 2 with a pipe, and a reader goroutine copies that
+// pipe to the real stderr. The runtime writes a panic trace to fd 2 and then
+// ends the process, so that goroutine is never scheduled and the trace dies in
+// the pipe. Measured on 2026-09-20: the ExaBGP compatibility mock server
+// panicked on three cases and the suite reported `exit status 2` with an empty
+// stderr for each, which cost a whole bisection to recover
+// (plan/journal/failing-gate-prints-no-cause.md).
+//
+// The check is structural because the behavior needs a process that dies. A
+// deferred call runs while the panic unwinds, before the runtime prints, and
+// Flush restores fd 2 to the real stderr. The ordinary path cannot rely on the
+// defer, because os.Exit runs no deferred function, so main calls Flush twice
+// and Flush acts once.
+func TestMainDefersTheCrashlogFlush(t *testing.T) {
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "main.go", nil, 0)
+	if err != nil {
+		t.Fatalf("parse main.go: %v", err)
+	}
+
+	body := mainFunctionBody(t, file)
+	for _, statement := range body.List {
+		deferred, isDefer := statement.(*ast.DeferStmt)
+		if !isDefer {
+			continue
+		}
+		name, isIdentifier := deferred.Call.Fun.(*ast.Ident)
+		if !isIdentifier {
+			continue
+		}
+		if name.Name == "flushCrashlog" {
+			return
+		}
+	}
+	t.Fatal("main does not defer flushCrashlog, so a panic exits 2 with its trace stuck in the crashlog pipe")
+}
+
+// mainFunctionBody returns the body of func main, and fails the test when the
+// file holds no such function.
+func mainFunctionBody(t *testing.T, file *ast.File) *ast.BlockStmt {
+	t.Helper()
+	for _, declaration := range file.Decls {
+		function, isFunction := declaration.(*ast.FuncDecl)
+		if !isFunction {
+			continue
+		}
+		if function.Recv != nil || function.Name.Name != "main" {
+			continue
+		}
+		if function.Body == nil {
+			t.Fatal("func main has no body")
+		}
+		return function.Body
+	}
+	t.Fatal("main.go declares no func main")
+	return nil
+}

cmd/ze/main.go

@@ -55,7 +55,21 @@ var (
 )
 
 func main() {
+	// crashlog.Init replaces fd 2 with a pipe that a reader goroutine copies to
+	// the real stderr. A panic that nothing recovers writes its trace into that
+	// pipe and the process dies immediately, so the reader is never scheduled
+	// and the operator gets exit status 2 with no output at all. A deferred
+	// flush runs while the panic unwinds, restores fd 2 to the real stderr and
+	// drains what the pipe already holds, and the runtime then prints the trace
+	// where somebody can read it.
+	//
+	// The call below it is still owed: os.Exit runs no deferred function, so the
+	// ordinary path flushes for itself. Flush acts once, so the pair is safe.
+	defer flushCrashlog()
+
 	code := dispatchMain(os.Args[1:])
 	flushCrashlog()
-	os.Exit(code)
+	// gocritic's exitAfterDefer names the shape above, and it is the intended
+	// one: the defer exists for the PANIC path, which os.Exit never reaches.
+	os.Exit(code) //nolint:gocritic // exitAfterDefer: the flush on the line above serves this path
 }

docs/architecture/api/json-format.md

@@ -275,7 +275,13 @@ With ADD-PATH:
 ```json
 "nlri": [{"prefix": "10.0.0.0/24", "path-id": 1}]
 ```
-<!-- source: internal/component/bgp/format/text.go -- NLRI formatting per family -->
+
+The negotiated layout decides the shape, never the identifier's value. RFC 7911
+Section 3 reserves no value for the Path Identifier, so a route whose identifier
+is zero is written as `{"prefix": "10.0.0.0/24", "path-id": 0}`. The bare string
+form says the session carried no identifier for that route.
+
+<!-- source: internal/component/bgp/format/text_json.go -- appendNLRIJSONValue -->
 
 ### Labeled Unicast (MPLS)
 

docs/architecture/testing/ci-format.md

@@ -985,6 +985,20 @@ an exabgp-compat config is left alone for the same reason.
 <!-- source: internal/test/runner/loopback_darwin.go -- SIOCAIFADDR on BSD -->
 <!-- source: internal/le/setup/actions.go -- Answer -->
 
+An exabgp-compat case runs TWO processes, ze and the mock BGP server, and its
+verdict names which one ended the case:
+
+- `ze exited before the mock BGP server finished its script: <error>` is a
+  daemon defect. Read the client stderr in the failure block.
+- `the mock BGP server failed: <error>` is a wire or document disagreement. The
+  mock prints the frame or the JSON member that did not match.
+- `the mock BGP server ended without reporting success` means its script did not
+  complete and it said nothing about why.
+
+Both used to print the bare `exit status N` of whichever process failed, which
+told a reader nothing about which of the two to open.
+<!-- source: internal/test/cli/cmd_exabgp.go -- exaBGPFailure -->
+
 ## Expectations
 
 ```

docs/architecture/wire/nlri.md

@@ -91,6 +91,14 @@ NLRI (interface)
 - `family` - AFI/SAFI address family
 - `prefix` - IP prefix (netip.Prefix)
 - `pathID` - RFC 7911 ADD-PATH identifier
+- `addPath` - true when the wire carried a Path Identifier, read through `HasAddPath()`
+
+RFC 7911 Section 3 reserves no value for the Path Identifier, so `pathID` of
+zero identifies a path and says nothing about whether one arrived. `addPath`
+answers that, and only the parser can set it, because the negotiation is what
+told the parser how to read the octets. A locally built NLRI reports false: it
+has no wire layout yet, and `WriteNLRI` takes the layout from the session's
+EncodingContext.
 
 **RDNLRIBase** (base.go) - Shared by RD-based types:
 - `rd` - Route Distinguisher (8 bytes)
@@ -147,6 +155,11 @@ NLRI (interface)
 | 192.168.1.0/24 | `18 C0 A8 01` | mask=24, 3 bytes |
 | 10.0.0.1/32 | `20 0A 00 00 01` | mask=32, 4 bytes (full IP) |
 
+`ParseINET` takes the ADD-PATH flag the session negotiated, consumes the 4-octet
+Path Identifier when it is set, and records the flag on the NLRI it returns. A
+reader of a parsed INET therefore asks `HasAddPath()` for the layout and reads
+`PathID()` for the value, including when that value is zero.
+
 <!-- source: internal/core/bgp/nlri/inet.go -- ParseINET, INET.Len, INET.WriteTo -->
 
 ### ExaBGP Implementation
@@ -572,6 +585,11 @@ The plugin text command `decode nlri <family> <hex>` and the `ze bgp decode`
 CLI both read a hex blob with no session behind it, so both decode with no Path
 Identifier.
 
+A core family takes the same route to the same answer. `INET` records the flag
+`ParseINET` was given, so `appendNLRIJSONValue` reads one interface for every
+family and renders `{"prefix": ..., "path-id": 0}` rather than a bare prefix
+string when the session carried a Path Identifier of zero.
+
 <!-- source: internal/core/bgp/nlri/nlri.go -- AddPathAware, SplitPathID -->
 <!-- source: internal/component/bgp/format/text_json.go -- appendNLRIJSONValue -->
 <!-- source: internal/component/plugin/registry/registry.go -- DecodeNLRIByFamily -->

docs/architecture/wire/qualifiers.md

@@ -318,6 +318,12 @@ class PathInfo:
 "path-information": "1.2.3.4"
 ```
 
+The member is written for every route the session carried a Path Identifier for,
+and RFC 7911 Section 3 reserves no value, so an identifier of zero renders as
+`"path-information": "0.0.0.0"`. `PathID()` returns the value alone, so a reader
+deciding whether the member is owed asks `HasAddPath()` instead of comparing
+that value against zero.
+
 <!-- source: internal/core/bgp/nlri/nlri.go -- WriteNLRI, LenWithContext -->
 <!-- source: internal/core/bgp/nlri/base.go -- PrefixNLRI.PathID -->
 

docs/exabgp/exabgp-differences.md

@@ -107,7 +107,7 @@ is gone.
 
 ## JSON member spellings the bridge folds
 
-Four members carry the same fact under different words. Ze keeps its own word,
+Five members carry the same fact under different words. Ze keeps its own word,
 because each is load-bearing on Ze's side, and the bridge writes ExaBGP's word
 so a script reads one vocabulary.
 
@@ -117,6 +117,7 @@ so a script reads one vocabulary.
 | RFC 7911 Path Identifier | `"path-id": 16909060` | `"path-information": "1.2.3.4"` | RFC 7911 Section 3 calls it a 4-octet value, and Ze's CLI and RIB read the number |
 | FlowSpec DSCP on IPv6 | `dscp` | `traffic-class` | RFC 8956 Section 8 registers component type 11 as `DSCP` under both its IPv4 and its IPv6 name |
 | FlowSpec traffic-marking and traffic-action | `mark:10`, `traffic-action:sample` | `mark 10`, `action sample` | the FlowSpec firewall lowering keys on the colon form |
+| Interface set transitivity | `interface-set:non-transitive:input:1234:10` | `interface-set:input:1234:10` plus `"transitive": false` | Ze carries every extended community in one flat list, and ExaBGP has a `scope` block to state it beside |
 
 Nothing is lost either way, so each is a spelling rather than a conversion. The
 RFC governs the wire and says nothing about a JSON member, which is what leaves
@@ -128,7 +129,7 @@ quad in both projects, and so do `l2info` and the FlowSpec redirect-to-IP
 communities, because Ze's config parser already read those spellings and its
 renderer wrote something the parser refuses.
 <!-- source: internal/exabgp/bridge/bridge_event.go -- exabgpRD, exabgpPathInformation, exabgpFlowComponentName -->
-<!-- source: internal/exabgp/bridge/bridge_wire_json.go -- exabgpCommunitySpellings -->
+<!-- source: internal/exabgp/bridge/bridge_wire_json.go -- exabgpCommunitySpellings, exabgpInterfaceSet -->
 
 ---
 
@@ -139,6 +140,19 @@ three members Ze's own JSON does not carry: the AS_PATH's segments and their
 types, the numeric value beside each extended community, and the flag octet in
 an unknown attribute's `attribute-0xCC-0xFF` name.
 
+The community value is read for both widths, RFC 4360's 8 octets and RFC 5701's
+20, and it is built exactly and rounded once. RFC 5701's community is 160 bits
+wide and JSON has one number type, so accumulating the octets in a float rounds
+at every step: doing that put the member two thousand off an expectation whose
+own decimal literal rounds cleanly.
+
+One community gains a second member here. ExaBGP writes `"transitive"` beside
+the interface set and beside nothing else, because that community
+(draft-ietf-idr-flowspec-interfaceset Section 5) is defined twice, transitive
+and non-transitive, differing by one bit of the type octet. Ze states that bit
+in the text instead, since it carries every extended community in one flat list
+and has no `scope` block to put it in.
+
 The live bridge cannot. `translateAndForward` receives Ze's JSON event as text
 and has no wire to read, so an ExaBGP process attached to a running Ze gets Ze's
 flattened AS_PATH and no community values. The ExaBGP compatibility fixtures go

internal/component/bgp/format/addpath_nlri_json_test.go

@@ -106,3 +106,71 @@ func TestAppendNLRIJSONValueCarriesAddPathToTheDecoder(t *testing.T) {
 		})
 	}
 }
+
+// TestNLRIJSONKeepsAZeroPathIdentifier drives the two NLRI JSON writers with a
+// route whose Path Identifier is zero, which is the value that used to make the
+// formatter render an ADD-PATH route as a plain prefix.
+//
+// RFC 7911 Section 3: "In order to carry the Path Identifier in an UPDATE
+// message, the NLRI encoding MUST be extended by prepending the Path Identifier
+// field, which is of four octets."
+//
+// The section reserves no value, so zero identifies a path like any other
+// number. ExaBGP writes it as "path-information":"0.0.0.0" (PathInfo.json,
+// src/exabgp/bgp/message/update/nlri/qualifier/path.py) and omits the member
+// only when ADD-PATH is disabled.
+//
+// VALIDATES: appendNLRIJSONValue and appendIPv4PrefixesFromWire decide the shape
+// from the negotiated layout, and write "path-id" for an identifier of zero.
+// PREVENTS: an ADD-PATH route with identifier zero rendering as the bare string
+// a route carrying no identifier renders as, which leaves a reader of the JSON
+// unable to tell the two apart.
+func TestNLRIJSONKeepsAZeroPathIdentifier(t *testing.T) {
+	// One /32 of 1.1.1.1, once behind a zero Path Identifier and once alone.
+	addPathSection := []byte{0x00, 0x00, 0x00, 0x00, 0x20, 0x01, 0x01, 0x01, 0x01}
+	plainSection := []byte{0x20, 0x01, 0x01, 0x01, 0x01}
+
+	cases := []struct {
+		name    string
+		data    []byte
+		addPath bool
+		want    string
+	}{
+		{
+			name:    "add-path negotiated",
+			data:    addPathSection,
+			addPath: true,
+			want:    `{"prefix":"1.1.1.1/32","path-id":0}`,
+		},
+		{
+			name:    "add-path not negotiated",
+			data:    plainSection,
+			addPath: false,
+			want:    `"1.1.1.1/32"`,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			parsed, rest, err := nlri.ParseINET(family.AFIIPv4, family.SAFIUnicast, tc.data, tc.addPath)
+			if err != nil {
+				t.Fatalf("parse NLRI: %v", err)
+			}
+			if len(rest) != 0 {
+				t.Fatalf("want the whole section consumed, %d octets left", len(rest))
+			}
+
+			got := string(appendNLRIJSONValue(nil, parsed, family.IPv4Unicast))
+			if got != tc.want {
+				t.Errorf("appendNLRIJSONValue wrote %s, want %s", got, tc.want)
+			}
+
+			// The body NLRI section never builds an NLRI struct, so it carries
+			// the same decision in its own loop and needs its own case.
+			fromWire := string(appendIPv4PrefixesFromWire(nil, tc.data, tc.addPath))
+			if fromWire != tc.want {
+				t.Errorf("appendIPv4PrefixesFromWire wrote %s, want %s", fromWire, tc.want)
+			}
+		})
+	}
+}

internal/component/bgp/format/json_test.go

@@ -1498,7 +1498,7 @@ func TestJSONEncoderMPLSVPN(t *testing.T) {
 			pathID:     42,
 			wantRD:     "2:65536:100",
 			wantLabels: `"labels":[[400,6401]]`, // each member is the label and the RFC 8277 stack entry it came from
-			wantPathID: false,              // path-id is transport-level, not in plugin decode output
+			wantPathID: false,                   // path-id is transport-level, not in plugin decode output
 		},
 	}