core-framework 3.1.0__tar.gz → 3.2.0__tar.gz

{core_framework-3.1.0 → core_framework-3.2.0}/.cursor/rules/error-boundary.mdc

@@ -37,7 +37,7 @@ Platform contract: **`docs/platform/client-error-visibility.md`**. Domain import
 
 ## Catalog constants
 
-**`GENERIC_BAD_REQUEST_DETAIL`** (400), **`GENERIC_NOT_FOUND_DETAIL`** (404), **`GENERIC_FORBIDDEN_DETAIL`** (403), **`GENERIC_CONFLICT_DETAIL`** (409), ingest 413/415, **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
+**`GENERIC_BAD_REQUEST_DETAIL`** (400), **`GENERIC_NOT_FOUND_DETAIL`** (404), **`GENERIC_FORBIDDEN_DETAIL`** (403), **`GENERIC_CONFLICT_DETAIL`** (409), ingest 413/415, **`GENERIC_SERVICE_UNAVAILABLE_DETAIL`** (503), **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
 
 ## Anti-enumeration (public routes)
 

{core_framework-3.1.0 → core_framework-3.2.0}/.cursor/skills/sync-host-rules/SKILL.md

@@ -31,6 +31,14 @@ Diff by **basename** against the host's **`.cursor/`** and applicable **`docs/`*
 
 **Do not overwrite** host-only rules, skills, or product docs.
 
+### Transactional email (when the bumped core ships it)
+
+Remind the host (via upgrade notes / playbook, not code changes here):
+
+1. Put **`register_email_content`** in the **same** shared host bootstrap helper API and worker already call — worker is load-bearing.
+1. Register branded renderers **before** **`EMAIL_ENABLED=true`** (core default deletion copy is generic English).
+1. Do **not** **`enqueue_transactional_email`** for **`account_deletion_scheduled`** unless the host re-implements gated checks — use the core gated task.
+
 ### `docs/deployments/guides/` layout
 
 Core walkthroughs live under **`docs/deployments/guides/setup/`** (one-time install) and **`docs/deployments/guides/playbook/`** (ops / incident runbooks) — not a flat **`guides/`** directory.

{core_framework-3.1.0 → core_framework-3.2.0}/.github/workflows/_deploy.yml

@@ -86,6 +86,11 @@ jobs:
           RETENTION_POST_VIEWS_DAYS: ${{ vars.RETENTION_POST_VIEWS_DAYS }}
           RETENTION_READ_NOTIFICATIONS_DAYS: ${{ vars.RETENTION_READ_NOTIFICATIONS_DAYS }}
           ANALYTICS_REFRESH_INTERVAL_SECONDS: ${{ vars.ANALYTICS_REFRESH_INTERVAL_SECONDS }}
+          EMAIL_ENABLED: ${{ vars.EMAIL_ENABLED }}
+          EMAIL_PROVIDER: ${{ vars.EMAIL_PROVIDER }}
+          EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
+          EMAIL_FROM_ADDRESS: ${{ vars.EMAIL_FROM_ADDRESS }}
+          EMAIL_FROM_NAME: ${{ vars.EMAIL_FROM_NAME }}
         run: |
           set -euo pipefail
 

{core_framework-3.1.0 → core_framework-3.2.0}/.gitignore

@@ -18,6 +18,7 @@ logs/
 
 # Coverage
 .coverage
+.coverage.*
 htmlcov/
 .hypothesis/
 

{core_framework-3.1.0 → core_framework-3.2.0}/CHANGELOG.md

