SUBSCRIBE

A subscription causes the publisher to send newly published objects for a track. A subscriber MUST NOT make multiple active subscriptions for a track within a single session and publishers SHOULD treat this as a protocol violation.

Filter Types

The subscriber specifies a filter on the subscription to allow the publisher to identify which objects need to be delivered.

All filters have a Start Location and an optional End Group. Only objects published or received via a subscription having Locations greater than or equal to Start and strictly less than or equal to the End Group (when present) pass the filter.

The Largest Object is defined to be the object with the largest Location (Section 1.4.1) in the track from the perspective of the endpoint processing the SUBSCRIBE message. Largest Object updates when the first byte of an Object with a larger Location than the previous value is published or received through a subscription.

There are 4 types of filters:

Largest Object (0x2): The filter Start Location is {Largest Object.Group, Largest Object.Object + 1} and Largest Object is communicated in SUBSCRIBE_OK. If no content has been delivered yet, the filter Start Location is {0, 0}. There is no End Group - the subscription is open ended. Note that due to network reordering or prioritization, relays can receive Objects with Locations smaller than Largest Object after the SUBSCRIBE is processed, but these Objects do not pass the Largest Object filter.

Next Group Start (0x1): The filter Start Location is {Largest Object.Group + 1, 0} and Largest Object is communicated in SUBSCRIBE_OK. If no content has been delivered yet, the filter Start Location is {0, 0}. There is no End Group - the subscription is open ended. For scenarios where the subscriber intends to start from more than one group in the future, it can use an AbsoluteStart filter instead.

AbsoluteStart (0x3): The filter Start Location is specified explicitly in the SUBSCRIBE message. The Start specified in the SUBSCRIBE message MAY be less than the Largest Object observed at the publisher. There is no End Group - the subscription is open ended. To receive all Objects that are published or are received after this subscription is processed, a subscriber can use an AbsoluteStart filter with Start = {0, 0}.

AbsoluteRange (0x4): The filer Start Location and End Group are specified explicitly in the SUBSCRIBE message. The Start specified in the SUBSCRIBE message MAY be less than the Largest Object observed at the publisher. If the specified End Group is the same group specified in Start, the remainder of that Group passes the filter. End Group MUST specify the same or a larger Group than specified in Start.

An endpoint that receives a filter type other than the above MUST be close the session with PROTOCOL_VIOLATION.

Subscribe only delivers newly published or received Objects. Objects from the past are retrieved using FETCH (Section 9.16).

A Subscription can also request a publisher to not forward Objects for a given track by setting the Forward field to 0. This allows the publisher or relay to prepare to serve the subscription in advance, reducing the time to receive objects in the future. Relays SHOULD set the Forward flag to 1 if a new subscription needs to be sent upstream, regardless of the value of the Forward field from the downstream subscription. Subscriptions that are not forwarded consume resources from the publisher, so a publisher might deprioritize, reject, or close those subscriptions to ensure other subscriptions can be delivered. Control messages, such as SUBCRIBE_DONE (Section 9.12) are still sent.

The format of SUBSCRIBE is as follows:

SUBSCRIBE Message {
  Type (i) = 0x3,
  Length (16),
  Request ID (i),
  Track Namespace (tuple),
  Track Name Length (i),
  Track Name (..),
  Subscriber Priority (8),
  Group Order (8),
  Forward (8),
  Filter Type (i),
  [Start Location (Location)],
  [End Group (i)],
  Number of Parameters (i),
  Parameters (..) ...
}

• Request ID: See Section 9.1.

• Track Namespace: Identifies the namespace of the track as defined in (Section 2.4.1).

• Track Name: Identifies the track name as defined in (Section 2.4.1).

• Subscriber Priority: Specifies the priority of a subscription relative to other subscriptions in the same session. Lower numbers get higher priority. See Section 7.

• Group Order: Allows the subscriber to request Objects be delivered in Ascending (0x1) or Descending (0x2) order by group. See Section 7. A value of 0x0 indicates the original publisher's Group Order SHOULD be used. Values larger than 0x2 are a protocol error.

• Forward: If 1, Objects matching the subscription are forwarded to the subscriber. If 0, Objects are not forwarded to the subscriber. Any other value is a protocol error and MUST terminate the session with a PROTOCOL_VIOLATION (Section 3.4).

• Filter Type: Identifies the type of filter, which also indicates whether the Start and End Group fields will be present.

• Start Location: The starting location for this subscriptions. Only present for "AbsoluteStart" and "AbsoluteRange" filter types.

• End Group: The end Group ID. Only present for the "AbsoluteRange" filter type.

• Parameters: The parameters are defined in Section 9.2.1.

On successful subscription, the publisher MUST reply with a SUBSCRIBE_OK, allowing the subscriber to determine the start group/object when not explicitly specified and the publisher SHOULD start delivering objects.

If a publisher cannot satisfy the requested start or end or if the end has already been published it SHOULD send a SUBSCRIBE_ERROR with code INVALID_RANGE. A publisher MUST NOT send objects from outside the requested start and end.