Skip to content

MPLS label-stack decoding (RFC 3032) #187

Description

@EONRaider

Target: 2.5.0 (Tier 3 — L2 discovery & tunneling)

Context

MPLS is registry.py's own canonical "how to add a protocol"
example (@register("ethertype", 0x8847) class MPLS(Protocol): ...),
repeated in ARCHITECTURE.md, README.md, and docs/CLAIMS.md as
the illustration of extending the library without editing its
source — and it's real code nobody has actually written yet.

Deliverable

Add netprotocols.MPLS (layer 2, dispatched from ethertype):

  • Decode the 4-byte label stack entry (RFC 3032 §2.1): Label (20
    bits), Traffic Class/EXP (3 bits), Bottom of Stack "S" bit (1 bit),
    TTL (8 bits). MPLS frames carry a stack of these — decode
    entries until S=1 marks the bottom, exposing MPLS.labels as a
    tuple rather than modeling only a single label.
  • Design question, not a footnote: MPLS's shim header has no
    next-protocol field.
    There is no way to know from the header alone
    whether the payload below the bottom label is IPv4, IPv6, or
    something else. Real stacks resolve this by convention, not
    signaling: sniff the payload's first nibble (4 → IPv4, 6 → IPv6) —
    the same heuristic dpkt and scapy both use, since RFC 4928's
    Pseudowire Control Word (a leading zero nibble) is the only other
    common case and is itself distinguishable from 4/6. Implement
    next_protocol() as that sniff, and say so plainly in the
    docstring — this is the one place in the library where dispatch
    isn't a clean table lookup on a wire value.
  • Add EtherType.MPLS — RFC 3032 defines two: unicast (0x8847) and
    multicast (0x8848) — with display names; wire both into Ethernet
    dispatch to the same MPLS class.

Acceptance criteria

  • MPLS decodes a full label stack (single and multi-label
    cases); bytes(MPLS.decode(x)) == x.
  • next_protocol() implements the first-nibble heuristic,
    documented as such, correctly resolving IPv4/IPv6-carrying MPLS
    frames end to end.
  • EtherType 0x8847 and 0x8848 both dispatch to MPLS.
  • Fixture with a stacked-label case and truncation.
  • CHANGELOG entry; full ladder green.

References

RFC 3032 · Canonical extension example: registry.py,
ARCHITECTURE.md, README.md, docs/CLAIMS.md

Part of #173

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions