diplomail (Stage E): LibreTranslate client + async translation worker

Synchronous translation on read (Stage D) blocks the HTTP handler on translator I/O. Stage E switches to "send moments-fast, deliver when translated": recipients whose preferred_language differs from the detected body_lang are inserted with available_at=NULL, and an async worker turns them on once a LibreTranslate call materialises the cache row (or fails terminally after 5 retries). Schema delta on diplomail_recipients: available_at, translation_attempts, next_translation_attempt_at, plus a snapshot recipient_preferred_language so the worker queries do not need a join. Read paths (ListInbox, GetMessage, UnreadCount) filter on available_at IS NOT NULL. Push fan-out is moved from Service to the worker so the recipient only sees the toast when the inbox row is actually visible. Translator backend is now a configurable choice: empty BACKEND_DIPLOMAIL_TRANSLATOR_URL → noop (deliver original); populated → LibreTranslate HTTP client. Per-attempt timeout, max attempts, and worker interval all live in DiplomailConfig. The HTTP client itself is unit-tested via httptest (happy path, BCP47 normalisation, unsupported pair, 5xx, identical src/dst, missing URL); worker delivery + fallback paths are covered by the testcontainers-backed e2e tests in diplomail_e2e_test.go. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-15 20:15:28 +02:00
parent e22f4b7800
commit 9f7c9099bc
16 changed files with 1222 additions and 155 deletions
@@ -13,14 +13,18 @@ import (
 )

 type DiplomailRecipients struct {
-	RecipientID       uuid.UUID `sql:"primary_key"`
-	MessageID         uuid.UUID
-	GameID            uuid.UUID
-	UserID            uuid.UUID
-	RecipientUserName string
-	RecipientRaceName *string
-	DeliveredAt       *time.Time
-	ReadAt            *time.Time
-	DeletedAt         *time.Time
-	NotifiedAt        *time.Time
+	RecipientID                uuid.UUID `sql:"primary_key"`
+	MessageID                  uuid.UUID
+	GameID                     uuid.UUID
+	UserID                     uuid.UUID
+	RecipientUserName          string
+	RecipientRaceName          *string
+	RecipientPreferredLanguage string
+	AvailableAt                *time.Time
+	TranslationAttempts        int32
+	NextTranslationAttemptAt   *time.Time
+	DeliveredAt                *time.Time
+	ReadAt                     *time.Time
+	DeletedAt                  *time.Time
+	NotifiedAt                 *time.Time
 }
