1. Introduction
-This document extends the concepts defined in [REPORTING] to enable a class +
This document extends the concepts defined in [REPORTING] to enable a class of reports which are not tied to the lifetime of any particular document. This enables network errors to be reported on, even (or especially) in cases where a document could not be loaded.
Decoupling reports from documents implies two major differences from the - document-centred reporting defined in [REPORTING]: First, configuration of + document-centred reporting defined in [REPORTING]: First, configuration of reporting must be done at the origin level, rather than through document response headers. Second, the reports are queued and delivered by the user agent separately from document reports.
@@ -614,7 +629,7 @@
Reporting can generate a good deal of traffic, so we allow developers to set
up groups of endpoints, using a failover and
- load-balancing mechanism inspired by the DNS SRV record. The user
+ load-balancing mechanism inspired by the DNS SRV record. The user
agent will do its best to deliver a particular report to at most
one endpoint in a group. Endpoints can be assigned weights to
distribute load, with each endpoint receiving a specified fraction of
@@ -685,10 +700,10 @@
weight, which determines how report
traffic is balanced across the failover class.
The algorithm that implements these rules is described in § 5.1 Choose an endpoint from a group.
- Note: The priority
and weight
fields have the same semantics as the
- corresponding fields in a DNS SRV record.
- Note: Failover and load balancing is a feature that would be generally useful
- outside of Reporting. Reporting delegates to the [FETCH] API to actually
+
Note: The priority
and weight
fields have the same semantics as the
+ corresponding fields in a DNS SRV record.
+ Note: Failover and load balancing is a feature that would be generally useful
+ outside of Reporting. Reporting delegates to the [FETCH] API to actually
upload reports once an endpoint has been selected. If, in the future, the
Fetch API adds native support for failover and load balancing of requests, a
future version of this specification will be updated to use it instead of this
@@ -716,7 +731,7 @@
3. Endpoint Delivery
A server MAY define a set of endpoint groups for an origin it controls
- through an origin policy manifest [ORIGIN-POLICY].
+ through an origin policy manifest [ORIGIN-POLICY].
Endpoint groups are specified with the "network_reporting_endpoints"
member, which defines the endpoint groups to be associated with that
origin.
This member is defined in § 3.1 The
@@ -740,7 +755,7 @@ endpoint group
will be given the name
"default
".
3.1.2. The include_subdomains
member
The OPTIONAL include_subdomains
member is a boolean that enables this endpoint group for all
- subdomains of the current origin’s host.
+ subdomains of the current origin’s host.
3.1.3. The max_age
member
The REQUIRED max_age
member defines the endpoint group’s lifetime, as a non-negative
integer number of seconds.
@@ -759,7 +774,7 @@ The REQUIRED url
member is a
string that defines the location of the endpoint.
The member’s value MUST be a string. Moreover, the URL that the member’s value
- represents MUST be potentially trustworthy [SECURE-CONTEXTS].
+ represents MUST be potentially trustworthy [SECURE-CONTEXTS].
Non-secure endpoints will be ignored.
3.1.6. The endpoints.priority
member
The OPTIONAL priority
member is
@@ -774,7 +789,7 @@
map (parsed), and an origin (origin),
this algorithm extracts a list of network reporting endpoints and endpoint groups for origin, and updates the reporting
cache accordingly.
-
Note: This algorithm is called from around step 9 of Origin Policy § parse-a-string-into-an-origin-policy, and only updates the reporting cache if the response has been delivered securely.
+ Note: This algorithm is called from around step 9 of Origin Policy § parse-a-string-into-an-origin-policy, and only updates the reporting cache if the response has been delivered securely.
- Note: This algorithm is the same as the target selection
- algorithm used for DNS SRV records.
+ Note: This algorithm is the same as the target selection
+ algorithm used for DNS SRV records.
Given an endpoint group (group), this algorithm chooses an arbitrary
eligible endpoint from the group, if there is one, taking into
account the priority
and weight
of the endpoints.
@@ -980,14 +995,14 @@ tuple origin whose host is a domain:
+
If origin is a tuple origin whose host is a domain:
-
-
For each parent domain that is a superdomain match for origin’s host [RFC6797], considering longer
+
For each parent domain that is a superdomain match for origin’s host [RFC6797], considering longer
domains first:
-
-
Let parent origin be a copy of origin, with its host replaced with parent domain.
+ Let parent origin be a copy of origin, with its host replaced with parent domain.
-
Let client be the entry in the reporting cache for parent origin.
-
@@ -1007,7 +1022,7 @@
Note: This algorithm ensures that more specific subdomains
policies take precendence over less specific ones,
+
Note: This algorithm ensures that more specific subdomains
policies take precendence over less specific ones,
and that subdomains
policies are ignored for any
non-domain origins (e.g., for a request to a raw IP address).
-
@@ -1048,7 +1063,7 @@
Note: reports remain in the reporting cache for potential
+
Note: reports remain in the reporting cache for potential
delivery to other endpoints.
Otherwise (if result is "Failure
"):
@@ -1058,7 +1073,7 @@ retry_after to
a point in the future which the user agent chooses.
-
Note: We don’t specify a particular algorithm here, but user
+
Note: We don’t specify a particular algorithm here, but user
agents are encouraged to employ some sort of exponential
backoff algorithm which increases the retry period with the
number of failures, with the addition of some random jitter to
@@ -1070,7 +1085,7 @@
Note: User agents MAY decide to attempt delivery for only a subset of the
+
Note: User agents MAY decide to attempt delivery for only a subset of the
collected reports or endpoints (because, for example, sending all the reports
at once would consume an unreasonable amount of bandwidth, etc). As reports
are only removed from the cache when they’re successfully delivered, skipped
@@ -1233,9 +1248,9 @@
9.
priority over the ability of a user to individually opt-out of such a system.
Sending reports costs bandwidth, and potentially could reveal some small
amount of additional information above and beyond what a website can obtain
- in-band ([NETWORK-ERROR-LOGGING], for instance). User agents MUST allow
+ in-band ([NETWORK-ERROR-LOGGING], for instance). User agents MUST allow
users to disable reporting with some reasonable amount of granularity in order
- to maintain the priority of constituencies espoused in [HTML-DESIGN-PRINCIPLES].
+ to maintain the priority of constituencies espoused in [HTML-DESIGN-PRINCIPLES].
priority
and weight
fields have the same semantics as the
- corresponding fields in a DNS SRV record.priority
and weight
fields have the same semantics as the
+ corresponding fields in a DNS SRV record.A server MAY define a set of endpoint groups for an origin it controls - through an origin policy manifest [ORIGIN-POLICY].
+ through an origin policy manifest [ORIGIN-POLICY].Endpoint groups are specified with the "network_reporting_endpoints"
member, which defines the endpoint groups to be associated with that
origin.
This member is defined in § 3.1 The
@@ -740,7 +755,7 @@ endpoint group
will be given the name
"default
".
3.1.2. The include_subdomains
member
The OPTIONAL include_subdomains
member is a boolean that enables this endpoint group for all
- subdomains of the current origin’s host.
3.1.3. The max_age
member
The REQUIRED max_age
member defines the endpoint group’s lifetime, as a non-negative
integer number of seconds.
The REQUIRED url
member is a
string that defines the location of the endpoint.
The member’s value MUST be a string. Moreover, the URL that the member’s value
- represents MUST be potentially trustworthy [SECURE-CONTEXTS].
+ represents MUST be potentially trustworthy [SECURE-CONTEXTS].
Non-secure endpoints will be ignored.
3.1.6. The endpoints.priority
member
The OPTIONAL priority
member is
@@ -774,7 +789,7 @@
map (parsed), and an origin (origin),
this algorithm extracts a list of network reporting endpoints and endpoint groups for origin, and updates the reporting
cache accordingly.
-
Note: This algorithm is called from around step 9 of Origin Policy § parse-a-string-into-an-origin-policy, and only updates the reporting cache if the response has been delivered securely.
+ Note: This algorithm is called from around step 9 of Origin Policy § parse-a-string-into-an-origin-policy, and only updates the reporting cache if the response has been delivered securely.
endpoints.priority
memberpriority
member is
@@ -774,7 +789,7 @@ priority
and weight
of the endpoints.For each parent domain that is a superdomain match for origin’s host [RFC6797], considering longer +
For each parent domain that is a superdomain match for origin’s host [RFC6797], considering longer domains first:
-
-
Let parent origin be a copy of origin, with its host replaced with parent domain.
+Let parent origin be a copy of origin, with its host replaced with parent domain.
-
Let client be the entry in the reporting cache for parent origin.
-
@@ -1007,7 +1022,7 @@
Note: This algorithm ensures that more specific
subdomains
policies take precendence over less specific ones, +Note: This algorithm ensures that more specific
subdomains
policies take precendence over less specific ones, and thatsubdomains
policies are ignored for any non-domain origins (e.g., for a request to a raw IP address). -
@@ -1048,7 +1063,7 @@
Note: reports remain in the reporting cache for potential +
Note: reports remain in the reporting cache for potential delivery to other endpoints.
Otherwise (if result is "Failure
"):
retry_after to a point in the future which the user agent chooses. -
Note: We don’t specify a particular algorithm here, but user +
Note: We don’t specify a particular algorithm here, but user agents are encouraged to employ some sort of exponential backoff algorithm which increases the retry period with the number of failures, with the addition of some random jitter to @@ -1070,7 +1085,7 @@
Note: User agents MAY decide to attempt delivery for only a subset of the +
Note: User agents MAY decide to attempt delivery for only a subset of the collected reports or endpoints (because, for example, sending all the reports at once would consume an unreasonable amount of bandwidth, etc). As reports are only removed from the cache when they’re successfully delivered, skipped @@ -1233,9 +1248,9 @@