@stackonward/cli 1.4.0 → 1.5.0

package/dist/resources/templates/go-backend/internal/core/integrationevent/service.go

@@ -0,0 +1,283 @@
+package integrationevent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+
+	"{{module}}/internal/common/canonicaljson"
+)
+
+const (
+	maxSourceSystemLength  = 191
+	maxEventIDLength       = 191
+	maxEventTypeLength     = 191
+	maxSchemaVersionLength = 32
+	maxProductCodeLength   = 50
+	maxAggregateTypeLength = 128
+	maxAggregateRefLength  = 191
+)
+
+var productCodePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{1,49}$`)
+
+// ReceiverService 原子执行入站事件幂等、连续版本校验与消费者处理。
+type ReceiverService struct {
+	repo      Repository
+	txManager TransactionManager
+	registry  *HandlerRegistry
+	config    ReceiverConfig
+	now       func() time.Time
+}
+
+// NewReceiverService 创建入站事件接收服务。
+func NewReceiverService(repo Repository, txManager TransactionManager, registry *HandlerRegistry, config ReceiverConfig) (*ReceiverService, error) {
+	if repo == nil {
+		return nil, fmt.Errorf("integration event repository is required")
+	}
+	if txManager == nil {
+		return nil, fmt.Errorf("integration event transaction manager is required")
+	}
+	if registry == nil {
+		return nil, fmt.Errorf("integration event handler registry is required")
+	}
+	normalizedConfig, err := config.normalized()
+	if err != nil {
+		return nil, err
+	}
+	return &ReceiverService{
+		repo:      repo,
+		txManager: txManager,
+		registry:  registry,
+		config:    normalizedConfig,
+		now:       func() time.Time { return time.Now().UTC() },
+	}, nil
+}
+
+// Receive 按全局事件身份和订阅者聚合水位处理一个已验证信封。
+func (s *ReceiverService) Receive(ctx context.Context, envelope Envelope) (*ReceiveResult, error) {
+	normalized, payloadHash, err := normalizeEnvelope(envelope)
+	if err != nil {
+		return nil, err
+	}
+	handler, registered := s.registry.resolve(normalized.SourceSystem, normalized.EventType, normalized.SchemaVersion)
+	if !registered {
+		return nil, ErrHandlerNotRegistered
+	}
+
+	var result *ReceiveResult
+	err = s.txManager.WithTransaction(ctx, func(txCtx context.Context) error {
+		now := s.now().UTC()
+		incoming := &InboxRecord{
+			SourceSystem:     normalized.SourceSystem,
+			EventID:          normalized.EventID,
+			EventType:        normalized.EventType,
+			SchemaVersion:    normalized.SchemaVersion,
+			ProductCode:      normalized.ProductCode,
+			AggregateType:    normalized.AggregateType,
+			AggregateRef:     normalized.AggregateRef,
+			AggregateVersion: normalized.AggregateVersion,
+			PayloadHash:      payloadHash,
+			EventPayload:     normalized.CanonicalEnvelope,
+			ReceivedAt:       now,
+			CreatedAt:        now,
+		}
+		persisted, _, persistErr := s.repo.CreateOrLoadInbox(txCtx, incoming)
+		if persistErr != nil {
+			return persistErr
+		}
+		if matches, matchErr := inboxMatchesEnvelope(persisted, incoming); matchErr != nil {
+			return matchErr
+		} else if !matches {
+			return ErrIdentityConflict
+		}
+
+		receipt, receiptCreated, receiptErr := s.repo.CreateOrLockReceipt(txCtx, &ReceiptRecord{
+			SourceSystem:        normalized.SourceSystem,
+			SubscriberCode:      s.config.SubscriberCode,
+			EventID:             normalized.EventID,
+			Status:              ReceiptProcessingStatusProcessing,
+			ProcessingStartedAt: now,
+			CreatedAt:           now,
+			UpdatedAt:           now,
+		})
+		if receiptErr != nil {
+			return receiptErr
+		}
+		if !receiptCreated {
+			if receipt.Status != ReceiptProcessingStatusProcessed || receipt.ReceiptStatus == nil {
+				return ErrReceiptStateConflict
+			}
+			result = s.resultFor(normalized, ReceiptOutcomeDuplicate)
+			return nil
+		}
+
+		if lockErr := s.repo.LockAggregateScope(txCtx, normalized.SourceSystem, s.config.SubscriberCode, normalized.AggregateType, normalized.AggregateRef); lockErr != nil {
+			return lockErr
+		}
+		checkpoint, checkpointErr := s.repo.FindCheckpointForUpdate(txCtx, normalized.SourceSystem, s.config.SubscriberCode, normalized.AggregateType, normalized.AggregateRef)
+		if checkpointErr != nil {
+			return checkpointErr
+		}
+		outcome, sequenceErr := classifySequence(checkpoint, normalized, payloadHash)
+		if sequenceErr != nil {
+			return sequenceErr
+		}
+		if outcome == ReceiptOutcomeDuplicate {
+			if finalizeErr := s.repo.MarkReceiptProcessed(txCtx, receipt.ID, ReceiptOutcomeDuplicate, now); finalizeErr != nil {
+				return finalizeErr
+			}
+			result = s.resultFor(normalized, ReceiptOutcomeDuplicate)
+			return nil
+		}
+
+		handlerEnvelope := normalized
+		handlerEnvelope.CanonicalEnvelope = append(json.RawMessage(nil), normalized.CanonicalEnvelope...)
+		if handleErr := handler.Handle(txCtx, handlerEnvelope); handleErr != nil {
+			return &HandlerError{Cause: handleErr}
+		}
+		if checkpoint == nil {
+			checkpoint = &AggregateCheckpoint{
+				SourceSystem:         normalized.SourceSystem,
+				SubscriberCode:       s.config.SubscriberCode,
+				AggregateType:        normalized.AggregateType,
+				AggregateRef:         normalized.AggregateRef,
+				LastAggregateVersion: normalized.AggregateVersion,
+				LastEventID:          normalized.EventID,
+				LastPayloadHash:      payloadHash,
+				RevisionNo:           1,
+				CreatedAt:            now,
+				UpdatedAt:            now,
+			}
+			if createErr := s.repo.CreateCheckpoint(txCtx, checkpoint); createErr != nil {
+				return createErr
+			}
+		} else {
+			expectedRevision := checkpoint.RevisionNo
+			checkpoint.LastAggregateVersion = normalized.AggregateVersion
+			checkpoint.LastEventID = normalized.EventID
+			checkpoint.LastPayloadHash = payloadHash
+			checkpoint.RevisionNo++
+			checkpoint.UpdatedAt = now
+			if advanceErr := s.repo.AdvanceCheckpoint(txCtx, checkpoint, expectedRevision); advanceErr != nil {
+				return advanceErr
+			}
+		}
+		if finalizeErr := s.repo.MarkReceiptProcessed(txCtx, receipt.ID, ReceiptOutcomeProcessed, now); finalizeErr != nil {
+			return finalizeErr
+		}
+		result = s.resultFor(normalized, ReceiptOutcomeProcessed)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		return nil, fmt.Errorf("integration event receiver transaction produced no result")
+	}
+	return result, nil
+}
+
+func (s *ReceiverService) resultFor(envelope Envelope, outcome ReceiptOutcome) *ReceiveResult {
+	return &ReceiveResult{
+		SourceSystem:   envelope.SourceSystem,
+		SubscriberCode: s.config.SubscriberCode,
+		EventID:        envelope.EventID,
+		Outcome:        outcome,
+	}
+}
+
+func normalizeEnvelope(envelope Envelope) (Envelope, string, error) {
+	normalized := Envelope{
+		SourceSystem:      strings.TrimSpace(envelope.SourceSystem),
+		EventID:           strings.TrimSpace(envelope.EventID),
+		EventType:         strings.TrimSpace(envelope.EventType),
+		SchemaVersion:     strings.TrimSpace(envelope.SchemaVersion),
+		ProductCode:       strings.TrimSpace(envelope.ProductCode),
+		AggregateType:     strings.TrimSpace(envelope.AggregateType),
+		AggregateRef:      strings.TrimSpace(envelope.AggregateRef),
+		AggregateVersion:  envelope.AggregateVersion,
+		CanonicalEnvelope: append(json.RawMessage(nil), envelope.CanonicalEnvelope...),
+	}
+	for _, field := range []struct {
+		name  string
+		value string
+		limit int
+	}{
+		{"source_system", normalized.SourceSystem, maxSourceSystemLength},
+		{"event_id", normalized.EventID, maxEventIDLength},
+		{"event_type", normalized.EventType, maxEventTypeLength},
+		{"schema_version", normalized.SchemaVersion, maxSchemaVersionLength},
+		{"product_code", normalized.ProductCode, maxProductCodeLength},
+		{"aggregate_type", normalized.AggregateType, maxAggregateTypeLength},
+		{"aggregate_ref", normalized.AggregateRef, maxAggregateRefLength},
+	} {
+		if field.value == "" || len(field.value) > field.limit {
+			return Envelope{}, "", fmt.Errorf("%w: %s is empty or exceeds %d bytes", ErrEnvelopeInvalid, field.name, field.limit)
+		}
+	}
+	if !productCodePattern.MatchString(normalized.ProductCode) {
+		return Envelope{}, "", fmt.Errorf("%w: product_code is invalid", ErrEnvelopeInvalid)
+	}
+	if normalized.AggregateVersion <= 0 {
+		return Envelope{}, "", fmt.Errorf("%w: aggregate_version must be positive", ErrEnvelopeInvalid)
+	}
+	canonical, err := canonicaljson.Canonicalize(normalized.CanonicalEnvelope)
+	if err != nil {
+		return Envelope{}, "", fmt.Errorf("%w: canonicalize envelope: %v", ErrEnvelopeInvalid, err)
+	}
+	if len(canonical) == 0 || canonical[0] != '{' {
+		return Envelope{}, "", fmt.Errorf("%w: canonical envelope must be a JSON object", ErrEnvelopeInvalid)
+	}
+	normalized.CanonicalEnvelope = canonical
+	payloadHash, err := canonicaljson.Hash(canonical)
+	if err != nil {
+		return Envelope{}, "", fmt.Errorf("%w: hash canonical envelope: %v", ErrEnvelopeInvalid, err)
+	}
+	return normalized, payloadHash, nil
+}
+
+func inboxMatchesEnvelope(persisted, incoming *InboxRecord) (bool, error) {
+	if persisted == nil || incoming == nil {
+		return false, fmt.Errorf("integration event inbox comparison requires both records")
+	}
+	if persisted.SourceSystem != incoming.SourceSystem ||
+		persisted.EventID != incoming.EventID ||
+		persisted.EventType != incoming.EventType ||
+		persisted.SchemaVersion != incoming.SchemaVersion ||
+		persisted.ProductCode != incoming.ProductCode ||
+		persisted.AggregateType != incoming.AggregateType ||
+		persisted.AggregateRef != incoming.AggregateRef ||
+		persisted.AggregateVersion != incoming.AggregateVersion ||
+		persisted.PayloadHash != incoming.PayloadHash {
+		return false, nil
+	}
+	equal, err := canonicaljson.Equal(persisted.EventPayload, incoming.EventPayload)
+	if err != nil {
+		return false, fmt.Errorf("compare persisted integration event envelope: %w", err)
+	}
+	return equal, nil
+}
+
+func classifySequence(checkpoint *AggregateCheckpoint, envelope Envelope, payloadHash string) (ReceiptOutcome, error) {
+	if checkpoint == nil {
+		if envelope.AggregateVersion == 1 {
+			return ReceiptOutcomeProcessed, nil
+		}
+		return "", &VersionGapError{Expected: 1, Actual: envelope.AggregateVersion}
+	}
+	expected := checkpoint.LastAggregateVersion + 1
+	switch {
+	case envelope.AggregateVersion == expected:
+		return ReceiptOutcomeProcessed, nil
+	case envelope.AggregateVersion > expected:
+		return "", &VersionGapError{Expected: expected, Actual: envelope.AggregateVersion}
+	case envelope.AggregateVersion == checkpoint.LastAggregateVersion &&
+		envelope.EventID == checkpoint.LastEventID && payloadHash == checkpoint.LastPayloadHash:
+		return ReceiptOutcomeDuplicate, nil
+	default:
+		return "", ErrVersionConflict
+	}
+}