AV-35207 - Restructure Distributed ACID Transactions docs (#273)

Author: maria-robobug

modules/ROOT/nav.adoc

@@ -16,10 +16,18 @@
 * xref:howtos:full-text-searching-with-sdk.adoc[Search]
 * xref:howtos:view-queries-with-sdk.adoc[MapReduce Views]
 
+.Transactions
+* xref:howtos:distributed-acid-transactions-from-the-sdk.adoc[How-to Guide]
+** xref:howtos:transactions-single-query.adoc[Single Query Transactions]
+// TODO: Add this for .NET when available
+//** xref:howtos:transactions-tracing.adoc[Tracing]
+* xref:concept-docs:transactions.adoc[Key Concepts]
+** xref:concept-docs:transactions-cleanup.adoc[Cleanup]
+** xref:concept-docs:transactions-error-handling.adoc[Error Handling]
+
 .Advanced Data Operations
 * xref:howtos:concurrent-async-apis.adoc[Async & React APIs]
 * xref:howtos:concurrent-document-mutations.adoc[Concurrent Document Mutations]
-* xref:howtos:distributed-acid-transactions-from-the-sdk.adoc[Distributed ACID Transactions]
 * xref:howtos:encrypting-using-sdk.adoc[Encrypting Your Data]
 * xref:howtos:transcoders-nonjson.adoc[Transcoders & Non-JSON]
 * xref:howtos:working-with-collections.adoc[Working with Collections]

modules/concept-docs/pages/errors.adoc

@@ -30,4 +30,4 @@ include::{version-server}@sdk:shared:partial$errors.adoc[tag=observability]
 
 == ACID Transactions
 
-For a discussion of errors affecting multi-document ACID transactions, see xref:howtos:distributed-acid-transactions-from-the-sdk.adoc#error-handling[our documentation on transactions from the .NET SDK].
+For a discussion of errors affecting multi-document ACID transactions, see xref:concept-docs:transactions-error-handling.adoc#error-handling[our documentation on transactions from the .NET SDK].

modules/concept-docs/pages/transactions-cleanup.adoc

@@ -0,0 +1,47 @@
+= Cleanup
+:description: The SDK takes care of failed or lost transactions, using an asynchronous cleanup background task.
+:page-toclevels: 2
+:page-pagination: full
+
+[abstract]
+{description}
+
+include::project-docs:partial$attributes.adoc[]
+include::howtos:partial$acid-transactions-attributes.adoc[]
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=cleanup;!integrated-sdk-cleanup-collections]
+
+[#tuning-cleanup]
+=== Configuring Cleanup
+
+The cleanup settings can be configured as so:
+
+[options="header"]
+|===
+|Setting|Default|Description
+|`CleanupWindow`|60 seconds|This determines how long a cleanup 'run' is; that is, how frequently this client will check its subset of ATR documents.  It is perfectly valid for the application to change this setting, which is at a conservative default.  Decreasing this will cause expiration transactions to be found more swiftly (generally, within this cleanup window), with the tradeoff of increasing the number of reads per second used for the scanning process.
+|`CleanupLostAttempts`|true|This is the thread that takes part in the distributed cleanup process described above, that cleans up expired transactions created by any client.  It is strongly recommended that it is left enabled.
+|`CleanupClientAttempts`|true|This thread is for cleaning up transactions created just by this client.  The client will preferentially aim to send any transactions it creates to this thread, leaving transactions for the distributed cleanup process only when it is forced to (for example, on an application crash).  It is strongly recommended that it is left enabled.
+|===
+
+// TODO: Add this for .NET when available
+////
+=== Monitoring Cleanup
+
+If the application wishes to monitor cleanup it may subscribe to these events:
+
+[source,csharp]
+----
+include::example$TransactionsExample.cs[tag=cleanup-events,indent=0]
+----
+
+`TransactionCleanupEndRunEvent` is raised whenever a current 'run' is finished, and contains statistics from the run.
+(A run is typically around every 60 seconds, with default configuration.)
+
+A `TransactionCleanupAttempt` event is raised when an expired transaction was found by this process, and a cleanup attempt was made.
+It contains whether that attempt was successful, along with any logs relevant to the attempt.
+
+In addition, if cleanup fails to cleanup a transaction that is more than two hours past expiry, it will raise the `TransactionCleanupAttempt` event at WARN level (rather than the default DEBUG).
+With most default configurations of the event-bus (see <<Logging>> below), this will cause that event to be logged somewhere visible to the application.
+If there is not a good reason for the cleanup to be failed (such as a downed node that has not yet been failed-over), then the user is encouraged to report the issue.
+////

modules/concept-docs/pages/transactions-error-handling.adoc

@@ -0,0 +1,36 @@
+= Error Handling
+:description:  Handling transaction errors with Couchbase.
+:page-toclevels: 2
+:page-pagination: prev
+
+[abstract]
+{description}
+
+include::project-docs:partial$attributes.adoc[]
+include::howtos:partial$acid-transactions-attributes.adoc[]
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=error-intro]
+
+== Transaction Errors
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=error]
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed]
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=config-expiration,indent=0]
+----
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=txnfailed1]
+
+Similar to `TransactionResult`, `SingleQueryTransactionResult` also has an `UnstagingComplete` property.
+
+=== Full Error Handling Example
+
+Pulling all of the above together, this is the suggested best practice for error handling:
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=full-error-handling,indent=0]
+----

