galaxy-game/mail/internal/service/renderdelivery/service.go

// Package renderdelivery implements deterministic rendering of template-mode
// deliveries.
package renderdelivery

import (
	"context"
	"errors"
	"fmt"
	"log/slog"
	"slices"
	"strings"
	"time"

	templatedir "galaxy/mail/internal/adapters/templates"
	"galaxy/mail/internal/domain/attempt"
	"galaxy/mail/internal/domain/common"
	deliverydomain "galaxy/mail/internal/domain/delivery"
	"galaxy/mail/internal/logging"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	oteltrace "go.opentelemetry.io/otel/trace"
)

var (
	// ErrServiceUnavailable reports that rendered or failed state could not be
	// persisted durably.
	ErrServiceUnavailable = errors.New("render delivery service unavailable")
)

const tracerName = "galaxy/mail/renderdelivery"

// FailureClassification identifies the stable render-failure classification
// surface.
type FailureClassification string

const (
	// FailureTemplateNotFound reports that the requested template family does
	// not exist in the catalog.
	FailureTemplateNotFound FailureClassification = "template_not_found"

	// FailureFallbackMissing reports that the requested locale is unavailable
	// and the mandatory `en` fallback variant is also missing.
	FailureFallbackMissing FailureClassification = "fallback_missing"

	// FailureTemplateParseFailed reports that a template variant could not be
	// parsed into a runnable form.
	FailureTemplateParseFailed FailureClassification = "template_parse_failed"

	// FailureMissingRequiredVariable reports that the accepted template
	// variables do not provide one or more required dot-path values.
	FailureMissingRequiredVariable FailureClassification = "missing_required_variable"

	// FailureTemplateExecuteFailed reports that template execution failed after
	// lookup and variable validation.
	FailureTemplateExecuteFailed FailureClassification = "template_execute_failed"
)

// IsKnown reports whether classification belongs to the stable render-failure
// surface.
func (classification FailureClassification) IsKnown() bool {
	switch classification {
	case FailureTemplateNotFound,
		FailureFallbackMissing,
		FailureTemplateParseFailed,
		FailureMissingRequiredVariable,
		FailureTemplateExecuteFailed:
		return true
	default:
		return false
	}
}

// Outcome identifies the coarse result of one render-delivery execution.
type Outcome string

const (
	// OutcomeRendered reports that template content was materialized and stored
	// durably as `mail_delivery.status=rendered`.
	OutcomeRendered Outcome = "rendered"

	// OutcomeFailed reports that rendering reached a classified terminal
	// failure and stored `mail_delivery.status=failed`.
	OutcomeFailed Outcome = "failed"
)

// IsKnown reports whether outcome belongs to the supported render-delivery
// result surface.
func (outcome Outcome) IsKnown() bool {
	switch outcome {
	case OutcomeRendered, OutcomeFailed:
		return true
	default:
		return false
	}
}

// Input stores one queued template delivery together with its current
// scheduled attempt.
type Input struct {
	// Delivery stores the queued template-mode delivery to render.
	Delivery deliverydomain.Delivery

	// Attempt stores the current scheduled attempt associated with Delivery.
	Attempt attempt.Attempt
}

// Validate reports whether input contains one queued template delivery and
// its scheduled attempt.
func (input Input) Validate() error {
	if err := input.Delivery.Validate(); err != nil {
		return fmt.Errorf("delivery: %w", err)
	}
	if err := input.Attempt.Validate(); err != nil {
		return fmt.Errorf("attempt: %w", err)
	}
	if input.Delivery.PayloadMode != deliverydomain.PayloadModeTemplate {
		return fmt.Errorf("delivery payload mode must be %q", deliverydomain.PayloadModeTemplate)
	}
	if input.Delivery.Status != deliverydomain.StatusQueued {
		return fmt.Errorf("delivery status must be %q", deliverydomain.StatusQueued)
	}
	if input.Attempt.DeliveryID != input.Delivery.DeliveryID {
		return errors.New("attempt delivery id must match delivery id")
	}
	if input.Attempt.AttemptNo < 1 {
		return errors.New("attempt number must be at least 1")
	}
	if input.Attempt.Status != attempt.StatusScheduled {
		return fmt.Errorf("attempt status must be %q", attempt.StatusScheduled)
	}

	return nil
}

