Module message 

Draft-22 control message encoding and decoding.

The one difference from draft-21 is LOCATION_FILTER (0x21). Its value opens with a Location Filter Type that names which vi64 fields follow, and nothing on the wire states its length: the parameter is self-delimiting, like a Location, and a receiver that does not understand the type cannot find the end of it (Section 9.20.9, Table 6). See decode_location_filter.

Everything else is draft-21’s wire, and so draft-20’s:

• FETCH (0x16) has no Fetch Type. Track Namespace and Track Name are inline fields of FETCH, and the range travels in the LOCATION_FILTER parameter (Section 9.11, Figure 16).
• PUBLISH_STATE_NOTIFY (0x22) carries no Request ID (Section 9.10, Figure 15).
• FILL_PARAMETERS (0x23) is a length-prefixed parameter carrying a nested parameter block in its own scope (Section 9.20.15).
• INCLUDE_PROPERTIES (0x35) is a uint8 restricted to 0 and 1 (Section 9.20.21).
• EXPIRES is the only parameter whose definition names PUBLISH_OK.
• PUBLISH_DONE status 0x3 and REQUEST_ERROR code 0x32 are unassigned.

Every section, table and figure reference in this module is draft-22’s own.

Re-exports

pub use crate::error::CodecError;

pub use crate::error::MAX_GOAWAY_URI_LENGTH;

pub use crate::error::MAX_MESSAGE_LENGTH;

pub use crate::error::MAX_NAMESPACE_TUPLE_SIZE;

pub use crate::error::MAX_REASON_PHRASE_LENGTH;

Modules

location_filter_types

The Location Filter Type values draft-22 Section 9.20.9 assigns, named as Table 6 names them.

publish_done_codes

Numeric values for the PublishDone fields.

request_error_codes

REQUEST_ERROR error codes with dedicated meaning.

Structs

Fetch

FETCH (0x16), rebuilt in draft-20 (Section 9.11, Figure 16).

FetchOk

FETCH_OK (0x18). end_of_track is uint8.

GoAway

GOAWAY (0x10). Draft-22’s GOAWAY has no Request ID field, so the control-stream and request-stream forms are identical on the wire. Draft-18 is the one draft that carries the field, and only when the message is sent on the control stream.

Namespace

NamespaceDone

Publish

PublishDone

PUBLISH_DONE (0x0B). The wire layout is unchanged from draft-19; what draft-20 changed is the Stream Count sentinel, what the count includes, and the removal of status code 0x3.

PublishNamespace

PublishSkipped

PUBLISH_SKIPPED (0x0F). Drafts 17 and 18 name this codepoint PUBLISH_BLOCKED; the wire layout — track namespace suffix then track name — is the same on all four drafts that carry the message.

PublishStateNotify

PUBLISH_STATE_NOTIFY (0x22), new in draft-20 (Section 9.10, Figure 15).

Redirect

Optional Redirect structure carried in REQUEST_ERROR with code 0x34.

RequestError

REQUEST_ERROR (0x05). Adds an optional Redirect structure when error_code is REDIRECT (0x34).

RequestOk

REQUEST_OK (0x07). Used as a generic OK response and as the alias for PUBLISH_OK / REQUEST_UPDATE_OK / TRACK_STATUS_OK / SUBSCRIBE_NAMESPACE_OK / PUBLISH_NAMESPACE_OK.

RequestUpdate

Setup

Unified SETUP (0x2F00).

Subscribe

SubscribeNamespace

SUBSCRIBE_NAMESPACE (0x50). Subscribes to NAMESPACE / NAMESPACE_DONE advertisements for namespaces matching namespace_prefix. Only drafts 16 and 17 carry a subscribe_options varint here; on draft-22 a namespace subscription only produces NAMESPACE / NAMESPACE_DONE.

SubscribeOk

SUBSCRIBE_OK (0x04).

SubscribeTracks

SUBSCRIBE_TRACKS (0x51, new in draft-18). Subscribes to PUBLISH messages for tracks whose namespace matches namespace_prefix. Carries the FORWARD parameter (Section 9.20.18), which on drafts 15 through 17 may appear on SUBSCRIBE_NAMESPACE instead.

