Task 12: Persistence (fluxer-platform::store) (#12) #49

Manually merged
charles merged 0 commits from task/12-platform-persistence into foundation 2026-11-11 18:28:09 +00:00
Owner

Stacked on: task/9-core-guilds-channels, task/10-core-messages-readstate, task/11-core-presence-ui (merged into this branch at 73799f7; everything after that commit is Task 12)

What this builds

fluxer-core::persist

  • PersistOp { SaveToken, ClearToken, SaveSettings(LocalSettings), CacheMessages { channel_id, messages }, CacheReady(Box<ReadyPayload>) } and PersistResult { Loaded { token, settings, cached_ready }, Ok }.
  • LocalSettings (instance_url, installation_id, sidebar_width, window {x,y,w,h,maximized}, notifications_enabled, status_api {enabled, token}); Debug does not print the status token.
  • Stored-token login: Loaded with a token -> Discovering (Api Discover) -> LoggingIn (Api Me) -> LoggedIn + ConnectGateway, no SaveToken. A 401 on Me emits ClearToken and ends in SessionExpired; any other failure leaves the token in the keyring.
  • cached_ready (only with a token) fills guilds, channels, users, presences, read markers and the synced user settings and sets App::stale. The live READY replaces all of it; the data is also dropped when the attempt ends or Me answers for another account.
  • Writes: CacheReady on each live READY, CacheMessages on each non-empty history page, SaveSettings when SidebarResized / SetInstance / SetNotificationsEnabled / SetStatusApiEnabled change something.

fluxer-platform

  • Paths::new("fluxer-native") / Paths::under(root).
  • settings::load / settings::save: defaults when missing (written at once), invalid file renamed settings.toml.bad, per-field fallback, atomic write, mode 0600 on Unix. Status token = 24 random bytes base64url, as in fork:fluxer_desktop/src/common/DesktopConfig.ts.
  • Secrets::new(host), save_token / load_token / clear_token over keyring::Entry::new("fluxer-native", host).
  • Cache::open (rusqlite bundled, user_version = 1): a file that is not a database, fails quick_check, or has another version is deleted and recreated; if the file is unusable the cache runs in memory. Never fails (Review Focus 5). put_messages (newest 200 per channel), get_messages(channel, limit) in ascending id order, put_ready / get_ready, clear.
  • Store: Store::load(paths) -> (Store, PersistResult::Loaded) and Store::execute(&PersistOp) for the runtime (Task 14).

How it was tested

cargo xtask ci green locally (Linux). New tests:

  • crates/fluxer-core/tests/persist.rs (15): loaded_token_triggers_me_then_connect, cached_ready_marks_store_stale_until_live_ready, plus rejected token, unreachable instance, other account, cancelled restore, caching and settings writes.
  • crates/fluxer-platform/tests/settings.rs (7): settings_default_when_missing_and_bad_file_renamed and per-field fallbacks, round trip, file mode.
  • crates/fluxer-platform/tests/cache.rs (11): cache_rebuilt_when_corrupt, cache_rebuilt_when_user_version_differs, cache_roundtrips_messages_in_id_order, truncated file, bound per channel, undecodable rows, in-memory fallback.
  • Unit tests for Store, Paths and Secrets. The keyring tests run against keyring-core's in-memory mock store: the real OS keyring is not exercised by any test, here or in CI. Not built or run on Windows locally.

Deviations from the plan

  • LocalSettings is defined in fluxer-core (PersistOp::SaveSettings carries it and core cannot depend on platform), so loading and saving are fluxer_platform::settings::load(&paths) / save(&paths, &settings), not methods. Core gains a uuid dependency for installation_id.
  • cached_ready is Option<Box<ReadyPayload>> (boxed like the merged GatewayEvent::Ready).
  • New App fields settings: Option<LocalSettings> and stale: bool; new Session::token(), which the runtime needs to send Me before a logged-in state exists.
  • Nothing is written before the Loaded event. This also keeps the Task 9-11 tests, which assert that READY emits no effects and never send Loaded, unchanged.
  • RegenerateStatusToken is not handled: the store has no randomness. settings::new_status_token() is public for whoever implements it.
  • Window geometry is stored and loaded, but no UserAction reports it yet, so nothing updates it.
  • Dependencies beyond the three the plan names (directories, keyring, rusqlite): toml, base64, getrandom, dev-only tempfile and keyring-core.
  • deny.toml now ignores RUSTSEC-2026-0370/-0371/-0372 (zvariant, zbus_names, zvariant_derive 5.x marked unmaintained after being merged into zbus 6; they come in through keyring's Secret Service store and there is no upgrade yet). Follow-up: #48. This is a policy exception for Charles to accept or reject.

For the reviewer: the stacking merge was not purely mechanical

Tasks 9, 10 and 11 each replaced the others' stub types, so merging them conflicted in crates/fluxer-core/src/{app.rs,lib.rs,selectors/mod.rs} and the README. Resolved in the two merge commits before 73799f7:

  • App::apply runs the reducers of all three (guilds/channels, then messages/typing/read state, then users/presence/ui, with ui after messages as its comment requires); the stub structs are gone.
  • messages.rs, typing.rs, read_state.rs import Channels / UiState from their real modules.
  • tests/presence_ui.rs: the user() helper no longer asserts that a user action emits no effects, because with Task 10 present SelectChannel fetches the first page.
  • Left as each branch had it: Task 11's users and presence reducers also run for gateway dispatches received while logged out, where Task 9's guilds and channels drop them.

Closes #12

🤖 Generated with Claude Code

Stacked on: task/9-core-guilds-channels, task/10-core-messages-readstate, task/11-core-presence-ui (merged into this branch at 73799f7; everything after that commit is Task 12) ## What this builds **`fluxer-core::persist`** - `PersistOp { SaveToken, ClearToken, SaveSettings(LocalSettings), CacheMessages { channel_id, messages }, CacheReady(Box<ReadyPayload>) }` and `PersistResult { Loaded { token, settings, cached_ready }, Ok }`. - `LocalSettings` (`instance_url`, `installation_id`, `sidebar_width`, `window {x,y,w,h,maximized}`, `notifications_enabled`, `status_api {enabled, token}`); `Debug` does not print the status token. - Stored-token login: `Loaded` with a token -> `Discovering` (`Api Discover`) -> `LoggingIn` (`Api Me`) -> `LoggedIn` + `ConnectGateway`, no `SaveToken`. A 401 on `Me` emits `ClearToken` and ends in `SessionExpired`; any other failure leaves the token in the keyring. - `cached_ready` (only with a token) fills guilds, channels, users, presences, read markers and the synced user settings and sets `App::stale`. The live `READY` replaces all of it; the data is also dropped when the attempt ends or `Me` answers for another account. - Writes: `CacheReady` on each live `READY`, `CacheMessages` on each non-empty history page, `SaveSettings` when `SidebarResized` / `SetInstance` / `SetNotificationsEnabled` / `SetStatusApiEnabled` change something. **`fluxer-platform`** - `Paths::new("fluxer-native")` / `Paths::under(root)`. - `settings::load` / `settings::save`: defaults when missing (written at once), invalid file renamed `settings.toml.bad`, per-field fallback, atomic write, mode 0600 on Unix. Status token = 24 random bytes base64url, as in `fork:fluxer_desktop/src/common/DesktopConfig.ts`. - `Secrets::new(host)`, `save_token` / `load_token` / `clear_token` over `keyring::Entry::new("fluxer-native", host)`. - `Cache::open` (rusqlite bundled, `user_version = 1`): a file that is not a database, fails `quick_check`, or has another version is deleted and recreated; if the file is unusable the cache runs in memory. Never fails (Review Focus 5). `put_messages` (newest 200 per channel), `get_messages(channel, limit)` in ascending id order, `put_ready` / `get_ready`, `clear`. - `Store`: `Store::load(paths) -> (Store, PersistResult::Loaded)` and `Store::execute(&PersistOp)` for the runtime (Task 14). ## How it was tested `cargo xtask ci` green locally (Linux). New tests: - `crates/fluxer-core/tests/persist.rs` (15): `loaded_token_triggers_me_then_connect`, `cached_ready_marks_store_stale_until_live_ready`, plus rejected token, unreachable instance, other account, cancelled restore, caching and settings writes. - `crates/fluxer-platform/tests/settings.rs` (7): `settings_default_when_missing_and_bad_file_renamed` and per-field fallbacks, round trip, file mode. - `crates/fluxer-platform/tests/cache.rs` (11): `cache_rebuilt_when_corrupt`, `cache_rebuilt_when_user_version_differs`, `cache_roundtrips_messages_in_id_order`, truncated file, bound per channel, undecodable rows, in-memory fallback. - Unit tests for `Store`, `Paths` and `Secrets`. The keyring tests run against keyring-core's in-memory mock store: the real OS keyring is not exercised by any test, here or in CI. Not built or run on Windows locally. ## Deviations from the plan - `LocalSettings` is defined in `fluxer-core` (`PersistOp::SaveSettings` carries it and core cannot depend on platform), so loading and saving are `fluxer_platform::settings::load(&paths)` / `save(&paths, &settings)`, not methods. Core gains a `uuid` dependency for `installation_id`. - `cached_ready` is `Option<Box<ReadyPayload>>` (boxed like the merged `GatewayEvent::Ready`). - New `App` fields `settings: Option<LocalSettings>` and `stale: bool`; new `Session::token()`, which the runtime needs to send `Me` before a logged-in state exists. - Nothing is written before the `Loaded` event. This also keeps the Task 9-11 tests, which assert that `READY` emits no effects and never send `Loaded`, unchanged. - `RegenerateStatusToken` is not handled: the store has no randomness. `settings::new_status_token()` is public for whoever implements it. - Window geometry is stored and loaded, but no `UserAction` reports it yet, so nothing updates it. - Dependencies beyond the three the plan names (`directories`, `keyring`, `rusqlite`): `toml`, `base64`, `getrandom`, dev-only `tempfile` and `keyring-core`. - `deny.toml` now ignores RUSTSEC-2026-0370/-0371/-0372 (`zvariant`, `zbus_names`, `zvariant_derive` 5.x marked unmaintained after being merged into zbus 6; they come in through keyring's Secret Service store and there is no upgrade yet). Follow-up: #48. This is a policy exception for Charles to accept or reject. ## For the reviewer: the stacking merge was not purely mechanical Tasks 9, 10 and 11 each replaced the others' stub types, so merging them conflicted in `crates/fluxer-core/src/{app.rs,lib.rs,selectors/mod.rs}` and the README. Resolved in the two merge commits before 73799f7: - `App::apply` runs the reducers of all three (guilds/channels, then messages/typing/read state, then users/presence/ui, with `ui` after `messages` as its comment requires); the stub structs are gone. - `messages.rs`, `typing.rs`, `read_state.rs` import `Channels` / `UiState` from their real modules. - `tests/presence_ui.rs`: the `user()` helper no longer asserts that a user action emits no effects, because with Task 10 present `SelectChannel` fetches the first page. - Left as each branch had it: Task 11's users and presence reducers also run for gateway dispatches received while logged out, where Task 9's guilds and channels drop them. Closes #12 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #8

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): store skeleton and session reducer
All checks were successful
ci / Windows (x64) (push) Successful in 42s
ci / Linux (x86_64) (push) Successful in 1m0s
ci / Windows (x64) (pull_request) Successful in 41s
ci / Linux (x86_64) (pull_request) Successful in 1m5s
cacedcbbf7
Refs #8

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #9

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #11

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): presence, users and ui state
All checks were successful
ci / Windows (x64) (push) Successful in 39s
ci / Windows (x64) (pull_request) Successful in 39s
ci / Linux (x86_64) (push) Successful in 1m7s
ci / Linux (x86_64) (pull_request) Successful in 1m3s
f4ce82e123
Refs #11

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): guild and channel reducers and sidebar selectors
All checks were successful
ci / Windows (x64) (pull_request) Successful in 45s
ci / Windows (x64) (push) Successful in 43s
ci / Linux (x86_64) (pull_request) Successful in 1m3s
ci / Linux (x86_64) (push) Successful in 1m10s
e753f32ec6
Refs #9

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #10

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): messages, typing and read state
All checks were successful
ci / Windows (x64) (push) Successful in 44s
ci / Windows (x64) (pull_request) Successful in 44s
ci / Linux (x86_64) (push) Successful in 1m4s
ci / Linux (x86_64) (pull_request) Successful in 1m3s
38a4f01a14
Refs #10

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
# Conflicts:
#	crates/fluxer-core/README.md
#	crates/fluxer-core/src/app.rs
#	crates/fluxer-core/src/lib.rs
#	crates/fluxer-core/src/selectors/mod.rs
# Conflicts:
#	crates/fluxer-core/README.md
#	crates/fluxer-core/src/app.rs
#	crates/fluxer-core/src/lib.rs
#	crates/fluxer-core/src/selectors/mod.rs
Refs #12

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(platform,core): settings, keyring token and sqlite cache
Some checks failed
ci / Windows (x64) (push) Failing after 23s
ci / Linux (x86_64) (push) Failing after 56s
ci / Windows (x64) (pull_request) Failing after 13s
ci / Linux (x86_64) (pull_request) Failing after 54s
6eb27db77c
Core: PersistOp/PersistResult/LocalSettings in fluxer_core::persist, the
stored-token login (Loaded -> Discover -> Me -> ConnectGateway), cached READY
data marked App::stale until the live READY, and the CacheReady/CacheMessages/
SaveSettings writes.

