feat: fal_client picks up x-fal-cdn-token header when calling run or submit

[hanchchch]

No description provided.

[linear]

INFRA-997 CDN: add support for ownership

INFRA-2094 CDN: request-scoped JWT

[efiop]

@claude review

[claude]

Claude finished @efiop's task in 1m 28s —— View job

---

Code Review

• Gathering context
• Reviewing changed files
• Posting review feedback

---

The PR title says "fal_client picks up x-fal-cdn-token header" but the actual diff is substantially larger — it also includes upload repository fallback logic, async callback support, WebSocket compatibility fixes, and a REST URL domain change. The review covers all of it.

_headers.py

Missing type annotation (projects/fal_client/src/fal_client/_headers.py:57)

def add_forwarded_headers(request_headers, _headers: dict[str, str]) -> None:

request_headers has no type annotation. Other functions in the file consistently type their parameters. This should be typed (e.g., Mapping[str, str] or a more specific headers type).

Inconsistent parameter naming — every other function in this file uses headers for the mutable dict being modified; this one uses _headers (with leading underscore, which conventionally signals "unused"). Fix this →

client.py

Unreachable code in _try_upload_with_fallback

def _try_upload_with_fallback(attempts):
    for idx, (label, attempt) in enumerate(attempts):
        try:
            return attempt()
        except Exception as exc:
            if idx >= len(attempts) - 1:
                raise          # always re-raises on last iteration
            ...
    raise RuntimeError("Upload attempts were exhausted")  # dead code

The final raise RuntimeError(...) is unreachable — the loop always re-raises on the last attempt. Same issue exists in _async_try_upload_with_fallback. This is minor but misleading.

_normalize_upload_repositories duplicates the type literal values

allowed = {"fal_v3", "cdn", "fal"}

These values are already defined in UploadRepositoryId = Literal["fal_v3", "cdn", "fal"]. Using get_args(UploadRepositoryId) would keep them in sync automatically.

_async_try_upload_with_fallback mixes sync and async callables without a clear contract — the function accepts Callable[[], Any] but silently handles both sync and coroutine returns via asyncio.iscoroutine(result). All callers pass async functions (via partial), so the sync-result path is dead code. Either constrain the type to async-only or document why sync callables are intentionally supported.

Multipart threshold silently skipped for non-fal_v3 repos — when repository_chain[0] != "fal_v3", large files skip the multipart path entirely and go through the single-POST path. This is probably intentional (cdn/fal don't support multipart), but there's no warning or comment when a large file is uploaded this way.

on_enqueue / on_queue_update async support — the change to await these callbacks if they're awaitable is clean. Using inspect.isawaitable(result) on the returned value is correct. No issues here.

WebSocket additional_headers rename — extra_headers → additional_headers is the correct API for newer versions of the websockets library. Good fix.

REST_URL domain change (rest.alpha.fal.ai → rest.fal.ai) — no tests or changelog notes for this. Worth verifying this is a straightforward redirect/promotion and not a breaking change for older deployments.

get_current_app fallback — the try/except ImportError fallback returning None is clean and ensures the feature degrades gracefully when fal is not installed.

Summary

The core feature (forwarding x-fal-cdn-token and x-fal-request-id via add_forwarded_headers) is correct. The main concerns are:

• Missing type annotation on request_headers
• Inconsistent _headers parameter name
• Unreachable raise RuntimeError in both _try_upload_with_fallback functions
• allowed set should derive from get_args(UploadRepositoryId)

These are all minor. Nothing blocking given the existing approval.