Clarifies cancellation token behavior

Explains how cancellation tokens are used during resource creation and
publish/subscribe operations to prevent unexpected behavior, such as
prematurely aborting infrastructure setup. This ensures that resource
creation only aborts when the message bus or queue is disposed, not
due to individual caller cancellations.

Provides guidance for implementation authors regarding the use of
`DisposedCancellationToken` for setup operations and linked tokens
for message sending and queue operations.

Author: niemyjski

docs/guide/messaging.md

@@ -755,6 +755,39 @@ await messageBus.SubscribeAsync<OrderCreated>(async order =>
 });
 ```
 
+## Cancellation Token Behavior
+
+Understanding how cancellation tokens are handled internally is important for building reliable publishers and subscribers.
+
+### Resource Creation Uses Disposal Token
+
+When you call `PublishAsync` or `SubscribeAsync`, the message bus may need to create infrastructure (e.g., Azure Service Bus topics, RabbitMQ exchanges, SQS topics). These setup operations use an internal disposal token — **not** the caller's cancellation token. This means:
+
+- **Topic and subscription creation only abort when the message bus is disposed**, never because a single caller cancelled their operation.
+- A cancelled publish will not leave topic infrastructure in a half-created state.
+- Multiple concurrent publishers/subscribers cannot interfere with each other's setup.
+
+### Linked Cancellation for Publish
+
+The caller's cancellation token is combined with the disposal token into a linked token for the actual publish operation. This means:
+
+- Publish cancels when **either** the caller cancels **or** the message bus is disposed.
+- Graceful shutdown via `Dispose()` cancels all in-flight publishes promptly.
+
+```csharp
+// Topic creation always completes (unless disposed), even if the publish is cancelled
+using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+await messageBus.PublishAsync(new OrderCreated { OrderId = 123 }, cancellationToken: cts.Token);
+```
+
+### For Implementation Authors
+
+If you are writing a custom `IMessageBus` implementation by extending `MessageBusBase<TOptions>`:
+
+- **`EnsureTopicCreatedAsync`** always receives `DisposedCancellationToken`. Use it for all setup operations (lock acquisition, API calls, etc.).
+- **`EnsureTopicSubscriptionAsync`** always receives `DisposedCancellationToken`. Use it for subscription infrastructure setup.
+- **`PublishImplAsync`** receives a linked token (caller + disposal). Respect it for the actual message send.
+
 ## Best Practices
 
 ### 1. Use Immutable Messages

docs/guide/queues.md

@@ -788,6 +788,42 @@ catch (QueueException ex)
 }
 ```
 
+## Cancellation Token Behavior
+
+Understanding how cancellation tokens are handled internally is important for building reliable queue consumers.
+
+### Resource Creation Uses Disposal Token
+
+When you call `EnqueueAsync`, `DequeueAsync`, or `GetDeadletterItemsAsync`, the queue may need to create infrastructure (e.g., SQS queues, Azure Service Bus queues, Redis streams). These setup operations use an internal disposal token — **not** the caller's cancellation token. This means:
+
+- **Queue creation only aborts when the queue is disposed**, never because a single caller cancelled their operation.
+- A cancelled `DequeueAsync` call (e.g., from a zero timeout) will not prevent queue creation from completing.
+- Multiple concurrent callers cannot interfere with each other's setup.
+
+### Linked Cancellation for Operations
+
+The caller's cancellation token is combined with the disposal token into a linked token for the actual operation (dequeue, deadletter retrieval, etc.). This means:
+
+- Operations cancel when **either** the caller cancels **or** the queue is disposed.
+- Graceful shutdown via `Dispose()` cancels all in-flight operations promptly.
+
+```csharp
+// This will never prevent queue creation, even though it times out immediately
+var entry = await queue.DequeueAsync(TimeSpan.Zero);
+
+// The cancellation token only affects the dequeue wait, not infrastructure setup
+using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+var entry = await queue.DequeueAsync(cts.Token);
+```
+
+### For Implementation Authors
+
+If you are writing a custom `IQueue<T>` implementation by extending `QueueBase<T>`:
+
+- **`EnsureQueueCreatedAsync`** always receives `DisposedCancellationToken`. Use it for all setup operations (lock acquisition, API calls, etc.).
+- **`DequeueImplAsync`** receives a linked token (caller + disposal). Respect it for the wait/poll operation.
+- **`EnqueueImplAsync`** does not receive a cancellation token — keep enqueue fast and non-blocking.
+
 ## Best Practices
 
 ### 1. Proper Resource Disposal

