feat: Add attributes-only UPDATE support for round-trip testing

Add support for generating and parsing UPDATE messages that contain only
path attributes with no NLRI (no announce, no withdraw). This enables
round-trip testing of empty UPDATEs like those containing just ORIGIN
and LOCAL_PREFERENCE.

Changes:
- Add Empty NLRI class for attributes-only UPDATE generation
- Update attributes parser to handle commands without nlri keyword
- Update UpdateCollection to generate attributes-only UPDATEs
- Add decoder support for generating 'attributes' command
- Update test framework to handle attributes-only encoding
- Fix runtime import of Negotiated in NLRI __hash__ and index methods

The new 'attributes' command syntax:
  attributes origin igp local-preference 100

Coverage improved from 98.0% (346/353) to 98.3% (347/353).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: thomas-mangin

.claude/exabgp/FLOWSPEC_ROUNDTRIP_LIMITATIONS.md

@@ -2,7 +2,7 @@
 
 This document explains why certain BGP messages cannot complete a round-trip test (decode → encode → compare). The test framework marks these with `# No cmd:` comments to skip verification.
 
-**Current coverage:** 346/353 (98.0%) - 7 skipped
+**Current coverage:** 347/353 (98.3%) - 6 skipped
 
 ---
 
@@ -70,9 +70,9 @@ The self-check test now uses `generic=True` to enable round-trip for all generic
 
 ---
 
-## 4. Empty UPDATE (1 case)
+## 4. Empty UPDATE (RESOLVED)
 
-### The Problem
+### The Problem (was 1 case)
 
 An UPDATE message with only path attributes and no NLRI (no announce, no withdraw).
 
