Reporting: Clarify "pending" reports, add README.md.

net/reporting/README.md

Index: net/reporting/README.md
diff --git a/net/reporting/README.md b/net/reporting/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..82d663a25cf9ec5371d4cbe8096a231e7e315b4f
--- /dev/null
+++ b/net/reporting/README.md
@@ -0,0 +1,77 @@
+# Reporting
+
+Reporting is a central mechanism for sending out-of-band error reports
+to origins from various other components (e.g. HTTP Public Key Pinning,
+Interventions, or Content Security Policy could potentially use it).
+
+The parts of it that are exposed to the web platform are specified in
+the [draft spec](http://wicg.github.io/reporting/). This document
+assumes that you've read that one.
+
+## Reporting in Chromium
+
+Reporting is implemented as part of the network stack in Chromium, such
+that it can be used by other parts of the network stack (e.g. HPKP) or
+by non-browser embedders as well as by Chromium.
+
+Almost all of Reporting lives in `//net/reporting`; there is a small
+amount of code in `//chrome/browser/net` to set up Reporting in
+profiles and provide a persistent store for reports and endpoints
+across browser restarts.
+
+### Inside `//net`
+
+* The top-level class is the *`ReportingService`*. This lives in the
+  `URLRequestContext`, and provides the high-level operations used by
+  other parts of `//net` and other components: queueing reports,
+  handling configuration headers, clearing browsing data, and so on.
+
+  * Within `ReportingService` lives *`ReportingContext`*, which in turn
+    contains the inner workings of Reporting, spread across several
+    classes:
+
+    * The *`ReportingCache`* stores undelivered reports and unexpired
+      endpoint configurations.
+
+    * The *`ReportingHeaderParser`* parses `Report-To:` headers and
+      updates the `Cache` accordingly.
+
+    * The *`ReportingDeliveryAgent`* reads reports from the `Cache`,
+      decides which endpoints to deliver them to, and attempts to
+      do so. It uses a couple of helper classes:
+
+      * The *`ReportingUploader`* does the low-level work of delivering
+        reports: accepts a URL and JSON from the `DeliveryAgent`,
+        creates a `URLRequest`, and parses the result.
+
+      * The *`ReportingEndpointManager`* keeps track of which endpoints
+        are in use, and manages exponential backoff (using
+        `BackoffEntry`) for failing endpoints.
+
+    * The *`ReportingGarbageCollector`* periodically examines the
+      `Cache` and removes reports that have remained undelivered for too
+      long, or that have failed delivery too many times.
+
+    * The *`ReportingSerializer`* reads the `Cache` and serializes it
+      into a `base::Value` for persistent storage (in Chromium, as a
+      pref); it can also deserialize a serialized `Value` back into the
+      `Cache`.
+
+    * The *`ReportingBrowsingDataRemover`* examines the `Cache` upon
+      request and removes browsing data (reports and endpoints) of
+      selected types and origins.
+
+### Outside `//net`
+
+* In `*ProfileImplIOData*::InitializeInternal`, the `ReportingService`
+  is created and set in the `URLRequestContext`, where the net stack
+  can use it.
+
+  (There is currently no interface to Reporting besides "hop over to
+  the IO thread and poke the `ReportingService` in your favorite
+  `URLRequestContext`", but that should change as various components
+  need to queue reports.)
+
+* *`ChromeReportingDelegate`* implements `ReportingDelegate` and plumbs
+  the persistent data interface into prefs. It lives in
+  `//chrome/browser/net`.