// Result stores the durable outcome of one render-delivery execution.
type Result struct {
	// Outcome stores the coarse render-delivery result.
	Outcome Outcome

	// Delivery stores the durably persisted delivery record after rendering or
	// render failure handling.
	Delivery deliverydomain.Delivery

	// Attempt stores the durably persisted terminal attempt when Outcome is
	// failed. Successful rendering keeps the scheduled attempt unchanged and
	// therefore leaves Attempt nil.
	Attempt *attempt.Attempt

	// ResolvedLocale stores the actual filesystem locale variant used by
	// template lookup when available.
	ResolvedLocale common.Locale

	// LocaleFallbackUsed reports whether template lookup fell back from the
	// requested locale to `en`.
	LocaleFallbackUsed bool

	// TemplateVersion stores the version marker of the resolved template
	// variant when available.
	TemplateVersion string

	// FailureClassification stores the stable classified failure code when
	// Outcome is failed.
	FailureClassification FailureClassification
}

// Validate reports whether result contains a complete supported render
// outcome.
func (result Result) Validate() error {
	if !result.Outcome.IsKnown() {
		return fmt.Errorf("render delivery outcome %q is unsupported", result.Outcome)
	}
	if err := result.Delivery.Validate(); err != nil {
		return fmt.Errorf("delivery: %w", err)
	}

	switch result.Outcome {
	case OutcomeRendered:
		if result.Attempt != nil {
			return errors.New("rendered result must not contain terminal attempt")
		}
		if result.Delivery.Status != deliverydomain.StatusRendered {
			return fmt.Errorf("rendered result delivery status must be %q", deliverydomain.StatusRendered)
		}
		if result.ResolvedLocale.IsZero() {
			return errors.New("rendered result resolved locale must not be empty")
		}
		if err := result.ResolvedLocale.Validate(); err != nil {
			return fmt.Errorf("resolved locale: %w", err)
		}
		if strings.TrimSpace(result.TemplateVersion) == "" {
			return errors.New("rendered result template version must not be empty")
		}
		if result.FailureClassification != "" {
			return errors.New("rendered result must not contain failure classification")
		}
	case OutcomeFailed:
		if result.Attempt == nil {
			return errors.New("failed result must contain terminal attempt")
		}
		if err := result.Attempt.Validate(); err != nil {
			return fmt.Errorf("attempt: %w", err)
		}
		if result.Attempt.DeliveryID != result.Delivery.DeliveryID {
			return errors.New("attempt delivery id must match delivery id")
		}
		if result.Delivery.Status != deliverydomain.StatusFailed {
			return fmt.Errorf("failed result delivery status must be %q", deliverydomain.StatusFailed)
		}
		if result.Attempt.Status != attempt.StatusRenderFailed {
			return fmt.Errorf("failed result attempt status must be %q", attempt.StatusRenderFailed)
		}
		if !result.FailureClassification.IsKnown() {
			return fmt.Errorf("failed result classification %q is unsupported", result.FailureClassification)
		}
		if !result.ResolvedLocale.IsZero() {
			if err := result.ResolvedLocale.Validate(); err != nil {
				return fmt.Errorf("resolved locale: %w", err)
			}
		}
		if result.Delivery.LastAttemptStatus != attempt.StatusRenderFailed {
			return fmt.Errorf("failed result delivery last attempt status must be %q", attempt.StatusRenderFailed)
		}
	}

	return nil
}

// MarkRenderedInput stores the durable mutation applied after successful
// template materialization.
type MarkRenderedInput struct {
	// Delivery stores the rendered delivery record.
	Delivery deliverydomain.Delivery
}

