Populate download_file_types proto and filter it for each platform

chrome/browser/resources/safe_browsing/README.md

Index: chrome/browser/resources/safe_browsing/README.md
diff --git a/chrome/browser/resources/safe_browsing/README.md b/chrome/browser/resources/safe_browsing/README.md
index 3d7f2e60fe855c0879352dd35e6981f86926f053..3fd57ad5b915a3dbe95c3528ae3fcdebfb84067c 100644
--- a/chrome/browser/resources/safe_browsing/README.md
+++ b/chrome/browser/resources/safe_browsing/README.md
@@ -1,7 +1,7 @@
 # Behavior of Download File Types in Chrome
 
 This describes how to adjust file-type download behavior in
-Chrome including interactions with Safe Browsing.  The metadata described
+Chrome including interactions with Safe Browsing. The metadata described
 here, and stored in `download_file_types.asciipb`, will be both baked into
 Chrome released and pushable to Chrome between releases. http://crbug.com/596555
 
@@ -9,42 +9,61 @@ Rendered version of this file: https://chromium.googlesource.com/chromium/src/+/
 
 
 ## Procedure for adding a new type
-  * Edit `download_file_types.asciipb`. Update `histograms.xml`
+  * Edit `download_file_types.asciipb` and update `histograms.xml`
   * Get it reviewed, submit.
   * Push via component update (PROCEDURE TBD)
 
 ## Guidelines for a DownloadFileType entry:
 See `download_file_types.proto` for all fields.
 
-  * `extension`: Value must be unique within the config. It should be
-    lowercase ASCII and not contain a dot.  If there _is_ a duplicate,
-    first one wins.  Only the `default_file_type` should leave this unset.
+  * `extension`: (required) Value must be unique within the config. It should be
+    lowercase ASCII and not contain a dot. If there _is_ a duplicate,
+    first one wins. Only the `default_file_type` should leave this unset.
 
-  * `uma_value`: Value must be unique and match one in the
+  * `uma_value`: (required) must be unique and match one in the
     `SBClientDownloadExtensions` enum in `histograms.xml`.
 
   * `is_archive`: `True` if this filetype is a container for other files.
      Leave it unset for `false`.
 
-  * `platform_settings`: (repeated) Must have one entry with an unset
-     `platform` field, and optionally additional entries with overrides
-     for one or more platforms.  An unset `platform` field acts as a
-     default for any platforms that don't have an override.  There should
-     not be two settings with the same `platform`, but if there are,
-     first one wins.  Keep them sorted by platform.
+  * `ping_setting`:  (required). This controls what sort of ping is sent
+     to Safe Browsing and if a verdict is checked before the user can
+     access the file.
+
+    * `SAMPLED_PING`: Don't send a full Safe Browsing ping, but
+       send a no-PII "light-ping" for a random sample of SBER users.
+       This should be the default for unknown types. The verdict won't
+       be used.
+    * `NO_PING`:  Don’t send any pings. This file is whitelisted. All
+      NOT_DANGEROUS files should normally use this.
+    * `FULL_PING`: Send full pings and use the verdict. All dangerous
+      file should use this.
+
+  * `platform_settings`: (repeated) Zero or more settings to differentiate
+     behavior by platform. Keep them sorted by platform. At build time,
+     this list will be filtered to contain exactly one setting by chosing
+     as follows before writing out the binary proto.
+
+       1. If there's an entry matching the built platform,
+         that will be preferred. Otherwise,
+
+       2. If there's a "PLATFORM_ANY" (i.e. `platform` is not set),
+       that will be used. Otherwise,
+
+       3. The `default_file_type`'s settings will be filled in.
 
   * `platform_settings.danger_level`: (required)
     * `NOT_DANGEROUS`: Safe to download and open, even if the download
        was accidental.
     * `DANGEROUS`: Always warn the user that this file may harm their
-      computer.  We let them continue or discard the file.  If Safe
+      computer. We let them continue or discard the file. If Safe
       Browsing returns a SAFE verdict, we still warn the user.
     * `ALLOW_ON_USER_GESTURE`: Warn the user normally but skip the warning
       if there was a user gesture or the user visited this site before
-      midnight last night (i.e. is a repeat visit).  If Safe Browsing
+      midnight last night (i.e. is a repeat visit). If Safe Browsing
       returns a SAFE verdict for this file, it won't show a warning.
 
-  * `platform_settings.auto_open_hint`: Required.
+  * `platform_settings.auto_open_hint`: (required).
     * `ALLOW_AUTO_OPEN`: File type can be opened automatically if the user
       selected that option from the download tray on a previous download
       of this type.
@@ -54,29 +73,17 @@ See `download_file_types.proto` for all fields.
       configuration of the system to cause harmful behavior immediately
       or at some time in the future. We *do* allow auto-open for files
       that upon opening sufficiently warn the user about the fact that it
-      was downloaded from the internet and can do damage.  **Note**:
+      was downloaded from the internet and can do damage. **Note**:
       Some file types (e.g.: .local and .manifest) aren't dangerous
-      to open.  However, their presence on the file system may cause
+      to open. However, their presence on the file system may cause
       potentially dangerous changes in behavior for other programs. We
       allow automatically opening these file types, but always warn when
       they are downloaded.
 
-  * `platform_settings.ping_setting`:  Required.  This controls what sort
-     of ping is sent to Safe Browsing and if a verdict is checked before
-     the user can access the file.
-    * `SAMPLED_PING`: Don't send a full Safe Browsing ping, but
-       send a no-PII "light-ping" for a random sample of SBER users.
-       This should be the default for unknown types.  The verdict won't
-       be used.
-    * `NO_PING`:  Don’t send any pings.  This file is whitelisted. All
-      NOT_DANGEROUS files should normally use this.
-    * `FULL_PING`: Send full pings and use the verdict. All dangerous
-      file should use this.
-
   * TODO(nparker): Support this: `platform_settings.unpacker`:
      optional. Specifies which archive unpacker internal to Chrome
-     should be used.  If potentially dangerous file types are found,
-     Chrome will send a full-ping for the entire file.  Otherwise, it'll
+     should be used. If potentially dangerous file types are found,
+     Chrome will send a full-ping for the entire file. Otherwise, it'll
      follow the ping settings. Can be one of UNPACKER_ZIP or UNPACKER_DMG.
 
 ## Guidelines for the top level DownloadFileTypeConfig entry:
@@ -87,10 +94,11 @@ See `download_file_types.proto` for all fields.
     users' downloads with unknown extensions (or
     ping_setting=SAMPLED_PING) should we send light-pings? [0.0 .. 1.0]
 
-  * `file_type`: The big list of all known file types. Keep them
+  * `file_types`: The big list of all known file types. Keep them
      sorted by extension.
 
   * `default_file_type`: Settings used if a downloaded file is not in
-    the above list.  `extension` is ignored, but other settings are used.
-    The ping_setting should be SAMPLED_PING for all platforms.
+    the above list. `extension` is ignored, but other settings are used.
+    The ping_setting should be SAMPLED_PING for all platforms. Only the
+    first platform_setting is used.