Merge pull request #456 from anumukul/feat/issues-301-302-308-309

Add draft persistence, rate-limit headers, webhook dead letters, and …

Author: ChaoLing140

backend/alembic/versions/005_add_webhook_delivery_status.py

@@ -0,0 +1,26 @@
+"""add webhook delivery status tracking
+
+Revision ID: 005
+Revises: 004
+Create Date: 2026-05-30
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "005"
+down_revision: Union[str, None] = "004"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "webhook_deliveries",
+        sa.Column("delivery_status", sa.String(length=32), nullable=False, server_default="pending"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("webhook_deliveries", "delivery_status")

backend/src/models.py

@@ -184,6 +184,7 @@ class WebhookDelivery(Base):
     response_body = Column(Text, nullable=True)
     success = Column(Boolean, default=False, nullable=False)
     attempts = Column(Integer, default=0, nullable=False)
+    delivery_status = Column(String(32), default="pending", nullable=False)
     last_attempt_at = Column(DateTime, nullable=True)
     created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
 
@@ -192,6 +193,7 @@ class WebhookDelivery(Base):
     def __init__(self, **kwargs):
         kwargs.setdefault("success", False)
         kwargs.setdefault("attempts", 0)
+        kwargs.setdefault("delivery_status", "pending")
         super().__init__(**kwargs)
 
     def __repr__(self):

backend/src/rate_limiter.py

@@ -3,26 +3,33 @@
 Uses slowapi for IP-based rate limiting with authenticated user bypass support.
 """
 import logging
+import re
+import time
+from typing import Optional
+
 from slowapi import Limiter
 from slowapi.util import get_remote_address
 from slowapi.errors import RateLimitExceeded
 from slowapi.middleware import SlowAPIMiddleware
-from fastapi import Request, Response
+from fastapi import Request
 from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
 from .config import get_settings
 
 logger = logging.getLogger(__name__)
 
 settings = get_settings()
 
+RATE_LIMIT_HEADER_NAMES = (
+    "Retry-After",
+    "X-RateLimit-Limit",
+    "X-RateLimit-Remaining",
+    "X-RateLimit-Reset",
+)
+
 
 def _get_rate_limit_key(request: Request) -> str:
-    """
-    Determine rate limit key based on request.
-    If authenticated user bypass is enabled and a valid Bearer token is present,
-    return a user-specific key that receives higher limits.
-    Otherwise, fall back to IP-based limiting.
-    """
     if settings.rate_limit_auth_bypass:
         auth_header = request.headers.get("Authorization", "")
         if auth_header.startswith("Bearer ") and len(auth_header) > 7:
@@ -34,34 +41,99 @@ def _get_rate_limit_key(request: Request) -> str:
     return get_remote_address(request)
 
 
