diff --git a/AGENTS.md b/AGENTS.md index f0df07b..f84eebc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -151,7 +151,8 @@ Keep the format `major.minor.micro`: the Makefile splits it on the dots and `mak - A **read-only** participant (`Role=source`, `Participant::readOnly`) is the reverse: never written to. It can win like any side, but is never sent a version, so its recorded generation stays the one it really holds; a change of its own that lost is recorded (tag only) so it is not raised again. Being behind is its normal state, and a change it makes from an older generation than the 3DS's is a conflict with the 3DS, by the generation rule below. `syncEntry()` leaves it out of an upload-only entry, and `runSync()` does not offer it `legacyUpload()`. - **Generations, not timestamps, say who is behind.** The manifest keeps the 3DS's own copy under `local|` (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 and still ask. +- 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 `.compare.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. - **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.=` (`_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 `#