package protocol.transactions

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: TransactionAttempt, TransactionCleanupAttempt

• NOTHING_WRITTEN = 0

• PENDING = 1

• ABORTED = 2

• COMMITTED = 3

• COMPLETED = 4

• ROLLED_BACK = 5

• UNKNOWN = 6

This will be propagated to other concurrent transactions, e.g. it can be used for gating and communicating between concurrent transactions

Used in: TransactionStreamDriverToPerformer, TransactionStreamPerformerToDriver

• oneof request

  • CommandSetLatch latch_set = 2

    Countdown a latch

Defined https://hackmd.io/foGjnSSIQmqfks2lXwNp8w#Protocol-Extensions

Used in: performer.PerformerCapsFetchResponse, CreateConnectionResponse

• EXT_TRANSACTION_ID = 0

  This is mandatory if PROTOCOL_VERSION_2_0 or higher is sent.

• EXT_DEFERRED_COMMIT = 1

• EXT_MEMORY_OPT_UNSTAGING = 2

  At least one of EXT_MEMORY_OPT_UNSTAGING and EXT_TIME_OPT_UNSTAGING must be supported

• EXT_TIME_OPT_UNSTAGING = 3

• EXT_CUSTOM_METADATA_COLLECTION = 4

• EXT_BINARY_METADATA = 5

• EXT_QUERY = 6

• EXT_STORE_DURABILITY = 7

• BF_CBD_3787 = 8

• BF_CBD_3794 = 9

• BF_CBD_3705 = 10

• BF_CBD_3838 = 11

• EXT_REMOVE_COMPLETED = 12

• EXT_ALL_KV_COMBINATIONS = 13

• EXT_UNKNOWN_ATR_STATES = 14

• BF_CBD_3791 = 15

• EXT_SINGLE_QUERY = 16

• EXT_REPLACE_BODY_WITH_XATTR = 17

• EXT_THREAD_SAFE = 18

• EXT_SERIALIZATION = 19

• EXT_SDK_INTEGRATION = 20

• EXT_MOBILE_INTEROP = 21

• EXT_INSERT_EXISTING = 22

• EXT_OBSERVABILITY = 23

• EXT_QUERY_CONTEXT = 24

• EXT_PARALLEL_UNSTAGING = 25

• EXT_BINARY_SUPPORT = 26

  Support for Caps.CONTENT_AS_PERFORMER_VALIDATION is a pre-requisite for all following extensions.

• EXT_REPLICA_FROM_PREFERRED_GROUP = 27

• EXT_GET_MULTI = 28

• EXT_REPLICA_FROM_PREFERRED_GROUP_PATCH1 = 29

• EXT_TTL = 30

The set of collections currently being cleaned up.

Used in: CleanupSetFetchResponse

• repeated shared.Collection cleanup_set = 1

Used as request type in: PerformerService.cleanupSetFetch

• string cluster_connection_id = 1

Used as response type in: PerformerService.cleanupSetFetch

• optional CleanupSet cleanup_set = 1

Used as request type in: PerformerService.clientRecordProcess

• string client_uuid = 1

• string bucket_name = 2

  The collection where the client record should exist (this message was created before Collection existed)

• string scope_name = 3

• string collection_name = 4

• repeated hooks.transactions.Hook hook = 5

  Any hooks can only use HookPoints in the CLIENT_RECORD_* range

• string cluster_connection_id = 6

  This is only needed for KV operations, so the driver will usually send the default cluster connection.

Used as response type in: PerformerService.clientRecordProcess

• int32 num_active_clients = 1

• int32 index_of_this_client = 2

• repeated string expired_client_ids = 4

• int32 num_existing_clients = 5

• int32 num_expired_clients = 6

• bool override_enabled = 7

• bool override_active = 8

• int64 override_expires = 9

• int64 cas_now_nanos = 10

• string client_uuid = 11

• bool success = 12

Used as request type in: PerformerService.clientRecordRemove

• string client_uuid = 1

• repeated hooks.transactions.Hook hook = 2

  Any hooks can only use HookPoints in the CLIENT_RECORD_* range

• string cluster_connection_id = 8

  This is only needed for KV operations, so the driver will usually send the default cluster connection.

Used as response type in: PerformerService.clientRecordRemove

• bool success = 1

Used as request type in: PerformerService.closeTransactions

(message has no fields)

Used as response type in: PerformerService.closeTransactions

(message has no fields)

A batch of commands, often to be performed in parallel. But not always, sometimes it's used so multiple threads can each run a series of commands in serial. (E.g. nested CommandBatches). So it's crucial that the performer respect the `parallelism` setting. Created long before HorizontalScaling. Note the semantics of this command aren't as defined as they could be - see some discussion on https://couchbase.slack.com/archives/C014WB8U2MQ/p1665062945395139 The requirements are: 1. The operations should be started in parallel (assuming `parallelism` > 1 of course) 2. The ~first error should be propagated out of the lambda. ("~first" as it's fine for this to be best-effort, e.g. it doesn't have to require atomic variables or locking. Because the first concurrent failure is anyway non-deterministic). What is not defined is what happens to the other operations if one of them fails. Are they left to run to completion, are they cancelled, is that cancellation waited on? These semantics probably need to be selectable. Currently it is acceptable to do whatever is easiest - e.g. Java reactor will automatically cancel the other operations, while in Go it's easiest to wait for them all to complete.

