中文版

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

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

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.

  • StatusApproved after grill, ready for implementation plan
  • Areabackend/go, frontend/solidstart/apps/panel
  • FollowsSlice 1 Foundation (PR #139), Slice 2 Idempotent Sync
  • New ADRADR-0065 source-scoped gallery ownership
  • DecisionsD37–D44 plus grill Q1–Q26, F1–F6
  • Out of scopePresign + CLI (Slice 5), webhooks (Slice 4)

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.

FactEvidenceMatters because
PhotoRepository has no delete — only Create, CountByProperty, ListByProperty, UpdatePositionports.go:123-135a declarative gallery must remove photos; the panel cannot delete a photo either
PhotoStore is Put and PublicURL only, "no signed URLs"ports.go:141-150presign would need a port change
The shared Storage port is deliberately minimal: "no signed URLs, listing, or stat surface"storage.go:28D37 avoids touching it; no orphan sweeper without a list call
Storage.RemoveObject already existsstorage.go:24delete is a one-line wrapper
SeaweedFS is reached over S3 with AWS4-HMAC-SHA256seaweedfs_storage_test.go:50presign is feasible later
10 photos per property, 5 MB each, jpeg/png onlyports.go:71-74the cap makes synchronous fetching viable (D40)
rental_property_photos has position and deleted_at, no hash and no URLmigrator_rental.go:79-88new columns needed
The panel's SetPosition swap has a known race; no unique (property_id, position)photo.go:55-64pre-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-200a 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-410no new 409 (Q4)
A global 30-second TimeoutMiddleware wraps every requestcmd/server/main.go:382the fetch budget must leave room for store and apply (Q15)
v1 has a per-key hourly rate limitv1_routes.go:46bounds outbound fetch volume (Q26)
IdempotencyUseCase.Execute runs the work in one transaction and replays by re-readingidempotent_executor.go:51-183why Q3 is not trivial
ProofUseCase.Upload already validates pdf/jpeg/png and the 5 MB capproof.go:74-157the proofs API is mounting, not building
ProofRepository has no delete; CountByProperty counts rows with verified_at setproof_repository.go:78-85the 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-127an API upload adds no new fraud surface
Outbox, relay and scheduler existinternal/shared/infrastructure/outbox/considered for async fetch, not needed under D40

Decisions

Slice 2 numbering continues.

#DecisionChosen
D37Which upload transports ship nowFetch-by-URL now; presigned upload deferred to Slice 5
D38What a declarative PUT ownsOnly the caller's own Source (source = X, any origin channel). Unowned photos untouched
D39OrderingA Source orders its own block, appended after photos it does not own
D40Fetch modeIn-request, parallel, outside any transaction. No worker, no status model, no retry table
D41SSRF policyConnect only to public IPs, checked on the resolved address, with connection pinning
D42What the hash and URL buyConditional-request skip, replace on change (new key), one copy per property. No cross-property object sharing
D43Proofs over the APIUpload and list metadata. Never download, for any key
D44Transports in v1Multipart 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

#RejectedWhy
D37Both transports in one sliceThree delivery paths plus gallery semantics; highest risk of the slice stalling half-done
D38PUT replaces the whole galleryA landlord who uploads by hand loses those photos on the next sync, with no warning
D38Opt-in "API manages all photos" per propertyA flag, a UI toggle and two behaviours to test, for a case nobody has asked for
D38Ownership by origin_channel = 'api' AND source = XA cli writer could never remove its own photos (Q5)
D39Absolute positions, last writer winsTwo sources then shuffle each other nightly with no human involved
D39Panel may hide, move or delete owned photosSync must remember human overrides: new schema and rules. Additive later (Q1)
D39A separate is_cover columnCleanest model, but costs a migration and a panel UI change to solve a problem D39 already solves
D40Background worker with per-photo statusAn entire subsystem, justified only if the cap were much higher
D40Fetch inside the locked transactionHolds a row lock and a DB connection for up to 20 seconds (Q2)
D41Domain allowlist per keyBreaks whenever a listing site changes CDN hostname, and every landlord must configure it
D41A fixed blocklist of private rangesMisses 0.0.0.0/8, fe80::/10, IPv4-mapped IPv6, NAT64 and others (Q6)
D41Drop bad IPs from a mixed DNS answer and dial the restA real CDN never mixes private answers in; a mix is an attack or a misconfiguration (Q21)
D42Cross-property object sharing with refcountingA delete that frees an object another property still displays is a visible bug
D42Unique index on (property_id, sha256)If a panel photo has the same bytes, every sync hard-fails forever
D42Overwrite the same storage key on changeCDNs and browsers keep serving the old image (Q7)
D43Full proof access including downloadA leaked key becomes an identity-document leak
D44Fetch proofs by URL tooWe 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_exceededThe existing cap already maps to 400; one limit must not have two answers (Q4)
—Orphan sweeper nowNeeds 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
#DecisionWhere
Q1Owned 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
Q2Three 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
Q3Idempotency-Key accepted but ignored on the gallery PUT; documented in rental-v1.yaml§8.4
Q4Existing 400 cap mapping on PUT and POST§4.6, §8.3
Q5Mine = source = X, any origin channel; source = NULL is unowned§3.2, §4.2
Q6Public-IP-only pinning; unmap IPv4-mapped; reject CGNAT, NAT64, benchmark; Proxy: nil§5.2
Q7Changed bytes get a new key; old objects removed after commit, best effort§4.3, §6.5
Q8, Q10Response = whole gallery in the GET photos shape, plus one result per input URL in request order§4.5
Q9Changed bytes that collide with a photo I do not own: remove my row, keep theirs, duplicate_image§4.3
Q11Before cross-owner dedupe, rebind a dropped row of mine with the same hash to the new URL. Query strings kept intact§4.3
Q12The same URL twice in one PUT: 400 before any fetch§4.1
Q13[] clears only this Source's photos§4.1
Q14A failed refresh keeps the existing row and reports the reason§4.3
Q15Fetch phase capped at 20 s under the global 30 s middleware§5.2, §5.4
Q16At most 10 proofs per property, panel and API alike, existing 400 style§7
Q17Apply re-plans under the lock using already-fetched objects; last commit wins§4.2
Q18Orphans logged; cleanup job is a follow-up; no sweeper now§6.5, §11
Q19Multipart: Put before the lock, then locked cap check and insert; cleanup on failure§8.2
Q20Multipart has no source in this slice§8.2
Q21Any non-public resolved IP rejects the URL§5.2
Q22Closed results status vocabulary; duplicate_image is not a failure§5.5
Q23200 even if every URL fails§4.5
Q24Replace updates width and height§6.4
Q25source exposed to the owner panel and v1 key; source_url internal; public JSON unchanged§8.5
Q26Existing key rate limit; ceiling documented in a ponytail: comment§5.4
F1Duplicate URLs re-download on every sync; bounded cost accepted§4.3, §5.3
F2Inside one Source, the earlier URL in the array wins§4.3
F3The pre-fetch cap check counts declared URLs§4.6
F4Cleanup runs on context.WithoutCancel with a short deadline§6.5
F5Non-HTTPS redirects rejected§5.2
F6Missing/null vs []; 2048-char URL limit; photo_id on a kept failed refresh; cap code pinned by golden§4.1, §4.5, §8.3

Fetching safely

The rules (D41)

RuleWhy
https onlyplain HTTP leaks and is trivially spoofed
Resolve DNS ourselves and check every resolved IPthe 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 hostnameotherwise 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 transportHTTP_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 pngmatches the existing upload rule
Confirm by magic bytes, not the headera header is whatever the server claims
Cut the stream at 5 MBContent-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 cookiesthe 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

4
created
a new photo was stored
unchanged
304, same hash, or a rebound row
replaced
new bytes, new key, same position
duplicate_image
bytes already in this gallery; no row of its own. Not a failure

Failure

7
url_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

ColumnTypeWhy
origin_channelTEXT NOT NULL DEFAULT 'panel'panel | api | cli, matching Slice 2's D34. Records how, never who owns
sourceTEXTthe owning Source; NULL = unowned
source_urlTEXTthe reconciliation key. Internal: never returned by any route (Q25)
sha256TEXTchange detection and per-property dedupe
etagTEXTconditional requests
last_modifiedTEXTstored 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_test column
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

MethodWhy
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

WhenWhat is removed
After a successful commitold 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 checkthe 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:

  1. 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.

  2. 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

MethodPathScopeKind
PUT/api/v1/rental/properties/:id/photosmedia:writedeclarative
POST/api/v1/rental/properties/:id/photosmedia:writemultipart
POST/api/v1/rental/properties/:id/proofsproofs:writemultipart
GET/api/v1/rental/properties/:id/proofsproofs:readmetadata only
  • GET .../photos shipped in Slice 1.
  • No DELETE endpoint: 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:

  1. Validate type and size.
  2. Put the object (no lock held).
  3. Lock the property row, count, check the cap, insert.
  4. 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)

