Landlord API — Slice 3: Media Sync
A declarative PUT keeps a property's photo gallery in step with a listing site: each Source owns only its own photos, fetches run outside the database lock behind a public-IP-only SSRF guard, and every URL gets its own result. API keys can also upload and list ownership proofs, but never download them.
- Predecessor Slice 2 — Idempotent Sync (2026-09-22)
- New ADR 0065
- Status Approved
Slice 3 lets a landlord's sync job keep a property's photo gallery in step with a listing site through one declarative PUT, and lets an API key upload (never download) ownership proofs. Each Source owns only its own photos, fetches run outside the database lock behind a strict public-IP SSRF guard, and every URL gets its own result.
Grill outcome
Grilled on 2026-09-23. Every decision is settled and listed in the grill decisions table (§3.5). The ownership rule (D38, D39, Q5, Q1) is recorded in ADR-0065.
Why
Slice 2 made property and listing writes repeatable. Photos were deliberately left out: publishing an upload shape before knowing how sync works would have frozen the wrong contract.
A listing without photos does not rent. Slice 3 lets a sync job keep a gallery in step with the source site, and lets a key upload the ownership document that unblocks submission.
What is already here
Verified in the repository on 2026-09-23.
| Fact | Evidence | Matters because |
|---|---|---|
PhotoRepository has no delete — only Create, CountByProperty, ListByProperty, UpdatePosition | ports.go:123-135 | a declarative gallery must remove photos; the panel cannot delete a photo either |
PhotoStore is Put and PublicURL only, "no signed URLs" | ports.go:141-150 | presign would need a port change |
The shared Storage port is deliberately minimal: "no signed URLs, listing, or stat surface" | storage.go:28 | D37 avoids touching it; no orphan sweeper without a list call |
Storage.RemoveObject already exists | storage.go:24 | delete is a one-line wrapper |
| SeaweedFS is reached over S3 with AWS4-HMAC-SHA256 | seaweedfs_storage_test.go:50 | presign is feasible later |
| 10 photos per property, 5 MB each, jpeg/png only | ports.go:71-74 | the cap makes synchronous fetching viable (D40) |
rental_property_photos has position and deleted_at, no hash and no URL | migrator_rental.go:79-88 | new columns needed |
The panel's SetPosition swap has a known race; no unique (property_id, position) | photo.go:55-64 | pre-existing, flagged not fixed |
SetPosition locks the property row FOR UPDATE; Upload takes no lock (count, then insert) | photo.go:66-110, photo.go:153-200 | a concurrent upload and PUT could exceed the cap (Q2) |
| The photo cap maps to 400, on purpose: "every other rental business rejection uses 400" | property_handler.go:398-410 | no new 409 (Q4) |
A global 30-second TimeoutMiddleware wraps every request | cmd/server/main.go:382 | the fetch budget must leave room for store and apply (Q15) |
| v1 has a per-key hourly rate limit | v1_routes.go:46 | bounds outbound fetch volume (Q26) |
IdempotencyUseCase.Execute runs the work in one transaction and replays by re-reading | idempotent_executor.go:51-183 | why Q3 is not trivial |
ProofUseCase.Upload already validates pdf/jpeg/png and the 5 MB cap | proof.go:74-157 | the proofs API is mounting, not building |
ProofRepository has no delete; CountByProperty counts rows with verified_at set | proof_repository.go:78-85 | the proof cap (Q16) is a lifetime cap per property |
verified_at on a proof means "the object write completed", not "a human checked ownership" | proof_repository.go:123-127 | an API upload adds no new fraud surface |
| Outbox, relay and scheduler exist | internal/shared/infrastructure/outbox/ | considered for async fetch, not needed under D40 |
Decisions
Slice 2 numbering continues.
| # | Decision | Chosen |
|---|---|---|
| D37 | Which upload transports ship now | Fetch-by-URL now; presigned upload deferred to Slice 5 |
| D38 | What a declarative PUT owns | Only the caller's own Source (source = X, any origin channel). Unowned photos untouched |
| D39 | Ordering | A Source orders its own block, appended after photos it does not own |
| D40 | Fetch mode | In-request, parallel, outside any transaction. No worker, no status model, no retry table |
| D41 | SSRF policy | Connect only to public IPs, checked on the resolved address, with connection pinning |
| D42 | What the hash and URL buy | Conditional-request skip, replace on change (new key), one copy per property. No cross-property object sharing |
| D43 | Proofs over the API | Upload and list metadata. Never download, for any key |
| D44 | Transports in v1 | Multipart for photos and proofs; URL fetch for photos only |
D37 · Fetch-by-URL now, presign later
Ship fetch-by-URL; defer presigned upload to Slice 5.
Presign and fetch-by-URL solve the same problem for different callers. A listing site already hosts its images at URLs, so fetch-by-URL is one call and needs no upload code from the integrator. Presign mainly serves a CLI pushing local files, which is Slice 5 — building it there gives it a real caller to test against. Deferring it also leaves the deliberately minimal Storage port untouched.
Rejected: both transports in one slice — three delivery paths plus gallery semantics; highest risk of the slice stalling half-done.
D38 · A PUT owns only its own Source's photos
A sync job must never destroy a choice a human made.
Scoping the declaration to the caller's own Source mirrors Slice 2's D14, where each Source keeps its own external_ref. Ownership is decided by source alone, never by origin_channel (Q5): a Slice 5 CLI writing with origin_channel = 'cli' still owns the photos it declared. A photo with source = NULL is unowned: no sync can remove it.
Rejected: PUT replaces the whole gallery; opt-in "API manages all photos" flag; ownership by origin_channel = 'api' AND source = X.
D40 · In-request fetch, outside the transaction
Fetch in parallel inside the request, with no transaction open.
A property caps at 10 photos. Five parallel fetches with a 10-second per-URL timeout finish in about 20 seconds worst case, inside the 20-second fetch budget, leaving about 10 seconds of the global 30-second middleware for storing and the locked apply (Q15). Because the PUT is declarative and idempotent, retrying a failed photo is sending the same PUT again — no worker, no per-photo status, no polling endpoint, no retry policy, no pending photo leaking into the public gallery. Fetching never runs inside the database transaction (Q2): holding a row lock and a connection while waiting on a stranger's CDN would block the panel for up to 20 seconds.
Rejected: background worker with per-photo status; fetch inside the locked transaction.
Rejected alternatives
| # | Rejected | Why |
|---|---|---|
| D37 | Both transports in one slice | Three delivery paths plus gallery semantics; highest risk of the slice stalling half-done |
| D38 | PUT replaces the whole gallery | A landlord who uploads by hand loses those photos on the next sync, with no warning |
| D38 | Opt-in "API manages all photos" per property | A flag, a UI toggle and two behaviours to test, for a case nobody has asked for |
| D38 | Ownership by origin_channel = 'api' AND source = X | A cli writer could never remove its own photos (Q5) |
| D39 | Absolute positions, last writer wins | Two sources then shuffle each other nightly with no human involved |
| D39 | Panel may hide, move or delete owned photos | Sync must remember human overrides: new schema and rules. Additive later (Q1) |
| D39 | A separate is_cover column | Cleanest model, but costs a migration and a panel UI change to solve a problem D39 already solves |
| D40 | Background worker with per-photo status | An entire subsystem, justified only if the cap were much higher |
| D40 | Fetch inside the locked transaction | Holds a row lock and a DB connection for up to 20 seconds (Q2) |
| D41 | Domain allowlist per key | Breaks whenever a listing site changes CDN hostname, and every landlord must configure it |
| D41 | A fixed blocklist of private ranges | Misses 0.0.0.0/8, fe80::/10, IPv4-mapped IPv6, NAT64 and others (Q6) |
| D41 | Drop bad IPs from a mixed DNS answer and dial the rest | A real CDN never mixes private answers in; a mix is an attack or a misconfiguration (Q21) |
| D42 | Cross-property object sharing with refcounting | A delete that frees an object another property still displays is a visible bug |
| D42 | Unique index on (property_id, sha256) | If a panel photo has the same bytes, every sync hard-fails forever |
| D42 | Overwrite the same storage key on change | CDNs and browsers keep serving the old image (Q7) |
| D43 | Full proof access including download | A leaked key becomes an identity-document leak |
| D44 | Fetch proofs by URL too | We would store a title deed in the private bucket on an API caller's say-so, after it passed through a third party |
| — | New 409 photo_limit_exceeded | The existing cap already maps to 400; one limit must not have two answers (Q4) |
| — | Orphan sweeper now | Needs a list call on the minimal storage port; crashes in the window are rare (Q18) |
Grill decisions (2026-09-23) — Q1–Q26, F1–F6 and where each is applied
| # | Decision | Where |
|---|---|---|
| Q1 | Owned photos are read-only in the panel: no move, no delete, enforced by the server, and each shows a message explaining why. The cover is always an unowned photo when one exists | §4.4, §10, §12, ADR-0065 |
| Q2 | Three phases: plan, fetch outside any transaction, then locked re-read, cap check and apply. Unused objects removed. Multipart takes the same lock | §4.2, §4.7, §8.2 |
| Q3 | Idempotency-Key accepted but ignored on the gallery PUT; documented in rental-v1.yaml | §8.4 |
| Q4 | Existing 400 cap mapping on PUT and POST | §4.6, §8.3 |
| Q5 | Mine = source = X, any origin channel; source = NULL is unowned | §3.2, §4.2 |
| Q6 | Public-IP-only pinning; unmap IPv4-mapped; reject CGNAT, NAT64, benchmark; Proxy: nil | §5.2 |
| Q7 | Changed bytes get a new key; old objects removed after commit, best effort | §4.3, §6.5 |
| Q8, Q10 | Response = whole gallery in the GET photos shape, plus one result per input URL in request order | §4.5 |
| Q9 | Changed bytes that collide with a photo I do not own: remove my row, keep theirs, duplicate_image | §4.3 |
| Q11 | Before cross-owner dedupe, rebind a dropped row of mine with the same hash to the new URL. Query strings kept intact | §4.3 |
| Q12 | The same URL twice in one PUT: 400 before any fetch | §4.1 |
| Q13 | [] clears only this Source's photos | §4.1 |
| Q14 | A failed refresh keeps the existing row and reports the reason | §4.3 |
| Q15 | Fetch phase capped at 20 s under the global 30 s middleware | §5.2, §5.4 |
| Q16 | At most 10 proofs per property, panel and API alike, existing 400 style | §7 |
| Q17 | Apply re-plans under the lock using already-fetched objects; last commit wins | §4.2 |
| Q18 | Orphans logged; cleanup job is a follow-up; no sweeper now | §6.5, §11 |
| Q19 | Multipart: Put before the lock, then locked cap check and insert; cleanup on failure | §8.2 |
| Q20 | Multipart has no source in this slice | §8.2 |
| Q21 | Any non-public resolved IP rejects the URL | §5.2 |
| Q22 | Closed results status vocabulary; duplicate_image is not a failure | §5.5 |
| Q23 | 200 even if every URL fails | §4.5 |
| Q24 | Replace updates width and height | §6.4 |
| Q25 | source exposed to the owner panel and v1 key; source_url internal; public JSON unchanged | §8.5 |
| Q26 | Existing key rate limit; ceiling documented in a ponytail: comment | §5.4 |
| F1 | Duplicate URLs re-download on every sync; bounded cost accepted | §4.3, §5.3 |
| F2 | Inside one Source, the earlier URL in the array wins | §4.3 |
| F3 | The pre-fetch cap check counts declared URLs | §4.6 |
| F4 | Cleanup runs on context.WithoutCancel with a short deadline | §6.5 |
| F5 | Non-HTTPS redirects rejected | §5.2 |
| F6 | Missing/null vs []; 2048-char URL limit; photo_id on a kept failed refresh; cap code pinned by golden | §4.1, §4.5, §8.3 |
The gallery PUT
The request
PUT /api/v1/rental/properties/:id/photos
{ "source": "propertyguru",
"photos": [ {"url": "https://cdn.pg.com/a.jpg"},
{"url": "https://cdn.pg.com/b.jpg"} ] }
Array order is the order. There is no position field.
Request validation, all before any fetch:
| Case | Result |
|---|---|
source missing | 400 validation_failed |
photos missing or null | 400 validation_failed |
photos: [] | valid: removes every photo owned by this Source, nothing else (Q13) |
| The same URL twice | 400 validation_failed (Q12) |
| A URL longer than 2048 characters | 400 validation_failed (F6) |
| More declared URLs than the cap allows | 400, the existing cap error (§4.6) |
URLs are compared exactly as sent. Query strings are part of the URL and are never normalised (Q11).
Reconciliation
Three phases (Q2). Only the last one holds a transaction.
- Plan (short read, no lock)
Check owner and key mode as
Uploaddoes. Load the live photos. Split into mine (source = <declared>, any origin channel) and others. Run the cap check (§4.6). Decide, per URL, what to fetch. - Fetch (no transaction)
Fetch in parallel (§5), hash, and store new objects under new keys.
- Apply (property row locked
FOR UPDATE)Re-read the live photos and plan again from the fresh read, reusing objects already fetched — never fetch again (Q17). Re-check the cap; if it now fails, return 400, apply nothing, and remove the fetched objects. Otherwise apply the per-URL rules, delete any of mine whose URL is absent from the list, and rewrite positions: others first, then mine in array order.
- Cleanup (after commit)
Remove objects that are no longer referenced (§6.5).
Two PUTs from the same Source at once: the last to commit wins. Each is a full declaration, so that is correct.
Per-URL rules
Matching runs in this order.
| Situation | Action | Status |
|---|---|---|
URL already mine, source returns 304 | keep, no download | unchanged |
| URL already mine, same hash | keep | unchanged |
| URL already mine, different hash | store under a new key, update the row in place, keep position (Q7) | replaced |
| URL already mine, refresh fails (timeout, 5xx, …) | keep the existing row and position (Q14) | the failure reason, with photo_id |
| URL not mine yet, hash matches a row of mine whose URL is being dropped | rebind that row to the new URL; keep key and position (Q11) | unchanged |
| URL not mine yet, new bytes | fetch, validate, store, insert | created |
| Two URLs of this Source end up with the same hash | the earlier URL in the array keeps the row; the later URL's row, if any, is removed (F2) | later URL: duplicate_image |
| Bytes already present under a photo this Source does not own | do not insert; if the URL had a row of mine, remove it and keep the other photo (Q9) | duplicate_image |
| New URL fails | nothing stored | the failure reason |
A duplicate_image URL produces no row of its own. The image is in the gallery, so nothing is wrong, but the caller is told rather than left guessing why its list and the gallery differ.
Ordering (D39)
The unowned block never moves, so the landlord's cover photo survives every sync.
Each owned photo shows a read-only message, so the missing controls are explained rather than just absent. The text is a translated panel message; {source} is the photo's Source identifier, shown as stored.
Read-only: managed by propertyguru. Changes here would be overwritten by the next sync. Update the source and sync again.
If a feed stops for good, its photos stay read-only. Any key of the landlord can still remove them by sending photos: [] for that Source (Q13), because a Source is declared by the caller, not bound to a key.
Response
A dead URL does not fail the request. Everything that can be applied is applied.
200 {
"photos": [ ... the whole gallery, final order, same shape as GET .../photos ... ],
"results": [ { "url": "https://cdn.pg.com/a.jpg", "status": "unchanged", "photo_id": "…" },
{ "url": "https://cdn.pg.com/b.jpg", "status": "fetch_timeout" } ]
}
resultshas exactly one entry per input URL, in request order (Q10).photo_idis present whenever a row exists for that URL, including a kept row whose refresh failed (F6).- The status vocabulary is closed (§5.5).
- The response is 200 even when every URL fails (Q23). The request was valid and
resultstells the full story. - Retrying is sending the same PUT again. Already-stored URLs cost one conditional request each.
- Deletions still happen when a fetch fails: removal is decided by the list, not by the download. A URL still in the list is never removed because its refresh failed.
The cap
Locking and positions
- The apply phase runs inside the existing locked-transaction pattern (
GetByIDForUpdate), and positions are rewritten with a singleUPDATE ... FROM (VALUES ...). - Multipart upload takes the same property lock for its cap check and insert (Q2, §8.2), so a PUT and an upload cannot together exceed the cap.
- No new unique constraint is added. A partial unique index cannot be deferred in Postgres, and the row lock is the real guard.
- The panel's
SetPositionswap race is pre-existing and untouched here.
Fetching safely
The rules (D41)
| Rule | Why |
|---|---|
https only | plain HTTP leaks and is trivially spoofed |
| Resolve DNS ourselves and check every resolved IP | the hostname tells us nothing |
| If any resolved IP is not public, reject the URL (Q21) | a mixed answer is an attack or a misconfiguration |
| Connect to the checked IP, not the hostname | otherwise DNS can change between check and connect |
Allowed: unmap IPv4-mapped IPv6 first, then IsGlobalUnicast() && !IsPrivate() | an allowlist of "public" cannot miss a range the way a blocklist can |
Also rejected: 100.64/10 (CGNAT), 198.18/15 (benchmark), 64:ff9b::/96 (NAT64) | public-looking ranges that reach internal networks |
Proxy: nil on the transport | HTTP_PROXY would bypass the pinned dialer completely |
Max 3 redirects, re-check every hop; any non-https hop rejected (F5) | one unchecked hop is enough to land anywhere |
Content-Type must be jpeg or png | matches the existing upload rule |
| Confirm by magic bytes, not the header | a header is whatever the server claims |
| Cut the stream at 5 MB | Content-Length can lie |
| 10 s per URL, 20 s for the whole fetch phase (Q15) | leaves room under the global 30 s middleware |
| Never send our auth headers or cookies | the request carries nothing of ours |
Pinning is implemented with a custom DialContext on the HTTP client, so the check and the connection cannot disagree. Redirect rules live in CheckRedirect.
Conditional requests (D42)
Each owned photo stores source_url, etag, last_modified and sha256.
GET https://cdn.pg.com/a.jpg
If-None-Match: "abc123"
If-Modified-Since: Tue, 16 Sep 2026 03:00:00 GMT
304 -> keep the photo, no download
200 -> hash the body
same hash -> keep
different hash -> store under a new key, update the row in place
A nightly sync of ten unchanged, owned photos costs ten small requests instead of fifty megabytes. duplicate_image URLs are the exception: they have no row, so they download in full every time (F1).
Parallelism and volume
- At most 5 fetches at once. With a cap of 10 photos the worst case is two rounds of 10 seconds, inside the 20-second fetch budget. URLs not finished when the budget runs out report
fetch_timeout. - Outbound volume is bounded by the existing per-key hourly rate limit times the 10-URL cap (Q26).
ponytail:one PUT counts as one request however many URLs it fetches; charge a PUT as N units if abuse is ever reported.
Result status vocabulary
Every results entry carries exactly one of these, never a raw error string — a raw error would leak our network shape to the caller. The list is closed and documented as an enum in rental-v1.yaml (Q22).
Success
4created- a new photo was stored
unchanged304, same hash, or a rebound rowreplaced- new bytes, new key, same position
duplicate_image- bytes already in this gallery; no row of its own. Not a failure
Failure
7url_not_https- scheme refused, including on a redirect hop
url_blocked- a resolved IP is not public
too_many_redirects- more than 3 hops
fetch_timeout- past 10 seconds, or the fetch budget ran out
fetch_failed- connection refused, 4xx, 5xx
unsupported_media_type- not jpeg or png by magic bytes
too_large- body exceeded 5 MB
Schema
Changed: rental_property_photos
| Column | Type | Why |
|---|---|---|
origin_channel | TEXT NOT NULL DEFAULT 'panel' | panel | api | cli, matching Slice 2's D34. Records how, never who owns |
source | TEXT | the owning Source; NULL = unowned |
source_url | TEXT | the reconciliation key. Internal: never returned by any route (Q25) |
sha256 | TEXT | change detection and per-property dedupe |
etag | TEXT | conditional requests |
last_modified | TEXT | stored as the raw header value |
- No new indexes
- The reconciliation loads all of a property's live photos anyway, and the cap is 10. URL matching, hash dedupe and partitioning all happen in memory.
- No
is_testcolumn - Photos cascade from their property, and Slice 2 already filters properties out of the public path. Slice 2's purge removes a test property's photos with it.
PhotoRepository gains three methods
| Method | Why |
|---|---|
Delete(ctx, photoID) | soft delete; the port has none today |
UpdatePositions(ctx, propertyID, pairs) | one statement inside the locked transaction |
UpdateContent(ctx, photoID, key, sha256, etag, lastModified, width, height) | replace or rebind in place, keep position. Width and height from image.DecodeConfig, as Upload does (Q24) |
A rebind also updates source_url. PhotoStore gains Remove(ctx, key), a one-line wrapper over the existing Storage.RemoveObject. The shared storage port is unchanged.
Object cleanup
| When | What is removed |
|---|---|
| After a successful commit | old keys of replaced photos, objects of deleted photos, fetched objects the apply phase did not use (Q7, Q2) |
| After a failed apply (cap re-check, DB error) | every object fetched by this request |
| Multipart upload fails its locked cap check | the object it just put (Q19) |
Cleanup is best effort. It runs on context.WithoutCancel(ctx) with a short deadline (about 5 s), so it still runs after the request context is cancelled by a timeout (F4). A failed removal is logged and the orphan left in place.
Proofs
ProofUseCase.Upload already validates pdf/jpeg/png and the 5 MB cap. This slice mounts it.
POST /api/v1/rental/properties/:id/proofs
multipart, scope proofs:write
-> 201 { id, created_at }
GET /api/v1/rental/properties/:id/proofs
scope proofs:read
-> [ { id, created_at } ]
The list returns id and date only. No URL, no filename, no bytes.
The proof cap (Q16)
A property holds at most 10 proofs. The same rule applies to the panel and the API, because both call ProofUseCase.Upload. The 11th upload is rejected with a 400 in the existing proofRejected style, naming the limit, like the photo cap. Without it, a buggy loop or a leaked key could upload without end into the private bucket.
The check fits the existing upload flow (proof.go:74-157) instead of changing it:
- Early check
Before any bytes are stored, next to the existing admin-hold check. At 10 proofs, reject. This is what stops a looping key from filling the bucket.
- Authoritative check
Inside the existing locked step that marks the proof verified (
applyReviewedEdit). At 10, reject and do not verify.
A rejection at step 2 leaves an unverified row and its object, exactly like the existing failures of that step. The row names the key, so nothing is untracked, and an unverified proof is never evidence. Only a race between two uploads reaches step 2.
Contract
New v1 endpoints
| Method | Path | Scope | Kind |
|---|---|---|---|
PUT | /api/v1/rental/properties/:id/photos | media:write | declarative |
POST | /api/v1/rental/properties/:id/photos | media:write | multipart |
POST | /api/v1/rental/properties/:id/proofs | proofs:write | multipart |
GET | /api/v1/rental/properties/:id/proofs | proofs:read | metadata only |
GET .../photosshipped in Slice 1.- No
DELETEendpoint: the declarative PUT removes its own photos, and an unowned photo is deliberately not deletable by a key. - No position endpoint: order is derived from the PUT's array (D39).
Multipart photo uploads have no source
POST /api/v1/rental/properties/:id/photos
-> 201, appended, origin_channel = 'api', source NULL
A photo uploaded this way is owned by no Source (Q20). It behaves like a panel photo, and a sync can never delete it. That is the honest consequence of D38, and it is the safe one. Slice 5 decides whether multipart may name a Source, together with presign.
Order of work (Q19), shared by the panel and v1 because both call Upload:
- Validate type and size.
- Put the object (no lock held).
- Lock the property row, count, check the cap, insert.
- If the cap check fails, remove the object (§6.5).
Errors
No new error code. The photo cap returns the existing 400 rejection on both the PUT and the multipart POST (Q4). Its exact v1 code is pinned by the golden test (F6). Per-URL problems are not errors: they appear in results and the request is still a 200.
Idempotency-Key
Accepted on the gallery PUT, and ignored (Q3). A request that sends it is not rejected, and the response never carries Idempotent-Replay. rental-v1.yaml states this on the endpoint.
IdempotencyUseCase.Execute runs the work in one transaction and replays by re-reading, not by re-running. Wiring this PUT through it would put the fetch back inside a transaction (contradicting D40), and a retry with the same key would never re-fetch failed URLs. The declarative PUT is already safe to repeat: sending it again is the retry.
Multipart POST photos and POST proofs keep Slice 2's D36 behaviour.
Field exposure (Q25)
| Field | Owner panel | v1 key API | Public JSON |
|---|---|---|---|
source | yes | yes | no |
source_url | no | no | no |
The public photo JSON is unchanged, and its golden test stays as it is. Raw source URLs can carry signed query tokens; the caller already knows its own URLs from results.
Testing
| What | Kind | Fails when |
|---|---|---|
| Scheme refused | unit | http:// is fetched |
| Non-public ranges | unit, table-driven | any private, loopback, link-local, metadata, CGNAT, benchmark or NAT64 IP connects |
| IPv4-mapped IPv6 | unit | ::ffff:169.254.169.254 connects |
| Mixed DNS answer | unit, stub resolver | one public and one private answer is not rejected |
| DNS rebinding | unit, stub resolver | a public answer then a private connect succeeds |
| Proxy environment | unit | HTTP_PROXY set routes the fetch around the pinned dialer |
| Redirect to a private IP | unit | a hop past the first is unchecked |
Redirect to http:// | unit | a non-HTTPS hop is followed |
Lying Content-Type | unit | a non-image passes on the header alone |
Lying Content-Length | unit | more than 5 MB is buffered |
| Conditional 304 | unit | a 304 re-downloads or drops the photo |
| Hash changed at the same URL | unit | the photo moves, or keeps its old key or old dimensions |
| Rotated CDN URL, same bytes | unit | the photo is deleted or re-inserted instead of rebound |
| Two own URLs, same hash | unit | the later URL keeps the row |
| Refresh fails for a kept URL | unit | the row is removed or photo_id is missing |
| Request validation | unit | missing source, missing/null photos, a repeated URL or a 2049-char URL is accepted |
| Cleanup after timeout | unit | removal is skipped because the request context is cancelled |
| Bytes already in the gallery | integration | a second row is inserted, or duplicate_image is missing |
| Panel photos untouched | integration | a sync PUT deletes an unowned photo |
| Two sources coexist | integration | one Source's PUT removes the other's |
| Empty list | integration | [] touches anything but this Source's photos |
| Ordering | integration | the unowned block moves |
| Panel owned-photo controls | render | an owned photo offers move or set-cover, or lacks its read-only message |
Owned photo SetPosition | integration | an owned photo moves, or an unowned photo swaps into the owned block |
| Cap check precedes fetch | integration | a rejected PUT still downloads, or returns anything but the existing 400 |
| Concurrent upload and PUT | integration | the gallery ends with more than 10 photos |
| Partial failure | integration | one dead URL loses the whole gallery, or the response is not 200 |
| Results shape | integration | results is not one entry per URL in request order |
| Proof content unreachable | integration | any v1 route returns proof bytes |
| Proof cap | integration | an 11th proof is verified, or its bytes are stored when the early check could see the cap, through the panel or the API |
Idempotency-Key on the PUT | integration | a repeated key replays instead of re-running, or the header is rejected |
| Public JSON shape | golden | photo fields renamed or missing, or source / source_url appear |
| Cap error code | golden | the v1 cap code changes |
Integration tests follow the existing recipe: pg-test on :55432, migrations run from a directory with no .env, because backend/go/.env points at UAT.
Tasks
| # | Task | Verify |
|---|---|---|
| 1 | Re-record the rental test baseline | numbers written down |
| 2 | Migration: photo columns | migration test |
| 3 | PhotoRepository Delete, UpdatePositions, UpdateContent (with width/height) | unit |
| 4 | PhotoStore.Remove wrapper and best-effort cleanup helper (WithoutCancel) | unit |
| 5 | Safe fetcher: public-only pinning, Proxy: nil, redirects, magic bytes, size cut | unit |
| 6 | Conditional request and hash comparison | unit |
| 7 | Gallery reconciliation use case: plan, fetch, locked apply | unit |
| 8 | PUT photos handler, validation and response shape | integration |
| 9 | Upload takes the property lock; SetPosition rejects owned photos and moves into the owned block; multipart POST photos in v1 | integration |
| 10 | Proof cap: early check plus check in the locked verify step; proofs POST and GET in v1 | integration |
| 11 | rental-v1.yaml (status enum, field exposure, Idempotency-Key ignored on the PUT) and golden re-pin | golden |
| 12 | Panel: on owned photos, hide the move and cover controls and show the translated read-only message | render test |
| 13 | End-to-end two-source gallery | integration |
Out of scope
- Presigned uploads and the CLI (Slice 5).
- Outbound webhooks (Slice 4).
- Cross-property object sharing (rejected, D42).
- Fixing the panel's
SetPositionrace (pre-existing, flagged). - An orphan-object sweeper (follow-up, Q18).
- Per-URL rate-limit cost (Q26).
- A "known duplicate" record (F1).
- Multipart
source(Q20).
Open risks
| Risk | Mitigation |
|---|---|
| SSRF through a hostname that resolves differently at connect time | Connection pinning to the checked public IP, Proxy: nil, every redirect hop re-checked; rebinding and proxy tests guard it |
| A slow source holds the request open | 10 s per URL, 20 s fetch budget, 5 at a time; fetch holds no lock |
| A sync silently deletes a landlord's own photos | D38 scopes deletion to the caller's own Source; an integration test asserts unowned photos survive |
| A CDN rotates signed URLs every night | Rebinding by hash keeps the photo (Q11) |
| A multipart-uploaded API photo can never be removed by its uploader | Accepted. It is unowned, so no key removes it, and the panel has no photo delete today. Panel delete is a separate feature |
| Duplicate URLs download in full on every sync | Accepted, bounded by the 10-photo cap (F1) |
| Orphaned objects after a crash or failed removal | Logged; cleanup job is a follow-up (Q18) |
| Outbound fetches used to hit a third party | Existing per-key hourly limit × 10-URL cap (Q26) |
| A leaked key exfiltrates identity documents | No v1 route returns proof content at all (D43) |
| A leaked key fills the private bucket with proofs | 10-proof cap per property (Q16) |
| A landlord hits the lifetime proof cap | Accepted; no proof delete exists yet, an admin resolves it |