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"}}})})