Task 23: Native notifications (#23) #56

Manually merged
charles merged 0 commits from task/23-notifications into foundation 2026-11-11 18:28:22 +00:00
Owner

Stacked on: task/10-core-messages-readstate, task/12-platform-persistence, task/14-app-runtime (base of this branch's own commits: d0f3c10).

What this builds

fluxer-core (src/notifications.rs): after every reducer, App::apply asks notification_for(app, event) and appends Effect::Notify(Notification { title, body, channel_id, message_id }) for a MESSAGE_CREATE that

  • arrives while notifications are on (LocalSettings::notifications_enabled),
  • was written by someone else and is a normal message or a reply,
  • is for a channel the client knows (Review Focus 2: an unknown channel notifies nothing),
  • mentions the user, or mentions everyone in a channel the user can see (can_view), or is in a DM / group DM,
  • and is not being looked at: the channel is not selected, or the window is not focused.

Title <author> in #channel / <author> (named as display_name does). Body: content with <@id>, <@&id>, <#id> and custom emoji written as names, Markdown kept (as the Electron client's preserveMarkdown), cut to 200 characters; Attachment: <filename> for a message without text.

fluxer-platform (src/notify/{mod,linux,windows}.rs): trait Notifier { fn notify(&self, &Notification) -> Result<()> } and system_notifier(on_click). Both backends use notify-rust 4 (new dependency, named by the task): the freedesktop service over zbus on Linux, a WinRT toast on Windows. On Linux the body is escaped when the server reads markup, and the default action reports a click. Clicks are waited for on one thread per open notification, at most 32.

Finding on the fork crate: fluxer_linux_notifications is napi-only (public API is a #[napi] class taking JS callbacks/objects, D-Bus code private, napi_build::setup() in build.rs), so the plan's fallback notify-rust is used. Recorded in crates/fluxer-platform/README.md and deny.toml.

apps/fluxer (outside the task's file list, the wiring Task 14 left for this task): Effect::Notify goes to a blocking worker owning the notifier; a click comes back as an internal event and becomes CloseSettings / SelectGuild / SelectChannel as needed. Runtime::with_notifier replaces the system notifier (tests).

How it was tested

  • crates/fluxer-core/tests/notifications.rs: the plan's four tests (mention_in_unselected_channel_notifies, message_in_selected_focused_channel_does_not_notify, dm_notifies_even_without_mention, notifications_disabled_suppresses) plus @everyone, own message, unknown channel, system message, logged out, mention names in the body, truncation, attachment fallback. Written first and seen failing (commit 099de95).
  • fluxer-platform unit tests: click watching (click, close, the 32 limit), capability parsing, markup escaping.
  • apps/fluxer unit tests: the notify worker (order, clicks, a failing notifier), what a click selects, stale clicks.
  • By hand on KDE Plasma 6.8.2: cargo run -p fluxer-platform --example notify was accepted and shown by the server. The click was not exercised by a person, and nothing was run on Windows.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally.

Deviations from the plan

  • No icon: AvatarSource on Notification. The type comes with Task 21, which is not in this stack and does not merge into it mechanically. Follow-up: #54.
  • "mention_everyone and channel allows" is implemented as "the user can view the channel"; the per-guild suppress-@everyone setting, mutes and role mentions are not modelled in Foundation.
  • crates/fluxer-core/tests/messages.rs (Task 10): one assertion that a DM message produces no effects now expects exactly the Notify.
  • Touched outside the file list: apps/fluxer/src/{runtime,lib}.rs (wiring), crates/fluxer-core/src/{app,effect,lib}.rs, the three READMEs, Cargo.toml/Cargo.lock/deny.toml (dependency), and crates/fluxer-platform/examples/notify.rs (the manual check).
  • notify-rust brings zbus 6 next to keyring's zbus 5 (cargo-deny: duplicate warning only).

For the reviewer

  • crates/fluxer-platform/src/notify/windows.rs was written against the notify-rust 4.19 sources and has only ever been compiled by the Windows runner.
  • With the default notifier, fluxer --devserver shows real notifications if a scenario contains a mention or DM (basic does not).
  • Deferred to the shell and packaging (raise the window on a click, WindowFocus, desktop entry, Windows app id): #55.

Closes #23

🤖 Generated with Claude Code

Stacked on: task/10-core-messages-readstate, task/12-platform-persistence, task/14-app-runtime (base of this branch's own commits: d0f3c10). ## What this builds **`fluxer-core`** (`src/notifications.rs`): after every reducer, `App::apply` asks `notification_for(app, event)` and appends `Effect::Notify(Notification { title, body, channel_id, message_id })` for a `MESSAGE_CREATE` that - arrives while notifications are on (`LocalSettings::notifications_enabled`), - was written by someone else and is a normal message or a reply, - is for a channel the client knows (Review Focus 2: an unknown channel notifies nothing), - mentions the user, or mentions everyone in a channel the user can see (`can_view`), or is in a DM / group DM, - and is not being looked at: the channel is not selected, or the window is not focused. Title `<author> in #channel` / `<author>` (named as `display_name` does). Body: content with `<@id>`, `<@&id>`, `<#id>` and custom emoji written as names, Markdown kept (as the Electron client's `preserveMarkdown`), cut to 200 characters; `Attachment: <filename>` for a message without text. **`fluxer-platform`** (`src/notify/{mod,linux,windows}.rs`): `trait Notifier { fn notify(&self, &Notification) -> Result<()> }` and `system_notifier(on_click)`. Both backends use `notify-rust` 4 (new dependency, named by the task): the freedesktop service over zbus on Linux, a WinRT toast on Windows. On Linux the body is escaped when the server reads markup, and the `default` action reports a click. Clicks are waited for on one thread per open notification, at most 32. **Finding on the fork crate:** `fluxer_linux_notifications` is napi-only (public API is a `#[napi]` class taking JS callbacks/objects, D-Bus code private, `napi_build::setup()` in `build.rs`), so the plan's fallback `notify-rust` is used. Recorded in `crates/fluxer-platform/README.md` and `deny.toml`. **`apps/fluxer`** (outside the task's file list, the wiring Task 14 left for this task): `Effect::Notify` goes to a blocking worker owning the notifier; a click comes back as an internal event and becomes `CloseSettings` / `SelectGuild` / `SelectChannel` as needed. `Runtime::with_notifier` replaces the system notifier (tests). ## How it was tested - `crates/fluxer-core/tests/notifications.rs`: the plan's four tests (`mention_in_unselected_channel_notifies`, `message_in_selected_focused_channel_does_not_notify`, `dm_notifies_even_without_mention`, `notifications_disabled_suppresses`) plus @everyone, own message, unknown channel, system message, logged out, mention names in the body, truncation, attachment fallback. Written first and seen failing (commit 099de95). - `fluxer-platform` unit tests: click watching (click, close, the 32 limit), capability parsing, markup escaping. - `apps/fluxer` unit tests: the notify worker (order, clicks, a failing notifier), what a click selects, stale clicks. - By hand on KDE Plasma 6.8.2: `cargo run -p fluxer-platform --example notify` was accepted and shown by the server. **The click was not exercised by a person**, and nothing was run on Windows. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. ## Deviations from the plan - **No `icon: AvatarSource` on `Notification`.** The type comes with Task 21, which is not in this stack and does not merge into it mechanically. Follow-up: #54. - "`mention_everyone` and channel allows" is implemented as "the user can view the channel"; the per-guild suppress-@everyone setting, mutes and role mentions are not modelled in Foundation. - `crates/fluxer-core/tests/messages.rs` (Task 10): one assertion that a DM message produces no effects now expects exactly the `Notify`. - Touched outside the file list: `apps/fluxer/src/{runtime,lib}.rs` (wiring), `crates/fluxer-core/src/{app,effect,lib}.rs`, the three READMEs, `Cargo.toml`/`Cargo.lock`/`deny.toml` (dependency), and `crates/fluxer-platform/examples/notify.rs` (the manual check). - `notify-rust` brings zbus 6 next to keyring's zbus 5 (cargo-deny: duplicate warning only). ## For the reviewer - `crates/fluxer-platform/src/notify/windows.rs` was written against the notify-rust 4.19 sources and has only ever been compiled by the Windows runner. - With the default notifier, `fluxer --devserver` shows real notifications if a scenario contains a mention or DM (`basic` does not). - Deferred to the shell and packaging (raise the window on a click, `WindowFocus`, desktop entry, Windows app id): #55. Closes #23 🤖 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>
Adds the gateway crate's dependencies (rustls, rustls-native-certs and zstd are
new to the workspace; Task 7 names tokio-tungstenite with rustls and zstd).

Refs #7

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

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

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

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(gateway): websocket transport with zstd streaming
All checks were successful
ci / Windows (x64) (push) Successful in 57s
ci / Windows (x64) (pull_request) Successful in 48s
ci / Linux (x86_64) (push) Successful in 1m3s
ci / Linux (x86_64) (pull_request) Successful in 1m3s
e60021584a
Refs #7

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>
Refs #13

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
feat(devserver): fixture-backed API and gateway for tests
All checks were successful
ci / Windows (x64) (pull_request) Successful in 1m11s
ci / Linux (x86_64) (pull_request) Successful in 1m20s
ci / Windows (x64) (push) Successful in 57s
ci / Linux (x86_64) (push) Successful in 1m10s
4c00cf12fd
Refs #13

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
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>
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>
# Conflicts:
#	Cargo.lock
# Conflicts:
#	Cargo.lock
#	Cargo.toml
Refs #14

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
ApiClient::with_observer shows each exchange that got a response (no
headers); Connection::connect_with_tap shows each frame received and
sent. Both are off unless asked for.

Refs #14

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(app): effect runtime, config, logging and record mode
Some checks failed
ci / Windows (x64) (pull_request) Failing after 19s
ci / Windows (x64) (push) Failing after 4s
ci / Linux (x86_64) (pull_request) Successful in 1m37s
ci / Linux (x86_64) (push) Successful in 1m43s
a2ce504001
Refs #14

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
ci(windows): free the build cache when the runner disk is low
All checks were successful
ci / Linux (x86_64) (push) Successful in 1m9s
ci / Windows (x64) (push) Successful in 1m33s
ci / Linux (x86_64) (pull_request) Successful in 1m12s
ci / Windows (x64) (pull_request) Successful in 1m21s
6ada26ce7e
The persistent Windows runner ran out of space on C: (os error 112). Log free
space, remove this project's own target dirs when it drops below 30 GB, and
turn off incremental compilation there. Also correct CLAUDE.md: one target dir
per worktree, and run the screenshot step locally before pushing.

Refs #51

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge remote-tracking branch 'origin/ci/51-windows-disk-space' into task/14-app-runtime
All checks were successful
ci / Linux (x86_64) (push) Successful in 1m49s
ci / Windows (x64) (push) Successful in 2m59s
ci / Linux (x86_64) (pull_request) Successful in 1m53s
ci / Windows (x64) (pull_request) Successful in 2m46s
d0f3c10f86
Refs #23

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat: native mention notifications
All checks were successful
ci / Linux (x86_64) (push) Successful in 2m8s
ci / Linux (x86_64) (pull_request) Successful in 1m49s
ci / Windows (x64) (push) Successful in 2m55s
ci / Windows (x64) (pull_request) Successful in 2m33s
c0c5a4e629
fluxer-core decides which MESSAGE_CREATE dispatches notify (mention, @everyone
in a visible channel, DM; not while the channel is open in the focused window;
not when notifications are off) and emits Effect::Notify. fluxer-platform shows
it through notify-rust (freedesktop service on Linux, WinRT toast on Windows);
the fork's fluxer_linux_notifications crate is napi-only. The runtime runs the
notifier on a blocking worker and turns a click into SelectGuild/SelectChannel.

Refs #23

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

Independent review: Task 23 (notifications)

Reviewed d0f3c10..c0c5a4e (branch task/23-notifications) in a fresh worktree.

Checks

  1. Plan tests: mention_in_unselected_channel_notifies, message_in_selected_focused_channel_does_not_notify, dm_notifies_even_without_mention, notifications_disabled_suppresses all exist in crates/fluxer-core/tests/notifications.rs, assert the full Notification (title "ada in #general" / "Ada L.", body, ids), and pass. The 200-character truncation and the "not selected OR unfocused" rule are tested too.
  2. Interfaces: trait Notifier { fn notify(&self, n: &Notification) -> Result<()> } present; Effect::Notify(Notification { title, body, channel_id, message_id }) emitted; click -> UserAction::SelectChannel (preceded by CloseSettings/SelectGuild when needed); LocalSettings.notifications_enabled and UiState.window_focused respected. One deviation, see finding 1.
  3. Invariants: fluxer-core gains no dependency (core-isolation step green); nothing in fluxer-ui; the <...> reference parser in notifications.rs slices only at ASCII </> boundaries and has no panicking path on server text; no tokens or secrets in code or fixtures. notify-rust is the dependency the plan names; cargo-deny green (new zbus 5/6 duplicate is a warning only).
  4. Review Focus 2 (unknown channel): message_for_unknown_channel_does_not_notify covers it.
  5. cargo xtask ci in the review worktree: green (fmt, clippy, deny, core-isolation, tests; screenshot step skipped because FLUXER_SCREENSHOT_TESTS was not set in my run).

Findings

  1. minor - crates/fluxer-core/src/effect.rs: Notification has no icon: AvatarSource, which the plan's Interfaces block lists. AvatarSource is produced by Task 21, which is not in this stack, and nothing merged consumes the field, so no other task breaks. Tracked in #54; adding the field later is a breaking struct-literal change for the tests here, so do it with Task 21's merge.
  2. minor - crates/fluxer-platform/src/notify/windows.rs: never compiled (no Windows target here either). I read it against the notify-rust 4.19.0 sources: show() returns windows::NotificationHandle, wait_for_response(impl ResponseHandler) -> Result<()> and NotificationResponse::is_default_action exist and the handle is Send, so it should compile, but the Windows runner is the first real compile. The integrator must see that runner green before merge.
  3. minor - apps/fluxer/src/runtime.rs: Runtime::new defaults to the system notifier, so apps/fluxer/tests/runtime.rs and --devserver would pop real desktop notifications as soon as a scenario contains a DM or a mention (basic has neither today: its one live MESSAGE_CREATE is an unmentioned guild message). Tests should pass a no-op notifier via with_notifier before such a scenario is added.
  4. minor - click path: the Linux click -> SelectChannel path was not exercised by hand (the KDE check only showed the notification); it is covered by unit tests of Clicks, notify_worker and click_actions only. Window raise on click is deferred to #55.
  5. minor - crates/fluxer-core/tests/messages.rs: one Task 10 assertion changed from "no effects" to "exactly one Effect::Notify" for a DM message. Correct consequence of this task, noted because it is outside the Files list.

Verdict: approve (0 blocking, 5 minor; local ci green, Windows runner still to be confirmed by the integrator).

## Independent review: Task 23 (notifications) Reviewed `d0f3c10..c0c5a4e` (branch `task/23-notifications`) in a fresh worktree. **Checks** 1. Plan tests: `mention_in_unselected_channel_notifies`, `message_in_selected_focused_channel_does_not_notify`, `dm_notifies_even_without_mention`, `notifications_disabled_suppresses` all exist in `crates/fluxer-core/tests/notifications.rs`, assert the full `Notification` (title `"ada in #general"` / `"Ada L."`, body, ids), and pass. The 200-character truncation and the "not selected OR unfocused" rule are tested too. 2. Interfaces: `trait Notifier { fn notify(&self, n: &Notification) -> Result<()> }` present; `Effect::Notify(Notification { title, body, channel_id, message_id })` emitted; click -> `UserAction::SelectChannel` (preceded by `CloseSettings`/`SelectGuild` when needed); `LocalSettings.notifications_enabled` and `UiState.window_focused` respected. One deviation, see finding 1. 3. Invariants: `fluxer-core` gains no dependency (core-isolation step green); nothing in `fluxer-ui`; the `<...>` reference parser in `notifications.rs` slices only at ASCII `<`/`>` boundaries and has no panicking path on server text; no tokens or secrets in code or fixtures. `notify-rust` is the dependency the plan names; cargo-deny green (new `zbus` 5/6 duplicate is a warning only). 4. Review Focus 2 (unknown channel): `message_for_unknown_channel_does_not_notify` covers it. 5. `cargo xtask ci` in the review worktree: **green** (fmt, clippy, deny, core-isolation, tests; screenshot step skipped because `FLUXER_SCREENSHOT_TESTS` was not set in my run). **Findings** 1. **minor** - `crates/fluxer-core/src/effect.rs`: `Notification` has no `icon: AvatarSource`, which the plan's Interfaces block lists. `AvatarSource` is produced by Task 21, which is not in this stack, and nothing merged consumes the field, so no other task breaks. Tracked in #54; adding the field later is a breaking struct-literal change for the tests here, so do it with Task 21's merge. 2. **minor** - `crates/fluxer-platform/src/notify/windows.rs`: never compiled (no Windows target here either). I read it against the notify-rust 4.19.0 sources: `show()` returns `windows::NotificationHandle`, `wait_for_response(impl ResponseHandler) -> Result<()>` and `NotificationResponse::is_default_action` exist and the handle is `Send`, so it should compile, but the Windows runner is the first real compile. The integrator must see that runner green before merge. 3. **minor** - `apps/fluxer/src/runtime.rs`: `Runtime::new` defaults to the system notifier, so `apps/fluxer/tests/runtime.rs` and `--devserver` would pop real desktop notifications as soon as a scenario contains a DM or a mention (`basic` has neither today: its one live `MESSAGE_CREATE` is an unmentioned guild message). Tests should pass a no-op notifier via `with_notifier` before such a scenario is added. 4. **minor** - click path: the Linux click -> `SelectChannel` path was not exercised by hand (the KDE check only showed the notification); it is covered by unit tests of `Clicks`, `notify_worker` and `click_actions` only. Window raise on click is deferred to #55. 5. **minor** - `crates/fluxer-core/tests/messages.rs`: one Task 10 assertion changed from "no effects" to "exactly one `Effect::Notify`" for a DM message. Correct consequence of this task, noted because it is outside the Files list. **Verdict: approve** (0 blocking, 5 minor; local ci green, Windows runner still to be confirmed by the integrator).
charles manually merged commit 24e7c9d137 into foundation 2026-11-11 18:28:22 +00:00
Sign in to join this conversation.
No description provided.