feat(worker-media): profile_photo_crop derived asset handler (spec 057) #1149
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/057-self-person-worker-crop"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary (spec 057, S4 — WORKER lane, task S057T004)
Implements the
profile_photo_cropjob handler inapps:worker-mediaper the pinned cross-lane contract.ProfilePhotoCrop(mirrors theFaceScopeCroppattern): job/derived-type constants, crop payload parsing, pixel-window geometry, and magic-byte container sniffing.MediaJobHandlers: newcase "profile_photo_crop"dispatch. Handler validates the payload, downloads the original (same media-access path as the existing crop handlers), decodes viadecodeRegionSource(EXIF-orientation aware, ImageMagick for HEIC), renders square JPEG variants 256 and 512 (largest first;qualityScorecomputed once from the largest rendered crop like the face-crop path), then:derived_assetresult per variant (256 → 512,complete:falsethencomplete:true) withderived_type="profile_photo",variant="256"/"512",generation_version=payload.generationVersion.CoreApiWorkerClient: extracted staticidempotencyKey(job, resultType, payload); per-variant discriminator now also applies toderived_assetresults ofprofile_photo_croponly (all other job/result key shapes byte-for-byte unchanged).profile_photo_cropadded to the worker's default capability list (WorkerProperties,application.yml).generationVersionmakesupsertDerivedAssetwrite new (media, type, variant, generation) rows; old generations stay superseded — same regeneration semantics as face-scope crops. The worker never deletes rows.Contract notes (cross-lane)
profile_photo_crop(string literal — apps/api has no shared job-type constants class, so no api constant was added).{mediaItemId, cropX, cropY, cropSize, generationVersion}exactly as pinned.cropX = left/W,cropY = top/H,cropSize = side/W(side_px = size × width), position clamped into the raster. This matches the frontend lane's already-writtenapps/web/src/lib/utils/selfPersonCrop.ts+src/lib/api/self-person.tsdocs — confirmed before implementing.detectedFormat, so the handler sniffs JPEG/PNG/HEIC magic bytes when the field is absent (HEIC still reaches the ImageMagick decode path).mediaItemId/crop/generationVersion→invalid_worker_payload, undecodable/missing source →image_decode_failed,mediaType=video→unsupported/profile_photo_crop_for_non_photo.Required api-side follow-ups (apps/api is owned by the parallel backend lane — NOT touched here)
WorkerResultService.shouldCompleteJobcompletes a job on the firstderived_assetresult (onlydiscovery_thumbnailhonors acompleteflag), andrequireLeasethen rejects any further result. Until Core honors thecompleteflag this worker already sends (false/true), the second variant submission is rejected withmissing_active_lease. The worker guards secondary submissions (warn + continue) so the worker loop never crashes; with the current API the 256 variant lands, the 512 variant is dropped. Recommended fix: honor an explicit payloadcompleteboolean forderived_assetresults (absent ⇒ true), exactly likediscovery_thumbnail."profile_photo_crop"toWorkerCredentialBootstrap.ML_JOB_TYPES(or aVxxxmigrationarray_cat-ingworker_credentials.allowed_job_types, precedent V084/V095) — claims filter onworker.allowsJobType, so the job is otherwise unclaimable.deploy/compose.yaml:145setsMEMORIES_WORKER_CAPABILITIESexplicitly formemories-worker-media; appendprofile_photo_cropthere (out of this lane's write scope).ProcessingActivityLanes/JobEventsService.JOB_LABELShave no entry for this job type (it just won't show in a labelled activity lane).Test evidence
rtk ./gradlew :apps:worker-media:test(from worktree root, freshcleanTestrun after rebase onto latestorigin/main):12 new test cases, including: both square variants rendered at 256/512 with the cropped region's pixels verified, per-variant
derived_assetpayloads (complete,width/height,generationVersion, sharedqualityScore), width-anchored window geometry + edge clamping, container sniffing, degenerate/sub-pixel crop, missing crop/generation, unreadable media, video media type, per-variant idempotency keys (existing key shapes asserted unchanged), and secondary-result rejection tolerance.1c4b964e21be0178cec2