af-downloads-client

Thin client for allfly-downloads, the service that gives out stable download links (https://downloads.quest.allfly.io/{token}) for files in our S3 buckets instead of raw presigned URLs. The service creates a short-lived presigned URL only when someone opens the link.

This package holds only the contract (request/response models and errors) and the client. All link logic (tokens, allowlist, expiry, presigning, landing pages) lives in the allfly-downloads repo. For now the client invokes the links Lambda directly; moving to HTTP later is a version bump, not an API change.

Installation

uv add af-downloads-client
# or
pip install af-downloads-client

Quickstart

from allfly.downloads.client import AllflyDownloads, LinkMode, RegisterDownloadRequest

downloads = AllflyDownloads()

# Export email: landing page link that expires
link = downloads.register_download(
    RegisterDownloadRequest(
        bucket="staging-jobs-system-assets",
        key=f"exports/{job_id}.xlsx",
        mode=LinkMode.landing,
        source=f"jobs:{job_id}",
        file_name="Report.xlsx",
    )
)
link.url         # https://downloads.quest.allfly.io/{token}
link.expires_at  # datetime, or None for links that never expire

# Intercom screenshot: inline link usable as <img src>, no expiry
image = downloads.register_download(
    RegisterDownloadRequest(
        bucket=bucket,
        key=key,
        mode=LinkMode.inline,
        source=f"request:{request_id}",
    )
)

# Revoke one link, or every link for a source
downloads.revoke(token=link.token)
downloads.revoke(source=f"request:{request_id}")  # returns how many were revoked

register_download is idempotent per source + key: a retry returns the existing active link.

Link modes

The mode decides the lifetime: landing links expire after the service's configured default, inline links never expire. There's no per-link override.

Request fields

There's no content type field: S3 serves the Content-Type stored on the object, so set it when you upload.

Configuration

Credentials come from the default boto3 chain (the ECS task role in our services). The caller's role must be allowed to invoke the links Lambda; that permission is managed in the allfly-downloads repo, not by consumers.

Errors

All errors derive from DownloadsError.

revoke() raises ValueError unless exactly one of token or source is given.

Wire format

Requests to the links Lambda:

{"action": "register", "bucket": "...", "key": "...", "mode": "landing", "source": "jobs:123", "file_name": "Report.xlsx"}
{"action": "revoke", "token": "..."}
{"action": "revoke", "source": "request:9"}

Replies:

{"ok": true, "data": {"token": "...", "url": "...", "expires_at": "2026-11-02T10:00:00Z"}}
{"ok": true, "data": {"revoked": 1}}
{"ok": false, "error": {"code": "not_allowed", "message": "..."}}

Response models ignore unknown fields, so the service can add fields without breaking older clients.

Testing consumers

Mock the client in your tests:

from unittest.mock import MagicMock

from allfly.downloads.client import AllflyDownloads, RegisterDownloadResponse

downloads = MagicMock(spec=AllflyDownloads)
downloads.register_download.return_value = RegisterDownloadResponse(token="t", url="https://downloads.example/t")

Development

cd af-downloads-client
uv sync
uv run pytest