Trait Reassembler 

pub trait Reassembler: Send + 'static {
    // Required method
    fn segment(&mut self, seq: u32, payload: &[u8], ts: Timestamp);

    // Provided methods
    fn segment_into(
        &mut self,
        seq: u32,
        payload: &[u8],
        ts: Timestamp,
    ) -> SegmentOutcome { ... }
    fn set_origin(&mut self, _seq: u32) { ... }
    fn peer_ack(&mut self, _ack: u32, _ts: Timestamp) { ... }
    fn fin_seen(&mut self, _end: u32, _ts: Timestamp) { ... }
    fn drain_into(&mut self, _out: &mut StreamChunks) { ... }
    fn flush_pending(&mut self) { ... }
    fn advance_time(&mut self, _now: Timestamp) { ... }
    fn fin(&mut self) { ... }
    fn rst(&mut self) { ... }
    fn dropped_segments(&self) -> u64 { ... }
    fn gaps(&self) -> u64 { ... }
    fn gap_bytes(&self) -> u64 { ... }
    fn bytes_dropped_oversize(&self) -> u64 { ... }
    fn stop_reason(&self) -> Option<ReassemblyStop> { ... }
    fn high_watermark(&self) -> u64 { ... }
    fn bytes_in_flight(&self) -> u64 { ... }
    fn high_watermark_crossings(&self) -> u64 { ... }
    fn high_watermark_threshold(&self) -> Option<(u64, u8)> { ... }
    fn retransmits(&self) -> u64 { ... }
    fn on_duplicate(&mut self, _seq: u32, _payload: &[u8], _ts: Timestamp) { ... }
    fn rexmit_inconsistencies(&self) -> u64 { ... }
    fn release(&mut self) { ... }
    fn current_bytes(&self) -> u64 { ... }
    fn out_of_window_segments(&self) -> u64 { ... }
    fn ack_confirmed_gaps(&self) -> u64 { ... }
    fn origin_resets(&self) -> u64 { ... }
}

Available on crate feature reassembler only.

Receives TCP segments for one direction of one session. Sync — implementors don’t await; for blocking consumers (Vec buffer, std::sync::mpsc, sync protocol parsers).

Two consumption styles are supported:

• Pull (the built-in reassemblers): segments accumulate in the reassembler and the driver drains them with Self::drain_into. This is what the session engines (crate::session::SessionDriver, crate::driver::Driver) use.
• Push: a custom reassembler forwards bytes from segment (to a channel, a file, …) and leaves drain_into at its no-op default.

Required Methods

fn segment(&mut self, seq: u32, payload: &[u8], ts: Timestamp)

New segment arrived in this direction.

payload borrows from the underlying frame — copy if you need it after returning. ts is the kernel/source timestamp of the packet carrying the segment.

Provided Methods

fn segment_into( &mut self, seq: u32, payload: &[u8], ts: Timestamp, ) -> SegmentOutcome

Like Self::segment, for a caller that can deliver the segment’s bytes itself, straight from the packet.

Return SegmentOutcome::Passthrough when payload[skip..] are exactly the next in-order bytes and nothing else is ready: the reassembler advances its position without buffering them, and the caller delivers them. Otherwise behave like segment and return SegmentOutcome::Buffered (the default). The session engines use this so in-order data is never copied or held per flow. New in 0.25.0.

fn set_origin(&mut self, _seq: u32)

The first byte of this direction has sequence number seq (ISN + 1, from the SYN / SYN-ACK). Called before the first segment when the handshake was seen; lets a reassembler anchor the stream instead of trusting the first data segment to arrive first. Default: no-op. New in 0.25.0.

fn peer_ack(&mut self, _ack: u32, _ts: Timestamp)

The peer acknowledged every byte of this direction below ack: those bytes were sent, even if the capture never saw them. Reassemblers use it to give up on holes the receiver already has (capture loss) instead of waiting for a deadline. Default: no-op. New in 0.25.0.

fn fin_seen(&mut self, _end: u32, _ts: Timestamp)

This direction sent a FIN whose sequence number is end: the stream ends there. Default: no-op. New in 0.25.0.

fn drain_into(&mut self, _out: &mut StreamChunks)

Move the reassembled output produced since the last call (in-order bytes, gap markers, and a stop reason if the reassembler stopped) onto the end of out. Default: no-op, for push-style reassemblers that deliver bytes themselves.

