/*! @license
* Shaka Player
* Copyright 2016 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
goog.provide('shaka.msf.draft18.MessageType');
goog.provide('shaka.msf.draft18.MessageTypeId');
goog.provide('shaka.msf.draft18.MessageWriter');
goog.require('shaka.config.MsfFilterType');
goog.require('shaka.msf.Utils');
goog.require('shaka.util.BufferUtils');
goog.require('shaka.util.DataViewWriter');
goog.require('shaka.util.StringUtils');
/**
* Message type IDs for draft-18.
*
* Deliberately separate from the draft-16 constants rather than shared. The
* drafts reassign IDs and, more dangerously, reuse them with different
* meanings: 0x7 was PUBLISH_NAMESPACE_OK and is now the generic REQUEST_OK,
* 0x8 was PUBLISH_NAMESPACE_ERROR and is now NAMESPACE, 0xE was
* TRACK_STATUS_OK and is now NAMESPACE_DONE, 0xF was TRACK_STATUS_ERROR and is
* now PUBLISH_BLOCKED, and SUBSCRIBE_NAMESPACE moved from 0x11 to 0x50. A
* shared enum would mis-parse silently instead of failing.
*
* Note the values are var ints, not single bytes: SETUP is 0x2F00.
*
* @enum {number}
*/
shaka.msf.draft18.MessageTypeId = {
SETUP: 0x2f00,
GOAWAY: 0x10,
SUBSCRIBE: 0x3,
SUBSCRIBE_OK: 0x4,
PUBLISH: 0x1d,
PUBLISH_OK: 0x1e,
PUBLISH_DONE: 0xb,
FETCH: 0x16,
FETCH_OK: 0x18,
TRACK_STATUS: 0xd,
PUBLISH_NAMESPACE: 0x6,
SUBSCRIBE_NAMESPACE: 0x50,
SUBSCRIBE_TRACKS: 0x51,
NAMESPACE: 0x8,
NAMESPACE_DONE: 0xe,
PUBLISH_BLOCKED: 0xf,
REQUEST_UPDATE: 0x2,
REQUEST_OK: 0x7,
REQUEST_ERROR: 0x5,
};
/**
* Internal discriminators for decoded draft-18 messages.
*
* @enum {string}
*/
shaka.msf.draft18.MessageType = {
SETUP: 'setup',
GOAWAY: 'goaway',
SUBSCRIBE: 'subscribe',
SUBSCRIBE_OK: 'subscribe_ok',
PUBLISH: 'publish',
PUBLISH_OK: 'publish_ok',
PUBLISH_DONE: 'publish_done',
FETCH: 'fetch',
FETCH_OK: 'fetch_ok',
TRACK_STATUS: 'track_status',
PUBLISH_NAMESPACE: 'publish_namespace',
SUBSCRIBE_NAMESPACE: 'subscribe_namespace',
SUBSCRIBE_TRACKS: 'subscribe_tracks',
NAMESPACE: 'namespace',
NAMESPACE_DONE: 'namespace_done',
PUBLISH_BLOCKED: 'publish_blocked',
REQUEST_UPDATE: 'request_update',
REQUEST_OK: 'request_ok',
REQUEST_ERROR: 'request_error',
};
/**
* Fetch Type values, from draft-18 section 10.12.
*
* @enum {number}
*/
shaka.msf.draft18.FetchType = {
STANDALONE: 0x1,
RELATIVE_JOINING: 0x2,
ABSOLUTE_JOINING: 0x3,
};
/**
* Serializes draft-18 control messages.
*
* Every message is a var int type, a 16-bit length, then the payload. Two
* things differ structurally from draft-16 beyond the field layouts:
*
* - The type is a var int rather than a single byte, because SETUP is 0x2F00.
* - Responses carry no Request ID. They arrive on the bidirectional stream
* that carried the request, and that stream is the correlation, so there is
* nothing to write.
*
* Draft-20 changed one message body and nothing else, so the field writers and
* the type/length framing are protected rather than private: draft-20 extends
* this class and overrides only marshalFetch().
*/
shaka.msf.draft18.MessageWriter = class {
/**
* @param {!shaka.extern.MsfCodec} codec
* @param {number=} initialSize
*/
constructor(codec, initialSize = 1024) {
/** @private {!shaka.extern.MsfCodec} */
this.codec_ = codec;
/** @private {!shaka.util.DataViewWriter} */
this.writer_ = new shaka.util.DataViewWriter(
initialSize, shaka.util.DataViewWriter.Endianness.BIG_ENDIAN);
}
/**
* @return {!Uint8Array}
*/
getBytes() {
return this.writer_.getBytes();
}
/** Resets the buffer to start writing from the beginning. */
reset() {
this.writer_.reset();
}
/**
* @param {bigint|number} value
* @protected
*/
writeVarInt(value) {
this.codec_.encodeVarInt(
this.writer_, typeof value == 'bigint' ? value : BigInt(value));
}
/**
* @param {string} str
* @protected
*/
writeString(str) {
const bytes = shaka.util.BufferUtils.toUint8(
shaka.util.StringUtils.toUTF8(str));
this.writeVarInt(bytes.length);
this.writer_.writeBytes(bytes);
}
/**
* A Track Namespace is a count of fields followed by each length-prefixed
* field.
*
* @param {Array<string>} namespace
* @protected
*/
writeNamespace(namespace) {
const fields = namespace || [];
this.writeVarInt(fields.length);
for (const field of fields) {
this.writeString(field);
}
}
/**
* @param {shaka.msf.Utils.Location} location
* @protected
*/
writeLocation(location) {
this.writeVarInt(location.group);
this.writeVarInt(location.object);
}
/**
* Writes delta-encoded Key-Value-Pairs without a count prefix, which is how
* Setup Options are framed: they span the whole message payload and are
* bounded by the message length.
*
* @param {!Array<shaka.msf.Utils.KeyValuePair>} pairs
* @protected
*/
writeKeyValuePairs(pairs) {
// Delta encoding requires ascending type order.
/** @type {!Array<shaka.msf.Utils.KeyValuePair>} */
const sorted = [...pairs].sort(
(a, b) => (a.type < b.type ? -1 : (a.type > b.type ? 1 : 0)));
let prevType = BigInt(0);
for (const pair of sorted) {
this.writeVarInt(pair.type - prevType);
prevType = pair.type;
if (pair.type % BigInt(2) === BigInt(0)) {
if (typeof pair.value !== 'bigint') {
throw new Error(
`Invalid value for even key ${pair.type}: expected bigint`);
}
this.writeVarInt(pair.value);
} else {
if (!ArrayBuffer.isView(pair.value)) {
throw new Error(
`Invalid value for odd key ${pair.type}: expected Uint8Array`);
}
const bytes = /** @type {!Uint8Array} */ (pair.value);
this.writeVarInt(bytes.byteLength);
this.writer_.writeBytes(bytes);
}
}
}
/**
* Writes a count-prefixed parameter list, which is how every message other
* than SETUP frames its parameters.
*
* @param {(Array<shaka.msf.Utils.KeyValuePair>|undefined)} pairs
* @protected
*/
writeParameters(pairs) {
const params = pairs || [];
this.writeVarInt(params.length);
this.writeKeyValuePairs(params);
}
/**
* Writes the var int type and 16-bit length around a payload.
*
* @param {shaka.msf.draft18.MessageTypeId} type
* @param {function()} writeContent
* @return {!shaka.msf.draft18.MessageWriter}
* @protected
*/
marshal(type, writeContent) {
this.writeVarInt(type);
const lengthPosition = this.writer_.getPosition();
this.writer_.writeUint16(0); // Placeholder
const contentStart = this.writer_.getPosition();
writeContent();
this.writer_.patchUint16(
lengthPosition, this.writer_.getPosition() - contentStart);
return this;
}
/**
* Draft-17 collapsed CLIENT_SETUP and SERVER_SETUP into one message whose
* payload is nothing but Setup Options, uncounted and bounded by the
* message length.
*
* @param {!Array<shaka.msf.Utils.KeyValuePair>} options
* @return {!shaka.msf.draft18.MessageWriter}
*/
marshalSetup(options) {
return this.marshal(shaka.msf.draft18.MessageTypeId.SETUP, () => {
this.writeKeyValuePairs(options);
});
}
/**
* @param {{
* requestId: bigint,
* namespace: Array<string>,
* trackName: string,
* params: (Array<shaka.msf.Utils.KeyValuePair>|undefined),
* }} msg
* @return {!shaka.msf.draft18.MessageWriter}
*/
marshalSubscribe(msg) {
return this.marshal(shaka.msf.draft18.MessageTypeId.SUBSCRIBE, () => {
this.writeVarInt(msg.requestId);
this.writeNamespace(msg.namespace);
this.writeString(msg.trackName);
this.writeParameters(msg.params);
});
}
/**
* A standalone FETCH. Start and End are Location structures rather than the
* four loose var ints draft-16 used, and the range is a field of the message
* rather than a parameter, which is what draft-20 changed.
*
* The range is an inclusive pair of absolute Locations, so the zeroed pair
* the caller may leave out asks for exactly the Object at {0, 0}, not for
* the whole track. Draft-20 says the same thing with a LOCATION_FILTER.
*
* @param {{
* requestId: bigint,
* namespace: Array<string>,
* trackName: string,
* startLocation: (shaka.msf.Utils.Location|undefined),
* endLocation: (shaka.msf.Utils.Location|undefined),
* params: (Array<shaka.msf.Utils.KeyValuePair>|undefined),
* }} msg
* @return {!shaka.msf.draft18.MessageWriter}
*/
marshalFetch(msg) {
const range = shaka.msf.draft18.MessageWriter.fetchRange(msg);
return this.marshal(shaka.msf.draft18.MessageTypeId.FETCH, () => {
this.writeVarInt(msg.requestId);
this.writeVarInt(shaka.msf.draft18.FetchType.STANDALONE);
this.writeNamespace(msg.namespace);
this.writeString(msg.trackName);
this.writeLocation(range.start);
this.writeLocation(range.end);
this.writeParameters(msg.params);
});
}
/**
* The parameter that makes a SUBSCRIBE start at a given Location rather than
* at the live edge, which is what seeking into already-published content
* needs.
*
* Draft-18 spells it SUBSCRIPTION_FILTER (0x21): a Filter Type followed by
* the fields that type takes. AbsoluteStart takes a Start Location and no
* end, so the subscription runs from there to the live edge and onwards, and
* the draft says outright that the Start Location MAY be smaller than the
* publisher's Largest Object (section 5.1.2). Draft-20 keeps the parameter
* type and changes its contents, so the draft-20 writer overrides this.
*
* @param {shaka.msf.Utils.Location} startLocation
* @return {shaka.msf.Utils.KeyValuePair}
*/
locationFilterParam(startLocation) {
return {
type: BigInt(shaka.msf.draft18.MessageWriter.Parameter.LOCATION_FILTER),
value: this.encodeVarIntField([
BigInt(shaka.config.MsfFilterType.ABSOLUTE_START),
startLocation.group,
startLocation.object,
]),
};
}
/**
* The Location range a FETCH covers, filling in the default the callers that
* do not care rely on. Shared with draft-20, which carries the same range in
* a parameter instead of in the message.
*
* @param {{
* startLocation: (shaka.msf.Utils.Location|undefined),
* endLocation: (shaka.msf.Utils.Location|undefined),
* }} msg
* @return {{
* start: shaka.msf.Utils.Location,
* end: shaka.msf.Utils.Location,
* }}
* @protected
*/
static fetchRange(msg) {
const origin = {group: BigInt(0), object: BigInt(0)};
return {
start: msg.startLocation || origin,
end: msg.endLocation || origin,
};
}
/**
* Encodes a sequence of var ints into a standalone byte field, for the
* parameters whose value is itself a var int structure rather than a single
* integer.
*
* @param {!Array<bigint>} values
* @return {!Uint8Array}
* @protected
*/
encodeVarIntField(values) {
// Nine bytes is the widest a var int gets in this draft family.
const writer = new shaka.util.DataViewWriter(
9 * values.length, shaka.util.DataViewWriter.Endianness.BIG_ENDIAN);
for (const value of values) {
this.codec_.encodeVarInt(writer, value);
}
return writer.getBytes();
}
/**
* @param {{
* requestId: bigint,
* namespace: Array<string>,
* params: (Array<shaka.msf.Utils.KeyValuePair>|undefined),
* }} msg
* @return {!shaka.msf.draft18.MessageWriter}
*/
marshalSubscribeNamespace(msg) {
return this.marshal(
shaka.msf.draft18.MessageTypeId.SUBSCRIBE_NAMESPACE, () => {
this.writeVarInt(msg.requestId);
this.writeNamespace(msg.namespace);
this.writeParameters(msg.params);
});
}
/**
* REQUEST_OK answers PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, TRACK_STATUS
* and the rest. It carries no Request ID: it goes back on the request's own
* bidirectional stream.
*
* @param {(Array<shaka.msf.Utils.KeyValuePair>|undefined)=} params
* @return {!shaka.msf.draft18.MessageWriter}
*/
marshalRequestOk(params) {
return this.marshal(shaka.msf.draft18.MessageTypeId.REQUEST_OK, () => {
this.writeParameters(params);
// Track Properties are empty for everything but TRACK_STATUS_OK.
});
}
};
/**
* The parameter types this player sends on a SUBSCRIBE or a FETCH.
*
* Draft-20 renamed 0x21 from SUBSCRIPTION_FILTER to LOCATION_FILTER and
* changed what its value holds, but the code point is the same in both, so
* there is one constant rather than one per draft.
*
* @enum {number}
*/
shaka.msf.draft18.MessageWriter.Parameter = {
FORWARD: 0x10,
SUBSCRIBER_PRIORITY: 0x20,
LOCATION_FILTER: 0x21,
};