An internal net_flow sequence number identifying a piece of data. More...

#include <seq_num.hpp>

Collaboration diagram for flow::net_flow::Sequence_number:

Classes
class	Generator
	An object of this type generates a series of initial sequence numbers (ISN) that are meant to be sufficiently secure to protect against ISN attacks and confusion among different connections between the same endpoints occurring in series. More...

Public Types
using	seq_num_t = uint64_t
	Raw sequence number type. More...

using	seq_num_delta_t = int64_t
	Integer type used to express differences (distances) between Sequence_numbers. More...

Public Member Functions
	Sequence_number ()
	Constructs sequence number that is zero (not a valid sequence number; less than all others). More...

	Sequence_number (const Sequence_number &source)
	Copy constructor. More...

Sequence_number &	operator= (const Sequence_number &source)
	Copy operator. More...

bool	valid () const
	Returns true if and only if `*this != Sequence_number()` (i.e., is non-zero). More...

seq_num_delta_t	operator- (const Sequence_number &rhs) const
	Returns the distance from `*this` to `rhs`. More...

Sequence_number	operator+ (seq_num_delta_t delta) const
	Returns new sequence number that is `*this` advanced (or reversed) by the given distance. More...

Sequence_number	operator- (seq_num_delta_t delta) const
	Equivalent to `operator+(-delta)`. More...

Sequence_number &	operator+= (seq_num_delta_t delta)
	Advances (or reverses) this sequence number by the given distance. More...

Sequence_number &	operator-= (seq_num_delta_t delta)
	Equivalent to: `operator+=(-delta)`. More...

bool	operator== (const Sequence_number &rhs) const
	Whether `*this` is the same sequence number as `rhs`. More...

bool	operator!= (const Sequence_number &rhs) const
	Return `!(*this == rhs)`. More...

bool	operator< (const Sequence_number &rhs) const
	Whether `*this` is less than `rhs`. More...

bool	operator> (const Sequence_number &rhs) const
	Return `rhs < *this`. More...

bool	operator<= (const Sequence_number &rhs) const
	Return `!(*this > rhs)`. More...

bool	operator>= (const Sequence_number &rhs) const
	Return `rhs <= *this`. More...

size_t	hash () const
	Hash value of this Sequence_number for `unordered_*<>`. More...

const seq_num_t &	raw_num_ref () const
	Provides the raw sequence number. More...

void	set_raw_num (seq_num_t num)
	Sets the raw sequence number. More...

void	set_metadata (char num_line_id=0, const Sequence_number &zero_point=Sequence_number(), seq_num_delta_t multiple_size=0)
	Updates the full set of metadata (used at least for convenient convention-based logging but not actual algorihtms) for this number. More...

Private Attributes
seq_num_t	m_num
	The raw sequence number. This is the only datum used in algorithms. The others are only for logging and similar. More...

char	m_num_line_id
	Identifies the owner number line; `char(0)` = unknown/none. See set_metadata(). More...

seq_num_t	m_zero_point_num
	Value for `m_num` such that the magnitude is zero. See set_metadata(). More...

seq_num_delta_t	m_multiple_size
	Expected size of a full contiguous "block" of these numbers; 0 = unknown/blocks not expected. See set_metadata(). More...

Friends
std::ostream &	operator<< (std::ostream &os, const Sequence_number &seq_num)
	Prints given sequence number to given `ostream`. More...

Related Functions
(Note that these are not member functions.)
size_t	hash_value (const Sequence_number &seq_num)
	Free function that returns `seq_num.hash()`; has to be a free function named `hash_value` for boost.hash to pick it up. More...

Detailed Description

An internal net_flow sequence number identifying a piece of data.

While it would not be hard to just deal with raw sequence numbers everywhere, it seemed prudent to wrap the raw number in a light-weight object in order to make the interface abstract and be able to change the implementation later. For example, we may change the size of the number and how wrapping works (and even whether there is wrapping), at which point we'd rather only change this class's internals as opposed to code all over the place. For example, operator+() may change from not worrying about wrapping to worrying about it (and similarly for operator-()).

The companion nested class Generator is used to generate the initial sequence number (ISN) for a connection.