FieldOwner panelv1 key APIPublic JSON
sourceyesyesno
source_urlnonono

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

WhatKindFails when
Scheme refusedunithttp:// is fetched
Non-public rangesunit, table-drivenany private, loopback, link-local, metadata, CGNAT, benchmark or NAT64 IP connects
IPv4-mapped IPv6unit::ffff:169.254.169.254 connects
Mixed DNS answerunit, stub resolverone public and one private answer is not rejected
DNS rebindingunit, stub resolvera public answer then a private connect succeeds
Proxy environmentunitHTTP_PROXY set routes the fetch around the pinned dialer
Redirect to a private IPunita hop past the first is unchecked
Redirect to http://unita non-HTTPS hop is followed
Lying Content-Typeunita non-image passes on the header alone
Lying Content-Lengthunitmore than 5 MB is buffered
Conditional 304unita 304 re-downloads or drops the photo
Hash changed at the same URLunitthe photo moves, or keeps its old key or old dimensions
Rotated CDN URL, same bytesunitthe photo is deleted or re-inserted instead of rebound
Two own URLs, same hashunitthe later URL keeps the row
Refresh fails for a kept URLunitthe row is removed or photo_id is missing
Request validationunitmissing source, missing/null photos, a repeated URL or a 2049-char URL is accepted
Cleanup after timeoutunitremoval is skipped because the request context is cancelled
Bytes already in the galleryintegrationa second row is inserted, or duplicate_image is missing
Panel photos untouchedintegrationa sync PUT deletes an unowned photo
Two sources coexistintegrationone Source's PUT removes the other's
Empty listintegration[] touches anything but this Source's photos
Orderingintegrationthe unowned block moves
Panel owned-photo controlsrenderan owned photo offers move or set-cover, or lacks its read-only message
Owned photo SetPositionintegrationan owned photo moves, or an unowned photo swaps into the owned block
Cap check precedes fetchintegrationa rejected PUT still downloads, or returns anything but the existing 400
Concurrent upload and PUTintegrationthe gallery ends with more than 10 photos
Partial failureintegrationone dead URL loses the whole gallery, or the response is not 200
Results shapeintegrationresults is not one entry per URL in request order
Proof content unreachableintegrationany v1 route returns proof bytes
Proof capintegrationan 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 PUTintegrationa repeated key replays instead of re-running, or the header is rejected
Public JSON shapegoldenphoto fields renamed or missing, or source / source_url appear
Cap error codegoldenthe 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