Used in: TransactionCommand

• repeated TransactionCommand commands = 1

  A limited subset of commands are supported here: CommandInsert, CommandReplace, CommandRemove and CommandGet. And replace/remove cannot use useStashedResult, as that is not a well-defined concept in parallel operations.

• int32 parallelism = 2

  If the commands are being performed in parallel, how many to do concurrently. The performer is required to have this many operations in flight at once. E.g. say this value is 3, and 10 operations are specified in `commands`. The performer should start the first 3 operations in `commands` in parallel. Once an operation finishes successfully the performer should immediately start the next operation in `commands`, in parallel with the still-running other 2. It should not 'batch' the operations and wait for them all to succeed before progressing with the next batch.

ExtSDKIntegration performers should ignore. Otherwise, perform an explicit ctx.commit()

Used in: TransactionCommand

• repeated ExpectedResult expected_result = 1

  What result(s) the command is allowed to return. Anything outside this will fail the test.

Used in: CommandGetOptional, TransactionCommand

• optional DocId doc_id = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test. Tests can generally just set one expected result. Multiple results are allowed to support tricky situations, such as an op generally failing with FAIL_TRANSIENT until it fails with FAIL_EXPIRY

• string expected_content_json = 3

  If not-null, the performer will check the fetched data equals this. Useful for read-your-own-write tests. This is superceded by content_as_validation, but that is only available with CONTENT_AS_PERFORMER_VALIDATION, so tests will continue to use this until that extension is fully rolled out.

• optional shared.ContentAsPerformerValidation content_as_validation = 6

  Added with cap CONTENT_AS_PERFORMER_VALIDATION and will only be sent if performer declares support for that.

• DocStatus expected_status = 4

  If not DO_NOT_CHECK, the performer will check the fetched document status equals this. Fully deprecated as of ExtSDKIntegration. The driver will only specify DO_NOT_CHECK now.

• optional int32 stash_in_slot = 5

  Since day one the performer must have supported stashing a single document. Whenever a CommandGet or CommandGetOptional is executed (but not a transactions.Get), the result is automatically stashed. ExtMobileInterop adds the concept of stashing multiple documents. This allows some more sophisticated tests particularly around CAS mismatches. If this `stashInSlot` is set, the performer needs to update or create a map of StashSlot (Int) -> TransactionGetResult. This is stored per-transaction and should be deleted at the end of the transaction. Subsequent CommandReplace and CommandReplace operations may may reference to one of these stashed results.

• optional TransactionGetOptions options = 7

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

The SDK needs to implement TransactionGetMultiReplicasFromPreferredServerGroupOptions and TransactionGetMultiReplicaFromPreferredServerGroupSpec. But to save testing effort, and because the APIs are currently identical except for naming, FIT will use the same CommandGetMulti for both. If they diverge in future we will copy the messages then.

Used in: TransactionCommand

• repeated CommandGetMulti.TransactionGetMultiSpec specs = 1

• optional TransactionGetMultiOptions options = 2

• repeated ExpectedResult expected_result = 3

  What result(s) this individual spec is allowed to return. Anything outside this will fail the test. The performer must perform this validation. If this is empty, the performer skips validation.

• bool get_multi_replicas_from_preferred_server_group = 4

  Iff true, performer should use ctx.getMultiReplicasFromPreferredServerGroup() instead of ctx.getMulti()

Used in: CommandGetMulti

• optional shared.DocLocation location = 1

• optional shared.Transcoder transcoder = 2

• bool expect_present = 3

  The performer always needs to check if the doc is returned as Optional.None or present, against this.

• optional shared.ContentAsPerformerValidation content_as_validation = 6

  Determines if and how the performer should execute transactionGetResult.contentAs() on this individual spec result.

• int32 expected_result_position = 5

  Each spec will result in a result in the output array. This contains the required position of the result in that array, which the SDK must validate.

There are two ways the implementation can implement getOptional: 1. An explicit ctx.getOptional() API. 2. ctx.get() throwing a catchable DocumentNotFoundException. Either is allowed.

Used in: TransactionCommand

• optional CommandGet get = 1

• bool expect_doc_present = 2

  Use this instead of passing EXPECT_FAIL_DOC_NOT_FOUND or EXPECT_FAIL_DOC_ALREADY_EXISTS

• optional shared.ContentAsPerformerValidation content_as_validation = 6

  Added with cap CONTENT_AS_PERFORMER_VALIDATION and will only be sent if performer declares support for that.

• optional TransactionGetOptions options = 4

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Used in: TransactionCommand

• optional DocId doc_id = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test.

• optional shared.ContentAsPerformerValidation content_as_validation = 6

  Added with cap CONTENT_AS_PERFORMER_VALIDATION and will only be sent if performer declares support for that.