What does one Sequence_number represent? A byte or a packet? This class is intentionally ignorant of this. It just deals with a number on the number line. The user of the class is responsible for such matters.

Metadata

Sequence numbers being used for a given purpose always have certain features to make them useful. The following is a (n arguably overfly formal and detailed) discussion of those features and how we support them via "metadata."

Each sequence number line has a "zero" point Z, which is a sequence number such that it is more useful to specify a given absolute sequence number as (S - Z) with the corresponding explicit sign. So S = Z is written as =0, S > Z (most typical) is +M, S < Z (typically invalid) is -M, where M means magnitude, with M > 0.
Sometimes, in particular when individual sequence numbers represent individual sequential bytes in non-stop traffic (i.e., where user has more bytes than bandwidth can pass at any time, so there are always more bytes), and when the traffic is packetized into blocks of size B, it is convenient to specify the magnitude M as a multiple of B. This can be written as xNR – or just xN when R = 0 – where N = M / B, R = M % B. If one chooses zero point Z just right (so that S = 0 represents the very first byte in the entire sequence), and there is so much traffic that there are no incomplete packets (i.e., of length < B) formed, then edge sequence numbers and packet (and multi-packet) ranges become extremely simple, small, convenient.
Consider Flow DATA/ACK sequence numbers in particular. The ISN is the value Si chosen for SYN message; therefore the very first byte has absolute number (Si + 1). So let's set Z = (Si + 1). If only full packets are ever sent (which would be true if the Send buffer is always kept full by user, i.e., pipe < user data supply, quite typical in test applications), then every single packet will have sequence number range [+xN, +x(N + 1)) (where N >= 0); and every single contiguous-packet range of I = 1 or more packets will thus have form [+xN, +x(N + I)). Of course, B = max-block-size.
- If one were to use absolute numbers instead, they would be incredibly far from zero and also multiples of many bytes (often that number, B, being something annoying like 8192 or even some odd number). That's a far cry from literally 0, 1, 2, ... (with remainder kicking in, if an incomplete packet of DATA is generated for some reason).
- CAUTION! It's tempting – for this particular application (or in TCP sequence numbers, as well) – to set Z = ISN. However, the ISN, by convention, equals 1 less than the first actual DATA byte's sequence number. Always remember to set Z = ISN + 1 – even inside the ISN itself!
Every sequence number line has some qualitative purpose; e.g., "Remote DATA-received sequence numbers" or "Local ACK-received sequence numbers." This can be identified by a single letter prefix places in front of a number on the line. E.g., a full number might look like: L-x23%1, which means S = Z - (23 x B + 1). The prefix is called "number line ID."
- Note that Z and B themselves are hidden. If computing S is ever necessary, one might have to hunt for it (or Z, B) in prior logs. This is a cost that would be paid for the conciseness of L+x2 (for example) instead of 1285561384998534.

Sequence_number has optional support for the above conventions. While m_num stores the basic absolute value S, we also store the following, called metadata:

Zero point, Z (m_zero_point_num).
- Z = 0 = default, is allowed.
  - However, by convention sign will be omitted from ostream-serialization – since raw number is unsigned, and no non-zero numbers less than 0 exist.
  - Recall, also, that S = 0 itself is reserved/illegal by convention.
Multiple size, B (m_multiple_size)
- 0 = default, "none chosen".
  - ostream-serialization will avoid mentioning multiples/remainders.
Number line ID (m_num_line_id).
- char(0) = default, "none chosen".
  - ostream-serialization will simply feature no prefix.

Use set_metadata() to set the full set of metadata. For maximum effectiveness, consider these tips – especially vis-a-vis DATA/ACK-pertinent sequence numbers.