@@ -82,9 +82,15 @@ An UPDATE message with only path attributes and no NLRI (no announce, no withdra
 
 ### Resolution
 
-**Status:** ✅ Expected (no NLRI to encode)
+**Status:** ✅ Fixed with `attributes` command
+
+The decoder now generates `attributes` command for empty UPDATEs:
+
+```
+attributes origin igp local-preference 100
+```
 
-Nothing to announce or withdraw - decoder cannot generate a meaningful command.
+The encoder uses an Empty NLRI internally to generate the attributes-only UPDATE.
 
 ---
 
@@ -135,17 +141,18 @@ Supported for all families: IPv4/IPv6, FlowSpec, MCAST-VPN, MUP, VPLS.
 | Interface-set transitive | 0 | ✅ | Fixed with `transitive` JSON field |
 | Withdraw with attrs | 6 | ✅ | RFC normalization (correct) |
 | Partial-decode attrs | 0 | ✅ | Fixed with `--generic` decode mode |
-| Empty UPDATE | 1 | ✅ | No NLRI to encode |
+| Empty UPDATE | 0 | ✅ | Fixed with `attributes` command |
 | Multi-NLRI batching | 0 | ✅ | Fixed with `group` command |
 | Pure generic attrs | 0 | ✅ | Fixed with `attribute [...]` |
-| **Total skipped** | **7** | | |
+| **Total skipped** | **6** | | |
 
 ---
 
 ## Coverage History
 
 | Date | Passed | Skipped | Coverage |
 |------|--------|---------|----------|
+| 2025-12-10 | 347 | 6 | 98.3% |
 | 2025-12-10 | 346 | 7 | 98.0% |
 | 2025-12-10 | 345 | 8 | 97.7% |
 | 2025-12-10 | 332 | 17 | 95.1% |

qa/api/api-flow.ci

@@ -1,7 +1,7 @@
 option:file:api-flow.conf
 1:cmd:announce eor ipv4 flow
 1:raw:FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF:001E:02:00000007900F0003000185
-# No cmd: empty UPDATE (attributes only, no NLRI to encode)
+1:cmd:attributes origin igp local-preference 100
 1:raw:FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF:0025:02:0000000E4001010040020040050400000064
 1:json:{"exabgp":"6.0.0","type":"update","neighbor":{"address":{"local":"127.0.0.1","peer":"127.0.0.1"},"asn":{"local":1,"peer":1},"direction":"in","message":{"update":{"attribute":{"origin":"igp","local-preference":100}}}}}
 1:cmd:withdraw ipv4 flow destination-ipv4 0.0.0.0/32 source-ipv4 0.0.0.0/32 protocol =tcp destination-port =3128 next-hop 0.0.0.0

qa/bin/test_api_encode

@@ -412,15 +412,62 @@ def encode_api_command(
             return packed.hex().upper()
 
         # Handle 'attributes' syntax: announce attributes ... nlri X Y Z
-        if parts[1] == "attributes":
+        # OR attributes-only: attributes origin igp local-preference 100
+        if parts[1] == "attributes" or parts[0] == "attributes":
             # Parse: announce attributes [path-info X] next-hop Y ... nlri A B C
-            attr_parts = parts[2:]
+            # OR: attributes origin igp local-preference 100 (no nlri keyword - attributes-only UPDATE)
+            if parts[0] == "attributes":
+                # attributes-only command: attributes origin igp local-preference 100
+                attr_parts = parts[1:]
+            else:
+                attr_parts = parts[2:]
             nlri_idx = None
             for i, p in enumerate(attr_parts):
                 if p == "nlri":
                     nlri_idx = i
                     break
             if nlri_idx is None:
+                # Attributes-only UPDATE (no NLRI)
+                attr_str = " ".join(attr_parts)
+
+                # Use unique neighbor address to avoid RIB cache collision
+                neighbor_ip = f"127.0.{(_encode_counter >> 8) & 255}.{_encode_counter & 255}"
+
+                conf = f"""
+neighbor {neighbor_ip} {{
+    router-id 10.0.0.2;
+    local-address 127.0.0.1;
+    local-as {local_as};
+    peer-as {peer_as};
+    family {{ ipv4 unicast; }}
+    static {{ attributes {attr_str}; }}
+}}
+"""
+                configuration = Configuration([conf], text=True)
+                if not configuration.reload():
+                    return None
+
+                if not configuration.neighbors:
+                    return None
+
+                for name in configuration.neighbors.keys():
+                    neighbor = configuration.neighbors[name]
+                    _, negotiated_out = _negotiated(neighbor)
+
+                    if not neighbor.rib.enabled:
+                        continue
+
+                    for _ in neighbor.rib.outgoing.updates(False):
+                        pass
+
+                    for route in neighbor.rib.outgoing.cached_routes():
+                        for packed in UpdateCollection(
+                            [RoutedNLRI(route.nlri, route.nexthop)], [], route.attributes
+                        ).messages(negotiated_out):
+                            neighbor.rib.uncache()
+                            return packed.hex().upper()
+
+                    neighbor.rib.uncache()
                 return None
 
             attr_str = " ".join(attr_parts[:nlri_idx])

src/exabgp/bgp/message/update/collection.py

@@ -205,6 +205,9 @@ def split(data: Buffer) -> tuple[Buffer, Buffer, Buffer]:
 
     # The routes MUST have the same attributes ...
     def messages(self, negotiated: Negotiated, include_withdraw: bool = True) -> Generator[bytes, None, None]:
+        # Import here to avoid circular import
+        from exabgp.bgp.message.update.nlri.empty import Empty
+
         # Sort and classify NLRIs into IPv4 and MP categories
         # v4_announces/v4_withdraws store bare NLRIs (nexthop is in NEXT_HOP attribute for IPv4)
         # mp_announces stores RoutedNLRI by family (nexthop needed for MP_REACH_NLRI encoding)
@@ -214,11 +217,20 @@ def messages(self, negotiated: Negotiated, include_withdraw: bool = True) -> Gen
         mp_announces: dict[tuple[AFI, SAFI], list[RoutedNLRI]] = {}
         mp_withdraws: dict[tuple[AFI, SAFI], list[NLRI]] = {}
 
+        # Track if we have Empty NLRI (attributes-only UPDATE)
+        has_empty_nlri = False
+
         # Process announces - self._announces contains RoutedNLRI
         # Sort by nlri for deterministic ordering
         for routed in sorted(self._announces, key=lambda r: r.nlri):
             nlri = routed.nlri
             nexthop = routed.nexthop
+
+            # Skip Empty NLRI but remember we had one
+            if isinstance(nlri, Empty):
+                has_empty_nlri = True
+                continue
+
             if nlri.family().afi_safi() not in negotiated.families:
                 continue
 
@@ -242,6 +254,11 @@ def messages(self, negotiated: Negotiated, include_withdraw: bool = True) -> Gen
 
         # Process withdraws - bare NLRIs (no nexthop needed)
         for nlri in sorted(self._withdraws):
+            # Skip Empty NLRI in withdraws
+            if isinstance(nlri, Empty):
+                has_empty_nlri = True
+                continue
+
             if nlri.family().afi_safi() not in negotiated.families:
                 continue
 
@@ -259,6 +276,11 @@ def messages(self, negotiated: Negotiated, include_withdraw: bool = True) -> Gen
         has_v4 = v4_announces or v4_withdraws
         has_mp = mp_announces or mp_withdraws
         if not has_v4 and not has_mp:
+            # Attributes-only UPDATE (Empty NLRI case)
+            if has_empty_nlri and self._attributes:
+                attr = self.attributes.pack_attribute(negotiated, with_default=True)
+                # Generate UPDATE with no withdrawn routes and no NLRI, just attributes
+                yield self._message(UpdateCollection.prefix(b'') + UpdateCollection.prefix(attr))
             return
 
         # If all we have is MP_UNREACH_NLRI, we do not need the default

src/exabgp/bgp/message/update/nlri/__init__.py

@@ -51,6 +51,7 @@
 from exabgp.bgp.message.update.nlri.bgpls import BGPLS
 from exabgp.bgp.message.update.nlri.mup import MUP
 from exabgp.bgp.message.update.nlri.mvpn import MVPN
+from exabgp.bgp.message.update.nlri.empty import Empty
 from exabgp.bgp.message.update.nlri.collection import NLRICollection, MPNLRICollection
 
 __all__ = [
@@ -66,6 +67,7 @@
     'BGPLS',
     'MUP',
     'MVPN',
+    'Empty',
     'NLRICollection',
     'MPNLRICollection',
 ]

src/exabgp/bgp/message/update/nlri/empty.py

@@ -0,0 +1,75 @@
+"""empty.py
+
+Empty NLRI for attributes-only UPDATE messages.
+
+Created for API command round-trip testing (empty UPDATE with just attributes).
+Copyright (c) 2024 Exa Networks. All rights reserved.
+License: 3-clause BSD. (See the COPYRIGHT file)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from exabgp.bgp.message.open.capability.negotiated import Negotiated
+
+from exabgp.bgp.message import Action
+from exabgp.bgp.message.update.nlri.nlri import NLRI
+from exabgp.bgp.message.update.nlri.qualifier.path import PathInfo
+from exabgp.protocol.family import AFI, SAFI
+from exabgp.util.types import Buffer
+
+
+class Empty(NLRI):
+    """Empty NLRI for attributes-only UPDATE messages.
+
+    This NLRI type represents "no routes" and is used to generate
+    UPDATE messages that contain only path attributes (no NLRI).
+
+    Such messages are valid per RFC 4271 but don't announce or withdraw
+    any routes - they're primarily useful for testing.
+    """
+
+    __slots__ = ()
+
+    # Class attribute to identify Empty NLRI instances
+    EMPTY_NLRI = True
+
+    def __init__(self, afi: AFI = AFI.ipv4, safi: SAFI = SAFI.unicast, action: Action = Action.ANNOUNCE) -> None:
+        """Create an Empty NLRI.
+
+        Args:
+            afi: Address Family Identifier (default: ipv4)
+            safi: Subsequent Address Family Identifier (default: unicast)
+            action: Action (ANNOUNCE or WITHDRAW, default: ANNOUNCE)
+        """
+        super().__init__(afi, safi, action, PathInfo.DISABLED)
+        self._packed = b''
+
+    def pack_nlri(self, negotiated: 'Negotiated') -> Buffer:
+        """Pack to empty bytes (no NLRI)."""
+        return b''
+
+    def json(self, compact: bool = False) -> str:
+        """JSON representation (empty object)."""
+        return '{}'
+
+    def __str__(self) -> str:
+        return 'empty'
+
+    def __repr__(self) -> str:
+        return 'Empty()'
+
+    def __copy__(self) -> 'Empty':
+        new = object.__new__(Empty)
+        self._copy_nlri_slots(new)
+        return new
+
+    def __deepcopy__(self, memo: dict[Any, Any]) -> 'Empty':
+        new = object.__new__(Empty)
+        self._deepcopy_nlri_slots(new, memo)
+        return new
+
+    def feedback(self, action: Action) -> str:
+        return 'empty'

src/exabgp/bgp/message/update/nlri/nlri.py

@@ -137,6 +137,8 @@ def __deepcopy__(self, memo: dict[Any, Any]) -> 'NLRI':
         raise NotImplementedError(f'{type(self).__name__} must implement __deepcopy__')
 
     def __hash__(self) -> int:
+        from exabgp.bgp.message.open.capability.negotiated import Negotiated
+
         return hash('{}:{}:{}'.format(self.afi, self.safi, self.pack_nlri(Negotiated.UNSET).hex()))
 
     def __eq__(self, other: Any) -> bool:
@@ -168,6 +170,8 @@ def add(self, data: Any) -> bool:
         raise NotImplementedError('add() only implemented by Flow NLRI')
 
     def index(self) -> bytes:
+        from exabgp.bgp.message.open.capability.negotiated import Negotiated
+
         return bytes(Family.index(self)) + self.pack_nlri(Negotiated.UNSET)
 
     def pack_nlri(self, negotiated: Negotiated) -> Buffer:

src/exabgp/configuration/command.py

@@ -529,6 +529,12 @@ def decode_to_api_command(payload_hex: str, neighbor: 'Neighbor', generic: bool
                 else:
                     commands.append(f'withdraw {api_family} {nlri_info}')
 
+        # Attributes-only UPDATE (no announce, no withdraw, just attributes)
+        if not commands and attributes:
+            attr_parts = format_attributes(attributes)
+            if attr_parts:
+                commands.append('attributes ' + ' '.join(attr_parts))
+
         return commands
 
     except Exception:

src/exabgp/configuration/static/__init__.py

@@ -137,19 +137,43 @@ def route(tokeniser: Any) -> list[Route]:
 
 @ParseStatic.register('attributes', 'append-route')
 def attributes(tokeniser: Any) -> list[Route]:
-    """Parse attributes with multiple NLRIs using deferred construction (Settings pattern).
+    """Parse attributes with optional NLRIs using deferred construction (Settings pattern).
 
     Collects shared settings first, then creates immutable NLRIs for each prefix.
+    If no 'nlri' keyword or no prefixes, returns an attributes-only Route
+    that generates an UPDATE with just path attributes and no NLRI.
     """
     from copy import copy
 
+    from exabgp.bgp.message.update.nlri.empty import Empty
+
     nlri_action = Action.ANNOUNCE if tokeniser.announce else Action.WITHDRAW
-    ipmask = prefix(lambda: tokeniser.tokens[-1])
-    tokeniser.afi = ipmask.afi
+
+    # Check if there are any IP prefixes in the tokens (look-ahead for nlri keyword)
+    has_nlri_keyword = 'nlri' in tokeniser.tokens
+
+    # Try to parse the last token as a prefix to determine AFI
+    # If it fails, this is an attributes-only command
+    has_prefix = False
+    ipmask = None
+    if has_nlri_keyword:
+        try:
+            ipmask = prefix(lambda: tokeniser.tokens[-1])
+            has_prefix = True
+        except (ValueError, KeyError):
+            pass
+
+    if has_prefix and ipmask is not None:
+        tokeniser.afi = ipmask.afi
+    else:
+        tokeniser.afi = AFI.ipv4  # Default for attributes-only
 
     # Create template settings with initial values
     template_settings = INETSettings()
-    template_settings.afi = IP.toafi(ipmask.top())
+    if has_prefix and ipmask is not None:
+        template_settings.afi = IP.toafi(ipmask.top())
+    else:
+        template_settings.afi = AFI.ipv4
     template_settings.action = nlri_action
     attr = AttributeCollection()
 
@@ -164,15 +188,24 @@ def attributes(tokeniser: Any) -> list[Route]:
     elif has_label:
         nlri_class = Label
         template_settings.safi = SAFI.nlri_mpls
-    else:
+    elif has_prefix and ipmask is not None:
         nlri_class = INET
         template_settings.safi = IP.tosafi(ipmask.top())
+    else:
+        nlri_class = INET
+        template_settings.safi = SAFI.unicast
 
     # Parse shared attributes - collect into template settings
     while True:
         command = tokeniser()
 
         if not command:
+            # No more tokens - check if we have NLRIs or just attributes
+            if not has_nlri_keyword:
+                # Attributes-only: return Route with Empty NLRI
+                if attr:
+                    empty_nlri = Empty(AFI.ipv4, SAFI.unicast, nlri_action)
+                    return [Route(empty_nlri, attr)]
             return []
 
         if command == 'nlri':
@@ -223,4 +256,9 @@ def attributes(tokeniser: Any) -> list[Route]:
         new_nlri = nlri_class.from_settings(settings)
         routes.append(Route(new_nlri, attr, nexthop=settings.nexthop))
 
+    # If 'nlri' keyword was present but no prefixes followed, return attributes-only
+    if not routes and attr:
+        empty_nlri = Empty(AFI.ipv4, SAFI.unicast, nlri_action)
+        return [Route(empty_nlri, attr)]
+
     return routes