velocity-python 0.1.93__tar.gz → 0.1.94__tar.gz

{velocity_python-0.1.93 → velocity_python-0.1.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.93
+Version: 0.1.94
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -250,7 +250,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Performance & Optimization | `docs/performance.md` | Connection pooling, batch operations, query caching, prepared statements, N+1 prevention, observability |
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
-| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |

{velocity_python-0.1.93 → velocity_python-0.1.94}/README.md

@@ -156,7 +156,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Performance & Optimization | `docs/performance.md` | Connection pooling, batch operations, query caching, prepared statements, N+1 prevention, observability |
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
-| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |

{velocity_python-0.1.93 → velocity_python-0.1.94}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.93"
+version = "0.1.94"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.93 → velocity_python-0.1.94}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.93"
+__version__ = version = "0.1.94"
 
 import importlib as _importlib
 

{velocity_python-0.1.93 → velocity_python-0.1.94}/src/velocity/aws/handlers/mixins/__init__.py

@@ -5,13 +5,16 @@ This package provides mixins for common Lambda handler patterns:
 - WebHandler: Activity tracking, logging, and error handling
 - ButtonHandler: Dynamic button action handler loading
 - DataServiceMixin: Generic CRUD operations for database-backed APIs
+- JobHandler: get-job-status / download-job-result / cancel-job for async jobs
 """
 
 from .web_handler import WebHandler, ButtonHandler
 from .data_service import DataServiceMixin
+from .job_handler import JobHandler
 
 __all__ = [
     "WebHandler",
     "ButtonHandler",
     "DataServiceMixin",
+    "JobHandler",
 ]

velocity_python-0.1.94/src/velocity/aws/handlers/mixins/job_handler.py

@@ -0,0 +1,175 @@
+"""JobHandler — the web-tier half of asynchronous jobs.
+
+velocity-react's job watcher (``JobProgressPortal`` + ``startJobWatcher``) polls
+three ``/event`` actions after a response carries ``jobs.events``:
+
+* ``get-job-status``      → ``{"job_status": {job_id, status, message, batch_id, updated}}``
+* ``download-job-result`` → a ``file-download`` (or ``redirect``) response action
+* ``cancel-job``          → flags the job ``CancelRequested`` for the worker
+
+They are identical for every app, so they live here (extracted from
+BackOfficeEvents). Mix into the HTTP handler alongside ``WebHandler``::
+
+    class HttpEventHandler(ButtonHandler, JobHandler, WebHandler, LambdaHandler):
+        ...
+
+A button action that wants the watcher enqueues, then announces the job::
+
+    result = context.enqueue("zip-invoices", payload)
+    job_id = result["Successful"][0]["Id"]
+    context.response().jobs.start(job_id=job_id, label="Zipping invoices")
+
+and the worker persists its output with ``velocity.aws.job_results.store_job_result``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from typing import Any, Dict, Optional
+
+from velocity.aws.handlers.exceptions import AlertError
+from velocity.aws.job_results import (
+    deliver_job_result,
+    job_result_files,
+    parse_job_message,
+)
+from velocity.misc.format import to_json
+
+TERMINAL_JOB_STATUSES = frozenset({"Completed", "Failed", "Cancelled"})
+# Statuses that can only persist this long because the worker died without
+# running onError (Lambda timeout / OOM): synthesize Failed so the UI moves on.
+STALE_JOB_STATUSES = frozenset({"Running", "Initialized"})
+
+
+class JobHandler:
+    JOB_ACTIVITY_TABLE = "aws_job_activity"
+    JOB_STALE_AFTER = datetime.timedelta(minutes=16)
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def _job_id_from(self, context) -> str:
+        payload = context.payload() or {}
+        job_id = payload.get("job_id") if isinstance(payload, dict) else None
+        if not job_id:
+            raise AlertError("job_id is required")
+        return str(job_id)
+
+    def _find_job(self, tx, job_id: str):
+        return tx.table(self.JOB_ACTIVITY_TABLE).find({"job_id": job_id})
+
+    def _job_is_stale(self, job) -> bool:
+        if (job.get("status") or "") not in STALE_JOB_STATUSES:
+            return False
+        ts = job.get("sys_modified") or job.get("initial_timestamp")
+        if ts is None:
+            return False
+        now = datetime.datetime.now(datetime.timezone.utc)
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=datetime.timezone.utc)
+        return (now - ts) > self.JOB_STALE_AFTER
+
+    @staticmethod
+    def _job_status_body(
+        job_id: str,
+        status: str,
+        message: Optional[Dict[str, Any]],
+        job=None,
+    ) -> Dict[str, Any]:
+        body = {"job_id": job_id, "status": status, "message": message}
+        if job is not None:
+            body["batch_id"] = job.get("batch_id")
+            body["updated"] = job.get("sys_modified")
+        return {"job_status": body}
+
+    # ── actions ───────────────────────────────────────────────────────────────
+
+    def OnActionGetJobStatus(self, tx, context):
+        """Current status + message for one job (polled by the job watcher)."""
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            context.response().set_body(
+                self._job_status_body(
+                    job_id, "NotFound", {"detail": "Job not found"}
+                )
+            )
+            return
+
+        if self._job_is_stale(job):
+            context.response().set_body(
+                self._job_status_body(
+                    job_id,
+                    "Failed",
+                    {
+                        "detail": "Job timed out — the server ran out of time or memory.",
+                        "error": "Lambda timed out or was killed (OOM)",
+                    },
+                    job,
+                )
+            )
+            return
+
+        message = parse_job_message(job.get("message")) or None
+        context.response().set_body(
+            self._job_status_body(job_id, job.get("status") or "", message, job)
+        )
+
+    def OnActionDownloadJobResult(self, tx, context):
+        """Deliver a completed job's file via the store that holds it."""
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            raise AlertError("Job result not found")
+
+        files = job_result_files(job.get("message"))
+        if not files:
+            raise AlertError("Job result is not ready")
+
+        # One file per job result; descriptors without a store are legacy
+        # BackOffice S3 entries.
+        descriptor = dict(files[0])
+        descriptor.setdefault("store", "s3" if descriptor.get("bucket") else "db")
+        deliver_job_result(tx, context, descriptor)
+        context.response().toast("Download ready.")
+
+    def OnActionCancelJob(self, tx, context):
+        """Ask the worker to stop: status CancelRequested + message flag.
+
+        Workers poll ``context.is_job_cancel_requested(tx)`` between units of
+        work and call ``context.mark_job_cancelled`` when they honour it.
+        """
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            raise AlertError("Job not found")
+
+        current = job.get("status") or ""
+        if current in TERMINAL_JOB_STATUSES:
+            raise AlertError(f"Job is already {current.lower()}")
+
+        payload = context.payload() or {}
+        message = parse_job_message(job.get("message"))
+        message.update(
+            {
+                "detail": payload.get("detail")
+                or payload.get("reason")
+                or "Cancellation requested by user",
+                "cancel_requested": True,
+            }
+        )
+        tx.table(self.JOB_ACTIVITY_TABLE).update(
+            {
+                "status": "CancelRequested",
+                "message": to_json(message),
+                "sys_modified": datetime.datetime.now(),
+                "sys_modified_by": (context.session() or {}).get("email_address"),
+            },
+            {"job_id": job_id},
+        )
+        context.response().set_body(
+            self._job_status_body(job_id, "CancelRequested", message)
+        )
+
+
+__all__ = ["JobHandler", "TERMINAL_JOB_STATUSES", "STALE_JOB_STATUSES"]