+def _parse_limit_value(limit_detail: str) -> int:
+    match = re.match(r"(\d+)", limit_detail or "")
+    return int(match.group(1)) if match else 60
+
+
+def _parse_retry_after_seconds(limit_detail: str) -> int:
+    detail = (limit_detail or "").lower()
+    count_match = re.search(r"(\d+)\s*per", detail)
+    window_match = re.search(r"per\s+(\d+)\s*(second|minute|hour|day)", detail)
+
+    count = int(count_match.group(1)) if count_match else 60
+    if not window_match:
+        return max(count, 1)
+
+    amount = int(window_match.group(1))
+    unit = window_match.group(2)
+    multipliers = {"second": 1, "minute": 60, "hour": 3600, "day": 86400}
+    window_seconds = amount * multipliers.get(unit, 60)
+    return max(window_seconds // max(count, 1), 1)
+
+
+def build_rate_limit_headers(limit_detail: str, remaining: Optional[int] = None) -> dict[str, str]:
+    limit_value = _parse_limit_value(limit_detail)
+    retry_after = _parse_retry_after_seconds(limit_detail)
+    reset_at = int(time.time()) + retry_after
+    resolved_remaining = str(max(remaining, 0)) if remaining is not None else str(max(limit_value - 1, 0))
+
+    return {
+        "Retry-After": str(retry_after),
+        "X-RateLimit-Limit": str(limit_value),
+        "X-RateLimit-Remaining": resolved_remaining,
+        "X-RateLimit-Reset": str(reset_at),
+    }
+
+
 limiter = Limiter(
     key_func=_get_rate_limit_key,
     default_limits=[settings.rate_limit_default],
     storage_uri=settings.redis_url if settings.redis_enabled else "memory://",
+    headers_enabled=True,
 )
 
 
 def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
-    """Handle rate limit exceeded errors with proper retry information."""
-    retry_after = exc.detail.split("per")[-1].strip() if "per" in exc.detail else "60"
-    logger.warning("Rate limit exceeded for %s on %s", _get_rate_limit_key(request), request.url.path)
+    limit_detail = str(exc.detail)
+    headers = build_rate_limit_headers(limit_detail, remaining=0)
+    retry_after = int(headers["Retry-After"])
+
+    logger.warning(
+        "Rate limit exceeded for %s on %s",
+        _get_rate_limit_key(request),
+        request.url.path,
+    )
+
     return JSONResponse(
         status_code=429,
         content={
             "error_code": "RATE_001",
-            "detail": f"Rate limit exceeded: {exc.detail}",
+            "detail": f"Rate limit exceeded: {limit_detail}",
             "retry_after": retry_after,
         },
-        headers={
-            "Retry-After": retry_after,
-            "X-RateLimit-Limit": str(exc.detail),
-        },
+        headers=headers,
     )
 
 
+class RateLimitHeaderMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+
+        if response.status_code == 429:
+            return response
+
+        limit_header = response.headers.get("X-RateLimit-Limit")
+        if limit_header:
+            for header_name in RATE_LIMIT_HEADER_NAMES:
+                if header_name in response.headers:
+                    continue
+            if "X-RateLimit-Remaining" not in response.headers:
+                response.headers["X-RateLimit-Remaining"] = str(max(_parse_limit_value(limit_header) - 1, 0))
+            if "X-RateLimit-Reset" not in response.headers:
+                retry_after = _parse_retry_after_seconds(settings.rate_limit_default)
+                response.headers["X-RateLimit-Reset"] = str(int(time.time()) + retry_after)
+
+        return response
+
+
 def setup_rate_limiting(app):
-    """Attach rate limiter and exception handler to the FastAPI app."""
     app.state.limiter = limiter
+    app.add_middleware(RateLimitHeaderMiddleware)
     app.add_middleware(SlowAPIMiddleware)
     app.add_exception_handler(RateLimitExceeded, rate_limit_exceeded_handler)
-    logger.info("Rate limiting enabled: default=%s, auth=%s", settings.rate_limit_default, settings.rate_limit_auth)
+    logger.info(
+        "Rate limiting enabled: default=%s, auth=%s",
+        settings.rate_limit_default,
+        settings.rate_limit_auth,
+    )

backend/src/routes/webhooks.py

@@ -16,6 +16,7 @@
     WebhookUpdateRequest,
     WebhookResponse,
     WebhookDeliveryResponse,
+    WebhookDeliveryDetailResponse,
     WebhookDeliveryListResponse,
     MessageResponse,
 )
@@ -38,6 +39,39 @@ def __init__(self, detail: str = "Webhook limit reached for this user"):
         super().__init__(status.HTTP_429_TOO_MANY_REQUESTS, detail, "WEBHOOK_003")
 
 
