DOCSP-31694: SOCKS5 proxy support (mongodb#439)

* DOCSP-31694: SOCKS5 proxy support

Author: Chris Cho

config/redirects

@@ -9,3 +9,4 @@ raw: ${prefix}/master -> ${base}/upcoming/
 [*-v4.6]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/fundamentals/crud/read-operations/retrieve/
 [*-master]: ${prefix}/${version}/fundamentals/csfle/ -> ${base}/${version}/fundamentals/encrypt-fields/
 [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/
+[*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/

source/fundamentals/connection.txt

@@ -11,6 +11,7 @@ Connection Guide
    /fundamentals/connection/mongoclientsettings
    /fundamentals/connection/network-compression
    /fundamentals/connection/tls
+   /fundamentals/connection/socks
    /fundamentals/connection/jndi
    Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
 
@@ -32,7 +33,8 @@ sections:
 - :ref:`Specify Connection Behavior with the MongoClient Class <specify-mongoclient-settings>`
 - :ref:`Enable Network Compression <network-compression>`
 - :ref:`Enable TLS/SSL on a Connection <tls-ssl>`
-- :ref:`Connect to MongoDB Using a JNDI Datasource <jndi>`
+- :ref:`Connect to MongoDB by Using a SOCKS5 Proxy <java-connect-socks>`
+- :ref:`Connect to MongoDB by Using a JNDI Datasource <jndi>`
 - :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
 
 For information about authenticating with a MongoDB instance,

source/fundamentals/connection/connection-options.txt

@@ -72,21 +72,21 @@ parameters of the connection URI to specify the behavior of the client.
 
    * - **ssl**
      - boolean
-     - Specifies that all communication with MongoDB instances should
+     - Specifies that all communication with MongoDB instances must 
        use TLS/SSL. Superseded by the **tls** option.
 
        | **Default**: ``false``
 
    * - **tls**
      - boolean
-     - Specifies that all communication with MongoDB instances should
+     - Specifies that all communication with MongoDB instances must 
        use TLS. Supersedes the **ssl** option.
 
        | **Default**: ``false``
 
    * - **tlsInsecure**
      - boolean
-     - Specifies that the driver should allow invalid hostnames for TLS
+     - Specifies that the driver must allow invalid hostnames for TLS
        connections. Has the same effect as setting
        **tlsAllowInvalidHostnames** to ``true``. To configure TLS security
        constraints in other ways, use a
@@ -96,7 +96,7 @@ parameters of the connection URI to specify the behavior of the client.
 
    * - **tlsAllowInvalidHostnames**
      - boolean
-     - Specifies that the driver should allow invalid hostnames in the
+     - Specifies that the driver must allow invalid hostnames in the
        certificate for TLS connections. Supersedes
        **sslInvalidHostNameAllowed**.
 
@@ -186,14 +186,14 @@ parameters of the connection URI to specify the behavior of the client.
        is greater. For more information, see the server documentation for the
        :manual:`maxStalenessSeconds option </reference/connection-string/#urioption.maxStalenessSeconds>`.
        Not providing a parameter or explicitly specifying ``-1`` indicates
-       that there should be no staleness check for secondaries.
+       that there must be no staleness check for secondaries.
 
        | **Default**: ``-1``
 
    * - **authMechanism**
      - string
      - Specifies the :doc:`authentication mechanism
-       </fundamentals/auth>` that the driver should use if a credential
+       </fundamentals/auth>` that the driver uses if a credential
        was supplied.
 
        | **Default**: By default, the client picks the most secure
@@ -204,9 +204,8 @@ parameters of the connection URI to specify the behavior of the client.
 
    * - **authSource**
      - string
-     - Specifies the database that the supplied credentials should be
-       validated against. 
-       
+     - Specifies the database in which the supplied credentials are validated. 
+
        | **Default**: ``admin``
 
    * - **authMechanismProperties**
@@ -239,7 +238,7 @@ parameters of the connection URI to specify the behavior of the client.
    * - **zlibCompressionLevel**
      - integer
      - Specifies the degree of compression that `Zlib <https://zlib.net/>`__
-       should use to decrease the size of requests to the connected MongoDB
+       uses to decrease the size of requests to the connected MongoDB
        instance. The level can range from ``-1`` to ``9``, with lower values
        compressing faster (but resulting in larger requests) and larger values
        compressing slower (but resulting in smaller requests).
@@ -249,15 +248,15 @@ parameters of the connection URI to specify the behavior of the client.
    * - **retryWrites**
      - boolean
      - Specifies that the driver must retry supported write operations
-       if they fail due to a network error.
+       if they are unable to complete due to a network error.
 
        | **Default**: ``true``
 
 
    * - **retryReads**
      - boolean
      - Specifies that the driver must retry supported read operations
-       if they fail due to a network error.
+       if they are unable to complete due to a network error.
 
        | **Default**: ``true``
 
@@ -280,23 +279,23 @@ parameters of the connection URI to specify the behavior of the client.
      - integer
      - Specifies the maximum number of connections a pool may be establishing
        concurrently.
-       
+
        | **Default**: ``2``
 
    * - **srvServiceName**
      - string
      - Specifies the service name of the
        `SRV resource records <https://www.rfc-editor.org/rfc/rfc2782>`__
-       the driver retrieves to construct your 
+       the driver retrieves to construct your
        :manual:`seed list </reference/glossary/#std-term-seed-list>`.
-       You must use the 
+       You must use the
        :manual:`DNS Seed List Connection Format </reference/connection-string/#dns-seed-list-connection-format>`
        in your
        :ref:`connection URI <connection-uri>`
-       to use this option. 
-       
+       to use this option.
+
        | **Default**: ``mongodb``
 
 For a complete list of options, see the
 `ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
-API reference page.
+API documentation.

source/fundamentals/connection/jndi.txt

@@ -1,8 +1,8 @@
 .. _jndi:
 
-==========================================
-Connect to MongoDB Using a JNDI Datasource
-==========================================
+=============================================
+Connect to MongoDB by Using a JNDI Datasource
+=============================================
 
 .. contents:: On this page
    :local:
@@ -15,7 +15,7 @@ Overview
 --------
 
 In this guide, you can learn how to connect the MongoDB Java driver
-to your MongoDB instance using a Java Naming and Directory Interface
+to your MongoDB instance by using a Java Naming and Directory Interface
 (JNDI) Datasource.
 
 MongoClientFactory includes a `JNDI
@@ -61,7 +61,7 @@ JNDI Datasource.
             Replace the placeholder connection value in the ``property`` tag
             with a value that points to your MongoDB installation.
 
-      This makes a MongoClient instance accessible via the JNDI name
+      This makes a MongoClient instance discoverable through the JNDI name
       ``MyMongoClient`` in the ``java:global`` context.
 
    .. tab:: Tomcat
@@ -106,7 +106,7 @@ JNDI Datasource.
               </res-auth>
             </resource-ref>
 
-      This makes a ``MongoClient`` instance accessible via the JNDI name
+      This makes a ``MongoClient`` instance discoverable through the JNDI name
       ``mongodb/MyMongoClient`` in the ``java:comp/env`` context.
 
 .. seealso::

source/fundamentals/connection/socks.txt

@@ -0,0 +1,136 @@
+.. _java-connect-socks:
+
+==========================================
+Connect to MongoDB by Using a SOCKS5 Proxy
+==========================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to connect to MongoDB by using a SOCKS5 proxy.
+SOCKS5 is a standardized protocol for communicating with network services
+through a proxy server.
+
+.. tip::
+
+   To learn more about the SOCKS5 protocol, see the Uncyclopedia entry on
+   :wikipedia:`SOCKS <w/index.php?title=SOCKS&oldid=1160087146>`.
+
+.. _socks-proxy-settings:
+
+SOCKS5 Proxy Settings
+---------------------
+
+The proxy settings specify the SOCKS5 proxy server address and your
+authentication credentials. You can specify your settings in an instance of
+``MongoClientSettings`` or in your connection string.
+
+.. important::
+
+   The driver ignores the proxy settings if you specify a custom
+   ``StreamFactoryFactory``, which by default creates instances of
+   ``SocketStreamFactory``.
+
+The following table describes the SOCKS5 client options:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 20 65
+
+   * - Name
+     - Accepted Values
+     - Description
+
+   * - **proxyHost**
+     - String
+     - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname.
+       You must provide this value to connect to a SOCKS5 proxy.
+
+   * - **proxyPort**
+     - non-negative Integer
+     - Specifies the TCP port number of the SOCKS5 proxy server. This option
+       defaults to ``1080`` when you set ``proxyHost``.
+
+   * - **proxyUsername**
+     - String
+     - Specifies the username for authentication to the SOCKS5 proxy server.
+       The driver ignores ``null`` and empty string values for this setting.
+       The driver requires that you pass values for both ``proxyUsername``
+       and ``proxyPassword`` or that you omit both values.
+
+   * - **proxyPassword**
+     - String
+     - Specifies the password for authentication to the SOCKS5 proxy server.
+       The driver ignores ``null`` and empty string values for this setting.
+       The driver requires that you pass values for both ``proxyUsername``
+       and ``proxyPassword`` or that you omit both values.
+
+
+Examples
+--------
+
+The following examples show how to instantiate a ``MongoClient`` that connects
+to MongoDB by using a SOCKS5 proxy. The proxy settings can be specified in a
+``MongoClientSettings`` instance or a connection string. These examples use
+the placeholder values described in the :ref:`socks-proxy-settings` section.
+Replace the placeholders with your proxy settings.
+
+Specify Proxy Settings in the MongoClientSettings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code example shows how to specify your SOCKS5 proxy settings by
+using the ``MongoClientSettings`` builder:
+
+.. code-block:: java
+   :emphasize-lines: 5-12
+
+   MongoClient mongoClient = MongoClients.create(
+       MongoClientSettings.builder()
+           .applyConnectionString(
+                   new ConnectionString("mongodb+srv://myDatabaseUser:[email protected]/"))
+           .applyToSocketSettings(builder ->
+                   builder.applyToProxySettings(proxyBuilder ->
+                           proxyBuilder
+                               .host("<proxyHost>")
+                               .port(<proxyPort>)
+                               .username("<proxyUsername>")
+                               .password("<proxyPassword>")
+                           )
+           ).build());
+
+Specify Proxy Settings in the Connection String
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code example shows how to specify your SOCKS5 proxy settings in
+your connection string:
+
+.. code-block:: java
+   :emphasize-lines: 2-5
+
+   String connectionString = "mongodb+srv://myDatabaseUser:[email protected]/" +
+           "?proxyHost=<proxyHost>" +
+           "&proxyPort=<proxyPort>" +
+           "&proxyUsername=<proxyUsername>" +
+           "&proxyPassword=<proxyPassword>";
+
+   MongoClient mongoClient = MongoClients.create(connectionString);
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types discussed in this guide, see the
+following API documentation:
+
+- `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
+- `SocketSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SocketSettings.Builder.html>`__
+- `MongoClients.create() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`__
+
+.. TODO
+   - provide the link for the proxysettings builder once the API docs are generated:
+   - `ProxySettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ProxySettings.Builder.html>`__