feat(api): owner metadata overrides end-to-end — effective detail values + revert (FR-041/SC-019, ISSUE-017) #1095

Merged
chris merged 6 commits from chris/feat/metadata-edit-api into main 2026-10-10 22:02:11 +02:00 AGit
Owner

What

Makes owner metadata overrides (capture date + GPS location) work end-to-end on the backend with revert support — implements spec FR-041 / SC-019 and fixes KNOWN_ISSUES ISSUE-017 (high/open: MetadataController passed ownerId=null into createOverride, so requireOwner denied every override call).

## Changes

- Owner resolution (ISSUE-017): create and the new DELETE revert resolve the owner via LocalAuthService.currentSession(authentication).ownerId() (MediaController pattern); unknown media now 404s instead of 500.
- Server-side validation (400 ProblemDetail via existing ApiExceptionHandler): capture_time ISO-8601 instant within 1800-01-01..now+1y; location lat −90..90 / lon −180..180; timezone must be an IANA zone id (offsets rejected); favorite boolean; rating number; title/description strings.
- Media detail applies overrides: GET /api/media/{id} returns effective captureTimestamp/location (active override wins, else extracted) with the existing shareLocation gate preserved (a gated-out location override never leaks coordinates); new fields captureTimestampSource / locationSource (extracted | user_override, null when no value/gated) and activeMetadataOverrides ({metadataClass, value, sourceValue, updatedAt} — sourceValue powers the revert UI, SC-019). effectiveMetadata is kept (apps/web favorite) and now carries natural JSON values.
- NEW DELETE /api/media/{id}/metadata-overrides/{metadataClass}: reverts the active override (replaced_at set, provenance annotated revertedAt/revertedBy, history retained; effective value falls back to extracted). Idempotent 204; 403 non-owner; 404 unknown media; 400 unknown class.
- V157: partial index on active capture_time/timezone/location overrides for the detail/suggestion joins (V005 covers title/description only, V144 favorite only). No destructive schema changes.
- Contract: core-api.openapi.yaml updated to match (request value shapes, {id} 201 response, DELETE path, new MediaDetail fields); contract test asserts the new path.

## API contract (frontend lane builds against this)

1. POST /api/media/{mediaItemId}/metadata-overrides — body {metadataClass, value}: capture_time = ISO-8601 instant string; location = {latitude, longitude}; timezone = IANA zone id. 201 + {id}; 403 non-owner; 400 invalid.
2. GET /api/media/{mediaItemId} — effective captureTimestamp/location + captureTimestampSource/locationSource + activeMetadataOverrides (with sourceValue).
3. DELETE /api/media/{mediaItemId}/metadata-overrides/{metadataClass} — 204 idempotent; 403 non-owner; 404 unknown media.

## Verification

- rtk ./gradlew :apps:api:test — full suite green (locally, post-rebase on origin/main).
- New tests: MetadataOverrideServiceTest (Testcontainers PG: owner/non-owner, invalid values, sourceValue, gated location, revert history + idempotency), MetadataControllerTest (ISSUE-017 regression), TimelineQueryServiceTest detail override/revert/gating tests, contract path assertion.

Closes ISSUE-017. References FR-041/SC-019 (specs/001-v1-baseline).

## What<br><br>Makes owner metadata overrides (capture date + GPS location) work end-to-end on the backend with revert support — implements spec **FR-041 / SC-019** and fixes **KNOWN_ISSUES ISSUE-017** (high/open: `MetadataController` passed `ownerId=null` into `createOverride`, so `requireOwner` denied every override call).<br><br>## Changes<br><br>- **Owner resolution (ISSUE-017)**: create and the new DELETE revert resolve the owner via `LocalAuthService.currentSession(authentication).ownerId()` (MediaController pattern); unknown media now 404s instead of 500.<br>- **Server-side validation** (400 ProblemDetail via existing `ApiExceptionHandler`): capture_time ISO-8601 instant within 1800-01-01..now+1y; location lat −90..90 / lon −180..180; timezone must be an IANA zone id (offsets rejected); favorite boolean; rating number; title/description strings.<br>- **Media detail applies overrides**: `GET /api/media/{id}` returns effective `captureTimestamp`/`location` (active override wins, else extracted) with the existing shareLocation gate preserved (a gated-out location override never leaks coordinates); new fields `captureTimestampSource` / `locationSource` (`extracted` | `user_override`, null when no value/gated) and `activeMetadataOverrides` (`{metadataClass, value, sourceValue, updatedAt}` — sourceValue powers the revert UI, SC-019). `effectiveMetadata` is kept (apps/web favorite) and now carries natural JSON values.<br>- **NEW `DELETE /api/media/{id}/metadata-overrides/{metadataClass}`**: reverts the active override (replaced_at set, provenance annotated `revertedAt`/`revertedBy`, history retained; effective value falls back to extracted). Idempotent 204; 403 non-owner; 404 unknown media; 400 unknown class.<br>- **V157**: partial index on active capture_time/timezone/location overrides for the detail/suggestion joins (V005 covers title/description only, V144 favorite only). No destructive schema changes.<br>- **Contract**: `core-api.openapi.yaml` updated to match (request value shapes, `{id}` 201 response, DELETE path, new MediaDetail fields); contract test asserts the new path.<br><br>## API contract (frontend lane builds against this)<br><br>1. `POST /api/media/{mediaItemId}/metadata-overrides` — body `{metadataClass, value}`: capture_time = ISO-8601 instant string; location = `{latitude, longitude}`; timezone = IANA zone id. 201 + `{id}`; 403 non-owner; 400 invalid.<br>2. `GET /api/media/{mediaItemId}` — effective `captureTimestamp`/`location` + `captureTimestampSource`/`locationSource` + `activeMetadataOverrides` (with `sourceValue`).<br>3. `DELETE /api/media/{mediaItemId}/metadata-overrides/{metadataClass}` — 204 idempotent; 403 non-owner; 404 unknown media.<br><br>## Verification<br><br>- `rtk ./gradlew :apps:api:test` — full suite green (locally, post-rebase on origin/main).<br>- New tests: `MetadataOverrideServiceTest` (Testcontainers PG: owner/non-owner, invalid values, sourceValue, gated location, revert history + idempotency), `MetadataControllerTest` (ISSUE-017 regression), `TimelineQueryServiceTest` detail override/revert/gating tests, contract path assertion.<br><br>Closes ISSUE-017. References FR-041/SC-019 (specs/001-v1-baseline).
ISSUE-017: MetadataController passed ownerId=null into createOverride, so
AuthorizationService.requireOwner denied every call (feature dead, fail-closed).
Both create and the new DELETE revert now resolve the owner via
LocalAuthService.currentSession(authentication).ownerId(), the MediaController
pattern.

