W3C home > Mailing lists > Public > public-ortc@w3.org > December 2015

RE: Issue 289: interfaces vs dictionaries

From: Bernard Aboba <Bernard.Aboba@microsoft.com>
Date: Tue, 1 Dec 2015 22:49:47 +0000
To: Robin Raymond <robin@hookflash.com>
CC: "public-ortc@w3.org" <public-ortc@w3.org>
Message-ID: <BLUPR03MB1490018D68AEBB930623525EC0F0@BLUPR03MB149.namprd03.prod.outlook.com>
Overall, I agree that defining RTCRtpContributingSource as an interface does not provide a benefit.

Sequence <RTCRtpContributingSource>  is returned by getContributingSources().  Since only a copy is returned, changing the attributes of an RTCRtpContributingSource dictionary does not affect the SSRC/CSRC values used by the RTP stack.  Also, since RTCRtpContributingSource is not an argument to any other method in the API, there is no benefit to defining the attributes as read-only.

With respect to how RTCRtpContributingSource ended up as an Interface in the WebRTC 1.0 and ORTC API specifications, here is what can be gleaned from the mailing list discussions, the WebRTC WG wiki and Github pull requests:

The WebIDL for RTCRtpContributingSource in the ORTC API was copied from WebRTC 1.0 API Section 5.3.2 (see http://w3c.github.io/webrtc-pc/#widl-RTCRtpReceiver-getContributingSources-sequence-RTCRtpContributingSource ), added to WebRTC 1.0 API specification via PR 300:

In terms of discussion in the WEBRTC WG, the proposal initially discussed at the Redmond Interim meeting included RTCRtpContributingSource as a dictionary:

But the final presentation defined it as an interface:

Subsequent discussion included both interface and dictionary definitions, sometimes in the same posting:

From: Robin Raymond [mailto:robin@hookflash.com]
Sent: Tuesday, December 1, 2015 11:47 AM
To: public-ortc@w3.org
Subject: Issue 289: interfaces vs dictionaries

For example, why is this an interface?

interface RTCRtpContributingSource {
    readonly        attribute DOMHighResTimeStamp timestamp;
    readonly        attribute unsigned long       source;
    readonly        attribute byte?               audioLevel;

I'm not sure how some structured data went from dictionaries and suddenly became interfaces. We must be very careful about interfaces vs dictionaries for simple structured data. There are many cases where a developer would need to construct these structured data from thin air (e.g. remote marshalled IceCandidates); We do not want the programmer being burdened with anything more than a simple json blob style creation, which is why this type of simple structured data must be dictionaries.

The only cases to make structured data as read-only interfaces instead of dictionaries would be when the information is returned by the API locally and used locally as an input parameter to another API where the data cannot be modified. For example, if we made the ICE usernameFrag/password being a constructible piece of data as an input parameter for the `IceGatherer`.

We must be careful in doing so though as it does add a burden onto the developer. Any API point where a real underlying object is used requires the programmer to hold onto the originally returned object instead of treating the information contained within the dictionary as just normal structured property data adds onto that burden. This makes the programmer unable to re-construct this structured data at will, or add hidden properties to the returned data, or insert the data into existing simple structured data (without creating hybrid simple/object mixed data).

PLUS even in the rare case this is still a bit of a headache for the ORTC engine. ORTC engines must be careful to trace the real object hierarchy back to a real internally constructed object to prevent developer from passing in object look-alike forgeries. Likewise, there are often easy alternatives than enforcing this object rule. In the case of ICE usernameFrag/password, the API could restrict receiving input usernameFrag/password combinations that could not have been possibly constructed by non ORTC engine entities by creating an internal "secret" when hashed with to the local ICE usernameFrag generates the associated local ICE password, thus removing the need to burden the application developer with anything more than simple dictionary. This technique is easily applied to many scenarios.

In other words, be careful with structured data becoming interfaces instead of dictionaries. This allows the programmer as much freedom as possible to consume structured data as dictionaries as they please (so the data becomes the programmer has their own private manipulatable and reconstructable copy of the data). If there is a true need for an interface for structured data, let's see if there is a simple alternative work around to prevent it.

Finally with `RTCRtpContributingSource`, I do not see the need to make it anything more than a simple dictionary.

That's my opinion.


Received on Tuesday, 1 December 2015 22:50:20 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 16:39:57 UTC