Subscriptions

All subscriptions begin in the Idle state. A subscription can be initiated and moved to the Pending state by either a publisher or a subscriber. A publisher initiates a subscription to a track by sending the PUBLISH message. The subscriber either accepts or rejects the subscription using PUBLISH_OK or REQUEST_ERROR. A subscriber initiates a subscription to a track by sending the SUBSCRIBE message. The publisher either accepts or rejects the subscription using SUBSCRIBE_OK or REQUEST_ERROR. Once either of these sequences is successful, the subscription moves to the Established state and can be updated by the subscriber using SUBSCRIBE_UPDATE. Either endpoint can terminate an Established subscription, moving it to the Terminated state. The subscriber terminates a subscription using UNSUBSCRIBE, the publisher terminates a subscription using PUBLISH_DONE.

This diagram shows the subscription state machine:

+--------+ | Idle | +--------+ | | SUBSCRIBE | | PUBLISH (subscriber)| | (publisher) V V +--------------+ +--------------+ | Pending | | Pending | +----| (Subscriber) | | (Publisher) |----+ | +--------------+ +--------------+ | | | | | REQUEST_ERROR | SUBSCRIBE_OK | | PUBLISH_OK | REQUEST_ERROR | (publisher)| | (subscriber) | | V V | | +-------------+ | | | Established | ------+ | | | | SUBSCRIBE_UPDATE | +-------------+ <-----+ | | | | | UNSUBSCRIBE | | PUBLISH_DONE | | (subscriber)| | (publisher) | | V V | | +-------------+ | +----------->| Terminated | <------------+ +-------------+

A publisher MUST send exactly one SUBSCRIBE_OK or REQUEST_ERROR in response to a SUBSCRIBE. A subscriber MUST send exactly one PUBLISH_OK or REQUEST_ERROR in response to a PUBLISH. The peer SHOULD close the session with a protocol error if it receives more than one.

A publisher MUST save the Largest Location communicated in PUBLISH or SUBSCRIBE_OK when establishing a subscription. This value can be used in a Joining FETCH (see Section 9.16.2) at any time while the subscription is active.

All Established subscriptions have a Forward State which is either 0 or 1. If the Forward State is 0, the publisher does not send objects for the subscription. If the Forward State is 1, the publisher sends objects. The initiator of the subscription sets the initial Forward State in either PUBLISH or SUBSCRIBE. The sender of PUBLISH_OK can update the Forward State based on its preference. Once the subscription is established, the subscriber can update the Forward State by sending SUBSCRIBE_UPDATE. Control messages, such as PUBLISH_DONE (Section 9.15) are still sent on subscriptions in Forward State 0.

Either endpoint can initiate a subscription to a track without exchanging any prior messages other than SETUP. Relays MUST NOT send any PUBLISH messages without knowing the client is interested in and authorized to receive the content. The communication of intent and authorization can be accomplished by the client sending SUBSCRIBE_NAMESPACE, or conveyed in other mechanisms out of band.

An endpoint MAY SUBSCRIBE to a Track it is publishing, though only Relays are required to handle such a SUBSCRIBE. Such self-subscriptions are identical to subscriptions initiated by other endpoints, and all published Objects will be forwarded back to the endpoint, subject to priority and congestion response rules.

A publisher SHOULD begin sending incomplete objects when available to avoid incurring additional latency.

Publishers MAY start sending Objects on PUBLISH-initiated subscriptions before receiving a PUBLISH_OK response to reduce latency. Doing so can consume unnecessary resources in cases where the Subscriber rejects the subscription with REQUEST_ERROR or sets Forward State=0 in PUBLISH_OK. It can also result in the Subscriber dropping Objects if its buffering limits are exceeded (see Section 10.3 and Section 10.4.2).

Subscription Filter {
  Filter Type (i),
  [Start Location (Location),]
  [End Group (i),]
}