Skip to content

feat(tomesync): sync on suspend — morning stats without waking the device (build 35)#129

Merged
bndct-devops merged 1 commit into
mainfrom
feat/tomesync-sync-on-suspend
Jul 18, 2026
Merged

feat(tomesync): sync on suspend — morning stats without waking the device (build 35)#129
bndct-devops merged 1 commit into
mainfrom
feat/tomesync-sync-on-suspend

Conversation

@bndct-devops

Copy link
Copy Markdown
Owner

Closes #128.

What

Two new opt-in TomeSync settings (both default off), plugin build 35 / semver 1.9.0:

  • Sync on suspend — when the device goes to sleep, catch up anything still pending: queued sessions, queued ratings, and (when "Auto-sync reading history on launch" is enabled) the KOReader reading-history backfill. Only syncs when WiFi is already connected.
  • Aggressive sync (turn WiFi on at suspend) — gated on the first toggle. If the radio is off at suspend, bring it up via NetworkMgr:turnOnWifiAndWaitForConnection, sync, and let the system power it back down as the device sleeps. For devices that aggressively sleep the radio (the reporter's PocketBook).

Plus one unconditional improvement: onNetworkConnected now also runs the reading-history backfill (previously launch-only, so morning WiFi-on didn't refresh stats without restarting KOReader) and no longer requires an open book to flush pending state — WiFi coming up in the file manager catches everything up.

Design notes

  • The aggressive path deliberately bypasses beforeWifiAction/wifi_enable_action: with the default "prompt" setting, honoring it would pop a connect dialog onto the sleep screen (the footgun stock KOSync warns about and makes the user reconfigure around). The toggle's promise is "turn WiFi on", so it does exactly that.
  • The whole suspend path is queue-or-resume safe by construction — sessions/ratings re-flush from their pending queues, and the history import resumes from the server-side watermark — so a device that finishes suspending mid-sync (or before WiFi associates) just completes on the next connection. First-run backfills won't fit in a suspend window; they make partial progress and resume. That's the accepted trade-off, documented in the toggle help text.

Verification

  • Full backend suite green (922 passed); the semver-pin test updated for 1.9.0.
  • Emulator round-trip on this branch (fake-WiFi + Suspend broadcast):
    • WiFi up + suspend → history sync runs (watermark GET observed server-side)
    • WiFi down + aggressive → radio comes up, sync completes ~2s later on NetworkConnected
    • Toggles off (default) → suspend is a no-op, byte-identical to current behavior
    • Aggressive toggle correctly disabled while the master toggle is off
  • Not yet validated on real hardware. The aggressive path is device-specific; plan is to ask the reporter (PocketBook Era) to validate via [KOReader Plugin] Sync on suspend #128 after merge, plus a Kindle pass before release.

…vice (build 35)

Closes #128. Two new opt-in settings: "Sync on suspend" catches up pending
sessions/ratings and the reading-history backfill at lid close when WiFi is
already connected; "Aggressive sync" turns WiFi on first via
turnOnWifiAndWaitForConnection (bypassing wifi_enable_action so "prompt"
never dialogs onto the sleep screen). Every step is queue-or-resume safe, so
a device that sleeps mid-sync just finishes on the next connection.

onNetworkConnected now also runs the history backfill (was launch-only) and
no longer requires an open book to flush pending state — WiFi coming up in
the file manager catches everything up.

Verified in the emulator: suspend with WiFi up syncs; suspend with WiFi down
+ aggressive brings the radio up and syncs after connect; toggle off = no-op;
aggressive toggle gates on the master toggle.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bndct-devops
bndct-devops merged commit 8bb7323 into main Jul 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[KOReader Plugin] Sync on suspend

1 participant