// Copyright 2017 Google LLC

//

// 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 firestore

import (

"context"

"errors"

pb "cloud.google.com/go/firestore/apiv1/firestorepb"

"cloud.google.com/go/internal/trace"

gax "github.com/googleapis/gax-go/v2"

"google.golang.org/grpc/codes"

"google.golang.org/grpc/status"

)

// Transaction represents a Firestore transaction.

type Transaction struct {

}

// A TransactionOption is an option passed to Client.Transaction.

type TransactionOption interface {

config(t *Transaction)

}

// MaxAttempts is a TransactionOption that configures the maximum number of times to

// try a transaction. In defaults to DefaultTransactionMaxAttempts.

func MaxAttempts(n int) maxAttempts { return maxAttempts(n) }

type maxAttempts int

func (m maxAttempts) config(t *Transaction) { t.maxAttempts = int(m) }

// DefaultTransactionMaxAttempts is the default number of times to attempt a transaction.

const DefaultTransactionMaxAttempts = 5

// ReadOnly is a TransactionOption that makes the transaction read-only. Read-only

// transactions cannot issue write operations, but are more efficient.

var ReadOnly = ro{}

type ro struct{}

func (ro) config(t *Transaction) { t.readOnly = true }

var (

// Defined here for testing.

errReadAfterWrite = errors.New("firestore: read after write in transaction")

errWriteReadOnly = errors.New("firestore: write in read-only transaction")

errNestedTransaction = errors.New("firestore: nested transaction")

)

type transactionInProgressKey struct{}

// RunTransaction runs f in a transaction. f should use the transaction it is given

// for all Firestore operations. For any operation requiring a context, f should use

// the context it is passed, not the first argument to RunTransaction.

//

// f must not call Commit or Rollback on the provided Transaction.

//

// If f returns nil, RunTransaction commits the transaction. If the commit fails due

// to a conflicting transaction, RunTransaction retries f. It gives up and returns an

// error after a number of attempts that can be configured with the MaxAttempts

// option. If the commit succeeds, RunTransaction returns a nil error.

//

// If f returns non-nil, then the transaction will be rolled back and

// this method will return the same error. The function f is not retried.

//

// Note that when f returns, the transaction is not committed. Calling code

// must not assume that any of f's changes have been committed until

// RunTransaction returns nil.

//

// Since f may be called more than once, f should usually be idempotent – that is, it

// should have the same result when called multiple times.

func (c *Client) RunTransaction(ctx context.Context, f func(context.Context, *Transaction) error, opts ...TransactionOption) (err error) {

}

func (t *Transaction) rollback() {

}

// Get gets the document in the context of the transaction. The transaction holds a

// pessimistic lock on the returned document. If the document does not exist, Get

// returns a NotFound error, which can be checked with

//

// status.Code(err) == codes.NotFound

func (t *Transaction) Get(dr *DocumentRef) (*DocumentSnapshot, error) {

}

// GetAll retrieves multiple documents with a single call. The DocumentSnapshots are

// returned in the order of the given DocumentRefs. If a document is not present, the

// corresponding DocumentSnapshot's Exists method will return false. The transaction

// holds a pessimistic lock on all of the returned documents.

func (t *Transaction) GetAll(drs []*DocumentRef) ([]*DocumentSnapshot, error) {

}

// A Queryer is a Query or a CollectionRef. CollectionRefs act as queries whose

// results are all the documents in the collection.

type Queryer interface {

query() *Query

}

// Documents returns a DocumentIterator based on given Query or CollectionRef. The

// results will be in the context of the transaction.

func (t *Transaction) Documents(q Queryer) *DocumentIterator {

}

// DocumentRefs returns references to all the documents in the collection, including

// missing documents. A missing document is a document that does not exist but has

// sub-documents.

func (t *Transaction) DocumentRefs(cr *CollectionRef) *DocumentRefIterator {

}

// Create adds a Create operation to the Transaction.

// See DocumentRef.Create for details.

func (t *Transaction) Create(dr *DocumentRef, data interface{}) error {

return t.addWrites(dr.newCreateWrites(data))

}

// Set adds a Set operation to the Transaction.

// See DocumentRef.Set for details.

func (t *Transaction) Set(dr *DocumentRef, data interface{}, opts ...SetOption) error {

return t.addWrites(dr.newSetWrites(data, opts))

}

// Delete adds a Delete operation to the Transaction.

// See DocumentRef.Delete for details.

func (t *Transaction) Delete(dr *DocumentRef, opts ...Precondition) error {

return t.addWrites(dr.newDeleteWrites(opts))

}

// Update adds a new Update operation to the Transaction.

// See DocumentRef.Update for details.

func (t *Transaction) Update(dr *DocumentRef, data []Update, opts ...Precondition) error {

return t.addWrites(dr.newUpdatePathWrites(data, opts))

}

func (t *Transaction) addWrites(ws []*pb.Write, err error) error {

}

// WithReadOptions specifies constraints for accessing documents from the database,

// e.g. at what time snapshot to read the documents.

func (t *Transaction) WithReadOptions(opts ...ReadOption) *Transaction {

}