feat(api): media crop endpoint for cast viewport mirror (spec 061 T001-T002) #1230

Merged
chris merged 2 commits from feat/061-cast-crop-api into main 2026-10-15 00:13:16 +02:00
Owner

Spec 061 backend lane (T001-T002): lets the Android cast sender mirror the phone's zoomed/panned viewport on the Chromecast Default Receiver via server-side crop.

Endpoint contract

GET /api/media/{mediaItemId}/crop

  • Params (required): sx, sy, sw, sh — normalized doubles in 0..1 describing the source rect relative to the full image. Validated: all finite; sx,sy in [0,1]; sw,sh in [0.01,1]; sx+sw <= 1 and sy+sh <= 1 (1e-6 float tolerance). Degenerate/out-of-range → 400 problem+json.
  • Params (optional): maxW — output width clamp, default 1280, hard maximum 1280 (larger values are clamped, not rejected); must be >= 1. Never upscales.
  • Source: the bounded derived preview rendition (thumbnail fallback); the original is NEVER decoded on this path (memory safety, FR-002). Neither rendition or invisible item → 404 (no-store); missing/corrupt file → 404; storage mount down → 503.
  • Output: image/jpeg (quality 0.85), crop rect rounded and clamped to bounds (min 1px), scaled so width <= maxW, aspect preserved.
  • Headers: Cache-Control: no-store (FR-006 — continuous parameter space, no caching), Vary: Cookie. No ETag.

Token support (spec 060 machinery, FR-003/FR-004)

  • POST /api/media/token now accepts rendition "crop" (mint whitelist + media:read scope + visibility re-check, unchanged flow).
  • MediaTokenAuthenticationFilter: new token-capable path /api/media/{id}/crop mapping to rendition "crop". Binding stays item+rendition — the rect params are not signed; a crop token authorizes any rect of that one item. Cookie/bearer precedence unchanged.

Tests

  • New MediaCropControllerTest (15 tests): crop content/dimensions from a generated two-tone JPEG, preview-preferred/thumbnail-fallback, 404s, token-claim binding, degenerate-rect rejection, maxW clamp/no-upscale, media:read scope, problem+json 400.
  • MediaTokenAccessTest extended (+11 tests) through the real security filter chain: mint crop, valid token → 200 image/jpeg, cookie path unchanged, expired/garbage/wrong-item → 403, crop token cannot access /original or /derived, no auth → 401, bad rect → 400.
  • rtk ./gradlew :apps:api:test: 2055 tests, 0 failures.
Spec 061 backend lane (T001-T002): lets the Android cast sender mirror the phone's zoomed/panned viewport on the Chromecast Default Receiver via server-side crop. ## Endpoint contract GET /api/media/{mediaItemId}/crop - Params (required): sx, sy, sw, sh — normalized doubles in 0..1 describing the source rect relative to the full image. Validated: all finite; sx,sy in [0,1]; sw,sh in [0.01,1]; sx+sw <= 1 and sy+sh <= 1 (1e-6 float tolerance). Degenerate/out-of-range → 400 problem+json. - Params (optional): maxW — output width clamp, default 1280, hard maximum 1280 (larger values are clamped, not rejected); must be >= 1. Never upscales. - Source: the bounded derived preview rendition (thumbnail fallback); the original is NEVER decoded on this path (memory safety, FR-002). Neither rendition or invisible item → 404 (no-store); missing/corrupt file → 404; storage mount down → 503. - Output: image/jpeg (quality 0.85), crop rect rounded and clamped to bounds (min 1px), scaled so width <= maxW, aspect preserved. - Headers: Cache-Control: no-store (FR-006 — continuous parameter space, no caching), Vary: Cookie. No ETag. ## Token support (spec 060 machinery, FR-003/FR-004) - POST /api/media/token now accepts rendition "crop" (mint whitelist + media:read scope + visibility re-check, unchanged flow). - MediaTokenAuthenticationFilter: new token-capable path /api/media/{id}/crop mapping to rendition "crop". Binding stays item+rendition — the rect params are not signed; a crop token authorizes any rect of that one item. Cookie/bearer precedence unchanged. ## Tests - New MediaCropControllerTest (15 tests): crop content/dimensions from a generated two-tone JPEG, preview-preferred/thumbnail-fallback, 404s, token-claim binding, degenerate-rect rejection, maxW clamp/no-upscale, media:read scope, problem+json 400. - MediaTokenAccessTest extended (+11 tests) through the real security filter chain: mint crop, valid token → 200 image/jpeg, cookie path unchanged, expired/garbage/wrong-item → 403, crop token cannot access /original or /derived, no auth → 401, bad rect → 400. - rtk ./gradlew :apps:api:test: 2055 tests, 0 failures.
feat(api): media crop endpoint for cast viewport mirror (spec 061 T001-T002)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 11m11s
b0777940c3
GET /api/media/{mediaItemId}/crop serves a JPEG crop of a normalized
source rect (sx,sy,sw,sh in 0..1, optional maxW default/hard-max 1280)
decoded from the bounded preview rendition (thumbnail fallback; the
original is never decoded on this path), with Cache-Control no-store.

The spec-060 media token gains rendition "crop": added to the mint
whitelist and to MediaTokenAuthenticationFilter's token-capable path
patterns. Binding stays item+rendition — a crop token authorizes any
rect of that one item; rect params are not signed. Cookie/bearer auth
is unchanged and keeps the shared viewer-permission predicate.
fix(api): guard crop decode dimensions + check scope before rect validation — oracle review
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 2m32s
1fdb78e875
M1: decodeSource now reads the image header via ImageIO readers and
rejects sources wider/taller than 4096px before any pixel decode, so a
corrupted or hostile derived file cannot force a width*height*4
allocation that bypasses ProblemDetail mapping via OutOfMemoryError.
Reader and input stream are closed via try-with-resources/dispose; an
oversized source is treated as unreadable (404), same as undecodable.

L1: requireApiScope(media:read) now runs before rect validation, so an
API credential without the scope gets 403 before any param work —
matching DerivedAssetController house style.

Tests: oversized synthetic source -> 404 without decode; missing
derived source with a decodable original present -> still 404 and the
original is never decoded (pins FR-002).
chris merged commit 24d1ddab72 into main 2026-10-15 00:13:16 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1230
No description provided.