// Validate reports whether input contains one rendered delivery record.
func (input MarkRenderedInput) Validate() error {
	if err := input.Delivery.Validate(); err != nil {
		return fmt.Errorf("delivery: %w", err)
	}
	if input.Delivery.Status != deliverydomain.StatusRendered {
		return fmt.Errorf("delivery status must be %q", deliverydomain.StatusRendered)
	}

	return nil
}

// MarkRenderFailedInput stores the durable mutation applied after classified
// render failure.
type MarkRenderFailedInput struct {
	// Delivery stores the failed delivery record.
	Delivery deliverydomain.Delivery

	// Attempt stores the terminal render-failed attempt record.
	Attempt attempt.Attempt
}

// Validate reports whether input contains one failed delivery record and its
// terminal render-failed attempt.
func (input MarkRenderFailedInput) Validate() error {
	if err := input.Delivery.Validate(); err != nil {
		return fmt.Errorf("delivery: %w", err)
	}
	if err := input.Attempt.Validate(); err != nil {
		return fmt.Errorf("attempt: %w", err)
	}
	if input.Delivery.Status != deliverydomain.StatusFailed {
		return fmt.Errorf("delivery status must be %q", deliverydomain.StatusFailed)
	}
	if input.Attempt.Status != attempt.StatusRenderFailed {
		return fmt.Errorf("attempt status must be %q", attempt.StatusRenderFailed)
	}
	if input.Attempt.DeliveryID != input.Delivery.DeliveryID {
		return errors.New("attempt delivery id must match delivery id")
	}
	if input.Delivery.LastAttemptStatus != attempt.StatusRenderFailed {
		return fmt.Errorf("delivery last attempt status must be %q", attempt.StatusRenderFailed)
	}

	return nil
}

// Store describes the durable persistence required by the render-delivery
// use case.
type Store interface {
	// MarkRendered stores the successful materialization result.
	MarkRendered(context.Context, MarkRenderedInput) error

	// MarkRenderFailed stores one classified terminal render failure.
	MarkRenderFailed(context.Context, MarkRenderFailedInput) error
}

// TemplateCatalog describes the immutable in-memory template registry used by
// the renderer.
type TemplateCatalog interface {
	// Lookup resolves one template family for locale using the frozen exact
	// match followed by `en` fallback rule.
	Lookup(common.TemplateID, common.Locale) (templatedir.ResolvedTemplate, error)
}

// Clock provides the current wall-clock time.
type Clock interface {
	// Now returns the current time.
	Now() time.Time
}

// Telemetry records low-cardinality render and delivery lifecycle metrics.
type Telemetry interface {
	// RecordDeliveryStatusTransition records one durable delivery status
	// transition.
	RecordDeliveryStatusTransition(context.Context, string, string)

	// RecordAttemptOutcome records one durable terminal attempt outcome.
	RecordAttemptOutcome(context.Context, string, string)

	// RecordLocaleFallback records one template locale fallback event.
	RecordLocaleFallback(context.Context, string, string, string)
}

// Config stores the dependencies used by Service.
type Config struct {
	// Catalog stores the immutable in-memory template registry.
	Catalog TemplateCatalog

	// Store owns the durable rendered and failed delivery state.
	Store Store

	// Clock provides the current time.
	Clock Clock

	// Telemetry records low-cardinality render and delivery lifecycle metrics.
	Telemetry Telemetry

	// TracerProvider constructs the application span recorder used by the
	// render flow.
	TracerProvider oteltrace.TracerProvider

	// Logger writes structured render logs.
	Logger *slog.Logger
}

// Service materializes queued template deliveries deterministically.
type Service struct {
	catalog        TemplateCatalog
	store          Store
	clock          Clock
	telemetry      Telemetry
	tracerProvider oteltrace.TracerProvider
	logger         *slog.Logger
}

