PcapFileEx.FlowKey (pcap_file_ex v0.5.5)

Stable identity for flow map lookups.

FlowKey contains only the fields necessary for identifying a unique flow: protocol type and endpoint information. It is used as a map key in AnalysisResult.flows for O(1) lookups.

Why FlowKey?

Using the full Flow struct as a map key would be fragile because Flow contains display fields (like from, server, client) that are derived and could vary. FlowKey contains only the authoritative fields needed for equality comparison.

Examples

iex> alias PcapFileEx.{FlowKey, Endpoint}
iex> client = Endpoint.new("192.168.1.10", 54321)
iex> server = Endpoint.new("192.168.1.20", 8080)
iex> FlowKey.new(:http2, client, server)
%PcapFileEx.FlowKey{
  protocol: :http2,
  client_endpoint: %PcapFileEx.Endpoint{ip: "192.168.1.10", port: 54321, host: nil},
  server_endpoint: %PcapFileEx.Endpoint{ip: "192.168.1.20", port: 8080, host: nil}
}

# UDP flows have nil client_endpoint
iex> FlowKey.new(:udp, nil, server)
%PcapFileEx.FlowKey{
  protocol: :udp,
  client_endpoint: nil,
  server_endpoint: %PcapFileEx.Endpoint{ip: "192.168.1.20", port: 8080, host: nil}
}

Summary

Types

protocol()

t()

Functions

equal?(key1, key2)

Compares two FlowKeys for equality.

new(protocol, client_endpoint, server_endpoint)

Creates a new FlowKey for map lookups.

normalize(key)

Normalizes a FlowKey for use as a map key.

Types

protocol()

@type protocol() :: :http1 | :http2 | :udp

t()

@type t() :: %PcapFileEx.FlowKey{
  client_endpoint: PcapFileEx.Endpoint.t() | nil,
  protocol: protocol(),
  server_endpoint: PcapFileEx.Endpoint.t()
}

Functions

equal?(key1, key2)

@spec equal?(t(), t()) :: boolean()

Compares two FlowKeys for equality.

Two FlowKeys are equal if they have the same protocol and endpoints. The host field in endpoints is ignored for comparison purposes since it's derived from hosts_map and may vary.

Examples

iex> alias PcapFileEx.{FlowKey, Endpoint}
iex> client = Endpoint.new("10.0.0.1", 12345)
iex> server = Endpoint.new("10.0.0.2", 80)
iex> key1 = FlowKey.new(:http1, client, server)
iex> key2 = FlowKey.new(:http1, client, server)
iex> FlowKey.equal?(key1, key2)
true

new(protocol, client_endpoint, server_endpoint)

@spec new(protocol(), PcapFileEx.Endpoint.t() | nil, PcapFileEx.Endpoint.t()) :: t()

Creates a new FlowKey for map lookups.

Parameters

protocol - The protocol type (:http1, :http2, or :udp)
client_endpoint - The client endpoint, or nil for UDP flows
server_endpoint - The server endpoint (required)

Examples

iex> alias PcapFileEx.{FlowKey, Endpoint}
iex> client = Endpoint.new("10.0.0.1", 12345)
iex> server = Endpoint.new("10.0.0.2", 80)
iex> key = FlowKey.new(:http1, client, server)
iex> key.protocol
:http1

iex> alias PcapFileEx.{FlowKey, Endpoint}
iex> server = Endpoint.new("10.0.0.2", 5005)
iex> key = FlowKey.new(:udp, nil, server)
iex> key.client_endpoint
nil

normalize(key)

@spec normalize(t()) :: t()

Normalizes a FlowKey for use as a map key.

Strips the host field from endpoints to ensure consistent key matching regardless of whether hosts_map was applied. This allows callers to pass either host-resolved or raw keys to AnalysisResult.get_flow/2.

Examples

iex> alias PcapFileEx.{FlowKey, Endpoint}
iex> client = Endpoint.new("10.0.0.1", 12345, "client-host")
iex> server = Endpoint.new("10.0.0.2", 80, "server-host")
iex> key = FlowKey.new(:http1, client, server)
iex> normalized = FlowKey.normalize(key)
iex> normalized.client_endpoint.host
nil
iex> normalized.server_endpoint.host
nil