src/Foundatio/Messaging/MessageBusBase.cs

@@ -65,6 +65,11 @@ protected CancellationTokenSource GetLinkedDisposableCancellationTokenSource(Can
     TimeProvider IHaveTimeProvider.TimeProvider => _timeProvider;
     IResiliencePolicyProvider IHaveResiliencePolicyProvider.ResiliencePolicyProvider => _resiliencePolicyProvider;
 
+    /// <summary>
+    /// Called before publishing to ensure the topic exists. The <paramref name="cancellationToken"/>
+    /// is always <see cref="MaintenanceBase.DisposedCancellationToken"/>; topic creation should only
+    /// abort when the message bus is being disposed, never due to an individual caller's cancellation.
+    /// </summary>
     protected virtual Task EnsureTopicCreatedAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 
     protected abstract Task PublishImplAsync(string messageType, object message, MessageOptions options, CancellationToken cancellationToken);
@@ -84,12 +89,13 @@ public async Task PublishAsync(Type messageType, object message, MessageOptions
                 options.Properties.Add("TraceState", Activity.Current.TraceStateString);
         }
 
-        using var linkedCancellationTokenSource = GetLinkedDisposableCancellationTokenSource(cancellationToken);
         try
         {
             // Use DisposedCancellationToken for setup: topic creation should only abort on disposal,
             // not due to an individual caller's cancellation token.
             await EnsureTopicCreatedAsync(DisposedCancellationToken).AnyContext();
+
+            using var linkedCancellationTokenSource = GetLinkedDisposableCancellationTokenSource(cancellationToken);
             await PublishImplAsync(GetMappedMessageType(messageType), message, options, linkedCancellationTokenSource.Token).AnyContext();
         }
         catch (Exception ex) when (ex is not OperationCanceledException and not MessageBusException)
@@ -147,6 +153,12 @@ protected virtual Type GetMappedMessageType(string messageType)
     }
 
     protected virtual Task RemoveTopicSubscriptionAsync() => Task.CompletedTask;
+    /// <summary>
+    /// Called after subscribing to ensure the topic subscription infrastructure exists. The
+    /// <paramref name="cancellationToken"/> is always <see cref="MaintenanceBase.DisposedCancellationToken"/>;
+    /// subscription setup should only abort when the message bus is being disposed, never due to
+    /// an individual caller's cancellation.
+    /// </summary>
     protected virtual Task EnsureTopicSubscriptionAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 
     protected virtual Task SubscribeImplAsync<T>(Func<T, CancellationToken, Task> handler, CancellationToken cancellationToken) where T : class

src/Foundatio/Queues/QueueBase.cs

@@ -123,6 +123,11 @@ public void AttachBehavior(IQueueBehavior<T> behavior)
         behavior.Attach(this);
     }
 
+    /// <summary>
+    /// Called before queue operations to ensure the queue exists. The <paramref name="cancellationToken"/>
+    /// is always <see cref="MaintenanceBase.DisposedCancellationToken"/>; queue creation should only
+    /// abort when the queue is being disposed, never due to an individual caller's cancellation.
+    /// </summary>
     protected abstract Task EnsureQueueCreatedAsync(CancellationToken cancellationToken = default);
 
     protected abstract Task<string> EnqueueImplAsync(T data, QueueEntryOptions options);