language-learning-app/api/docs/object-storage.md

Object Storage

This document explains how object storage works today, and how to control it across environments.

TL;DR

• The app has one storage interface (StorageClient) and two implementations:
  • MinioClient for local/dev (S3-compatible MinIO)
  • BunnyClient for deployed environments (Bunny Storage + Bunny CDN)
• Provider selection is controlled by STORAGE_PROVIDER:
  • local -> MinIO
  • bunny -> Bunny
• The client is initialised once at API startup and stored as a process-level singleton.

Runtime Lifecycle

1. API startup runs init_storage() from app.outbound.storage_factory.
2. init_storage() reads config from app.config.settings.
3. It creates either MinioClient or BunnyClient.
4. The client instance is set via _set_storage_client(...).
5. App code calls get_storage_client() anywhere it needs object URLs or file operations.

If storage is used before startup initialisation, get_storage_client() raises an assertion error.

Interface Contract

StorageClient currently exposes:

• upload(path, data) -> bool
• get_url(path) -> str
• get_public_url(path) -> str
• delete(path) -> bool
• download(path) -> (bytes, content_type)

Important behavior differences:

• MinIO supports download(...) for API media proxy routes.
• Bunny does not support direct download in this adapter and raises NotImplementedError; callers should use signed CDN URLs from get_url(...).

URL Behavior

Local/MinIO mode (STORAGE_PROVIDER=local)

• get_url(path) returns API-proxied URLs under /media/....
• Browser requests go through the API media router.
• Media router validates DB ownership/existence, then streams bytes from storage.

Bunny mode (STORAGE_PROVIDER=bunny)

• get_url(path) returns a signed Bunny CDN URL.
• Signature uses token auth key + path + expiry (currently 1 hour).
• Browser requests go directly to Bunny CDN (no API proxy hop).

Configuration

Local/MinIO settings

• STORAGE_PROVIDER=local
• STORAGE_ENDPOINT_URL (for Docker dev: http://storage:9000)
• STORAGE_ACCESS_KEY
• STORAGE_SECRET_KEY
• STORAGE_BUCKET
• API_BASE_URL (used to build /media/... URLs)

On startup, MinioClient.ensure_bucket_exists() is called.

Bunny settings

• STORAGE_PROVIDER=bunny
• BUNNY_ZONE
• BUNNY_API_KEY
• BUNNY_CDN_BASE_URL
• BUNNY_TOKEN_AUTH_KEY
• BUNNY_STORAGE_ENDPOINT

On startup, Bunny client runs list_directory("") as a connection test.

Where Storage Is Used

• BFF routers call get_storage_client().get_url(...) to expose audio URLs.
• Media router calls get_storage_client().download(...) to stream files for /media/... routes.

Practically:

• In local mode, /media/... endpoints are expected and functional.
• In Bunny mode, clients should consume returned CDN URLs directly.

Operational Notes

• Upload content type is currently fixed to audio/wav in both adapters.
• Bunny signed URL expiry is _SIGNED_URL_EXPIRY_SECONDS = 3600.
• The storage client is per-process; each API process initialises its own instance at boot.