// New constructs Service from cfg.
func New(cfg Config) (*Service, error) {
	switch {
	case cfg.Catalog == nil:
		return nil, errors.New("new render delivery service: nil catalog")
	case cfg.Store == nil:
		return nil, errors.New("new render delivery service: nil store")
	case cfg.Clock == nil:
		return nil, errors.New("new render delivery service: nil clock")
	default:
		tracerProvider := cfg.TracerProvider
		if tracerProvider == nil {
			tracerProvider = otel.GetTracerProvider()
		}
		logger := cfg.Logger
		if logger == nil {
			logger = slog.Default()
		}

		return &Service{
			catalog:        cfg.Catalog,
			store:          cfg.Store,
			clock:          cfg.Clock,
			telemetry:      cfg.Telemetry,
			tracerProvider: tracerProvider,
			logger:         logger.With("component", "render_delivery"),
		}, nil
	}
}

// Execute resolves, validates, renders, and durably stores one template-mode
// delivery outcome.
func (service *Service) Execute(ctx context.Context, input Input) (Result, error) {
	if ctx == nil {
		return Result{}, errors.New("render delivery: nil context")
	}
	if service == nil {
		return Result{}, errors.New("render delivery: nil service")
	}
	if err := input.Validate(); err != nil {
		return Result{}, fmt.Errorf("render delivery: %w", err)
	}

	ctx, span := service.tracerProvider.Tracer(tracerName).Start(ctx, "mail.render_delivery")
	defer span.End()
	span.SetAttributes(
		attribute.String("mail.delivery_id", input.Delivery.DeliveryID.String()),
		attribute.String("mail.source", string(input.Delivery.Source)),
		attribute.String("mail.template_id", input.Delivery.TemplateID.String()),
		attribute.Int("mail.attempt_no", input.Attempt.AttemptNo),
		attribute.String("mail.requested_locale", input.Delivery.Locale.String()),
	)

	resolved, err := service.catalog.Lookup(input.Delivery.TemplateID, input.Delivery.Locale)
	if err != nil {
		classification := classifyLookupError(err)
		return service.fail(ctx, input, classification, failureSummaryForLookup(input.Delivery, classification), nil)
	}

	requiredPaths := resolved.RequiredVariablePaths()
	missingPaths := collectMissingPaths(input.Delivery.TemplateVariables, requiredPaths)
	if len(missingPaths) > 0 {
		result, failErr := service.fail(
			ctx,
			input,
			FailureMissingRequiredVariable,
			failureSummaryForMissingVariables(missingPaths),
			&resolved,
		)
		if failErr != nil {
			return Result{}, failErr
		}
		return result, nil
	}

	content, err := renderContent(resolved, input.Delivery.TemplateVariables)
	if err != nil {
		result, failErr := service.fail(
			ctx,
			input,
			FailureTemplateExecuteFailed,
			"template execution failed",
			&resolved,
		)
		if failErr != nil {
			return Result{}, failErr
		}
		return result, nil
	}

	renderedDelivery := input.Delivery
	renderedDelivery.Content = content
	renderedDelivery.Status = deliverydomain.StatusRendered
	renderedDelivery.LocaleFallbackUsed = resolved.LocaleFallbackUsed()
	renderedDelivery.UpdatedAt = service.clock.Now().UTC().Truncate(time.Millisecond)
	if err := renderedDelivery.Validate(); err != nil {
		return Result{}, fmt.Errorf("render delivery: build rendered delivery: %w", err)
	}

	if err := service.store.MarkRendered(ctx, MarkRenderedInput{Delivery: renderedDelivery}); err != nil {
		return Result{}, fmt.Errorf("%w: store rendered delivery: %v", ErrServiceUnavailable, err)
	}
	service.recordStatusTransition(ctx, renderedDelivery)

	result := Result{
		Outcome:            OutcomeRendered,
		Delivery:           renderedDelivery,
		ResolvedLocale:     resolved.ResolvedLocale(),
		LocaleFallbackUsed: resolved.LocaleFallbackUsed(),
		TemplateVersion:    resolved.Template().Version,
	}
	if err := result.Validate(); err != nil {
		return Result{}, fmt.Errorf("render delivery: build rendered result: %w", err)
	}
	span.SetAttributes(
		attribute.String("mail.resolved_locale", result.ResolvedLocale.String()),
		attribute.Bool("mail.locale_fallback_used", result.LocaleFallbackUsed),
		attribute.String("mail.status", string(renderedDelivery.Status)),
	)
	logArgs := logging.DeliveryAttemptAttrs(renderedDelivery, input.Attempt)
	logArgs = append(logArgs,
		"requested_locale", input.Delivery.Locale.String(),
		"resolved_locale", result.ResolvedLocale.String(),
		"locale_fallback_used", result.LocaleFallbackUsed,
		"template_version", result.TemplateVersion,
	)
	logArgs = append(logArgs, logging.TraceAttrsFromContext(ctx)...)
	if result.LocaleFallbackUsed {
		service.recordLocaleFallback(ctx, renderedDelivery.TemplateID.String(), input.Delivery.Locale.String(), result.ResolvedLocale.String())
		service.logger.Info("delivery rendered with locale fallback", logArgs...)
	} else {
		service.logger.Info("delivery rendered", logArgs...)
	}

	return result, nil
}

