RUBY-3160 Fix all parse errors except bson-tutorials (#2672) (#2765) (#2767)

Co-authored-by: Neil Shweky <neilshweky@gmail.com>

Author: comandeo-mongo

docs/contribute.txt

@@ -58,7 +58,7 @@ Contribute Code
 The MongoDB Ruby driver source is located
 `at GitHub <https://github.com/mongodb/mongo-ruby-driver>`_.
 
-The list of known issues in the driver is available 
+The list of known issues in the driver is available
 `in JIRA <https://jira.mongodb.org/browse/RUBY>`_.
 
 We recommend creating a JIRA ticket before starting work on a bug fix or
@@ -73,7 +73,7 @@ the changes to the stable branches, if needed.
 A MongoDB deployment is required to run the tests. Setup procedures and
 recommendations for various deployments, as well as how to configure the
 driver's test suite for the deployments, are covered in the `spec
-readme <https://github.com/mongodb/mongo-ruby-driver/blob/master/spec/README.md>`.
+readme <https://github.com/mongodb/mongo-ruby-driver/blob/master/spec/README.md>`__.
 
 The driver is tested on `Evergreen <https://github.com/evergreen-ci/evergreen>`_,
 MongoDB's in-house continuous integration platform. After a pull request

docs/tutorials/client-side-encryption.txt

@@ -74,12 +74,12 @@ enterprise-only feature. If you only intend to use explicit encryption, you may
 skip this step.
 
 Mongocryptd comes pre-packaged with enterprise builds of the MongoDB server
-(versions 4.2 and newer). For installation instructions, see
-`the MongoDB manual <https://docs.mongodb.com/manual/reference/security-client-side-encryption-appendix/#installation>`_.
+(versions 4.2 and newer). For installation instructions, see the
+`MongoDB manual <https://mongodb.com/docs/manual/reference/security-client-side-encryption-appendix/#installation>`_.
 
 In order to configure mongocryptd (for example, which port it listens on or the
 path used to spawn the daemon), it is necessary to pass different options to the
-``Mongo::Client`` performing automatic encryption. See the `:extra_options`_
+``Mongo::Client`` performing automatic encryption. See the :ref:`:extra_options <cse-extra-options>`
 section of this tutorial for more information.
 
 Automatic Encryption
@@ -202,11 +202,12 @@ The example above demonstrates using automatic encryption with a local master ke
 For more information about using the AWS Key Management Service to create a
 master key and create data keys, see the following sections of this tutorial:
 
-- `Creating A Master Key`_
-- `Creating A Data Key`_
+- :ref:`Creating A Master Key <creating-a-master-key>`
+- :ref:`Creating A Data Key <creating-a-data-key>`
 
 Explicit Encryption
 ===================
+
 Explicit encryption is a feature that allows users to encrypt and decrypt
 individual pieces of data such as strings, integers, or symbols. Explicit
 encryption is a community feature and does not require an enterprise build
@@ -296,8 +297,8 @@ The example above demonstrates using explicit encryption with a local master key
 For more information about using the AWS Key Management Service to create a
 master key and create data keys, see the following sections of this tutorial:
 
-- `Creating A Master Key`_,
-- `Creating A Data Key`_,
+- :ref:`Creating A Master Key <creating-a-master-key>`
+- :ref:`Creating A Data Key <creating-a-data-key>`
 
 Creating a Master Key
 =====================
@@ -307,8 +308,11 @@ user data. The master key can be generated in one of two ways: by creating a
 local key, or by creating a key in the Amazon Web Services Key Management
 Service (AWS KMS).
 
+.. _local-master-key:
+
 Local Master Key
 ~~~~~~~~~~~~~~~~
+
 A local master key is a 96-byte binary string. It should be persisted
 on your machine as an environment variable or in a text file.
 
@@ -329,14 +333,25 @@ AWS Master Key
 It is recommended that you use Amazon's Key Management Service to create and
 store your master key. To do so, follow steps 1 and 2 of the
 :drivers:`"Convert to a Remote Master Key" section</security/client-side-field-level-encryption-local-key-to-kms/#convert-to-a-remote-master-key>`
+.. _remote-master-key:
+
+Remote Master Key
+~~~~~~~~~~~~~~~~~
+It is recommended that you use a remote Key Management Service to create and
+store your master key. To do so, follow steps of the
+`"Set up a Remote Master Key" <https://www.mongodb.com/docs/manual/core/csfle/tutorials/#set-up-a-remote-master-key>`_
 in the MongoDB Client-Side Encryption documentation.
 
 For more information about creating a master key, see the
 :drivers:`Create a Master Key </security/client-side-field-level-encryption-guide/#a-create-a-master-key>`
+`Create a Master Key <https://www.mongodb.com/docs/manual/core/csfle/#a.-create-a-master-key>`_
 section of the MongoDB manual.
 
+.. _creating-a-data-key:
+
 Creating a Data Key
 ===================
+
 Once you have created a master key, create a data key by calling the
 ``#create_data_key`` method on an instance of the ``Mongo::ClientEncryption``
 class. This method generates a new data key and inserts it into the key vault
@@ -376,8 +391,8 @@ key with the following code snippet:
   data_key_id = client_encryption.create_data_key('local')
   # => <BSON::Binary... type=ciphertext...>
 
-See the `Local Master Key`_ section for more information about generating a new
-local master key.
+See the :ref:`Local Master Key <local-master-key>` section for more information
+about generating a new local master key.
 
 Create a Data Key Using an AWS Master Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -423,18 +438,20 @@ generating a new master key on AWS and finding the information you need to
 create data keys.
 
 For more information about creating a data key, see the
-:drivers:`Create a Data Encryption Key </security/client-side-field-level-encryption-guide/#b-create-a-data-encryption-key>`
+`Create a Data Encryption Key <https://www.mongodb.com/docs/manual/core/csfle/#b.-create-a-data-encryption-key>`_
 section of the MongoDB manual.
 
 Auto-Encryption Options
 =======================
+
 Automatic encryption can be configured on a ``Mongo::Client`` using the
 ``auto_encryption_options`` option ``Hash``. This section provides an overview
 of the fields inside ``auto_encryption_options`` and explains how to choose their
 values.
 
 ``:key_vault_client``
 ~~~~~~~~~~~~~~~~~~~~~
+
 The key vault client is a ``Mongo::Client`` instance that will be used to connect
 to the MongoDB collection containing your encryption data keys. For example, if
 your key vault was hosted on a MongoDB instance at ``localhost:30000``:
@@ -456,6 +473,7 @@ to insert and fetch data keys.
 
 ``:key_vault_namespace``
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
 The key vault namespace is a ``String`` in the format ``"database_name.collection_name"``,
 where ``database_name`` and ``collection_name`` are the name of the database and
 collection in which you would like to store your data keys. For example, if your data
@@ -474,6 +492,7 @@ There is no default key vault namespace, and this option must be provided.
 
 ``:schema_map``
 ~~~~~~~~~~~~~~~
+
 A schema map is a Hash with information about which fields to automatically
 encrypt and decrypt.
 
@@ -549,11 +568,12 @@ When you intend to use your schema map, convert it to a Ruby ``Hash`` using the
 
 .. seealso::
 
-  :drivers:`Specify Encrypted Fields Using JSON Schema</security/client-side-field-level-encryption-guide/#c-specify-encrypted-fields-using-json-schema>`,
+  `Specify Encrypted Fields Using JSON Schema <https://www.mongodb.com/docs/manual/core/csfle/#c-specify-encrypted-fields-using-json-schema>`_,
   :manual:`Automatic Encryption Rules</reference/security-client-side-automatic-json-schema/>`
 
 ``:bypass_auto_encryption``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The ``:bypass_auto_encryption`` option is a ``Boolean`` that specifies whether the
 ``Mongo::Client`` should skip encryption when writing to the database. If
 ``:bypass_auto_encryption`` is ``true``, the client will still perform automatic
@@ -568,8 +588,11 @@ decryption of any previously-encrypted data.
     }
   )
 