+class WebhookDeliveryNotFoundError(StellarInsureError):
+    def __init__(self, detail: str = "Webhook delivery not found"):
+        super().__init__(status.HTTP_404_NOT_FOUND, detail, "WEBHOOK_004")
+
+
+def _format_delivery(delivery: WebhookDelivery) -> WebhookDeliveryResponse:
+    return WebhookDeliveryResponse(
+        id=delivery.id,
+        webhook_id=delivery.webhook_id,
+        event_type=delivery.event_type,
+        response_status=delivery.response_status,
+        success=delivery.success,
+        attempts=delivery.attempts,
+        delivery_status=delivery.delivery_status,
+        created_at=delivery.created_at,
+    )
+
+
+def _format_delivery_detail(delivery: WebhookDelivery) -> WebhookDeliveryDetailResponse:
+    return WebhookDeliveryDetailResponse(
+        id=delivery.id,
+        webhook_id=delivery.webhook_id,
+        event_type=delivery.event_type,
+        response_status=delivery.response_status,
+        success=delivery.success,
+        attempts=delivery.attempts,
+        delivery_status=delivery.delivery_status,
+        created_at=delivery.created_at,
+        response_body=delivery.response_body,
+        last_attempt_at=delivery.last_attempt_at,
+    )
+
+
 def _format_webhook(webhook: Webhook) -> WebhookResponse:
     return WebhookResponse(
         id=webhook.id,
@@ -119,6 +153,37 @@ async def list_webhooks(
     return [_format_webhook(w) for w in webhooks]
 
 
+@router.get(
+    "/deliveries/{delivery_id}",
+    response_model=WebhookDeliveryDetailResponse,
+    summary="Get webhook delivery status",
+    description="Returns the current delivery state for operator review, including retry and dead-letter status.",
+    responses={
+        200: {"description": "Delivery status"},
+        404: {"description": "Delivery not found"},
+        401: {"description": "Not authenticated"},
+    },
+)
+async def get_webhook_delivery_status(
+    delivery_id: int,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db),
+):
+    delivery = (
+        db.query(WebhookDelivery)
+        .join(Webhook, Webhook.id == WebhookDelivery.webhook_id)
+        .filter(
+            WebhookDelivery.id == delivery_id,
+            Webhook.user_id == current_user.id,
+        )
+        .first()
+    )
+    if delivery is None:
+        raise WebhookDeliveryNotFoundError()
+
+    return _format_delivery_detail(delivery)
+
+
 @router.get(
     "/{webhook_id}",
     response_model=WebhookResponse,
@@ -267,18 +332,7 @@ async def list_webhook_deliveries(
     )
 
     return WebhookDeliveryListResponse(
-        deliveries=[
-            WebhookDeliveryResponse(
-                id=d.id,
-                webhook_id=d.webhook_id,
-                event_type=d.event_type,
-                response_status=d.response_status,
-                success=d.success,
-                attempts=d.attempts,
-                created_at=d.created_at,
-            )
-            for d in deliveries
-        ],
+        deliveries=[_format_delivery(d) for d in deliveries],
         total=total,
         page=page,
         per_page=per_page,

backend/src/schemas.py

@@ -366,12 +366,18 @@ class WebhookDeliveryResponse(BaseModel):
     response_status: Optional[int] = Field(None, description="HTTP response status code")
     success: bool = Field(..., description="Whether delivery was successful")
     attempts: int = Field(..., description="Number of delivery attempts")
+    delivery_status: str = Field(..., description="Delivery lifecycle status")
     created_at: datetime = Field(..., description="Delivery creation timestamp")
 
     class Config:
         from_attributes = True
 
 
+class WebhookDeliveryDetailResponse(WebhookDeliveryResponse):
+    response_body: Optional[str] = Field(None, description="Last response body or error message")
+    last_attempt_at: Optional[datetime] = Field(None, description="Timestamp of the last delivery attempt")
+
+
 class WebhookDeliveryListResponse(BaseModel):
     deliveries: List[WebhookDeliveryResponse] = Field(..., description="List of webhook deliveries")
     total: int = Field(..., description="Total number of deliveries", example=100)