From 579b162965eb326d289a8bb462a01042c676d1c2 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 10:52:42 -0400 Subject: [PATCH 01/13] DOCSP-31694: SOCKS5 proxy support --- .../connection/connection-options.txt | 35 +++-- source/fundamentals/connection/socks.txt | 123 ++++++++++++++++++ 2 files changed, 140 insertions(+), 18 deletions(-) create mode 100644 source/fundamentals/connection/socks.txt diff --git a/source/fundamentals/connection/connection-options.txt b/source/fundamentals/connection/connection-options.txt index e487c9ba3..e8758a661 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/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 `. 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 - ` that the driver should use if a credential + ` 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 `__ - 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,7 +248,7 @@ 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`` @@ -257,7 +256,7 @@ parameters of the connection URI to specify the behavior of the client. * - **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 `__ - the driver retrieves to construct your + the driver retrieves to construct your :manual:`seed list `. - You must use the + You must use the :manual:`DNS Seed List Connection Format ` in your :ref:`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. diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt new file mode 100644 index 000000000..8e97a4645 --- /dev/null +++ b/source/fundamentals/connection/socks.txt @@ -0,0 +1,123 @@ +.. _java-connect-socks: + +=========================== +Enable SOCKS5 Proxy Support +=========================== + +.. 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 Wikipedia entry on + :wikipedia:`SOCKS `. + +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 URI. + +The following table describes the SOCKS5 client options: + +.. list-table:: + :header-rows: 1 + :widths: 15 20 10 55 + + * - Name + - Accepted Values + - Default Value + - Description + + * - **proxyHost** + - String + - ``null`` + - *Required*. Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. + + * - **proxyPort** + - non-negative Integer + - ``null`` + - Specifies the TCP port number of the SOCKS5 proxy server. If you + set the ``proxyHost`` option, the value of this option defaults + to ``1080``. + + * - **proxyUsername** + - String + - ``null`` + - Specifies the username for authentication to the SOCKS5 + proxy server. The driver ignores ``null`` and empty string values for + this setting. + + * - **proxyPassword** + - String + - ``null`` + - Specifies the password for authentication to the SOCKS5 + proxy server. The driver ignores ``null`` and empty string values + for this setting. + + +Example +------- + +This example shows how to instantiate a ``MongoClient`` that connects to +MongoDB by using a SOCKS5 proxy. It uses the placeholder values described in +the previous section: + +.. code-block:: java + :emphasize-lines: 4-11 + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .applyToSocketSettings(builder -> + builder.applyToProxySettings(proxyBuilder -> + proxyBuilder + .host("") + .port() + .username("") + .password("") + ) + ).build()); + + +.. important:: + + The driver throws an exception if you set the ``proxyPort``, + ``proxyUsername``, or ``proxyPassword`` options without setting the + ``proxyHost`` option. + +Alternatively, you can specify the proxy settings in your connection string. +The following code example shows how to include your SOCKS5 proxy settings +in a connection string and instantiate a ``MongoClient`` from it. + +.. code-block:: java + :emphasize-lines: 2-5 + + String connectionString = "mongodb+srv://myDatabaseUser:myPassword@example.org/" + + "?proxyHost=proxy.example1.org" + + "&proxyPort=12345" + + "&proxyUsername="myProxyUsername" + + "&proxyPassword="myProxyPassword"; + + MongoClient mongoClient = MongoClients.create(connectionString); + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods and types discussed in this guide, see the +following API documentation: + + +.. TODO + From 5b8762471fd961d5927658f99a6521ec6353eb58 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 10:59:45 -0400 Subject: [PATCH 02/13] add to ToC --- source/fundamentals/connection.txt | 4 +++- source/fundamentals/connection/socks.txt | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index a041f4f56..6f398ba7d 100644 --- a/source/fundamentals/connection.txt +++ b/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 @@ -32,7 +33,8 @@ sections: - :ref:`Specify Connection Behavior with the MongoClient Class ` - :ref:`Enable Network Compression ` - :ref:`Enable TLS/SSL on a Connection ` -- :ref:`Connect to MongoDB Using a JNDI Datasource ` +- :ref:`Connect to MongoDB by Using a SOCKS5 Proxy ` +- :ref:`Connect to MongoDB by Using a JNDI Datasource ` - :atlas:`Connect to MongoDB Atlas from AWS Lambda ` For information about authenticating with a MongoDB instance, diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 8e97a4645..55dbfca32 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -1,8 +1,8 @@ .. _java-connect-socks: -=========================== -Enable SOCKS5 Proxy Support -=========================== +========================================== +Connect to MongoDB by Using a SOCKS5 Proxy +========================================== .. contents:: On this page :local: From ecd8f1245c80311348cda20f0ddb9ef367ba1e50 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 11:06:46 -0400 Subject: [PATCH 03/13] JNDI page title fix and vale fixes --- source/fundamentals/connection/jndi.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/connection/jndi.txt b/source/fundamentals/connection/jndi.txt index 43d53f142..8f1d9d5af 100644 --- a/source/fundamentals/connection/jndi.txt +++ b/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. - 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:: From 8318bc1271ea36091a7ea1c68051572637bf8811 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 11:20:25 -0400 Subject: [PATCH 04/13] split examples into separate sections --- source/fundamentals/connection/socks.txt | 36 +++++++++++++----------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 55dbfca32..f89b56b31 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -22,6 +22,8 @@ through a proxy server. To learn more about the SOCKS5 protocol, see the Wikipedia entry on :wikipedia:`SOCKS `. +.. _socks-proxy-settings: + SOCKS5 Proxy Settings --------------------- @@ -67,12 +69,20 @@ The following table describes the SOCKS5 client options: for this setting. -Example -------- +Examples +-------- + +The following examples show how to instantiate a ``MongoClient`` that connects +to MongoDB by using a SOCKS5 proxy by using 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This example shows how to instantiate a ``MongoClient`` that connects to -MongoDB by using a SOCKS5 proxy. It uses the placeholder values described in -the previous section: +The following code example shows how to specify your SOCKS5 proxy settings by +using the ``MongoClientSettings`` builder: .. code-block:: java :emphasize-lines: 4-11 @@ -90,16 +100,11 @@ the previous section: ) ).build()); +Specify Proxy Settings in the Connection String +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. important:: - - The driver throws an exception if you set the ``proxyPort``, - ``proxyUsername``, or ``proxyPassword`` options without setting the - ``proxyHost`` option. - -Alternatively, you can specify the proxy settings in your connection string. -The following code example shows how to include your SOCKS5 proxy settings -in a connection string and instantiate a ``MongoClient`` from it. +This following code example shows how to specify your SOCKS5 proxy settings in +your connection string: .. code-block:: java :emphasize-lines: 2-5 @@ -115,9 +120,8 @@ in a connection string and instantiate a ``MongoClient`` from it. API Documentation ~~~~~~~~~~~~~~~~~ -To learn more about the methods and types discussed in this guide, see the +To learn more about the methods and types discussed in this guide, see the following API documentation: - .. TODO From 85f082da26a42d572bd911c4e5f6166a5d0db1a1 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 11:25:24 -0400 Subject: [PATCH 05/13] remove default value column, add connection string placeholders --- source/fundamentals/connection/socks.txt | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index f89b56b31..270d5c37d 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -35,35 +35,30 @@ The following table describes the SOCKS5 client options: .. list-table:: :header-rows: 1 - :widths: 15 20 10 55 + :widths: 15 20 65 * - Name - Accepted Values - - Default Value - Description * - **proxyHost** - String - - ``null`` - *Required*. Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. * - **proxyPort** - non-negative Integer - - ``null`` - Specifies the TCP port number of the SOCKS5 proxy server. If you set the ``proxyHost`` option, the value of this option defaults to ``1080``. * - **proxyUsername** - String - - ``null`` - Specifies the username for authentication to the SOCKS5 proxy server. The driver ignores ``null`` and empty string values for this setting. * - **proxyPassword** - String - - ``null`` - Specifies the password for authentication to the SOCKS5 proxy server. The driver ignores ``null`` and empty string values for this setting. @@ -110,10 +105,10 @@ your connection string: :emphasize-lines: 2-5 String connectionString = "mongodb+srv://myDatabaseUser:myPassword@example.org/" + - "?proxyHost=proxy.example1.org" + - "&proxyPort=12345" + - "&proxyUsername="myProxyUsername" + - "&proxyPassword="myProxyPassword"; + "?proxyHost=" + + "&proxyPort=" + + "&proxyUsername="" + + "&proxyPassword=""; MongoClient mongoClient = MongoClients.create(connectionString); From 5201d0531d92e2ab5704825642471b04b8ea4bb9 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 11:42:14 -0400 Subject: [PATCH 06/13] fix placeholder --- source/fundamentals/connection/socks.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 270d5c37d..8127cd7ae 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -84,7 +84,7 @@ using the ``MongoClientSettings`` builder: MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() - .applyConnectionString(new ConnectionString("")) + .applyConnectionString(new ConnectionString("mongodb+srv://myDatabaseUser:myPassword@example.org/")) .applyToSocketSettings(builder -> builder.applyToProxySettings(proxyBuilder -> proxyBuilder @@ -107,8 +107,8 @@ your connection string: String connectionString = "mongodb+srv://myDatabaseUser:myPassword@example.org/" + "?proxyHost=" + "&proxyPort=" + - "&proxyUsername="" + - "&proxyPassword=""; + "&proxyUsername=" + + "&proxyPassword="; MongoClient mongoClient = MongoClients.create(connectionString); @@ -118,5 +118,8 @@ API Documentation To learn more about the methods and types discussed in this guide, see the following API documentation: +- `MongoClientSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoClients.create() <{+api+}/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`__ + .. TODO From 0c5fc6c27e6ad55bde464d730f54ce45e3c9317b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Sep 2023 16:32:39 -0400 Subject: [PATCH 07/13] add redirect and API docs links --- config/redirects | 1 + source/fundamentals/connection/socks.txt | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/config/redirects b/config/redirects index 18ccb714a..a3893739e 100644 --- a/config/redirects +++ b/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}/ diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 8127cd7ae..f679fcf51 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -76,7 +76,7 @@ proxy settings. Specify Proxy Settings in the MongoClientSettings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following code example shows how to specify your SOCKS5 proxy settings by +The following code example shows how to specify your SOCKS5 proxy settings by using the ``MongoClientSettings`` builder: .. code-block:: java @@ -98,7 +98,7 @@ using the ``MongoClientSettings`` builder: Specify Proxy Settings in the Connection String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This following code example shows how to specify your SOCKS5 proxy settings in +This following code example shows how to specify your SOCKS5 proxy settings in your connection string: .. code-block:: java @@ -119,7 +119,8 @@ To learn more about the methods and types discussed in this guide, see the following API documentation: - `MongoClientSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `SocketSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/connection/SocketSettings.Builder.html>`__ - `MongoClients.create() <{+api+}/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 From efdf2abe1591b3aa99a7f527429b26bca80e8e1f Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 18 Sep 2023 14:20:47 -0400 Subject: [PATCH 08/13] fix api docs links --- source/fundamentals/connection/socks.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index f679fcf51..0172e6f5e 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -118,9 +118,9 @@ API Documentation To learn more about the methods and types discussed in this guide, see the following API documentation: -- `MongoClientSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ -- `SocketSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/connection/SocketSettings.Builder.html>`__ -- `MongoClients.create() <{+api+}/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`__ +- `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 From 924b69912c2261f6152f2d19c6447a2a942e8a3d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 19 Sep 2023 11:00:30 -0400 Subject: [PATCH 09/13] PRR fixes --- source/fundamentals/connection/socks.txt | 41 ++++++++++++------------ 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 0172e6f5e..e57630112 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -29,7 +29,7 @@ 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 URI. +``MongoClientSettings`` or in your connection string. The following table describes the SOCKS5 client options: @@ -68,10 +68,10 @@ Examples -------- The following examples show how to instantiate a ``MongoClient`` that connects -to MongoDB by using a SOCKS5 proxy by using 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. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,25 +80,26 @@ The following code example shows how to specify your SOCKS5 proxy settings by using the ``MongoClientSettings`` builder: .. code-block:: java - :emphasize-lines: 4-11 - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder() - .applyConnectionString(new ConnectionString("mongodb+srv://myDatabaseUser:myPassword@example.org/")) - .applyToSocketSettings(builder -> - builder.applyToProxySettings(proxyBuilder -> - proxyBuilder - .host("") - .port() - .username("") - .password("") - ) - ).build()); + :emphasize-lines: 5-12 + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyConnectionString( + new ConnectionString("mongodb+srv://myDatabaseUser:myPassword@example.org/")) + .applyToSocketSettings(builder -> + builder.applyToProxySettings(proxyBuilder -> + proxyBuilder + .host("") + .port() + .username("") + .password("") + ) + ).build()); Specify Proxy Settings in the Connection String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This following code example shows how to specify your SOCKS5 proxy settings in +The following code example shows how to specify your SOCKS5 proxy settings in your connection string: .. code-block:: java From 5bf94fff7b0e6049590ebc9d3f46a68ed34450d5 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 19 Sep 2023 11:07:30 -0400 Subject: [PATCH 10/13] additional edits --- source/fundamentals/connection/socks.txt | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index e57630112..50846bb9c 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -43,25 +43,23 @@ The following table describes the SOCKS5 client options: * - **proxyHost** - String - - *Required*. Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. + - 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. If you - set the ``proxyHost`` option, the value of this option defaults - to ``1080``. + - 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. + - Specifies the username for authentication to the SOCKS5 proxy server. + The driver ignores ``null`` and empty string values for this setting. * - **proxyPassword** - String - - Specifies the password for authentication to the SOCKS5 - proxy server. The driver ignores ``null`` and empty string values - for this setting. + - Specifies the password for authentication to the SOCKS5 proxy server. + The driver ignores ``null`` and empty string values for this setting. Examples From 3889dbe50039f9c831a266c422af921437d7e3fd Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 22 Sep 2023 16:47:16 -0400 Subject: [PATCH 11/13] PRR fixes --- source/fundamentals/connection/socks.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 50846bb9c..272ac3e00 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -55,11 +55,15 @@ The following table describes the SOCKS5 client options: - 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 From 33845eac7cc321e7282bf95967ef0825d8b9afeb Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Sat, 23 Sep 2023 13:25:06 -0400 Subject: [PATCH 12/13] SocketStreamFactory callout --- source/fundamentals/connection/socks.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 272ac3e00..36fcc39dc 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -31,6 +31,12 @@ 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:: @@ -126,4 +132,5 @@ following API documentation: - `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 + - provide the link for the proxysettings builder once the API docs are generated. Should resemble: + - `ProxySettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ProxySettings.Builder.html>`__ From 3f97f98ccdf6cb67623dc37c21be44d434e3b67e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Sat, 23 Sep 2023 13:33:15 -0400 Subject: [PATCH 13/13] vale fixes --- source/fundamentals/connection/socks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt index 36fcc39dc..c5d0d900c 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/fundamentals/connection/socks.txt @@ -132,5 +132,5 @@ following API documentation: - `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. Should resemble: + - 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>`__