• optional int32 stash_in_slot = 5

  Refer to `stashInSlot` in CommandGet for details. `useStashedResult` and `useStashedSlot` will not be sent together.

• optional TransactionGetOptions options = 7

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Used in: TransactionCommand

• optional DocId doc_id = 1

• oneof content_option

  • string content_json = 2

    This is superceded by `content`, but that is only available with EXT_BINARY_SUPPORT, so tests will continue to use this until that extension is fully rolled out.

  • shared.Content content = 5

    Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

• repeated ExpectedResult expected_result = 3

  What result(s) the command is allowed to return. Anything outside this will fail the test.

• optional TransactionInsertOptions options = 4

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Insert a document using a regular KV operation. The command is expected to succeed. Created long before SdkCommandInsert.

Used in: TransactionCommand

• optional DocId doc_id = 1

• string content_json = 2

Run a query command.

Used in: TransactionCommand, TransactionSingleQueryRequest

• string statement = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test.

• bool check_row_content = 3

  Whether to check the returned rows against expectedRows

• repeated string expected_rows = 4

  What rows the query should return, as JSON

• bool check_row_count = 6

  Whether to check the number of returned rows against expectedRowCount

• int32 expected_row_count = 7

  How many rows the query should return

• bool check_mutations = 8

  Whether to check the returned mutations

• int32 expected_mutations = 9

  How many mutations the query should create

• optional CommandQueryParameters query_parameters = 10

  Deprecated as of ExtSDKIntegration, replaced by queryOptions, which allows optional. FIT will send both for now, performers should remove support for queryParameters.

• optional TransactionQueryOptions query_options = 12

• optional shared.Scope scope = 11

Parameters for the Query Statement

Used in: CommandQuery

• int32 timeout = 10

  Extra deprecated as it was never possible to set timeout on TransactionQueryOptions

• shared.ScanConsistency scan_consistency = 11

Used in: TransactionCommand

• optional DocId doc_id = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test.

• bool use_stashed_result = 3

  Whether to use the result of the last get operation This will not be set inside a CommandBatch, due to the 'last' operation not being a valid concept during parallel ops.

• optional int32 use_stashed_slot = 4

  Refer to `stashInSlot` in CommandGet for details. `useStashedResult` and `useStashedSlot` will not be sent together.

Remove a document using a regular KV operation. The command is expected to succeed. Created long before SdkCommandRemove.

Used in: TransactionCommand

• optional DocId doc_id = 1

Used in: TransactionCommand

• optional DocId doc_id = 1

• oneof content_option

  • string content_json = 2

  • shared.Content content = 7

    Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

• repeated ExpectedResult expected_result = 3

  What result(s) the command is allowed to return. Anything outside this will fail the test.

• bool use_stashed_result = 4

  Whether to use the result of the last get operation. This will not be set inside a CommandBatch, due to the 'last' operation not being a valid concept during parallel ops.

• optional int32 use_stashed_slot = 5

  Refer to `stashInSlot` in CommandGet for details. `useStashedResult` and `useStashedSlot` will not be sent together.

• optional TransactionReplaceOptions options = 6

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Replace a document using a regular KV operation. The command is expected to succeed. Created long before SdkCommandReplace.

Used in: TransactionCommand

• optional DocId doc_id = 1

• string content_json = 2

ExtSDKIntegration performers: throw an exception (or raise an error) to cause an auto-rollback. Otherwise, perform an explicit ctx.rollback()

Used in: TransactionCommand

• repeated ExpectedResult expected_result = 1

  What result(s) the command is allowed to return. Anything outside this will fail the test.

Used in: BroadcastToOtherConcurrentTransactionsRequest, TransactionCommand

• string latch_name = 1

If the performer executes this command, it should report a failure. This is usually used to check an earlier operation definitely failed the transaction.

Used in: TransactionCommand

(message has no fields)

Simulates the application throwing an exception inside the lambda. Could be used to simulate an application bug, or the application choosing to rollback this way (as opposed to ctx.rollback(), e.g. app-rollback). Application exceptions will be classified as FAIL_OTHER.

Used in: TransactionCommand

(message has no fields)

Used in: TransactionCommand

• string latch_name = 1

Requests the performer creates a connection to a Couchbase cluster, and return performer caps. In the transactions package as it was part of the original transactions-only implementation, and has been replaced now.

Used as request type in: PerformerService.createConnection

• string cluster_hostname = 1

• string cluster_username = 2

• string cluster_password = 3

• string bucket_name = 4

  As of ExtSDKIntegration this field will no longer be sent and should be ignored. It is unclear why it was ever required.

• bool use_as_default_connection = 5

  As of ExtSDKIntegration this field will no longer be sent and should be ignored. The driver will now always explicitly send a clusterConnectionId.

• bool use_custom_serializer = 6

  The performer should use a custom JsonSerializer when creating the Cluster. This custom JsonSerializer is required to have specific serialization and deserialization logic, which the driver will validate. See the Java performer for implementation details.

• bool use_tls = 7

  Used for TLS enabled clusters such as Capella clusters

• optional string cert_path = 8

