@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/database/transaction_test.go

@@ -0,0 +1,282 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+type transactionTestContextKey struct{}
+
+func TestRequireTransactionRejectsMissingOrInvalidContext(t *testing.T) {
+	tests := []struct {
+		name string
+		ctx  context.Context
+	}{
+		{
+			name: "missing transaction",
+			ctx:  context.Background(),
+		},
+		{
+			name: "invalid transaction value",
+			ctx:  context.WithValue(context.Background(), ctxTxKey{}, "invalid"),
+		},
+		{
+			name: "nil transaction",
+			ctx:  context.WithValue(context.Background(), ctxTxKey{}, (*transactionContext)(nil)),
+		},
+		{
+			name: "transaction without database",
+			ctx:  context.WithValue(context.Background(), ctxTxKey{}, &transactionContext{}),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := RequireTransaction(tt.ctx)
+			if err == nil {
+				t.Fatal("RequireTransaction() error = nil")
+			}
+			if err.Error() != "database transaction context is required" {
+				t.Fatalf("RequireTransaction() error = %q", err.Error())
+			}
+		})
+	}
+}
+
+func TestRequireTransactionRejectsCompletedTransactionContext(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+	var completedCtx context.Context
+	var transactionDB *gorm.DB
+
+	mock.ExpectBegin()
+	mock.ExpectCommit()
+
+	err := txManager.WithTransaction(context.Background(), func(txCtx context.Context) error {
+		completedCtx = txCtx
+		transactionDB = GetDB(txCtx, db)
+		return RequireTransaction(txCtx)
+	})
+	if err != nil {
+		t.Fatalf("WithTransaction() error = %v", err)
+	}
+	if err := RequireTransaction(completedCtx); err == nil {
+		t.Fatal("RequireTransaction() accepted a completed transaction context")
+	}
+	if completedDB := GetDB(completedCtx, db); completedDB != transactionDB {
+		t.Fatal("GetDB() silently escaped a completed transaction")
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRequireTransactionAcceptsRequiredTransactionWithoutNesting(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+
+	mock.ExpectBegin()
+	mock.ExpectCommit()
+
+	err := txManager.WithTransaction(context.Background(), func(txCtx context.Context) error {
+		if err := RequireTransaction(txCtx); err != nil {
+			return err
+		}
+
+		derivedCtx := context.WithValue(txCtx, transactionTestContextKey{}, "derived")
+		if err := RequireTransaction(derivedCtx); err != nil {
+			return err
+		}
+
+		outerDB := GetDB(txCtx, db)
+		return txManager.WithTransaction(txCtx, func(joinedCtx context.Context) error {
+			if err := RequireTransaction(joinedCtx); err != nil {
+				return err
+			}
+			if joinedDB := GetDB(joinedCtx, db); joinedDB != outerDB {
+				t.Fatal("WithTransaction() created a nested transaction context")
+			}
+			return nil
+		})
+	})
+	if err != nil {
+		t.Fatalf("WithTransaction() error = %v", err)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRequireTransactionAcceptsNewTransaction(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+
+	mock.ExpectBegin()
+	mock.ExpectCommit()
+
+	err := txManager.WithNewTransaction(context.Background(), func(txCtx context.Context) error {
+		return RequireTransaction(txCtx)
+	})
+	if err != nil {
+		t.Fatalf("WithNewTransaction() error = %v", err)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTransactionCompletionRunsAfterCommitWithoutTransactionContext(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+	var outcome TransactionCompletionOutcome
+	completionHadTransaction := false
+
+	mock.ExpectBegin()
+	mock.ExpectCommit()
+
+	err := txManager.WithTransaction(context.Background(), func(txCtx context.Context) error {
+		_, registered := RegisterTransactionCompletion(txCtx, func(completionCtx context.Context, value TransactionCompletionOutcome) error {
+			outcome = value
+			completionHadTransaction = RequireTransaction(completionCtx) == nil
+			return nil
+		})
+		if !registered {
+			t.Fatal("RegisterTransactionCompletion() registered = false")
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("WithTransaction() error = %v", err)
+	}
+	if outcome != TransactionCompletionCommitted {
+		t.Fatalf("completion outcome = %q", outcome)
+	}
+	if completionHadTransaction {
+		t.Fatal("transaction completion reused the completed transaction context")
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTransactionCompletionRunsInReverseOrderAfterRollback(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+	transactionErr := errors.New("business transaction failed")
+	completionErr := errors.New("external compensation failed")
+	var calls []string
+
+	mock.ExpectBegin()
+	mock.ExpectRollback()
+
+	err := txManager.WithTransaction(context.Background(), func(txCtx context.Context) error {
+		RegisterTransactionCompletion(txCtx, func(context.Context, TransactionCompletionOutcome) error {
+			calls = append(calls, "first")
+			return completionErr
+		})
+		RegisterTransactionCompletion(txCtx, func(_ context.Context, outcome TransactionCompletionOutcome) error {
+			if outcome != TransactionCompletionRolledBack {
+				t.Fatalf("completion outcome = %q", outcome)
+			}
+			calls = append(calls, "second")
+			return nil
+		})
+		return transactionErr
+	})
+	if !errors.Is(err, transactionErr) || !errors.Is(err, completionErr) {
+		t.Fatalf("WithTransaction() error = %v", err)
+	}
+	if !reflect.DeepEqual(calls, []string{"second", "first"}) {
+		t.Fatalf("completion calls = %#v", calls)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTransactionPreservesBusinessErrorIdentityWithoutCompletionFailure(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+	transactionErr := errors.New("business transaction failed")
+
+	mock.ExpectBegin()
+	mock.ExpectRollback()
+
+	err := txManager.WithTransaction(context.Background(), func(context.Context) error {
+		return transactionErr
+	})
+	if err != transactionErr {
+		t.Fatalf("WithTransaction() error identity changed: %v", err)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTransactionCompletionJoinsOutermostTransactionAndSupportsCancellation(t *testing.T) {
+	db, mock, closeDB := openTransactionMock(t)
+	defer closeDB()
+	txManager := NewTransactionManager(db)
+	completionCalls := 0
+
+	mock.ExpectBegin()
+	mock.ExpectCommit()
+
+	err := txManager.WithTransaction(context.Background(), func(txCtx context.Context) error {
+		return txManager.WithTransaction(txCtx, func(joinedCtx context.Context) error {
+			cancel, registered := RegisterTransactionCompletion(joinedCtx, func(context.Context, TransactionCompletionOutcome) error {
+				completionCalls++
+				return nil
+			})
+			if !registered {
+				t.Fatal("RegisterTransactionCompletion() registered = false")
+			}
+			cancel()
+			return nil
+		})
+	})
+	if err != nil {
+		t.Fatalf("WithTransaction() error = %v", err)
+	}
+	if completionCalls != 0 {
+		t.Fatalf("completion calls = %d", completionCalls)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRegisterTransactionCompletionRejectsMissingTransaction(t *testing.T) {
+	_, registered := RegisterTransactionCompletion(context.Background(), func(context.Context, TransactionCompletionOutcome) error {
+		return nil
+	})
+	if registered {
+		t.Fatal("RegisterTransactionCompletion() registered = true")
+	}
+}
+
+func openTransactionMock(t *testing.T) (*gorm.DB, sqlmock.Sqlmock, func()) {
+	t.Helper()
+	raw, mock, err := sqlmock.New()
+	if err != nil {
+		t.Fatalf("sqlmock.New() error = %v", err)
+	}
+	db, err := gorm.Open(postgres.New(postgres.Config{Conn: raw}), &gorm.Config{DisableAutomaticPing: true})
+	if err != nil {
+		_ = raw.Close()
+		t.Fatalf("gorm.Open() error = %v", err)
+	}
+	return db, mock, func() { _ = raw.Close() }
+}

package/dist/resources/templates/go-backend/internal/core/distlock/lock.go

@@ -0,0 +1,353 @@
+package distlock
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/go-redsync/redsync/v4"
+	rsredis "github.com/go-redsync/redsync/v4/redis"
+	"github.com/go-redsync/redsync/v4/redis/goredis/v9"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 锁接口
+// ═══════════════════════════════════════════════════════════════
+
+// Lock 已获取的分布式锁
+type Lock struct {
+	mutex    *redsync.Mutex
+	resource string
+}
+
+// Resource 获取被锁定的资源名
+func (l *Lock) Resource() string {
+	return l.resource
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 错误定义
+// ═══════════════════════════════════════════════════════════════
+
+// LockAcquisitionError 表示锁已被 Redis quorum 占用
+type LockAcquisitionError struct {
+	Resource string
+}
+
+func (e *LockAcquisitionError) Error() string {
+	return fmt.Sprintf("failed to acquire lock for resource: %s", e.Resource)
+}
+
+// LockOperationError 锁操作失败
+type LockOperationError struct {
+	Operation string
+	Resource  string
+	Cause     error
+}
+
+func (e *LockOperationError) Error() string {
+	return fmt.Sprintf("lock %s operation failed for resource: %s", e.Operation, e.Resource)
+}
+
+func (e *LockOperationError) Unwrap() error {
+	return e.Cause
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 配置
+// ═══════════════════════════════════════════════════════════════
+
+// Options 分布式锁配置
+type Options struct {
+	// 锁默认 TTL（默认 30s）
+	DefaultTTL time.Duration
+	// 获取锁重试次数（默认 3）
+	RetryCount int
+	// 重试间隔（默认 200ms）
+	RetryDelay time.Duration
+	// 键前缀（默认 "lock:"）
+	KeyPrefix string
+}
+
+// DefaultOptions 默认配置
+var DefaultOptions = Options{
+	DefaultTTL: 30 * time.Second,
+	RetryCount: 3,
+	RetryDelay: 200 * time.Millisecond,
+	KeyPrefix:  "lock:",
+}
+
+// AcquireOptions 获取锁选项
+type AcquireOptions struct {
+	// 锁 TTL（覆盖默认值）
+	TTL time.Duration
+	// 重试次数（覆盖默认值）
+	RetryCount *int
+	// 重试间隔（覆盖默认值）
+	RetryDelay time.Duration
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 分布式锁服务
+// ═══════════════════════════════════════════════════════════════
+
+// Service 基于 Redis 的分布式锁服务（使用 Redsync 实现 Redlock 算法）
+type Service struct {
+	logger  *zap.Logger
+	rs      *redsync.Redsync
+	options Options
+}
+
+// New 创建分布式锁服务
+func New(logger *zap.Logger, redisClient *redis.Client, opts ...Options) *Service {
+	opt := DefaultOptions
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+
+	pool := goredis.NewPool(redisClient)
+	rs := redsync.New(pool)
+
+	return &Service{
+		logger:  logger.Named("DistLock"),
+		rs:      rs,
+		options: opt,
+	}
+}
+
+// NewWithClients 使用多个 Redis 客户端创建（完整 Redlock）
+func NewWithClients(logger *zap.Logger, clients []*redis.Client, opts ...Options) *Service {
+	opt := DefaultOptions
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+
+	pools := make([]rsredis.Pool, len(clients))
+	for i, c := range clients {
+		pools[i] = goredis.NewPool(c)
+	}
+	rs := redsync.New(pools...)
+
+	logger.Named("DistLock").Info("initialized with multiple Redis instances",
+		zap.Int("instances", len(clients)),
+	)
+
+	return &Service{
+		logger:  logger.Named("DistLock"),
+		rs:      rs,
+		options: opt,
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 锁操作
+// ═══════════════════════════════════════════════════════════════
+
+// Acquire 获取分布式锁
+func (s *Service) Acquire(ctx context.Context, key string, opts ...AcquireOptions) (*Lock, error) {
+	resource := s.options.KeyPrefix + key
+
+	// 构建 Redsync Mutex 选项
+	var rsOpts []redsync.Option
+
+	ttl := s.options.DefaultTTL
+	retryCount := s.options.RetryCount
+	retryDelay := s.options.RetryDelay
+
+	if len(opts) > 0 {
+		opt := opts[0]
+		if opt.TTL > 0 {
+			ttl = opt.TTL
+		}
+		if opt.RetryCount != nil {
+			retryCount = *opt.RetryCount
+		}
+		if opt.RetryDelay > 0 {
+			retryDelay = opt.RetryDelay
+		}
+	}
+
+	rsOpts = append(rsOpts,
+		redsync.WithExpiry(ttl),
+		redsync.WithTries(retryCount+1), // redsync 的 tries 包含首次尝试
+		redsync.WithRetryDelay(retryDelay),
+	)
+
+	mutex := s.rs.NewMutex(resource, rsOpts...)
+
+	if err := mutex.LockContext(ctx); err != nil {
+		s.logger.Debug("failed to acquire lock",
+			zap.String("key", key),
+			zap.Error(err),
+		)
+
+		var takenErr *redsync.ErrTaken
+		if errors.As(err, &takenErr) {
+			return nil, &LockAcquisitionError{Resource: key}
+		}
+
+		cause := err
+		if ctxErr := ctx.Err(); ctxErr != nil && !errors.Is(err, ctxErr) {
+			cause = errors.Join(err, ctxErr)
+		}
+		return nil, &LockOperationError{Operation: "acquire", Resource: key, Cause: cause}
+	}
+
+	s.logger.Debug("lock acquired", zap.String("key", key))
+
+	return &Lock{
+		mutex:    mutex,
+		resource: key,
+	}, nil
+}
+
+// Release 释放锁
+func (s *Service) Release(ctx context.Context, lock *Lock) error {
+	ok, err := lock.mutex.UnlockContext(ctx)
+	if err != nil {
+		s.logger.Warn("failed to release lock",
+			zap.String("resource", lock.resource),
+			zap.Error(err),
+		)
+		return &LockOperationError{Operation: "release", Resource: lock.resource, Cause: err}
+	}
+
+	if !ok {
+		s.logger.Warn("lock was not released (may have expired)",
+			zap.String("resource", lock.resource),
+		)
+		return &LockOperationError{Operation: "release", Resource: lock.resource}
+	}
+
+	s.logger.Debug("lock released", zap.String("resource", lock.resource))
+	return nil
+}
+
+// Extend 延长锁的 TTL
+func (s *Service) Extend(ctx context.Context, lock *Lock) error {
+	ok, err := lock.mutex.ExtendContext(ctx)
+	if err != nil {
+		s.logger.Warn("failed to extend lock",
+			zap.String("resource", lock.resource),
+			zap.Error(err),
+		)
+		return &LockOperationError{Operation: "extend", Resource: lock.resource, Cause: err}
+	}
+
+	if !ok {
+		s.logger.Warn("lock extension failed (may have expired)",
+			zap.String("resource", lock.resource),
+		)
+		return &LockOperationError{Operation: "extend", Resource: lock.resource}
+	}
+
+	s.logger.Debug("lock extended", zap.String("resource", lock.resource))
+	return nil
+}
+
+// WithLock 在持有锁的情况下执行函数（自动获取和释放）
+func (s *Service) WithLock(ctx context.Context, key string, ttl time.Duration, fn func(ctx context.Context) error) error {
+	lock, err := s.Acquire(ctx, key, AcquireOptions{TTL: ttl})
+	if err != nil {
+		return err
+	}
+
+	defer func() {
+		if releaseErr := s.Release(ctx, lock); releaseErr != nil {
+			s.logger.Error("failed to release lock in WithLock",
+				zap.String("key", key),
+				zap.Error(releaseErr),
+			)
+		}
+	}()
+
+	return fn(ctx)
+}
+
+// WithRenewedLock 在持有锁并自动续租的情况下执行函数。
+func (s *Service) WithRenewedLock(ctx context.Context, key string, ttl time.Duration, fn func(ctx context.Context) error) error {
+	lock, err := s.Acquire(ctx, key, AcquireOptions{TTL: ttl})
+	if err != nil {
+		return err
+	}
+
+	runCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	done := make(chan struct{})
+	renewStopped := make(chan struct{})
+	extendErrCh := make(chan error, 1)
+	go func() {
+		defer close(renewStopped)
+		s.renewLockUntilDone(ctx, lock, ttl, done, extendErrCh, cancel)
+	}()
+
+	fnErr := fn(runCtx)
+	close(done)
+	<-renewStopped
+
+	if releaseErr := s.Release(ctx, lock); releaseErr != nil {
+		s.logger.Error("failed to release lock in WithRenewedLock",
+			zap.String("key", key),
+			zap.Error(releaseErr),
+		)
+		if fnErr == nil {
+			fnErr = releaseErr
+		}
+	}
+	if fnErr != nil {
+		select {
+		case extendErr := <-extendErrCh:
+			return extendErr
+		default:
+			return fnErr
+		}
+	}
+	select {
+	case extendErr := <-extendErrCh:
+		return extendErr
+	default:
+		return nil
+	}
+}
+
+func (s *Service) renewLockUntilDone(
+	ctx context.Context,
+	lock *Lock,
+	ttl time.Duration,
+	done <-chan struct{},
+	extendErrCh chan<- error,
+	cancel context.CancelFunc,
+) {
+	interval := ttl / 3
+	if interval <= 0 {
+		interval = time.Second
+	}
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			if err := s.Extend(ctx, lock); err != nil {
+				select {
+				case extendErrCh <- err:
+				default:
+				}
+				cancel()
+				return
+			}
+		case <-done:
+			return
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// IsReady 检查服务是否就绪
+func (s *Service) IsReady() bool {
+	return s.rs != nil
+}