diplomail (Stage A→D): backend in-game diplomatic mail #10

Merged

developer merged 6 commits from feature/diplomail-backend into development 2026-05-15 18:43:27 +00:00

Conversation 0 Commits 6 Files Changed 46

+8194 -13

developer commented 2026-05-15 16:29:48 +00:00

Owner

Copy Link

Copy Source

Implements the diplomatic-mail backend in four CI-gated stages.

Stages

• A (this commit) — schema + personal single-recipient send / read / delete, push event, lobby unread badge, OpenAPI, e2e.
• B — admin / owner sends + lifecycle hooks (paused / cancelled / kick).
• C — paid-tier personal broadcast + admin multi-game broadcast + bulk purge.
• D — body-language detection (whatlanggo) + translation cache + async worker.

Plan reference

Design live at ~/.claude/plans/witty-honking-flamingo.md and summarised in backend/internal/diplomail/README.md.

Test plan

• go test ./... against the testcontainers harness
• OpenAPI contract test covers the new operations
• migrations smoke test sees the three new tables
• Stage B–D land on this branch before merging

Implements the diplomatic-mail backend in four CI-gated stages. ## Stages - **A (this commit)** — schema + personal single-recipient send / read / delete, push event, lobby unread badge, OpenAPI, e2e. - **B** — admin / owner sends + lifecycle hooks (paused / cancelled / kick). - **C** — paid-tier personal broadcast + admin multi-game broadcast + bulk purge. - **D** — body-language detection (whatlanggo) + translation cache + async worker. ## Plan reference Design live at `~/.claude/plans/witty-honking-flamingo.md` and summarised in `backend/internal/diplomail/README.md`. ## Test plan - [x] `go test ./...` against the testcontainers harness - [x] OpenAPI contract test covers the new operations - [x] migrations smoke test sees the three new tables - [ ] Stage B–D land on this branch before merging

developer added 1 commit 2026-05-15 16:29:48 +00:00

diplomail (Stage A): add in-game personal mail subsystem ... 535e27008f

Phase 28 of ui/PLAN.md needs a persistent player-to-player mail
channel; the existing `mail` package is a transactional email
outbox and the `notification` catalog is one-way platform events.
Stage A lands the schema (diplomail_messages / _recipients /
_translations), a single-recipient personal send/read/delete
service path, a `diplomail.message.received` push kind plumbed
through the notification pipeline, and an unread-counts endpoint
that drives the lobby badge. Admin / system mail, lifecycle hooks,
paid-tier broadcast, multi-game broadcast, bulk purge and language
detection / translation cache come in stages B–D.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

developer added 1 commit 2026-05-15 16:48:00 +00:00

diplomail (Stage B): admin/owner sends + lifecycle hooks ... b3f24cc440

Item 7 of the spec wants game-state and membership-state changes to
land as durable inbox entries the affected players can re-read after
the fact — push alone times out of the 5-minute ring buffer. Stage B
adds the admin-kind send matrix (owner-driven via /user, site-admin
driven via /admin) plus the lobby lifecycle hooks: paused / cancelled
emit a broadcast system mail to active members, kick / ban emit a
single-recipient system mail to the affected user (which they keep
read access to even after the membership row is revoked, per item 8).

Migration relaxes diplomail_messages_kind_sender_chk so an owner
sending kind=admin keeps sender_kind=player; the new
LifecyclePublisher dep on lobby.Service is wired through a thin
adapter in cmd/backend/main, mirroring how lobby's notification
publisher is plumbed today.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

developer added 1 commit 2026-05-15 17:02:52 +00:00

diplomail (Stage C): paid-tier broadcast + multi-game + cleanup ... 362f92e520

Closes out the producer-side of the diplomail surface. Paid-tier
players can fan out one personal message to the rest of the active
roster (gated on entitlement_snapshots.is_paid). Site admins gain a
multi-game broadcast (POST /admin/mail/broadcast with `selected` /
`all_running` scopes) and the bulk-purge endpoint that wipes
diplomail rows tied to games finished more than N years ago. An
admin listing (GET /admin/mail/messages) rounds out the
observability surface.

EntitlementReader and GameLookup are new narrow deps wired from
`*user.Service` and `*lobby.Service` in cmd/backend/main; the lobby
service grows a one-off `ListFinishedGamesBefore` helper for the
cleanup path (the cache evicts terminal-state games so the cache
walk is not enough). Stage D will swap LangUndetermined for an
actual body-language detector and add the translation cache.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

developer added 1 commit 2026-05-15 17:16:21 +00:00

diplomail (Stage D): language detection + lazy translation cache ... e22f4b7800

Replaces the LangUndetermined placeholder with whatlanggo-backed
body detection on every send path, then adds a translation cache
keyed on (message_id, target_lang) populated lazily on the
per-message read endpoint. The noop translator that ships with
Stage D returns engine="noop", which the service treats as
"translation unavailable" — wiring a real backend (LibreTranslate
HTTP client is the documented next step) is a one-file swap.

GetMessage and ListInbox now accept a targetLang argument; the HTTP
layer resolves the caller's accounts.preferred_language and
forwards it. Inbox uses the cache only (never calls the
translator) so bulk reads stay fast under future SaaS backends.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

developer added 1 commit 2026-05-15 18:15:39 +00:00

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

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>

developer added 1 commit 2026-05-15 18:35:45 +00:00

diplomail (Stage F): docs + edge-case tests + LibreTranslate recipe ... 2d36b54b8d

Closes the documentation gaps from the freshly-audited diplomail
implementation. FUNCTIONAL.md gains a §11 "Diplomatic mail" with
the full user-facing story across all five stages, mirrored into
FUNCTIONAL_ru.md as the project conventions require. A new
backend/docs/diplomail-translator-setup.md captures the
LibreTranslate operational recipe (Docker image, env wiring,
manual smoke test, troubleshooting). The package README gains a
"Multi-instance posture" note documenting the deliberate absence
of FOR UPDATE in the worker pickup query — single-instance is
safe today; multi-instance scaling will revisit the claim
mechanism.

Two small edge-case tests round things out: malformed
LibreTranslate response bodies (single string, short array,
empty array, missing field) must surface as errors so the worker
falls back instead of crashing; and an empty translation queue
must produce zero events on three consecutive Worker.Tick calls.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

developer merged commit 74c1e7ab24 into development 2026-05-15 18:43:27 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

developer

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: developer/galaxy-game#10