Returns the capabilities of the performer (or more specifically, the transactions-implementation-under-test by that performer), along with a reference to the created cluster connection. As of ExtSDKIntegration, this is now legacy. Performers should implement getPerformerCaps and createClusterConnection instead. This

Used as response type in: PerformerService.createConnection

• repeated Caps performer_caps = 1

• string performer_user_agent = 2

  Human-readable string identifying the performer. For example, "java".

• string performer_library_version = 4

  Identifies the version of the library under test. For example, "1.1.2".

• string protocol_version = 3

  Defined https://hackmd.io/foGjnSSIQmqfks2lXwNp8w#Protocol-Versions Must be "1.0", "2.0" or "2.1" any other values will cause the driver to abort.

• repeated shared.API supported_apis = 6

  The APIs this implementation supports. This is primarily used to run tests on multiple APIs, so if an implementation only supports one, it should just return one - see comments for `API` for details. If the performer does not return anything, it will be assumed to support just API.DEFAULT.

• string cluster_connection_id = 5

• string cluster_connection_id = 1

Exists for legacy reasons. Newer messages should use DocLocation.

Used in: CommandGet, CommandGetReplicaFromPreferredServerGroup, CommandInsert, CommandInsertRegularKV, CommandRemove, CommandRemoveRegularKV, CommandReplace, CommandReplaceRegularKV, TransactionAttempt, TransactionCleanupATRRequest, TransactionCleanupAttempt, TransactionCleanupRequest

• string bucket_name = 1

• string scope_name = 2

• string collection_name = 3

• string doc_id = 4

This was only exposed in the Java API and is deprecated as of 1.1.3 Other implementations are not required to check this.

Used in: CommandGet

• NORMAL = 0

• IN_TXN_COMMITTED = 1

• IN_TXN_OTHER = 2

• OWN_WRITE = 3

• AMBIGUOUS = 4

• DO_NOT_CHECK = 5

Used in: ErrorWrapper

• EC_FAIL_HARD = 0

• EC_FAIL_OTHER = 1

• EC_FAIL_TRANSIENT = 2

• EC_FAIL_AMBIGUOUS = 3

• EC_FAIL_DOC_ALREADY_EXISTS = 4

• EC_FAIL_DOC_NOT_FOUND = 5

• EC_FAIL_PATH_ALREADY_EXISTS = 10

• EC_FAIL_PATH_NOT_FOUND = 6

• EC_FAIL_CAS_MISMATCH = 7

• EC_FAIL_WRITE_WRITE_CONFLICT = 8

• EC_FAIL_ATR_FULL = 9

• EC_FAIL_EXPIRY = 11

• EC_ANYTHING = 12

  Any ErrorClass is permitted - including the TransactionOperationFailed not having one Note that ErrorClass validation is now deprecated and performers should remove their validation logic.

This maps to the TransactionOperationFailed defined in the design doc

Used in: ExpectedResult

• ErrorClass error_class = 1

  This is now deprecated and the performer can feel free to disable validation of this. Once all performers have removed validation, it will be removed.

• bool auto_rollback_attempt = 2

• bool retry_transaction = 3

• TransactionException to_raise = 4

• optional ExpectedCause cause = 5

Used in: TransactionCreateRequest

• EventType type = 1

Used in: Event

• EventCleanupFailedEvent = 0

• EventIllegalDocumentState = 1

• EventLostCleanupThreadEndedPrematurely = 2

• EventTransactionCleanupAttempt = 3

• EventTransactionCleanupEndRunEvent = 4

• EventTransactionCleanupStartRunEvent = 5

• EventTransactionsStarted = 6

• EventUnknown = 7

Used in: ErrorWrapper

• oneof cause

  • bool do_not_check = 1

    Tests should specify the expected cause wherever possible

  • ExternalException exception = 2

Used in: CommandCommit, CommandGet, CommandGetMulti, CommandGetReplicaFromPreferredServerGroup, CommandInsert, CommandQuery, CommandRemove, CommandReplace, CommandRollback, Get, Insert, Remove, Replace

• oneof result

  • bool success = 1

    If the command should succeed

  • bool anything_allowed = 2

    If the command is permitted to do anything, e.g. succeed or throw errors. Required for some complex tests where it's tricky to calculate what a given op will do.

  • ErrorWrapper error = 3

    The operation throws an ErrorWrapper/TransactionOperationFailed, the only exception an operation may throw. Update: as of EXT_QUERY, EXT_SDK_INTEGRATION and EXT_INSERTS_EXISTING, that is no longer the case, some operations can throw some other exceptions.

  • ExternalException exception = 4

    Require a non-TransactionOperationFailed exception.

The root cause of the TransactionException. Will only be checked if TransactionException != NO_EXCEPTION_THROWN

Used in: ExpectedCause, ExpectedResult, TransactionResult, TransactionSingleQueryResponse

• Unknown = 0

• ActiveTransactionRecordEntryNotFound = 1

• ActiveTransactionRecordFull = 2

• ActiveTransactionRecordNotFound = 3

• DocumentAlreadyInTransaction = 4

