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
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,12 +153,14 @@ Keep the format `major.minor.micro`: the Makefile splits it on the dots and `mak
- **Generations, not timestamps, say who is behind.** The manifest keeps the 3DS's own copy under `local|<path>` (mtime, size, `generation`), and each remote's record holds the generation it last received. The generation goes up whenever the 3DS's copy changes. A remote whose tag moved is *changed*; one whose generation is older is *behind* and is sent the current version — unless it is both, which is a conflict with the 3DS, because its edit started from a version the 3DS has since replaced. Without generations a remote that was offline for a run looks like it made the change it missed.
- **Manifests from before the n-way engine** have no `local|` entry and no `"gen"`. The newest remote record becomes the 3DS baseline, and a record without a generation counts as holding the baseline's when its recorded mtime/size match it (`sameStat()`), which makes the first run after an upgrade decide what the pairwise engine would have. `"gen"` is only written when non-zero, so such a manifest round-trips byte for byte, and an older 3DSync ignores both additions.
- Change detection compares the local mtime **and** size against the `local|` record, plus each remote's `tag`. `SyncProvider::localTag()` is the content-based fallback for stale mtimes and is only meaningful where the remote's tag is derivable from file contents (Drive's MD5, Dropbox's `content_hash`); it returns "" elsewhere. It also settles a remote that changed to the very bytes the 3DS has (no conflict, nothing copied) — which is what lets a remote added with copies already on it avoid a conflict per file. Size+mtime remotes cannot prove that from the listing; for a *conflict* the engine then compares the bytes (see the next point).
- **A conflict is checked against the bytes before anyone is asked.** With two or more sides changed and the 3DS holding a copy, `sameAsLocalCopy()` in `syncengine.cpp` takes each changed remote without a content hash: a known `RemoteFileInfo::size` that differs from the 3DS's settles it; otherwise, within `SyncEntry::compareUpTo` (`[Sync] CompareUpTo=` in KB, default 4096, 0 = no limit (`COMPARE_UP_TO_UNLIMITED`), parsed by `parseCompareUpTo()` in `remoteconfig.cpp`; a `SyncEntry`'s own default of 0 never compares, which keeps the other engine tests free of comparison downloads; `[Sync] CompareConflicts=false` (`parseCompareConflicts()`) sets that 0 whatever `CompareUpTo=` says), it `download()`s the remote copy to `<save>.compare<side>.3dstmp` and `compareFiles()` (`utils/fsutil`) it. A match is `sameAsLocal` — out of the prompt, recorded as in step, nothing copied. A copy that differs is kept as `Side::fetched`: if that side wins the prompt, `downloadFrom()` moves it into place with `replaceLocalFile()` instead of downloading it again, and `FetchedCopies` removes every unused one however `syncFile()` returns. A failed or over-size check leaves the conflict as it was. FTP (`SIZE`), SMB and WebDAV (`getcontentlength`) fill `size`; Drive and Dropbox never need it. `recurse_dir()` skips names ending in `.3dstmp`, so a comparison or download cut short is never synced as a save.
- **A conflict is checked against the bytes before anyone is asked.** With two or more sides changed and the 3DS holding a copy, `sameAsLocalCopy()` in `syncengine.cpp` takes each changed remote without a content hash: a known `RemoteFileInfo::size` that differs from the 3DS's settles it; otherwise, within `SyncEntry::compareUpTo` (`[Sync] CompareUpTo=` in KB, default 4096, 0 = no limit (`COMPARE_UP_TO_UNLIMITED`), parsed by `parseCompareUpTo()` in `remoteconfig.cpp`; a `SyncEntry`'s own default of 0 never compares, which keeps the other engine tests free of comparison downloads; `[Sync] CompareConflicts=false` (`parseCompareConflicts()`) sets that 0 whatever `CompareUpTo=` says), it `download()`s the remote copy to `<save>.compare<side>.3dstmp` and `compareFiles()` (`utils/fsutil`) it. A match is `sameAsLocal` — out of the prompt, recorded as in step, nothing copied. A copy that differs is kept as `Side::fetched`: if that side wins the prompt, `downloadFrom()` moves it into place with `replaceLocalFile()` instead of downloading it again, and `FilePlan`'s destructor removes every unused one, however the file ends (see "Review first" below for `FilePlan`). A failed or over-size check leaves the conflict as it was. FTP (`SIZE`), SMB and WebDAV (`getcontentlength`) fill `size`; Drive and Dropbox never need it. `recurse_dir()` skips names ending in `.3dstmp`, so a comparison or download cut short is never synced as a save.
- **Path names keep their spelling on the remote** (#71). INIReader lowercases every key, so `configuredPaths()` gives a `SyncEntry` both: `remoteName`, the folder as written (`INIReader::GetSpelling()`), which the providers, the log and the picker get; and `name`, lowercased, which is what `Only=` (`takesPart()`), `[Filter]` (`forEntry()`) and Drive's `Folder.<name>=` (`_pathFolders`, looked up through `asciiLower()`) compare. Versions before this one sent the lowercased name, so a case-sensitive server may hold `gba` where the INI says `GBA`: for a name with capitals, `resolveRoot()` in `syncengine.cpp` asks `SyncProvider::findRoot()` — which never creates anything — for the name as written, then lowercased, and only calls `ensureRoot()` (as written) when neither exists. FTP (a name-only listing, refused = missing), WebDAV (Depth 0 `PROPFIND`, 404 expected) and SMB (`smb2_stat()`) implement it; Dropbox and Drive compare names ignoring case and keep the default, which finds nothing. A lowercase name costs no extra request.
- **The extension filter** (`[Filter]`, `ExtensionFilter` and `PathFilters` in `sync/extfilter.h`) is per path and defaults to all files. `Extensions=` is the list for every path; a key naming a path (`roms/nds=dsv`, lowercased like every INIReader key) replaces it for that one, `*` included. `parsePathFilters()` collects keys naming no configured path in `unknown`, which `configIssues()` turns into a startup issue; a path named `extensions` cannot have its own line. It is applied twice on purpose: `getConfiguredSyncPaths()` drops non-matching local files, because a provider's `legacyUpload()` only ever sees `localFiles`; and `syncEntry()` filters both `localFiles` and every remote listing, so a remote-only file it excludes is never downloaded. Filtered files are skipped *before* the decision table, so their manifest entries are neither updated nor removed — widening the filter again must not look like a first sync and raise a conflict for every file. The menu card shows `PathFilters::describe()` under FILES (it is in `signature()`): the default's list, or "per path" once any path has its own. A run prints an entry's filter under that entry's header, when it has one. List separators are commas and whitespace, never `;` (inih's inline comment); the configurator refuses a `;` for that reason.
- Manifest keys are `Participant::keyPrefix + "|" + localPath`, the prefix being `manifestScope()`: `SyncProvider::manifestPrefix()` for an unnamed section, plus `#<label>` for a labelled one. Changing a provider's prefix orphans every existing entry for that remote, which makes the next sync treat every file as unseen — so keep them stable.
- Conflict resolution calls `SyncUi::resolveConflict(localPath, sides)` with the names of the sides that changed (`LOCAL_SIDE`, "3DS", first when it is one), which on the 3DS is `frontend::WorkerSyncUi` and returns a `ConflictChoice`: `keep(index)`, `skip()` (X) or `cancel()` (START). The prompt lists the sides however many there are (two included): the highlighted side is the A button, and tapping another row, R (wrapping) or D-pad ↑/↓ move the highlight. It starts on the first side, so A alone still keeps the 3DS's version whenever that is one of them; there is no B. Four rows fit; beyond that the list window follows the highlight (`conflictListFirst()`), with a small arrow at a scrolled-off end. L toggles "for all": a skip then skips every later conflict, a kept side is kept in every later conflict it is part of, and one it is not part of is asked again.
- The main menu (`frontend::waitForMenu()`) returns a `frontend::MenuChoice`: A runs a sync, Y runs the same sync in debug mode, X (or tapping the card's PATHS line) opens the path picker, START exits. `main()` calls `setDebugEnabled()` and `debugLogReset()` from that choice *before* `frontend::runWorker()`, because the providers read the flag when they construct their `Curl` handle. START also cancels a running sync, and the flag stays set only for that run.
- The main menu (`frontend::waitForMenu()`) returns a `frontend::MenuChoice`: A runs a sync, B a review-first sync (`MENU_REVIEW`, see next point), Y runs the same sync in debug mode, X (or tapping the card's PATHS line) opens the path picker, START exits. `main()` calls `setDebugEnabled()` and `debugLogReset()` from that choice *before* `frontend::runWorker()`, because the providers read the flag when they construct their `Curl` handle. START also cancels a running sync, and the flag stays set only for that run.
- **Review first** (B). `syncFile()` is split in two: `decideFile()` does everything up to and including the conflict prompt (and the byte comparison before it) and returns a `FilePlan` — the sides, the source, the new generation and one `SideAction` per side (source, same, read-only, renumber, upload) — and `applyFile()` carries it out: transfers, then the manifest. A normal sync (`syncEntry()`) applies each plan at once, so it behaves as before; a review-first one runs `planEntry()` for every entry (no transfer, no manifest write), prints `planLines()`, asks `frontend::askStartTransfers()` (`SCREEN_REVIEW`), and only then `applyEntryPlan()` for each (`transferPlanned()` in `main.cpp`). A plan owns its comparison copies (`FilePlan`'s destructor removes unused ones) and points into its participants and their listings, which `PlannedEntry` (a `std::list`) keeps alive in between. `applyFile()` re-stats the 3DS's copy and leaves it alone, as a `problems` entry, if it changed since it was decided. Drive's `legacyUpload()` transfers as it goes, so `SyncProvider::hasLegacyUpload()` tells the review to hold it back for the second pass.
- **Unattended transfers.** `frontend::setUnattended(true)` for the second pass only: `aptSetSleepAllowed(false)`, so closing the lid does not sleep the console (which drops Wi-Fi and the SMB session), and `frame()` polls `PTMU_GetShellState()` and turns the backlights off (`GSPLCD_PowerOffBacklight()`) while the lid is closed. Off again restores sleep and the backlight. `ptmuInit()`/`gspLcdInit()` are in `componentsInit()`. Never leave sleep refused outside that pass: a console that does not sleep with the lid shut drains its battery.
- **The path picker** (`frontend::choosePaths()`, `SCREEN_PATHS`) ticks which configured paths the next syncs take. `main()` owns the choice — one `bool` per `configuredPaths()` entry, all ticked at startup — and hands it to `runSync()` through `SyncRequest`. It lasts for the session only: 3DSync.ini is never rewritten for it. `runSync()` neither walks nor syncs an unticked path, and lists the ones left out at the top of the log. **A remote that takes part in none of the chosen entries is not connected at all** — not built, no login, no SMB/FTP timeout — and says so in one line; `RemoteConfig::takesPart()` is that rule (its `Only=`, and never an upload-only entry for a `Role=source` remote), shared with `syncAllEntries()` so the two cannot disagree.
- The manifest (`/3ds/3DSync/manifest.json`) is a hand-parsed JSON file. Use `Manifest::set/get/has/remove` — never write JSON by hand elsewhere.
- `svcSleepThread(nanoseconds)` is the 3DS sleep call (from `<3ds.h>`). Use it for rate-limit back-offs.
Expand Down
23 changes: 21 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,10 @@ label says which, so either works:

| Where | Buttons |
|---|---|
| Menu | **A** sync, **Y** sync with debug output, **X** (or tap **PATHS**) choose paths, **START** exit |
| Menu | **A** sync, **B** review first (see below), **Y** sync with debug output, **X** (or tap **PATHS**) choose paths, **START** exit |
| Choosing paths | Tap a path to tick or untick it, or move with **D-pad ↑/↓** and press **A**. **Y** ticks all (or clears all), **B** goes back. The choice lasts until 3DSync is closed; a remote that none of the ticked paths go to is not connected |
| During a sync | **START** stops after the current file |
| During a sync | **START** stops, the file being transferred included |
| Review first, before the transfers | **A** start them, **B** or **START** cancel: nothing is transferred |
| Conflict | The versions that changed are listed; **A** keeps the highlighted one (the 3DS's at first). Tap a version, or move to it with **R** or **D-pad ↑/↓**. **X** skips the file, **L** applies the answer to every remaining conflict, **START** stops. The log still scrolls with ←/→, the Circle Pad and the scroll strip |
| End of a run | **A** save its log, **B** discard it |
| Problems in 3DSync.ini, at startup | **A** continue to the menu, **START** exit; the list scrolls like the log |
Expand All @@ -49,6 +50,24 @@ The log can be scrolled at any time, including while a sync is running:
touch screen. While you are scrolled up, new output does not move the text;
scroll back to the bottom and the log follows it again.

### Review first

A normal sync deals with each file in turn, so a conflict can come up between
two long transfers and you have to keep an eye on it. **B** on the menu splits
the run in two:

1. 3DSync lists every remote and decides every file, asking every conflict as
it goes (the [check for identical files](#conflicts-that-are-the-same-file)
runs first, so only real differences are asked). Nothing is transferred yet.
2. The log lists every file it will download or upload, and the bottom screen
asks once whether to start.
3. The transfers then run without another question. You can close the lid:
the screens go dark and the sync keeps going, which a normal sync does not
(the console sleeps and drops Wi-Fi). **START** still stops it.

A save you play between the review and its transfer is left alone and named in
the summary, so a review never overwrites newer progress.

---

## Installation
Expand Down
Loading
Loading