Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 69 additions & 4 deletions docs/CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -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 <peerId> 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

Expand All @@ -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
Expand Down
22 changes: 21 additions & 1 deletion internal/cliapp/cli_gaps_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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())
Expand Down
17 changes: 16 additions & 1 deletion internal/cliapp/commands_sync.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
Expand Down
39 changes: 31 additions & 8 deletions internal/cliapp/syncsummary.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand All @@ -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"}
}
Expand Down
79 changes: 66 additions & 13 deletions opensave-decky-plugin/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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":
Expand Down
9 changes: 8 additions & 1 deletion opensave-decky-plugin/src/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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 };
Expand Down Expand Up @@ -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";
}
Expand Down Expand Up @@ -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) {
Expand Down
Loading
Loading