• DocumentExistsException = 5

• DocumentNotFoundException = 6

• NotSet = 7

• FeatureNotAvailableException = 8

• TransactionAbortedExternally = 9

• PreviousOperationFailed = 10

• ForwardCompatibilityFailure = 11

• ParsingFailure = 12

• IllegalStateException = 13

• CouchbaseException = 14

• ServiceNotAvailableException = 15

• RequestCanceledException = 16

• ConcurrentOperationsDetectedOnSameDocument = 17

• CommitNotPermitted = 18

• RollbackNotPermitted = 19

• TransactionAlreadyAborted = 20

• TransactionAlreadyCommitted = 21

• UnambiguousTimeoutException = 22

• AmbiguousTimeoutException = 23

• AuthenticationFailureException = 24

• DocumentUnretrievableException = 25

  Added with EXT_REPLICA_FROM_PREFERRED_GROUP

Used in: TransactionCommand

• optional shared.DocLocation location = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test. The performer must perform this validation. If this is empty, the performer skips validation.

• optional int32 stash_in_slot = 3

  If this `stashInSlot` is set, the performer needs to update or create a map of StashSlot (Int) -> TransactionGetResult. This is stored per-transaction and should be deleted at the end of the transaction. Subsequent operations may may reference to one of these stashed results. transactions.CommandGet and transactions.Get share the same map.

• optional shared.ContentAs content_as = 4

  Determines if and how the performer should execute transactionGetResult.contentAs(). Added with CONTENT_AS_PERFORMER_VALIDATION and will only be sent if performer declares support for that.

• optional TransactionGetOptions options = 5

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Used in: TransactionCommand

• optional shared.DocLocation location = 1

• optional shared.Content content = 2

• repeated ExpectedResult expected_result = 3

  What result(s) the command is allowed to return. Anything outside this will fail the test. The performer must perform this validation. If this is empty, the performer skips validation.

• optional TransactionInsertOptions options = 4

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Used in: TransactionCommand

• optional shared.DocLocation location = 1

• repeated ExpectedResult expected_result = 2

  What result(s) the command is allowed to return. Anything outside this will fail the test. The performer must perform this validation. If this is empty, the performer skips validation.

• optional int32 use_stashed_slot = 3

  Refer to `stashInSlot` in CommandGet for details.

Used in: TransactionCommand

• optional shared.DocLocation location = 1

• optional shared.Content content = 2

• repeated ExpectedResult expected_result = 3

  What result(s) the command is allowed to return. Anything outside this will fail the test. The performer must perform this validation. If this is empty, the performer skips validation.

• optional int32 use_stashed_slot = 4

  Refer to `stashInSlot` in CommandGet for details.

• optional TransactionReplaceOptions options = 5

  Added with EXT_BINARY_SUPPORT and will only be sent if performer declares support for that.

Used in: TransactionResult

• AttemptStates state = 1

• string attempt_id = 2

• optional DocId atr = 3

  Can be empty iff state=NOTHING_WRITTEN

Used in: TransactionCreateRequest

• repeated TransactionCommand commands = 1

Used as request type in: PerformerService.transactionCleanupATR

• string atr_id = 1

  For backwards-compatibility with performers that don't support `atr` yet - will be removed eventually

  Field `atr` should be used instead.

• optional DocId atr = 3

• repeated hooks.transactions.Hook hook = 2

  Any hooks can only use HookPoints in the CLEANUP_* range

• string cluster_connection_id = 4

Used as response type in: PerformerService.transactionCleanupATR

• repeated TransactionCleanupAttempt result = 1

• int32 num_entries = 2

  Total number of entries found in the ATR

• int32 num_expired_entries = 3

  Total number of expired entries found in the ATR

The result of attempting to cleanup a single attempt entry in an ATR

Used as response type in: PerformerService.transactionCleanup

Used as field type in: TransactionCleanupATRResult, TransactionCleanupQueueResult

• bool success = 1

  Whether the attempt succeeded

• repeated string logs = 2

  All logs related to the attempt

• AttemptStates state = 3

  The state of the ATR entry, before cleanup. This field is optional. It will allow additional verification in some tests if it is provided.

• optional DocId atr = 7

  The ATR's location

• string atr_id = 4

  The key of the ATR document For backwards-compatibility with performers that don't support `atr` yet - aiming to remove eventually.

  Field `atr` should be used instead.

• string atr_bucket_name = 5

  The name of the bucket the ATR is on

  Field `atr` should be used instead.

• string attempt_id = 6

  The ID of the transaction attempt that was being cleaned up

Used as response type in: PerformerService.transactionProcessCleanupQueue

• repeated TransactionCleanupAttempt attempts = 1

Used as request type in: PerformerService.transactionCleanup

• optional DocId atr = 5

• string atr_id = 1

  For backwards-compatibility with performers that don't support `atr` yet - will be removed eventually

  Field `atr` should be used instead.

• string attempt_id = 2

• string transaction_id = 3

• repeated hooks.transactions.Hook hook = 4

  Any hooks can only use HookPoints in the CLEANUP_* range