MetadataOverrideService gains server-side validation per the shared contract:
capture_time ISO-8601 instant within 1800-01-01..now+1y, location lat/lon
bounds, timezone must be an IANA zone id (offsets rejected), favorite boolean,
rating number, title/description strings; violations are IllegalArgumentException
→ 400 ProblemDetail. Unknown media now maps to 404 (NoSuchElementException)
instead of a 500.

revertOverride (FR-041/SC-019) supersedes the active row (replaced_at set,
provenance annotated with revertedAt/revertedBy) so history stays inspectable
while the effective value falls back to extracted; it is idempotent.

V157 adds the partial index for active capture_time/timezone/location lookups
that the detail path and the album-suggestion query need (V005 covers only
title/description, V144 only favorite).
GET /api/media/{id} now returns effective values: captureTimestamp and
location honor the active owner override (COALESCE join over metadata_overrides,
the AlbumSuggestionEligibleMediaQueryService pattern) and fall back to the
extracted columns. The existing shareLocation gate is refactored into a single
location_visible lateral so it gates effective coordinates once; a gated-out
location override never leaks coordinates (also excluded from
activeMetadataOverrides).

New MediaDetail fields per the shared contract:
- captureTimestampSource / locationSource: extracted | user_override (null
  when no value or gated)
- activeMetadataOverrides: {metadataClass, value, sourceValue, updatedAt} with
  the extracted source value so the revert UI can show the original (SC-019)

effectiveMetadata stays (apps/web reads it for favorite) and is now built from
the same override rows as natural JSON values instead of raw jsonb objects.
- POST /api/media/{id}/metadata-overrides: value is now a per-class shape
  (string | number | boolean | object) instead of object-only; the unused
  supersedesMetadataRecordId is dropped (supersede is server-side); the 201
  response matches the actual {id} body (CreateMetadataOverrideResponse)
  instead of the never-returned MetadataRecord.
- NEW DELETE /api/media/{id}/metadata-overrides/{metadataClass}: revert, 204
  idempotent, 403 non-owner, 404 unknown media, 400 unknown class.
- MediaDetail: captureTimestampSource, locationSource, activeMetadataOverrides
  (with sourceValue for the revert UI); captureTimestamp/location documented as
  effective values.
test(api): metadata override create/revert/detail coverage
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 5s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
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 plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (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 5m40s
eb6dc4ddc1
- MetadataOverrideServiceTest (Testcontainers PG): owner create success,
  non-owner 403, invalid lat/lon/date/timezone 400 without persisting, active
  overrides with extracted sourceValue, gated location omission, revert keeps
  history + provenance revert markers + idempotency, re-create after revert,
  unknown media 404.
- MetadataControllerTest: owner resolution regression for ISSUE-017 (session
  owner passed to service, never null), 403 propagation, revert wiring.
- TimelineQueryServiceTest: detail applies overrides with sources + sourceValue,
  revert falls back to extracted with history rows retained; gated viewers
  never see the location override while capture overrides still apply.
docs: archive ISSUE-017 (metadata override owner resolution fixed)
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 / Android unit tests and debug APK (push) Has been skipped
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 plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (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 6m17s
6585c30a02
docs: reference PR#1095 in archived ISSUE-017 entry
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 / Android unit tests and debug APK (push) Has been skipped
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 plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (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 1m57s
d74409c362
chris merged commit 6bc84c2615 into main 2026-10-10 22:02:11 +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!1095
No description provided.