velocity_python-0.1.94/src/velocity/aws/job_results.py

@@ -0,0 +1,453 @@
+"""Result storage for asynchronous jobs.
+
+A button action that may outrun the API Gateway budget enqueues work instead
+(``context.enqueue``), the queue worker produces a file, and the browser — which
+velocity-react is already polling via ``get-job-status`` — fetches it with
+``download-job-result``. This module is the seam between the two halves:
+
+* workers call :func:`store_job_result` — persist the bytes through a
+  :class:`JobResultStore` and record a *file descriptor* on the job's
+  ``aws_job_activity.message.result.files`` (the shape BackOffice's export
+  pipeline established, so existing UI code keeps working);
+* the web tier (``JobHandler.OnActionDownloadJobResult``) calls
+  :func:`deliver_job_result`, which routes the descriptor back to the store
+  that wrote it and emits the response action that gets the file to the user.
+
+Two stores ship:
+
+``DbJobResultStore`` (default)
+    Bytes live in the ``aws_job_results`` table and are delivered inline as a
+    ``file-download`` action (base64 over API Gateway). No infrastructure
+    beyond the database, but bounded by the ~6 MB Lambda response limit — see
+    ``max_inline_bytes``.
+``S3JobResultStore``
+    Bytes go to a bucket and are delivered as a short-lived presigned GET via a
+    ``redirect`` action — no size ceiling, needs a bucket + IAM.
+
+Stores are registered by name (``descriptor["store"]``) so an app can swap
+backends without touching its workers: ``register_job_result_store(
+S3JobResultStore("my-bucket"), default=True)``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional
+
+from velocity.misc.format import to_json
+
+# ``velocity.aws.handlers`` initializes a DB engine when its package is imported,
+# so the user-facing error type is imported lazily: workers, schema scripts and
+# tests can import this module without database configuration.
+
+
+def _alert(message: str) -> Exception:
+    from velocity.aws.handlers.exceptions import AlertError
+
+    return AlertError(message)
+
+__all__ = [
+    "JOB_RESULTS_TABLE",
+    "JOB_RESULTS_SCHEMA",
+    "JOB_RESULTS_INDEXES",
+    "JobResultStore",
+    "DbJobResultStore",
+    "S3JobResultStore",
+    "register_job_result_store",
+    "get_job_result_store",
+    "default_job_result_store",
+    "registered_job_result_stores",
+    "store_job_result",
+    "record_job_result",
+    "deliver_job_result",
+    "parse_job_message",
+    "job_result_files",
+]
+
+JOB_RESULTS_TABLE = "aws_job_results"
+
+# Declared SQL types so an app's schema lane can create the table up front in
+# locked environments (velocity also creates it lazily on first write in dev).
+JOB_RESULTS_SCHEMA: Dict[str, str] = {
+    "job_id": "TEXT",
+    "filename": "TEXT",
+    "content_type": "TEXT",
+    "payload": "BYTEA",
+    "size_bytes": "BIGINT",
+    "created_by": "TEXT",
+    "expires_at": "TIMESTAMPTZ",
+}
+JOB_RESULTS_INDEXES = (
+    (
+        "aws_job_results_job_id_idx",
+        "CREATE UNIQUE INDEX IF NOT EXISTS aws_job_results_job_id_idx "
+        "ON aws_job_results (job_id)",
+    ),
+)
+
+_SAFE_FILENAME = re.compile(r"[^A-Za-z0-9._ -]+")
+
+
+def _safe_filename(filename: Optional[str], default: str = "download") -> str:
+    """Last path segment only, restricted to a conservative character set."""
+    name = re.split(r"[\\/]+", str(filename or "").strip())[-1]
+    name = _SAFE_FILENAME.sub("_", name).strip(" .")
+    return name or default
+
+
+def parse_job_message(raw: Any) -> Dict[str, Any]:
+    """``aws_job_activity.message`` as a dict (it is stored as JSON text, but
+    legacy rows carry plain strings — those become ``{"detail": text}``)."""
+    if raw is None or raw == "":
+        return {}
+    if isinstance(raw, dict):
+        return dict(raw)
+    try:
+        parsed = json.loads(raw)
+    except (TypeError, ValueError):
+        return {"detail": str(raw)}
+    return parsed if isinstance(parsed, dict) else {"detail": str(raw)}
+
+
+def job_result_files(message: Any) -> list:
+    """The ``result.files`` descriptors recorded on a job message, or ``[]``."""
+    parsed = parse_job_message(message)
+    result = parsed.get("result")
+    if not isinstance(result, dict):
+        return []
+    files = result.get("files")
+    return [f for f in files if isinstance(f, dict)] if isinstance(files, list) else []
+
+
+class JobResultStore(ABC):
+    """Persist a job's output file and deliver it back to the browser later.
+
+    ``put`` returns a JSON-safe *descriptor* — at minimum ``store`` (this
+    store's name), ``filename``, ``contentType`` and ``size`` — which is what
+    gets recorded on the job and handed back to ``deliver``.
+    """
+
+    name: str = ""
+
+    @abstractmethod
+    def put(
+        self,
+        tx,
+        *,
+        job_id: str,
+        filename: str,
+        payload: bytes,
+        content_type: str = "application/octet-stream",
+        created_by: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Persist ``payload`` for ``job_id`` and return its descriptor."""
+
+    @abstractmethod
+    def deliver(self, tx, context, descriptor: Dict[str, Any]) -> None:
+        """Emit the response action(s) that get the described file to the user."""
+
+    def _descriptor(self, **fields) -> Dict[str, Any]:
+        base = {"store": self.name}
+        base.update({k: v for k, v in fields.items() if v is not None})
+        return base
+
+
+class DbJobResultStore(JobResultStore):
+    """Results stored as ``bytea`` rows in ``aws_job_results`` and delivered
+    inline as a ``file-download`` action.
+
+    ``max_inline_bytes`` guards the Lambda/API Gateway response ceiling (6 MB
+    after base64 inflation ≈ 4.5 MB of file); larger outputs need the S3 store.
+    """
+
+    name = "db"
+
+    def __init__(
+        self,
+        table: str = JOB_RESULTS_TABLE,
+        *,
+        max_inline_bytes: int = 4_500_000,
+        retention: Optional[timedelta] = timedelta(days=7),
+    ):
+        self.table = table
+        self.max_inline_bytes = max_inline_bytes
+        self.retention = retention
+
+    def put(
+        self,
+        tx,
+        *,
+        job_id,
+        filename,
+        payload,
+        content_type="application/octet-stream",
+        created_by=None,
+    ):
+        if not job_id:
+            raise ValueError("DbJobResultStore.put requires a job_id")
+        payload = bytes(payload)
+        if len(payload) > self.max_inline_bytes:
+            raise ValueError(
+                f"Job result is {len(payload):,} bytes; the database store delivers "
+                f"inline and is capped at {self.max_inline_bytes:,} bytes. Use "
+                "S3JobResultStore for outputs this large."
+            )
+        filename = _safe_filename(filename)
+        now = datetime.now(timezone.utc)
+        row = {
+            "filename": filename,
+            "content_type": content_type,
+            "payload": payload,
+            "size_bytes": len(payload),
+            "created_by": created_by,
+            "expires_at": (now + self.retention) if self.retention else None,
+        }
+        tx.table(self.table).upsert(row, {"job_id": str(job_id)})
+        return self._descriptor(
+            table=self.table,
+            job_id=str(job_id),
+            filename=filename,
+            contentType=content_type,
+            size=len(payload),
+        )
+
+    def deliver(self, tx, context, descriptor):
+        job_id = descriptor.get("job_id")
+        if not job_id:
+            raise _alert("Job result descriptor is missing its job_id")
+        row = tx.table(descriptor.get("table") or self.table).find({"job_id": job_id})
+        if not row:
+            raise _alert("Job result is no longer available")
+        payload = row["payload"]
+        if isinstance(payload, memoryview):
+            payload = payload.tobytes()
+        if payload is None:
+            raise _alert("Job result is empty")
+        payload = bytes(payload)
+        if len(payload) > self.max_inline_bytes:
+            raise _alert(
+                "Job result is too large to download inline; ask an administrator "
+                "to enable S3-backed job results."
+            )
+        filename = descriptor.get("filename") or row.get("filename") or "download"
+        content_type = (
+            descriptor.get("contentType")
+            or row.get("content_type")
+            or "application/octet-stream"
+        )
+        context.response().file_download(
+            {
+                "filename": filename,
+                "data": base64.b64encode(payload).decode(),
+                "mimeType": content_type,
+                "contentType": content_type,
+            }
+        )
+
+    def purge_expired(self, tx, now: Optional[datetime] = None) -> int:
+        """Delete rows past ``expires_at``; returns the number removed."""
+        now = now or datetime.now(timezone.utc)
+        return tx.table(self.table).delete({"<expires_at": now}) or 0
+
+
+class S3JobResultStore(JobResultStore):
+    """Results uploaded to S3 and delivered as a presigned GET ``redirect``."""
+
+    name = "s3"
+
+    def __init__(
+        self,
+        bucket: str,
+        *,
+        prefix: str = "job-results",
+        expires_in: int = 300,
+        s3_client=None,
+    ):
+        if not bucket:
+            raise ValueError("S3JobResultStore requires a bucket name")
+        self.bucket = bucket
+        self.prefix = prefix.strip("/")
+        self.expires_in = expires_in
+        self._s3 = s3_client
+
+    def _client(self):
+        if self._s3 is None:
+            import boto3
+
+            self._s3 = boto3.client("s3")
+        return self._s3
+
+    def key_for(self, job_id: str, filename: str) -> str:
+        parts = [p for p in (self.prefix, str(job_id), _safe_filename(filename)) if p]
+        return "/".join(parts)
+
+    def put(
+        self,
+        tx,
+        *,
+        job_id,
+        filename,
+        payload,
+        content_type="application/octet-stream",
+        created_by=None,
+    ):
+        del tx, created_by
+        if not job_id:
+            raise ValueError("S3JobResultStore.put requires a job_id")
+        filename = _safe_filename(filename)
+        key = self.key_for(job_id, filename)
+        payload = bytes(payload)
+        self._client().put_object(
+            Bucket=self.bucket,
+            Key=key,
+            Body=payload,
+            ContentType=content_type,
+            ContentDisposition=f'attachment; filename="{filename}"',
+        )
+        return self._descriptor(
+            bucket=self.bucket,
+            key=key,
+            filename=filename,
+            contentType=content_type,
+            size=len(payload),
+        )
+
+    def deliver(self, tx, context, descriptor):
+        del tx
+        from velocity.aws.s3 import generate_presigned_get
+
+        bucket = descriptor.get("bucket") or self.bucket
+        key = descriptor.get("key")
+        if not key:
+            raise _alert("Job result descriptor is missing its S3 key")
+        url = generate_presigned_get(
+            bucket,
+            key,
+            expires_in=self.expires_in,
+            filename=descriptor.get("filename") or key.rsplit("/", 1)[-1],
+            content_type=descriptor.get("contentType") or "application/octet-stream",
+        )
+        context.response().redirect(url)
+
+
+# ── Registry ──────────────────────────────────────────────────────────────────
+
+_STORES: Dict[str, JobResultStore] = {}
+_DEFAULT: Optional[str] = None
+
+
+def register_job_result_store(store: JobResultStore, *, default: bool = False) -> None:
+    """Register ``store`` under ``store.name``; ``default=True`` makes it the
+    store :func:`store_job_result` uses when none is passed."""
+    global _DEFAULT
+    if not getattr(store, "name", None):
+        raise ValueError("A job result store must declare a non-empty name")
+    _STORES[store.name] = store
+    if default or _DEFAULT is None:
+        _DEFAULT = store.name
+
+
+def registered_job_result_stores() -> Dict[str, JobResultStore]:
+    return dict(_STORES)
+
+
+def get_job_result_store(name: Optional[str] = None) -> JobResultStore:
+    """The store registered as ``name`` (or the default when ``name`` is None)."""
+    key = name or _DEFAULT
+    if key is None or key not in _STORES:
+        raise _alert(
+            f"No job result store registered as {key!r}"
+            if name
+            else "No default job result store is registered"
+        )
+    return _STORES[key]
+
+
+def default_job_result_store() -> JobResultStore:
+    return get_job_result_store(None)
+
+
+# The database store needs nothing configured, so it is the out-of-the-box
+# default; apps register an S3 store when they outgrow inline delivery.
+register_job_result_store(DbJobResultStore(), default=True)
+
+
+# ── Worker / web-tier helpers ─────────────────────────────────────────────────
+
+
+def record_job_result(
+    context,
+    descriptors,
+    *,
+    detail: Optional[str] = None,
+    percent: Optional[float] = 100,
+    extra: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Write ``result.files`` onto the current job's message (the job is the
+    one in ``context.postdata("job_id")``). Returns the message written.
+
+    Status is left alone: the queue handler's ``afterAction`` flips it to
+    ``Completed``, and a lifecycle that preserves a message carrying ``result``
+    (as BackOffice's does) keeps these descriptors intact.
+    """
+    if isinstance(descriptors, dict):
+        descriptors = [descriptors]
+    message: Dict[str, Any] = {}
+    if extra:
+        message.update(extra)
+    if percent is not None:
+        message["percent"] = percent
+    if detail:
+        message["detail"] = detail
+    message["result"] = {"files": list(descriptors)}
+    context.update_job({"message": to_json(message)})
+    return message
+
+
+def store_job_result(
+    tx,
+    context,
+    *,
+    filename: str,
+    payload: bytes,
+    content_type: str = "application/octet-stream",
+    store: Optional[JobResultStore] = None,
+    detail: Optional[str] = None,
+    created_by: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Persist a worker's output and record it on the job.
+
+    Returns the descriptor, or ``None`` when there is no job_id on the context
+    (the same code path ran synchronously and nothing needs storing).
+    """
+    job_id = context.postdata("job_id")
+    if not job_id:
+        return None
+    store = store or default_job_result_store()
+    if created_by is None:
+        payload_meta = context.payload() or {}
+        created_by = payload_meta.get("requested_by") if isinstance(payload_meta, dict) else None
+    descriptor = store.put(
+        tx,
+        job_id=job_id,
+        filename=filename,
+        payload=payload,
+        content_type=content_type,
+        created_by=created_by,
+    )
+    record_job_result(
+        context,
+        descriptor,
+        detail=detail or f"{descriptor.get('filename')} is ready",
+    )
+    return descriptor
+
+
+def deliver_job_result(tx, context, descriptor: Dict[str, Any]) -> None:
+    """Hand a recorded descriptor back to the store that wrote it."""
+    store = get_job_result_store(descriptor.get("store"))
+    store.deliver(tx, context, descriptor)