• string cluster_connection_id = 6

  This is only needed for KV operations, so the driver will usually send the default cluster connection.

Used in: CommandBatch, TransactionAttemptRequest

• oneof command

  • CommandInsert insert = 1

  • CommandReplace replace = 2

  • CommandRemove remove = 3

  • CommandCommit commit = 4

  • CommandRollback rollback = 5

  • CommandGet get = 6

  • CommandGetOptional get_optional = 7

  • CommandWaitOnLatch wait_on_latch = 8

  • CommandSetLatch set_latch = 9

  • CommandBatch parallelize = 10

    All operations in the batch will be performed in parallel

  • CommandReplaceRegularKV replace_regular_kv = 11

  • CommandRemoveRegularKV remove_regular_kv = 12

  • CommandInsertRegularKV insert_regular_kv = 13

  • CommandThrowException throw_exception = 14

  • CommandQuery query = 15

  • CommandTestFail test_fail = 16

  • Insert insert_v2 = 17

    Why do we have transactions.CommandInsert and transactions.Insert? The former stems from the original days of FIT that just did integration testing of transactions. The latter is for modern FIT and supports the abstractions we need now, including for performance testing. These will only be sent if the performer declares support for TRANSACTIONS_WORKLOAD_1.

  • Get get_v2 = 18

  • Remove remove_v2 = 19

  • Replace replace_v2 = 20

  • CommandGetMulti get_multi = 22

  • CommandGetReplicaFromPreferredServerGroup get_from_preferred_server_group = 21

• bool do_not_propagate_error = 100

  Added for TXNJ-249: make the application (erroneously) catch and not propagate the error.

• int32 wait_msecs = 101

  If given, the performer will pause (blocking) for `wait_msecs` before executing the TransactionCommand

Initiates a single transaction.

Used as request type in: PerformerService.transactionCreate

Used as field type in: TransactionStreamDriverToPerformer, Workload

• optional string transactions_factory_ref = 1

  Non-ExtSDKIntegration: A reference to a previously constructed Transactions object (e.g. factory). ExtSDKIntegration: ignore this (it will not be sent), and just use `clusterConnectionId` to get `cluster.transactions()`.

• repeated TransactionAttemptRequest attempts = 2

  A transaction can consist of multiple attempts. Usually we want each attempt to do the same thing, but there are a handful of tests where we need more complex logic and need to do different things on different attempts. If the transaction does more attempts than are in this field, the commands in the last attempt are what will be repeated.

• optional TransactionOptions options = 3

• repeated shared.Latch latches = 4

  Any latches that the transaction should create.

• string name = 5

  Just for debugging, name the test

• repeated Event expected_events = 6

  Instead of the performer returning any raised events, the driver specifies which are expected, or explicitly not expected. Event buses can be asynchronous so this prevents the performer having to wait for an unknown amount of time on each test. Also, each implementation handles events differently - some use an event bus, some simply log. So this allows the performer to also check as appropriate. For expectedAbsenceOfEvents, the performer should pick an appropriate amount of time to wait for events before deciding an event will definitely not arrive.

• repeated Event expected_absence_of_events = 9

• string cluster_connection_id = 7

  Used for ExtSDKIntegration to create the transaction, and both in that and in non-ExtSDKIntegration to access collections for KV operations.

• shared.API api = 8

  The API to use for this transaction. See the comments for `API`.

• string transaction_ref = 1

Used in: TransactionStreamPerformerToDriver

(message has no fields)

The exception received by the application, if any

Used in: ErrorWrapper, TransactionResult, TransactionSingleQueryResponse

• NO_EXCEPTION_THROWN = 0

• EXCEPTION_FAILED = 1

• EXCEPTION_EXPIRED = 2

• EXCEPTION_UNKNOWN = 3

• EXCEPTION_COMMIT_AMBIGUOUS = 4

• EXCEPTION_FAILED_POST_COMMIT = 5

Used as response type in: PerformerService.transactionsFactoryClose

(message has no fields)

Used in: CommandGetMulti

• optional TransactionGetMultiOptions.TransactionGetMultiMode mode = 1

Used in: TransactionGetMultiOptions

• PRIORITISE_LATENCY = 0

• DISABLE_READ_SKEW_DETECTION = 1

• PRIORITISE_READ_SKEW_DETECTION = 2

Used in: CommandGet, CommandGetOptional, CommandGetReplicaFromPreferredServerGroup, Get

• optional shared.Transcoder transcoder = 1

Used in: CommandInsert, Insert

• optional shared.Transcoder transcoder = 1

• optional shared.Expiry expiry = 2

  Added with EXT_TTL and will only be sent if performer declares support for that

Options that can be overridden at the individual transaction level. Note that pre-ExtSDKIntegration, this struct was empty. Not in the implementation, where PerTransactionConfig existed, but here at the FIT level. So, it will only be populated for ExtSDKIntegration performers.

Used in: TransactionCreateRequest

• optional shared.Durability durability = 1

  Durability to use for all mutating KV operations in this transaction.

