feat: mail service

2026-04-17 18:39:16 +02:00
parent 23ffcb7535
commit 5b7593e6f6
183 changed files with 31215 additions and 248 deletions
@@ -0,0 +1,200 @@
+// Package attempt defines the logical delivery-attempt entity owned by Mail
+// Service.
+package attempt
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"galaxy/mail/internal/domain/common"
+)
+
+// Status identifies the lifecycle state of one concrete delivery attempt.
+type Status string
+
+const (
+	// StatusScheduled reports that the attempt is durably planned but has not
+	// started execution yet.
+	StatusScheduled Status = "scheduled"
+
+	// StatusInProgress reports that one worker currently owns the attempt.
+	StatusInProgress Status = "in_progress"
+
+	// StatusProviderAccepted reports that the provider accepted the SMTP
+	// envelope.
+	StatusProviderAccepted Status = "provider_accepted"
+
+	// StatusProviderRejected reports that the provider rejected the SMTP
+	// envelope.
+	StatusProviderRejected Status = "provider_rejected"
+
+	// StatusTransportFailed reports that the attempt failed before a stable
+	// provider accept or reject result was obtained.
+	StatusTransportFailed Status = "transport_failed"
+
+	// StatusTimedOut reports that the provider call exceeded the configured
+	// execution deadline.
+	StatusTimedOut Status = "timed_out"
+
+	// StatusRenderFailed reports that template rendering failed before any
+	// provider interaction was attempted.
+	StatusRenderFailed Status = "render_failed"
+)
+
+// IsKnown reports whether Status is supported by the current Mail Service
+// attempt state machine.
+func (status Status) IsKnown() bool {
+	switch status {
+	case StatusScheduled,
+		StatusInProgress,
+		StatusProviderAccepted,
+		StatusProviderRejected,
+		StatusTransportFailed,
+		StatusTimedOut,
+		StatusRenderFailed:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsTerminal reports whether Status can no longer accept a lifecycle
+// transition.
+func (status Status) IsTerminal() bool {
+	switch status {
+	case StatusProviderAccepted,
+		StatusProviderRejected,
+		StatusTransportFailed,
+		StatusTimedOut,
+		StatusRenderFailed:
+		return true
+	default:
+		return false
+	}
+}
+
+// CanTransitionTo reports whether the current Status may move to next under
+// the frozen Stage 2 attempt lifecycle rules.
+func (status Status) CanTransitionTo(next Status) bool {
+	switch status {
+	case StatusScheduled:
+		switch next {
+		case StatusInProgress, StatusRenderFailed:
+			return true
+		}
+	case StatusInProgress:
+		switch next {
+		case StatusProviderAccepted, StatusProviderRejected, StatusTransportFailed, StatusTimedOut:
+			return true
+		}
+	}
+
+	return false
+}
+
+// Attempt stores one durable execution record for a delivery attempt.
+type Attempt struct {
+	// DeliveryID identifies the owning logical delivery.
+	DeliveryID common.DeliveryID
+
+	// AttemptNo stores the monotonically increasing attempt sequence number.
+	AttemptNo int
+
+	// ScheduledFor stores when the attempt becomes due.
+	ScheduledFor time.Time
+
+	// StartedAt stores when a worker claimed the attempt for execution.
+	StartedAt *time.Time
+
+	// FinishedAt stores when the attempt reached a terminal outcome.
+	FinishedAt *time.Time
+
+	// Status stores the current attempt lifecycle state.
+	Status Status
+
+	// ProviderClassification stores provider-specific or adapter-specific
+	// result classification details when available.
+	ProviderClassification string
+
+	// ProviderSummary stores redacted provider outcome details when available.
+	ProviderSummary string
+}
+
+// Validate reports whether Attempt satisfies the frozen Stage 2 structural and
+// lifecycle invariants.
+func (record Attempt) Validate() error {
+	if err := record.DeliveryID.Validate(); err != nil {
+		return fmt.Errorf("attempt delivery id: %w", err)
+	}
+	if record.AttemptNo < 1 {
+		return fmt.Errorf("attempt number must be at least 1")
+	}
+	if err := common.ValidateTimestamp("attempt scheduled for", record.ScheduledFor); err != nil {
+		return err
+	}
+	if !record.Status.IsKnown() {
+		return fmt.Errorf("attempt status %q is unsupported", record.Status)
+	}
+	if err := validateOptionalToken("attempt provider classification", record.ProviderClassification); err != nil {
+		return err
+	}
+	if err := validateOptionalToken("attempt provider summary", record.ProviderSummary); err != nil {
+		return err
+	}
+
+	switch record.Status {
+	case StatusScheduled:
+		if record.StartedAt != nil {
+			return fmt.Errorf("scheduled attempt must not contain started at")
+		}
+		if record.FinishedAt != nil {
+			return fmt.Errorf("scheduled attempt must not contain finished at")
+		}
+	case StatusInProgress:
+		if record.StartedAt == nil {
+			return fmt.Errorf("in-progress attempt must contain started at")
+		}
+		if err := common.ValidateTimestamp("attempt started at", *record.StartedAt); err != nil {
+			return err
+		}
+		if record.StartedAt.Before(record.ScheduledFor) {
+			return fmt.Errorf("attempt started at must not be before scheduled for")
+		}
+		if record.FinishedAt != nil {
+			return fmt.Errorf("in-progress attempt must not contain finished at")
+		}
+	default:
+		if record.StartedAt == nil {
+			return fmt.Errorf("terminal attempt must contain started at")
+		}
+		if err := common.ValidateTimestamp("attempt started at", *record.StartedAt); err != nil {
+			return err
+		}
+		if record.StartedAt.Before(record.ScheduledFor) {
+			return fmt.Errorf("attempt started at must not be before scheduled for")
+		}
+		if record.FinishedAt == nil {
+			return fmt.Errorf("terminal attempt must contain finished at")
+		}
+		if err := common.ValidateTimestamp("attempt finished at", *record.FinishedAt); err != nil {
+			return err
+		}
+		if record.FinishedAt.Before(*record.StartedAt) {
+			return fmt.Errorf("attempt finished at must not be before started at")
+		}
+	}
+
+	return nil
+}
+
+func validateOptionalToken(name string, value string) error {
+	if value == "" {
+		return nil
+	}
+	if strings.TrimSpace(value) != value {
+		return fmt.Errorf("%s must not contain surrounding whitespace", name)
+	}
+
+	return nil
+}
@@ -0,0 +1,168 @@
+package attempt
+
+import (
+	"testing"
+	"time"
+
+	"galaxy/mail/internal/domain/common"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestStatusCanTransitionTo(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		from Status
+		to   Status
+		want bool
+	}{
+		{name: "scheduled to in progress", from: StatusScheduled, to: StatusInProgress, want: true},
+		{name: "scheduled to render failed", from: StatusScheduled, to: StatusRenderFailed, want: true},
+		{name: "scheduled to accepted", from: StatusScheduled, to: StatusProviderAccepted, want: false},
+		{name: "in progress to accepted", from: StatusInProgress, to: StatusProviderAccepted, want: true},
+		{name: "in progress to rejected", from: StatusInProgress, to: StatusProviderRejected, want: true},
+		{name: "in progress to transport failed", from: StatusInProgress, to: StatusTransportFailed, want: true},
+		{name: "in progress to timed out", from: StatusInProgress, to: StatusTimedOut, want: true},
+		{name: "accepted terminal", from: StatusProviderAccepted, to: StatusTimedOut, want: false},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			require.Equal(t, tt.want, tt.from.CanTransitionTo(tt.to))
+		})
+	}
+}
+
+func TestStatusIsTerminal(t *testing.T) {
+	t.Parallel()
+
+	require.False(t, StatusScheduled.IsTerminal())
+	require.False(t, StatusInProgress.IsTerminal())
+	require.True(t, StatusProviderAccepted.IsTerminal())
+	require.True(t, StatusProviderRejected.IsTerminal())
+	require.True(t, StatusTransportFailed.IsTerminal())
+	require.True(t, StatusTimedOut.IsTerminal())
+	require.True(t, StatusRenderFailed.IsTerminal())
+}
+
+func TestAttemptValidate(t *testing.T) {
+	t.Parallel()
+
+	scheduledFor := time.Unix(1_775_121_700, 0).UTC()
+	startedAt := scheduledFor.Add(time.Minute)
+	finishedAt := startedAt.Add(2 * time.Second)
+
+	tests := []struct {
+		name    string
+		record  Attempt
+		wantErr bool
+	}{
+		{
+			name: "valid scheduled",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    1,
+				ScheduledFor: scheduledFor,
+				Status:       StatusScheduled,
+			},
+		},
+		{
+			name: "valid in progress",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    2,
+				ScheduledFor: scheduledFor,
+				StartedAt:    &startedAt,
+				Status:       StatusInProgress,
+			},
+		},
+		{
+			name: "valid terminal",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    3,
+				ScheduledFor: scheduledFor,
+				StartedAt:    &startedAt,
+				FinishedAt:   &finishedAt,
+				Status:       StatusProviderAccepted,
+			},
+		},
+		{
+			name: "valid render failed",
+			record: Attempt{
+				DeliveryID:             common.DeliveryID("delivery-123"),
+				AttemptNo:              4,
+				ScheduledFor:           scheduledFor,
+				StartedAt:              &startedAt,
+				FinishedAt:             &finishedAt,
+				Status:                 StatusRenderFailed,
+				ProviderClassification: "missing_required_variable",
+				ProviderSummary:        "missing required variables: player.name",
+			},
+		},
+		{
+			name: "attempt number must be positive",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				ScheduledFor: scheduledFor,
+				Status:       StatusScheduled,
+			},
+			wantErr: true,
+		},
+		{
+			name: "in progress missing started at",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    1,
+				ScheduledFor: scheduledFor,
+				Status:       StatusInProgress,
+			},
+			wantErr: true,
+		},
+		{
+			name: "terminal missing finished at",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    1,
+				ScheduledFor: scheduledFor,
+				StartedAt:    &startedAt,
+				Status:       StatusProviderRejected,
+			},
+			wantErr: true,
+		},
+		{
+			name: "finished before started",
+			record: Attempt{
+				DeliveryID:   common.DeliveryID("delivery-123"),
+				AttemptNo:    1,
+				ScheduledFor: scheduledFor,
+				StartedAt:    &startedAt,
+				FinishedAt:   &scheduledFor,
+				Status:       StatusTimedOut,
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := tt.record.Validate()
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+
+			require.NoError(t, err)
+		})
+	}
+}