Consider not calling set_metadata() on an incoming packet's various sequence number members until it has been logged (if appropriate) once. Thus the raw number is available if necessary (hopefully never).
Remember that, by Flow-protocol (and, arguably, TCP) convention, Z = ISN + 1. Z =/= ISN. See above for details.
- Even for the Sequence_number storing the ISN; actually, especially that one (see below re. copying)!
Importantly, every copy (operator=(), copy constructor), including many implicit invocations thereof (operator+(), associative storage, etc.), will always copy the metadata too. Be sure to rely on this strongly! If you set an ISN with its Z = ISN + 1 and B = socket's max-block-size; and then all other Sequence_number objects are copies (direct or otherwise) thereof, then they should have the proper metadata and will be beautifully logged as a result. So just set the induction base and let the machinery work.
Metadata are not the actual data (m_num = actual data) and absolutely do not participate in any comparison, arithmetic, or hash operations (which means they're also 100% ignored in associative lookups). So algorithms will work even if there's some bug with metadata.

Thread safety

Equally thread-safe as built-in types (not safe to read/write or write/write one object simultaneously).

Implementation notes

Generator and Sequence_number work based on the same assumptions (like the structure of the sequence number space), and thus their implementations may be related. So if one is changed the other may also need to be changed (internally).

Definition at line 125 of file seq_num.hpp.

Member Typedef Documentation

◆ seq_num_delta_t

using flow::net_flow::Sequence_number::seq_num_delta_t = int64_t

Integer type used to express differences (distances) between Sequence_numbers.

Note: This type can overflow for extremely large sequence number differences (those spanning over half of the range). This should not usually be a concern in practice.

Todo:: Allowing overflow by using this definition of seq_num_delta_t is somewhat unlike the rest of the implementation of Sequence_number which avoids overflow like the plague. Should we do something like use double or a big-integer type from boost.multiprecision?

Definition at line 150 of file seq_num.hpp.

◆ seq_num_t

using flow::net_flow::Sequence_number::seq_num_t = uint64_t

Raw sequence number type.

64 bits used because sequence number wrap-around would take many centuries at high network speeds to occur if the initial sequence number is picked to be sufficiently small. See also Generator::S_MAX_INIT_SEQ_NUM.

Definition at line 138 of file seq_num.hpp.

Constructor & Destructor Documentation

◆ Sequence_number() [1/2]

flow::net_flow::Sequence_number::Sequence_number ( )

explicit

Constructs sequence number that is zero (not a valid sequence number; less than all others).

Definition at line 96 of file seq_num.cpp.

Referenced by operator+().

Here is the caller graph for this function:

◆ Sequence_number() [2/2]

flow::net_flow::Sequence_number::Sequence_number ( const Sequence_number & source )

default

Copy constructor.

Identical to calling: operator=(source);.

Implementation detail: Default implementation used. This is basically here for documentation purposes.

Parameters

source Source object.

Member Function Documentation

◆ hash()

size_t flow::net_flow::Sequence_number::hash ( ) const

Hash value of this Sequence_number for unordered_*<>.

Returns: Ditto.

Definition at line 252 of file seq_num.cpp.

References hash_value(), flow::net_flow::hash_value(), and m_num.

Referenced by hash_value().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator!=()

bool flow::net_flow::Sequence_number::operator!= ( const Sequence_number & rhs ) const

Return !(*this == rhs).

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 144 of file seq_num.cpp.

◆ operator+()

Sequence_number flow::net_flow::Sequence_number::operator+ ( seq_num_delta_t delta ) const

Returns new sequence number that is *this advanced (or reversed) by the given distance.

Parameters

delta How much to advance (or reverse, if negative) the result.

Returns: See above.

Definition at line 129 of file seq_num.cpp.

References Sequence_number().

Referenced by operator-().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator+=()

Sequence_number & flow::net_flow::Sequence_number::operator+= ( seq_num_delta_t delta )

Advances (or reverses) this sequence number by the given distance.

Parameters

delta How much to advance (or reverse, if negative) *this.

Returns: *this.

Definition at line 118 of file seq_num.cpp.

References m_num.

Referenced by operator-=().

Here is the caller graph for this function:

◆ operator-() [1/2]

Sequence_number::seq_num_delta_t flow::net_flow::Sequence_number::operator- ( const Sequence_number & rhs ) const

Returns the distance from *this to rhs.

This may be negative, meaning rhs > *this.

Note: This will overflow if the difference is extremely large (over half of the sequence number range). This should not usually be a concern in practice... but see to-do on seq_num_delta_t.

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 111 of file seq_num.cpp.

References m_num.

◆ operator-() [2/2]

Sequence_number flow::net_flow::Sequence_number::operator- ( seq_num_delta_t delta ) const

Equivalent to operator+(-delta).

Parameters

delta How much to reverse (or advance, if negative) the result.

Returns: See above.

Definition at line 134 of file seq_num.cpp.

References operator+().

Here is the call graph for this function:

◆ operator-=()

Sequence_number & flow::net_flow::Sequence_number::operator-= ( seq_num_delta_t delta )

Equivalent to: operator+=(-delta).

Parameters

delta How much to reverse (or advance, if negative) *this.

Returns: *this.

Definition at line 124 of file seq_num.cpp.

References operator+=().

Here is the call graph for this function:

◆ operator<()

bool flow::net_flow::Sequence_number::operator< ( const Sequence_number & rhs ) const

Whether *this is less than rhs.

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 149 of file seq_num.cpp.

References m_num.

◆ operator<=()

bool flow::net_flow::Sequence_number::operator<= ( const Sequence_number & rhs ) const

Return !(*this > rhs).

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 164 of file seq_num.cpp.

◆ operator=()

Sequence_number & flow::net_flow::Sequence_number::operator= ( const Sequence_number & source )

default

Copy operator.

Copies both the data (the essential absolute value) and all the metadata.

Implementation detail: Default implementation used. This is basically here for documentation purposes.

Parameters

source Source object. *this is allowed but pointless.

Returns: *this.

◆ operator==()

bool flow::net_flow::Sequence_number::operator== ( const Sequence_number & rhs ) const

Whether *this is the same sequence number as rhs.

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 139 of file seq_num.cpp.

References m_num.

◆ operator>()

bool flow::net_flow::Sequence_number::operator> ( const Sequence_number & rhs ) const

Return rhs < *this.

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 154 of file seq_num.cpp.

◆ operator>=()

bool flow::net_flow::Sequence_number::operator>= ( const Sequence_number & rhs ) const

Return rhs <= *this.

Parameters

rhs	Object to compare.

Returns: See above.

Definition at line 159 of file seq_num.cpp.

◆ raw_num_ref()

const Sequence_number::seq_num_t & flow::net_flow::Sequence_number::raw_num_ref ( ) const

Provides the raw sequence number.

This method is primarily intended for serialization.

Returns: The raw sequence number.

Definition at line 258 of file seq_num.cpp.

References m_num.

◆ set_metadata()

void flow::net_flow::Sequence_number::set_metadata	(	char	num_line_id = `0`,
		const Sequence_number &	zero_point = `Sequence_number()`,
		seq_num_delta_t	multiple_size = `0`
	)

Updates the full set of metadata (used at least for convenient convention-based logging but not actual algorihtms) for this number.

See class Sequence_number doc header for important tips and even more detail before using this surprisingly powerful utility. It's all quite intuitive, but there are various nuances one might not expect.

Note: Metadata propagate via copy (copy construction, operator=(), and many implicit calls thereto), so it is important to call this method with final values before the propagating begins. See class Sequence_number doc header for discussion.

Parameters

num_line_id	A 1-character descriptive identifier (conventionally, an upper-case letter such as L for Local) for the number line of which this Sequence_number is a part. `char(0)` means "none" or "unknown" and is default at construction.
zero_point	The Sequence_number `Z` such that the relative sequence number is expressed depending on `this->m_num` versus `Z.m_num`; its sign is +, -, or = if the latter is less than, greater than, or equal to the former, respectively; its magnitude is the absolute value of their difference. 0 is legal, but see class Sequence_number for nuance(s). 0 is default at construction.
multiple_size	The block size, or multiple size, which is a positive value given when data are generally expected to be segmented in whole multiples of this many contiguous Sequence_numbers. 0 means "data are not expected to be such multiples" or "unknown"; this is the default at construction.

Definition at line 268 of file seq_num.cpp.

References m_multiple_size, m_num, m_num_line_id, and m_zero_point_num.

Referenced by flow::net_flow::Node::connect_worker(), flow::net_flow::Syn_packet::deserialize_type_specific_data_from_raw_data_packet(), flow::net_flow::Syn_ack_packet::deserialize_type_specific_data_from_raw_data_packet(), flow::net_flow::Data_packet::deserialize_type_specific_data_from_raw_data_packet(), flow::net_flow::Ack_packet::deserialize_type_specific_data_from_raw_data_packet(), and flow::net_flow::Node::handle_syn_to_listening_server().

Here is the caller graph for this function:

◆ set_raw_num()

void flow::net_flow::Sequence_number::set_raw_num ( seq_num_t num )

Sets the raw sequence number.

This method is primarily intended for deserialization.

Parameters

num	The raw sequence number.

Definition at line 263 of file seq_num.cpp.

References m_num.

Referenced by flow::net_flow::Syn_packet::deserialize_type_specific_data_from_raw_data_packet(), flow::net_flow::Syn_ack_packet::deserialize_type_specific_data_from_raw_data_packet(), flow::net_flow::Data_packet::deserialize_type_specific_data_from_raw_data_packet(), and flow::net_flow::Ack_packet::deserialize_type_specific_data_from_raw_data_packet().

Here is the caller graph for this function:

◆ valid()

bool flow::net_flow::Sequence_number::valid ( ) const

Returns true if and only if *this != Sequence_number() (i.e., is non-zero).

Returns: Ditto.

Definition at line 106 of file seq_num.cpp.

References m_num.

Friends And Related Function Documentation

◆ hash_value()

size_t hash_value ( const Sequence_number & seq_num )

Parameters

seq_num Object to hash.

Returns: seq_num.hash().

Definition at line 275 of file seq_num.cpp.

References hash().

Referenced by hash().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Sequence_number &	seq_num
	)