• optional int64 timeout_millis = 2

  Timeout (nee expirationTime) for this transaction.

• repeated hooks.transactions.Hook hook = 3

  Any hooks can only use HookPoints before the CLEANUP_* range.

• optional shared.Collection metadata_collection = 4

  Will only be sent to ExtSDKIntegration-enabled performers.

• optional string parent_span_id = 5

  Identifies a tracing span to use as the parent for this transaction. Only sent to performers that declare support for Caps.OBSERVABILITY_1.

Used as request type in: PerformerService.transactionProcessCleanupQueue

• string transactions_factory_ref = 1

• string cluster_connection_id = 2

Used in: CommandQuery

• optional shared.ScanConsistency scan_consistency = 1

• map<string, string> raw = 2

• optional bool adhoc = 3

• optional string profile = 4

  "off", "phases", or "timings"

• optional bool readonly = 5

• repeated string parameters_positional = 6

• map<string, string> parameters_named = 7

• optional bool flex_index = 8

• optional int32 pipeline_cap = 9

• optional int32 pipeline_batch = 10

• optional int32 scan_cap = 11

• optional int32 scan_wait_millis = 12

• optional string client_context_id = 13

Used in: CommandReplace, Replace

• optional shared.Transcoder transcoder = 1

• optional shared.Expiry expiry = 2

  Added with EXT_TTL and will only be sent if performer declares support for that

The result of closing a transaction: whether the transaction succeeded, its logs, any exception thrown...

Used as response type in: PerformerService.transactionCreate

Used as field type in: run.Result, TransactionSingleQueryResponse, TransactionStreamPerformerToDriver

• repeated shared.MutationToken mutation_tokens = 1

  With CBD-3802 this is now only checked for the Java performer, other implementations should not provide this. It will eventually be removed.

• repeated TransactionAttempt attempts = 2

  Next three fields are all now deprecated. They are no longer used by FIT and performers do not need to return them. They will eventually be removed.

• string atrCollection = 3

• string atrId = 4

• TransactionException exception = 5

  Any TransactionFailed error raised by the operation.

• ExternalException exception_cause = 10

  The cause field from any TransactionFailed error.

• repeated string log = 6

  The implementation's in-memory log. It's optional but helps greatly with debugging.

• string transaction_id = 7

• int32 cleanup_requests_pending = 8

  How many attempts need to be cleaned up, as a direct result of this transaction. This field is only valid if cleanupClientAttempts was set (transactions will not queue a cleanup attempt if there is nothing to handle it)

• bool cleanup_requests_valid = 9

  Whether the cleanupRequestsPending field is valid, e.g. whether it can be checked

• bool unstaging_complete = 11

• optional string performer_specific_validation = 12

  Allows the performer to flag implementation/platform-specific validation failures that cannot be handled generically. E.g. if an erroneous event is detected it can be returned here. If present, the driver will fail the test, logging this message.

• string cluster_connection_id = 13

  As of ExtSDKIntegration, this is deprecated, and the performer no longer needs to return it - it will be ignored. It's somewhat unclear why it was here in the first place. Appears to be used for creating a TransactionCleanupRequest, but that can use any clusterConnectionId, including the default.

Runs a single query transaction (tximplicit). ExtSDKIntegration: cluster.query() Non-ExtSDKIntegration: transactions.query()

Used as request type in: PerformerService.transactionSingleQuery

• optional string transactions_factory_ref = 1

  A reference to a previously constructed Transactions object (e.g. factory). Not sent to ExtSDKIntegration performers.

• string cluster_connection_id = 2

  A reference to a previously constructed cluster connection. Will always be sent, but is only used by ExtSDKIntegration performers.

• optional CommandQuery query = 3

  The query to run

• optional sdk.query.QueryOptions query_options = 4

  Config needs handling differently in the performer based on ExtSDKIntegration or not. The structure of these messages is based around how things work in ExtSDKIntegration, and need some finangling for non-ExtSDKIntegration performers. ExtSDKIntegration: - The user calls `(cluster|scope).query(String, queryOptions().asTransaction([SingleQueryTransactionOptions]))`. - Everything in GRPC QueryOptions should be passed to an SDK QueryOptions. - The nested GRPC SingleQueryTransactionOptions should be passed as the SDK SingleQueryTransactionOptions block on QueryOptions.asTransaction(), if it is present. Otherwise call QueryOptions.asTransaction() with no args. Non-ExtSDKIntegration: - The user calls `transactions().query([Scope], String, [SingleQueryTransactionConfig])` - SDK SingleQueryTransactionConfig contains an SDK TransactionQueryOptions. This should be populated from GRPC QueryOptions. -- If no GRPC QueryOptions settings are specified, no SDK TransactionQueryOptions should be created. -- The GRPC QueryOptions.timeout() field must be applied at the SDK SingleQueryTransactionConfig level instead. - SDK SingleQueryTransactionConfig is populated from GRPC QueryOptions.SingleQueryTransactionOptions. - GRPC SingleQueryTransactionOptions.metadataCollection can be ignored. That was added in ExtSDKIntegration.

