vintasend-api 3.5.0__py3-none-any.whl

vintasend_api/asgi.py

@@ -0,0 +1,15 @@
+"""ASGI entrypoint. Point uvicorn/daphne at ``vintasend_api.asgi:application``.
+
+The API's own view layer is synchronous (see ``dashboard/service.py`` for why), so
+running under ASGI buys nothing on its own. It is here for deployments that already
+standardise on an ASGI server.
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "vintasend_api.settings")
+
+application = get_asgi_application()

vintasend_api/dashboard/api.py

@@ -0,0 +1,390 @@
+"""Assembles the HTTP application: error envelope, auth, and the notification routes.
+
+Each handler maps HTTP input to a VintaSend service call and the result back to the wire
+contract -- no business logic beyond the translation itself.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from django.http import Http404, HttpRequest, HttpResponse, JsonResponse
+from ninja import NinjaAPI, Query, Status
+from ninja.errors import AuthenticationError, HttpError, ValidationError
+
+from .auth import ApiKeyAuth
+from .bodies import JsonBodyParser, refuse_an_empty_json_body
+from .contract import (
+    API_VERSION,
+    URLS_NAMESPACE,
+    ApiErrorResponse,
+    CancelledNotificationOut,
+    DataResponse,
+    HealthOut,
+    NotificationDetailOut,
+    NotificationOut,
+    NotificationPreviewOut,
+    PaginatedResponse,
+    UserNotificationOut,
+)
+from .errors import STATUS_BY_CODE, ApiError, invalid_request, issue
+from .filters import build_backend_filter, build_order_by
+from .hooks import REQUEST_ID_HEADER, report_unhandled_error, request_id_for
+from .preview import build_notification_preview
+from .query import NotificationListQuery, PaginationQuery, ResendBody
+from .serialize import (
+    AnyNotification,
+    ListNotificationOut,
+    serialize_notification,
+    serialize_notification_detail,
+    serialize_user_notification,
+)
+from .service import ServiceCaller, get_service_caller
+from .template_source import get_template_client
+
+
+NotificationPage = PaginatedResponse[NotificationOut]
+
+# Error responses are produced by the exception handlers below rather than returned from
+# a view, so they are declared purely so the generated schema documents them the way
+# `openapi.yaml` does. Each route declares the subset the contract lists for it, and a test
+# pins the two together.
+#
+# Every authenticated route can refuse the caller twice over: 401 when no valid credential
+# was presented, 403 (FORBIDDEN) when a host authenticated the caller and then refused it.
+AUTH_ERRORS: dict[int, Any] = {401: ApiErrorResponse, 403: ApiErrorResponse}
+LIST_ERRORS: dict[int, Any] = {400: ApiErrorResponse, **AUTH_ERRORS}
+LOOKUP_ERRORS: dict[int, Any] = {**AUTH_ERRORS, 404: ApiErrorResponse}
+PREVIEW_ERRORS: dict[int, Any] = {
+    **LOOKUP_ERRORS,
+    409: ApiErrorResponse,
+    502: ApiErrorResponse,
+}
+RESEND_ERRORS: dict[int, Any] = {
+    400: ApiErrorResponse,
+    **AUTH_ERRORS,
+    409: ApiErrorResponse,
+}
+# The request body is optional, so an omitted one falls back to this. Shared rather
+# than constructed per call because it is only ever read.
+DEFAULT_RESEND_BODY = ResendBody(useStoredContext=False)
+
+CANCEL_ERRORS: dict[int, Any] = {
+    **LOOKUP_ERRORS,
+    409: ApiErrorResponse,
+}
+
+api = NinjaAPI(
+    title="VintaSend Dashboard API",
+    version="1.0.0",
+    description=(
+        "HTTP contract between a VintaSend notification service and the VintaSend "
+        "dashboard UI. openapi.yaml in the repository root is the source of truth."
+    ),
+    # Unique, so the templates management API can be mounted beside it. See contract.py.
+    urls_namespace=URLS_NAMESPACE,
+    auth=ApiKeyAuth(),
+    # Reads a body under the contract's media-type rule; see `bodies.py`.
+    parser=JsonBodyParser(),
+    # The contract's own envelope is emitted by the handlers below, so Ninja's default
+    # 404/validation bodies are never used.
+    docs_url="/docs",
+)
+
+
+# --- error envelope ------------------------------------------------------------------
+
+
+def _envelope(
+    request: HttpRequest, code: str, message: str, details: Any | None = None
+) -> HttpResponse:
+    error: dict[str, Any] = {"code": code, "message": message}
+    if details is not None:
+        error["details"] = details
+    return JsonResponse({"error": error}, status=STATUS_BY_CODE[code])
+
+
+@api.exception_handler(ApiError)
+def handle_api_error(request: HttpRequest, exc: ApiError) -> HttpResponse:
+    return _envelope(request, exc.code, exc.message, exc.details)
+
+
+@api.exception_handler(AuthenticationError)
+def handle_authentication_error(request: HttpRequest, exc: AuthenticationError) -> HttpResponse:
+    """A safety net for Ninja's own authentication failure.
+
+    ``ApiKeyAuth`` refuses every caller by raising ``ApiError`` itself -- a missing or
+    non-bearer header as much as a wrong key -- and a host's authenticator does the same, so
+    Ninja only raises this if an auth callable returns nothing. It still gets the envelope.
+    """
+    return _envelope(request, "UNAUTHORIZED", "A valid API key is required.")
+
+
+@api.exception_handler(ValidationError)
+def handle_validation_error(request: HttpRequest, exc: ValidationError) -> HttpResponse:
+    """Report invalid input as a 400 listing the offending fields.
+
+    ``loc`` arrives as ``("query", "status")`` / ``("body", "payload", "useStoredContext")``.
+    The leading source segment and Ninja's synthetic body-argument name are dropped so
+    the reported path is the field name the client actually sent.
+    """
+    issues = [
+        issue(
+            ".".join(str(part) for part in _issue_path(failure.get("loc", ()))),
+            str(failure.get("msg", "")),
+        )
+        for failure in exc.errors
+    ]
+    return handle_api_error(request, invalid_request(issues))
+
+
+def _issue_path(loc: Any) -> list[Any]:
+    parts = list(loc)
+    if parts and parts[0] in {"query", "body", "path", "form", "header", "cookie"}:
+        parts = parts[1:]
+    # Ninja names the request-body argument after the view parameter ("payload"), which
+    # is an implementation detail the client never sent and should not be told about.
+    if parts and parts[0] == "payload":
+        parts = parts[1:]
+    return parts
+
+
+@api.exception_handler(HttpError)
+def handle_http_error(request: HttpRequest, exc: HttpError) -> HttpResponse:
+    """Put Ninja's own refusals in the error envelope.
+
+    Ninja raises ``HttpError`` when it cannot read a request body, wrapping whatever the
+    parser raised. ``JsonBodyParser`` raises the contract's 400, so that is unwrapped and
+    answered as it stands. Any other 400 gets the same shape. Anything else is unexpected.
+    """
+    if isinstance(exc.__cause__, ApiError):
+        return handle_api_error(request, exc.__cause__)
+    if exc.status_code == 400:
+        return handle_api_error(request, invalid_request([issue("", str(exc))]))
+    return handle_unexpected_error(request, exc)
+
+
+@api.exception_handler(Http404)
+def handle_not_found(request: HttpRequest, exc: Http404) -> HttpResponse:
+    return _envelope(
+        request,
+        "NOT_FOUND",
+        f"No route matches {request.method} {request.path}.",
+    )
+
+
+@api.exception_handler(Exception)
+def handle_unexpected_error(request: HttpRequest, exc: Exception) -> HttpResponse:
+    """Report unexpected errors generically, and never log them whole.
+
+    The client gets a fixed message, so backend internals -- connection strings, credentials
+    in driver messages -- never leak to it. The log gets one line by default: the error's
+    class, a request id, the method and the route pattern. An error from the notification
+    store, a provider or a context generator can carry notification content, recipients or
+    context values, which can be health data, so its message, its traceback and the concrete
+    path are not logged. A host that wants more sets ``VINTASEND_UNHANDLED_ERROR_HANDLER`` --
+    see ``hooks``. The response carries the request id in ``X-Request-Id``, to match a
+    client's report to the log line.
+    """
+    request_id = request_id_for(request)
+    report_unhandled_error(exc, request, request_id)
+    response = _envelope(
+        request,
+        "INTERNAL_ERROR",
+        "An unexpected error occurred while handling the request.",
+    )
+    response[REQUEST_ID_HEADER] = request_id
+    # Django logs every 5xx response again on ``django.request``, with the concrete path and
+    # the request object attached -- which mail_admins or an error tracker on the root logger
+    # turns into a report with request data. This error has been reported above, so that
+    # second record is suppressed.
+    response._has_been_logged = True  # type: ignore[attr-defined]
+    return response
+
+
+# --- helpers -------------------------------------------------------------------------
+
+
+def _paginate(
+    read: Callable[[int, int], Sequence[AnyNotification]], page: int, page_size: int
+) -> dict[str, Any]:
+    """One page of a listing, and whether the next page has a row.
+
+    Backends are not required to count, so that is asked directly: a full page is followed by
+    a one-row read of the first row after it, which is page ``page * page_size + 1`` of one-row
+    pages. A short page is the last one without asking. ``read`` takes the contract's
+    1-indexed pages; ``ServiceCaller`` converts them for the backend.
+    """
+    notifications = read(page, page_size)
+    has_more = len(notifications) == page_size and bool(read(page * page_size + 1, 1))
+    data: list[ListNotificationOut] = [
+        serialize_notification(notification) for notification in notifications
+    ]
+    return {"data": data, "page": page, "pageSize": page_size, "hasMore": has_more}
+
+
+def _find_notification(service: ServiceCaller, notification_id: str) -> AnyNotification:
+    notification = service.get_notification(notification_id)
+    if notification is None:
+        raise ApiError.not_found(f"Notification with ID {notification_id} was not found.")
+    return notification
+
+
+# --- system --------------------------------------------------------------------------
+
+
+@api.get(
+    "/capabilities",
+    response={200: DataResponse[dict[str, bool]], **AUTH_ERRORS},
+    tags=["system"],
+)
+def get_capabilities(request: HttpRequest) -> dict[str, Any]:
+    return {"data": get_service_caller().get_capabilities()}
+
+
+# --- notifications -------------------------------------------------------------------
+#
+# The literal collection paths are registered before `/notifications/{id}` on purpose:
+# routes match in registration order, so declaring the detail route first would make it
+# swallow `/notifications/pending`.
+
+
+@api.get(
+    "/notifications",
+    response={200: NotificationPage, **LIST_ERRORS},
+    tags=["notifications"],
+)
+def list_notifications(request: HttpRequest, query: Query[NotificationListQuery]) -> dict[str, Any]:
+    service = get_service_caller()
+    capabilities = service.get_capabilities()
+
+    # Page numbers stay in the contract's 1-indexed terms here. `ServiceCaller` converts
+    # to whatever the configured backend uses, which it learns from the backend's own
+    # `pagination.oneIndexed` capability rather than assuming.
+    backend_filter = build_backend_filter(query, capabilities)
+    order_by = build_order_by(query, capabilities)
+
+    return _paginate(
+        lambda page, page_size: service.filter_notifications(
+            backend_filter, page, page_size, order_by
+        ),
+        query.page,
+        query.pageSize,
+    )
+
+
+@api.get(
+    "/notifications/pending",
+    response={200: NotificationPage, **LIST_ERRORS},
+    tags=["notifications"],
+)
+def list_pending_notifications(
+    request: HttpRequest, query: Query[PaginationQuery]
+) -> dict[str, Any]:
+    service = get_service_caller()
+    return _paginate(service.get_pending_notifications, query.page, query.pageSize)
+
+
+@api.get(
+    "/notifications/future",
+    response={200: NotificationPage, **LIST_ERRORS},
+    tags=["notifications"],
+)
+def list_future_notifications(
+    request: HttpRequest, query: Query[PaginationQuery]
+) -> dict[str, Any]:
+    service = get_service_caller()
+    return _paginate(service.get_future_notifications, query.page, query.pageSize)
+
+
+@api.get(
+    "/notifications/one-off",
+    response={200: NotificationPage, **LIST_ERRORS},
+    tags=["notifications"],
+)
+def list_one_off_notifications(
+    request: HttpRequest, query: Query[PaginationQuery]
+) -> dict[str, Any]:
+    service = get_service_caller()
+    return _paginate(service.get_one_off_notifications, query.page, query.pageSize)
+
+
+@api.get(
+    "/notifications/{id}",
+    response={200: DataResponse[NotificationDetailOut], **LOOKUP_ERRORS},
+    tags=["notifications"],
+)
+def get_notification(request: HttpRequest, id: str) -> dict[str, Any]:  # noqa: A002
+    service = get_service_caller()
+    notification = _find_notification(service, id)
+    return {"data": serialize_notification_detail(notification)}
+
+
+@api.get(
+    "/notifications/{id}/preview",
+    response={200: DataResponse[NotificationPreviewOut], **PREVIEW_ERRORS},
+    tags=["notifications"],
+)
+def preview_notification(request: HttpRequest, id: str) -> dict[str, Any]:  # noqa: A002
+    service = get_service_caller()
+    notification = _find_notification(service, id)
+
+    preview = build_notification_preview(service, get_template_client(), notification)
+    return {"data": preview}
+
+
+@api.post(
+    "/notifications/{id}/resend",
+    response={201: DataResponse[UserNotificationOut], **RESEND_ERRORS},
+    tags=["notifications"],
+)
+def resend_notification(
+    request: HttpRequest,
+    id: str,  # noqa: A002
+    payload: ResendBody = DEFAULT_RESEND_BODY,
+) -> Status:
+    refuse_an_empty_json_body(request)
+    service = get_service_caller()
+    resent = service.resend_notification(id, payload.useStoredContext)
+
+    if resent is None:
+        raise ApiError.conflict(
+            "The notification could not be resent. It may not exist, may be a one-off "
+            "notification, or may be scheduled for the future."
+        )
+
+    return Status(201, {"data": serialize_user_notification(resent)})
+
+
+@api.post(
+    "/notifications/{id}/cancel",
+    response={200: DataResponse[CancelledNotificationOut], **CANCEL_ERRORS},
+    tags=["notifications"],
+)
+def cancel_notification(request: HttpRequest, id: str) -> dict[str, Any]:  # noqa: A002
+    service = get_service_caller()
+    notification = _find_notification(service, id)
+
+    if notification.status != "PENDING_SEND":
+        raise ApiError.conflict("Only notifications in PENDING_SEND status can be cancelled.")
+
+    service.cancel_notification(id)
+
+    return {"data": CancelledNotificationOut(id=id, status="CANCELLED")}
+
+
+# --- health --------------------------------------------------------------------------
+#
+# Unauthenticated and outside the versioned prefix: load balancers and container health
+# checks have no API key.
+
+health_api = NinjaAPI(
+    version="health",
+    urls_namespace="vintasend_api_health",
+    auth=None,
+    docs_url=None,
+)
+
+
+@health_api.get("/health", response=HealthOut, tags=["system"])
+def health(request: HttpRequest) -> dict[str, str]:
+    return {"status": "ok", "apiVersion": API_VERSION}

