FETCH

9.16.1. Standalone Fetch

A Fetch of Objects performed independently of any Subscribe.

A Standalone Fetch includes this structure:

Standalone Fetch {
  Track Namespace (..),
  Track Name Length (i),
  Track Name (..),
  Start Location (Location),
  End Location (Location)
}

• 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).

• Start Location: The start Location.

• End Location: The end Location, plus 1. A Location.Object value of 0 means the entire group is requested.

9.16.2. Joining Fetches

A Joining Fetch is associated with a Subscribe request by specifying the Request ID of a subscription in the Established or Pending (subscriber) state. A publisher receiving a Joining Fetch uses properties of the associated Subscribe to determine the Track Namespace, Track Name and End Location such that it is contiguous with the associated Subscribe. The subscriber can set the Start Location to an absolute Location or a Location relative to the current group.

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 Largest Object; any other value results in closing the session with a PROTOCOL_VIOLATION.

If no Objects have been published for the track, and the SUBSCRIBE_OK did not include a LARGEST_OBJECT parameter (Section 9.2.2.7), the publisher MUST respond with a REQUEST_ERROR with error code INVALID_RANGE.

A Joining Fetch includes this structure:

Joining Fetch {
  Joining Request ID (i),
  Joining Start (i)
}

• Joining Request ID: The Request ID of the subscription to be joined. If a publisher receives a Joining Fetch with a Request ID that does not correspond to a subscription in the same session in the Established or Pending (subscriber) states, it MUST return a REQUEST_ERROR with error code INVALID_JOINING_REQUEST_ID.

• Joining Start : A relative or absolute value used to determing the Start Location, described below.

9.16.3. Fetch Handling

The format of FETCH is as follows:

FETCH Message {
  Type (i) = 0x16,
  Length (16),
  Request ID (i),
  Fetch Type (i),
  [Standalone (Standalone Fetch),]
  [Joining (Joining Fetch),]
  Number of Parameters (i),
  Parameters (..) ...
}

• Request ID: See Section 9.1.

• Fetch Type: Identifies the type of Fetch, whether Standalone, Relative Joining or Absolute Joining.

• Standalone: Standalone Fetch structure included when Fetch Type is 0x1

• Joining: Joining Fetch structure included when Fetch Type is 0x2 or 0x3.

• Parameters: The parameters are defined in Section 9.2.2.

A publisher responds to a FETCH request with either a FETCH_OK or a REQUEST_ERROR message. The publisher creates a new unidirectional stream that is used to send the Objects. The FETCH_OK or REQUEST_ERROR can come at any time relative to object delivery.

The publisher responding to a FETCH is responsible for delivering all available Objects in the requested range in the requested order (see Section 9.2.2.4). The Objects in the response are delivered on a single unidirectional stream. Any gaps in the Group and Object IDs in the response stream indicate objects that do not exist. For Ascending Group Order this includes ranges between the first requested object and the first object in the stream; between objects in the stream; and between the last object in the stream and the Largest Group/Object indicated in FETCH_OK, so long as the fetch stream is terminated by a FIN. If no Objects exist in the requested range, the publisher opens the unidirectional stream, sends the FETCH_HEADER (see Section 10.4.4) and closes the stream with a FIN.

A relay that has cached objects from the beginning of the range MAY start sending objects immediately in response to a FETCH. If it encounters an object in the requested range that is not cached and has unknown status, the relay MUST pause subsequent delivery until it has confirmed the object's status upstream. If the upstream FETCH fails, the relay sends a REQUEST_ERROR and can reset the unidirectional stream. It can choose to do so immediately or wait until the cached objects have been delivered before resetting the stream.

The Object Forwarding Preference does not apply to fetches.

Fetch specifies an inclusive range of Objects starting at Start Location and ending at End Location. End Location MUST specify the same or a larger Location than Start Location for Standalone and Absolute Joining Fetches.

Objects that are not yet published will not be retrieved by a FETCH. The Largest available Object in the requested range is indicated in the FETCH_OK, and is the last Object a fetch will return if the End Location have not yet been published.

If Start Location is greater than the Largest Object (Section 9.9) the publisher MUST return REQUEST_ERROR with error code INVALID_RANGE.

A publisher MUST send fetched groups in the requested group order, either ascending or descending. Within each group, objects are sent in Object ID order; subgroup ID is not used for ordering.

If a Publisher receives a FETCH with a range that includes one or more Objects with unknown status (e.g. a Relay has temporarily lost contact with the Original Publisher and does not have the Object in cache), it can choose to reset the FETCH data stream with UNKNOWN_OBJECT_STATUS, or indicate the range of unknown Objects and continue serving other known Objects.