• shared.API api = 8

  The API to use for this transaction. See the comments for `API`.

Used as response type in: PerformerService.transactionSingleQuery

• optional TransactionResult result = 1

  Deprecated as this was from the initial version of ExtSingleQuery, pre SDK-integration. The replacement fields below are compatible with the SDK integration, when only a QueryResult (or TransactionFailed-derived error) is going to be returned to the user. If `result` is returned then FIT will validate that, else it will use the replacement fields.

• TransactionException exception = 2

  Any TransactionFailed error raised by the operation, at the point of performing the cluster.query()/transactions.query() If it threw a non-TransactionFailed exception, return EXCEPTION_UNKNOWN

• ExternalException exception_cause = 3

  If `exception` is EXCEPTION_UNKNOWN, then this is the exception raised at the point of performing the cluster.query()/transactions.query(). e.g. this is how non-TransactionFailed errors are indicated. Otherwise, it's the cause field of the TransactionFailed.

• TransactionException exception_during_streaming = 4

  Any TransactionFailed error raised by the operation, at the point of streaming the rows.

• ExternalException exception_cause_during_streaming = 5

  If `exceptionDuringStreaming` is NO_EXCEPTION_THROWN, then this is the exception raised while streaming the rows. e.g. this is how non-TransactionFailed errors are indicated. Otherwise, it's the cause field of the TransactionFailed.

• repeated string log = 6

  The implementation's in-memory log. It's optional (and not possible to return when the SDK integrated cluster.query() succeeds), but helps greatly with debugging on failures.

• optional string performer_specific_validation = 7

  Allows the performer to flag implementation/platform-specific validation failures that cannot be handled generically. E.g. if an erroneous event is detected it can be returned here. If present, the driver will fail the test, logging this message.

Used in: TransactionStreamDriverToPerformer

(message has no fields)

Used as request type in: PerformerService.transactionStream

• oneof request

  • TransactionCreateRequest create = 1

    This will setup a TwoWayTransaction but not start it. Must only be one of these per stream..

  • TransactionStartRequest start = 2

    Starts a previously setup TwoWayTransaction Only one of these will be sent per stream, and it will be after the TransactionCreateRequest.

  • BroadcastToOtherConcurrentTransactionsRequest broadcast = 3

    A request broadcast from another TwoWayTransaction, that is being broadcast to the rest via the driver.

Used as response type in: PerformerService.transactionStream

• oneof response

  • TransactionResult final_result = 1

    The transaction is completed, and the stream is done

  • TransactionCreated created = 2

    The transaction has been created e.g. as result of a TransactionCreateRequest, and is now ready to start e.g. a TransactionStartRequest

  • BroadcastToOtherConcurrentTransactionsRequest broadcast = 3

Shuts down a previously created Transactions (factory)

Used as request type in: PerformerService.transactionsFactoryClose

• string transactions_factory_ref = 1

Creates a Transactions object, e.g. a transactions factory

Used as request type in: PerformerService.transactionsFactoryCreate

• shared.Durability durability = 1

  The following fields are deprecated and replaced by the `config` field (which allows optional fields) They will still be sent by FIT, but performers should remove them while implementing the breaking change for ExtSDKIntegration

• int32 expiration_millis = 2

• bool cleanup_lost_attempts = 4

• bool cleanup_client_attempts = 5

• int64 cleanup_window_millis = 6

• UnstagingMode unstaging_mode = 7

• optional shared.Collection metadata_collection = 8

• repeated hooks.transactions.Hook hook = 3

  Any hooks can only use HookPoints before the CLEANUP_* range

• string cluster_connection_id = 9

  The Cluster to use for `Transactions.create()`

• optional shared.TransactionsConfig config = 10

Used as response type in: PerformerService.transactionsFactoryCreate

• string transactions_factory_ref = 1

Used in: TransactionsFactoryCreateRequest

• TIME_OPTIMIZED = 0

• MEMORY_OPTIMIZED = 1

Used in: run.Workload

• repeated TransactionCreateRequest command = 1

  The commands to run. Each command should send back one TransactionResult. The commands should be executed in a loop following `bounds`. E.g. the performer may go through all the commands multiple times. If the command fails, the performer should not propagate the failure (but should still send back an TransactionResult). E.g. it should continue until bounds is exhausted (or it has run all commands, if bounds is not specified).

• optional shared.Bounds bounds = 2

  Controls how the commands should be run. If it's not present, just run the commands through once.

• bool performance_mode = 3

  Performance mode indicates that this is a performance test, where the performer should disable various functionality. This includes: 1. Minimise the returned result A TransactionResult is heavy-weight, including things like a full log of the transaction. This requests that a minimal TransactionResult be returned, to reduce the performance impact. Specifically, on success the performer should only set exception=NO_EXCEPTION_THROWN, and populate no other fields. On failure, the performer should populate a full TransactionResult as normal - as it's expected that normal performance tests should not include failed transactions). 2. Reduce all performer logging to minimise impact. The transactions/SDK logging though should not be affected - this should be configured through the standard configuration paths. Because we will want to measure the impact of having it enabled.