Documentation fix for Manage Downloads feature (SeleniumHQ#1351)

Updated the documentation to reflect the current 
Capabilities of “auto manage downloads” feature.

[deploy site]

Author: krmahadevan

website_and_docs/content/documentation/grid/configuration/cli_options.en.md

@@ -224,7 +224,7 @@ pull request updating this page.
 | `--drain-after-session-count`| int | `1` | Drain and shutdown the Node after X sessions have been executed. Useful for environments like Kubernetes. A value higher than zero enables this feature. |
 | `--hub`| string | `http://localhost:4444` | The address of the Hub in a Hub-and-Node configuration. Can be a hostname or IP address (`hostname`), in which case the Hub will be assumed to be `http://hostname:4444`, the `--grid-url` will be the same `--publish-events` will be `tcp://hostname:4442` and `--subscribe-events` will be `tcp://hostname:4443`. If `hostname` contains a port number, that will be used for `--grid-url` but the URIs for the event bus will remain the same. Any of these default values may be overridden but setting the correct flags. If the hostname has  a protocol (such as `https`) that will be used too. |
 | `--enable-cdp`| boolean | `true` | Enable CDP proxying in Grid. A Grid admin can disable CDP if the network doesnot allow websockets. True by default. |
-| `--downloads-path`| string | `/usr/downloads` | The default location wherein all browser triggered file downloads would be available to be retrieved from. This is usually the directory that you configure in your browser as the default location for storing downloaded files. |
+| `--enable-managed-downloads`| boolean | `false` | This causes the Node to auto manage files downloaded for a given session on the Node. |
 | `--selenium-manager`| boolean | `false` | When drivers are not available on the current system, use Selenium Manager. False by default. |
 
 ### Relay
@@ -352,101 +352,241 @@ driver.quit();
 
 Set the custom capability to `false` in order to match the Node B.
 
-#### Specifying path from where downloaded files can be retrieved
+#### Enabling Managed downloads by the Node
 
-At times a test may need to access files that were downloaded by it on the Node. To retrieve 
-such files, following can be done.
+At times a test may need to access files that were downloaded by it on the Node. 
+To retrieve such files, following can be done.
 
 ##### Start the Hub
 ```
 java -jar selenium-server-<version>.jar hub
 ```
 
-##### Start the Node with downloads path specified
+##### Start the Node with manage downloads enabled
 ```
-java -jar selenium-server-<version>.jar node --downloads-path /usr/downloads
+java -jar selenium-server-<version>.jar node --enable-managed-downloads true
 ```
-##### Important information when dowloading a file:
+##### Set the capability at the test level
 
-* The endpoint to `GET` from is `/session/<sessionId>/se/file?filename=`
+Tests that want to use this feature should set the capability `"se:downloadsEnabled"`to `true` 
+
+```java
+options.setCapability("se:downloadsEnabled", true);
+```
+
+##### How does this work
+
+* The Grid infrastructure will try to match a session request with `"se:downloadsEnabled"` against ONLY those nodes which were started with `--enable-managed-downloads true`
+* If a session is matched, then the Node automatically sets the required capabilities to let the browser know, as to where should a file be downloaded. 
+* The Node now allows a user to: 
+    * List all the files that were downloaded for a specific session and 
+    * Retrieve a specific file from the list of files.
+* The directory into which files were downloaded for a specific session gets automatically cleaned up when the session ends (or) timesout due to inactivity.
+
+**Note: Currently this capability is ONLY supported on:** 
+
+* `Edge`
+* `Firefox` and
+* `Chrome` browser
+
+##### Listing files that can be downloaded for current session:
+
+* The endpoint to `GET` from is `/session/<sessionId>/se/files`.
+* The session needs to be active in order for the command to work.
+* The raw response looks like below:
+
+```json
+{
+  "value": {
+    "names": [
+      "Red-blue-green-channel.jpg"
+    ]
+  }
+}
+```
+
+In the response the list of file names appear under the key `names`.
+
+
+##### Dowloading a file:
+
+* The endpoint to `POST` from is `/session/<sessionId>/se/files` with a payload of the form `{"name": "fileNameGoesHere}`
 * The session needs to be active in order for the command to work.
+* The raw response looks like below:
+
+```json
+{
+	"value": {
+		"filename": "Red-blue-green-channel.jpg",
+		"contents": "Base64EncodedStringContentsOfDownloadedFileAsZipGoesHere"
+	}
+}
+```
+
 * The response blob contains two keys,
-    * `filename` - Same as what was specified in the request.
+    * `filename` - The file name that was downloaded.
     * `contents` - Base64 encoded zipped contents of the file.
 * The file contents are Base64 encoded and they need to be unzipped.
 
-##### Sample that retrieves the downloaded file
+##### List files that can be downloaded
+
+The below mentioned `curl` example can be used to list all the files that were downloaded by the current session in the Node, and which can be retrieved locally.
 
-Assuming the downloaded file is named `my_file.pdf`, and using `curl`, the 
+```bash
+curl -X GET "http://localhost:4444/session/90c0149a-2e75-424d-857a-e78734943d4c/se/files"
+```
+
+A sample response would look like below:
+
+```json
+{
+  "value": {
+    "names": [
+      "Red-blue-green-channel.jpg"
+    ]
+  }
+}
+```
+
+##### Retrieve a downloaded file
+
+Assuming the downloaded file is named `Red-blue-green-channel.jpg`, and using `curl`, the 
 file could be downloaded with the following command:
 
 ```bash
-curl -X GET "http://localhost:4444/session/<sessionId>/se/file?filename=my_file.pdf"
+curl -H "Accept: application/json" \
+-H "Content-Type: application/json; charset=utf-8" \
+-X POST -d '{"name":"Red-blue-green-channel.jpg"}' \
+"http://localhost:4444/session/18033434-fa4f-4d11-a7df-9e6d75920e19/se/files"
+```
+
+A sample response would look like below:
+
+```json
+{
+  "value": {
+    "filename": "Red-blue-green-channel.jpg",
+    "contents": "UEsDBBQACAgIAJpagVYAAAAAAAAAAAAAAAAaAAAAUmVkLWJsAAAAAAAAAAAAUmVkLWJsdWUtZ3JlZW4tY2hhbm5lbC5qcGdQSwUGAAAAAAEAAQBIAAAAcNkAAAAA"
+  }
+}
 ```
 
-Below is an example in Java that shows how to download a file named `my_file.pdf`.
+##### Complete sample code in Java
+
+Below is an example in Java that does the following:
+
+* Sets the capability to indicate that the test requires automatic managing of downloaded files. 
+* Triggers a file download via a browser.
+* Lists the files that are available for retrieval from the remote node (These are essentially files that were downloaded in the current session)
+* Picks one file and downloads the file from the remote node to the local machine.
 
 ```java
+import static java.util.Collections.singletonMap;
 import static org.openqa.selenium.remote.http.Contents.string;
 
 import java.io.File;
-import java.io.IOException;
+import java.lang.reflect.Type;
 import java.net.URL;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
 import org.openqa.selenium.By;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.firefox.FirefoxOptions;
 import org.openqa.selenium.io.Zip;
 import org.openqa.selenium.json.Json;
+import org.openqa.selenium.json.TypeToken;
 import org.openqa.selenium.remote.RemoteWebDriver;
+import org.openqa.selenium.remote.http.Contents;
 import org.openqa.selenium.remote.http.HttpClient;
 import org.openqa.selenium.remote.http.HttpMethod;
 import org.openqa.selenium.remote.http.HttpRequest;
 import org.openqa.selenium.remote.http.HttpResponse;
 
 public class DownloadsSample {
 
-  public static void main(String[] args) throws InterruptedException, IOException {
-    // Make sure the following directory exists on your machine
-    File dirToCopyTo = new File("/usr/downloads/file");
+  public static void main(String[] args) throws Exception {
     // Assuming the Grid is running locally.
     URL gridUrl = new URL("http://localhost:4444");
     RemoteWebDriver driver = new RemoteWebDriver(gridUrl, firefoxOptions());
-    // This public website resets the available files for dowload on a daily basis, 
-    // check the name of the file that will be downloaded and replace it below.
+    try {
+      demoFileDownloads(driver, gridUrl);
+    } finally {
+      driver.quit();
+    }
+  }
+
+  private static void demoFileDownloads(RemoteWebDriver driver, URL gridUrl) throws Exception {
+    // Make sure the following directory exists on your machine
+    File dirToCopyTo = new File("/usr/downloads/file");
     driver.get("http://the-internet.herokuapp.com/download");
     WebElement element = driver.findElement(By.cssSelector(".example a"));
     element.click();
 
-    // The download happens in a remote Node, which makes difficult to know when the file 
-    // has been completely downloaded. For demonstration purposes, this example uses a 
-    // 10 second sleep which should be enough time for a file to be downloaded. 
-    // We strongly recommend to avoid hardcoded sleeps, and ideally, to modify your 
-    // application under test so it offers a way to know when the file has been completely 
-    // downloaded. 
+    // The download happens in a remote Node, which makes it difficult to know when the file
+    // has been completely downloaded. For demonstration purposes, this example uses a
+    // 10-second sleep which should be enough time for a file to be downloaded.
+    // We strongly recommend to avoid hardcoded sleeps, and ideally, to modify your
+    // application under test so it offers a way to know when the file has been completely
+    // downloaded.
     TimeUnit.SECONDS.sleep(10);
 
-    HttpRequest request = new HttpRequest(HttpMethod.GET, String.format("/session/%s/se/file", driver.getSessionId()));
-    request.addQueryParameter("filename", "my_file.pdf");
+    //This is the endpoint which will provide us with list of files to download and also to
+    //let us download a specific file.
+    String uri = String.format("/session/%s/se/files", driver.getSessionId());
+
+    String fileToDownload = null;
+
     try (HttpClient client = HttpClient.Factory.createDefault().createClient(gridUrl)) {
+      // To list all files that are were downloaded on the remote node for the current session
+      // we trigger GET request.
+      HttpRequest request = new HttpRequest(HttpMethod.GET, uri);
       HttpResponse response = client.execute(request);
-      Map<String, Object> map = new Json().toType(string(response), Json.MAP_TYPE);
+      String text = string(response);
+      Type responseType = new TypeToken<Map<String, Map<String, List<String>>>>() {
+      }.getType();
+      Map<String, Map<String, List<String>>> map = new Json().toType(text, responseType);
+      Map<String, List<String>> parsedResponse = map.get("value");
+      for (String eachFile : parsedResponse.get("names")) {
+        if (fileToDownload == null) {
+          // Let's say there were "n" files downloaded for the current session, we would like
+          // to retrieve ONLY the first file.
+          fileToDownload = eachFile;
+        }
+      }
+    }
+    try (HttpClient client = HttpClient.Factory.createDefault().createClient(gridUrl)) {
+      // To retrieve a specific file from one or more files that were downloaded by the current session
+      // on a remote node, we use a POST request.
+
+      HttpRequest request = new HttpRequest(HttpMethod.POST, uri);
+      request.setContent(Contents.asJson(singletonMap("name", fileToDownload)));
+      HttpResponse response = client.execute(request);
+      String text = string(response);
+      Type responseType = new TypeToken<Map<String, Map<String, String>>>() {
+      }.getType();
+
+      Map<String, Map<String, String>> map = new Json().toType(text, responseType);
+      Map<String, String> parsedResponse = map.get("value");
       // The returned map would contain 2 keys,
       // filename - This represents the name of the file (same as what was provided by the test)
       // contents - Base64 encoded String which contains the zipped file.
-      String encodedContents = map.get("contents").toString();
+      String encodedContents = parsedResponse.get("contents");
 
       //The file contents would always be a zip file and has to be unzipped.
       Zip.unzip(encodedContents, dirToCopyTo);
-    } finally {
-      driver.quit();
+      System.out.println("The file which was "
+          + "downloaded in the node is now available in the directory: "
+          + dirToCopyTo.getAbsolutePath());
     }
   }
 
   private static FirefoxOptions firefoxOptions() {
     FirefoxOptions options = new FirefoxOptions();
-    // Options specific for Firefox to avoid prompting a dialog for downloads. They might 
+    // This capability tells the Grid, that this test should be routed ONLY to a node that can
+    // auto manage downloads.
+    options.setCapability("se:downloadsEnabled", true);
+    // Options specific for Firefox to avoid prompting a dialog for downloads. They might
     // change in the future, so please refer to the Firefox documentation for up to date details.
     options.addPreference("browser.download.manager.showWhenStarting", false);
     options.addPreference("browser.helperApps.neverAsk.saveToDisk",