Trait KeyFields

Source

pub trait KeyFields {
    // Provided methods
    fn src_ip(&self) -> Option<IpAddr> { ... }
    fn src_port(&self) -> Option<u16> { ... }
    fn dest_ip(&self) -> Option<IpAddr> { ... }
    fn dest_port(&self) -> Option<u16> { ... }
    fn proto_str(&self) -> Option<&'static str> { ... }
    fn protocol_identifier(&self) -> Option<u8> { ... }
    fn app_proto_str(&self) -> Option<&'static str> { ... }
    fn stable_hash(&self) -> Option<u64> { ... }
    fn shard_index(&self, n: usize) -> Option<usize> { ... }
    fn community_id(&self) -> Option<String> { ... }
    fn community_id_seeded(&self, seed: u16) -> Option<String> { ... }
}

Expand description

Structured access to flow-key fields for emit writers.

All methods default to None so implementors override only the fields they actually carry. Emit writers MUST tolerate None returns — they correspond to “field not applicable for this key type” (e.g. src_port() on an IP-only key).

§Implementing for custom keys

Custom crate::FlowExtractor::Key types should implement this trait if they want to flow through CSV / NDJSON / Zeek / EVE without fallback Debug formatting:

use std::net::IpAddr;
use flowscope::KeyFields;

struct MyKey { src: IpAddr, dst: IpAddr }

impl KeyFields for MyKey {
    fn src_ip(&self) -> Option<IpAddr> { Some(self.src) }
    fn dest_ip(&self) -> Option<IpAddr> { Some(self.dst) }
}

Provided Methods§

Source

fn src_ip(&self) -> Option<IpAddr>

Source IP for the flow.

Source

fn src_port(&self) -> Option<u16>

Source port (TCP/UDP).

Source

fn dest_ip(&self) -> Option<IpAddr>

Destination IP for the flow.

Source

fn dest_port(&self) -> Option<u16>

Destination port (TCP/UDP).

Source

fn proto_str(&self) -> Option<&'static str>

L4 protocol as a static EVE-compatible label ("TCP" / "UDP" / "ICMP" / "ICMPv6" / "SCTP").

Source

fn protocol_identifier(&self) -> Option<u8>

L4 protocol number per IANA assigned numbers (TCP=6, UDP=17, ICMP=1, ICMPv6=58, SCTP=132). Used by IPFIX-IE-keyed exporters that need the numeric ID alongside the Self::proto_str label. Default None — override on keys that carry an L4 protocol.

Issue #16 — needed by the FlowRecord::from_key_fields generic constructor so emit writers can unify the write_event(Ended) → write_flow_record code path.

Source

fn app_proto_str(&self) -> Option<&'static str>

Application-layer protocol label, e.g. "http" / "dns" / "tls". Default None — emit writers typically thread the parser_kind from crate::driver::SlotMessage instead. Override only on custom keys that carry app-layer hints natively.

Source

fn stable_hash(&self) -> Option<u64>

Stable, seed-fixed 64-bit hash over the canonical (direction-normalized) 5-tuple.

Unlike a #[derive(Hash)] run through RandomState (a per-process random seed), this is reproducible across threads and processes — the property required for sharding a merged flow table so both legs of a flow always land on the same worker (see Self::shard_index). A→B and B→A produce the same value.

Returns None if any of (proto, src ip/port, dest ip/port) is unknown. The algorithm is FNV-1a. This is a fast, non-portable in-process identifier — it is not emitted by the EVE / NDJSON writers (which lead with the portable community_id since 0.19, issue #88). Use it for sharding / in-memory keying, not for cross-tool pivots.

Issue #76 (folds #70).

Source

fn shard_index(&self, n: usize) -> Option<usize>

Deterministic shard index in 0..n for sharded flow tables. None if n == 0 or the key lacks a full 5-tuple.

Built on Self::stable_hash, so both directions of a flow map to the same shard across processes — the correctness requirement for tap-merge sharding.

Issue #76 (folds #70).

Source

fn community_id(&self) -> Option<String>

Corelight Community ID v1 with the universal default seed (0) — the cross-tool flow id for pivoting flowscope output against Zeek / Suricata / Security Onion.

Returns Some only when the crate is built with the community-id feature and the key carries a full 5-tuple; otherwise None. TCP/UDP/SCTP are exact; ICMP is stable but not spec-compatible (see crate::community_id).

Issue #76.

Source