@@ -4,6 +4,36 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-07-20
+
+### Added
+
+- **Transactional email (Resend):** Capability-only email domain (port + facade + Resend adapter), **`[email]`** Settings (`provider` allowlist **`resend`**; **`api_key`** / **`from_address`** required when enabled; **`from_name`** composition; values stripped; CR/LF rejected in envelope fields when enabled), content registry with host **`register_email_content`** (replace-on-duplicate; put all kinds in **one** shared host bootstrap helper called from API **and** worker — worker is load-bearing), generic **`enqueue_transactional_email`** / **`process_transactional_email`**, and gated **`process_account_deletion_scheduled_email`** after a **newly** scheduled **`PUT /users/me/account/deletion`**. Schedule/cancel HTTP stay **204**; mail is best-effort (verified Firebase email only; missing/unverified skips without failing the schedule). Default deletion copy is generic English (no `user_id` in body). Deploy: **`EMAIL_*`** vars + **`EMAIL_API_KEY`** secret. Design: **`docs/design/transactional-email-design.md`**.
+
+### Breaking
+
+- **Breaking (hosts — config):** Add **`job_timeout`** under **`[worker]`** (required on **`Settings`**; core **`config.toml`** / template ship **300**). Nested env override **`WORKER__JOB_TIMEOUT`**. `Settings` rejects values above **300** so the outbox visibility lease (**420s**) keeps **120s** of queue/finalization headroom. ARQ **`job_completion_wait`** is **`job_timeout` + 30s** (hooks/Redis after the timed coroutine; ARQ 0.28 applies this wait to **SIGTERM and SIGINT**, so local Ctrl+C waits the same budget). Deploy worker compose should keep **`stop_grace_period`** above that wait plus shutdown teardown (core ships **360s** for the default **300s** timeout).
+
+### Changed
+
+- **Domain strong-read renames (hosts calling domain services/repositories):** Stats-aggregation and destructive-purge recount helpers that previously used normal-read names now exist only as **`*_strong`** accessors (replica-safe recount / write-adjacent enumeration). Update call sites:
+  - **post:** `retrieve_post_ids_by_author_id` → `retrieve_post_ids_by_author_id_strong`; `retrieve_post_like_count` → `retrieve_post_like_count_strong`; `retrieve_post_view_count_delta` → `retrieve_post_view_count_delta_strong` (matching `select_*_strong` on the repository).
+  - **comment:** `retrieve_post_comment_count` → `retrieve_post_comment_count_strong`; `retrieve_comment_like_count` → `retrieve_comment_like_count_strong`; `retrieve_comment_reply_count` → `retrieve_comment_reply_count_strong`.
+  - **user:** `retrieve_user_follow_counts` → `retrieve_user_follow_counts_strong`.
+  - **moderation:** `retrieve_post_report_count` → `retrieve_post_report_count_strong`; `retrieve_comment_report_count` → `retrieve_comment_report_count_strong`.
+
+### Fixed
+
+- **Public profile false 404 on snapshot miss:** `GET /users/{target_user_id}/profile` falls back to a strong full-detail load when the Redis/replica presentation snapshot misses but the authoritative profile still exists.
+- **Worker media decode / shutdown timeouts:** Avatar, banner, and attachment encode/probe run in a **warm spawn worker** (one per API/worker process, serialized) with separate **30s admission** and **30s execution** deadlines, so queue wait does not consume image-processing time. Admission saturation leaves active work untouched: attachment ingest returns retryable **503** with **`Retry-After: 30`**, and media worker jobs raise explicit ARQ retry. Execution timeout terminates and replaces the affected Pillow worker. Worker settings wire ARQ **`job_timeout`** from **`[worker].job_timeout`** and **`job_completion_wait`** as **`job_timeout` + 30s**; deploy worker compose uses **`stop_grace_period: 360s`**.
+- **Cache invalidation failure semantics:** Post-write paths (including admin mutations and media) use best-effort invalidation. Public-profile reads independently strong-read current existence and visibility, so failed invalidation may stale presentation fields but cannot expose a full card after a privacy change or keep a deleted profile visible. Admin cache tooling uses strict invalidation: exact-key requests log and continue on per-item failures; pattern-invalidation worker jobs re-raise so the failure is visible in ARQ/logs, but ordinary exceptions are terminal (no ARQ auto-retry)—operators resubmit the pattern request after Redis recovers.
+- **Outbox timeout headroom:** The visibility lease is **420s**, with `Settings` enforcing **120s** of expected queue/finalization headroom beyond the maximum permitted **300s** global worker job timeout.
+- **Event tokens:** Each issued token embeds a fresh ULID payload so impression dedup on `(post_id, token)` no longer collapses unrelated clients that previously shared empty-payload tokens. Docs describe collision risk as negligible rather than impossible.
+- **Unknown mentions:** Post/comment mention references use `UserIdentity.DEFAULT` for missing users instead of echoing the stored `user_id` as `username`, which could fail response validation and 500 feed reads.
+- **Notification failures after commit:** In-app notification attempts after a successful primary write log and swallow errors so a missed notification cannot turn the write into an HTTP 500 or skip follow-up scheduling. Flow docs for post/comment create and follow state this as best-effort (not on the outbox).
+- **Username case sensitivity:** Availability checks and database uniqueness are **case-sensitive** (exact string match in Postgres and the taken-usernames cache). Docs that previously described case-insensitive checks were corrected.
+- **Strong reads for write-adjacent counts:** Stats aggregation recounts and destructive user purge post-id enumeration use strong reads so replica lag cannot permanently stale counters or leave orphan comments. Flow docs link to platform/design for that mechanics; they no longer embed strong-read implementation detail.
+
 ## [3.1.0] - 2026-07-16
 
 ### Fixed
