Abstract

The Network Information API enables web applications to access information about the network connection in use by the device.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://wicg.github.io/netinfo/ for the Editor's draft.

This specification was published by the Web Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Use cases and requirements

This document attempts to address the requirements from the Review of Apps that Use Network Information. Those are:

2. Examples of usage

This section is non-normative.

For examples of the kinds of applications one can build with this API, see the Review of Apps that Use Network Information.

Example 1
// Get the connection type.
var type = navigator.connection.type;

// Get an upper bound on the downlink speed of the first network hop
var max = navigator.connection.downlinkMax;

function changeHandler(e) {
  // Handle change to connection here.
}

// Register for event changes.
navigator.connection.onchange = changeHandler;

// Alternatively.
navigator.connection.addEventListener('change', changeHandler);

3. Definitions

For clarity, a megabit is 1,000,000 bits, and megabits per second is equivalent to transferring:

4. Connection types

4.1 Underlying connection technology

This section defines the connection types and the underlying connection technology that the user agent is using (if any):

bluetooth
A Bluetooth connection.
cellular
A cellular connection (e.g., EDGE, HSPA, LTE, etc.).
ethernet
An Ethernet connection.
none
No network connection. The user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail) - i.e., equivalent to navigator.onLine === false in HTML.
mixed
The user agent is using multiple connection types.
other
The connection type that is known, but not one of enumerated connection types.
unknown
The user agent has established a network connection, but is unable, or unwilling, to determine the underlying connection technology.
wifi
A Wi-Fi connection.
wimax
A WiMAX connection.

The connection types are represented in this API by the ConnectionType enum.

4.2 ConnectionType enum

enum ConnectionType {
    "bluetooth",
    "cellular",
    "ethernet",
    "mixed",
    "none",
    "other",
    "unknown",
    "wifi",
    "wimax"
};

4.3 Effective connection types

This section defines the effective connection types (ECT):

Table of effective connection types
ECT Minimum RTT (ms) Maximum downlink (Kbps) Explanation
slow-2g 2000 50 The network is suited for small transfers only such as text-only pages.
2g 1400 70 The network is suited for transfers of small images.
3g 270 700 The network is suited for transfers of large assets such as high resolution images, audio, and SD video.
4g 0 ∞ The network is suited for HD video, real-time video, etc.

The above round-trip and bandwidth values are based on real user measurement observations:

The absolute values provided above are based on real user measurement on Chrome on Android, as captured in April 2017. The user agent MAY update these values in the future to reflect changes in the measurement data.

The effective connection types are represented in this API by the EffectiveConnectionType enum.

4.4 EffectiveConnectionType enum

enum EffectiveConnectionType {
    "2g",
    "3g",
    "4g",
    "slow-2g"
};

5. NavigatorNetworkInformation interface

The NavigatorNetworkInformation interface exposes access to NetworkInformation interface by extending the Navigator and WorkerNavigator interface.

[NoInterfaceObject,
 Exposed=(Window,Worker)]
interface NavigatorNetworkInformation {
    readonly attribute NetworkInformation connection;
};

Navigator implements NavigatorNetworkInformation;

WorkerNavigator implements NavigatorNetworkInformation;

5.1 connection attribute

The connection attribute, when getting, returns an object that implements the NetworkInformation interface.

6. NetworkInformation interface

The NetworkInformation interface provides a means to access information about the network connection the user agent is currently using. The EventTarget is defined in [DOM].

[Exposed=(Window,Worker)]
interface NetworkInformation : EventTarget {
    readonly attribute ConnectionType          type;
    readonly attribute EffectiveConnectionType effectiveType;
    readonly attribute Megabit                 downlinkMax;
    readonly attribute Megabit                 downlink;
    readonly attribute Millisecond             rtt;
    readonly attribute boolean                 saveData;
             attribute EventHandler            onchange;
};

typedef unrestricted double Megabit;

