[Meta] Proof-read and modernize spec #463

rakuco · 2023-07-21T10:50:29Z

This has been discussed in passing at TPAC in the last couple of years, so I'm finally filing an issue to keep track of this task.

Most of the spec text was written some 6-7 years ago, and since then new best practices have come up (for example, the Privacy Considerations and Security Considerations sections are expected to be separate these days). I also think the spec is not great at defining some terms and concepts, and some algorithms are a bit hand-wavy.

Doing an internal spec review and addressing these items would also show that this WG is committed to following the latest best practices and that this spec is well-maintained, in addition to helping us if we ever need to ask for a TAG review again.

Instead of having several paragraphs mixing what a sensor type must or may and algorithms, the "Sensor Type" section now only has two paragraphs and two groups containing what must be defined and what may be defined to make it easier to follow. This also has consequences for the "Extensibility" section, as its "Definition Requirements" subsection used to duplicate some of the contents in "Sensor Type". It now just refers to the latter and provides more details about how some of a sensor type's associated data must be defined in extension specifications. Some data that used to be associated with a sensor type has been removed: - "Associated sensors" were never properly defined and it was not clear that they meant "associated _platform_ sensors". They were only used in the generic sensor permission revocation algorithm, which has been rewritten. - "Permission request algorithm" is a term that has been moved from the Permissions spec to the Requesting Permissions permission in WICG. None of the extension specifications ever defined it. The generic sensor permission revocation algorithm was moved to the "Abstract Operations" section. It has also been merged with the revoke sensor permission algorithm since it was its only caller. There should not be any user-visible effects though: the language was just made more formal by iterating over all Sensor instances belonging to the current realm (like the Web Bluetooth spec does) instead of hand-wavingly gathering all platform sensors (which technically are per-navigable) with the same sensor type. Related to w3c#463.

The association was implicit so far: in some abstract operations we retrieved a Sensor instance's "associated sensor type" without ever specifying what it actually meant. Doing this also simplifies algorithms that retrieved a sensor type via a Sensor instance's platform sensor. Related to w3c#463.

This commit addresses a few issues with the way frequency management was handled in the specification: 1. "Sampling frequency" was interchangeably used as a number as well as an interval ("sampling frequency bounds"), and the latter was not even properly defined. 2. The actual bounds were not properly defined, and neither was the clamping process that used them. 3. There were too many frequency-related terms in use. Let us start with the changes in the concepts and definitions: - A platform sensor has a sampling frequency, a positive number or null. It represents the frequency at which the platform sensor attempts to retrieve data from the device sensor and it is calculated in an implementation-defined manner based on the `[[frequency]]` of the associated Sensor objects. It is therefore a mixture of the previous "sampling frequency" and "requested sampling frequency" definitions. . How the sampling process works is implementation-defined: it could be polling, or requesting updates at this interval, or something else entirely. - A device sensor has a sampling frequency. It is similar to the above, but operating system or hardware dependent and opaque to this specification. . As such, the device sensor may choose a sampling frequency that differs from the platform sensor's sampling frequency and we have no control over it. - A device sensor MAY report lower and/or upper sampling frequency bounds. With the above, the actual sampling bounds are defined and checked: - A sensor type MUST have lower and upper sampling frequency bounds. The lower bound is "max(implementation-defined value, optional spec-defined value)", and the upper bound is "min(implementation-defined value, optional spec-defined value)". - A new algorithm returns a platform sensor's lower and upper sampling bounds as a tuple "(max(optional device sensor lower bound, sensor type lower bound), min(optional device sensor upper bound, sensor type upper bound))". - A Sensor's `[[frequency]]` is always set to a value within a platform sensor's sampling bounds in "Connect to a sensor" (before that it might not have an associated platform sensor and should be in the "activated" state). - "Set sensor settings" requires that the platform sensor sampling value calculated based on its associated sensors' `[[frequency]]` values lies within its sampling bounds. The "optimal sampling frequency" and "requested sampling frequency" <dfn>s have been removed, and so has the "Find the reporting frequency of a sensor object" algorithm, which addresses point (3). The "Automation" section has only received enough changes to avoid Bikeshed errors and warnings, as the entire section is being rewritten. Related to w3c#463.

latest reading["timestamp"] was not defined strictly enough: the definition mentioned "the time origin", which is a concept that only exists related to a given environment settings object. We now have it be an "unsafe current time" as defined by the High Resolution Time specification, and its value is always set using the same monotonic clock -- if we get a timestamp directly from a device sensor (e.g. a WinRT timestamp relative to the Windows epoch) it needs to be translated into a timestamp that makes sense with the monotonic clock. Finally, Sensor.timestamp no longer just returns latest reading["timestamp"] and instead ensures that whatever "unsafe current time" the latter returns is coarsened and converted to a value relative to its relevant time origin. Related to w3c#463.