Skip to content

Flow keys — hashable 5-tuples with a canonical bidirectional form #89

Description

@EONRaider

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

Headers are already frozen, slotted and hashable — hash(eth) works
and headers can be dict keys or set members today. What is missing is
the thing everyone builds on top of that: a flow key.

There is no Flow, no FlowKey, no five_tuple anywhere in src/.
The only flow in the codebase is IPv6.flow_label.

What to do

A flow_key() returning a hashable tuple of
(src, dst, src_port, dst_port, protocol), plus a canonical
bidirectional form
so both directions of one conversation collapse
to a single key — that second part is the piece people most often get
subtly wrong by hand.

Design questions:

  • Where does it live? It needs a network layer and a transport layer,
    so neither header alone can produce it. A free function taking both,
    or a method on Packet (Make Packet pull its weight — type indexing, hashing, and a rename #90), fits better than a method on TCP.
  • Typed shape: a NamedTuple gives field names and stays hashable and
    cheap; a frozen dataclass matches house style. Prefer consistency
    with the rest of the library.
  • What about ICMP, which has no ports, and IPv6 with extension
    headers between network and transport?

Why it matters

This is what scapy cannot do well (its packets are mutable and
unhashable) and what dpkt makes you hand-roll. It is the natural
payoff of a design decision already made.

Acceptance criteria

  • Both directions of a conversation produce equal canonical keys.
  • Keys are hashable and usable as dict keys directly.
  • Works across IPv4, IPv6, TCP and UDP; ICMP behaviour documented.

Part of #104.

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