typedef unsigned long long Millisecond;

6.1 type attribute

The type attribute, when getting, returns the connection type that the user agent is using.

6.2 effectiveType attribute

The effectiveType attribute, when getting, returns the effective connection type that is determined using a combination of recently observed rtt and downlink values.

6.3 downlinkMax attribute

The downlinkMax attribute represents an upper bound on the downlink speed of the first network hop. The reported value is in megabits per second and determined by the properties of the underlying connection technology.

Note

The user agent has no knowledge of the total number or the performance characteristics of the various network hops required to fulfill a particular request; different requests may follow different routes and have different performance characteristics. The reported upper bound on the downlink speed of the first network hop value is determined by the properties of the underlying connection technology of the first network hop. The end-to-end performance of any request cannot exceed this value, but it is also not a guarantee of performance and may be significantly worse.

6.4 onchange attribute

The onchange event handler attribute handles "change" events fired during the steps to update the connection values.

6.5 downlink attribute

The downlink attribute represents the effective bandwidth estimate in megabits per second, rounded to nearest multiple of 25 kilobits per second, and is based on recently observed application layer throughput across recently active connections, excluding connections made to private address space [RFC1918]. In absence of recent bandwidth measurement data, the attribute value is determined by the properties of the underlying connection technology.

6.6 rtt attribute

The rtt attribute represents the effective round-trip time estimate in milliseconds, rounded to nearest multiple of 25 milliseconds, and is based on recently observed application-layer RTT measurements across recently active connections, excluding connections made to private address space [RFC1918]. In absence of recent RTT measurement data, the attribute value is determined by the properties of the underlying connection technology.

6.7 saveData attribute

The saveData attribute, when getting, returns true if the user has requested a reduced data usage mode from the user agent, and false otherwise.

Note

The user may enable such preference, if made available by the user agent, due to high data transfer costs, slow connection speeds, or other reasons.

6.7.1 Save-Data (Client Hint) Request Header Field

The “Save-Data” request header field consists of one or more tokens that indicate user agent's preference for reduced data usage.

      Save-Data = sd-token *( OWS ";" OWS [sd-token] )
      sd-token = token