@@ -17,16 +17,20 @@ type diplomailRecipientsTable struct {
 	postgres.Table

 	// Columns
-	RecipientID       postgres.ColumnString
-	MessageID         postgres.ColumnString
-	GameID            postgres.ColumnString
-	UserID            postgres.ColumnString
-	RecipientUserName postgres.ColumnString
-	RecipientRaceName postgres.ColumnString
-	DeliveredAt       postgres.ColumnTimestampz
-	ReadAt            postgres.ColumnTimestampz
-	DeletedAt         postgres.ColumnTimestampz
-	NotifiedAt        postgres.ColumnTimestampz
+	RecipientID                postgres.ColumnString
+	MessageID                  postgres.ColumnString
+	GameID                     postgres.ColumnString
+	UserID                     postgres.ColumnString
+	RecipientUserName          postgres.ColumnString
+	RecipientRaceName          postgres.ColumnString
+	RecipientPreferredLanguage postgres.ColumnString
+	AvailableAt                postgres.ColumnTimestampz
+	TranslationAttempts        postgres.ColumnInteger
+	NextTranslationAttemptAt   postgres.ColumnTimestampz
+	DeliveredAt                postgres.ColumnTimestampz
+	ReadAt                     postgres.ColumnTimestampz
+	DeletedAt                  postgres.ColumnTimestampz
+	NotifiedAt                 postgres.ColumnTimestampz

 	AllColumns     postgres.ColumnList
 	MutableColumns postgres.ColumnList
@@ -68,35 +72,43 @@ func newDiplomailRecipientsTable(schemaName, tableName, alias string) *Diplomail

 func newDiplomailRecipientsTableImpl(schemaName, tableName, alias string) diplomailRecipientsTable {
 	var (
-		RecipientIDColumn       = postgres.StringColumn("recipient_id")
-		MessageIDColumn         = postgres.StringColumn("message_id")
-		GameIDColumn            = postgres.StringColumn("game_id")
-		UserIDColumn            = postgres.StringColumn("user_id")
-		RecipientUserNameColumn = postgres.StringColumn("recipient_user_name")
-		RecipientRaceNameColumn = postgres.StringColumn("recipient_race_name")
-		DeliveredAtColumn       = postgres.TimestampzColumn("delivered_at")
-		ReadAtColumn            = postgres.TimestampzColumn("read_at")
-		DeletedAtColumn         = postgres.TimestampzColumn("deleted_at")
-		NotifiedAtColumn        = postgres.TimestampzColumn("notified_at")
-		allColumns              = postgres.ColumnList{RecipientIDColumn, MessageIDColumn, GameIDColumn, UserIDColumn, RecipientUserNameColumn, RecipientRaceNameColumn, DeliveredAtColumn, ReadAtColumn, DeletedAtColumn, NotifiedAtColumn}
-		mutableColumns          = postgres.ColumnList{MessageIDColumn, GameIDColumn, UserIDColumn, RecipientUserNameColumn, RecipientRaceNameColumn, DeliveredAtColumn, ReadAtColumn, DeletedAtColumn, NotifiedAtColumn}
-		defaultColumns          = postgres.ColumnList{}
+		RecipientIDColumn                = postgres.StringColumn("recipient_id")
+		MessageIDColumn                  = postgres.StringColumn("message_id")
+		GameIDColumn                     = postgres.StringColumn("game_id")
+		UserIDColumn                     = postgres.StringColumn("user_id")
+		RecipientUserNameColumn          = postgres.StringColumn("recipient_user_name")
+		RecipientRaceNameColumn          = postgres.StringColumn("recipient_race_name")
+		RecipientPreferredLanguageColumn = postgres.StringColumn("recipient_preferred_language")
+		AvailableAtColumn                = postgres.TimestampzColumn("available_at")
+		TranslationAttemptsColumn        = postgres.IntegerColumn("translation_attempts")
+		NextTranslationAttemptAtColumn   = postgres.TimestampzColumn("next_translation_attempt_at")
+		DeliveredAtColumn                = postgres.TimestampzColumn("delivered_at")
+		ReadAtColumn                     = postgres.TimestampzColumn("read_at")
+		DeletedAtColumn                  = postgres.TimestampzColumn("deleted_at")
+		NotifiedAtColumn                 = postgres.TimestampzColumn("notified_at")
+		allColumns                       = postgres.ColumnList{RecipientIDColumn, MessageIDColumn, GameIDColumn, UserIDColumn, RecipientUserNameColumn, RecipientRaceNameColumn, RecipientPreferredLanguageColumn, AvailableAtColumn, TranslationAttemptsColumn, NextTranslationAttemptAtColumn, DeliveredAtColumn, ReadAtColumn, DeletedAtColumn, NotifiedAtColumn}
+		mutableColumns                   = postgres.ColumnList{MessageIDColumn, GameIDColumn, UserIDColumn, RecipientUserNameColumn, RecipientRaceNameColumn, RecipientPreferredLanguageColumn, AvailableAtColumn, TranslationAttemptsColumn, NextTranslationAttemptAtColumn, DeliveredAtColumn, ReadAtColumn, DeletedAtColumn, NotifiedAtColumn}
+		defaultColumns                   = postgres.ColumnList{RecipientPreferredLanguageColumn, TranslationAttemptsColumn}
 	)

 	return diplomailRecipientsTable{
 		Table: postgres.NewTable(schemaName, tableName, alias, allColumns...),

 		//Columns
-		RecipientID:       RecipientIDColumn,
-		MessageID:         MessageIDColumn,
-		GameID:            GameIDColumn,
-		UserID:            UserIDColumn,
-		RecipientUserName: RecipientUserNameColumn,
-		RecipientRaceName: RecipientRaceNameColumn,
-		DeliveredAt:       DeliveredAtColumn,
-		ReadAt:            ReadAtColumn,
-		DeletedAt:         DeletedAtColumn,
-		NotifiedAt:        NotifiedAtColumn,
+		RecipientID:                RecipientIDColumn,
+		MessageID:                  MessageIDColumn,
+		GameID:                     GameIDColumn,
+		UserID:                     UserIDColumn,
+		RecipientUserName:          RecipientUserNameColumn,
+		RecipientRaceName:          RecipientRaceNameColumn,
+		RecipientPreferredLanguage: RecipientPreferredLanguageColumn,
+		AvailableAt:                AvailableAtColumn,
+		TranslationAttempts:        TranslationAttemptsColumn,
+		NextTranslationAttemptAt:   NextTranslationAttemptAtColumn,
+		DeliveredAt:                DeliveredAtColumn,
+		ReadAt:                     ReadAtColumn,
+		DeletedAt:                  DeletedAtColumn,
+		NotifiedAt:                 NotifiedAtColumn,

 		AllColumns:     allColumns,
 		MutableColumns: mutableColumns,
@@ -722,16 +722,20 @@ CREATE INDEX diplomail_messages_sender_user_idx
 -- rare admin notifications addressed to a player who no longer has an
 -- active membership in the game.
 CREATE TABLE diplomail_recipients (
-    recipient_id          uuid        PRIMARY KEY,
-    message_id            uuid        NOT NULL REFERENCES diplomail_messages (message_id) ON DELETE CASCADE,
-    game_id               uuid        NOT NULL,
-    user_id               uuid        NOT NULL,
-    recipient_user_name   text        NOT NULL,
-    recipient_race_name   text,
-    delivered_at          timestamptz,
-    read_at               timestamptz,
-    deleted_at            timestamptz,
-    notified_at           timestamptz,
+    recipient_id                  uuid        PRIMARY KEY,
+    message_id                    uuid        NOT NULL REFERENCES diplomail_messages (message_id) ON DELETE CASCADE,
+    game_id                       uuid        NOT NULL,
+    user_id                       uuid        NOT NULL,
+    recipient_user_name           text        NOT NULL,
+    recipient_race_name           text,
+    recipient_preferred_language  text        NOT NULL DEFAULT '',
+    available_at                  timestamptz,
+    translation_attempts          integer     NOT NULL DEFAULT 0,
+    next_translation_attempt_at   timestamptz,
+    delivered_at                  timestamptz,
+    read_at                       timestamptz,
+    deleted_at                    timestamptz,
+    notified_at                   timestamptz,
    CONSTRAINT diplomail_recipients_unique UNIQUE (message_id, user_id)
 );

@@ -740,7 +744,17 @@ CREATE INDEX diplomail_recipients_inbox_idx

 CREATE INDEX diplomail_recipients_unread_idx
    ON diplomail_recipients (user_id, game_id)
-    WHERE read_at IS NULL AND deleted_at IS NULL;
+    WHERE read_at IS NULL AND deleted_at IS NULL AND available_at IS NOT NULL;
+
+-- Index drives the translation worker's pending-pair pickup. The
+-- partial filter keeps the scan tight: terminal-state recipients
+-- (with a non-NULL available_at) never appear in this btree. The
+-- composite ordering puts the next-attempt clock first so the
+-- backoff filter (`next_translation_attempt_at <= now()`) seeks
+-- before the secondary cluster on (message_id, lang).
+CREATE INDEX diplomail_recipients_pending_translation_idx
+    ON diplomail_recipients (next_translation_attempt_at, message_id, recipient_preferred_language)
+    WHERE available_at IS NULL;

 -- diplomail_translations caches one rendered translation per
 -- (message, target_lang) so a broadcast addressed to many recipients