beadhub 0.1.0__py3-none-any.whl

beadhub/notifications.py

@@ -0,0 +1,275 @@
+"""Notification outbox pattern for reliable delivery.
+
+This module implements the outbox pattern to ensure notifications are:
+1. Recorded atomically (as close as possible to the triggering event)
+2. Delivered reliably with retry capability
+3. Tracked for observability
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from typing import TYPE_CHECKING, List
+from uuid import UUID
+
+from aweb.messages_service import deliver_message
+
+if TYPE_CHECKING:
+    from .beads_sync import BeadStatusChange
+    from .db import DatabaseInfra
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRY_ATTEMPTS = 3
+
+
+async def record_notification_intents(
+    status_changes: List["BeadStatusChange"],
+    project_id: str,
+    db_infra: "DatabaseInfra",
+) -> int:
+    """Record notification intents in the outbox for later processing.
+
+    This should be called immediately after the triggering event commits.
+    Each status change that has subscribers will get an outbox entry.
+
+    Args:
+        status_changes: List of bead status changes to notify about
+        project_id: Project UUID for tenant isolation
+        db_infra: Database infrastructure
+
+    Returns:
+        Number of outbox entries created
+    """
+    from .routes.subscriptions import get_subscribers_for_bead
+
+    server_db = db_infra.get_manager("server")
+    entries_created = 0
+
+    for change in status_changes:
+        # Skip notifications for new issues (no old_status)
+        if change.old_status is None:
+            continue
+
+        # Get subscribers for this bead
+        subscribers = await get_subscribers_for_bead(
+            db_infra=db_infra,
+            project_id=project_id,
+            bead_id=change.bead_id,
+            event_type="status_change",
+            repo=change.repo,
+        )
+
+        if not subscribers:
+            continue
+
+        # Build notification payload
+        payload = {
+            "bead_id": change.bead_id,
+            "repo": change.repo,
+            "branch": change.branch,
+            "old_status": change.old_status,
+            "new_status": change.new_status,
+            "title": change.title,
+        }
+
+        # Create outbox entry for each subscriber
+        for sub in subscribers:
+            await server_db.execute(
+                """
+                INSERT INTO {{tables.notification_outbox}}
+                    (project_id, event_type, payload, recipient_workspace_id, recipient_alias)
+                VALUES ($1, $2, $3, $4, $5)
+                """,
+                project_id,
+                "bead_status_change",
+                json.dumps(payload),
+                sub["workspace_id"],
+                sub["alias"],
+            )
+            entries_created += 1
+
+    return entries_created
+
+
+async def process_notification_outbox(
+    project_id: str,
+    db_infra: "DatabaseInfra",
+    *,
+    sender_agent_id: str,
+    sender_alias: str,
+    limit: int = 100,
+) -> tuple[int, int]:
+    """Process pending notifications from the outbox.
+
+    Fetches pending/failed entries, attempts to send each notification,
+    and updates the outbox entry with the result.
+
+    Args:
+        project_id: Project UUID to process notifications for
+        db_infra: Database infrastructure
+        redis: Redis client for message events
+        limit: Maximum number of entries to process in one batch
+
+    Returns:
+        Tuple of (sent_count, failed_count)
+    """
+    server_db = db_infra.get_manager("server")
+    sent_count = 0
+    failed_count = 0
+
+    # Fetch pending entries (including failed entries under retry limit)
+    rows = await server_db.fetch_all(
+        """
+        SELECT id, payload, recipient_workspace_id, recipient_alias, attempts
+        FROM {{tables.notification_outbox}}
+        WHERE project_id = $1
+          AND status IN ('pending', 'failed')
+          AND attempts < $2
+        ORDER BY created_at ASC
+        LIMIT $3
+        FOR UPDATE SKIP LOCKED
+        """,
+        project_id,
+        MAX_RETRY_ATTEMPTS,
+        limit,
+    )
+
+    for row in rows:
+        outbox_id = row["id"]
+        payload = row["payload"]
+        recipient_workspace_id = str(row["recipient_workspace_id"])
+        attempts = row["attempts"] + 1
+
+        if isinstance(payload, str):
+            payload = json.loads(payload)
+
+        # Mark as processing
+        await server_db.execute(
+            """
+            UPDATE {{tables.notification_outbox}}
+            SET status = 'processing', attempts = $2
+            WHERE id = $1
+            """,
+            outbox_id,
+            attempts,
+        )
+
+        try:
+            # Skip sending to deleted/missing workspaces (subscriptions may outlive workspaces).
+            recipient_row = await server_db.fetch_one(
+                """
+                SELECT deleted_at
+                FROM {{tables.workspaces}}
+                WHERE workspace_id = $1 AND project_id = $2
+                """,
+                UUID(recipient_workspace_id),
+                UUID(project_id),
+            )
+            if not recipient_row or recipient_row.get("deleted_at") is not None:
+                raise RuntimeError("Recipient workspace not found or deleted")
+
+            # Build notification message
+            bead_id = payload.get("bead_id", "unknown")
+            old_status = payload.get("old_status", "unknown")
+            new_status = payload.get("new_status", "unknown")
+            title = payload.get("title", "")
+            repo = payload.get("repo", "")
+            branch = payload.get("branch", "")
+
+            subject = f"Bead status changed: {bead_id}"
+            body = f"**{bead_id}** status changed from `{old_status}` to `{new_status}`\n\n"
+            if title:
+                body += f"Title: {title}\n"
+            if repo:
+                body += f"Repo: {repo}\n"
+            if branch:
+                body += f"Branch: {branch}\n"
+
+            # Generate deterministic thread ID for this bead
+            thread_uuid = uuid.uuid5(uuid.NAMESPACE_URL, f"bead:{bead_id}")
+
+            message_id, _created_at = await deliver_message(
+                db_infra,
+                project_id=project_id,
+                from_agent_id=sender_agent_id,
+                from_alias=sender_alias,
+                to_agent_id=recipient_workspace_id,
+                subject=subject,
+                body=body,
+                priority="normal",
+                thread_id=str(thread_uuid),
+            )
+
+            # Mark as completed
+            await server_db.execute(
+                """
+                UPDATE {{tables.notification_outbox}}
+                SET status = 'completed',
+                    processed_at = NOW(),
+                    message_id = $2,
+                    last_error = NULL
+                WHERE id = $1
+                """,
+                outbox_id,
+                message_id,
+            )
+            sent_count += 1
+
+        except Exception as e:
+            logger.exception(
+                "Failed to send notification for outbox entry %s (attempt %d)",
+                outbox_id,
+                attempts,
+            )
+            # Mark as failed - stays retriable until MAX_RETRY_ATTEMPTS exhausted
+            error_msg = str(e)[:500]  # Truncate long errors
+            await server_db.execute(
+                """
+                UPDATE {{tables.notification_outbox}}
+                SET status = 'failed',
+                    last_error = $2
+                WHERE id = $1
+                """,
+                outbox_id,
+                error_msg,
+            )
+            failed_count += 1
+
+    return sent_count, failed_count
+
+
+async def cleanup_old_notifications(
+    db_infra: "DatabaseInfra",
+    project_id: str,
+    days_old: int = 7,
+) -> int:
+    """Delete old completed notifications from the outbox.
+
+    Args:
+        db_infra: Database infrastructure
+        project_id: Project UUID for tenant isolation
+        days_old: Delete completed entries older than this many days
+
+    Returns:
+        Number of entries deleted
+    """
+    server_db = db_infra.get_manager("server")
+
+    result = await server_db.fetch_value(
+        """
+        WITH deleted AS (
+            DELETE FROM {{tables.notification_outbox}}
+            WHERE project_id = $1
+              AND status = 'completed'
+              AND processed_at < NOW() - INTERVAL '1 day' * $2
+            RETURNING id
+        )
+        SELECT COUNT(*) FROM deleted
+        """,
+        project_id,
+        days_old,
+    )
+    return int(result or 0)

beadhub/pagination.py

@@ -0,0 +1,125 @@
+"""Cursor-based pagination helpers for BeadHub API endpoints.
+
+This module provides consistent pagination across all list endpoints:
+- Cursor encoding/decoding for stateless pagination
+- Standard response format with {items, has_more, next_cursor}
+- Parameter validation with sensible defaults and limits
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Generic, Optional, TypeVar
+
+from pydantic import BaseModel
+
+# Pagination constants per spec
+DEFAULT_LIMIT = 50
+MAX_LIMIT = 200
+MAX_CURSOR_SIZE_BYTES = 8192  # 8KB max cursor size to prevent DoS
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Standard paginated response format.
+
+    Attributes:
+        items: List of items for the current page
+        has_more: True if there are more items after this page
+        next_cursor: Opaque cursor string for fetching the next page, None if no more items
+    """
+
+    items: list[T]
+    has_more: bool
+    next_cursor: Optional[str] = None
+
+
+def encode_cursor(data: dict[str, Any]) -> str:
+    """Encode pagination state as a URL-safe cursor string.
+
+    Args:
+        data: Dictionary containing pagination state (e.g., last id, timestamp)
+
+    Returns:
+        URL-safe base64 encoded string representing the pagination state
+    """
+    json_bytes = json.dumps(data, separators=(",", ":")).encode("utf-8")
+    return base64.urlsafe_b64encode(json_bytes).decode("ascii").rstrip("=")
+
+
+def decode_cursor(cursor: Optional[str]) -> Optional[dict[str, Any]]:
+    """Decode a cursor string back to pagination state.
+
+    Args:
+        cursor: URL-safe base64 encoded cursor string, or None/empty
+
+    Returns:
+        Dictionary containing pagination state, or None if cursor was None/empty
+
+    Raises:
+        ValueError: If cursor is malformed (invalid base64 or JSON) or too large
+    """
+    if cursor is None or cursor == "":
+        return None
+
+    # Validate size before decoding
+    if len(cursor) > MAX_CURSOR_SIZE_BYTES:
+        raise ValueError(f"Invalid cursor: exceeds maximum size of {MAX_CURSOR_SIZE_BYTES} bytes")
+
+    try:
+        # Over-pad to let base64 library handle any valid padding
+        json_bytes = base64.urlsafe_b64decode(cursor + "===")
+    except ValueError as e:
+        raise ValueError(f"Invalid cursor: malformed encoding ({e})") from e
+
+    # Validate decoded size
+    if len(json_bytes) > MAX_CURSOR_SIZE_BYTES:
+        raise ValueError("Invalid cursor: decoded data exceeds maximum size")
+
+    try:
+        data = json.loads(json_bytes.decode("utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid cursor: malformed data at position {e.pos}") from e
+    except UnicodeDecodeError:
+        raise ValueError("Invalid cursor: contains invalid UTF-8 data")
+
+    if not isinstance(data, dict):
+        raise ValueError("Invalid cursor: must decode to a dictionary")
+
+    return data
+
+
+def validate_pagination_params(
+    limit: Optional[int],
+    cursor: Optional[str],
+) -> tuple[int, Optional[dict[str, Any]]]:
+    """Validate and normalize pagination parameters.
+
+    Args:
+        limit: Requested page size (will be clamped to valid range)
+        cursor: Opaque cursor string from previous response
+
+    Returns:
+        Tuple of (validated_limit, decoded_cursor_dict)
+        - limit is clamped to [1, MAX_LIMIT], defaults to DEFAULT_LIMIT
+        - cursor is decoded to dict, or None if not provided
+
+    Raises:
+        ValueError: If cursor is malformed
+    """
+    # Validate and clamp limit
+    if limit is None:
+        validated_limit = DEFAULT_LIMIT
+    elif limit < 1:
+        validated_limit = 1
+    elif limit > MAX_LIMIT:
+        validated_limit = MAX_LIMIT
+    else:
+        validated_limit = limit
+
+    # Decode cursor (will raise ValueError if malformed)
+    decoded_cursor = decode_cursor(cursor)
+
+    return validated_limit, decoded_cursor