fn flush_pending(&mut self)

Give up on every hole still open: skip each one (reporting a gap) and make all buffered out-of-order data drainable. The driver calls this once when the flow ends, before the final drain. Default: no-op.

fn advance_time(&mut self, _now: Timestamp)

Time moved on without a segment for this side (the driver’s sweep). Reassemblers that wait for holes to fill use it to expire holes past their deadline. Default: no-op.

fn fin(&mut self)

FIN observed in this direction. Default: no-op.

fn rst(&mut self)

RST observed in this direction (or session aborted). Default: no-op.

fn dropped_segments(&self) -> u64

Segments whose bytes were discarded without ever being delivered — a segment that arrived after the hole it belonged to had already been skipped. Default: 0.

A default-zero return means “this implementation doesn’t track that counter,” not “the counter is zero.” Distinct from retransmits, which counts re-deliveries of bytes already accounted for.

fn gaps(&self) -> u64

Number of holes skipped (reported as gaps). Default: 0.

fn gap_bytes(&self) -> u64

Total bytes skipped across all gaps — Zeek’s missed_bytes. Default: 0.

fn bytes_dropped_oversize(&self) -> u64

Number of payload bytes dropped because the per-side buffer cap was exceeded. Default: 0.

fn stop_reason(&self) -> Option<ReassemblyStop>

Why the reassembler stopped accepting bytes, if it did (see ReassemblyStop). Default: None.

fn high_watermark(&self) -> u64

Peak buffer occupancy ever observed for this side. Default: 0 (custom reassemblers may not track this).

fn bytes_in_flight(&self) -> u64

Bytes currently buffered, awaiting consumption. Default: 0.

fn high_watermark_crossings(&self) -> u64

Running count of below→above transitions of the configured high-watermark threshold (see [BufferedReassembler:: with_high_watermark_threshold]). Default: 0. The driver uses per-tick deltas of this counter to emit crate::AnomalyKind::ReassemblerHighWatermark events without spamming on repeated above-threshold ticks.

fn high_watermark_threshold(&self) -> Option<(u64, u8)>

Some((cap, percent)) when a high-watermark threshold is configured; None otherwise. Default: None.

fn retransmits(&self) -> u64

Number of TCP segments classified as retransmits — re-deliveries of bytes the reassembler has already accounted for. Default 0.

fn on_duplicate(&mut self, _seq: u32, _payload: &[u8], _ts: Timestamp)

Hook called when a segment is classified as a retransmit rather than appended to the buffer. Default no-op. Custom reassemblers can use this to drive RTT estimators, retransmit-rate metrics, etc.

fn rexmit_inconsistencies(&self) -> u64

Running count of retransmits whose bytes differ from what the reassembler previously saw for the overlapping sequence range — the classic Ptacek-Newsham TCP overlap evasion IOC (cf. Zeek’s rexmit_inconsistency). Default 0 for implementations that don’t retain enough history to detect the divergence.

fn release(&mut self)

Stop reassembling and release whatever is buffered. After a release, Self::stop_reason should report ReassemblyStop::Memcap.

For callers driving a reassembler themselves. Since 0.25 crate::FlowDriver does not rely on it: when the tracker-wide memcap reclaims a side, the driver drops that side’s reassembler (keeping only its final counters), so the memory is freed whatever this method does. The default is a no-op.

fn current_bytes(&self) -> u64

Current live byte occupancy (ready bytes plus any out-of-order data held, including bookkeeping overhead). The tracker-wide memcap sums this across flows. Default 0.

fn out_of_window_segments(&self) -> u64

Segments dropped because they started too far from the expected sequence number (see crate::FlowTrackerConfig::reassembly_max_ahead) and were never corroborated — strays from an earlier connection on the same ports, injected segments. Default 0. New in 0.25.0.

fn ack_confirmed_gaps(&self) -> u64

Holes skipped early because the peer had acknowledged the missing bytes (capture loss). Included in Self::gaps. Default 0. New in 0.25.0.

fn origin_resets(&self) -> u64

Times the stream was re-anchored after corroborated out-of-window data (massive loss). Default 0. New in 0.25.0.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Reassembler for BufferedReassembler

impl Reassembler for NoopReassembler

impl Reassembler for SegmentBufferReassembler