Joining Fetch

draft-ietf-moq-transport.md

@@ -1514,6 +1514,27 @@ objects within a track. The publisher responding to a FETCH is responsible for r
 all available Objects. If there are gaps between Objects, the publisher omits them from the
 fetch response. All omitted objects have status Object Does Not Exist.
 
+**Fetch Types**
+
+There are two types of Fetch messages:
+
+Standalone Fetch (0x1) : A Fetch of Objects performed independently of any Subscribe.
+
+Joining Fetch (0x2) : A Fetch joined together with a Subscribe. A Joining Fetch
+shares the same Subscribe ID as an already-sent Subscribe. A publisher receiving a
+Joining Fetch should use properties of the associated Subscribe to determine the
+Track Namespace, Track, StartGroup, StartObject, EndGroup, and EndObject for the
+Joining Fetch such that it is contiguous with the associated Subscribe and begins
+Preceding Group Offset prior.
+
+A Subscriber can use a Joining Fetch to, for example, fill a playback buffer with a
+certain number of groups prior to the live edge of a track.
+
+A Joining Fetch is only permitted when the associated Subscribe has the Filter
+Type Latest Object.
+
+A Fetch Type other than the above MUST be treated as an error.
+
 A publisher responds to a FETCH request with either a FETCH_OK or a FETCH_ERROR
 message.  If it responds with FETCH_OK, the publisher creates a new unidirectional
 stream that is used to send the Objects.  A relay MAY start sending objects immediately
@@ -1533,29 +1554,31 @@ FETCH Message {
   Type (i) = 0x16,
   Length (i),
   Subscribe ID (i),
-  Track Namespace (tuple),
-  Track Name Length (i),
-  Track Name (..),
   Subscriber Priority (8),
   Group Order (8),
-  StartGroup (i),
-  StartObject (i),
-  EndGroup (i),
-  EndObject (i),
+  Fetch Type (i),
+  [Track Namespace (tuple),
+   Track Name Length (i),
+   Track Name (..),
+   StartGroup (i),
+   StartObject (i),
+   EndGroup (i),
+   EndObject (i),]
+  [Preceding Group Offset (i),]
   Number of Parameters (i),
   Parameters (..) ...
 }
 ~~~
 {: #moq-transport-fetch-format title="MOQT FETCH Message"}
 
+Fields common to all Fetch Types:
+
 * Subscribe ID: The Subscribe ID identifies a given fetch request. Subscribe ID
 is a variable length integer that MUST be unique and monotonically increasing
-within  a session.
-
-* Track Namespace: Identifies the namespace of the track as defined in
-({{track-name}}).
-
-* Track Name: Identifies the track name as defined in ({{track-name}}).
+within a session. For a Standalone Fetch a new Subscribe ID MUST be used. For
+a Joining Fetch, the Subscribe ID MUST correspond to a Subscribe which has already
+been sent. If a publisher receives a Joining Fetch with a Subscribe ID that does
+not correspond to an existing Subscribe, it MUST respond with a Fetch Error.
 
 * Subscriber Priority: Specifies the priority of a fetch request relative to
 other subscriptions or fetches in the same session. Lower numbers get higher
@@ -1566,6 +1589,17 @@ Ascending (0x1) or Descending (0x2) order by group. See {{priorities}}.
 A value of 0x0 indicates the original publisher's Group Order SHOULD be
 used. Values larger than 0x2 are a protocol error.
 
+* Fetch Type: Identifies the type of Fetch, whether joining or standalone.
+
+* Parameters: The parameters are defined in {{version-specific-params}}.
+
+Fields present only for Standalone Fetch (0x1):
+
+* Track Namespace: Identifies the namespace of the track as defined in
+({{track-name}}).
+
+* Track Name: Identifies the track name as defined in ({{track-name}}).
+
 * StartGroup: The start Group ID.
 
 * StartObject: The start Object ID.
@@ -1575,8 +1609,11 @@ used. Values larger than 0x2 are a protocol error.
 * EndObject: The end Object ID, plus 1. A value of 0 means the entire group is
 requested.
 
-* Parameters: The parameters are defined in {{version-specific-params}}.
+Field present only for Joining Fetch (0x2):
 
+* Preceding Group Offset: The group offset for the Fetch prior and relative
+to the StartGroup of the corresponding Subscribe. A value of 0 indicates
+the current Group.
 
 Objects that are not yet published will not be retrieved by a FETCH.
 The latest available Object is indicated in the FETCH_OK, and is the last
@@ -1590,9 +1627,40 @@ subgroup ID is not used for ordering.
 If StartGroup/StartObject is greater than the latest published Object group,
 the publisher MUST return FETCH_ERROR with error code 'No Objects'.
 
-A publisher MUST send fetched groups in group order, either ascending or
-descending. Within each group, objects are sent in Object ID order;
-subgroup ID is not used for ordering.
+### Calculating the Range of a Joining Fetch
+
+A publisher which receives a Fetch message with a Fetch Type of 0x2 treats it
+as a Fetch with a range dynamically determined by the Preceding Group Offset
+field and field values derived from the corresponding SUBSCRIBE message
+(hereafter "the Subscribe").
+
+The following values are used:
+
+* Resolved Subscribe Start Group: the Largest Group ID of the associated Subscribe.
+* Resolved Subscribe Start Object: the Largest Object ID of the associated Subscribe.
+
+The Resolved Subscribe Start values for a Joining Fetch MUST correspond to the
+referenced Subscribe within the same session so that the ranges of Objects covered
+by the Fetch and Subscribe are contiguous and non-overlapping.
+If no Objects have been published for the track, so the SUBSCRIBE_OK has a
+ContentExists value of 0, the publisher MUST respond to the Joining Fetch with a
+FETCH_ERROR.
+
+The publisher receiving a Joining Fetch computes the fetch range as follows:
+
+* Fetch StartGroup: Resolved Subscribe Start Group - Preceding Group Offset
+* Fetch StartObject: 0
+
+If Resolved Subscribe Start Object is 0:
+* Fetch EndGroup: Resolved Subscribe Start Group - 1
+* Fetch EndObject: 0 (all objects in the group)
+
+Else, if Resolved Subscribe Start Object is 1 or more:
+* Fetch EndGroup: Resolved Subscribe Start Group
+* Fetch EndObject: Resolved Subscribe Start Object
+
+If Fetch EndGroup < Fetch StartGroup, there are no Objects to retrieve,
+so respond with a `FETCH_ERROR`.
 
 ## FETCH_CANCEL {#message-fetch-cancel}