Reassembly Base Class¶

pcapkit.foundation.reassembly.reassembly contains Reassembly, the abstract base class of a custom reassembly class, and ReassemblyBase, which it and the built-in IP, TCP and DTLS reassembly classes derive from. The algorithms follow RFC 791 and RFC 815.

class pcapkit.foundation.reassembly.reassembly.Reassembly[_PT: Info, _DT: Info, _IT: tuple, _BT: Info](*, strict=True, store=True, timeout=None)[source]¶

Bases: ReassemblyBase[_PT, _DT, _IT, _BT], Generic[_PT, _DT, _IT, _BT]

Base reassembly class.

Example

Registration is opt-in. Pass keyword argument protocol at class definition to register the reassembly under that protocol name:

class MyProtocol(Reassembly, protocol='my_protocol'):
    ...

Omit it and the subclass is not registered, which is how a class that is not meant to be selectable by name declines:

class MyMixin(Reassembly):  # not registered
    ...

Such a class can still be registered later, on demand:

Extractor.register_reassembly('my_mixin', MyMixin)

Parameters:

strict (bool) – if True, report a datagram that is not completely reassembled as the tuple of its received runs; otherwise as one contiguous payload, its holes zero-filled – or, for IP while the total length is unknown, only the prefix up to the first hole
store (bool) – if store reassembled datagram in memory, i.e., self._dtgram (if not, datagram will be discarded after callback)
timeout (float | None) – reassembly timeout in seconds, on the capture’s own clock; None selects the protocol’s __timeout__ default

Changed in version 1.3.0: name and protocol are read from __protocol_name__ and __protocol_type__, where they were abstract properties each reassembly implemented, and the built-in names are short: 'IPv4' rather than 'Internet Protocol version 4'. A subclass registers itself with Extractor at class definition.

