diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..04f41dc
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,3 @@
+# Code of Conduct
+
+All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).
diff --git a/index.src.html b/index.src.html
index ea86eb9..fc0c6d6 100644
--- a/index.src.html
+++ b/index.src.html
@@ -1,9 +1,9 @@
Reporting API
-Status: CG-DRAFT
-ED: https://wicg.github.io/reporting/
+Status: ED
+ED: https://w3c.github.io/reporting/
Shortname: reporting
-Group: wicg
+Group: webperf
Editor: Douglas Creager 103120, Google Inc., dcreager@google.com
Editor: Ilya Grigorik 56102, Google Inc., igrigorik@google.comm
Editor: Mike West 56384, Google Inc., mkwst@google.com
@@ -15,9 +15,9 @@ Reporting API
reports in a consistent manner.
Level: 1
Indent: 2
-Version History: https://github.com/wicg/reporting/commits/master/index.src.html
+Version History: https://github.com/w3c/reporting/commits/master/index.src.html
Boilerplate: omit conformance, omit feedback-header
-!Participate: File an issue (open issues)
+!Participate: File an issue (open issues)
Markup Shorthands: css off, markdown on
@@ -77,6 +77,13 @@ Reporting API
type: dfn
text: origin
text: top-level browsing context
+ urlPrefix: system-state.html
+ type: dfn
+ text: navigator.userAgent; url: dom-navigator-useragent
+spec: RFC2782; for: SRV; urlPrefix: https://tools.ietf.org/html/rfc2782
+ type: dfn
+ text: SRV record; url:
+ text: target selection algorithm; url: page-4
spec: RFC3986; urlPrefix: https://tools.ietf.org/html/rfc3986
type: grammar
text: absolute-uri; url: section-4.3
@@ -85,7 +92,7 @@ Reporting API
url: section-8.2
text: superdomain match
text: congruent match
-spec: RFC7159; urlPrefix: https://tools.ietf.org/html/rfc7159
+spec: RFC8259; urlPrefix: https://tools.ietf.org/html/rfc8259
type: dfn
text: JSON text; url: section-2
spec: RFC7230; urlPrefix: https://tools.ietf.org/html/rfc7230
@@ -160,11 +167,12 @@ Guarantees
for a report to be dropped on the floor if things go badly.
Reporting can generate a good deal of traffic, so we allow developers to set
- up groups of endpoints. 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 reporting traffic. Endpoints can be
- assigned priorities, allowing developers to set up fallback collectors that
+ up groups of endpoints, using a failover and 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 reporting traffic. Endpoints can
+ be assigned priorities, allowing developers to set up fallback collectors that
are only tried when uploads to primary collectors fail.
Examples
@@ -306,10 +314,10 @@ Report Type
that is contained in the [=report/body=] of a report.
When a report type is defined (in this spec or others), it can be
- specified to be observable from JavaScript, meaning
+ specified to be visible to ReportingObservers, meaning
that reports of that type can be observed by a reporting
- observer. By default, report types are not observable from
- JavaScript.
+ observer. By default, report types are not visible to
+ ReportingObservers.
Note: See [[#deprecation-report]] as an example report type definition.
@@ -333,6 +341,17 @@ Reports
Each report has an origin,
which is an origin representing the report's initiator.
+ Each report has a user agent, which is
+ the value of the User-Agent header of the request
+ from which the report was generated.
+
+ Note: The user agent of a report represents the
+ User-Agent sent by the browser for the page which generated the
+ report. This is potentially distinct from the User-Agent
+ sent in the HTTP headers when uploading the report to a collector — for
+ instance, where the browser has chosen to use a non-default
+ User-Agent string such as the "request desktop site" feature.
+
Each report has a group,
which is a string representing the {{endpoint group/name}} of the
origin's endpoint group that the report will be sent
@@ -381,6 +400,16 @@ Failover and load balancing
The algorithm that implements these rules is described in
[[#choose-endpoint]].
+
+ Note: The {{endpoint/priority}} and {{endpoint/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 the Reporting API will be updated to use it instead of this
+ bespoke mechanism.
@@ -398,7 +427,7 @@
Report-To = json-field-value
- ; See Section 2 of [[HTTP-JFV]], and Section 2 of [[RFC7159]]
+ ; See Section 2 of [[HTTP-JFV]], and Section 2 of [[RFC8259]]
The header's value is interpreted as an array of JSON objects, as described in
@@ -618,6 +647,11 @@ Report Delivery
in the period directly after its generation than it would be a day or a week
later.
+
+
+ The media type used when POSTing reports to a specified endpoint is
+ `application/reports+json`.
+
Queue |data| as |type| for |endpoint group| on |settings|
@@ -634,6 +668,8 @@
:: |data|
: [=report/origin=]
:: |settings|'s origin
+ : [=report/user agent=]
+ :: The current value of navigator.userAgent
: [=report/group=]
:: |endpoint group|
: [=report/type=]
@@ -675,6 +711,9 @@
Choose an |endpoint| from a |group|
+ 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 {{endpoint/priority}} and {{endpoint/weight}} of the endpoints.
@@ -853,6 +892,8 @@
:: |report|'s [=report/type=]
: `url`
:: |report|'s [=report/url=]
+ : `user_agent`
+ :: |report|'s [=report/user agent=]
: `body`
:: |report|'s [=report/body=]
@@ -873,7 +914,7 @@
:: |origin|
: `header list`
:: A new header list containing a header named
- "`Content-Type`" whose value is "`application/report`"
+ "`Content-Type`" whose value is "`application/reports+json`"
: `client`
:: `null`
: `window`
@@ -979,7 +1020,7 @@ Interface {{ReportingObserver}}
- A {{ReportingObserverOptions}} dictionary called
options.
- A list of {{Report}} objects called the report
- list, which is initially empty.
+ queue, which is initially empty.
A {{ReportList}} represents a sequence of {{Report}}s, providing developers
with all the convenience methods found on JavaScript arrays.
@@ -1026,9 +1067,9 @@ Interface {{ReportingObserver}}
The takeRecords() method,
when invoked, must run these steps:
- 1. Let |reports| be a copy of the context object's report list.
+ 1. Let |reports| be a copy of the context object's report queue.
- 2. Empty the context object's report list.
+ 2. Empty the context object's report queue.
3. Return |reports|.
@@ -1053,11 +1094,11 @@
Given a report |report| and a {{ReportingObserver}} |observer|, this
- algorithm adds |report| to |observer|'s report list, so long as
+ algorithm adds |report| to |observer|'s report queue, so long as
|report|'s type is observable by |observer|.
- 1. If |report|'s [=report/type=] is not observable from JavaScript,
- return.
+ 1. If |report|'s [=report/type=] is not visible to
+ ReportingObservers, return.
2. If |observer|'s options has a non-empty
{{ReportingObserverOptions/types}} member which does not contain |report|'s
@@ -1069,11 +1110,11 @@
Issue: how to polymorphically initialize body?
- 3. Append |r| to |observer|'s report list.
+ 3. Append |r| to |observer|'s report queue.
- 4. If the size of |observer|'s report list is 1, Queue a task to
- [[#invoke-observers]] with a copy of the registered reporting observer
- list of the ECMAScript global
+ 4. If the size of |observer|'s report queue is 1, Queue a task
+ to [[#invoke-observers]] with a copy of the registered reporting
+ observer list of the ECMAScript global
environment associated with |observer|.
@@ -1085,11 +1126,11 @@
1. For each {{ReportingObserver}} |observer| in |notify list|:
- 1. If |observer|'s report list is empty, then continue.
+ 1. If |observer|'s report queue is empty, then continue.
- 2. Let |reports| be a copy of |observer|'s report list
+ 2. Let |reports| be a copy of |observer|'s report queue
- 3. Empty |observer|'s report list
+ 3. Empty |observer|'s report queue
4. Invoke |observer|'s callback with a list of
arguments consisting of |reports| and |observer|, and |observer| as the
@@ -1107,7 +1148,8 @@ Deprecation
Deprecation reports have the report type "deprecation".
- Deprecation reports are observable from JavaScript.
+ Deprecation reports are visible to
+ ReportingObservers.
interface DeprecationReportBody : ReportBody {
@@ -1157,12 +1199,13 @@ Intervention
Intervention reports indicate that a user agent has decided not to
honor a request made by the application (e.g. for security, performance or
user annoyance reasons). Note that the report properties are the same as those
- for deprecation reports, except for the absense of
+ for deprecation reports, except for the absence of
[=DeprecationReportBody/anticipated_removal=].
Intervention reports have the report type "intervention".
- Intervention reports are observable from JavaScript.
+ Intervention reports are visible to
+ ReportingObservers.
interface InterventionReportBody : ReportBody {
@@ -1178,7 +1221,7 @@ Intervention
{{InterventionReportBody}}, contains the following fields:
- id: an implementation-defined
- string identifying the specific intervention that occured. This string can
+ string identifying the specific intervention that occurred. This string can
be used for grouping and counting related reports.
- message: A human-readable string
@@ -1249,12 +1292,13 @@ Sample Reports
POST / HTTP/1.1
Host: example.com
...
- Content-Type: application/report
+ Content-Type: application/reports+json
[{
"type": "csp",
"age": 10,
"url": "https://example.com/vulnerable-page/",
+ "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"body": {
"blocked": "https://evil.com/evil.js",
"directive": "script-src",
@@ -1266,6 +1310,7 @@ Sample Reports
"type": "hpkp",
"age": 32,
"url": "https://www.example.com/",
+ "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"body": {
"date-time": "2014-04-06T13:00:50Z",
"hostname": "www.example.com",
@@ -1287,6 +1332,7 @@ Sample Reports
"type": "nel",
"age": 29,
"url": "https://example.com/thing.js",
+ "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
"body": {
"referrer": "https://www.example.com/",
"server-ip": "234.233.232.231",
@@ -1390,7 +1436,7 @@ Network Leakage
one network to be sent while the user is on another network, even if they
don't explicitly open the page from which the report was sent.
- ISSUE(WICG/BackgroundSync#107): Consider mitigations. For example, we could
+ ISSUE(w3c/BackgroundSync#107): Consider mitigations. For example, we could
drop reports if we change from one network to another.
Clock Skew
@@ -1460,13 +1506,11 @@ Disabling Reporting
IANA Considerations
+
+
The permanent message header field registry should be updated
with the following registration: [[!RFC3864]]
-
- Report-To
-
-
: Header field name
:: `Report-To`
: Applicable protocol
@@ -1477,4 +1521,39 @@
:: W3C
: Specification document
:: This specification (see [[#header]])
+
+
+
+ : Type name
+ :: application
+ : Subtype name
+ :: reports+json
+ : Required parameters
+ :: N/A
+ : Optional parameters
+ :: N/A
+ : Encoding considerations
+ :: Encoding considerations are identical to those specified for the "application/json" media type. See [[RFC8259]].
+ : Security considerations
+ :: See [[#security]].
+ : Interoperability considerations
+ :: This document specifies the format of conforming messages and the interpretation thereof.
+ : Published specification
+ :: [[#media-type]]
+ : Applications that use this media type
+ : Fragment identifier considerations
+ : Additional information
+ :: N/A
+ : Person and email address to contact for further information
+ :: This document's editors.
+ : Intended usage:
+ :: COMMON
+ : Restrictions on usage:
+ :: N/A
+ : Author
+ :: This document's editors.
+ : Change controller
+ :: W3C
+ : Provisional registration?
+ :: Yes.