[SERVER-64017] Unify the terms used to refer to sessions created to run internal transactions Created: 25/Feb/22  Updated: 12/Dec/23

Status: Open
Project: Core Server
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major - P3
Reporter: Cheahuychou Mao Assignee: Backlog - Cluster Scalability
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to SERVER-55346 Architecture Guide updates for Runnin... Closed
Assigned Teams:
Cluster Scalability
Sprint: Sharding 2022-05-02, Sharding NYC 2022-05-16, Sharding NYC 2022-05-30, Sharding 2022-06-27
Participants:

 Description   

Throughout the codebase and design for internal transactions, we have been using a wide range of terms to refer to sessions started by an external client and sessions are started by a router to run transactions on behalf of a client. Those terms include external/internal/non-internal sessions, child/parent sessions, logical/transaction sessions, internal sessions for retryable/non-retryable write etc. The lack of formal terminology has made it difficult for us to write clear code. For example, the name of this _isInternalSession() method is misleading since it is possible for an internally started session to not have a parent session. This ticket to unify the naming and investigate if there is any bug caused by the existing ambiguity. 



 Comments   
Comment by Jack Mulrow [ 02/Jun/22 ]

Moving this out of PM-2210 since it isn't required to close that out, but it's a nice improvement so I will keep it on myself as a non-project ticket.

Comment by Jack Mulrow [ 19/Apr/22 ]

Proposed naming scheme:

  1. Logical Session
    1. A type represented by the LogicalSessionId IDL type. May represent any of the following "session types" below depending on which fields are present and where the session is used.
  2. Transaction Session
    1. The unit used by the SessionCatalog and any decorations on the Session type, like TransactionParticipant and TransactionRouter, backed by a config.transactions entry. Each distinct transaction session can be used for a multi document transaction, but they will all share the same logical session. Also represented by the LogicalSessionId IDL type and can have any fields set.
  3. Parent Session
    1. A session id that could have come from an external user, ie has only the "id" and "uid" fields set. May have been started by an internal client (e.g. a mongos).
    2. The unit used by the logical session cache, backed by a config.system.sessions entry. Multiple transaction sessions may map to the same parent session via the "child session" relationship noted below. Represented by the LogicalSessionId IDL type, but should never have "txnNumber" or "txnUUID" set.
    3. May have a transaction session associated with it, which can be used for either a multi document transaction or a retryable write.
  4. Child Session
    1. A session id that can only come from an internal user, ie has the "txnUUID" and possibly the "txnNumber" fields set, in addition to "id" and "uid."
    2. Associated with a "parent session" which is where the "id" and "uid" fields come from. Using the child session will update its parent session in the logical session cache for the purposes of reaping, expiration, killing, etc.
    3. Have their own transaction sessions distinct from their parent session, with behaviors noted below. Can only be used for multi document transactions, not retryable writes.
  5. Retryable child session
    1. Child session with the txnNumber field set. Associated with the retryable write on its parent session that had that txnNumber and its history (ie config.transactions entry) will be maintained as long as that retryable write's history must be maintained, including across chunk migrations and resharding.
    2. Multiple child sessions may be spawned on behalf of the same parent session retryable write. Statement ids are unique across all child session transactions and the parent session's retryable write.
  6. Non-retryable child session
    1. Child session with only the txnUUID field set, in addition to the parent session fields. Not associated with any retryable write and its history is not maintained once it is safe to remove for the purpose of the transaction machinery itself (e.g. the transaction has left the prepared state) and not copied by chunk migrations or resharding.
    2. Statement ids are not meaningful.
  7. Internal Transaction
    1. Any transaction started within the server. Can use a parent session or either kind of child session.
  8. Retryable transaction
    1. A transaction where statement ids are meaningful, which is only possible on a retryable child session.

These are essentially the same names as before except we'd get rid of the internal/external session distinction, e.g. the example in the description would become _isChildSession(). It keeps the "internal transaction" distinction but we won't branch any behavior based on that - we'd only consider the transaction's session type. It's just a convenient way to refer to transactions not from a user.

cheahuychou.mao@mongodb.com, sanika.phanse@mongodb.com, israel.hsu@mongodb.com, jason.zhang@mongodb.com, what do you all think of these names? Any ideas for improvement?

Generated at Thu Feb 08 05:59:16 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.