Skip to content

refactor(protocols): __index__ returns the protocol's LinkType, EtherType, TransType or AppType value where one exists #2627

New issue
New issue
Closed
#2652
Closed
refactor(protocols): __index__ returns the protocol's LinkType, EtherType, TransType or AppType value where one exists#2627
#2652
Labels
refactorRestructuring for its own sake — neither a fix nor a new capability (refactor: prefix)
Milestone
PyPCAPKit v1.6

Description

@JarryShaw
JarryShaw
opened on Nov 2, 2026

Owner ruling, given in session and paraphrased: a protocol's __index__ returns its LinkType, EtherType, TransType or AppType value wherever one exists, ahead of any other registry's code, such as ARPHRD or NLPID.

Today the classes are inconsistent. Radiotap.__index__ returns ARPHRD.IEEE80211_RADIOTAP (803), although LinkType.IEEE802_11_RADIOTAP (127) exists, while #2608 makes IEEE802_11.__index__ return LinkType.IEEE802_11 (105).

Plan:

  1. Audit every protocol's __index__: what it returns or raises, which standard registry value exists for it, and which code relies on it.
  2. Switch each one to the standard value where one exists. Any registration that keyed a secondary registry, such as LinuxSLL's ARPHRD map, by __index__ names its key explicitly instead.
  3. Write the rule onto the registry convention page.

Byte-for-byte output must not change.

Activity

  1. JarryShaw
    added this to the PyPCAPKit v1.6 milestone on Nov 2, 2026
  2. JarryShaw
    added
    refactorRestructuring for its own sake — neither a fix nor a new capability (refactor: prefix)
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 2, 2026
  3. github-project-automation
    added this to PyPCAPKiton Nov 2, 2026
  4. JarryShaw
    moved this to WIP in PyPCAPKiton Nov 2, 2026

  5. JarryShaw commented on Nov 2, 2026

    @JarryShaw
    JarryShaw
    on Nov 2, 2026
    OwnerAuthor

    The __index__ migration is done locally (352f6894c) and passed a Sonnet review. These now return their standard value:

    Class Value
    Radiotap LinkType.IEEE802_11_RADIOTAP (127)
    FRAD LinkType.FRELAY (107)
    Netlink LinkType.NETLINK (253)
    GRE TransType.GRE (47)
    L2TPv2 UDP.l2tp
    FTP / FTP_DATA TCP.ftp / TCP.ftp_data
    HTTP TCP.http
    NGAP SCTP.ng_control

    All 1,367 dispatch maps dump identically, every capture parses identically, and the rule is written onto registry-protocol.rst.

    Being fixed now: an AppType member is a StrEnum, so returning it from __index__ makes int(FTP(...)) raise TypeError: __index__ returned non-int. AppType-valued classes will return the member's port number as an int.

    Needs deciding. The branch proceeds on these recommendations unless you choose otherwise.

    1. TLS and DTLS still raise, although TCP 443 and UDP 5684 bind them. Should they return TCP.https and UDP.coaps, the port they are dispatched under, as HTTP returns TCP.http? Recommend yes.
    2. Netlink → LinkType.NETLINK (253). A LINKTYPE_NETLINK record opens with an SLL-style header that Netlink itself does not parse. (a) Keep 253 per the rule. (b) Keep ARPHRD.NETLINK, because 253 names the SLL-framed form rather than this class. Recommend (b).
    3. Bindings. FRAD (107), Netlink (253) and GRE (IP protocol 47) now name values that no table dispatches on. A reachability test lists them as unbound. Binding them changes parse output from Raw to the dissector, so I recommend a follow-up issue, not this PR.
    4. Label. Seven shipped classes go from raising to returning a value: L2TPv2, FTP, FTP_DATA, HTTP, HTTPv1, HTTPv2 and NGAP. No shipped value changes. Recommend not labelling it breaking.
  6. JarryShaw
    added
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Nov 2, 2026
  7. JarryShaw
    moved this from WIP to Needs decision in PyPCAPKiton Nov 2, 2026

  8. JarryShaw commented on Nov 2, 2026

    @JarryShaw
    JarryShaw
    on Nov 2, 2026
    OwnerAuthor
    1. Yes
    2. B
    3. Followup issue
    4. Take recommendations

  9. JarryShaw commented on Nov 2, 2026

    @JarryShaw
    JarryShaw
    on Nov 2, 2026
    OwnerAuthor

    The owner answered all four, paraphrased:

    1. TLS and DTLS return the port they are dispatched under, TCP.https (443) and UDP.coaps (5684), as an int, as HTTP returns TCP.http.
    2. Netlink keeps ARPHRD.NETLINK, because LINKTYPE_NETLINK (253) names the SLL-framed form, not this class.
    3. Binding FRAD's and GRE's values goes to a follow-up, feat(protocols): bind FRAD's and GRE's standard registry values #2649.
    4. No breaking label: the seven shipped classes go from raising to returning a value, and no shipped value changes.

    This settles every open question, so needs: decision comes off. The branch (3a9f9047e, with the AppType values returning int) is being updated for 1 and 2. A cross-review follows before the PR opens.

    The decision watch missed this answer for about two and a half hours. It arrived seconds before one of my posts, and I moved the watch's marker past it. The marker logic is fixed.

  10. JarryShaw
    removed
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Nov 2, 2026
  11. JarryShaw
    moved this from Needs decision to WIP in PyPCAPKiton Nov 2, 2026

  12. JarryShaw commented on Nov 2, 2026

    @JarryShaw
    JarryShaw
    on Nov 2, 2026
    OwnerAuthor

    The PR is #2652.

  13. JarryShaw
    added 2 commits that reference this issue on Nov 2, 2026

    refactor(protocols): index each protocol by its LinkType, EtherType, …

    e56b57c

    refactor(protocols): index each protocol by its LinkType, EtherType, …

    32935fc
  14. JarryShaw
    closed this as completedin #2652on Nov 2, 2026
  15. github-project-automation
    moved this from WIP to Done in PyPCAPKiton Nov 2, 2026
  16. JarryShaw
    removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 2, 2026
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

    refactorRestructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions