Reporting API

1. Introduction

This document provides three pieces of infrastructure for generic reporting, which may be used or extended by other specifications:

1. A generic framework for defining report types and reporting endpoints, and a document format for sending reports to endpoints over HTTP.

2. A specific mechanism for configuring reporting endpoints in a document or worker, and for delivering reports whose lifetime is tied to that document or worker.

3. A JavaScript interface for observing reports generated within a document or worker.

Other specifications may extend or make use of these pieces, for instance by defining concrete report types, or alternative configuration or delivery mechanisms for non-document-based reports.

1.1. Guarantees

This specification aims to provide a best-effort report delivery system that executes out-of-band with website activity. The user agent will be able to do a better job prioritizing and scheduling delivery of reports, as it has an overview of cross-origin activity that individual websites do not, and can deliver reports based on error conditions that would prevent a website from loading in the first place.

The delivery is not, however, guaranteed in any way, and reporting is not intended to be used as a reliable communications channel. Network conditions may prevent reports from reaching their destination at all, and user agents are permitted to reject and not deliver a report for any reason.

1.2. Examples

Reporting-Endpoints: endpoint-1="https://example.com/reports"

Content-Security-Policy: ...; report-to endpoint-1
Public-Key-Pins: ...; report-to=endpoint-1

Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports",
                     hpkp-endpoint="https://example.com/hpkp-reports"

Content-Security-Policy: ...; report-to csp-endpoint
Public-Key-Pins: ...; report-to=hpkp-endpoint

2. Generic Reporting Framework

This section defines the generic concepts of reports and endpoints, and how reports are serialized into the application/reports+json format.

2.1. Concepts

2.1.1. Endpoints

An endpoint is location to which reports for a particular origin may be sent.

Each endpoint has a name, which is an ASCII string.

Each endpoint has a url, which is a URL.

Each endpoint has a failures, which is a non-negative integer representing the number of consecutive times this endpoint has failed to respond to a request.

2.1.2. Report Type

A report type is a non-empty string that specifies the set of data that is contained in the body of a report.

When a report type is defined (in this spec or others), it can be 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 visible to ReportingObservers.

2.1.3. Reports

A report is a collection of arbitrary data which the user agent is expected to deliver to a specified endpoint.

Each report has a body, which is either null or an object which can be serialized into a JSON text. The fields contained in a report’s body are determined by the report’s type.

Each report has a url, which is typically the address of the Document or Worker from which the report was generated.

Note: We strip the username, password, and fragment from this serialized URL. See § 8.1 Capability URLs.

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 destination, which is a string representing the name of the endpoint that the report will be sent to.

Each report has a type, which is a report type.

Each report has a timestamp, which records the time at which the report was generated, in milliseconds since the unix epoch.

Each report has an attempts counter, which is a non-negative integer representing the number of times the user agent attempted to deliver the report.

2.2. Media Type

The media type used when POSTing reports to a specified endpoint is application/reports+json.

2.3. Queue data as type for destination

To generate a report given a serializable object (data), a string (type), another string (destination), an optional environment settings object (settings), and an optional URL (url):

1. Let report be a new report object with its values initialized as follows:

   body

   data

   user agent

   The current value of navigator.userAgent

   destination

   destination

   type

   type

   timestamp

   The current timestamp.

   attempts

   0

2. If url was not provided by the caller, let url be settings’s creation URL.

3. Set url’s username to the empty string, and its password to null.

4. Set report’s url to the result of stripping URL for use in reports, given url.

5. Return report.

Note: reporting observers can only observe reports from the same environment settings object.

Note: We strip the username, password, and fragment from the serialized URL in the report. See § 8.1 Capability URLs.

Note: The user agent MAY reject reports for any reason. This API does not guarantee delivery of arbitrary amounts of data, for instance.

Note: Non user agent clients (with no JavaScript engine) should not interact with reporting observers, and thus should return in step 6.

2.4. Serialize Reports

To serialize a list of reports to JSON,

1. Let collection be an empty list.

2. For each report in reports:

   1. Let data be a map with the following key/value pairs:

      age

      The number of milliseconds between report’s timestamp and the current time.

      type

      report’s type

      url

      report’s url

      user_agent

      report’s user agent

      body

      report’s body

      Note: Client clocks are unreliable and subject to skew. We therefore deliver an age attribute rather than an absolute timestamp. See also § 9.2 Clock Skew

   2. Increment report’s attempts.

   3. Append data to collection.

3. Return the byte sequence resulting from executing serialize an Infra value to JSON bytes on collection.

3. Document Centered Reporting

This section defines the mechanism for configuring reporting endpoints for reports generated by actions in a document (or in a worker script). Such reports have a lifetime which is tied to that of the document or worker where they were generated.

3.1. Document configuration

Each object implementing WindowOrWorkerGlobalScope has an endpoints list, which is a list of endpoints, each of which MUST have a distinct name. (Uniqueness is guaranteed by the algorithm in § 3.3 Process reporting endpoints for response.)

Each object implementing WindowOrWorkerGlobalScope has an reports list, which is a list of reports.

To initialize a global’s endpoint list, given a WindowOrWorkerGlobalScope (scope) and a response (response), set scope’s