modules/concept-docs/pages/transactions.adoc

@@ -0,0 +1,70 @@
+= Distributed ACID Transactions
+:description:  A high-level overview of Distributed ACID Transactions with Couchbase.
+:page-toclevels: 2
+:page-pagination: next
+
+include::project-docs:partial$attributes.adoc[]
+include::howtos:partial$acid-transactions-attributes.adoc[]
+
+[abstract]
+{description}
+
+For a practical guide, see xref:howtos:distributed-acid-transactions-from-the-sdk.adoc[Distributed ACID Transactions from the Java SDK].
+
+== Overview
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=intro]
+
+== Transaction Mechanics
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=create-simple,indent=0]
+----
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=mechanics;!integrated-sdk-cleanup-process]
+
+TIP: Committing is automatic: if there is no explicit call to `ctx.CommitAsync()` at the end of the transaction logic callback, and no exception is thrown, it will be committed.
+
+=== Rollback
+
+When an exception is thrown, either by the application from the {lambda}, or by the transactions logic itself (e.g. on a failed operation), then that attempt is rolled back.
+
+The application's {lambda} may or may not be retried, depending on the error that occurred.
+The general rule for retrying is whether the transaction is likely to succeed on a retry.
+For example, if this transaction is trying to write a document that is currently involved in another transaction (a write-write conflict), this will lead to a retry as that is likely a transient state.
+But if the transaction is trying to get a document that does not exist, it will not retry.
+
+If the transaction is not retried then it will throw a `{transaction-failed}`.
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=rollback-cause,indent=0]
+----
+
+The transaction can also be explicitly rolled back:
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=rollback,indent=0]
+----
+
+In this case, if `ctx.RollbackAsync()` is reached, then the transaction will be regarded as successfully rolled back and no `{transaction-failed}` will be thrown.
+
+After a transaction is rolled back, it cannot be committed, no further operations are allowed on it, and the SDK will not try to automatically commit it at the end of the code block.
+
+== Transaction Operations
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tags=query;!integrated-sdk-begin-transaction]
+
+== Custom Metadata Collections
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=custom-metadata-1]
+
+[source,csharp]
+----
+include::howtos:example$TransactionsExample.cs[tag=custom-metadata,indent=0]
+----
+
+include::{version-server}@sdk:shared:partial$acid-transactions.adoc[tag=custom-metadata-2]
+

modules/howtos/examples/Couchbase.Examples/Couchbase.Examples.csproj

@@ -7,9 +7,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="CouchbaseNetClient" Version="3.1.3" />
+    <PackageReference Include="CouchbaseNetClient" Version="3.3.4" />
     <PackageReference Include="Couchbase.Extensions.Encryption" Version="2.0.0-dp.1" />