vintasend_api/dashboard/apps.py

@@ -0,0 +1,88 @@
+"""App configuration, including the startup checks that make a bad deployment fail fast."""
+
+from django.apps import AppConfig
+from django.core.checks import Error, register
+
+from . import conf
+from .auth import configured_authenticator
+from .hooks import HANDLER_SETTING, configured_handler
+
+
+class DashboardConfig(AppConfig):
+    name = "vintasend_api.dashboard"
+    label = "vintasend_dashboard"
+    verbose_name = "VintaSend Dashboard API"
+
+
+@register()
+def check_api_configuration(app_configs: object, **kwargs: object) -> list[Error]:
+    """Refuse to start without the settings every request depends on.
+
+    Registered as a Django system check rather than raised at import time so
+    ``manage.py`` stays usable and the message arrives as a readable checklist. Both
+    ``runserver`` and ``manage.py check`` run these; ``gunicorn`` deployments should run
+    ``manage.py check --deploy`` in their release step to get the same guarantee.
+
+    ``VINTASEND_API_KEY`` is only required when no ``VINTASEND_API_AUTHENTICATOR`` is
+    configured: an authenticator replaces the key check.
+
+    The ``GITHUB_*`` settings are deliberately absent: they are only read when
+    ``/preview`` is called, so an API that does not use template previews is correctly
+    configured without them.
+    """
+    errors: list[Error] = []
+
+    if not conf.hook_setting(conf.AUTHENTICATOR):
+        if not conf.api_key():
+            errors.append(
+                Error(
+                    "VINTASEND_API_KEY is not set.",
+                    hint=(
+                        "Every /api/v1 request must present this as a bearer token. Set it "
+                        "to a long random string shared with the dashboard, or set "
+                        f"{conf.AUTHENTICATOR} to authenticate callers yourself."
+                    ),
+                    id="vintasend_api.E001",
+                )
+            )
+    else:
+        try:
+            configured_authenticator()
+        except (ImportError, TypeError) as error:
+            errors.append(
+                Error(
+                    f"{conf.AUTHENTICATOR} cannot be used: {error}",
+                    hint=(
+                        "Point it at an importable callable taking the request, or leave it "
+                        "empty to require VINTASEND_API_KEY instead."
+                    ),
+                    id="vintasend_api.E004",
+                )
+            )
+
+    if not conf.service_factory():
+        errors.append(
+            Error(
+                "NOTIFICATION_SERVICE_FACTORY is not set.",
+                hint=(
+                    "Point it at a callable returning a configured NotificationService "
+                    "or AsyncIONotificationService, for example "
+                    "'vintasend_api.vintasend_config.create_notification_service'. "
+                    "Start from vintasend_config.example.py."
+                ),
+                id="vintasend_api.E002",
+            )
+        )
+
+    try:
+        configured_handler()
+    except (ImportError, TypeError) as error:
+        errors.append(
+            Error(
+                f"{HANDLER_SETTING} cannot be used: {error}",
+                hint="Point it at an importable callable, or leave it empty.",
+                id="vintasend_api.E003",
+            )
+        )
+
+    return errors