This specification defines the "on" sd-token value, which is used as a signal indicating explicit user opt-in into a reduced data usage mode (i.e. when saveData's value is true), and when communicated to origins allows them to deliver alternate content honoring such preference - e.g. smaller image and video resources, alternate markup, and so on.

If Save-Data occurs in a message more than once, the last value overrides all previous occurrences.

Issue 1

TODO: update Fetch#fetching algorithm to use connection.saveData as signal to append the Save-Data header.

7. Underlying connection technology

The relationship between an underlying connection technology and its upper bound on the downlink speed of the first network hop is determined by the available network interfaces that may be used to fulfill new network requests.

The downlinkMax for an available interface is determined via the standardized, or generally accepted, maximum download data rate captured in the table of maximum downlink speeds. Where possible, this value may be refined to report a more accurate upper bound based on current properties of the interface - e.g. signal strength, modulation algorithm, and other "network weather" variables.

The upper bound on the downlink speed of the first network hop is determined by the rules described in handling changes to the underlying connection.

Note

The enumeration of available network interfaces and their generation and version is not directly exposed to script. Instead, downlinkMax exposes a single value in megabits per second that accounts for all available interfaces and their current network conditions.

7.1 Handling changes to the underlying connection

When the properties of the underlying connection technology change, due to a switch to a different connection type or effective connection type, change in upper bound on the downlink speed of the first network hop, change in effective downlink or rtt estimates, or change in saveData preference, the user agent MUST run the steps to update the connection values:

  1. Let new-type be the connection type that represents the underlying connection technology.
  2. Let new-effective-type be the effective connection type determined by current downlink and rtt values.
  3. Let new-saveData be the current saveData preference.
  4. Let new-downlink be the result of:
    1. Rounding downlink value to nearest multiple of 25 kilobits per second.
    2. If the resulting value is 10% greater or smaller than the value of connection.downlink, then set new-dowlink to resulting value. Otherwise, set new-downlink to the value of connection.downlink.
  5. Let new-rtt be the result of:
    1. Rounding rtt value to nearest multiple of 25 milliseconds.
    2. If the resulting value is 10% greater or smaller than the value of connection.rtt, then set new-rtt to resulting value. Otherwise, set new-rtt to the value of connection.rtt.
  6. If new-type is "none", set max-value to 0.
  7. if new-type is "unknown", set max-value to +Infinity.
  8. If new-type is "mixed", set max-value to an applicable value for the interface configuration used to service new network requests - e.g. if multiple interfaces may be used, sum their downlinkMax for an available interface values.
  9. Otherwise, set max-value to downlinkMax for an available interface.
  10. If max-value is not equal to the value of connection.downlinkMax, or if new-type is not equal to the value of connection.type, or if new-downlink is not equal to the value of connection.downlink, or if new-rtt is not equal to the value of connection.rtt, or if new-saveData is not equal to the value of connection.saveData:
    1. Using the networking task source, queue a task to perform the following:
      1. Set connection.downlinkMax to max-value.
      2. Set connection.type to new-type.
      3. set connection.effectiveType to new-effective-type.
      4. Set connection.downlink to new-downlink.
      5. Set connection.rtt to new-rtt.
      6. Set connection.saveData to new-saveData.
      7. Fire an event named change at the NetworkInformation object.

8. Privacy Considerations

The Network Information API exposes information about the observed end-to-end network bandwidth and latency, and the first network hop between the user agent and the server; specifically, the type of connection and the upper bound of the downlink speed, as well as signals whenever this information changes. Such information may be used to:

However, above considerations are not new, and sufficiently motivated attackers may already obtain such information using other technologies:

Further, by repeating one of the above strategies (e.g. via invoking periodic fetch or refresh of a resource; via periodic SSE or WebSocket messages; via periodic STUN requests, etc.), the attacker can observe changes over time in the performance characteristics of client's connection and IP address. Such data can then be used to refine the user fingerprint, infer users location (e.g. are they home, at work, or in transit), and extract various behavioral patterns.

The above list is not a complete overview. However, as the above examples illustrate, the attacks are possible both from the sender and the receiver:

Mitigating such attacks initiated from the client requires preventing the attacker from observing and initiating network requests - e.g., use HTTPS to prevent trivial content injection by malicious parties; disable JavaScript to prevent scripted resource fetch of any kind. Mitigating attacks from the sender is possible via the use of a VPN or an HTTP proxy - e.g. to hide the client's true IP address, to introduce additional latency, and so on.

As such, while the Network Information API makes it easier to obtain information about the end-to-end network throughput, latency, and the first network hop, by avoiding the need to observe or make network requests, it does not expose anything that is not already available to a sufficiently-motivated attacker.

If the client wants to mitigate this class of attacks, they should disable JavaScript, monitor that all outbound requests are made to trusted origins, and make diligent use of anonymizing VPN/proxy services.

9. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST are to be interpreted as described in [RFC2119].

There is only one class of product that can claim conformance to this specification: a user agent.

A. Acknowledgments

This document reuses text from the [HTML] specification as permitted by the license of that specification.

B. References

B.1 Normative references

[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC1918]
Address Allocation for Private Internets. Y. Rekhter; B. Moskowitz; D. Karrenberg; G. J. de Groot; E. Lear. IETF. February 1996. Best Current Practice. URL: https://tools.ietf.org/html/rfc1918
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

B.2 Informative references

[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[netinfo-usecases]
Review of apps that use network information. Marcos Caceres; Fernando Jiménez Moreno; Ernesto Jimenez. W3C. 3 April 2014. W3C Note. URL: https://www.w3.org/TR/netinfo-usecases/