0078-control_frame_payloads_v1_0_0.md

Control Frame Payloads v1.0.0

• Proposal: SDL-0078
• Author: Joey Grover
• Status: Accepted with Revisions
• Impacted Platforms: [Protocol/Android/iOS/Core]

Introduction

With the acceptance of Constructed Payloads for Control Frames we need to ensure we spec out all the changes that will be needed for the first version of these payloads. This includes adding a new param to the StartService frame for RPC services that contains the max version supported for control frame payloads.

Motivation

It is important to have proper specs when it comes to the protocol API within SDL. The new constructed payloads feature presents a challenge to keep track of all changes and how to version those changes.

Proposed solution

The proposed solution is to document all the payloads in the protocol spec. Because of the introduction of control frame payloads we will also have to bump the protocol version.

All changes are documented as followed:

Payloads

Added: Protocol Version 5.0.0
Note: All payloads are optional

Control frames use BSON to store payload data. All payload types are directly from the BSON spec. Each control frame info type will have a defined set of available data. Most types will also have differently available data based on their service type.

Note: Heartbeat, Heartbeat ACK, and Service Data ACK control frame types are not covered for any service as they were deprecated before payloads were introduced.

Control Service

No defined payloads at this time.

RPC Service

Start Service

Tag Name	Type	Description
protocolVersion	string	The max version of the protocol supported by client requesting service to start. Must be in the format "Major.Minor.Patch"

Start Service ACK

Tag Name	Type	Description
hashId	int32	Hash ID to identify this service and used when sending an EndService control frame
mtu	int64	Max transport unit to be used for this service
protocolVersion	string	The negotiated version of the protocol. Must be in the format "Major.Minor.Patch"

Note: protocolVersion is used to have a higher granular approach to versioning the protocol without having to change the protocol header itself. This is necessary to prevent continuous changes based on control frame payloads. Changing the header would result in a breaking change for apps that haven't updated. This param also changes how version negotiation works, see Version Negotiation.

Start Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters

End Service

Tag Name	Type	Description
hashId	int32	Hash ID supplied in the StartServiceACK for this service type

End Service ACK

End Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters such as: [hashId]

Audio Service

Start Service

Start Service ACK

Tag Name	Type	Description
hashId	int32	Hash ID to identify this service and used when sending an EndService control frame
mtu	int64	Max transport unit to be used for this service. If not included the client should use the one set via the RPC service or protocol version default.

Start Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters such as: [videoProtocol, videoProtocol]

End Service

Tag Name	Type	Description
hashId	int32	Hash ID supplied in the StartServiceACK for this service type

End Service ACK

End Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters such as: [hashId ]

Video Service

Start Service

Tag Name	Type	Description
height	int32	Desired height in pixels from the client requesting the video service to start
width	int32	Desired width in pixels from the client requesting the video service to start
videoProtocol	String	Desired video protocol to be used. See VideoStreamingProtocol RPC
videoCodec	String	Desired video codec to be used. See VideoStreamingCodec RPC

Start Service ACK

Tag Name	Type	Description
hashId	int32	Hash ID to identify this service and used when sending an EndService control frame
mtu	int64	Max transport unit to be used for this service. If not included the client should use the one set via the RPC service or protocol version default.
height	int32	Accepted height in pixels from the client requesting the video service to start
width	int32	Accepted width in pixels from the client requesting the video service to start
videoProtocol	String	Accepted video protocol to be used. See VideoStreamingProtocol RPC
videoCodec	String	Accepted video codec to be used. See VideoStreamingCodec RPC

Start Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters such as: [videoProtocol, videoProtocol]

End Service

Tag Name	Type	Description
hashId	int32	Hash ID supplied in the StartServiceACK for this service type

End Service ACK

End Service NAK

Tag Name	Type	Description
rejectedParams	String Array	An array of rejected parameters such as: [hashId]

Version Negotiation

Since control frames will now have payloads we need to slightly modify how version negotiation takes place.

Version 1-4 Negotiation

Proxy	Direction	Core
StartService Version: v1 Payload: no payload	----------->
	<-----------	StartServiceACK Version: Max supported by Core Payload: raw bytes for hashID
SingleFrame Version: Highest version supported by both Core and Proxy Payload: Lots of bytes	----------->

Version 5+ Negotiation

Proxy	Direction	Core
StartService Version: v1 Payload: Constructed payload [protocolVersion: 5.x.x]	----------->	v4 Core: Ignores payload, sends protocol version 4 frame and uses previous negotiation scheme. v5 Core: Reads in payload data, uses this information to determine version.
	<-----------	StartServiceACK Version: Highest version supported by both Core and Proxy Payload: Constructed payload [protocolVersion: 5.x.x, hashId: 0x9873, mtu: 130687]
SingleFrame Version: Highest version supported by both Core and Proxy Payload: Lots of bytes	----------->

The proxy would include it's max supported version in the StartService payload, however, it would still operate under the same logic when receiving a StartServiceACK from Core to ensure proper version.

Potential downsides

• Introduces a new version that will have to be kept track of.
• Testing would have to be performed with legacy systems that do not support version 5 of the protocol to ensure adding the payload to the StartService frame doesn't break anything.

Impact on existing code

Same impacts as the previously accepted Constructed Payloads with a few minor additions to keep track of control frame payload versions.

Alternatives considered

• Not including controlVersion param into the RPC service StartService and ACK. This would force us to bump the protocol version every time we made a change. Unless we kept everything optional and agreed that param additions didn't require a bump, but that is messy.
• Expanding the protocol header to include more than a single digit version code: this introduces a bit of extra testing as we would change to a new header definition. It is doable. If the original 4bits for version were equal or greater than the header size would increase by 2 more bytes to hold the minor and patch versions. It would look like:

Potential Version 5 Frame Header

Byte 1			Byte 2	Byte 3	Byte 4
Version Flag	E	Frame Type	Version Major	Version Minor	Version Patch

Byte 5	Byte 6	Byte 7	Byte 8
(TBD)	Service Type	Frame Info	Session ID

Byte 9	Byte 10	Byte 11	Byte 12
Data Size

Byte 13	Byte 14	Byte 15	Byte 16
Message ID