The subscriber sends a SUBSCRIBE_NAMESPACE control message on a new
bidirectional stream to a publisher to request the current set of matching
published namespaces and/or Established subscriptions, as well as future
updates to the set.
SUBSCRIBE_NAMESPACE Message {
Type (vi64) = 0x11,
Length (16),
Request ID (vi64),
Required Request ID Delta (vi64),
Track Namespace Prefix (..),
Subscribe Options (vi64),
Number of Parameters (vi64),
Parameters (..) ...
}
-
Request ID: See Section 9.1.
-
Required Request ID Delta: See Section 9.2.
-
Track Namespace Prefix: A Track Namespace structure as described in Section 2.4.1 with between 0 and 32 Track Namespace Fields. This prefix is matched against track namespaces known to the publisher. For example, if the publisher is a relay that has received PUBLISH_NAMESPACE messages for namespaces ("example.com", "meeting=123", "participant=100") and ("example.com", "meeting=123", "participant=200"), a SUBSCRIBE_NAMESPACE for ("example.com", "meeting=123") would match both. If an endpoint receives a Track Namespace Prefix consisting of greater than than 32 Track Namespace Fields, it MUST close the session with a
PROTOCOL_VIOLATION. -
Subscribe Options: Allows subscribers to request PUBLISH (0x00), NAMESPACE (0x01), or both (0x02) for a given SUBSCRIBE_NAMESPACE request.
-
Parameters: The parameters are defined in Section 9.3.
The publisher will respond with REQUEST_OK or REQUEST_ERROR on the response half
of the stream. If the subscriber receives any frame other than a REQUEST_OK or a
REQUEST_ERROR as the first frame on the response half of the stream, then it MUST
close the session with a PROTOCOL_VIOLATION. If the SUBSCRIBE_NAMESPACE is
successful, the publisher will send matching NAMESPACE messages on the response
stream if they are requested. If it is an error, the stream will be immediately
closed via FIN. Also, any matching PUBLISH messages without an Established
Subscription will be established on new bidirectional streams. When there are
changes to the namespaces or subscriptions being published and the subscriber
is subscribed to them, the publisher sends the corresponding NAMESPACE,
NAMESPACE_DONE, or PUBLISH messages.
A subscriber cannot make overlapping namespace subscriptions on a single
session. Within a session, if a publisher receives a SUBSCRIBE_NAMESPACE with a
Track Namespace Prefix that shares a common prefix with an established namespace
subscription, it MUST respond with REQUEST_ERROR with error code
PREFIX_OVERLAP.
The publisher MUST ensure the subscriber is authorized to perform this namespace subscription.
SUBSCRIBE_NAMESPACE is not required for a publisher to send PUBLISH_NAMESPACE or PUBLISH messages to a subscriber. It is useful in applications or relays where subscribers are only interested in or authorized to access a subset of available namespaces and tracks.
If the FORWARD parameter (Section 9.3.10) is present in this message and equal to 0, PUBLISH messages resulting from this SUBSCRIBE_NAMESPACE will set the FORWARD parameter to 0. If the FORWARD parameter is equal to 1 or omitted from this message, PUBLISH messages resulting from this SUBSCRIBE_NAMESPACE will set the FORWARD parameter to 1, or indicate that value by omitting the parameter (see Section 5.1).
The publisher MUST NOT send NAMESPACE_DONE for a namespace suffix before the corresponding NAMESPACE. If a subscriber receives a NAMESPACE_DONE before the corresponding NAMESPACE, it MUST close the session with a 'PROTOCOL_VIOLATION'.
If the publisher is unable to send NAMESPACE or NAMESPACE_DONE messages in a timely manner because the SUBSCRIBE_NAMESPACE response stream is blocked by flow control, the publisher MAY reset the SUBSCRIBE_NAMESPACE response stream. When a subscriber receives a stream reset on a SUBSCRIBE_NAMESPACE response stream, it SHOULD treat this as though each active namespace received a NAMESPACE_DONE.