A public protocol registry

[EONRaider]

Target: 2.0.0 (Tier 2 — from codec to platform)

There is no registry. Dispatch is four hardcoded functions
(_ethertype_class, _ip_protocol_class, udp_app_class,
tcp_app_class) with dict literals inside them. There is no
__init_subclass__, no decorator, no public hook.

Nobody can add a protocol to NETProtocols without editing library
source and sending a pull request. Every serious user eventually
meets a protocol we do not implement — MPLS, VXLAN, a proprietary
telemetry header, something from an industrial bus — and their only
options today are to fork or to leave.

This is the single biggest structural limitation in the codebase.

Why it is also the performance fix

A real registry is a module-level dict built once, which is exactly
what #82 needs. The two are the same change. Ship #82 as the
internal table, then generalise it here — or design them together.

Prior art worth following

Both leading designs in this space work this way: Wireshark's
DissectorTable has dissectors register themselves against a parent
field value rather than parents hard-coding their children, and
gopacket does the same. Being able to extend the decode walk without
forking is the main practical reason people reach for scapy over a
small library.

Shape to aim for

@register(EtherType.MPLS)
class MPLS(Protocol):
 ...

# and for numbers with no enum member yet
register(IPProtocol, 132, SCTP)

Design questions to settle first

• Does registration mutate global state, or can a caller get an
  isolated registry? Global is simpler; isolated is safer for
  libraries that embed us and for test isolation.
• What happens on a duplicate registration — raise, or last-wins?
• Does the ipv6= gating generalise, or stay special-cased?
• Wireshark's "Decode As" equivalent: should decode_frame() (Ship decode_frame() — the chain walker belongs in the library #88)
  accept a per-call override such as decode_as={6969: DNS}?

Acceptance criteria

• A third party can register a decoder without editing library
  source.
• Existing dispatch behaviour, including IPv6-only gating, is
  unchanged.
• The registry is the dispatch mechanism, not a layer on top of the
  hardcoded functions.

[EONRaider]

Design questions settled

Decisions from the maintainer, recorded before implementation.

1. Registration scope — global default, explicit registry on the walker.

next_protocol() is a zero-argument accessor on a frozen header; threading a
registry through it would change the public signature of every protocol class
for a use case most callers do not have. decode_frame() (#88) is a function
and takes registry= for free, so that is where isolation lives.

ip.next_protocol() # global default, unchanged

reg = Registry.from_defaults()
reg.register("udp.port", 6969, DNS)
decode_frame(frame, registry=reg) # isolated

The default registry's tables stay the module-level dicts the layer modules
already hold, so the hot path remains a bare dict.get and #82's 91× stands.
A ContextVar was considered and rejected: it costs a lookup per dispatch and
makes the active registry implicit.

2. Duplicate registration — raise, override=True to replace.

The error names the incumbent class so a conflict between two third-party
packages is diagnosable rather than order-dependent. One non-negotiable detail:
re-registering the same class to the same key is a no-op, not an error,
because @register(...) re-runs on any module re-execution (reload, doctest
collection, test reruns) and a strict raise would turn that into spurious
failures.

3. ipv6= gating — generalised into named tables.

The boolean does not generalise but the concept does: what ipv6= encodes is
which table this parent dispatches into. IPv4's protocol and IPv6's
next_header share a number space but are different tables.

ethertype GRE protocol-type and VLAN chain into this one too
ip.proto IPv4 payloads
ip.proto.v6 inherits ip.proto, adds the four extension headers
udp.port
tcp.port

ip.proto.v6 is flattened at build time, so gating costs nothing at lookup —
dispatch is still one dict.get, exactly as #82 left it. Registering into
ip.proto reaches both; registering into ip.proto.v6 reaches the v6 chain
only.

Consequence to accept: test_dispatch_tables_differ_only_by_the_ipv6_only_numbers
currently reads live module globals, and once third parties can add to
ip.proto.v6 that invariant only holds over the built-in registrations.
The test will be re-stated accordingly rather than deleted.

4. "Decode As" — yes, table-scoped, built in #88.

{6969: DNS} is ambiguous (UDP port? TCP port? ethertype?), and with named
tables the unambiguous form falls straight out. It stays out of this issue's
scope — decode_frame() does not exist yet — but #87 must ship the primitive
that makes it a small change:

child = registry.derive({"udp.port": {6969: DNS}}) # #87 ships this
decode_frame(frame, decode_as={...}) # #88 spends it

One thing found while grounding this

#82 named only _ethertype_class and _ip_protocol_class. The other two
dispatch points were never in its scope and still rebuild a dict literal and
re-run their deferred imports on every call — layer4/_ports.py:34 and :50:

udp_app_class 362.4 ns/call
_ethertype_class 61.7 ns/call
ratio 5.9x

The registry closes this for free, since all four dispatch points become table
lookups. It also means this issue lands with a measurable throughput delta that
the 15% CI gate will register — unusual for a Tier 2 API change.

Deviation from the sketch above

The issue sketches @register(EtherType.MPLS) with the table inferred from the
enum. With decision 3 the table is named explicitly instead, so the shape is
@register("ethertype", EtherType.MPLS). Inferring the table from an enum
member would work for the two enum-keyed tables but not for the port tables,
which are plain int, so the explicit form is the only one that covers all
five uniformly.

---

Generated by Claude Code