-    <PackageReference Include="MessagePack" Version="2.2.85" />
+    <PackageReference Include="MessagePack" Version="2.4.35" />
   </ItemGroup>
 
 </Project>

modules/howtos/examples/TransactionsExample.cs

@@ -36,7 +36,7 @@ static async Task Main(string[] args)
             var options = new ClusterOptions().WithCredentials("Administrator", "password");
             var cluster = await Cluster.ConnectAsync("couchbase://localhost", options).ConfigureAwait(false);
             var bucket = await cluster.BucketAsync("default").ConfigureAwait(false);
-            var collection = bucket.DefaultCollection();
+            var collection = await bucket.ScopeAsync("inventory").CollectionAsync("airport").ConfigureAwait(false);
 
             // Create the single Transactions object
             var transactions = Transactions.Create(cluster, TransactionConfigBuilder.Create());
@@ -78,6 +78,24 @@ void ConfigCleanup(byte[] encoded)
             // #end::config-cleanup[]
         }
 
+        async Task CreateSimpleAsync()
+        {
+            var doc1Content = new { };
+            var doc2Content = new { };
+
+            // tag::create-simple[]
+            await _transactions.RunAsync(async (ctx) =>
+            {
+                await ctx.InsertAsync(_collection, "doc-1", doc1Content).ConfigureAwait(false);
+
+                var doc2 = await ctx.GetAsync(_collection, "doc-2").ConfigureAwait(false);
+                await ctx.ReplaceAsync(doc2, doc2Content).ConfigureAwait(false);
+
+                await ctx.CommitAsync().ConfigureAwait(false);
+            }).ConfigureAwait(false);
+            // end::create-simple[]
+        }
+
         async Task CreateAsync()
         {
             // #tag::create[]
@@ -335,9 +353,7 @@ public class BalanceInsufficientException : Exception { }
         private async Task RollbackCause()
         {
             const int costOfItem = 10;
-
-            // #tag::rollback-cause[]
-
+            // tag::rollback-cause[]
             try
             {
                 await _transactions.RunAsync(async ctx =>
@@ -351,8 +367,7 @@ await _transactions.RunAsync(async ctx =>
             catch (TransactionCommitAmbiguousException e)
             {
                 // This exception can only be thrown at the commit point, after the
-                // BalanceInsufficient logic has been passed, so there is no need to
-                // check getCause here.
+                // BalanceInsufficient logic has been passed.
                 Console.Error.WriteLine("Transaction possibly committed");
                 Console.Error.WriteLine(e);
             }
@@ -361,7 +376,7 @@ await _transactions.RunAsync(async ctx =>
                 Console.Error.WriteLine("Transaction did not reach commit point");
             }
 
-            // #end::rollback-cause[]
+            // end::rollback-cause[]
         }
 
         async Task CompleteErrorHandling()
@@ -559,7 +574,10 @@ await ctx.QueryAsync<object>(
             {
                 // tag::queryInsert[]
                 await transactions.RunAsync(async ctx => {
-                    await ctx.QueryAsync<object>("INSERT INTO `default` VALUES ('doc', {'hello':'world'})", TransactionQueryConfigBuilder.Create());  // <1>
+                    await ctx.QueryAsync<object>(
+                        "INSERT INTO `default` VALUES ('doc', {'hello':'world'})",
+                        TransactionQueryConfigBuilder.Create()
+                    );  // <1>
 
                     // Performing a 'Read Your Own Write'
                     var st = "SELECT `default`.* FROM `default` WHERE META().id = 'doc'"; // <2>
@@ -649,7 +667,8 @@ await ctx.QueryAsync<object>("INSERT INTO `default` VALUES ('doc', {'hello':'wor
 
             {
                 // tag::custom-metadata[]
-                ICouchbaseCollection metadataCollection = null; // this is a Collection opened by your code earlier
+                // Replace with your own metadata collection.
+                ICouchbaseCollection metadataCollection = null;
                 Transactions transactionsWithCustomMetadataCollection = Transactions.Create(cluster,
                         TransactionConfigBuilder.Create().MetadataCollection(metadataCollection));
                 // end::custom-metadata[]