@@ -572,4 +602,5 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [2.3.3]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.2...v2.3.3
 [3.0.0]: https://github.com/NepNepFFXIV/core-framework/compare/v2.3.3...v3.0.0
 [3.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v3.0.0...v3.1.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v3.1.0...HEAD
+[3.2.0]: https://github.com/NepNepFFXIV/core-framework/compare/v3.1.0...v3.2.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v3.2.0...HEAD

{core_framework-3.1.0 → core_framework-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 3.1.0
+Version: 3.2.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework
@@ -34,6 +34,7 @@ Requires-Dist: pillow-heif>=1.4.0
 Requires-Dist: pillow>=12.3.0
 Requires-Dist: pyinstrument>=5.1.2
 Requires-Dist: python-ulid>=3.1.0
+Requires-Dist: resend[async]>=2.34.0
 Requires-Dist: structlog>=26.1.0
 Requires-Dist: tenacity>=9.1.4
 Provides-Extra: testing

{core_framework-3.1.0 → core_framework-3.2.0}/config.toml

@@ -114,6 +114,7 @@ max_connections = 4
 [worker]
 max_jobs = 10
 max_tries = 2
+job_timeout = 300
 
 [retention]
 post_views_retention_days = 90
@@ -137,3 +138,10 @@ host = "127.0.0.1"
 port = 6379
 cache_db = 0
 queue_db = 1
+
+[email]
+enabled = false
+provider = "resend"
+api_key = ""
+from_address = ""
+from_name = ""

{core_framework-3.1.0 → core_framework-3.2.0}/config.toml.template

@@ -98,6 +98,7 @@ max_connections = 4
 [worker]
 max_jobs = 10
 max_tries = 2
+job_timeout = 300
 
 [retention]
 post_views_retention_days = $RETENTION_POST_VIEWS_DAYS
@@ -121,3 +122,10 @@ host = "$REDIS_HOST"
 port = $REDIS_PORT
 cache_db = 0
 queue_db = 1
+
+[email]
+enabled = $EMAIL_ENABLED
+provider = "$EMAIL_PROVIDER"
+api_key = "$EMAIL_API_KEY"
+from_address = "$EMAIL_FROM_ADDRESS"
+from_name = "$EMAIL_FROM_NAME"

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/bootstrap.py

@@ -1,6 +1,7 @@
 import core_framework.domains.moderation.dependencies as moderation_deps
 import core_framework.domains.user.dependencies as user_deps
 from core_framework.application.analytics.registry import configure_activity_sources
+from core_framework.application.email.registry import configure_email_content_registry
 from core_framework.application.events.event_service import configure_event_handlers
 from core_framework.application.events.event_token import configure_event_token
 from core_framework.application.events.utm_capture_kinds import configure_utm_capture_kinds
@@ -13,6 +14,7 @@ from core_framework.core.runtime import CoreRuntime
 from core_framework.domains.analytics.dependencies import configure_analytics_dependencies
 from core_framework.domains.auth.dependencies import configure_auth_dependencies
 from core_framework.domains.comment.dependencies import configure_comment_dependencies
+from core_framework.domains.email.dependencies import configure_email_dependencies
 from core_framework.domains.media.dependencies import configure_media_dependencies
 from core_framework.domains.moderation.dependencies import configure_moderation_dependencies
 from core_framework.domains.notification.dependencies import configure_notification_dependencies
@@ -35,11 +37,13 @@ def configure_application_dependencies(*, runtime: CoreRuntime) -> None:
     """Wire application-level dependencies from the shared runtime."""
     configure_event_handlers()
     configure_utm_capture_kinds()
+    configure_email_content_registry()
     configure_activity_sources()
     configure_worker_jobs(runtime=runtime)
     configure_cashews_backend(redis_cache_url=runtime.settings.redis.redis_cache_url)
     configure_auth_dependencies()
     configure_comment_dependencies(runtime)
+    configure_email_dependencies(runtime)
     configure_media_dependencies(runtime)
     configure_moderation_dependencies(runtime)
     configure_notification_dependencies(runtime)

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/comments/aggregation_service.py

@@ -9,10 +9,14 @@ from core_framework.domains.comment import CommentStatsImpact, CommentSubjectTyp
 async def aggregate_comment_stats(*, comment_id: str) -> None:
     """Recompute and persist aggregate stats for a comment."""
     async with TaskGroup() as tg:
-        like_task = tg.create_task(comment_deps.comment_service.retrieve_comment_like_count(comment_id=comment_id))
-        reply_task = tg.create_task(comment_deps.comment_service.retrieve_comment_reply_count(comment_id=comment_id))
+        like_task = tg.create_task(
+            comment_deps.comment_service.retrieve_comment_like_count_strong(comment_id=comment_id)
+        )
+        reply_task = tg.create_task(
+            comment_deps.comment_service.retrieve_comment_reply_count_strong(comment_id=comment_id)
+        )
         report_task = tg.create_task(
-            moderation_deps.moderation_service.retrieve_comment_report_count(comment_id=comment_id)
+            moderation_deps.moderation_service.retrieve_comment_report_count_strong(comment_id=comment_id)
         )
 
     await comment_deps.comment_service.update_comment_stats(

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/comments/public_service.py

@@ -1,7 +1,7 @@
 from asyncio import TaskGroup
 from collections import defaultdict
 from datetime import datetime
-from typing import Any, Final
+from typing import Any
 
 import core_framework.domains.comment.dependencies as comment_deps
 import core_framework.domains.moderation.dependencies as moderation_deps
@@ -20,7 +20,6 @@ from core_framework.domains.notification import NotificationMuteSubjectType
 from core_framework.domains.user import UserIdentity
 
 _MAX_AUTHOR_COMMENT_VISIBILITY_FETCH_ROUNDS = 10
-_UNKNOWN_MENTION_DISPLAY_NAME: Final[str] = "unknown"
 
 
 def _mention_references(
@@ -28,26 +27,15 @@ def _mention_references(
     mentioned_user_ids: list[str],
     user_identity_mapping: defaultdict[str, UserIdentity],
 ) -> list[dict[str, Any]]:
-    mentions: list[dict[str, Any]] = []
-    for user_id in mentioned_user_ids:
-        identity = user_identity_mapping[user_id]
-        if identity.user_id == user_id:
-            mentions.append(
-                {
-                    "user_id": user_id,
-                    "username": identity.username,
-                    "display_name": identity.display_name,
-                }
-            )
-        else:
-            mentions.append(
-                {
-                    "user_id": user_id,
-                    "username": user_id,
-                    "display_name": _UNKNOWN_MENTION_DISPLAY_NAME,
-                }
-            )
-    return mentions
+    """Build mention ``UserReference`` dicts; unknown ids use ``UserIdentity.DEFAULT``."""
+    return [
+        {
+            "user_id": user_id,
+            "username": user_identity_mapping[user_id].username,
+            "display_name": user_identity_mapping[user_id].display_name,
+        }
+        for user_id in mentioned_user_ids
+    ]
 
 
 def _mentioned_user_ids_for_comments(

core_framework-3.2.0/core_framework/application/email/__init__.py

@@ -0,0 +1,29 @@
+"""Transactional email content registry and generic enqueue (host surface).
+
+Hosts put every ``register_email_content`` call in one shared bootstrap helper
+(alongside UTM / activity sources) and invoke that helper from both API and
+worker after ``configure_application_dependencies``. Worker registration is
+load-bearing; API-only register still enqueues but the worker keeps core
+defaults or hits ``missing_renderer``. Register branded renderers before enabling
+email in production (core default deletion copy is generic English).
+
+Enqueue host-owned kinds with ``enqueue_transactional_email``. Do not use it for
+core gated kinds such as ``account_deletion_scheduled`` unless the host
+re-implements those gates (prefer the gated core task).
+
+Render+send runs only on the worker (via core tasks); it is not part of this
+public export — do not call it from the API process. Registry reset
+(``configure_email_content_registry``) is bootstrap-internal only.
+"""
+
+from core_framework.application.email.enqueue import enqueue_transactional_email
+from core_framework.application.email.registry import (
+    ACCOUNT_DELETION_SCHEDULED_KIND,
+    register_email_content,
+)
+
+__all__ = [
+    "ACCOUNT_DELETION_SCHEDULED_KIND",
+    "enqueue_transactional_email",
+    "register_email_content",
+]

core_framework-3.2.0/core_framework/application/email/account_deletion_scheduled.py

@@ -0,0 +1,77 @@
+from datetime import UTC
+
+from structlog import get_logger
+
+import core_framework.domains.auth.dependencies as auth_deps
+import core_framework.domains.user.dependencies as user_deps
+from core_framework.application.email.registry import ACCOUNT_DELETION_SCHEDULED_KIND
+from core_framework.application.email.send import render_and_send_transactional_email
+
+logger = get_logger(__name__)
+
+
+async def process_account_deletion_scheduled_email(*, user_id: str) -> None:
+    """Send ``account_deletion_scheduled`` mail when the schedule and verified email allow."""
+    scheduled_for = await user_deps.user_service.retrieve_user_deletion_scheduled_for_strong(user_id=user_id)
+    if scheduled_for is None:
+        logger.info(
+            "Skipped account deletion scheduled email",
+            reason="canceled",
+            user_id=user_id,
+            kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        )
+        return
+
+    try:
+        firebase_user = await auth_deps.auth_service.get_user(user_id=user_id)
+    except Exception:
+        logger.exception(
+            "Account deletion scheduled email auth lookup failed",
+            reason="auth_lookup_failure",
+            user_id=user_id,
+            kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        )
+        return
+
+    if firebase_user is None:
+        logger.info(
+            "Skipped account deletion scheduled email",
+            reason="auth_user_missing",
+            user_id=user_id,
+            kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        )
+        return
+
+    email = (firebase_user.email or "").strip()
+    if not email:
+        logger.info(
+            "Skipped account deletion scheduled email",
+            reason="missing_email",
+            user_id=user_id,
+            kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        )
+        return
+
+    if not firebase_user.email_verified:
+        logger.info(
+            "Skipped account deletion scheduled email",
+            reason="unverified_email",
+            user_id=user_id,
+            kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        )
+        return
+
+    context: dict[str, object] = {
+        "user_id": user_id,
+        "deletion_date": scheduled_for.astimezone(UTC).date().isoformat(),
+        "grace_period_days": user_deps.user_service.ACCOUNT_DELETION_GRACE_DAYS,
+    }
+    identity = await user_deps.user_service.retrieve_user_identity(user_id=user_id)
+    if identity.user_id == user_id:
+        context["username"] = identity.username
+
+    await render_and_send_transactional_email(
+        to=email,
+        kind=ACCOUNT_DELETION_SCHEDULED_KIND,
+        context=context,
+    )

core_framework-3.2.0/core_framework/application/email/enqueue.py

@@ -0,0 +1,36 @@
+from collections.abc import Mapping
+from typing import Any
+
+from structlog import get_logger
+
+import core_framework.application.shared.worker_jobs as worker_jobs
+from core_framework.application.shared.enums import WorkerJobName
+
+logger = get_logger(__name__)
+
+
+async def enqueue_transactional_email(
+    *,
+    to: str,
+    kind: str,
+    context: Mapping[str, Any],
+    _job_id: str | None = None,
+) -> None:
+    """Best-effort enqueue of ``process_transactional_email``."""
+    trimmed_kind = kind.strip()
+    if not trimmed_kind:
+        raise ValueError("email content kind must not be empty or whitespace-only")
+    job_kwargs: dict[str, Any] = {
+        "to": to,
+        "kind": trimmed_kind,
+        "context": dict(context),
+    }
+    if _job_id is not None:
+        job_kwargs["_job_id"] = _job_id
+    try:
+        await worker_jobs.enqueue_job(
+            job_name=WorkerJobName.PROCESS_TRANSACTIONAL_EMAIL,
+            **job_kwargs,
+        )
+    except Exception:
+        logger.exception("Failed to enqueue transactional email", kind=trimmed_kind)

core_framework-3.2.0/core_framework/application/email/registry.py

@@ -0,0 +1,64 @@
+from collections.abc import Callable, Mapping
+from html import escape
+from typing import Any, Final
+
+ACCOUNT_DELETION_SCHEDULED_KIND: Final[str] = "account_deletion_scheduled"
+
+# Sync pure function: context → (subject, html_body, plain_text_body). No I/O.
+type EmailRenderer = Callable[[Mapping[str, Any]], tuple[str, str, str]]
+
+_renderers: dict[str, EmailRenderer] = {}
+
+
+def configure_email_content_registry() -> None:
+    """Reset the email content registry and register core default renderers."""
+    global _renderers
+    _renderers = {}
+    register_email_content(
+        ACCOUNT_DELETION_SCHEDULED_KIND,
+        render_account_deletion_scheduled,
+    )
+
+
+def register_email_content(kind: str, renderer: EmailRenderer) -> None:
+    """Register or replace a transactional email renderer for ``kind``."""
+    trimmed = kind.strip()
+    if not trimmed:
+        raise ValueError("email content kind must not be empty or whitespace-only")
+    _renderers[trimmed] = renderer
+
+
+def get_email_renderer(kind: str) -> EmailRenderer | None:
+    """Return the registered renderer for ``kind``, or ``None`` if missing."""
+    return _renderers.get(kind.strip())
+
+
+def render_account_deletion_scheduled(context: Mapping[str, Any]) -> tuple[str, str, str]:
+    """Default English copy for ``account_deletion_scheduled`` (HTML-escapes interpolations)."""
+    _ = context["user_id"]  # required context key; not shown in copy
+    deletion_date = context["deletion_date"]
+    grace_period_days = context["grace_period_days"]
+    username = context.get("username")
+
+    deletion_date_str = str(deletion_date)
+    grace_str = str(grace_period_days)
+    greeting_plain = f"Hi {username}," if username is not None else "Hi,"
+    greeting_html = f"Hi {escape(str(username))}," if username is not None else "Hi,"
+
+    subject = "Your account is scheduled for deletion"
+    plain_text_body = (
+        f"{greeting_plain}\n\n"
+        f"Your account is scheduled for deletion on {deletion_date_str}. "
+        f"You have a {grace_str}-day grace period.\n\n"
+        "If you did not request this, cancel the deletion from your account settings "
+        "before that date.\n"
+    )
+    html_body = (
+        f"<p>{greeting_html}</p>"
+        f"<p>Your account is scheduled for deletion on "
+        f"<strong>{escape(deletion_date_str)}</strong>. "
+        f"You have a {escape(grace_str)}-day grace period.</p>"
+        "<p>If you did not request this, cancel the deletion from your account settings "
+        "before that date.</p>"
+    )
+    return subject, html_body, plain_text_body

core_framework-3.2.0/core_framework/application/email/send.py

@@ -0,0 +1,52 @@
+from collections.abc import Mapping
+from typing import Any
+
+from structlog import get_logger
+
+import core_framework.domains.email.dependencies as email_deps
+from core_framework.application.email.registry import get_email_renderer
+
+logger = get_logger(__name__)
+
+
+async def render_and_send_transactional_email(
+    *,
+    to: str,
+    kind: str,
+    context: Mapping[str, Any],
+) -> None:
+    """Render a registered kind and send via the email facade (worker-facing)."""
+    kind = kind.strip()
+    email_service = email_deps.email_service
+    if not email_service.enabled:
+        await email_service.send(
+            to="",
+            subject="",
+            html_body="",
+            plain_text_body="",
+            kind=kind,
+        )
+        return
+
+    renderer = get_email_renderer(kind)
+    if renderer is None:
+        logger.error(
+            "Transactional email renderer missing",
+            reason="missing_renderer",
+            kind=kind,
+        )
+        raise RuntimeError(f"missing email renderer for kind {kind!r}")
+
+    try:
+        subject, html_body, plain_text_body = renderer(context)
+    except Exception:
+        logger.exception("Transactional email render failed", kind=kind)
+        raise
+
+    await email_service.send(
+        to=to,
+        subject=subject,
+        html_body=html_body,
+        plain_text_body=plain_text_body,
+        kind=kind,
+    )

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/events/event_token.py

@@ -1,5 +1,6 @@
 from itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer
 from structlog import get_logger
+from ulid import ULID
 
 logger = get_logger(__name__)
 
@@ -24,16 +25,12 @@ def _get_serializer() -> URLSafeTimedSerializer:
 
 
 def generate_token() -> str:
-    """Return a signed token clients include when posting analytics events."""
-    return _get_serializer().dumps("")
+    """Return a signed token with a unique ULID payload for analytics event posts."""
+    return _get_serializer().dumps(str(ULID()))
 
 
 def verify_token(*, token: str) -> bool:
-    """Return whether the event token is valid (signed and not expired).
-
-    The token is type-agnostic: one global max-age applies to every event type,
-    so hosts can introduce event types without a core token-policy change.
-    """
+    """Return whether the event token is valid (signed and not expired)."""
     try:
         _get_serializer().loads(token, max_age=EVENT_TOKEN_MAX_AGE_SECONDS)
         return True

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/media/attachment_service.py

@@ -1,5 +1,6 @@
 from collections.abc import AsyncIterator, Awaitable
 from dataclasses import dataclass
+from math import ceil
 from typing import Final, Protocol
 
 from structlog import get_logger
@@ -14,7 +15,9 @@ from core_framework.application.shared.exceptions import (
     BadRequestException,
     IngestBodyTooLargeException,
     IngestUnsupportedMediaTypeException,
+    ServiceUnavailableException,
 )
+from core_framework.core.process import ProcessAdmissionTimeoutError
 from core_framework.domains.media import (
     ATTACHMENT_STAGING_TTL_DAYS,
     AttachmentIngestRegistration,
@@ -61,12 +64,17 @@ async def accept_attachment_ingest_upload(
         raise IngestBodyTooLargeException()
     if staging_bytes is None:
         raise BadRequestException()
-    (
-        probe_outcome,
-        display_dimensions,
-    ) = await media_deps.attachment_service.try_probe_attachment_display_dimensions_from_staging(
-        staging_bytes=staging_bytes,
-    )
+    try:
+        (
+            probe_outcome,
+            display_dimensions,
+        ) = await media_deps.attachment_service.try_probe_attachment_display_dimensions_from_staging(
+            staging_bytes=staging_bytes,
+        )
+    except ProcessAdmissionTimeoutError as exc:
+        raise ServiceUnavailableException(
+            retry_after_seconds=max(1, ceil(exc.timeout_seconds)),
+        ) from exc
     if probe_outcome == AttachmentStagingImageProbeOutcome.PROCESSING_FAILED or display_dimensions is None:
         raise BadRequestException()
     display_width, display_height = display_dimensions

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/media/avatar_service.py

@@ -13,7 +13,7 @@ from core_framework.application.shared.exceptions import (
     IngestUnsupportedMediaTypeException,
 )
 from core_framework.core import CacheKey
-from core_framework.core.cache import invalidate_cache
+from core_framework.core.cache import invalidate_cache_best_effort
 from core_framework.domains.media import (
     AvatarIngestRegistration,
     IngestBodyOutcome,
@@ -142,8 +142,8 @@ async def process_media_asset_variants(*, owner_user_id: str, asset_id: str, ing
         actor_id=owner_user_id,
     )
     if apply_result.applied:
-        await invalidate_cache(CacheKey.USER_PUBLIC_PROFILE, user_id=owner_user_id)
-        await invalidate_cache(CacheKey.USER_DETAIL, user_id=owner_user_id)
+        await invalidate_cache_best_effort(CacheKey.USER_PUBLIC_PROFILE, user_id=owner_user_id)
+        await invalidate_cache_best_effort(CacheKey.USER_DETAIL, user_id=owner_user_id)
         if apply_result.old_avatar_id is not None:
             await enqueue_delete_superseded_avatar_finals(asset_id=apply_result.old_avatar_id)
     await media_deps.avatar_service.delete_avatar_staging_blob(staging_filename=registry_entry.staging_filename)

{core_framework-3.1.0 → core_framework-3.2.0}/core_framework/application/media/banner_service.py

@@ -13,7 +13,7 @@ from core_framework.application.shared.exceptions import (
     IngestUnsupportedMediaTypeException,
 )
 from core_framework.core import CacheKey
-from core_framework.core.cache import invalidate_cache
+from core_framework.core.cache import invalidate_cache_best_effort
 from core_framework.domains.media import (
     BannerIngestRegistration,
     IngestBodyOutcome,
@@ -138,8 +138,8 @@ async def process_banner_asset_variants(*, owner_user_id: str, asset_id: str, in
         actor_id=owner_user_id,
     )
     if apply_result.applied:
-        await invalidate_cache(CacheKey.USER_PUBLIC_PROFILE, user_id=owner_user_id)
-        await invalidate_cache(CacheKey.USER_DETAIL, user_id=owner_user_id)
+        await invalidate_cache_best_effort(CacheKey.USER_PUBLIC_PROFILE, user_id=owner_user_id)
+        await invalidate_cache_best_effort(CacheKey.USER_DETAIL, user_id=owner_user_id)
         if apply_result.old_banner_id is not None:
             await enqueue_delete_superseded_banner_finals(asset_id=apply_result.old_banner_id)
     await media_deps.banner_service.delete_banner_staging_blob(staging_filename=registry_entry.staging_filename)