Skip to content

Commit 02fdbba

Browse files
rustagirmongoKart
rustagir
authored and
mongoKart
committed
DOCSP-31621: socks dependency is optional (mongodb#748)
* DOCSP-31621: socks is optional * missed changes * first draft full * upgrade guide entry * CC PR fixes 1 * small fix * CC PR fixes 2
1 parent 30c0cbf commit 02fdbba

File tree

6 files changed

+166
-7
lines changed

6 files changed

+166
-7
lines changed

‎source/code-snippets/connection/socks.js

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { MongoClient } from "mongodb";
2+
3+
// start-socks
4+
const uri = "<connection string uri>";
5+
6+
const socksOptions = {
7+
proxyHost: "<host>",
8+
proxyPort: 1080,
9+
proxyUsername: "<username>",
10+
proxyPassword: "<password>",
11+
};
12+
13+
const client = new MongoClient(uri, socksOptions);
14+
// end-socks
15+
16+
async function run() {
17+
try {
18+
const db = client.db("myDB");
19+
const myColl = db.collection("myColl");
20+
const doc = await myColl.findOne({});
21+
console.log(doc);
22+
} finally {
23+
await client.close();
24+
}
25+
}
26+
run().catch(console.dir);

‎source/fundamentals/connection.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Connection
1212
/fundamentals/connection/connection-options
1313
/fundamentals/connection/network-compression
1414
/fundamentals/connection/tls
15+
/fundamentals/connection/socks
1516
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
1617

1718
.. contents:: On this page
@@ -31,6 +32,7 @@ learn:
3132
- :ref:`The Available Connection Options <node-connection-options>`
3233
- :ref:`How to Enable Network Compression <node-network-compression>`
3334
- :ref:`How to Enable TLS on a Connection <node-connect-tls>`
35+
- :ref:`How to Enable SOCKS5 Proxy Support <node-connect-socks>`
3436
- :atlas:`How to Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
3537

3638
For information about authenticating to MongoDB,

‎source/fundamentals/connection/connection-options.txt

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -124,25 +124,29 @@ parameters of the connection URI to specify the behavior of the client.
124124
* - **proxyHost**
125125
- string
126126
- ``null``
127-
- Specifies the IPv4/IPv6 address or domain name of a SOCKS5 proxy
128-
server used for connecting to MongoDB services.
127+
- Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain
128+
name.
129129

130130
* - **proxyPort**
131131
- non-negative integer
132132
- ``null``
133-
- Specifies the port of the SOCKS5 proxy server specified in ``proxyHost``.
133+
- Specifies the TCP port number of the SOCKS5 proxy server. If you
134+
set the ``proxyHost`` option, the value of this option defaults
135+
to ``1080``.
134136

135137
* - **proxyUsername**
136138
- string
137139
- ``null``
138-
- Specifies the username for username/password authentication to the SOCKS5
139-
proxy server specified in ``proxyHost``.
140+
- Specifies the username for authentication to the SOCKS5
141+
proxy server. If you set
142+
this option to a zero-length string, the driver ignores it.
140143

141144
* - **proxyPassword**
142145
- string
143146
- ``null``
144-
- Specifies the password for username/password authentication to the SOCKS5
145-
proxy server specified in ``proxyHost``.
147+
- Specifies the password for authentication to the SOCKS5
148+
proxy server. If you set
149+
this option to a zero-length string, the driver ignores it.
146150

147151
* - **readConcernLevel**
148152
- string

‎source/fundamentals/connection/socks.txt

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
.. _node-connect-socks:
2+
3+
===========================
4+
Enable SOCKS5 Proxy Support
5+
===========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to connect to MongoDB instances by using
17+
a SOCKS5 proxy. SOCKS5 is a standardized protocol for connecting
18+
to network services through a proxy server.
19+
20+
.. tip::
21+
22+
To learn more about the SOCKS5 protocol, see the Uncyclopedia entry on
23+
:wikipedia:`SOCKS <w/index.php?title=SOCKS&oldid=1160087146>`.
24+
25+
Install the socks Package
26+
-------------------------
27+
28+
Starting in version 6.0 of the {+driver-short+}, you must install
29+
the ``socks`` package to use SOCKS5 proxy support in your
30+
application. You can install ``socks`` by running the following command
31+
in your shell:
32+
33+
.. code-block:: bash
34+
35+
npm i socks
36+
37+
SOCKS5 Client Options
38+
---------------------
39+
40+
You can set options in your ``MongoClientOptions`` instance or
41+
in your connection URI to configure SOCKS5 proxy support for
42+
your connection. The following table describes the client options
43+
related to SOCKS5:
44+
45+
.. list-table::
46+
:header-rows: 1
47+
:widths: 15 20 10 55
48+
49+
* - Name
50+
- Accepted Values
51+
- Default Value
52+
- Description
53+
54+
* - **proxyHost**
55+
- string
56+
- ``null``
57+
- Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain
58+
name.
59+
60+
* - **proxyPort**
61+
- non-negative integer
62+
- ``null``
63+
- Specifies the TCP port number of the SOCKS5 proxy server. If you
64+
set the ``proxyHost`` option, the value of this option defaults
65+
to ``1080``.
66+
67+
* - **proxyUsername**
68+
- string
69+
- ``null``
70+
- Specifies the username for authentication to the SOCKS5
71+
proxy server. If you set
72+
this option to a zero-length string, the driver ignores it.
73+
74+
* - **proxyPassword**
75+
- string
76+
- ``null``
77+
- Specifies the password for authentication to the SOCKS5
78+
proxy server. If you set
79+
this option to a zero-length string, the driver ignores it.
80+
81+
.. important::
82+
83+
The driver throws an error if you set the ``proxyPort``,
84+
``proxyUsername``, or ``proxyPassword`` options without setting the
85+
``proxyHost`` option.
86+
87+
Example
88+
-------
89+
90+
This example shows how to instantiate a ``MongoClient`` that uses SOCKS5
91+
proxy support. The following example code specifies proxy server options
92+
and connects to MongoDB:
93+
94+
.. literalinclude:: /code-snippets/connection/socks.js
95+
:language: javascript
96+
:start-after: start-socks
97+
:end-before: end-socks
98+
99+
.. tip::
100+
101+
The preceding sample code uses placeholders for the connection URI
102+
and proxy server details. To run this code, you must replace these
103+
placeholders with the information for your deployment and proxy server.
104+
105+
Additional Information
106+
----------------------
107+
108+
For more information about SOCKS5 proxy support, see the
109+
`MongoDB SOCKS5 specification <https://github.com/mongodb/specifications/blob/master/source/socks5-support/socks5.rst>`__.
110+
111+
API Documentation
112+
~~~~~~~~~~~~~~~~~
113+
114+
To learn more about the methods and types discussed in this
115+
guide, see the following API Documentation:
116+
117+
- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__
118+
- `MongoClient <{+api+}/classes/MongoClient.html>`__
119+
- `ProxyOptions <{+api+}/interfaces/ProxyOptions.html>`__

‎source/upgrade.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ Version 6.x Breaking Changes
9494
- The ``Binary.write()`` method no longer accepts a string to write to the binary
9595
BSON object.
9696
- The ClientEncryption API returns promises instead of callbacks.
97+
- The ``socks`` package, which enables SOCKS5 proxy support, is a
98+
peer-optional dependency. You must install the package to enable
99+
SOCKS5 in your application.
97100
- If you start a session on a client, then pass that session to a
98101
different client, the driver throws an error when you
99102
perform any operations in the session.

‎source/whats-new.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,11 @@ What's New in 6.0
7676

7777
- The ClientEncryption API returns promises instead of callbacks.
7878

79+
- The ``socks`` package, which enables SOCKS5 proxy support, is a
80+
peer-optional dependency. To use ``socks`` functionality in your
81+
application, you must install the package. To learn more, see
82+
:ref:`node-connect-socks`.
83+
7984
- If you start a session on a client, then pass that session to a
8085
different client, the driver throws an error when you
8186
perform any operations in the session.

0 commit comments

Comments
 (0)