feat: Implement Link-Local Next Hop Capability procedures

Implements the wire-encoding and configuration for LLNH (code 77)
per draft-ietf-idr-linklocal-capability:

- Add _encode_nexthop() for LLNH-aware next-hop encoding:
  - 16-byte: link-local only or global only
  - 32-byte: global + link-local (always this order per RFC)
- Add local-link-local config for explicit LLA in next-hop
- Add link-local-prefer config for receiver forwarding preference
- Add is_multihop() to exclude LLA when TTL > 1 (not directly connected)
- Add link_local_address() and link_local_prefer() to Negotiated
- Validate local-link-local is fe80::/10

Configuration:
  neighbor X {
    local-link-local fe80::1;
    capability {
      link-local-nexthop enable;
      link-local-prefer enable;
    }
  }

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: thomas-mangin

src/exabgp/bgp/message/open/capability/negotiated.py

@@ -241,6 +241,23 @@ def validate(self, neighbor: Any) -> tuple[int, int, str] | None:
     def nexthopself(self, afi: AFI) -> 'IP':
         return self.neighbor.ip_self(afi)
 
+    def link_local_address(self) -> 'IP | None':
+        """Get the local link-local IPv6 address if available."""
+        return self.neighbor.session.ip_link_local()
+
+    def link_local_prefer(self) -> bool:
+        """Check if link-local nexthop is preferred over global."""
+        return self.neighbor.capability.link_local_prefer
+
+    def is_multihop(self) -> bool:
+        """Check if session is multihop (TTL > 1).
+
+        Used to determine if link-local addresses should be excluded from
+        next-hop (link-local only valid for directly connected peers).
+        """
+        ttl = self.neighbor.session.outgoing_ttl
+        return ttl is not None and ttl > 1
+
     @property
     def is_ibgp(self) -> bool:
         """Return True if this is an IBGP session (local_as == peer_as)."""

src/exabgp/bgp/message/update/attribute/mprnlri.py

@@ -191,8 +191,10 @@ def unpack_attribute(cls, data: Buffer, negotiated: Negotiated) -> Attribute:
 
         length, rd = Family.size[(afi, safi)]
 
-        # Note: link-local nexthop capability (code 77) doesn't change validation -
-        # 16-byte nexthops are already valid for IPv6 families in Family.size
+        # Link-Local Next Hop Capability (code 77) validation:
+        # - 16-byte IPv6 nexthops are valid (could be global or link-local)
+        # - With LLNH negotiated, 16-byte link-local (fe80::/10) is explicitly allowed
+        # - Semantic interpretation of 16-byte NH depends on LLNH negotiation
         if negotiated.nexthop:
             if len_nh in (16, 32, 24):
                 nh_afi = AFI.ipv6

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

@@ -272,6 +272,72 @@ def _attr_len(self, payload_len: int) -> int:
         """Calculate total attribute length including header."""
         return payload_len + (4 if payload_len > 255 else 3)
 
