Transaction Settings

The microservices provided by GS2 generally have a field named TransactionSetting in their namespace configuration. TransactionSetting has the following structure:

Field Explanation

enableAutoRun

Configures whether issued transactions are automatically executed. There is almost no reason to set this to false nowadays.

In the past, GS2 lacked a mechanism for automatically executing transactions. The primary method for executing transactions involved manually requesting and processing issued transactions with each microservice. However, this approach only complicates error handling when transactions fail midway.

enableAtomicCommit

The AtomicCommit feature is a relatively recent addition within the history of GS2’s transaction system. Before AtomicCommit existed, issued transactions were executed asynchronously. For example, when calling the product purchase API in GS2-Showcase, the purchase process wasn’t complete at that stage. Only after the result of the asynchronously executed transaction was returned could you determine whether the transaction succeeded or failed. The challenge with this design lay in what happened when an error occurred during transaction execution.

The auto-execution mechanism works like this: after a consumption action succeeds, if an acquisition action fails but the failure is a server error worth retrying, the server automatically attempts a retry to complete the transaction. However, if the acquisition action fails due to exceeding the allowed quantity, or if one of multiple configured consumption actions fails due to insufficient resources, the transaction fails at that point. Yet, the successful consumption action might still be executed.

AtomicCommit was introduced to solve this problem. It executes consumption and acquisition actions before returning the response from the GS2-Showcase item purchase API. Only if all actions succeed will the results be reflected in the database. Enabling this setting prevents transactions from executing in an incomplete state. Therefore, we strongly recommend enabling AtomicCommit when developing new games using GS2.

However, AtomicCommit is not a panacea. Since it executes consumption and acquisition actions concurrently, attempting to update the same resource within the same action will result in an error. Note that AtomicCommit cannot be enabled when executing such transactions.

Furthermore, enabling AtomicCommit extends its effect not only to transaction execution but also to pre-scripts executed via that API. For example, if you have a script configured for product purchases, any operations within that script that call the GS2 API to modify data, or transactions initiated by the script, will have their results reflected when the GS2-Showcase product purchase API succeeds.

transactionUseDistributor

This option is available when enableAtomicCommit is enabled. This setting configures transaction execution to be asynchronous. When enabled, consumption and acquisition actions are processed as AtomicCommit, but the GS2-Showcase item purchase API returns a response without waiting for their completion. It is intended for use when waiting for transaction results is unnecessary, or when there is a conflict between the data rewritten by the purchase script and the data rewritten by the transaction.

commitScriptResultInUseDistributor

This option is available when transactionUseDistributor is enabled. Processes rewritten by pre-scripts can also be included in the transaction for consumption and acquisition actions executed asynchronously. This allows transactions to run asynchronously while preventing only the script execution results from being reflected.

acquireActionUseJobQueue

An option available when enableAtomicCommit is enabled. It allows configuring the acquire action of the issued transaction to register a job with GS2-JobQueue, executing the acquire action asynchronously. This setting helps avoid issues when consume actions and acquire actions conflict, or when multiple configured acquire actions conflict with each other.

distributorNamespaceId

Configures the GS2-Distributor namespace used when automatically executing transactions.

queueNamespaceId

Configures the GS2-JobQueue namespace used when executing transaction acquisition actions via the job queue.

Flowchart for determining which transaction system to use

graph TD
  Start --> 1st["enableAutoRun = true, enableAtomicCommit = true"]
  1st --> Async{"Does the game need to use the transaction result?"}
  Async -- Need to wait --> UseDistributor2["transactionUseDistributor = true"]
  Async -- Waiting required --> Conflict{"Does a conflict error occur?"}
  Conflict -- Not conflict --> End
  Conflict -- Conflicted --> 2nd{"Investigate conflict details"}
  2nd -- Conflict is between script and transaction --> UseDistributor["transactionUseDistributor = true"]
  2nd -- Transaction consumption actions --> NotAtomicCommit["enableAtomicCommit = false"]
  2nd -- Transaction consumption action and acquisition action --> UseJobQueue["acquireActionUseJobQueue = true"]
  2nd -- Transaction acquisition actions --> UseJobQueue
  UseDistributor2 --> 3rd{"Is a pre-script configured?"}
  3rd -- Not configured --> Conflict
  3rd -- Configured --> UseScript{"Should the script result also be committed with the transaction?"}
  UseScript -- Not required --> Conflict
  UseScript -- Required --> CommitScriptResultInUseDistributor["commitScriptResultInUseDistributor = true"]
  CommitScriptResultInUseDistributor --> Conflict
  NotAtomicCommit --> End
  UseJobQueue --> End