func (service *Service) fail(
	ctx context.Context,
	input Input,
	classification FailureClassification,
	summary string,
	resolved *templatedir.ResolvedTemplate,
) (Result, error) {
	failureAt := service.clock.Now().UTC().Truncate(time.Millisecond)
	if failureAt.Before(input.Attempt.ScheduledFor) {
		failureAt = input.Attempt.ScheduledFor
	}

	failedDelivery := input.Delivery
	failedDelivery.Status = deliverydomain.StatusFailed
	failedDelivery.LastAttemptStatus = attempt.StatusRenderFailed
	failedDelivery.ProviderSummary = summary
	failedDelivery.UpdatedAt = failureAt
	failedDelivery.FailedAt = ptrTime(failureAt)

	failedAttempt := input.Attempt
	failedAttempt.Status = attempt.StatusRenderFailed
	failedAttempt.StartedAt = ptrTime(failureAt)
	failedAttempt.FinishedAt = ptrTime(failureAt)
	failedAttempt.ProviderClassification = string(classification)
	failedAttempt.ProviderSummary = summary

	storeInput := MarkRenderFailedInput{
		Delivery: failedDelivery,
		Attempt:  failedAttempt,
	}
	if err := storeInput.Validate(); err != nil {
		return Result{}, fmt.Errorf("render delivery: build failed result: %w", err)
	}

	if err := service.store.MarkRenderFailed(ctx, storeInput); err != nil {
		return Result{}, fmt.Errorf("%w: store failed delivery: %v", ErrServiceUnavailable, err)
	}
	service.recordStatusTransition(ctx, failedDelivery)
	service.recordAttemptOutcome(ctx, failedAttempt.Status, failedDelivery.Source)

	result := Result{
		Outcome:               OutcomeFailed,
		Delivery:              failedDelivery,
		Attempt:               &failedAttempt,
		FailureClassification: classification,
	}
	if resolved != nil {
		result.ResolvedLocale = resolved.ResolvedLocale()
		result.LocaleFallbackUsed = resolved.LocaleFallbackUsed()
		result.TemplateVersion = resolved.Template().Version
	}
	if err := result.Validate(); err != nil {
		return Result{}, fmt.Errorf("render delivery: build failed result: %w", err)
	}
	spanAttrs := []attribute.KeyValue{
		attribute.String("mail.status", string(failedDelivery.Status)),
		attribute.String("mail.attempt_status", string(failedAttempt.Status)),
		attribute.String("mail.failure_classification", string(classification)),
	}
	if resolved != nil {
		spanAttrs = append(spanAttrs, attribute.String("mail.resolved_locale", resolved.ResolvedLocale().String()))
	}
	oteltrace.SpanFromContext(ctx).SetAttributes(spanAttrs...)
	logArgs := logging.DeliveryAttemptAttrs(failedDelivery, failedAttempt)
	logArgs = append(logArgs,
		"failure_classification", string(classification),
		"provider_summary", summary,
	)
	if resolved != nil {
		logArgs = append(logArgs,
			"requested_locale", input.Delivery.Locale.String(),
			"resolved_locale", resolved.ResolvedLocale().String(),
			"locale_fallback_used", resolved.LocaleFallbackUsed(),
		)
	}
	logArgs = append(logArgs, logging.TraceAttrsFromContext(ctx)...)
	service.logger.Warn("delivery rendering failed", logArgs...)

	return result, nil
}