#TaskVerify
1Re-record the rental test baselinenumbers written down
2Migration: photo columnsmigration test
3PhotoRepository Delete, UpdatePositions, UpdateContent (with width/height)unit
4PhotoStore.Remove wrapper and best-effort cleanup helper (WithoutCancel)unit
5Safe fetcher: public-only pinning, Proxy: nil, redirects, magic bytes, size cutunit
6Conditional request and hash comparisonunit
7Gallery reconciliation use case: plan, fetch, locked applyunit
8PUT photos handler, validation and response shapeintegration
9Upload takes the property lock; SetPosition rejects owned photos and moves into the owned block; multipart POST photos in v1integration
10Proof cap: early check plus check in the locked verify step; proofs POST and GET in v1integration
11rental-v1.yaml (status enum, field exposure, Idempotency-Key ignored on the PUT) and golden re-pingolden
12Panel: on owned photos, hide the move and cover controls and show the translated read-only messagerender test
13End-to-end two-source galleryintegration

Out of scope

  • Presigned uploads and the CLI (Slice 5).
  • Outbound webhooks (Slice 4).
  • Cross-property object sharing (rejected, D42).
  • Fixing the panel's SetPosition race (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

RiskMitigation
SSRF through a hostname that resolves differently at connect timeConnection 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 open10 s per URL, 20 s fetch budget, 5 at a time; fetch holds no lock
A sync silently deletes a landlord's own photosD38 scopes deletion to the caller's own Source; an integration test asserts unowned photos survive
A CDN rotates signed URLs every nightRebinding by hash keeps the photo (Q11)
A multipart-uploaded API photo can never be removed by its uploaderAccepted. 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 syncAccepted, bounded by the 10-photo cap (F1)
Orphaned objects after a crash or failed removalLogged; cleanup job is a follow-up (Q18)
Outbound fetches used to hit a third partyExisting per-key hourly limit × 10-URL cap (Q26)
A leaked key exfiltrates identity documentsNo v1 route returns proof content at all (D43)
A leaked key fills the private bucket with proofs10-proof cap per property (Q16)
A landlord hits the lifetime proof capAccepted; no proof delete exists yet, an admin resolves it