Supporting transactional session for send only endpoints (#7089)

* Remove send only limitation

* Add skeleton docs

* Add link to persisters

* Document that persisters will disable cleanup when a remote processor is used

* Pull new section out to partial

* Add v3.3 snippet

* Clarify that not all pesisters have endpoint driven cleanup

* Update to beta 1

* Typo

* Add place holder for SQLP config

* SQLP instructions for sharing outbox table

* Add prerelease marker

* Add sql p to outbox cleanup disable list

* Fix cleanup

* Add cosmos config requirements

* Wording

* Document ravendb

* Cleanup

* Spike docs for setting ravendb endpoint name

* Improve ravendb outbox docs and link back to processor section

* Add dynamo db

* Add docs for dynamo

* Add note

* Remove docs for new api

* Cleanup docs to match new design

* Update snippets to new api

* Correct label

* Use stable component for snippets

* Typos

* Add inline upgrade guide

* Update nservicebus/transactional-session/index_remote-processor_transactionalsession_[3.3,).partial.md

Co-authored-by: Poornima Nayar <[email protected]>

* Spelling

* Document new failure scenario

* Spelling

* Apply suggestions from code review

Co-authored-by: Poornima Nayar <[email protected]>

* Spelling

* Add note about tx session having to be enabled

* Fix link

* Fix link

* Update index_remote-processor_transactionalsession_[3.3,).partial.md

* Update nservicebus/transactional-session/index.md

* minor improvement to existing text

* adding link back

---------

Co-authored-by: Poornima Nayar <[email protected]>
Co-authored-by: Christian <[email protected]>

Author: 3 people

Snippets/TransactionalSession/TransactionalSession.sln

@@ -11,6 +11,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TransactionalSession_3", "T
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TransactionalSession_3.1", "TransactionalSession_3.1\TransactionalSession_3.1.csproj", "{F914C826-E6E1-47F5-89AD-1BA1A5DA19BE}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TransactionalSession_3.3", "TransactionalSession_3.3\TransactionalSession_3.3.csproj", "{1D6EA06A-D31A-476E-833C-981C5A8DC946}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -69,6 +71,18 @@ Global
 		{F914C826-E6E1-47F5-89AD-1BA1A5DA19BE}.Release|x64.Build.0 = Release|Any CPU
 		{F914C826-E6E1-47F5-89AD-1BA1A5DA19BE}.Release|x86.ActiveCfg = Release|Any CPU
 		{F914C826-E6E1-47F5-89AD-1BA1A5DA19BE}.Release|x86.Build.0 = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|x64.Build.0 = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Debug|x86.Build.0 = Debug|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|x64.ActiveCfg = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|x64.Build.0 = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|x86.ActiveCfg = Release|Any CPU
+		{1D6EA06A-D31A-476E-833C-981C5A8DC946}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Snippets/TransactionalSession/TransactionalSession_3.3/Api.cs

@@ -0,0 +1,51 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.DependencyInjection;
+using NServiceBus;
+using NServiceBus.Persistence;
+using NServiceBus.TransactionalSession;
+
+class Api
+{
+    public async Task Open(IServiceScope scope, CancellationToken cancellationToken)
+    {
+        var session = scope.ServiceProvider.GetRequiredService<ITransactionalSession>();
+
+        #region configuring-commit-delay-transactional-session
+
+        await session.Open(new MyPersistenceOpenSessionOptions
+            {
+                CommitDelayIncrement = TimeSpan.FromSeconds(1)
+            },
+            cancellationToken: cancellationToken);
+
+        #endregion
+    }
+
+    public void ConfigureRemoteProcessor(EndpointConfiguration endpointConfiguration)
+    {
+        #region configure-remote-processor
+
+        var transactionalSessionOptions = new TransactionalSessionOptions
+        {
+            ProcessorEndpoint = "MyProcessorEndpoint"
+        };
+
+        endpointConfiguration.UsePersistence<MyPersistence>()
+            .EnableTransactionalSession(transactionalSessionOptions);
+
+        #endregion
+    }
+}
+
+public static class TransactionalSessionConfigurationExtensions
+{
+    public static void EnableTransactionalSession(this PersistenceExtensions<MyPersistence> persistence, TransactionalSessionOptions transactionalSessionOptions = null)
+    {
+    }
+}
+
+public class MyPersistence : PersistenceDefinition
+{
+}

Snippets/TransactionalSession/TransactionalSession_3.3/MyPersistenceOpenSessionOptions.cs

@@ -0,0 +1,5 @@
+using NServiceBus.TransactionalSession;
+
+class MyPersistenceOpenSessionOptions : OpenSessionOptions
+{
+}

Snippets/TransactionalSession/TransactionalSession_3.3/TransactionalSession_3.3.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="NServiceBus.TransactionalSession" Version="3.3.0" />
+  </ItemGroup>
+</Project>

nservicebus/transactional-session/index.md

@@ -8,7 +8,7 @@ related:
 - samples/transactional-session/cosmosdb
 ---
 
-This article describes how to achieve consistency when modifying business data and sending messages, similar to the [outbox](/nservicebus/outbox), outside the context of an NServiceBus message handler.
+This article describes how to achieve consistency when modifying business data and sending messages, similar to the [outbox](/nservicebus/outbox), but outside the context of an NServiceBus message handler.
 
 youtube: https://www.youtube.com/watch?v=-UOyxjnlYXs
 
@@ -58,11 +58,13 @@ Once all the operations that are part of the atomic request have been executed,
 
 snippet: committing-transactional-session
 
-Disposing the transactional session without committing will roll back any changes that were made.
+Disposing of the transactional session without committing will roll back any changes that were made.
 
 > [!NOTE]
 > The `Commit` operation may fail and throw an exception for reasons outlined in the [failure scenarios section](#failure-scenarios).
 
+partial: remote-processor
+
 ## Requirements
 
 The transactional session feature requires a supported persistence package to store outgoing messages. This feature is currently supported for the following persistence packages:
@@ -73,6 +75,7 @@ The transactional session feature requires a supported persistence package to st
 * [NHibernate](/persistence/nhibernate)
 * [RavenDB](/persistence/ravendb)
 * [MongoDB](/persistence/mongodb)
+* [DynamoDB](/persistence/dynamodb/)
 
 ## Transaction consistency
 
@@ -87,7 +90,7 @@ With the outbox disabled, database and message operations are not applied until
 
 The transactional session feature guarantees that all outgoing message operations are eventually consistent with the data operations.
 
-Returning to the earlier example of a message handler which creates a `User` and then publishes a `UserCreated` event, the following process occurs. Details are described following the diagram.
+Returning to the earlier example of a message handler that creates a `User` and then publishes a `UserCreated` event, the following process occurs. Details are described following the diagram.
 
 ```mermaid
 sequenceDiagram
@@ -169,20 +172,35 @@ The endpoint receives the control message and processes it as follows:
 
 ## Failure scenarios
 
-The transactional session provides atomic store-and-send guarantees, similar to the outbox feature (except for incoming message de-duplication). The control message is used to ensure that **exactly one** of the following outcomes occur:
+The transactional session provides atomic store-and-send guarantees, similar to the outbox feature (except for incoming message de-duplication). The control message is used to ensure that **exactly one** of the following outcomes occurs:
 
 * Transaction finishes with data being stored, and outgoing messages eventually sent - when the `Commit` path successfully stores the `OutboxRecord`
 * Transaction finishes with no visible side effects - when the control message stores the `OutboxRecord`
 
-Sending the control message first ensures that eventually, the transaction will have an atomic outcome. If the `Commit` of the `OutboxRecord` succeeds, the control message will ensure the outgoing operations are sent. If the `Commit` fails, the control message will (after the [maximum commit duration](#advanced-configuration-maximum-commit-duration) elapses) eventually be consumed, leaving no side effects.
+Sending the control message first ensures that eventually, the transaction will have an atomic outcome. If the `Commit` of the `OutboxRecord` succeeds, the control message will ensure the outgoing operations are sent. 
+
+### Failure to dispatch the control message
 
 If dispatching the control message fails, the transactional session changes will roll back, and an error will be raised to the user committing the session.
 
-If the transaction completes and the control message fails to process through all the retry attempts, the control message will be moved to the error queue, and the outgoing messages will not be dispatched. Once the error is resolved, the control message must be manually retried in ServicePulse to ensure the outgoing messages are dispatched. If this doesn't happen, the stored outgoing messages will never delivered. If that's undesirable, the system should be returned to a consistent state through another action.
+If the transaction completes and the control message fails to process through all the retry attempts, the control message will be moved to the error queue, and the outgoing messages will not be dispatched. Once the error is resolved, the control message must be manually retried in ServicePulse to ensure the outgoing messages are dispatched. If this doesn't happen, the stored outgoing messages will never be delivered. If that's undesirable, the system should be returned to a consistent state through another action.
+
+### Failure to commit the outbox record
+
+If the `Commit` fails, the control message will (after the [maximum commit duration](#advanced-configuration-maximum-commit-duration) elapses) eventually be consumed, leaving no side effects.
+
+### Commit takes too long
+
+When the commit takes longer than the [maximum commit duration](#advanced-configuration-maximum-commit-duration) the control message will result in a tombstone record in the outbox preventing the commit to succeed. The following exception is thrown:
+
+`Failed to commit the transactional session. This might happen if the maximum commit duration is exceeded`
+
+A variation of this is when using a remote processing endpoint that does not have the transactional session enabled. In this scenario, the tombstone record will be created immediately when the control message is processed, forcing a rollback of the commit. When this happens, the following exception is thrown:
+
+`Failed to commit the transactional session. This might happen if the maximum commit duration is exceeded or if the transactional session has not been enabled on the configured processor endpoint - MyProcessorEndpoint`
 
 ## Limitations
 
-* The transactional session cannot be used in send-only endpoints. A full endpoint is required to send a control message to the local queue.
 * The transport must have the same or higher availability guarantees as the database.
 
 ## Advanced configuration

…_transactionalsession_[3.1, ).partial.md …g_transactionalsession_[3.1,).partial.mdnservicebus/transactional-session/index_config_transactionalsession_[3.1, ).partial.md renamed to nservicebus/transactional-session/index_config_transactionalsession_[3.1,).partial.md nservicebus/transactional-session/index_config_transactionalsession_[3.1, ).partial.md renamed to nservicebus/transactional-session/index_config_transactionalsession_[3.1,).partial.md

@@ -1,4 +1,3 @@
-
 #### CommitDelayIncrement
 
 The time increment used to delay the commit of the transactional session when the outbox record is not yet in the storage (more details see [Phase 2](#how-it-works-phase-2)).

nservicebus/transactional-session/index_remote-processor_transactionalsession_[3.3,).partial.md

@@ -0,0 +1,47 @@
+## Send-only 
+
+When used in a [send-only](/nservicebus/hosting/#self-hosting-send-only-hosting) endpoint, the transactional session must be configured with a remote endpoint(processor endpoint) that will manage the outbox on behalf of the send-only endpoint.
+
+snippet: configure-remote-processor
+
+> [!WARNING]
+> Both the send-only endpoint and the processor endpoint must be connected to the same database. See [documentation for the individual persisters](/persistence/) for more details.
+
+> [!NOTE]
+The processor endpoint [must have both the outbox and the transactional session enabled](/nservicebus/transactional-session/#failure-scenarios-commit-takes-too-long).
+
+> [!NOTE]
+> If migrating to this mode from an endpoint couldn't be made send-only due to the previous limitations of the transactional session, see the migration guidance below.
+
+### Outbox cleanup
+
+For persisters where [Outbox cleanup](/nservicebus/outbox/#outbox-expiration-duration) is performed by the endpoint instances, only the remote processing endpoint should have the cleanup enabled to prevent concurrent cleanup from happening.
+
+Applies to:
+
+- SQL Persistence
+- NHibernate
+
+### Migration to send-only endpoint mode
+
+For endpoints that previously couldn't be send-only because of the transactional session limitations, you can use the following procedure to migrate your endpoint.
+
+#### Preparation
+
+1. Ensure that no message handlers exist in the endpoint
+1. Deploy a new processor endpoint
+1. Stop the endpoint and ensure that all messages in the input queue are consumed
+
+#### Configuration
+
+1. Make the endpoint send only
+1. Configure the endpoint to use the new processor endpoint as shown above
+1. Start the endpoint
+
+> [!NOTE]
+> The send-only endpoint will now use the outbox of the new processor endpoint. Since [message deduplication is not possible when using the transactional session](https://github.com/Particular/NServiceBus.TransactionalSession/issues/97), no data migration is needed
+
+#### Cleanup
+
+1. Remove the no longer used input queue of the send-only endpoint
+1. As needed, remove any database artefacts (tables, documents, etc) related to the send-only endpoint.  See [documentation for the individual persisters](/persistence/) for more details.

persistence/ravendb/outbox.md

@@ -15,9 +15,9 @@ include: cluster-configuration-info
 
 The [Outbox](/nservicebus/outbox) feature requires persistence in order to store messages and enable deduplication.
 
-## Extra collections created by the RavenDB Outbox persistence
+## Storage format
 
-To keep track of duplicate messages, the RavenDB implementation of Outbox creates a special collection of documents called `OutboxRecord`.
+The persister stores outbox data for all endpoints in a [collection](https://ravendb.net/docs/article-page/7.0/csharp/client-api/faq/what-is-a-collection) called `OutboxRecords`. To separate data for individual endpoints stored documents will have their endpoint name embedded in the document ID using the following format `Outbox/{Endpoint-name}/{Message-id}`.
 
 ## Deduplication record lifespan