+.. _cse-extra-options:
+
 ``:extra_options``
 ~~~~~~~~~~~~~~~~~~
+
 ``:extra_options`` is a ``Hash`` of options related to spawning mongocryptd.
 Every option in this ``Hash`` has a default value, so it is only necessary to
 provide the options whose defaults you want to override.

docs/tutorials/common-errors.txt

@@ -29,7 +29,7 @@ to connect to; if no database name is specified, the client will use the
 .. code-block:: ruby
 
   Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb')
-  
+
   # Or using the URI syntax:
   Mongo::Client.new("mongodb://127.0.0.1:27017/mydb")
 
@@ -82,7 +82,7 @@ The database can be specified during ``Client`` construction:
 
   # Using Ruby client options:
   client = Mongo::Client.new(['localhost'], database: 'mydb')
-  
+
   # Using a MongoDB URI:
   client = Mongo::Client.new('mongodb://localhost/mydb')
 
@@ -92,9 +92,9 @@ new ``Client`` instance configured with the specified database:
 .. code-block:: ruby
 
   client = Mongo::Client.new(['localhost'], database: 'mydb')
-  
+
   admin_client = client.use('admin')
-  
+
   # Issue an administrative command
   admin_client.database.command(replSetGetConfig: 1).documents.first
 
@@ -125,7 +125,7 @@ To force all operations to be performed on the designated server, specify the
 .. code-block:: ruby
 
   Mongo::Client.new([ '1.2.3.4:27017' ], database: 'mydb', direct_connection: true)
