Add network interception to .NET

This commit adds the ability of a user to intercept and manipulate
network traffic between the browser and the web site being automated. To
use this feature at present, the browser being automated must support
the Chromium DevTools Protocol, and the driver instance must implement
the IDevTools interface. Attempting to use these features will cause an
exception to be thrown at runtime if the driver is not capable of this
communication. To access this feature, use the following code:

    // Assume "driver" is a valid IWebDriver instance
    INetwork network = driver.Manage().Network;

    // Set up monitoring information by adding handlers
    // and subscribing to events.

    // Begin monitoring by starting the monitor.
    await network.StartMonitoring();

With this new functionality, users can do the following:
* Monitor HTTP requests and responses between browser and web server
* Add handlers to modify requests that meet user-defined criteria
* Add handlers to supply responses for requests that meet user-defined
  criteria
* Add handlers to supply authentication credentials for sites using
  basic and digest authentication

Author: jimevans

dotnet/src/support/Events/EventFiringWebDriver.cs

@@ -884,6 +884,11 @@ public ILogs Logs
                 get { return this.wrappedOptions.Logs; }
             }
 
+            public INetwork Network
+            {
+                get { return this.wrappedOptions.Network; }
+            }
+
             /// <summary>
             /// Provides access to the timeouts defined for this driver.
             /// </summary>

dotnet/src/webdriver/DevTools/HttpRequestData.cs renamed to dotnet/src/webdriver/HttpRequestData.cs

@@ -20,7 +20,7 @@
 using System.Collections.Generic;
 using System.Text;
 
-namespace OpenQA.Selenium.DevTools
+namespace OpenQA.Selenium
 {
     /// <summary>
     /// Represents the response data for an intercepted HTTP call.

dotnet/src/webdriver/DevTools/HttpResponseData.cs renamed to dotnet/src/webdriver/HttpResponseData.cs

@@ -21,7 +21,7 @@
 using System.Data.Common;
 using System.Text;
 
-namespace OpenQA.Selenium.DevTools
+namespace OpenQA.Selenium
 {
     /// <summary>
     /// Represents the response data for an intercepted HTTP call.

dotnet/src/webdriver/ICredentials.cs

@@ -0,0 +1,28 @@
+// <copyright file="ICredentials.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Marker interface describing a set of credentials to be used with network requests.
+    /// This allows the ability to expand beyond simple user name/password security mechanisms.
+    /// </summary>
+    public interface ICredentials
+    {
+    }
+}

dotnet/src/webdriver/INetwork.cs

@@ -0,0 +1,78 @@
+// <copyright file="INetwork.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Defines an interface allowing the user to manage network communication by the browser.
+    /// </summary>
+    public interface INetwork
+    {
+        /// <summary>
+        /// Occurs when a browser sends a network request.
+        /// </summary>
+        event EventHandler<NetworkRequestSentEventArgs> NetworkRequestSent;
+
+        /// <summary>
+        /// Occurs when a browser receives a network response.
+        /// </summary>
+        event EventHandler<NetworkResponseRecievedEventArgs> NetworkResponseReceived;
+
+        /// <summary>
+        /// Adds a <see cref="NetworkRequestHandler"/> to examine incoming network requests,
+        /// and optionally modify the request or provide a response. 
+        /// </summary>
+        /// <param name="handler">The <see cref="NetworkRequestHandler"/> to add.</param>
+        void AddRequestHandler(NetworkRequestHandler handler);
+
+        /// <summary>
+        /// Clears all added <see cref="NetworkRequestHandler"/> instances.
+        /// </summary>
+        void ClearRequestHandlers();
+
+        /// <summary>
+        /// Adds a <see cref="NetworkAuthenticationHandler"/> to supply authentication
+        /// credentials for network requests.
+        /// </summary>
+        /// <param name="handler">The <see cref="NetworkAuthenticationHandler"/> to add.</param>
+        void AddAuthenticationHandler(NetworkAuthenticationHandler handler);
+
+        /// <summary>
+        /// Clears all added <see cref="NetworkAuthenticationHandler"/> instances.
+        /// </summary>
+        void ClearAuthenticationHandlers();
+
+        /// <summary>
+        /// Asynchronously starts monitoring for network traffic.
+        /// </summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
+        Task StartMonitoring();
+
+        /// <summary>
+        /// Asynchronously stops monitoring for network traffic.
+        /// </summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
+        Task StopMonitoring();
+    }
+}

dotnet/src/webdriver/IOptions.cs

@@ -36,10 +36,15 @@ public interface IOptions
         IWindow Window { get; }
 
         /// <summary>