func (service *Service) recordStatusTransition(ctx context.Context, record deliverydomain.Delivery) {
	if service == nil || service.telemetry == nil {
		return
	}

	service.telemetry.RecordDeliveryStatusTransition(ctx, string(record.Status), string(record.Source))
}

func (service *Service) recordAttemptOutcome(ctx context.Context, status attempt.Status, source deliverydomain.Source) {
	if service == nil || service.telemetry == nil {
		return
	}

	service.telemetry.RecordAttemptOutcome(ctx, string(status), string(source))
}

func (service *Service) recordLocaleFallback(ctx context.Context, templateID string, requestedLocale string, resolvedLocale string) {
	if service == nil || service.telemetry == nil {
		return
	}

	service.telemetry.RecordLocaleFallback(ctx, templateID, requestedLocale, resolvedLocale)
}

func renderContent(resolved templatedir.ResolvedTemplate, variables map[string]any) (deliverydomain.Content, error) {
	subject, err := resolved.ExecuteSubject(variables)
	if err != nil {
		return deliverydomain.Content{}, err
	}

	textBody, err := resolved.ExecuteText(variables)
	if err != nil {
		return deliverydomain.Content{}, err
	}

	htmlBody, ok, err := resolved.ExecuteHTML(variables)
	if err != nil {
		return deliverydomain.Content{}, err
	}
	if !ok {
		htmlBody = ""
	}

	content := deliverydomain.Content{
		Subject:  subject,
		TextBody: textBody,
		HTMLBody: htmlBody,
	}
	if err := content.ValidateMaterialized(); err != nil {
		return deliverydomain.Content{}, err
	}

	return content, nil
}

func collectMissingPaths(variables map[string]any, requiredPaths []string) []string {
	missing := make([]string, 0)
	for _, path := range requiredPaths {
		if hasJSONPath(variables, path) {
			continue
		}
		missing = append(missing, path)
	}

	return missing
}

func hasJSONPath(value map[string]any, path string) bool {
	if len(value) == 0 || strings.TrimSpace(path) == "" {
		return false
	}

	current := any(value)
	for _, part := range strings.Split(path, ".") {
		typed, ok := current.(map[string]any)
		if !ok {
			return false
		}

		next, ok := typed[part]
		if !ok {
			return false
		}
		current = next
	}

	return true
}

func classifyLookupError(err error) FailureClassification {
	switch {
	case errors.Is(err, templatedir.ErrFallbackMissing):
		return FailureFallbackMissing
	case errors.Is(err, templatedir.ErrTemplateParseFailed):
		return FailureTemplateParseFailed
	default:
		return FailureTemplateNotFound
	}
}

func failureSummaryForLookup(record deliverydomain.Delivery, classification FailureClassification) string {
	switch classification {
	case FailureFallbackMissing:
		return fmt.Sprintf(
			"template %q locale %q and fallback %q are unavailable",
			record.TemplateID,
			record.Locale,
			common.Locale("en"),
		)
	case FailureTemplateParseFailed:
		return "template parsing failed"
	default:
		return fmt.Sprintf("template %q is not available", record.TemplateID)
	}
}

func failureSummaryForMissingVariables(missingPaths []string) string {
	cloned := append([]string(nil), missingPaths...)
	slices.Sort(cloned)

	return "missing required variables: " + strings.Join(cloned, ", ")
}

func ptrTime(value time.Time) *time.Time {
	return &value
}