+    def _encode_nexthop(
+        self,
+        nlri_nexthop: IP,
+        family_key: tuple[AFI, SAFI],
+        negotiated: 'Negotiated',
+    ) -> bytes:
+        """Encode nexthop bytes for MP_REACH_NLRI.
+
+        Handles link-local nexthop capability (RFC draft-ietf-idr-linklocal-capability):
+        - 16-byte: link-local only (when LLNH negotiated) or global only
+        - 32-byte: global + link-local (for IPv6 unicast/labeled)
+
+        Args:
+            nlri_nexthop: The route's next-hop IP address.
+            family_key: (AFI, SAFI) tuple for the family.
+            negotiated: BGP session parameters.
+
+        Returns:
+            Packed nexthop bytes (including RD if applicable).
+        """
+        from exabgp.protocol.family import Family
+
+        if nlri_nexthop is IP.NoNextHop:
+            return b''
+
+        _, rd_size = Family.size.get(family_key, (0, 0))
+        nh_rd = bytes([0]) * rd_size if rd_size else b''
+
+        try:
+            nh_packed = nlri_nexthop.pack_ip()
+        except TypeError:
+            # Fallback for invalid nexthop
+            return bytes([0]) * 4
+
+        # Only apply LLNH logic for IPv6 families
+        if family_key[0] != AFI.ipv6:
+            return nh_rd + nh_packed
+
+        # Check if LLNH capability is negotiated
+        if not negotiated.linklocal_nexthop:
+            # Without LLNH, just send the nexthop as-is
+            return nh_rd + nh_packed
+
+        # Check if session is multihop - link-local not usable beyond 1 hop
+        # RFC draft-ietf-idr-linklocal-capability: exclude LLA for non-directly-connected peers
+        if negotiated.is_multihop():
+            return nh_rd + nh_packed
+
+        # Get link-local address if available
+        link_local = negotiated.link_local_address()
+        is_nh_link_local = nlri_nexthop.is_link_local()
+
+        # Case 1: Nexthop is already link-local - send as 16-byte (with LLNH negotiated)
+        if is_nh_link_local:
+            return nh_rd + nh_packed
+
+        # Case 2: Nexthop is global, and we have a link-local to include
+        # Wire format is ALWAYS: Global (16 bytes) + Link-local (16 bytes)
+        # The link-local-prefer config affects receiver's forwarding decision, not wire order
+        if link_local is not None:
+            lla_packed = link_local.pack_ip()
+            return nh_rd + nh_packed + lla_packed
+
+        # Case 3: Global nexthop, no link-local available - send as 16-byte
+        return nh_rd + nh_packed
+
     def packed_reach_attributes(
         self,
         negotiated: 'Negotiated',
@@ -288,8 +354,6 @@ def packed_reach_attributes(
         Yields:
             Wire-format attribute bytes (with flags/type/length header).
         """
-        from exabgp.protocol.family import Family
-
         # Filter NLRIs for this family and group by nexthop
         mpnlri: dict[bytes, list[bytes]] = {}
         family_key = (self._afi, self._safi)
@@ -301,19 +365,8 @@ def packed_reach_attributes(
             if nlri.family().afi_safi() != family_key:
                 continue
 
-            # Encode nexthop
-            # Note: link-local capability doesn't change encoding - existing code
-            # already produces correct lengths (16 for IPv6, 24 for VPNv6)
-            if nlri_nexthop is IP.NoNextHop:
-                nexthop = b''
-            else:
-                _, rd_size = Family.size.get(family_key, (0, 0))
-                nh_rd = bytes([0]) * rd_size if rd_size else b''
-                try:
-                    nexthop = nh_rd + nlri_nexthop.pack_ip()
-                except TypeError:
-                    # Fallback for invalid nexthop
-                    nexthop = bytes([0]) * 4
+            # Encode nexthop with LLNH support
+            nexthop = self._encode_nexthop(nlri_nexthop, family_key, negotiated)
 
             mpnlri.setdefault(nexthop, []).append(bytes(nlri.pack_nlri(negotiated)))
 

src/exabgp/bgp/neighbor/capability.py

@@ -81,6 +81,7 @@ class NeighborCapability:
     nexthop: TriState = TriState.UNSET
     aigp: TriState = TriState.UNSET
     link_local_nexthop: TriState = TriState.UNSET
+    link_local_prefer: bool = False  # Prefer link-local over global when both present
     software_version: str | None = None
 
     def copy(self) -> 'NeighborCapability':
@@ -99,6 +100,7 @@ def copy(self) -> 'NeighborCapability':
             nexthop=self.nexthop,
             aigp=self.aigp,
             link_local_nexthop=self.link_local_nexthop,
+            link_local_prefer=self.link_local_prefer,
             software_version=self.software_version,
         )
 
@@ -117,5 +119,6 @@ def __eq__(self, other: object) -> bool:
             and self.nexthop == other.nexthop
             and self.aigp == other.aigp
             and self.link_local_nexthop == other.link_local_nexthop
+            and self.link_local_prefer == other.link_local_prefer
             and self.software_version == other.software_version
         )

src/exabgp/bgp/neighbor/session.py

@@ -36,6 +36,7 @@ class Session:
 
     # With defaults (non-None where possible)
     local_address: IP = field(default_factory=lambda: IP.NoNextHop)  # NoNextHop = auto-discovery
+    local_link_local: IP | None = None  # Link-local address for IPv6 (fe80::/10)
     local_as: ASN = field(default_factory=lambda: ASN(0))  # 0 = auto (mirror peer)
     peer_as: ASN = field(default_factory=lambda: ASN(0))  # 0 = auto
     router_id: 'RouterID | None' = None  # Derived from local_address if None and IPv4
@@ -127,6 +128,14 @@ def ip_self(self, afi: AFI) -> IP:
             f'use of "next-hop self": the route ({afi}) does not have the same family as the BGP tcp session ({local_afi})',
         )
 
+    def ip_link_local(self) -> IP | None:
+        """Get the local link-local IPv6 address if available.
+
+        Returns:
+            Link-local IP or None if not set.
+        """
+        return self.local_link_local
+
     def connection_established(self, local: str) -> None:
         """Called after TCP connection to set auto-discovered values.
 

src/exabgp/configuration/capability.py

@@ -140,6 +140,14 @@ class ParseCapability(Section):
                 operation=ActionOperation.SET,
                 key=ActionKey.COMMAND,
             ),
+            'link-local-prefer': Leaf(
+                type=ValueType.BOOLEAN,
+                description='Prefer link-local over global IPv6 next-hop when both present',
+                default=False,
+                target=ActionTarget.SCOPE,
+                operation=ActionOperation.SET,
+                key=ActionKey.COMMAND,
+            ),
         },
     )
 
