go-transaction-manager

1
// Package trm contains of interfaces to programmatic transaction management.
2
package trm
3

4
//go:generate mockgen -source=$GOFILE -destination=drivers/mock/$GOFILE -package=mock
5

6
import (
7
	"context"
8
	"errors"
9
	"fmt"
10
)
11

12
var (
13
	// ErrTransaction is an error while working with a transaction.
14
	ErrTransaction = errors.New("transaction")
15
	// ErrAlreadyClosed occurs if the transaction was closed outside the Manager.
16
	ErrAlreadyClosed = errTransaction("already closed")
17

18
	// ErrBegin occurs when a transaction started with an error.
19
	ErrBegin = errTransaction("begin")
20
	// ErrCommit occurs when commit finished with an error.
21
	ErrCommit = errTransaction("commit")
22
	// ErrRollback occurs when rollback finished with an error.
23
	ErrRollback = errTransaction("rollback")
24

25
	// ErrNestedBegin occurs when nested transaction started with an error.
26
	ErrNestedBegin = errNested(ErrBegin, "nested")
27
	// ErrNestedCommit occurs when nested transaction finished with an error.
28
	ErrNestedCommit = errNested(ErrCommit, "nested")
29
	// ErrNestedRollback occurs when rollback nested transaction finished with an error.
30
	ErrNestedRollback = errNested(ErrRollback, "nested")
31
)
32

33
// TrFactory is used in Manager to creates Transaction.
34
type TrFactory func(ctx context.Context, s Settings) (context.Context, Transaction, error)
35

36
// NestedTrFactory creates nested Transaction.
37
type NestedTrFactory interface {
38
	Begin(ctx context.Context, s Settings) (context.Context, Transaction, error)
39
}
40

41
// Transaction wraps different transaction implementations.
42
type Transaction interface {
43
	// Transaction returns the real transaction sql.Tx, sqlx.Tx or another.
44
	Transaction() interface{}
45
	// Commit the trm.Transaction.
46
	// Commit should be used only inside of Manager.
47
	Commit(context.Context) error
48
	// Rollback the trm.Transaction.
49
	// Rollback should be used only inside of Manager.
50
	Rollback(context.Context) error
51
	// IsActive returns true if the transaction started but not committed or rolled back.
52
	IsActive() bool
53
	// Closed returns a channel that's closed when transaction committed or rolled back.
54
	Closed() <-chan struct{}
55
}
56

57
// transactionWithSP is used for tests to generate mock.
58
//
59
//nolint:unused
60
type transactionWithSP interface {
61
	Transaction
62
	NestedTrFactory
63
}
64

65
var (
66
	// ErrPropagation occurs because of Propagation setting.
67
	ErrPropagation = errTransaction("propagation")
68
	// ErrPropagationMandatory occurs when the transaction doesn't exist.
69
	ErrPropagationMandatory = errNested(ErrPropagation, "mandatory")
70
	// ErrPropagationNever occurs when the transaction already exists.
71
	ErrPropagationNever = errNested(ErrPropagation, "never")
72
)
73

74
// Propagation is a type for transaction propagation rules.
75
type Propagation int8
76

77
const (
78
	// PropagationRequired supports a current transaction, create a new one if none exists. This is default setting.
79
	PropagationRequired Propagation = iota
80
	// PropagationNested executes within a nested transaction
81
	// if a current transaction exists, create a new one if none exists.
82
	PropagationNested
83
	// PropagationsMandatory supports a current transaction, throws an exception if none exists.
84
	PropagationsMandatory
85
	// PropagationNever executes non-transactionally, throws an exception if a transaction exists.
86
	PropagationNever
87
	// PropagationNotSupported executes non-transactionally, suspends the current transaction if one exists.
88
	PropagationNotSupported
89
	// PropagationRequiresNew creates a new transaction, suspends the current transaction if one exists.
90
	PropagationRequiresNew
91
	// PropagationSupports supports a current transaction, execute non-transactionally if none exists.
92
	PropagationSupports
93
)
94

95
func errNested(err error, msg string) error {
96
	return fmt.Errorf("%w: %s", err, msg)
97
}
98

99
func errTransaction(msg string) error {
100
	return errNested(ErrTransaction, msg)
101
}
102