friend

Prints given sequence number to given ostream.

set_metadata()'s effects are felt here; see Sequence_number class doc header for details.

Parameters

os	Stream to which to print.
seq_num	Object to serialize.

Returns: os.

Definition at line 169 of file seq_num.cpp.

Member Data Documentation

◆ m_multiple_size

seq_num_delta_t flow::net_flow::Sequence_number::m_multiple_size

private

Expected size of a full contiguous "block" of these numbers; 0 = unknown/blocks not expected. See set_metadata().

Definition at line 356 of file seq_num.hpp.

Referenced by set_metadata().

◆ m_num

seq_num_t flow::net_flow::Sequence_number::m_num

private

The raw sequence number. This is the only datum used in algorithms. The others are only for logging and similar.

Definition at line 347 of file seq_num.hpp.

Referenced by hash(), operator+=(), operator-(), operator<(), operator==(), raw_num_ref(), set_metadata(), set_raw_num(), and valid().

◆ m_num_line_id

char flow::net_flow::Sequence_number::m_num_line_id

private

Identifies the owner number line; char(0) = unknown/none. See set_metadata().

Definition at line 350 of file seq_num.hpp.

Referenced by set_metadata().

◆ m_zero_point_num

seq_num_t flow::net_flow::Sequence_number::m_zero_point_num

private

Value for m_num such that the magnitude is zero. See set_metadata().

Definition at line 353 of file seq_num.hpp.

Referenced by set_metadata().

The documentation for this class was generated from the following files:

net_flow/detail/seq_num.hpp
net_flow/detail/net_flow_fwd.hpp
net_flow/detail/seq_num.cpp

Classes

Public Types

Public Member Functions

Private Attributes

Friends

Related Functions

Detailed Description

Metadata

Thread safety

Implementation notes

Member Typedef Documentation

◆ seq_num_delta_t

◆ seq_num_t

Constructor & Destructor Documentation

◆ Sequence_number() [1/2]

◆ Sequence_number() [2/2]

Member Function Documentation

◆ hash()

◆ operator!=()

◆ operator+()

◆ operator+=()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator-=()

◆ operator<()

◆ operator<=()

◆ operator=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ raw_num_ref()

◆ set_metadata()

◆ set_raw_num()

◆ valid()

Friends And Related Function Documentation

◆ hash_value()

◆ operator<<

Member Data Documentation

◆ m_multiple_size

◆ m_num

◆ m_num_line_id

◆ m_zero_point_num