-  
+
   # Or using the URI syntax:
   Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?directConnection=true")
 
@@ -153,7 +153,7 @@ connect to the replica set.
 
   Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ],
     :database => 'mydb', replica_set: 'myapp')
-  
+
   # Or using the URI syntax:
   Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?replicaSet=myapp")
 
@@ -186,7 +186,7 @@ spread the operation load accordingly.
 .. code-block:: ruby
 
   Mongo::Client.new([ '1.2.3.4:27017', '1.2.3.5:27017' ], :database => 'mydb')
-  
+
   Mongo::Client.new("mongodb://1.2.3.4:27017,1.2.3.5:27017/mydb")
 
 
@@ -270,7 +270,7 @@ Ruby Options
 
    * - ``:auth_mech_properties``
      - Provides additional authentication mechanism properties.
-     
+
        The keys in properties are interpreted case-insensitively.
        When the client is created, keys are lowercased.
 
@@ -319,8 +319,8 @@ Ruby Options
      - none
 
    * - ``:compressors``
-     - A list of potential compressors to use, in order of preference. The driver chooses the first
-       compressor that is also supported by the server. Currently the driver only supports 'zlib'.
+     - A list of potential compressors to use, in order of preference.
+       Please see below for details on how the driver implements compression.
      - ``Array<String>``
      - none
 
@@ -436,11 +436,11 @@ Ruby Options
              max_staleness: 5,
            }
          }
-         
+
        If tag sets are provided, they must be an array of hashes. A server
        satisfies the read preference if its tags match any one hash in the
        provided tag sets.
-       
+
        Each tag set must be a hash, and will be converted internally to
        a ``BSON::Document`` instance prior to being used for server selection.
        Hash keys can be strings or symbols. The keys are case sensitive.
@@ -480,12 +480,12 @@ Ruby Options
        subscriber not receiving some of the SDAM events. The ``:sdam_proc``
        option permits adding event subscribers on the client being constructed
        before any SDAM events are published.
-       
+
        Pass a ``Proc`` which will be called with the ``Client`` as the argument
        after the client's event subscription mechanism has been initialized
        but before any of the servers are added to the client. Use this
        ``Proc`` to set up SDAM event subscribers on the client.
-       
+
        Note: the client is not fully constructed when the ``Proc`` provided in
        ``:sdam_proc is invoked, in particular the cluster is nil at this time.
        ``:sdam_proc`` procedure should limit itself to calling
@@ -696,6 +696,7 @@ URI options are explained in detail in the :manual:`Connection URI reference
 </reference/connection-string/>`.
 
 .. note::
+
   Options that are set in **milliseconds** in the URI are
   represented as a ``float`` in Ruby and the units are **seconds**.
 
@@ -1090,6 +1091,53 @@ file and both must be stored in the same file. Example usage:
   URI option values must be properly URI escaped. This applies, for example, to
   slashes in the paths.
 
