feat(cloud-sync): serve RetroArch Cloud Sync over WebDAV

[gantoine]

Description
^{Explain the changes or enhancements you are proposing with this pull request.}

Makes RomM a native cloud-sync target for RetroArch, so .srm saves and .state save states sync straight into RomM's existing asset storage with no sidecar service. Closes #2313.

RetroArch's cloud-sync driver only speaks a narrow slice of WebDAV: it GETs a JSON manifest of {path, hash} entries from manifest.server, diffs it three ways against its local state, then GETs/PUTs/DELETEs individual files. It never issues PROPFIND, so there is no collection listing to implement. This PR serves exactly that slice at /api/cloud-sync.

Setup for users: point RetroArch's Cloud Sync at https://<host>/api/cloud-sync/ (trailing slash required), enable save/state sync only, and authenticate with a RomM username and password over HTTP Basic.

What's here

• backend/endpoints/cloud_sync.py — the DAV surface: OPTIONS, GET, PUT, DELETE, MKCOL, MOVE.
• backend/handler/cloud_sync_handler.py — path grammar, ROM resolution, manifest construction.
• Supporting additions: get_roms_by_fs_name_no_ext, get_state_by_path, compute_file_md5.

Design notes

• Path is /api/cloud-sync, not the /webdav/ proposed in the issue. nginx already proxies /api to the backend; a new top-level path would fall into location / (the static SPA) and need its own location block.
• No core-name translation table. The community shim this is modelled on maps snes9x ↔ Snes9x. Here the emulator string is stored verbatim and namespaces storage exactly as it already does for /api/saves uploads (saves/<platform>/<rom_id>/<emulator>/). RetroArch's own rows round-trip exactly, and there's no table to keep current as cores come and go.
• Failed PUTs return 409, not a fake success. Answering OK for a file we didn't store would put it in RetroArch's local manifest; the next sync would then read its absence from ours as a remote delete and wipe the local copy. Same reasoning rejects the config/, thumbnails/ and system/ roots, which RomM has nowhere to store.
• Error responses carry no body. RetroArch logs failure responses from a fixed-size buffer and mishandles large ones.
• Slotted saves are excluded from the manifest. They're RomM's own versioned history, and their datetime-tagged file names aren't loadable by any core.
• MOVE is treated as a delete. It's what RetroArch sends in non-destructive mode to shelve a file under deleted/; RomM has no such holding area, and keeping the row would just push the file back on the next sync.
• The router gates itself instead of using @protected_route, so it can answer a 401 WWW-Authenticate challenge rather than the 403 that decorator produces. HTTP Basic already worked in HybridAuthBackend, and CSRFMiddleware already skips Basic-authenticated requests, so no middleware changes were needed.
• Manifest hashes are Redis-cached, keyed on path + size + updated_at. Without it, a library with a few hundred save states would re-read gigabytes on every sync.
• Routes are include_in_schema=False, so OpenAPI is unchanged and no frontend type regeneration is needed.

Known limitations

• ROMs are matched by file name alone, since that's all the client sends. A name shared across platforms resolves ambiguously (lowest ROM id wins, stably).
• No config/, thumbnails/ or system/ sync — RomM has no generic blob storage.
• PSP/PPSSPP multi-file save folders aren't bundled; only single-file saves and states are handled.
• ROM-library browsing over DAV is deliberately out of scope; RomM has better delivery paths for that.

AI assistance disclosure

Written with Claude Code (Opus 4.8). The protocol behaviour was re-derived from RetroArch's own tasks/task_cloudsync.c and network/cloud_sync/webdav.c; the design was informed by reading the README of the unlicensed community shim fmustafayaman/retroarch-webdav-romm, but none of its code was used. All design decisions above were reviewed by me, and I ran the test suite and linters locally.

Checklist
^{Please check all that apply.}

• I've tested the changes locally
• I've updated relevant comments
• I've assigned reviewers for this PR
• I've added unit tests that cover the changes

