vasilito
9f2de2a0b1
Docs:
- Baseline was stated as 0.3.1 across the canonical set while the branch,
Cat 0/1 crates and every Cat 2 fork are 0.3.2. AGENTS.md also cited a
sources/redbear-0.3.1/ archive that does not exist; the only archive
present is sources/redbear-0.1.0/. Versioning examples now match the
forks as they actually stand (redoxfs/syscall 0.9.1, libredox 0.1.19).
- Repaired 18 instances of 'immutable archived' across 8 documents, where
a global find/replace had turned sync/synced/archived into that phrase
and produced ungrammatical text ('never auto-immutable archived',
'### Source immutable archived').
- Settled the apply-patches.sh contradiction empirically. Both sides were
wrong: the GROSS WARNING blocks (x5) described it as routine
patch-linking, and SCRIPT-BEHAVIOR-MATRIX.md said build-redbear.sh
'never invokes' it. It is invoked at build-redbear.sh:487, but only to
auto-repair a failed verify-overlay-integrity.sh check.
- Dropped the dangling reference to a local/AGENTS.md section
'NO OVERLAY-STYLE PATCHES — SCOPED POLICY' that does not exist.
Build system:
- mk/prefix.mk hardcoded 13.2.0 in the limits.h removal, which silently
no-ops after a toolchain upgrade and leaves the conflicting header.
Version-globbed.
- Parameterized GCC_RECIPE so the from-source toolchain path is not
pinned to gcc13.
- The three cstdlib strtold seds were not idempotent -- the shipped GCC
13 toolchain carried that comment block 17 times from repeated
'make prefix' runs. Each is now guarded.
63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
# redbear-notifications — D-Bus Interface
|
|
|
|
**Bus:** session
|
|
**Well-known name:** `org.freedesktop.Notifications`
|
|
**Object paths:**
|
|
- `/org/freedesktop/Notifications` — Notifications server
|
|
|
|
## Interface: `org.freedesktop.Notifications`
|
|
|
|
### Methods
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `Notify` | `(app_name: s, replaces_id: u, app_icon: s, summary: s, body: s, actions: as, hints: a{sv}, expire_timeout: i) → (u)` | Create or replace a notification. Returns notification ID. If `replaces_id` is non-zero and matches an existing notification owned by the same sender, the record is updated in-place. Maximum 1024 active notifications. |
|
|
| `CloseNotification` | `(id: u) → ()` | Close a notification by ID. Emits `NotificationClosed` signal with reason 3 (closed). |
|
|
| `GetCapabilities` | `() → (as)` | Returns `["body", "body-markup"]` |
|
|
| `GetServerInformation` | `() → (ssss)` | Returns `("Red Bear Notifications", "redbear", "0.3.1", "1.2")` |
|
|
| `InvokeAction` | `(id: u, action_key: s) → ()` | Invoke an action on a notification. Validates: (1) caller is the notification owner, (2) the action key was declared at notify time. Emits `ActionInvoked` signal, then removes the notification. |
|
|
|
|
### Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `Idle` | `b` | Always `false` (idle tracking not implemented) |
|
|
|
|
### Signals
|
|
|
|
| Signal | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `NotificationClosed` | `(id: u, reason: u)` | A notification was closed. Reason: 1=expired, 2=dismissed, 3=closed. |
|
|
| `ActionInvoked` | `(id: u, action_key: s)` | An action was invoked on a notification. |
|
|
|
|
## Notification Lifecycle
|
|
|
|
1. **Creation** (`Notify`): A notification record is stored with owner (sender bus name), action keys, expire timeout, and issue timestamp. Monotonically increasing IDs starting from 1. If `replaces_id` matches an existing record, that record is updated; otherwise a new record is created.
|
|
|
|
2. **Expiry** (background sweeper, 500 ms interval): Notifications with `expire_timeout > 0` are checked against `issued_at + expire_timeout`. Expired notifications are removed and `NotificationClosed(1)` is emitted. Notifications with `expire_timeout <= 0` never expire.
|
|
|
|
3. **Action invocation** (`InvokeAction`): Validates sender ownership and action key. Emits `ActionInvoked`, then removes the notification and emits `NotificationClosed(2)`.
|
|
|
|
4. **Close** (`CloseNotification`): Removes the notification and emits `NotificationClosed(3)`.
|
|
|
|
5. **Sender vanishing** (background reaper, 2 s interval): Every 2 seconds, the daemon queries `org.freedesktop.DBus.NameHasOwner` for each tracked sender. If a sender has vanished from the bus, all its notifications are removed and `NotificationClosed(2)` is emitted for each.
|
|
|
|
6. **Bound enforcement**: When the active notification count exceeds 1024, the oldest notification (by insertion order) is evicted and `NotificationClosed(2)` is emitted.
|
|
|
|
## Action Format
|
|
|
|
The `actions` parameter is a flat string array of alternating key-label pairs:
|
|
```
|
|
["default", "Open", "reply", "Reply"]
|
|
```
|
|
The daemon extracts keys (every even-indexed element) and validates `InvokeAction` against them.
|
|
|
|
## Connection
|
|
|
|
- Session bus (`ConnectionBuilder::session()`)
|
|
- Registers well-known name `org.freedesktop.Notifications` on the session bus
|
|
|
|
## References
|
|
- [Desktop Notifications Specification](https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html) v1.2
|
|
- Conformance: Full Notify/CloseNotification/GetCapabilities/GetServerInformation. Action invocation with ownership validation. Expiry sweeper. Sender reaper for vanished bus names. Bounded notification store (1024 max). No persistence across restarts. No sound/image/hint processing beyond storage. No idle tracking.
|