@@ -154,6 +162,7 @@ class ParseCapability(Section):
         '   extended-message enable|disable;\n'
         '   software-version enable|disable;\n'
         '   link-local-nexthop enable|disable;\n'
+        '   link-local-prefer enable|disable;\n'
         '}\n'
     )
 
@@ -176,6 +185,7 @@ class ParseCapability(Section):
         'extended-message': True,
         'software-version': False,
         'link-local-nexthop': None,
+        'link-local-prefer': False,
     }
 
     name = 'capability'

src/exabgp/configuration/neighbor/__init__.py

@@ -66,6 +66,13 @@ class ParseNeighbor(Section):
                 operation=ActionOperation.SET,
                 key=ActionKey.COMMAND,
             ),
+            'local-link-local': Leaf(
+                type=ValueType.IP_ADDRESS,
+                description='Local IPv6 link-local address for LLNH capability (fe80::/10)',
+                target=ActionTarget.SCOPE,
+                operation=ActionOperation.SET,
+                key=ActionKey.COMMAND,
+            ),
             'local-as': Leaf(
                 type=ValueType.ASN,
                 description='Local AS number (or "auto" to copy peer-as)',
@@ -332,6 +339,7 @@ def _post_get_scope(self) -> dict[str, Any]:
     _CONFIG_TO_SESSION: dict[str, str] = {
         'router-id': 'router_id',
         'local-address': 'local_address',
+        'local-link-local': 'local_link_local',
         'source-interface': 'source_interface',
         'peer-address': 'peer_address',
         'local-as': 'local_as',
@@ -413,6 +421,8 @@ def _post_capa_default(self, neighbor: Neighbor, local: dict[str, Any]) -> None:
         if 'link-local-nexthop' in capability:
             if capability['link-local-nexthop'] is not None:
                 cap.link_local_nexthop = TriState.from_bool(capability['link-local-nexthop'])
+        if 'link-local-prefer' in capability:
+            cap.link_local_prefer = capability['link-local-prefer']
         if 'graceful-restart' in capability:
             gr = capability['graceful-restart']
             if gr is False:
@@ -540,6 +550,11 @@ def post(self) -> bool:
         if neighbor.session.peer_address is IP.NoNextHop:
             return self.error.set('peer-address must be set')
 
+        # Validate local-link-local is actually a link-local address if set
+        if neighbor.session.local_link_local is not None:
+            if not neighbor.session.local_link_local.is_link_local():
+                return self.error.set('local-link-local must be an IPv6 link-local address (fe80::/10)')
+
         # peer_address is always IPRange when parsed from configuration (see parser.peer_ip)
         assert isinstance(neighbor.session.peer_address, IPRange)
         peer_range = neighbor.session.peer_address

tests/fuzz/test_update_message_integration.py

@@ -88,6 +88,12 @@ def create_negotiated_mock(families: Any = None, asn4: Any = False, msg_size: An
     negotiated.local_as = ASN(65000)
     negotiated.peer_as = ASN(65001)
 
+    # Link-local nexthop capability (default: disabled)
+    negotiated.linklocal_nexthop = False
+    negotiated.link_local_address = Mock(return_value=None)
+    negotiated.link_local_prefer = Mock(return_value=False)
+    negotiated.is_multihop = Mock(return_value=False)
+
     return negotiated