Module fill 

Location filters and fill fetch streams, the two things draft-20 asks a subscriber to build that no earlier draft has.

Draft-20 moved the range of a FETCH out of the message and into the LOCATION_FILTER message parameter (Section 5.1.2), and added FILL_PARAMETERS (Section 10.2.15) — a parameter whose presence on a SUBSCRIBE or a REQUEST_UPDATE asks the publisher to open a fill fetch stream, and whose value is a nested parameter block that overrides the subscription’s own settings for that fill alone.

Both are parameter values a caller has to construct byte by byte, which is why they are here rather than left to the caller: the two encodings are the places draft-20 is least explicit, and getting either wrong desynchronises the whole parameter list rather than producing a recognisable error.

What this module decides, and where the draft is silent

• A LOCATION_FILTER’s shape comes from how many vi64 fields its value holds, not from the byte length. See LocationFilter.
• A FILL_PARAMETERS value begins with a Number of Parameters count, and its Type Delta chain restarts at 0. See FillParameters.
• A fill fetch stream with no GROUP_ORDER anywhere is read Ascending. See group_order.

Every value this module builds is handed to the codec’s own decoder before it is returned, so a disagreement between the two is an error here rather than a frame on the wire.

Ranges are inclusive

Draft-19’s fetch end was “the last Object, plus 1; or 0 to indicate the entire Group”. Draft-20 Sections 5.1.2 and 10.13 both say the Location filter “specifies an inclusive range of Locations”, and both draft-19 conventions are gone. Nothing in this module adds or subtracts one from an end location, and a caller porting draft-19 arithmetic forward fetches one object too many.

Structs

FillParameters

A draft-20 FILL_PARAMETERS (Parameter Type 0x23), Section 10.2.15.

LocationFilter

A draft-20 LOCATION_FILTER (Parameter Type 0x21), Section 5.1.2.

Enums

FillError

Errors from building a LOCATION_FILTER or a FILL_PARAMETERS value.

Constants

FILL_PARAMETERS_ALLOWED 🔒

The parameter types draft-20 Section 10.2.15, Table 6 permits inside a FILL_PARAMETERS value, in ascending order.

GROUP_ORDER

GROUP_ORDER, Parameter Type 0x22 (Section 10.2.8).

GROUP_ORDER_ASCENDING 🔒

The GROUP_ORDER value Section 10.2.8 assigns to Ascending.

GROUP_ORDER_DESCENDING 🔒

The GROUP_ORDER value Section 10.2.8 assigns to Descending.

Functions

check_end_group 🔒

encode_group_order 🔒

The Section 10.2.8 value for a Group Order.

encode_nested_value 🔒

Write one nested parameter’s value in the shape its type names.

group_order

The Group Order a fill fetch stream’s Objects arrive in, given the parameters of the SUBSCRIBE (or REQUEST_UPDATE) that asked for the fill.

insert_parameter

Put parameter into parameters at the position ascending type order requires.

is_length_prefixed 🔒

Whether a Table 6 parameter’s value carries its own length prefix.

is_uint8 🔒

Whether a Table 6 parameter’s value is a single raw byte rather than a varint or a length-prefixed block.

may_repeat 🔒

The five Range Filters, of which four may be nested. Only these may repeat.

read_group_order 🔒

The GROUP_ORDER in one parameter list, or None if it holds none.