# IMPORTANT
This doc is no longer maintained. Please see current version on https://github.com/couchbaselabs/couchbase-transactions-specs/

# Couchbase Transactions ATR Stages
Contains all transactions protocol logic related to writing ATRs.

## Binary Document
The transactional metadata documents (e.g. all those starting `_txn:`) are intended to be binary documents.

ExtBinaryMetadata details that the document body should be binary.

ExtBinarySupport goes further and details that the document's user flags should also be set to the binary common flags, whenever the ATR is written.

## SetATRPending
This is done before the first mutation in a transaction.
This is the point where the ATR entry for the attempt is created.

* If not in ExpiryOvertimeMode: if transaction has expired (stage name is "atrPending"), raise an AttemptExpired, which will be handled by the error block in this section.
* Call debug hook `beforeAtrPending`, passing this AttemptContext and the documents's key.
* Perform the mutation:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.UPSERT, durability as per the transaction's config.
* Prefix for all these fields is "attempts.ATTEMPT_ID.". They are all performed as xattr:
* Insert "tid" with transactionId (not attemptId). Use createPath for this.
* Insert "st" with "PENDING".
* Insert "tst" with "${Mutation.CAS}" (a Mutation Macro that will be expanded to the CAS of this mutation).
* Insert "exp" with transaction’s expiration time in millis in field “exp”.
* Protocol 1.0: This is the absolute expiration time set in the configuration, ignoring any already-expired time (which is likely to be negligible). By default this is 15 seconds so what would be written is `"exp:":15000`. None of the other fields in Active Transaction Record Metadata are to be written at this point. Note there is a [bug](https://issues.couchbase.com/browse/CBD-3381) to remedy here.
* Protocol 2.0: Use [Time Remaining](#Time-Remaining)
* ExtStoreDurability: Insert "d" with the configured durability level:
* MAJORITY -> "m"
* MAJORITY_AND_PERSIST_TO_ACTIVE -> "pa"
* PERSIST_TO_MAJORITY -> "pm"
* NONE -> "n"
* ExtBinaryMetadata: Replace "" (the document body), with a byte array of length 1, containing a single null byte. With SDK3 a MutateInSpec.Replace results in a SET (0x1) spec being sent. This is not performed as an xattr operation.
* ExtBinarySupport: set the document's user flags to binary common flags (note that this needs to be done wherever an ATR is written).
* On success, call hook `afterAtrPending`, passing this AttemptContext and the documents's key.
* On error err (from any of the preceding items in this section), classify as error class ec then:
* If in ExpiryOvertimeMode -> `Error(FAIL_EXPIRY, AttemptExpired(err), rollback=false, raise=TRANSACTION_EXPIRED)`
* Else FAIL_EXPIRY -> set ExpiryOvertimeMode and raise `Error(ec, AttemptExpired(err), raise=TRANSACTION_EXPIRED)`
* Else FAIL_ATR_FULL -> `Error(ec, ActiveTransactionRecordFull(err))`
* Else FAIL_AMBIGUOUS -> A little tricky. If we raise an error, then this op won’t be rolled back as we’re in NOTHING_WRITTEN state. So, retry the op from the top of this algo, after OpRetryDelay.
* Else FAIL_PATH_EXISTS -> We’re using UUIDs, so either the very-unlikely has happened and two attempts have created the same UUID in the same ATR at the same time period, or, rather more likely, we tried the op on FAIL_AMBIGUOUS and it turns out it was successful. In this case, process as though the op was successful (see handling, below).
* Else FAIL_HARD -> Error(ec, err, rollback=false)
* Else FAIL_TRANSIENT -> Error(ec, err, retry=true)
* Else -> `Error(ec, err)`
* Else (success):
* Set state to PENDING.
* ExtSDKIntegration: add this ATR collection to `cleanupSet`. See [Couchbase Transactions Cleanup](/w5hsXGwYTRmv2IxBfAoORw).

## SetATRCommit
This marks the "point of no return" for the transaction. Error handling before and after this stage are very different. Before the transaction commits, it can be safely rolled back and retried. Afterwards, due to MAV reads, another actor may have seen the committed data from this transaction. It is no longer possible to rollback, we can go only go forwards.

The transaction is conceptually fully committed after this stage. If all Couchbase components could do MAV reads, then the unstaging of the documents themselves could be seen purely as cleanup.

Protocol 1 and BF_CBD_3838: This routine has a boolean parameter`ambiguityResolutionMode`, defaulting to false.
* BF_CBD_3838: There are two forms of ambiguity resolution when committing the ATR:
* `ambiguityResolutionMode`: hit FAIL_AMBIGUOUS and are in the process of retrying the write.
* path-exists resolution: found the "p" field has already been written, and need to find out what's happened.

The algo:
* If transaction has expired (stage name is "atrCommit"), and not in ExpiryOvertimeMode, raise an AttemptExpired, which will be handled by the error block in this section.
* Call debug hook `beforeAtrCommit`, passing this AttemptContext.
* Perform the mutation:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Prefix for all these fields is "attempts.ATTEMPT_ID.". They are all performed as xattr:
* Upsert "st" with "COMMITTED".
* Upsert "tsc" with "${Mutation.CAS}" (a Mutation Macro that will be expanded to the CAS of this mutation). This is just for debugging and potentially future requirements, it's not used currently by the protocol.
* Upsert "ins" with an array of all INSERTs from `stagedMutations`. This will be used by cleanup if anything goes wrong. Each INSERT is written as this JSON:
* {"id":<document's id>,"bkt",<document's bucket name>,"scp",<document's scope name>,"col":<document's collection name>}
* Upsert "rep" with an array of all REPLACEs from `stagedMutations`. Write same as INSERTs.
* Upsert "rem" with an array of all REMOVEs from `stagedMutations`. Write same as INSERTs.
* Protocol 2: Insert "p" with a value of 0. This is used to prevent (unlikely) conflicts with the cleanup process. Historical note: added in [TXNJ-108](https://issues.couchbase.com/browse/TXNJ-108)
* On success, call hook `afterAtrCommit`, passing this AttemptContext.
* On error err (from any of the preceding items in this section), classify as error class ec then:
* FAIL_EXPIRY ->
* Protocol 1:
* If ambiguityResolutionMode==true, we were unable to attain clarity over whether we reached committed or not. Set ExpiryOvertimeMode and raise `Error(ec, AttemptExpired(err), raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else, we unambiguously were not able to set the ATR to Committed. Set ExpiryOvertimeMode and raise `Error(ec, AttemptExpired(err), raise=TRANSACTION_EXPIRED)`
* Else if BF_CBD_3838:
* (This is the same as the Protocol 1 logic but without ExpiryOvertimeMode, which is in the process of being removed, and hence without rollback.)
* If ambiguityResolutionMode==true raise `Error(ec, AttemptExpired(err), rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else `Error(ec, AttemptExpired(err), rollback=false, raise=TRANSACTION_EXPIRED)`
* Else:
* We unambiguously were not able to set the ATR to Committed. Set ExpiryOvertimeMode and raise `Error(ec, AttemptExpired(err), raise=TRANSACTION_EXPIRED)`
* Else FAIL_AMBIGUOUS ->
* Ambiguity resolution is very important here, and we cannot proceed until we are certain. E.g. if the op succeeded then we are past the point of no return and must commit.
* Protocol 1 or BF_CBD_3838:
* Repeat the SetATRCommit step from the top to retry the idempotent commit step, with ambiguityResolutionMode=true, after waiting [OpRetryDelay](#OpRetryDelay).
* Protocol 2:
* Perform the [SetATRCommit Ambiguity Resolution](#SetATRCommit-Ambiguity-Resolution) logic.
* Else FAIL_HARD ->
* If BF_CBD_3838 and ambiguityResolutionMode==true:
* We were unable to attain clarity over whether we reached committed or not. Raise `Error(ec, rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else raise `Error(ec, rollback=false, err)`
* Else FAIL_TRANSIENT ->
* If BF_CBD_3838 and ambiguityResolutionMode==true:
* We haven't yet reached clarity on what state this attempt is in, so we can't rollback or continue.
* Repeat the SetATRCommit step from the top, passing the current `ambiguityResolutionMode`, after waiting [OpRetryDelay](#OpRetryDelay).
* Else: raise `error(ec, err, retry=true)`
* Else if BF_CBD_3838 and FAIL_PATH_ALREADY_EXISTS ->
* The "p" field we tried to insert, has been inserted already. There could be multiple reasons:
* Previously tried the write and it failed with FAIL_AMBIGUOUS but actually succeeded - in which case it is fine to proceed.
* Cleanup has hit the [TXNJ-108](https://issues.couchbase.com/browse/TXNJ-108) case and ABORTed this transaction - in which case we should not proceed.
* Some future actor has ABORTed us. This is not currently part of the protocol, but may well be later.
* Either way, we need to fetch the current state and decide how to proceed. Perform the [SetATRCommit Ambiguity Resolution](#SetATRCommit-Ambiguity-Resolution) logic. This is the path-exists form of ambiguity resolution.
* Else ->
* If BF_CBD_3838:
* `cause` = `err`
* `rollback` = true
* If FAIL_DOC_NOT_FOUND -> cause = ActiveTransactionRecordNotFound; rollback = false
* Else if FAIL_PATH_NOT_FOUND -> cause = ActiveTransactionRecordEntryNotFound; rollback = false
* Else if FAIL_ATR_FULL -> cause = ActiveTransactionRecordFull; rollback = false
* (We don't rollback on these three errors, because rollback will likely hit the same issue. Bailout and leave for cleanup.)
* If ambiguityResolutionMode==true:
* We were unable to attain clarity over whether we reached committed or not. Raise `Error(ec, cause=cause, rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else raise `Error(ec, cause=cause, rollback=rollback, err)`
* Else raise `Error(ec, err)`
* Else (success): set state to COMMITTED

## SetATRCommit Ambiguity Resolution
We've tried to set COMMITTED state but discovered, via the "p" field, that something has already set this transaction's state. The transaction cannot proceed until we're unambiguously certain what happened.

There's a couple of things to be careful of, that the algo below should ensure:
* Should not rollback unless we're certain the transaction is not in COMMITTED state.
* Should raise TRANSACTION_COMMIT_AMBIGUOUS if transaction expires and we're not certain on its status.

The algo:
* If transaction has expired, and not in ExpiryOvertimeMode, raise an AttemptExpired, which will be handled by the error block in this section.
* Call debug hook `beforeAtrCommitAmbiguityResolution`, passing this AttemptContext.
* Perform a KV lookupIn:
* Sub-Document lookupIn on the chosen ATR id.
* Pass a single xattr LookupInSpec.get spec, for field "attempts.ATTEMPT_ID.st".
* Use a set [RetryStrategy](#RetryStrategy).
* On success, take action based on the status field:
* If BF_CBD_3838:
* "COMMITTED" -> The ambiguous operation actually succeeded. Continue as success, e.g. proceed with the rest of committing.
* "ABORTED" -> Another actor has aborted this transaction under us. We will rollback and retry. Raise an `Error(ec = FAIL_OTHER, retry=true)`. (While nothing in the protocol can _currently_ abort another transaction, it's a strong contender for a future feature.)
* Else (including any unknown status) -> Shouldn't happen with current protocol, but perhaps a future extension has done something interesting that we don't know how to be compatible with. Bailout and leave the transaction for cleanup by raising `Error(ec = FAIL_OTHER, rollback=false, cause=IllegalStateException)`. (No need to raise TransactionCommitAmbiguous here - it's unambigously failed pre-commit.)
* Else:
* "COMMITTED" -> The ambiguous operation actually succeeded. Return success.
* "PENDING" -> The ambiguous operation did not succeed. Restart from the top of [SetATRCommit](#SetATRCommit).
* "ABORTED" | "ROLLED_BACK" -> Another actor has aborted this transaction under us. Raise an `Error(ec = FAIL_OTHER, rollback=false, cause=TransactionAbortedExternally)`
* Else -> Unknown status, perhaps from a future protocol or extension. Bailout and leave the transaction for cleanup by raising `Error(ec = FAIL_OTHER, rollback=false, cause=IllegalStateException [or platform-specific equivalent])`. See [CBD-3838](https://issues.couchbase.com/browse/CBD-3838) for discussion on why COMPLETED state is included here.
* On error err (from any of the preceding items in this section), classify as error class ec then:
* FAIL_EXPIRY ->
* We were unable to attain clarity over whether we reached committed or not. It is important to not rollback here as we possibly got to committed.
* If not BF_CBD_3838: Set ExpiryOvertimeMode. (BF_CBD_3838 does not do ExpiryOvertimeMode as that is being deprecated. Though since we are doing rollback=false here it has no real impact either way.)
* Raise `Error(ec, cause=AttemptExpired(err), rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else FAIL_HARD ->
* If BF_CBD_3838: Raise `Error(ec, err, rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else: Error(ec, err, rollback=false)
* Else FAIL_TRANSIENT | FAIL_OTHER -> We can't proceed until we're resolved the ambiguity or expired, so retry from the top of this section, after waiting [OpRetryDelay](#OpRetryDelay).
* Else ->
* If BF_CBD_3838:
* `cause` = `err`
* `rollback` = true
* If FAIL_DOC_NOT_FOUND -> cause = ActiveTransactionRecordNotFound; rollback = false
* Else if FAIL_PATH_NOT_FOUND -> cause = ActiveTransactionRecordEntryNotFound; rollback = false
* Raise `Error(ec, err, rollback=false, raise=TRANSACTION_COMMIT_AMBIGUOUS)`
* Else: raise `Error(ec, err, rollback=false)`

## SetATRComplete
The transaction has successfully finished the commit, e.g. all documents are committed. This step is only needed so that the cleanup process doesn’t confuse this for an expired, incomplete transaction - in which case it will try to commit the documents.

Future improvement: We could consider removing this step, and instead delete the ATR entry (which also avoids the subsequent need to remove the entry, saving two writes). It needs thought to consider how it overlaps with other parts of the algorithm that make use the existence or not of the ATR entry as a signal.

* If transaction has expired and not in ExpiryOvertimeMode: though technically expired, the transaction should be regarded as successful, as this is just a cleanup step. Return success.
* Call debug hook `beforeAtrComplete`, passing this AttemptContext.
* Perform the mutation:
* If EXT_REMOVE_COMPLETED:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Remove "attempts.ATTEMPT_ID" as an xattr.
* Else:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Prefix for all these fields is "attempts.ATTEMPT_ID.". They are all performed as xattr:
* Upsert "st" with "COMPLETED".
* Upsert "tsco" with "${Mutation.CAS}" (a Mutation Macro that will be expanded to the CAS of this mutation). This is just for debugging and potentially future requirements, it's not used currently by the protocol.
* On success, call hook `afterAtrComplete`, passing this AttemptContext.
* On success, set state to COMPLETED.
* On error err (from any of the preceding items in this section), classify as error class ec then:
* FAIL_HARD -> Error(ec, err, rollback=false, raise=TRANSACTION_FAILED_POST_COMMIT)
* Else -> Setting the ATR to COMPLETED is purely a cleanup step, there's no need to retry it until expiry. Simply return success (leaving state at COMMITTED, or COMPLETED/removed if the error was a successful FAIL_AMBIGUOUS).
* Note this will leave `TransactionResult::unstageCompleted()` returning false, even though a use of `TransactionResult::mutationState()` would be fine. Fixing this issue would require the complexity of maintaining additional mutable state. We will monitor if this is a problem in real deployments and can consider returning to this.
* A FAIL_AMBIGUOUS could leave the ATR state as COMPLETED but the in-memory state as COMMITTED. This shouldn't cause any problems.

## SetATRAborted
This method takes one boolean parameter:
* `isAppRollback` - indicating whether it was initiated by a `ctx.rollback()`.
* ExtThreadSafety: if false, then any `TransactionOperationFailed` raised by this section, does _not_ set internal state bits. (The user does not care about problems that happen during auto-rollback.)

The algo is:
* If not in ExpiryOvertimeMode, if transaction has expired, raise an AttemptExpired internal exception which will be handled by the error handling block of this section.
* Call debug hook `beforeAtrAborted`, passing this AttemptContext.
* Perform the mutation:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Prefix for all these fields is "attempts.ATTEMPT_ID.". They are all performed as xattr:
* Upsert "st" with "ABORTED".
* Upsert "tsrs" with "${Mutation.CAS}" (a Mutation Macro that will be expanded to the CAS of this mutation). This is just for debugging and potentially future requirements, it's not used currently by the protocol.
* Upsert "ins" with an array of all INSERTs from `stagedMutations`. This will be used by cleanup if anything goes wrong. Write it in the same style as in [SetATRCommit](#SetATRCommit)
* Upsert "rep" with an array of all REPLACEs from `stagedMutations`. Write same as INSERTs.
* Upsert "rem" with an array of all REMOVEs from `stagedMutations`. Write same as INSERTs.
* On success, call hook `afterAtrAborted`, passing this AttemptContext.
* On error err (from any of the preceding items in this section), classify as error class ec then:
* If in ExpiryOvertimeMode -> `Error(FAIL_EXPIRY, cause=AttemptExpired(err), rollback=false, raise=TRANSACTION_EXPIRED)`
* Else if `FAIL_EXPIRY` -> set ExpiryOvertimeMode and retry operation, after waiting [OpRetryBackoff](#OpRetryBackoff). We want to make one further attempt to complete the rollback.
* Else `FAIL_PATH_NOT_FOUND` ->
Perhaps we're trying to rollback an ATR entry after failing trying to create it. Perhaps, the cleanup process has removed the entry, as it was expired. Neither of these should happen, so we should bailout as we're now in a strange state. `Error(ec, cause=ActiveTransactionRecordEntryNotFound, rollback=false)`
* Else `FAIL_DOC_NOT_FOUND` -> The ATR has been deleted, or we're trying to rollback an attempt that failed to create a new ATR. Neither should happen, so bailout. `Error(ec, cause=ActiveTransactionRecordNotFound, rollback=false)`
* Else `FAIL_ATR_FULL` -> Bailout to reduce pressure on ATRs. `Error(ec, cause=ActiveTransactionRecordFull, rollback=false)`
* Else `FAIL_HARD` -> Error(ec, err, rollback=false)
* Else -> Default current logic is that rollback will continue in the event of failures until expiry. Retry operation, after waiting [OpRetryBackoff](#OpRetryBackoff). Takes care of `FAIL_AMBIGUOUS`.
* On success: set state to ABORTED

## SetATRRolledBack
This method takes one boolean parameter:
* `isAppRollback` - indicating whether it was initiated by a `ctx.rollback()`.
* ExtThreadSafety: if false, then any `TransactionOperationFailed` raised by this section, does _not_ set internal state bits. (The user does not care about problems that happen during auto-rollback.)

The algo:
* If not in ExpiryOvertimeMode, if transaction has expired, raise an AttemptExpired internal exception which will be handled by the error handling block of this section.
* Call debug hook `beforeAtrRolledBack`, passing this AttemptContext.
* Perform the mutation:
* If EXT_REMOVE_COMPLETED:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Remove "attempts.ATTEMPT_ID" as an xattr.
* Else:
* Sub-Document mutation on the chosen ATR id, StoreSemantics.REPLACE, durability as per the transaction's config.
* Prefix for all these fields is "attempts.ATTEMPT_ID.". They are all performed as xattr:
* Upsert "st" with "ROLLED_BACK".
* Upsert "tsrc" with "${Mutation.CAS}" (a Mutation Macro that will be expanded to the CAS of this mutation). This is just for debugging and potentially future requirements, it's not used currently by the protocol.
* On success, call hook `afterAtrRolledBack`, passing this AttemptContext.
* On error `err` (from any of the preceding items in this section), classify as error class `ec` then:
* If EXT_REMOVE_COMPLETED:
* If in ExpiryOvertimeMode -> `Error(FAIL_EXPIRY, cause=AttemptExpired(err), rollback=false, raise=TRANSACTION_EXPIRED)`
* Else if `FAIL_EXPIRY` ->
* Expiry overtime mode is not being added to new code, so simply:
* Raise `Error(ec, err, rollback=false, raise=TRANSACTION_EXPIRED)`
* Else `FAIL_PATH_NOT_FOUND` or `FAIL_DOC_NOT_FOUND` ->
* Multiple possible causes:
* FAIL_DOC_NOT_FOUND can easily lead to FAIL_PATH_NOT_FOUND if the user accidentally deletes the ATRs and they are recreated, so the handling of each should be the same.
* A successful FAIL_AMBIGUOUS leads to retry and will hit FAIL_PATH_NOT_FOUND
* Perhaps, the cleanup process has removed the entry, as it was expired (though this is unlikely).
* Whatever has happened, the necessary handling for all these is the same: continue as if success. The ATR entry has been removed.
* Else `FAIL_HARD` -> Error(ec, err, rollback=false)
* Else -> Default current logic is that rollback will continue in the event of failures until expiry. Retry operation, after waiting [OpRetryBackoff](#OpRetryBackoff). Takes care of `FAIL_AMBIGUOUS`.
* Also handles FAIL_ATR_FULL. It seems unlikely we would get this since we're solely removing a field, but just in case, we want to be doing everything possible to reduce the ATR size.
* Else:
* If in ExpiryOvertimeMode -> `Error(FAIL_EXPIRY, cause=AttemptExpired(err), rollback=false, raise=TRANSACTION_EXPIRED)`
* Else if `FAIL_EXPIRY` -> set ExpiryOvertimeMode and retry operation, after waiting [OpRetryBackoff](#OpRetryBackoff). We want to make one further attempt to complete the rollback.
* Else `FAIL_PATH_NOT_FOUND` ->
Perhaps, the cleanup process has removed the entry, as it was expired (though this is unlikely). Continue as though success.
* Else `FAIL_DOC_NOT_FOUND` -> The ATR has been deleted, or we're trying to rollback an attempt that failed to create a new ATR. Neither should happen, so bailout. `Error(ec, cause=ActiveTransactionRecordNotFound, rollback=false)`
* Else `FAIL_HARD` -> Error(ec, err, rollback=false)
* Else -> Default current logic is that rollback will continue in the event of failures until expiry. Retry operation, after waiting [OpRetryBackoff](#OpRetryBackoff). Takes care of `FAIL_AMBIGUOUS`.
* On success: set state to ROLLED_BACK