vintasend_api/dashboard/auth.py

@@ -0,0 +1,152 @@
+"""Who may call ``/api/v1``.
+
+Two ways, chosen by settings, both read per request so ``override_settings`` works:
+
+``VINTASEND_API_AUTHENTICATOR`` -- ``(request) -> None``
+    A host's own check, as a dotted path or as the callable itself. It refuses a caller by
+    raising ``ApiError("UNAUTHORIZED", ...)`` (401, no valid credential) or
+    ``ApiError("FORBIDDEN", ...)`` (403, a caller it knows and refuses); returning lets the
+    request through. It may be ``async``. When it is set, the shared key is not checked and
+    need not be configured. ``bearer_token`` reads the header for one built around a token
+    the host verifies itself, such as its identity provider's. Mirrors the TypeScript
+    reference's ``authenticate`` option.
+
+``VINTASEND_API_KEY``
+    The shared secret, when no authenticator is set: every request must carry
+    ``Authorization: Bearer <VINTASEND_API_KEY>``. The dashboard calls the API from its
+    server side only, so the key never reaches a browser.
+
+An authenticator that cannot be resolved answers every request with a 500 rather than falling
+back to the key: a typo in a setting must not quietly change who is let in. The system check
+``vintasend_api.E004`` reports it before that.
+"""
+
+import hmac
+import inspect
+import re
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from django.http import HttpRequest
+from ninja.security.http import HttpAuthBase
+
+from asgiref.sync import async_to_sync
+
+from . import conf
+from .errors import ApiError
+from .hooks import _awaited, configured_hook
+
+
+__all__ = [
+    "ApiError",
+    "ApiKeyAuth",
+    "Authenticator",
+    "as_refusal",
+    "bearer_token",
+    "check_api_key",
+    "configured_authenticator",
+]
+
+Authenticator = Callable[[HttpRequest], "None | Awaitable[None]"]
+
+# The scheme is matched in any case, as RFC 9110 has it. `\s+` rather than one space, and the
+# token stripped, so the answer is the same as the TypeScript twin's `bearerToken`.
+_BEARER = re.compile(r"Bearer\s+(.+)", re.IGNORECASE)
+
+_KEY_REQUIRED = "A valid API key is required."
+
+
+# What an authenticator answers when it refuses a caller.
+_REFUSALS = ("UNAUTHORIZED", "FORBIDDEN")
+
+
+def as_refusal(error: BaseException) -> ApiError | None:
+    """The refusal an authenticator raised, as this package's ``ApiError``, or None.
+
+    One authenticator can serve both VintaSend APIs mounted in one project, so it may raise
+    the other package's ``ApiError``. That one is recognised by its class name and code, as
+    the TypeScript packages do, rather than by its class, which this package cannot import.
+    Only a 401 or a 403 is an answer an authenticator gives; any other code is a failure.
+    """
+    if isinstance(error, ApiError):
+        return error
+    code = getattr(error, "code", None)
+    if type(error).__name__ != "ApiError" or code not in _REFUSALS:
+        return None
+    message = getattr(error, "message", None)
+    return ApiError(code, message if isinstance(message, str) else str(error))
+
+
+def bearer_token(request_or_header: HttpRequest | str | None) -> str | None:
+    """The token in an ``Authorization: Bearer <token>`` header, or None when there is none.
+
+    Takes the request or the header's value. A header with another scheme, or with an empty
+    token, is None too, so a caller only has to check for one thing.
+    """
+    header = (
+        request_or_header.headers.get("Authorization")
+        if isinstance(request_or_header, HttpRequest)
+        else request_or_header
+    )
+    if not header:
+        return None
+    match = _BEARER.fullmatch(header)
+    token = match.group(1).strip() if match else ""
+    return token or None
+
+
+def configured_authenticator() -> Authenticator | None:
+    """The callable ``VINTASEND_API_AUTHENTICATOR`` names, or None when it is unset.
+
+    raises ImportError: if a dotted path cannot be imported.
+    raises TypeError: if the setting names something that is not callable.
+    """
+    return cast("Authenticator | None", configured_hook(conf.AUTHENTICATOR))
+
+
+def check_api_key(request: HttpRequest) -> None:
+    """The shared-secret check, used when no authenticator is configured.
+
+    ``hmac.compare_digest`` keeps the comparison time-independent of how many leading
+    characters match, so the key cannot be recovered a byte at a time. An unset key matches
+    nothing, so a deployment that never set one refuses every request.
+    """
+    expected = conf.api_key()
+    token = bearer_token(request)
+
+    if not expected or token is None:
+        raise ApiError.unauthorized(_KEY_REQUIRED)
+
+    if not hmac.compare_digest(token.encode("utf-8"), expected.encode("utf-8")):
+        raise ApiError.unauthorized(_KEY_REQUIRED)
+
+
+class ApiKeyAuth(HttpAuthBase):
+    """Ninja's auth hook for every ``/api/v1`` route.
+
+    Declared as an HTTP bearer scheme, and still named ``ApiKeyAuth``, because Ninja
+    documents the security scheme from both: the generated schema describes the same scheme
+    whichever check a host chooses. Not an ``HttpBearer``: that refuses a request without a
+    bearer header before a host authenticator could look at it, and under ``DEBUG`` it logs a
+    header it cannot parse, credentials included.
+    """
+
+    openapi_scheme = "bearer"
+
+    def __call__(self, request: HttpRequest) -> bool:
+        authenticator = configured_authenticator()
+        if authenticator is None:
+            check_api_key(request)
+        else:
+            try:
+                outcome = authenticator(request)
+                # An unawaited coroutine would let every caller through.
+                if inspect.isawaitable(outcome):
+                    async_to_sync(_awaited)(outcome)
+            except Exception as error:
+                refusal = as_refusal(error)
+                if refusal is None or refusal is error:
+                    raise
+                raise refusal from error
+        # Ninja treats a falsy answer as "not authenticated", so success is spelled out.
+        return True