DOCSP-28691 when to write to destination cluster (#118)

* DOCSP-28691 write blocking on dest cluster

* DOCSP-28691 write blocking on dest cluster

* DOCSP-28691 write blocking on dest cluster

* Staging fixes

* Staging fixes

* Staging fixes

* fake commit

* Force build

* Write blocking

* Write blocking

* Review feedback

* Staging fixes

* Heading

* review feedback

* Review feedback

* Review feedback

* Review feedback

* Review feedback

Author: Dave Cuthbert

source/includes/api/tables/progress-response.rst

@@ -20,9 +20,12 @@
 
    * - ``canWrite``
      - boolean
-     - If ``true``, indicates that it is possible to write to the
-       destination cluster. Index validation continues until the 
-       :ref:`commit <c2c-api-commit>` is complete.
+     - If ``true``, indicates that writes are permitted on the
+       destination cluster. Do not write to the destination cluster
+       while ``canWrite`` is ``false``.
+       
+       Index validation continues until the :ref:`commit
+       <c2c-api-commit>` is complete. 
 
    * - ``info``
      - string

source/includes/fact-write-blocking-check.rst

@@ -0,0 +1,8 @@
+To see what state ``mongosync`` is in, call the :ref:`/progress
+<c2c-api-progress>` API endpoint. The ``/progress`` output includes a
+boolean value, ``canWrite``.
+
+- When ``canWrite`` is ``true``, it is safe to write to the destination
+  cluster.
+- When ``canWrite`` is ``false``, do not write to the destination
+  cluster.

source/includes/fact-write-blocking-enable.rst

@@ -0,0 +1,8 @@
+When write-blocking is enabled, ``mongosync`` blocks writes:
+
+- On the destination cluster during sync
+- On the source cluster while committing
+
+To enable write-blocking, use the :ref:`start API <c2c-api-start>`
+to set ``enableUserWriteBlocking`` to ``true``. You cannot enable
+write-blocking after the sync starts.

source/includes/fact-write-blocking-when.rst

@@ -0,0 +1,3 @@
+You can safely write to the source cluster while ``mongosync`` is
+syncing. Do not write to the destination cluster unless ``canWrite`` is
+``true``.

source/reference/api/reverse.txt

@@ -35,9 +35,13 @@ Requirements
 
 To use the ``reverse`` endpoint:
 
-- You must have started your original sync operation with the
-  ``reversible`` and ``enableUserWriteBlocking`` options set to
-  ``true``.
+- ``mongosync`` must be configured when the initial sync begins. The
+  call to the :ref:`/start <c2c-api-start>` API endpoint must set:
+  
+  - ``reversible`` to ``true``
+  - ``enableUserWriteBlocking`` to ``true``
+  
+  You cannot update these options after the sync starts.
 - ``mongosync`` must be in the ``COMMITTED`` state.
 - Source and destination clusters must be MongoDB 6.0 or later.
 - :ref:`Unique indexes <index-type-unique>` on the original source

source/reference/mongosync-states.txt

@@ -42,7 +42,9 @@ operations in that state.
      - Description
      - Possible API Operations
 
-   * - ``IDLE``
+   * - .. _c2c-state-idle:
+
+       ``IDLE``
      - ``mongosync`` is initialized and ready for a sync job to
        begin.
      - - ``POST`` :ref:`/start <c2c-api-start>`
@@ -62,7 +64,9 @@ operations in that state.
      - - ``POST`` :ref:`/resume <c2c-api-resume>`
        - ``GET`` :ref:`/progress <c2c-api-progress>`
 
-   * - ``COMMITTING``
+   * - .. _c2c-state-committing:
+   
+       ``COMMITTING``
      - The cutover for the sync process has started. The time it takes
        to transition to the ``COMMITTED`` phase depends on
        ``lagTimeSeconds``. To monitor ``lagTimeSeconds`` or to see if
@@ -73,3 +77,26 @@ operations in that state.
    * - ``COMMITTED``
      - The cutover for the sync process is complete.
      - - ``GET`` :ref:`/progress <c2c-api-progress>`
+
+Read Operations
+---------------
+
+Read operations on the source cluster are always permitted.
+
+When the ``/progress`` endpoint reports ``canWrite`` is ``true``, the
+data on the source and destination clusters is consistent.
+
+Write Operations
+----------------
+
+.. include:: /includes/fact-write-blocking-check.rst
+
+.. include:: /includes/fact-write-blocking-when.rst
+
+Write-blocking
+~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-write-blocking-enable.rst
+
+.. include:: /includes/fact-write-blocking-requirement.rst
+

source/reference/mongosync.txt

@@ -200,27 +200,30 @@ show an empty ``system.views`` collection in that database. The empty
 ``system.views`` collection will not change the accuracy of user
 data on the destination.
 
+.. c2c-write-blocking:
+
 Write Blocking
 ~~~~~~~~~~~~~~
 
-By default, write-blocking is not enabled during synchronization. When
-write-blocking is enabled, ``mongosync`` blocks writes:
-
-- On the destination cluster during replication
-- On the source cluster while committing
+.. include:: /includes/fact-write-blocking-enable.rst
 
-To enable write-blocking, use the :ref:`start API <c2c-api-start>`
-to set ``enableUserWriteBlocking`` to ``true``.
+Write-blocking is not enabled by default. You must enable write-blocking
+when you start ``mongosync`` if you want to use :ref:`reverse
+synchronization <c2c-api-reverse>` later.
 
-:ref:`Reverse synchronization <c2c-api-reverse>` requires
-write-blocking. To enable reverse synchronization between the source
-and destination clusters, use the ``start API`` to initiate replication
-with ``reversible`` and ``enableUserWriteBlocking`` set to ``true``.
-The options must be set when replication begins, they cannot be updated
-later.
+User Permissions
+````````````````
 
 .. include:: /includes/fact-write-blocking-requirement.rst
 
+Permissible Writes
+``````````````````
+
+.. include:: /includes/fact-write-blocking-check.rst
+
+.. include:: /includes/fact-write-blocking-when.rst
+
+
 .. _c2c-capped-collections:
 
 Capped Collections