Changed in version 1.5.0: Registration is opt-in, under the protocol class keyword; 1.4.x registered every subclass, under its name when the keyword was omitted (#514). The timeout argument is added: a buffer older than it on the capture’s clock is abandoned.

See also

For customisation and extension, see Customisation & Extensions.

property name: str¶: Protocol name of current reassembly class.

Note

Also a class variable, set by __protocol_name__.

property protocol: Type[pcapkit.protocols.protocol.ProtocolBase]¶: Protocol of current reassembly class.

Note

Also a class variable, set by __protocol_type__.

property registry: dict[str, ModuleDescriptor[ReassemblyBase] | Type[ReassemblyBase]]¶: Mapping of protocol names to reassembly classes.

Note

A class variable only, defined on ReassemblyMeta. It is not per-class: it reads __reassembly__, the one table every reassembly registration lands in.

property count: int¶: Total number of reassembled packets.

property datagram: tuple[_DT, ...]¶

Reassembled datagram.

Raises:: UnsupportedCall – If self._flag_d is set to False.

property timeout: float¶

Reassembly timeout, in seconds, of the current reassembly object.

A buffer whose first-arriving fragment is older than this many seconds on the capture’s own clock is abandoned rather than held for the life of the object – see expire(). math.inf disables expiry.

abstractmethod reassembly(info)¶

Reassembly procedure.

Parameters:: info (_PT) – info record of packets to be reassembled

abstractmethod submit(buf, **kwargs)¶

Submit reassembled payload.

Parameters:

buf (_BT) – buffer dict of reassembled packets
**kwargs (Any) – arbitrary keyword arguments; implementations accept timeout, set when the buffer is being submitted because expire() abandoned it rather than because it completed or the capture ended

Return type:

list[_DT]

expire(timestamp)¶

Abandon every buffer whose reassembly timeout has elapsed.

Parameters:: timestamp (float) – Current time on the capture’s clock, in seconds since the Unix epoch – i.e. the capture timestamp of the packet just handed to reassembly().
Return type:: list[_DT]
Returns:: Datagrams of the buffers abandoned, reported with Completion.TIMEOUT. Empty when nothing expired, which is the overwhelmingly common case.

A buffer expires when more than timeout seconds separate timestamp from the capture timestamp of its first-arriving fragment, which is the deadline RFC 8200 Section 4.5 states (“within 60 seconds of the reception of the first-arriving fragment”) and which RFC 815 suggests implementing by reading “the clock when each first fragment arrives”. A later fragment therefore does not extend the deadline.

Note

The clock only advances when this reassembly object is fed, since a packet handed to it is the only evidence an offline parser has that capture time has moved on. For TCP that is every segment, for IPv4 every frame whose DF flag is clear, and for IPv6 only the fragments, so an IPv6 buffer that stalls and is followed by no further IPv6 fragment is reported as Completion.PARTIAL at the end of the capture. That is the honest answer: the capture never shows that the deadline passed. A caller with an outside source of time may call this method itself to advance the clock.

fetch()¶

Fetch datagram.

Return type:: tuple[_DT, ...]
Returns:: Tuple of reassembled datagrams.

Fetch reassembled datagrams from self._dtgram and returns a tuple of such datagrams.

If no cache found, the method will call self.submit to forcedly obtain newly reassembled payload. Otherwise, the already calculated self._dtgram will be returned.

index(pkt_num)¶

Return datagram index.

Parameters:: pkt_num (int) – index of packet
Return type:: int | None
Returns:: Reassembled datagram index which was from No. pkt_num packet; if not found, returns None.

run(packets)¶

Run automatically.

Parameters:: packets (list[_PT]) – list of packet dicts to be reassembled

classmethod register(callback, *, index=None)¶

Parameters:

callback (Callable[[List[_DT]], None]) – callback function, which will be called when reassembled datagram is obtained, with the list of reassembled datagrams as its only argument
index (int | None) – index to be inserted in the callback list; by default, the callback will be appended to the end of the list

Return type:

None

__callback_fn__: list[Callable[[List[_DT]], None]]¶: List of callback functions upon reassembled datagram.

_flag_s: bool¶

Strict mode flag. If set to True, a datagram not completely reassembled is reported as the tuple of its received runs; otherwise, as one contiguous payload, its holes zero-filled – or, for IP while the total length is unknown, only the prefix up to the first hole.

Type:: bool

_flag_d: bool¶

Store mode flag. If set to True, all reassembled datagram will be stored in memory, i.e., self._dtgram; otherwise, datagram will be discarded after callback.

Type:: bool

_flag_n: bool¶

New datagram flag. If set to True, the self._dtgram will be repopulated.

Type:: bool

_timeout: float¶

Reassembly timeout in seconds, on the capture’s clock. math.inf disables expiry.

Type:: float

_buffer: dict[_IT, _BT]¶

Dict buffer field. This field is used to store reassembled packets in the form of {bufid: buffer}.

Type:: dict[_IT, _BT]

_dtgram: list[_DT]¶

List reassembled datagram. This list is used to store reassembled datagrams.

Type:: list[_DT]

__call__(packet)¶

Call packet reassembly.

Parameters:: packet (_PT) – packet dict to be reassembled (detailed format described in corresponding protocol)

classmethod __init_subclass__(protocol=None, *args, **kwargs)[source]¶

Initialise subclass.

This method is to be used for registering the reassembly class to Extractor class.

Parameters:

protocol (str | None) – Protocol name to register the subclass under, lowercased. None (the default) skips registration entirely.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Raises:

UnsupportedCall – If any unrecognised class keyword is given.

Return type:

None

Registration is opt-in: the subclass is registered if and only if protocol is given. This is what lets a subclass decline registration rather than having to inherit ReassemblyBase to avoid it, and it matches EnumSchema.__init_subclass__, which guards on its own code keyword the same way.

Note

__protocol_name__ is not an opt-in. It supplies the name the reassembly reports, which it does whether or not the class is registered; only the keyword decides registration.

Internal Definitions¶

class pcapkit.foundation.reassembly.reassembly.ReassemblyBase[_PT: Info, _DT: Info, _IT: tuple, _BT: Info](*, strict=True, store=True, timeout=None)[source]¶

Bases: ReduceAsProtocol2, Generic[_PT, _DT, _IT, _BT]

Base class for reassembly procedure.

Parameters:

strict (bool) – if True, report a datagram that is not completely reassembled as the tuple of its received runs; otherwise as one contiguous payload, its holes zero-filled – or, for IP while the total length is unknown, only the prefix up to the first hole
store (bool) – if store reassembled datagram in memory, i.e., self._dtgram (if not, datagram will be discarded after callback)
timeout (float | None) – reassembly timeout in seconds, measured on the capture’s clock; None selects the protocol’s own __timeout__ default

Note

This class is for internal use only. For customisation, please use Reassembly instead.

class pcapkit.foundation.reassembly.reassembly.ReassemblyMeta(name, bases, namespace, /, **kwargs)[source]¶

Bases: ABCMeta

Meta class to add dynamic support to Reassembly.

It provides Reassembly.name, Reassembly.protocol and Reassembly.registry as class properties, the first two read from __protocol_name__ and __protocol_type__ where a subclass sets them.

Type Variables¶

pcapkit.foundation.reassembly.reassembly._PT: pcapkit.corekit.infoclass.Info¶: Packet data structure.

pcapkit.foundation.reassembly.reassembly._DT: pcapkit.corekit.infoclass.Info¶: Datagram data structure.

pcapkit.foundation.reassembly.reassembly._IT: tuple¶: Buffer ID data structure.

pcapkit.foundation.reassembly.reassembly._BT: pcapkit.corekit.infoclass.Info¶: Buffer data structure.