Message flows and endpoint state management (Was: ANNOUNCE) (#643)

Fixes #556
Fixes #557 
Fixes #583 
Fixes #584 

Also eliminates text from the relay section that is redundant, because
it applies to endpoints whether or not they are relays.

Author: ianswett

draft-ietf-moq-transport.md

@@ -626,6 +626,114 @@ and announcements. The client can choose to delay closing the session if it
 expects more OBJECTs to be delivered. The server closes the session with a
 'GOAWAY Timeout' if the client doesn't close the session quickly enough.
 
+# Track Discovery and Retrieval (#track-discovery}
+
+Discovery of MoQT servers is always done out-of-band. Namespace discovery can be
+done in the context of an established MoQT session.
+
+Given sufficient out of band information, it is valid for a subscriber
+to send a SUBSCRIBE or FETCH message to a publisher (including a relay) without
+any previous MoQT messages besides SETUP. However, SUBSCRIBE_ANNOUNCES and
+ANNOUNCE messages provide an in-band means of discovery of subscribers and
+publishers for a namespace.
+
+The syntax of these messages is described in {{message}}.
+
+## SUBSCRIBE_ANNOUNCES
+
+If the subscriber is aware of a namespace of interest, it can send
+SUBSCRIBE_ANNOUNCES to publishers/relays it has established a session with. The
+recipient of this message will send any relevant ANNOUNCE messages for that
+namespace, or subset of that namespace.
+
+A publisher MUST send exactly one SUBSCRIBE_ANNOUNCES_OK or
+SUBSCRIBE_ANNOUNCES_ERROR in response to a SUBSCRIBE_ANNOUNCES. The subscriber
+SHOULD close the session with a protocol error if it detects receiving more than
+one.
+
+The receiver of a SUBSCRIBE_NAMESPACES_OK or SUBSCRIBE_NAMESPACES_ERROR ought to
+forward the result to the application, so that it can make decisions about
+further publishers to contact.
+
+An UNSUBSCRIBE_NAMESPACES withdraws a previous SUBSCRIBE_NAMESPACES. It does
+not prohibit the receiver (publisher) from sending further ANNOUNCE messages.
+
+## ANNOUNCE
+
+A publisher MAY send ANNOUNCE messages to any subscriber. An ANNOUNCE indicates
+to the subscriber where to route a SUBSCRIBE or FETCH for that namespace. A
+subscriber MAY send SUBSCRIBE or FETCH for a namespace without having received
+an ANNOUNCE for it.
+
+If a publisher is authoritative for a given namespace, or is a relay that has
+received an authorized ANNOUNCE for that namespace from an upstream publisher,
+it MUST send an ANNOUNCE to any subscriber that has subscribed to ANNOUNCE for
+that namespace, or a subset of that namespace. A publisher MAY send the ANNOUNCE
+to any other subscriber.
+
+An endpoint SHOULD NOT, however, send an ANNOUNCE advertising a namespace that
+exactly matches a namespace for which the peer sent an earlier ANNOUNCE
+(i.e. an ANNOUNCE ought not to be echoed back to its sender).
+
+The receiver of an ANNOUNCE_OK or ANNOUNCE_ERROR SHOULD report this to the
+application to inform the search for additional subscribers for a namespace,
+or abandoning the attempt to publish under this namespace. This might be
+especially useful in upload or chat applications. A subscriber MUST send exactly
+one ANNOUNCE_OK or ANNOUNCE_ERROR in response to an ANNOUNCE. The publisher
+SHOULD close the session with a protocol error if it receives more than one.
+
+An UNANNOUNCE message withdraws a previous ANNOUNCE, although it is not a
+protocol error for the subscriber to send a SUBSCRIBE or FETCH message after
+receiving an UNANNOUNCE.
+
+A subscriber can send ANNOUNCE_CANCEL to revoke acceptance of an ANNOUNCE, for
+example due to expiration of authorization credentials. The message enables the
+publisher to ANNOUNCE again with refreshed authorization, or discard associated
+state. After receiving an ANNOUNCE_CANCEL, the publisher does not send UNANNOUNCE.
+
+While ANNOUNCE does provide hints on where to route a SUBSCRIBE or FETCH, it is
+not a full-fledged routing protocol and does not protect against loops and other
+phenomena. In particular, ANNOUNCE SHOULD NOT be used to find paths through
+richly connected networks of relays.
+
+## SUBSCRIBE/FETCH
+
+The central interaction with a publisher is to send SUBSCRIBE and/or FETCH for
+a particular track. The subscriber expects to receive a
+SUBSCRIBE_OK/FETCH_OK and objects from the track.
+
+A subscriber MAY send a SUBSCRIBE or FETCH for a track to any publisher. If it
+has accepted an ANNOUNCE with a namespace that exactly matches the namespace for
+that track, it SHOULD only request it from the senders of those ANNOUNCE
+messages.
+
+A publisher MUST send exactly one SUBSCRIBE_OK or SUBSCRIBE_ERROR in response to
+a SUBSCRIBE. It MUST send exactly one FETCH_OK or FETCH_ERROR in response to a
+FETCH. The subscriber SHOULD close the session with a protocol error if it
+receives more than one.
+
+A subscriber keeps SUBSCRIBE state until it sends UNSUBSCRIBE, or after receipt
+of a SUBSCRIBE_DONE or SUBSCRIBE_ERROR. Note that SUBSCRIBE_DONE does not
+usually indicate that state can immediately be destroyed, see
+{{message-subscribe-done}}.
+
+A subscriber keeps FETCH state until it sends FETCH_CANCEL, receives
+FETCH_ERROR, or receives a FIN or RESET_STREAM for the FETCH data stream. If the
+data stream is already open, it MAY send STOP_SENDING for the data stream along
+with FETCH_CANCEL, but MUST send FETCH_CANCEL.
+
+The Publisher can destroy subscription or fetch state as soon as it has received
+UNSUBSCRIBE or FETCH_CANCEL, respectively. It MUST reset any open streams
+associated with the SUBSCRIBE or FETCH. It can also destroy state after closing
+the FETCH data stream.
+
+The publisher can immediately delete SUBSCRIBE state after sending
+SUBSCRIBE_DONE, but MUST NOT send it until it has closed all related streams. It
+can destroy all FETCH state after closing the data stream.
+
+A SUBSCRIBE_ERROR or FETCH_ERROR indicates no objects will be delivered, and
+both endpoints can immediately destroy relevant state. Objects MUST NOT be sent
+for requests that end with an error.
 
 # Priorities {#priorities}
 
@@ -735,17 +843,13 @@ Relays MAY cache Objects, but are not required to.
 
 ## Subscriber Interactions
 
-Subscribers interact with the Relays by sending a SUBSCRIBE or FETCH
-control message for the tracks of interest. Relays MUST ensure subscribers are
-authorized to access the content associated with the track. The authorization
+Subscribers subscribe to tracks by sending a SUBSCRIBE
+({{message-subscribe-req}}) control message for each track of
+interest. Relays MUST ensure subscribers are authorized to access the
+content associated with the track. The authorization
 information can be part of subscription request itself or part of the
-encompassing session. The specifics of how a relay authorizes a user are
-outside the scope of this specification. The subscriber is notified
-of the result of the subscription via a
-SUBSCRIBE_OK ({{message-subscribe-ok}}) or SUBSCRIBE_ERROR
-{{message-subscribe-error}} control message. The entity receiving the
-SUBSCRIBE MUST send only a single response to a given SUBSCRIBE of
-either SUBSCRIBE_OK or SUBSCRIBE_ERROR.
+encompassing session. The specifics of how a relay authorizes a user are outside
+the scope of this specification.
 
 The relay will have to send an upstream SUBSCRIBE and/or FETCH if it does not
 have all the objects in the FETCH, or is not currently subscribed to the full
@@ -756,9 +860,7 @@ one from upstream.
 For successful subscriptions, the publisher maintains a list of
 subscribers for each track. Each new OBJECT belonging to the
 track within the subscription range is forwarded to each active
-subscriber, dependent on the congestion response. A subscription
-remains active until soon after the publisher of the track terminates the
-subscription with a SUBSCRIBE_DONE (see {{message-subscribe-done}}).
+subscriber, dependent on the congestion response.
 
 A caching relay saves Objects to its cache identified by the Object's
 Full Track Name, Group ID and Object ID. Relays MUST be able to
@@ -769,12 +871,6 @@ Group ID and Object ID, Relays MAY ignore subsequently received Objects
 or MAY use them to update the cache. Implementations that update the
 cache need to protect against cache poisoning.
 
-Caching can also reduce the number of upstream FETCH requests.
-
-Objects MUST NOT be sent for unsuccessful subscriptions, and if a subscriber
-receives a SUBSCRIBE_ERROR after receiving objects, it MUST close the session
-with a 'Protocol Violation'.
-
 A relay MUST NOT reorder or drop objects received on a multi-object stream when
 forwarding to subscribers, unless it has application specific information.
 
@@ -843,19 +939,14 @@ to the old relay can be stopped with an UNSUBSCRIBE.
 Publishing through the relay starts with publisher sending ANNOUNCE
 control message with a `Track Namespace` ({{model-track}}).
 The ANNOUNCE enables the relay to know which publisher to forward a
-SUBSCRIBE to if the track belongs to the namespace in the ANNOUNCE.
+SUBSCRIBE to.
 
 Relays MUST verify that publishers are authorized to publish
 the content associated with the set of
 tracks whose Track Namespace matches the announced namespace. Where the
 authorization and identification of the publisher occurs depends on the way the
 relay is managed and is application specific.
 
-Relays respond with an ANNOUNCE_OK or ANNOUNCE_ERROR control message
-providing the result of announcement. The entity receiving the
-ANNOUNCE MUST send only a single response to a given ANNOUNCE of
-either ANNOUNCE_OK or ANNOUNCE_ERROR.
-
 A Relay can receive announcements from multiple publishers for the same
 Track Namespace and it SHOULD respond with the same response to each of the
 publishers, as though it was responding to an ANNOUNCE
@@ -1390,9 +1481,8 @@ See {{priorities}}.
 ## UNSUBSCRIBE {#message-unsubscribe}
 
 A subscriber issues a `UNSUBSCRIBE` message to a publisher indicating it is no
-longer interested in receiving media for the specified track and Objects
-should stop being sent as soon as possible.  The publisher sends a
-SUBSCRIBE_DONE to acknowledge the unsubscribe was successful.
+longer interested in receiving media for the specified track and requesting that
+the publisher stop sending Objects as soon as possible.
 
 The format of `UNSUBSCRIBE` is as follows:
 
@@ -1564,10 +1654,6 @@ The subscriber sends an `ANNOUNCE_CANCEL` control message to
 indicate it will stop sending new subscriptions for tracks
 within the provided Track Namespace.
 
-If a publisher receives new subscriptions for that namespace after
-receiving an ANNOUNCE_CANCEL, it SHOULD close the session as a
-'Protocol Violation'.
-
 ~~~
 ANNOUNCE_CANCEL Message {
   Type (i) = 0xC,
@@ -1749,7 +1835,6 @@ SUBSCRIBE_ERROR
   the subscriber MUST close the connection with a Duplicate Track Alias error
   ({{session-termination}}).
 
-
 ## FETCH_OK {#message-fetch-ok}
 
 A publisher sends a FETCH_OK control message in response to successful fetches.
@@ -1814,7 +1899,6 @@ FETCH_ERROR
 
 * Reason Phrase: Provides the reason for fetch error.
 
-
 ## SUBSCRIBE_DONE {#message-subscribe-done}
 
 A publisher sends a `SUBSCRIBE_DONE` message to indicate it is done publishing
@@ -2067,8 +2151,6 @@ failure.
 
 * Reason Phrase: Provides the reason for the namespace subscription error.
 
-
-
 # Data Streams {#data-streams}
 
 A publisher sends Objects matching a subscription on Data Streams.