From 7d844849d71e733b173ffbec458dd84860a08db5 Mon Sep 17 00:00:00 2001 From: Omar Date: Mon, 9 Nov 2026 01:35:03 +0530 Subject: [PATCH] A sync that did not reach a device is no longer called in sync The CLI and the Deck plugin read a sync's answer per device, and any status they did not know counted as in sync: another device playing the game, with syncing paused, a save folder here that could not be written, or a sync with a device that failed. So "already in sync" was said of a save that had not gone over, and at a launch the Deck started the game quietly on the save it had while the game was being played on the PC. Each of those is now said for what it is. A failed sync with a device is a failure; a status not known here is shown rather than read as in sync. The Deck says it at a launch too. docs/CLI.md also covers the commands added since it was last written: pause, resume, transfers, activity, sessions, rename, offers, peers trust, emptied, relocate, storage and verify. --- docs/CLI.md | 73 ++++++++++++++++++++-- internal/cliapp/cli_gaps_test.go | 22 ++++++- internal/cliapp/commands_sync.go | 17 ++++- internal/cliapp/syncsummary.go | 39 +++++++++--- opensave-decky-plugin/main.py | 79 ++++++++++++++++++++---- opensave-decky-plugin/src/index.tsx | 9 ++- opensave-decky-plugin/tests/test_main.py | 31 ++++++++++ 7 files changed, 242 insertions(+), 28 deletions(-) diff --git a/docs/CLI.md b/docs/CLI.md index 18053531..1ad72179 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -37,9 +37,10 @@ The **daemon** is the background process that watches save folders, talks to peers and serves the local API. The desktop app runs one; on a headless box you run one yourself. -- **Needs a daemon** — anything about live state: `sync`, `peers`, `pair`, - `relay`, `conflicts`, `resolve`, `cloud`, `daemon status`, `probe`, `launch`, - `prune`, `files`, `backup`. +- **Needs a daemon** — anything about live state: `sync`, `pause`, `resume`, + `transfers`, `peers`, `pair`, `relay`, `conflicts`, `resolve`, `offers`, + `relocate`, `cloud`, `daemon status`, `probe`, `launch`, `wrap`, `prune`, + `files`, `backup`. Without one you get: *the OpenSave daemon isn't reachable at … — start it with `opensave daemon start`*. - **Works either way** — anything that only touches local data: `scan`, `add`, @@ -198,7 +199,61 @@ save lands on a separate branch, so nothing is discarded while you work out which you wanted. Auto-sync means you rarely need `sync` by hand; it is there for when you want -to be sure before shutting a machine down. +to be sure before shutting a machine down. `sync` says what happened with each +game: synced, already in sync, or why not — another device is playing it, has +syncing paused, or is waiting for a folder. + +```bash +opensave pause 30m # stop syncing for a while (or until resumed) +opensave resume # start again and catch up +opensave transfers # what is moving between devices now +opensave activity elden-ring # what happened to a save lately +opensave sessions # when games were played here, and for how long +opensave rename elden-ring "Elden Ring (main)" # what this device calls it +``` + +Pausing still takes snapshots. Renaming changes only the name shown here; the +game's ID, and how it syncs, stay as they are. + +## Task: games from your other devices + +When another device syncs a game this one doesn't have, OpenSave sets it up by +itself only in a folder it recognises as that game's save folder here. +Anywhere else, the game is **offered**, and you choose the folder: + +```bash +opensave offers # what is waiting for a folder +opensave offers place elden-ring "D:/Saves/Elden Ring" +opensave offers decline elden-ring # not offered again +``` + +For a device that is yours, you can let it choose folders here instead: + +```bash +opensave peers trust on # off to take it back +``` + +Only do that for your own devices: its games then go in the folder it names. + +## Task: when a save goes missing + +If every save file of a game is deleted on this device, OpenSave holds that +back instead of deleting the files on your other devices too, and asks: + +```bash +opensave emptied # what is held back +opensave emptied elden-ring restore # put the files back here +opensave emptied elden-ring delete # it was meant: delete them everywhere +``` + +If a game's save folder is missing and the same path exists on another drive +here — a renamed drive letter, a card in a different slot — it is offered, never +switched to by itself: + +```bash +opensave relocate elden-ring use # use that folder +opensave relocate elden-ring dismiss # not that one +``` ## Task: snapshots and going back @@ -210,6 +265,16 @@ opensave rollback elden-ring snap_1730000000000 Rolling back snapshots your current save first, so it is always reversible. +How much space they take, and whether they can all still be restored: + +```bash +opensave storage # space per game, the biggest snapshots +opensave storage --compact # have older snapshots share unchanged files +opensave verify # check every snapshot can be restored +opensave verify --repair # put damaged ones back from the cloud copy +opensave verify --remove-damaged # remove those that cannot be restored +``` + One file rather than the lot: ```bash diff --git a/internal/cliapp/cli_gaps_test.go b/internal/cliapp/cli_gaps_test.go index d1a61da6..c380a315 100644 --- a/internal/cliapp/cli_gaps_test.go +++ b/internal/cliapp/cli_gaps_test.go @@ -97,13 +97,33 @@ func TestSyncOutcomes(t *testing.T) { `{"p1":{"status":"peer_awaiting_folder","peerName":"Deck"}}`: "waiting", `{"p1":{"status":"peer_busy","peerName":"Deck"}}`: "queued", `{"p1":{"status":"peer_busy"},"p2":{"status":"updated"}}`: "changed", - `{}`: "in-sync", + `{"p1":{"status":"peer_playing","peerName":"Deck"}}`: "waiting", + `{"p1":{"status":"peer_paused","peerName":"Deck"}}`: "waiting", + `{"p1":{"status":"unwritable"}}`: "waiting", + `{"p1":{"status":"peer_playing"},"p2":{"status":"updated"}}`: "waiting", + `{"p1":{"status":"error","peerName":"Deck"}}`: "error", + `{"p1":{"status":"error"},"p2":{"status":"in_sync"}}`: "error", + `{"p1":{"status":"peer_missing"},"p2":{"status":"in_sync"}}`: "in-sync", + `{"p1":{"status":"something_new"}}`: "waiting", + `{}`: "in-sync", } { if got := syncOutcomeOf("g", json.RawMessage(raw)).Kind; got != want { t.Errorf("%s -> %q, want %q", raw, got, want) } } + // Whether some device took it, when another did not. + for raw, want := range map[string]bool{ + `{"p1":{"status":"peer_playing"}}`: false, + `{"p1":{"status":"peer_playing"},"p2":{"status":"updated"}}`: true, + `{"p1":{"status":"error"},"p2":{"status":"in_sync"}}`: true, + `{"p1":{"status":"error"}}`: false, + } { + if got := syncOutcomeOf("g", json.RawMessage(raw)).Some; got != want { + t.Errorf("%s: some = %v, want %v", raw, got, want) + } + } + s := summarizeSync([]syncOutcome{{Kind: "paused"}, {Kind: "paused"}, {Kind: "skipped"}}) if s.nothingSynced() != "paused" { t.Errorf("all paused: %q", s.nothingSynced()) diff --git a/internal/cliapp/commands_sync.go b/internal/cliapp/commands_sync.go index 90f0c7f7..e4c67407 100644 --- a/internal/cliapp/commands_sync.go +++ b/internal/cliapp/commands_sync.go @@ -61,8 +61,23 @@ func cmdSync(args []string) int { hint("opensave conflicts") return 1 case "waiting": - success("Synced %s with the devices that could take it.", bold(gameID)) + if o.Some { + success("Synced %s with the devices that could take it.", bold(gameID)) + } else { + warning("%s was not synced.", bold(gameID)) + } + note(o.Detail) + case "error": + if o.Some { + warning("Synced %s with some devices, but not all.", bold(gameID)) + } else { + warning("%s was not synced.", bold(gameID)) + } note(o.Detail) + hint("opensave activity") + return 1 + case "queued": + success("Queued %s: another device was still applying a sync of it, and it is asked again when done.", bold(gameID)) default: success("%s is already in sync.", bold(gameID)) } diff --git a/internal/cliapp/syncsummary.go b/internal/cliapp/syncsummary.go index b5518341..3da20203 100644 --- a/internal/cliapp/syncsummary.go +++ b/internal/cliapp/syncsummary.go @@ -24,6 +24,9 @@ type syncOutcome struct { // Detail is the error, the device a conflict is with, or what a device // is waiting on. Detail string + // Some is whether at least one device took the save, when another did + // not (waiting, error). + Some bool } type peerSyncResult struct { @@ -81,7 +84,9 @@ func outcomeFromPeers(gameID string, peers map[string]peerSyncResult) syncOutcom ids = append(ids, id) } sort.Strings(ids) - changed, busy, waiting := false, false, "" + changed, busy := false, false + var waiting, failed, missing []string + reached := 0 for _, id := range ids { p := peers[id] who := p.PeerName @@ -91,29 +96,47 @@ func outcomeFromPeers(gameID string, peers map[string]peerSyncResult) syncOutcom switch p.Status { case "conflict": return syncOutcome{Game: gameID, Kind: "conflict", Detail: who} + case "in_sync": + reached++ case "updated", "updated_bidirectional", "deletions_synced", "triggered_peer_pull": changed = true + reached++ case "peer_busy": // The other device was still applying a sync of its own; the // daemon asks again the moment it has finished. busy = true case "peer_awaiting_folder": - waiting = who + " is waiting for a folder to be chosen for it" + waiting = append(waiting, who+" is waiting for a folder to be chosen for it") case "peer_holding": - waiting = who + " is holding it back: its save was emptied there" + waiting = append(waiting, who+" is holding it back: its save was emptied there") + case "peer_playing": + waiting = append(waiting, "it is being played on "+who+"; its save comes over when that session ends") + case "peer_paused": + waiting = append(waiting, who+" has syncing paused") + case "unwritable": + waiting = append(waiting, "its save folder here could not be written to; OpenSave tries again in 30 minutes or after a restart") case "peer_missing": - if waiting == "" { - waiting = who + " does not track it" - } + missing = append(missing, who+" does not track it") + case "error": + failed = append(failed, "the sync with "+who+" failed (opensave activity says why)") + default: + // A status this CLI does not know yet, from a newer daemon. Not + // read as in sync: nothing says it is. + waiting = append(waiting, fmt.Sprintf("%s answered %q", who, p.Status)) } } + some := reached > 0 switch { + case len(failed) > 0: + return syncOutcome{Game: gameID, Kind: "error", Detail: strings.Join(failed, "; "), Some: some} + case len(waiting) > 0: + return syncOutcome{Game: gameID, Kind: "waiting", Detail: strings.Join(waiting, "; "), Some: some || changed} case changed: return syncOutcome{Game: gameID, Kind: "changed"} case busy: return syncOutcome{Game: gameID, Kind: "queued"} - case waiting != "": - return syncOutcome{Game: gameID, Kind: "waiting", Detail: waiting} + case len(missing) > 0 && !some: + return syncOutcome{Game: gameID, Kind: "waiting", Detail: strings.Join(missing, "; ")} default: return syncOutcome{Game: gameID, Kind: "in-sync"} } diff --git a/opensave-decky-plugin/main.py b/opensave-decky-plugin/main.py index 082fea6c..230f5f33 100644 --- a/opensave-decky-plugin/main.py +++ b/opensave-decky-plugin/main.py @@ -105,23 +105,68 @@ def reason_of(message: str, reason: str = "") -> str: CHANGED = ("updated", "updated_bidirectional", "deletions_synced", "triggered_peer_pull") -def game_outcome(entry) -> str: - """One game's outcome in a sync-all answer: changed, in-sync, conflict, - queued, skipped, or why it did not sync (paused, held, offline, error).""" +# What a device answered that means the save did not go over to it, or come +# from it, yet: why, in a few words. Anything not known here is said too, +# rather than read as in sync. +WAITING = { + "peer_awaiting_folder": "{who} is waiting for a folder to be chosen for it", + "peer_holding": "{who} is holding it back: its save was emptied there", + "peer_playing": "It's being played on {who} — its save comes over when that session ends", + "peer_paused": "{who} has syncing paused", + "unwritable": "Its save folder here can't be written to", +} + + +def game_result(entry): + """One game's outcome in a sync answer, and what explains it: changed, + in-sync, conflict, waiting (detail says on what), queued, skipped, or why + it did not sync (paused, held, offline, error).""" if not isinstance(entry, dict): - return "error" + return "error", "" status = entry.get("status") if isinstance(status, str): if status == "error": - return reason_of(entry.get("error", ""), entry.get("reason", "")) + return reason_of(entry.get("error", ""), entry.get("reason", "")), entry.get("error", "") if status in ("queued", "skipped"): - return status - peers = [p for p in entry.values() if isinstance(p, dict)] - if any(p.get("status") == "conflict" for p in peers): - return "conflict" - if any(p.get("status") in CHANGED for p in peers): - return "changed" - return "in-sync" + return status, "" + peers = sorted((k, p) for k, p in entry.items() if isinstance(p, dict)) + changed = busy = False + reached = 0 + waiting, failed, missing = [], [], [] + for _, p in peers: + who = p.get("peerName") or "the other device" + st = p.get("status") + if st == "conflict": + return "conflict", who + if st == "in_sync": + reached += 1 + elif st in CHANGED: + changed = True + reached += 1 + elif st == "peer_busy": + busy = True + elif st == "peer_missing": + missing.append(f"{who} does not track it") + elif st == "error": + failed.append(f"The sync with {who} failed") + else: + waiting.append(WAITING.get(st, '{who} answered "' + str(st) + '"').format(who=who)) + if failed: + return "error", "; ".join(failed) + if waiting: + return "waiting", "; ".join(waiting) + if changed: + return "changed", "" + if busy: + return "queued", "" + if missing and not reached: + return "waiting", "; ".join(missing) + return "in-sync", "" + + +def game_outcome(entry) -> str: + """One game's outcome in a sync answer (game_result, without its detail).""" + return game_result(entry)[0] def summarize_sync_all(results: dict) -> dict: @@ -157,6 +202,8 @@ def n(count, one, many): extra.append(n(counts["conflict"], "needs a decision", "need a decision")) if counts.get("held"): extra.append(n(counts["held"], "held back", "held back")) + if counts.get("waiting"): + extra.append(n(counts["waiting"], "waiting on another device", "waiting on another device")) if counts.get("error"): extra.append(n(counts["error"], "failed", "failed")) if extra: @@ -235,7 +282,13 @@ async def sync_game(self, game_id: str) -> dict: answer = _request(f"/api/games/{game_id}/sync", method="POST", body={}, timeout=120) or {} if answer.get("queued"): return {"success": True, "outcome": "queued"} - return {"success": True, "outcome": game_outcome(answer.get("results") or {})} + outcome, detail = game_result(answer.get("results") or {}) + if outcome == "error": + decky.logger.error(f"sync_game({game_id}): {detail}") + return {"success": False, "reason": "error", "error": detail} + if outcome == "waiting": + return {"success": True, "outcome": "waiting", "detail": detail} + return {"success": True, "outcome": outcome} except DaemonRefused as e: reason = reason_of(str(e), e.reason) if reason == "error": diff --git a/opensave-decky-plugin/src/index.tsx b/opensave-decky-plugin/src/index.tsx index bc574abf..85e0954a 100644 --- a/opensave-decky-plugin/src/index.tsx +++ b/opensave-decky-plugin/src/index.tsx @@ -80,9 +80,11 @@ interface DaemonStatus { /** A sync of one game: what it did, or why it did not happen. */ interface SyncResult { success: boolean; - outcome?: "changed" | "in-sync" | "conflict" | "queued" | "timeout"; + outcome?: "changed" | "in-sync" | "conflict" | "queued" | "waiting" | "timeout"; reason?: "paused" | "held" | "offline" | "error"; error?: string; + /** For "waiting": what it waits on, said for the person. */ + detail?: string; } type Done = { success: boolean; error?: string }; @@ -164,6 +166,8 @@ function syncSaid(res: SyncResult): string { return "Queued behind a sync already running"; case "conflict": return "Changed here and on another device — choose which to keep"; + case "waiting": + return res.detail || "Not synced yet"; default: return "Already in sync"; } @@ -650,6 +654,9 @@ function lifecycleSaid(res: SyncResult, when: "launch" | "exit"): string { if (res.outcome === "changed") return when === "launch" ? "Brought the newest save in" : "Save synced"; if (res.outcome === "conflict") return "Changed here and on another device — open OpenSave to choose"; if (res.outcome === "timeout") return "Still syncing — started anyway, the save follows"; + // Not "in sync": at a launch, most often the game is being played on + // another device, and this one is about to start on the save it has. + if (res.outcome === "waiting") return res.detail || "Not synced yet"; return when === "exit" ? "Save synced" : ""; } switch (res.reason) { diff --git a/opensave-decky-plugin/tests/test_main.py b/opensave-decky-plugin/tests/test_main.py index 3e29e3f0..ba804575 100644 --- a/opensave-decky-plugin/tests/test_main.py +++ b/opensave-decky-plugin/tests/test_main.py @@ -121,6 +121,37 @@ def test_sync_all_no_longer_says_started_when_nothing_could_sync(self): self.assertEqual(mixed["message"], "Synced 2 games: 1 updated, 1 already in sync — 1 needs a decision") self.assertFalse(main.summarize_sync_all({"a": {"status": "error", "error": "boom"}})["success"]) + def test_a_sync_that_did_not_reach_a_device_is_not_called_in_sync(self): + cases = { + "peer_playing": "being played on PC", + "peer_paused": "PC has syncing paused", + "unwritable": "can't be written", + "something_new": 'PC answered "something_new"', + } + for status, said in cases.items(): + stub = StubDaemon({"POST /api/games/hades/sync": (200, {"results": {"p": {"status": status, "peerName": "PC"}}})}) + try: + res = run(main.Plugin().sync_game("hades")) + finally: + stub.close() + self.assertEqual(res["outcome"], "waiting", status) + self.assertIn(said, res["detail"]) + + stub = StubDaemon({"POST /api/games/hades/sync": (200, {"results": { + "p": {"status": "error", "peerName": "PC"}, "q": {"status": "in_sync"}}})}) + try: + res = run(main.Plugin().sync_game("hades")) + finally: + stub.close() + self.assertFalse(res["success"]) + self.assertEqual(res["reason"], "error") + + summary = main.summarize_sync_all({ + "a": {"p": {"status": "in_sync"}}, + "b": {"p": {"status": "peer_playing", "peerName": "PC"}}, + }) + self.assertEqual(summary["message"], "Synced 1 game: 1 already in sync — 1 waiting on another device") + def test_sync_all_end_to_end(self): stub = StubDaemon({"POST /api/games/sync-all": (200, {"results": { "a": {"status": "error", "error": "no online peers available", "reason": "offline"}}})})