Skip to content

File versions in the Craft Cloud app, through the agent - #28

Open
Skyfuller1303 wants to merge 9 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:history-ui
Open

Skyfuller1303 wants to merge 9 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:history-ui

Conversation

@Skyfuller1303

@Skyfuller1303 Skyfuller1303 commented Nov 4, 2026 •

Copy link
Copy Markdown

Stacked on #21 (version history and restore): this branch contains #21's commit; the diff of this PR alone is the last four commits. #21 adds the server routes; this makes them usable from the Craft Cloud app, through the agent (desktop → agent local API → server), as the layering requires.

What

  • Agent local API:

    Method Route Input
    GET /v1/files/history path, optional cursor and limit
    POST /v1/files/restore {path, version, expected_version}
    • Requests name a path relative to the sync root, because apps know paths, not node IDs.
    • The agent validates each component with Name::new (no .., absolute paths, drive letters, NUL or reserved names). It then resolves the path in its saved sync state. Only synced files are forwarded:
      • an unknown or unsynced path is 404;
      • a path outside the root is 400;
      • a folder is 400.
    • Server status and error codes pass through typed, and a server 401 becomes the local 409 needs_you, like the other signed-in routes. The usual Host/Origin/token guard and body limits apply.
    • After a successful restore the agent asks for a normal sync pass. It never writes the file itself; the restored version arrives through the change feed like any other change.
  • Types in crates/api/src/local.rs, and blocking calls file_history and restore_file in crates/app. app still depends on api only.

  • Craft Cloud app: a "File versions…" button on the signed-in screen opens a Versions screen with a path field.

    • The list is newest first and paged. Each row shows date, size and device.
    • "Restore this version" asks for confirmation. A conflict (the file changed meanwhile) reloads the list and says so, and a refusal (a deleted file, a file with a live document) is explained.
    • Stale answers are dropped by tickets, as on the admin pages. A restore isn't accepted while a page is still loading.
    • The path is sent exactly as typed.
  • docs/agent.md lists the two routes.

Assumptions (please confirm or redirect)

  1. Paths, not node IDs, on the local API.
  2. A path field rather than a file picker. A picker limited to the sync root is easy to add later.
  3. A restore while a page loads is refused, not queued; the confirmation stays open.

Testing

  • cargo fmt --all -- --check, cargo check --workspace --all-targets --locked, cargo clippy --workspace --all-targets --locked -- -D warnings.
  • Agent: --test local_api (14 tests, against a real server on loopback) and --lib (173 tests). The local_api tests cover:
    • history with paging;
    • a restore that the agent then syncs to disk, compared byte for byte;
    • a stale expected_version (409);
    • an unknown path (404), a path outside the root (400) and a folder (400);
    • the Host/Origin/token matrix on both routes.
  • cargo test -p craft-cloud-app, -p craft-cloud-api -p craft-cloud-proto.
  • Desktop --lib -- --test-threads=1 (59 tests):
    • model tests for listing, paging, restore, conflict reload, refusal messages, stale tickets, a restore while a page loads, and the path sent as typed;
    • new snapshots versions-empty.png, versions-loaded.png and versions-confirm.png;
    • the four signed-in snapshots, redrawn with the new button.

Not tested

Adds the request and answer types of GET /nodes/{id}/history and POST /nodes/{id}/restore, the opaque history cursor with a single accepted spelling, and the paging limits (default 50, at most 200).
history() pages a file's versions newest first by (seq, id) with an exclusive cursor. restore_version() records a new version with the content of an old one as an ordinary update, checking the source, the current version, deletion and live documents under the same space lock as a commit. No migration is needed.
GET /api/v1/nodes/{id}/history and POST /api/v1/nodes/{id}/restore, resolved in the caller's own space. A stale expected_version answers 409 conflict. Covers permissions, paging, conflicts, restoring old and missing versions, and parallel restores in the API tests.
Updates the API table and the milestone note in the sync design, and adds a short section to the server guide.
A history page now reads versions through an index on (space_id, node, seq, id) in the order of the query, so the page size bounds the work. The migration adds the index on both databases. The restore note in the sync design no longer claims the engine prefers a newer live-document state: a restore is an ordinary new version and files with a live document are refused.
Types for the agent's /v1/files/history and /v1/files/restore in crates/api, and the blocking client calls file_history and restore_file in crates/app. The app crate still depends on api only.
GET /v1/files/history and POST /v1/files/restore take a path relative to the sync root, validate each component, resolve it in the saved sync state and forward to the server; unknown or unsynced paths are 404, paths outside the root and folders 400, server errors pass through typed and a server 401 becomes 409 needs_you. A successful restore asks for a normal sync pass; the agent never writes the file itself.
A File versions button on the signed-in screen opens a screen with a path field, the file's versions newest first and paged (date, size, device) and a confirmed restore. A conflict reloads the list and says so, refusals are explained, stale answers are dropped by tickets, a restore is refused while a page is loading, and the path is sent exactly as typed. The signed-in snapshots are redrawn with the new button.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant