kasuvia-media-client

Shared internal client for talking to kasuvia-media-system. Every Kasuvia microservice that needs to upload/confirm/delete media goes through this package instead of hand-rolling its own HTTP client — the goal is that a bug in "how we auth to kasuvia-media-system" or "how we retry" is fixed in one file, not four.

Contents

• client.py — MediaSystemClient, async (httpx.AsyncClient). Use from FastAPI services: kasuvia-store-management, kasuvia-cms, kasuvia-website-builder-system.
• sync_client.py — SyncMediaSystemClient, sync (httpx.Client), identical method contract. Use from kasuvia-auth (Django, coded fully synchronously).
• auth.py — builds the X-Internal-Service header.
• retry.py — shared retry policy: 3 attempts, exponential backoff 1s/2s/4s, only on network failures and 502/503/504 (not on 4xx — those are permanent rejections, retrying wastes the attempt budget).
• exceptions.py — MediaClientError and subclasses (MediaUploadError, PresignedUrlExpiredError, MediaValidationError, MediaNotFoundError, MediaServiceUnavailableError), mapped from HTTP status codes.
• types.py — shared request/response models (PresignedUrlRequest, PresignedUrlResponse, ConfirmUploadRequest, MediaAssetResponse) and the Context constants used across every domain.

Usage (async — FastAPI services)

from kasuvia_media_client import MediaSystemClient, PresignedUrlRequest, ConfirmUploadRequest, Context

client = MediaSystemClient(
    base_url=settings.KASUVIA_MEDIA_SYSTEM_URL,
    internal_service_secret=settings.INTERNAL_SERVICE_SECRET,
)

presigned = await client.get_presigned_url(
    PresignedUrlRequest(
        filename=file.filename,
        content_type=file.content_type,
        business_id=business_id,
        context=Context.PRODUCT,
        entity_id=product_id,
    )
)
# ... client PUTs the file bytes directly to `presigned.presigned_url` ...
asset = await client.confirm_upload(
    ConfirmUploadRequest(
        storage_path=presigned.storage_path,
        business_id=business_id,
        original_filename=file.filename,
        content_type=file.content_type,
        size=file_size,
        context=Context.PRODUCT,
        entity_id=product_id,
    )
)

Usage (sync — kasuvia-auth / Django)

Same shapes, no await:

from kasuvia_media_client import SyncMediaSystemClient, PresignedUrlRequest, Context

client = SyncMediaSystemClient(
    base_url=settings.KASUVIA_MEDIA_SYSTEM_URL,
    internal_service_secret=settings.INTERNAL_SERVICE_SECRET,
)
presigned = client.get_presigned_url(
    PresignedUrlRequest(
        filename=filename,
        content_type=content_type,
        business_id=business_id,
        context=Context.USER_AVATAR,
        entity_id=user_id,
    )
)

Development

pip install -e ".[test]"
pytest