go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/gae/filter/txnBuf/doc.go

// Copyright 2015 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package txnBuf contains a transaction buffer filter for the datastore
// service.
//
// By default, datastore transactions take a snapshot of the entity group as
// soon as you Get or Put into it. All subsequent Get (and query) operations
// reflect the state of the ORIGINAL transaction snapshot, regardless of any
// Put/Delete operations you've done since the beginning of the transaction.
//
// If you've installed this transaction buffer, then:
//
//   - All mutations will be reflected in all read operations (see LIMITATIONS).
//     Without the buffer, read operations always observe the state of the
//     entity group(s) at the time that the transaction started.
//
//   - All mutation operations will be buffered until the close of the
//     transaction. This can help reduce the transaction size, and thus avoid
//     the transaction size limit (currently 10MB). Multiple puts to the same
//     entity will not increase the transaction size multiple times.
//
//   - Transactions inside of an existing transaction will add to their outer
//     transaction if they don't cause the outer transaction to exceed its
//     size budget.
//
//   - If an inner transaction would cause the OUTERMOST transaction to exceed
//     the appengine-imposed 10MB transaction size limit, an error will be
//     returned from the inner transaction, instead of adding it into the
//     outermost transaction. This only applies to the first level of inner
//     transactions, and does not apply to recursive transactions. The reason
//     for this is that it's entirely feasible for inner transactions to
//     temporarially exceed the limit, but still only commit an outer
//     transaction which is under the limit. An example of this would be having
//     one inner-inner transaction add a lot of large entities and then having
//     a subsequent inner-inner transaction delete some of those entities.
//
// LIMITATIONS (only inside of a transaction)
//
//   - KeysOnly/Projection/Count queries are supported, but may incur additional
//     costs.
//
//     These query types are implemented via projection queries, but will
//     project all order-by fields in addition to any specified in the original
//     query.
//
//   - Distinct Projection queries do all 'distinct' deduplication in-memory.
//     This could make them substantially more expensive than their native
//     equivalent.
//
//   - Metadata entities (e.g. `__entity_group__`) will reflect their values as
//     they were at the beginning of the transaction, and will not increment
//     as you write inside of the transaction.
//
//   - Query cursors are not supported. Since the cursor format for the
//     in-memory datastore implementation isn't compatible with the production
//     cursors, it would be pretty tricky to make it so that cursors were
//     viable outside the transaction as well as inside of it while also having
//     it accurately reflect the 'merged' query results.
//
//   - No parallel access* to datastore while in a transaction; all nested
//     operations are serialized. This is done for simplicity and correctness.
//
//   - The exception is that callbacks inside of
//     a Run/GetMulti/DeleteMulti/PutMulti query MAY read/write the current
//     transaction. Modifications to the datastore during query executions will
//     not affect the query results (e.g. the query has snapshot consistency
//     from the moment that it begins iteration). Note, however, that datastore
//     operations within the callback are still synchronized. This behavior is
//     so that the user is not forced to buffer all of the query results before
//     doing work with them, but can treat the query like a stream of events,
//     if they so choose.
//
//   - The changing of namespace inside of a transaction is undefined... This is
//     just generally a terrible idea anyway, but I thought it was worth
//     mentioning.
//
//   - Currently, the soft transactions are not directly accessible using the
//     CurrentTransaction interface; it returns the wrapped datastore's
//     transaction. While this is still correct, it could definitely be made
//     more useful by adding transaction buffer metadata to the returned
//     object.
package txnBuf