_{Testing note: 34 new endpoint/unit tests pass, and the saves/states/assets/sync/roms suites (279 tests) show no regressions; trunk fmt && trunk check is clean. The tests exercise the real middleware stack via TestClient, but this has not yet been run against a live RetroArch client — the manifest shape, verb set and status-code expectations come from reading RetroArch's source. Worth a real-device sync before merging.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

Adds a RetroArch-compatible WebDAV cloud-sync surface.

• Implements authenticated manifest, download, upload, deletion, MOVE, MKCOL, and OPTIONS handling.
• Maps RetroArch save/state paths onto existing per-user ROM asset storage.
• Adds basename-based ROM lookup, state lookup by path, raw-file MD5 hashing, endpoint tests, router registration, and architecture documentation.

Confidence Score: 2/5

The PR should not merge until cloud paths consistently identify assets and failed uploads cannot leave filesystem and database state inconsistent.

Same-named ROMs can make manifest paths resolve to the wrong database asset, while upload failures after the filesystem write leave orphaned files or stale metadata and hashes.

backend/handler/cloud_sync_handler.py, backend/endpoints/cloud_sync.py

Important Files Changed

Filename	Overview
backend/endpoints/cloud_sync.py	Adds the authenticated WebDAV surface, but ambiguous ROM resolution and uncoordinated filesystem/database writes can leave requests targeting the wrong asset or storage state inconsistent.
backend/handler/cloud_sync_handler.py	Adds path parsing, ROM resolution, hashing, and manifest generation, but generated paths cannot uniquely address same-named ROMs across platforms.
backend/handler/database/roms_handler.py	Adds a deterministic cross-platform basename query whose lowest-ID ordering drives ambiguous cloud-sync resolution.
backend/handler/database/states_handler.py	Adds a scoped state lookup by user, ROM, path, and filename.
backend/handler/filesystem/assets_handler.py	Adds raw-file MD5 computation with filesystem-error handling.
backend/main.py	Registers the cloud-sync router under the API prefix.
backend/tests/endpoints/test_cloud_sync.py	Covers protocol, authentication, manifest, and CRUD behavior but does not exercise colliding ROM basenames or post-write failures.
docs/BACKEND_ARCHITECTURE.md	Documents cloud-sync setup, supported methods, storage mapping, and stated limitations.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
backend/handler/cloud_sync_handler.py:170
**Manifest paths lose ROM identity**

When visible ROMs on different platforms share a filesystem basename, the manifest emits the same path for their assets while GET, PUT, and DELETE independently select the lowest-ID ROM. This causes an advertised download or deletion to return 404, attaches uploads to the wrong ROM, and makes one asset shadow the other when both exist.

### Issue 2 of 2
backend/endpoints/cloud_sync.py:183-185
**Upload commits before asset metadata**

When scanning or the subsequent database mutation fails after this write, the new bytes remain on disk without a corresponding row, or an existing file is overwritten while its metadata remains stale. The request returns an error, but the manifest then omits the orphaned upload or can retain the previous cached hash, leaving filesystem and database state inconsistent.

_{Reviews (1): Last reviewed commit: "feat(cloud-sync): serve RetroArch Cloud ..." | Re-trigger Greptile}

[greptile-apps]

Manifest paths lose ROM identity

When visible ROMs on different platforms share a filesystem basename, the manifest emits the same path for their assets while GET, PUT, and DELETE independently select the lowest-ID ROM. This causes an advertised download or deletion to return 404, attaches uploads to the wrong ROM, and makes one asset shadow the other when both exist.

Prompt To Fix With AI

This is a comment left during a code review.
Path: backend/handler/cloud_sync_handler.py
Line: 170

Comment:
**Manifest paths lose ROM identity**

When visible ROMs on different platforms share a filesystem basename, the manifest emits the same path for their assets while GET, PUT, and DELETE independently select the lowest-ID ROM. This causes an advertised download or deletion to return 404, attaches uploads to the wrong ROM, and makes one asset shadow the other when both exist.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Upload commits before asset metadata

When scanning or the subsequent database mutation fails after this write, the new bytes remain on disk without a corresponding row, or an existing file is overwritten while its metadata remains stale. The request returns an error, but the manifest then omits the orphaned upload or can retain the previous cached hash, leaving filesystem and database state inconsistent.

Knowledge Base Used:

• Database Models and Migrations
• Filesystem Handler

Prompt To Fix With AI

This is a comment left during a code review.
Path: backend/endpoints/cloud_sync.py
Line: 183-185

Comment:
**Upload commits before asset metadata**

When scanning or the subsequent database mutation fails after this write, the new bytes remain on disk without a corresponding row, or an existing file is overwritten while its metadata remains stale. The request returns an error, but the manifest then omits the orphaned upload or can retain the previous cached hash, leaving filesystem and database state inconsistent.

**Knowledge Base Used:**
- [Database Models and Migrations](https://app.greptile.com/romm/-/custom-context/knowledge-base/rommapp/romm/-/docs/database-models.md)
- [Filesystem Handler](https://app.greptile.com/romm/-/custom-context/knowledge-base/rommapp/romm/-/docs/filesystem-handler.md)

How can I resolve this? If you propose a fix, please make it concise.