TrackStatus

Enums

ControlMessage

MessageType

ParamEncoding 🔒

How a parameter value is encoded on the wire.

Constants

AUTHORIZATION_TOKEN 🔒

AUTHORIZATION TOKEN, Parameter Type 0x03.

FILL_PARAMETERS

The FILL_PARAMETERS parameter type, draft-22 Section 9.20.15.

FILL_PARAMETERS_ALLOWED 🔒

The parameter types draft-22 Section 9.20.15, Table 7 permits inside a FILL_PARAMETERS value, in ascending order.

IMMUTABLE_PROPERTIES 🔒

Immutable Properties, Property Type 0xB.

KNOWN_SETUP_OPTIONS 🔒

The Setup Option types this draft defines.

LOCATION_FILTER

The LOCATION_FILTER parameter type, draft-22 Section 9.20.9.

REPEATABLE_SETUP_OPTION 🔒

The one Setup Option whose definition allows more than one instance.

Functions

add_delta 🔒

Add a delta to the previous delta-encoded key.

check_authorization_tokens 🔒

Hold every AUTHORIZATION TOKEN parameter to the Token structure it names.

check_discriminators 🔒

Refuse a message whose discriminator disagrees with the fields beside it.

check_full_track_name 🔒

Hold a namespace-plus-name pair to the Full Track Name cap.

check_location_filter_fields 🔒

Hold a decoded LOCATION_FILTER to the one arithmetic rule draft-22 states about it.

check_location_filters 🔒

Hold every LOCATION_FILTER and FILL_PARAMETERS parameter to the structure its own type names.

check_parameter_scope 🔒

Refuse a message carrying a Message Parameter its own definition does not place there.

check_track_property_values 🔒

Refuse a Track Property whose value falls outside the range its type allows, wherever in the list it is carried.

decode_fill_parameters

Decode the nested parameter block a FILL_PARAMETERS value carries.

decode_kvp_delta 🔒

Decode delta-encoded KVPs with even/odd convention (for setup options and track properties). Read until buffer is exhausted.

decode_location_filter

Decode a draft-22 LOCATION_FILTER value into its Location Filter Type and the fields that type names.

decode_parameter_value 🔒

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

decode_parameters 🔒

Decode a count-prefixed list of parameters with delta-encoded types.

decode_setup_options 🔒

Decode the Setup Options of a SETUP message.

decode_track_properties 🔒

Decode the Track Properties that fill the tail of a control message.

encode_kvp_delta 🔒

Encode delta-encoded KVPs with even/odd convention.

encode_parameters 🔒

Encode a count-prefixed list of parameters with delta-encoded types.

encode_setup_options 🔒

Encode the Setup Options of a SETUP message.

encode_track_properties 🔒

Encode a control message’s Track Properties.

is_location_value 🔒

Whether bytes is exactly the wire form of a Location — two consecutive varints and nothing after them.

is_track_namespace_value 🔒

Whether bytes is exactly the wire form of a Track Namespace, with nothing after it. The same reasoning as is_location_value: the value goes out verbatim, so it has to be something this draft can read back.

location_filter_field_count

How many vi64 fields follow a Location Filter Type, or None for a type draft-22 does not assign.

param_encoding 🔒

parameter_in_scope

Whether draft-22 lets Message Parameter key appear in message.

parameter_may_repeat 🔒

Whether draft-22 lets a message carry parameter type key more than once.

read_location_filter 🔒

Read one LOCATION_FILTER value off buf: the Location Filter Type, then exactly the fields that type names.

track_property_value_in_range 🔒

Whether value is inside the range draft-22 allows for a Track Property type that restricts one.

uint8_value_in_range 🔒

Whether value is inside the range draft-22 allows for a uint8-valued parameter.

write_location_filter 🔒

Write a LOCATION_FILTER value in its minimal encoding: the type, then the fields, each the shortest vi64 that holds it.