+
+.. _modifying-tls-context:
+
+Modifying ``SSLContext``
+------------------------
+It may be desirable to further configure TLS options in the driver, for example
+by enabling or disabling certain ciphers. Currently, the Ruby driver does not
+provide a way to do this when initializing a ``Mongo::Client``.
+
+However, the Ruby driver provides a way to set global "TLS context hooks" --
+these are user-provided ``Proc``s that will be invoked before any TLS socket
+connection and can be used to modify the underlying ``OpenSSL::SSL::SSLContext``
+object used by the socket.
+
+To set the TLS context hooks, add ``Proc``s to the ``Mongo.tls_context_hooks``
+array. This should be done before creating any Mongo::Client instances.
+For example, in a Rails application this code could be placed in an initializer.
+
+.. code-block:: ruby
+
+  Mongo.tls_context_hooks.push(
+    Proc.new { |context|
+      context.ciphers = ["AES256-SHA"]
+    }
+  )
+
+  # Only the AES256-SHA cipher will be enabled from this point forward
+
+Every ``Proc`` in ``Mongo.tls_context_hooks`` will be passed an
+``OpenSSL::SSL::SSLContext`` object as its sole argument. These ``Proc``s will
+be executed sequentially during the creation of every ``Mongo::Socket::SSL`` object.
+
+It is possible to assign the entire array of hooks calling ``Mongo.tls_context_hooks=``,
+but doing so will remove any previously assigned hooks. It is recommended to use
+the ``Array#push`` or ``Array#unshift`` methods to add new hooks.
+
+It is also possible to remove hooks from ``Mongo.tls_context_hooks`` by storing
+a reference to the Procs somewhere else in the application, and then using
+``Array#delete_if`` to remove the desired hooks.
+
+.. warning::
+
+  TLS context hooks are global and will affect every instance of ``Mongo::Client``.
+  Any library that allows applications to enable these hooks should expose methods to
+  modify the hooks (which can be called by the application) rather than
+  automatically enabling the hooks when the library is loaded.
+
 Further information on configuring MongoDB server for TLS is available in the
 :manual:`MongoDB manual </tutorial/configure-ssl/>`.
 
@@ -1162,10 +1210,13 @@ The ``:ssl_ca_cert_string`` option supports specifying only one CA certificate.
   CA certificate options. Doing so would elevate the intermediate certificates
   to the status of root certificates, rather than verifying intermediate
   certificates against the root certificates.
-  
+
   If intermediate certificates need to be used, specify them as part of the
   client or server TLS certificate files.
 
+
+.. _ocsp-verification:
+
 OCSP Verification
 -----------------
 
@@ -1300,7 +1351,7 @@ Usage with Forking Servers
 ==========================
 
 .. note::
-  
+
   Applications using Mongoid should follow `Mongoid's forking guidance
   <https://docs.mongodb.com/mongoid/current/tutorials/mongoid-configuration/#usage-with-forking-servers>`_.
   The guidance and sample code below is provided for applications using the
@@ -1316,7 +1367,7 @@ This is because:
 2. File descriptors like network sockets are shared between parent and
    child processes.
 
-The driver attempts to detect client use from forked processes and 
+The driver attempts to detect client use from forked processes and
 reestablish network connections when such use is detected, alleviating
 the issue of file descriptor sharing.
 

docs/tutorials/ruby-driver-create-client.txt

@@ -900,7 +900,7 @@ underscore one that Ruby driver uses.
 A Note about the BSON Symbol type
 =================================
 
-Because the BSON specification deprecated the BSON symbol type, the `bson` gem
+Because the BSON specification deprecated the BSON symbol type, the ``bson`` gem
 will serialize Ruby symbols into BSON strings when used on its own. However, in
 order to maintain backwards compatibility with older datasets, the Ruby driver
 overrides this behavior to serialize Ruby symbols as BSON symbols. This is

docs/tutorials/ruby-driver-crud-operations.txt

@@ -252,7 +252,7 @@ by default into the ``fs.chunks`` collection and file metadata is inserted into
 
   client.database.fs.insert_one(file)
 
-To insert into collections with a name prefix other than `fs`, access the
+To insert into collections with a name prefix other than ``fs``, access the
 filesystem with a ``:fs_name`` option.
 
 .. code-block:: ruby