DOCSP-13757: Delivery guarantees for sink and source (#44)

* DOCSP-13757: Delivery guarantees for sink and source

Author: Chris Cho

source/kafka-sink.txt

@@ -12,8 +12,12 @@ Kafka Sink Connector Guide
    :depth: 2
    :class: singlecol
 
-Apache Kafka uses a sink connector to consume records from a topic and
-save the data to a datastore.
+
+Overview
+--------
+
+The MongoDB Kafka Sink Connector consumes records from a Kafka topic and
+saves the data to a MongoDB database.
 
 This section of the guide covers the configuration settings necessary to
 set up a Kafka Sink connector.
@@ -27,6 +31,33 @@ set up a Kafka Sink connector.
    :manual:`use an index to support these queries
    <tutorial/create-indexes-to-support-queries/>`.
 
+
+Message Delivery Guarantee
+--------------------------
+
+The Sink Connector guarantees "at-least-once" message delivery by default.
+If there is an error while processing data from a topic, the connector
+retries the write.
+
+An "exactly-once" message delivery guarantee can be achieved using an
+idempotent operation such as insert or update. Configure the connector to
+ensure messages include a value for the ``_id`` field.
+
+.. note::
+
+   You can configure the :ref:`DocumentIdAdder post processor <config-document-id-adder>`
+   to define a custom behavior and a value for a ``_id`` field. By default,
+   the sink connector uses the ``BsonOidStrategy`` which generates a
+   new :manual:`BSON ObjectId </reference/bson-types/#objectid>` for the
+   ``_id`` field if one does not exist.
+
+If you need an "exactly-once" message delivery guarantee, configure the
+connector to ensure messages include a value for the ``_id`` field. For
+example, you can specify the :ref:`DocumentIdAdder post processor <config-document-id-adder>`
+to add a value for the ``_id`` field.
+
+The sink connector does not support the "at-most-once" guarantee.
+
 .. toctree::
    :titlesonly:
    :hidden:

source/kafka-source.txt

@@ -12,6 +12,9 @@ Kafka Source Connector Guide
    :depth: 2
    :class: singlecol
 
+Overview
+--------
+
 The MongoDB Kafka Source Connector moves data from a MongoDB replica set
 into a Kafka cluster. The connector configures and consumes :manual:`change
 stream event documents </changeStreams>` and publishes them to a topic.
@@ -28,6 +31,14 @@ for more information.
 
    Change streams require a replicaSet or a sharded cluster using replicaSets.
 
+Message Delivery Guarantee
+--------------------------
+
+The Source Connector guarantees "at-least-once" delivery by default. If
+you set the ``copy.existing`` setting to **true**, the connector may
+deliver duplicate messages. Since these messages are idempotent, there
+is no need to support "at-most-once" nor "exactly-once" guarantees.
+
 Change Stream Event Document Format
 -----------------------------------