-        /// Gets an object allowing the user to examing the logs for this driver instance.
+        /// Gets an object allowing the user to examine the logs for this driver instance.
         /// </summary>
         ILogs Logs { get; }
 
+        /// <summary>
+        /// Gets an object allowing the user to manage network communication by the browser.
+        /// </summary>
+        INetwork Network { get; }
+
         /// <summary>
         /// Provides access to the timeouts defined for this driver.
         /// </summary>

dotnet/src/webdriver/NetworkAuthenticationHandler.cs

@@ -0,0 +1,40 @@
+// <copyright file="NetworkAuthenticationHandler.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Allows a user to supply authentication information for network requests.
+    /// </summary>
+    public class NetworkAuthenticationHandler
+    {
+        /// <summary>
+        /// Gets or sets a function that takes a <see cref="Uri"/> object, and returns a
+        /// value indicating whether the supplied URI matches the specified criteria.
+        /// </summary>
+        public Func<Uri, bool> UriMatcher { get; set; }
+
+        /// <summary>
+        /// Gets or sets the credentials to use when responding to an authentication request
+        /// that matches the specified criteria.
+        /// </summary>
+        public ICredentials Credentials { get; set; }
+    }
+}

dotnet/src/webdriver/NetworkRequestHandler.cs

@@ -0,0 +1,48 @@
+// <copyright file="NetworkRequestHandler.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Allows a user to handle a network request, potentially modifying the request or providing a known response.
+    /// </summary>
+    public class NetworkRequestHandler
+    {
+        /// <summary>
+        /// Gets or sets a function that evaluates request data in an <see cref="HttpRequestData"/> object,
+        /// and returns a value indicating whether the data matches the specified criteria.
+        /// </summary>
+        public Func<HttpRequestData, bool> RequestMatcher { get; set; }
+
+        /// <summary>
+        /// Gets or sets a function that accepts an <see cref="HttpRequestData"/> object describing a network
+        /// request to be sent, and returns a modified <see cref="HttpRequestData"/> object to use in the actual
+        /// network request.
+        /// </summary>
+        public Func<HttpRequestData, HttpRequestData> RequestTransformer { get; set; }
+
+        /// <summary>
+        /// Gets or sets a function that accepts an <see cref="HttpRequestData"/> object describing a network
+        /// request to be sent, and returns an <see cref="HttpResponseData"/> object as the response for the
+        /// request, bypassing the actual network request.
+        /// </summary>
+        public Func<HttpRequestData, HttpResponseData> ResponseSupplier { get; set; }
+    }
+}

dotnet/src/webdriver/NetworkRequestSentEventArgs.cs

@@ -0,0 +1,76 @@
+// <copyright file="NetworkRequestSentEventArgs.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Collections.Generic;
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Provides data for the NetworkRequestSent event of an object implementing the <see cref="INetwork"/> interface.
+    /// </summary>
+    public class NetworkRequestSentEventArgs : EventArgs
+    {
+        private readonly string requestId;
+        private readonly string requestUrl;
+        private readonly string requestMethod;
+        private readonly string requestPostData;
+        private readonly Dictionary<string, string> requestHeaders = new Dictionary<string, string>();
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NetworkRequestSentEventArgs"/> class.
+        /// </summary>
+        /// <param name="requestData">The <see cref="HttpRequestData"/> that describes the network request.</param>
+        public NetworkRequestSentEventArgs(HttpRequestData requestData)
+        {
+            this.requestId = requestData.RequestId;
+            this.requestUrl = requestData.Url;
+            this.requestMethod = requestData.Method;
+            this.requestPostData = requestData.PostData;
+            foreach (KeyValuePair<string, string> header in requestData.Headers)
+            {
+                this.requestHeaders[header.Key] = header.Value;
+            }
+        }
+
+        /// <summary>
+        /// Gets the internal request ID of the network request.
+        /// </summary>
+        public string RequestId => requestId;
+        
+        /// <summary>
+        /// Gets the URL of the network request.
+        /// </summary>
+        public string RequestUrl => requestUrl;
+
+        /// <summary>
+        /// Gets the HTTP method of the network request.
+        /// </summary>
+        public string RequestMethod => requestMethod;
+
+        /// <summary>
+        /// Gets the post data of the network request, if any.
+        /// </summary>
+        public string RequestPostData => requestPostData;
+
+        /// <summary>
+        /// Gets the collection of headers associated with the network request.
+        /// </summary>
+        public IReadOnlyDictionary<string, string> RequestHeaders => requestHeaders;
+    }
+}