Platform: Paths, settings.toml (defaults on missing, .bad on invalid), the
keyring token, the SQLite cache (rebuilt when corrupt or of another schema
version, in memory if the file is unusable) and Store, which ties them to
PersistOp for the runtime.

New dependencies: directories, keyring, rusqlite (bundled), toml, base64,
getrandom, tempfile (dev), keyring-core (dev, mock store).

Refs #12

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 12 (head 6eb27db, diff from 73799f7)

Verdict: APPROVE — no blocking findings; cargo xtask ci green locally on Linux in a fresh review worktree with its own target dir (screenshot step skipped, FLUXER_SCREENSHOT_TESTS unset). Not checked by me: Windows build/run, and the real OS keyring (tests use keyring-core's mock store only).

Checks

  1. Plan tests — all six exist under the plan's names and assert what it says: settings_default_when_missing_and_bad_file_renamed (320 / https://fluxer.forked.io/ / notifications on, .bad holds the original bytes), cache_rebuilt_when_corrupt (garbage bytes, open succeeds on disk, empty, user_version 1), cache_rebuilt_when_user_version_differs, cache_roundtrips_messages_in_id_order, loaded_token_triggers_me_then_connect (Discover, Me, ConnectGateway, no SaveToken), cached_ready_marks_store_stale_until_live_ready.
  2. Interfaces — PersistOp and PersistResult variants, Paths::new, Secrets::{save,load,clear}_token, Cache::open/put_messages/get_messages/put_ready/get_ready are present. Deviations are listed under minor.
  3. Invariants — fluxer-core gains only uuid, still no I/O; the token is SecretString, StatusApiSettings redacts Debug, only the scrubbed flx_FIXTURE… placeholder appears; cache and settings files are 0600 on Unix; no panic path on server or disk data (the one expect is on a constant with a test).
  4. Review Focus 5 — corrupt, truncated, wrong-version and unversioned files are all deleted and rebuilt, with an in-memory fallback; Cache::open cannot fail.
  5. Stale logic and 401 handling (implementer's item 9) — read and traced: cleared on live READY, failed or cancelled restore, and another account; 401 on Me clears the token, other failures keep it. Covered by tests.

Findings (all minor)

  • minor — interface deviations Task 14/15 must build against: Loaded.cached_ready is Option<Box<ReadyPayload>> (plan: Option<ReadyPayload>); LocalSettings lives in fluxer_core::persist and load/save are free functions fluxer_platform::settings::{load,save} rather than LocalSettings::load(&Paths); the keyring user is host[:port], not the bare host.
  • minor — core's settings copy can overwrite runtime-written values (crates/fluxer-core/src/persist.rs): every SaveSettings carries core's whole LocalSettings, and no event updates status_api.token or window in it. If Task 15 regenerates the status token, or the app saves window geometry, straight to the file, the next sidebar drag writes the old values back. RegenerateStatusToken and geometry are not implemented (stated by the implementer); they need a core event, and deserve a follow-up issue.
  • minor — another account's cached messages survive on disk (crates/fluxer-platform/src/lib.rs): the cache is emptied only on ClearToken. After a restore that failed for a non-401 reason followed by a login as a different user, or a Me that returns another account, CacheReady replaces the READY row but the previous account's messages rows stay. Clearing on a READY whose user id differs from the cached one would close it.
  • minor — SaveSettings per sidebar-drag event does a full write + fsync (settings.rs); documented as coalescible by the runtime, so Task 14 has to do that.
  • minor — policy exception for Charles: deny.toml ignores RUSTSEC-2026-0370/-0371/-0372 (zvariant, zbus_names, zvariant_derive 5.x unmaintained, via keyring 4's Secret Service store); follow-up #48. Extra dependencies beyond the plan's three: toml, base64, getrandom, uuid in core, dev-only tempfile and keyring-core.
  • minor — an orphaned token stays in the keyring when the instance is changed while a token is stored under the old host (e.g. after a restore that failed on the network).
## Independent review: Task 12 (head 6eb27db, diff from 73799f7) **Verdict: APPROVE** — no blocking findings; `cargo xtask ci` green locally on Linux in a fresh review worktree with its own target dir (screenshot step skipped, `FLUXER_SCREENSHOT_TESTS` unset). Not checked by me: Windows build/run, and the real OS keyring (tests use keyring-core's mock store only). ### Checks 1. **Plan tests** — all six exist under the plan's names and assert what it says: `settings_default_when_missing_and_bad_file_renamed` (320 / `https://fluxer.forked.io/` / notifications on, `.bad` holds the original bytes), `cache_rebuilt_when_corrupt` (garbage bytes, open succeeds on disk, empty, `user_version` 1), `cache_rebuilt_when_user_version_differs`, `cache_roundtrips_messages_in_id_order`, `loaded_token_triggers_me_then_connect` (Discover, Me, ConnectGateway, no SaveToken), `cached_ready_marks_store_stale_until_live_ready`. 2. **Interfaces** — `PersistOp` and `PersistResult` variants, `Paths::new`, `Secrets::{save,load,clear}_token`, `Cache::open/put_messages/get_messages/put_ready/get_ready` are present. Deviations are listed under minor. 3. **Invariants** — fluxer-core gains only `uuid`, still no I/O; the token is `SecretString`, `StatusApiSettings` redacts `Debug`, only the scrubbed `flx_FIXTURE…` placeholder appears; cache and settings files are 0600 on Unix; no panic path on server or disk data (the one `expect` is on a constant with a test). 4. **Review Focus 5** — corrupt, truncated, wrong-version and unversioned files are all deleted and rebuilt, with an in-memory fallback; `Cache::open` cannot fail. 5. **Stale logic and 401 handling** (implementer's item 9) — read and traced: cleared on live READY, failed or cancelled restore, and another account; 401 on `Me` clears the token, other failures keep it. Covered by tests. ### Findings (all minor) - **minor — interface deviations Task 14/15 must build against**: `Loaded.cached_ready` is `Option<Box<ReadyPayload>>` (plan: `Option<ReadyPayload>`); `LocalSettings` lives in `fluxer_core::persist` and load/save are free functions `fluxer_platform::settings::{load,save}` rather than `LocalSettings::load(&Paths)`; the keyring user is `host[:port]`, not the bare host. - **minor — core's settings copy can overwrite runtime-written values** (`crates/fluxer-core/src/persist.rs`): every `SaveSettings` carries core's whole `LocalSettings`, and no event updates `status_api.token` or `window` in it. If Task 15 regenerates the status token, or the app saves window geometry, straight to the file, the next sidebar drag writes the old values back. `RegenerateStatusToken` and geometry are not implemented (stated by the implementer); they need a core event, and deserve a follow-up issue. - **minor — another account's cached messages survive on disk** (`crates/fluxer-platform/src/lib.rs`): the cache is emptied only on `ClearToken`. After a restore that failed for a non-401 reason followed by a login as a different user, or a `Me` that returns another account, `CacheReady` replaces the READY row but the previous account's `messages` rows stay. Clearing on a READY whose user id differs from the cached one would close it. - **minor — `SaveSettings` per sidebar-drag event does a full write + fsync** (`settings.rs`); documented as coalescible by the runtime, so Task 14 has to do that. - **minor — policy exception for Charles**: `deny.toml` ignores RUSTSEC-2026-0370/-0371/-0372 (zvariant, zbus_names, zvariant_derive 5.x unmaintained, via keyring 4's Secret Service store); follow-up #48. Extra dependencies beyond the plan's three: `toml`, `base64`, `getrandom`, `uuid` in core, dev-only `tempfile` and `keyring-core`. - **minor — an orphaned token stays in the keyring** when the instance is changed while a token is stored under the old host (e.g. after a restore that failed on the network).
chore(deps): bump num-bigint 0.4.7 -> 0.4.8 (0.4.7 was yanked)
All checks were successful
ci / Windows (x64) (push) Successful in 1m2s
ci / Linux (x86_64) (push) Successful in 1m20s
ci / Windows (x64) (pull_request) Successful in 51s
ci / Linux (x86_64) (pull_request) Successful in 1m18s
6b043c3a08
cargo deny (yanked = deny) failed on both runners for run 71/72: num-bigint 0.4.7,
a transitive dependency of keyring's Secret Service store, was yanked from crates.io.
Lockfile-only patch bump; no manifest change.

Refs #12

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
charles manually merged commit 24e7c9d137 into foundation 2026-11-11 18:28:09 +00:00
Sign in to join this conversation.
No description provided.