Question about singleton ICapPublisher and transaction safety

[xingyi5990]

Hi, I have a question regarding CAP. Currently, ICapPublisher is registered as a singleton. Can I safely assign a value directly to ICapPublisher.Transaction? How does CAP ensure that, even though ICapPublisher is a singleton, transactions remain isolated and do not conflict across multiple concurrent requests?

For example, in a high-concurrency scenario where multiple requests start MongoDB transactions simultaneously, each request might call StartTransaction on the singleton ICapPublisher. I am curious how CAP guarantees that these transactions are isolated and do not interfere with each other.

[yang-xiaodong]

Answer from ChatGPT

---

Short answer

• Yes, it’s safe to start/attach a transaction from a singleton ICapPublisher.
• CAP keeps transactions isolated across concurrent requests by storing the “current transaction” in an async-flow-local context (AsyncLocal), not on the singleton instance itself.

How CAP makes this safe

• ICapPublisher is registered as a singleton but is effectively stateless.
• The Transaction you see on ICapPublisher is backed by a per-async-context accessor (think “ambient transaction”). Internally this is stored using AsyncLocal, so each request (each logical async flow) gets its own transaction reference.
• When you call Begin/StartTransaction (EF Core, ADO.NET, MongoDB, etc.), CAP wraps the underlying transaction/session (e.g., DbTransaction, IClientSessionHandle) in an ICapTransaction and sets it into that AsyncLocal slot for the current async context.
• Publish/PublishAsync reads the “current transaction” from that accessor; messages are written to the outbox within the same DB transaction/session and commit/rollback together with your business transaction.
• On commit/rollback/dispose, CAP clears the ambient transaction so it doesn’t leak to other code paths.

Practical guidance

• Prefer the provider-specific helpers instead of manually setting the property:
  • EF Core: use the CAP EF extension (e.g., database.BeginTransaction(_capPublisher, autoCommit: true)) so CAP and your DbContext share the same transaction automatically.
  • MongoDB: create an IClientSessionHandle, start a transaction, then use CAP’s Begin/UseTransaction overload for Mongo to bind the session to CAP for the current async flow.
• You generally shouldn’t cache or reuse ICapTransaction across requests, nor set Transaction outside the scope where you control commit/rollback.
• Be mindful when you start parallel work within the same request:
  • AsyncLocal flows with the logical async context. If you intentionally run multiple parallel operations that should have different transactions, create/separate the transaction scopes appropriately.
  • For fire-and-forget/background work, start it after your request transaction completes, or explicitly create a new scope/transaction for that work.

Edge cases to avoid

• Don’t share a transaction object across threads or requests.
• Don’t start background work that accidentally “inherits” the current request’s AsyncLocal transaction unless that’s intended. Make transaction boundaries explicit in such cases.

Bottom line
Even though ICapPublisher is a singleton, CAP binds transactions to the current async execution context via AsyncLocal, so concurrent requests each see their own transaction. Use CAP’s transaction helpers for your data provider to ensure proper binding and cleanup, and you’ll have the isolation you expect—even under high concurrency with MongoDB or EF Core.

[xingyi5990]

Thanks for the clarification! Now I understand how it works. Really appreciate your help