garwarp Public

Watch 0 Fork 0 Star 0
markdown · 2754 bytes Raw Blame History

garwarp

garwarp is the Gardesk XDG desktop portal backend project.

Primary scope for the first implementation track:

  1. Screenshot portal backend flows.
  2. OpenURI/OpenFile portal backend flows.
  3. App chooser and app-integration portal flows.

Planning documents live in docs/ and are currently local-only.

Current Status

  1. Sprint 01 complete: workspace, daemon lifecycle, control protocol scaffold, activation files.
  2. Sprint 02 complete: control-plane hardening (idempotence, parser strictness, trusted peers, store durability/fallback, health recovery policy).
  3. Sprint 03 in progress: screenshot/filechooser/appchooser interfaces export method skeletons at /org/freedesktop/portal/desktop.
  4. Request-handle parsing and deterministic request-id derivation are implemented (/org/freedesktop/portal/desktop/request/<sender>/<token> model).
  5. DBus method handling derives caller identity from message headers and rejects mismatched request-handle ownership.
  6. Typed option parsing foundations are in place for screenshot/filechooser/appchooser known keys.
  7. DBus method dispatch now registers request lifecycle state through an internal portal dispatcher (current placeholder path ends in failed).

Local Commands

  1. Start daemon: cargo run -p garwarp -- daemon
  2. Check health and request counters: cargo run -p garwarpctl -- status
  3. Stop daemon: cargo run -p garwarpctl -- stop
  4. Verify D-Bus activation: ./scripts/test-dbus-activation.sh
  5. Verify DBus interfaces are exported: ./scripts/test-dbus-interfaces.sh
  6. Verify DBus method dispatch: ./scripts/test-dbus-method-dispatch.sh
  7. Verify request-store fallback: ./scripts/test-request-store-fallback.sh
  8. Run direct portal smoke calls: cargo run -p garwarpctl -- portal-smoke
  9. Create mock request: cargo run -p garwarpctl -- begin req-1 :1.2 - x11:0x2a
  10. Transition mock request: cargo run -p garwarpctl -- transition req-1 :1.2 awaiting_user
  11. List known requests: cargo run -p garwarpctl -- list
  12. Inspect request snapshot: cargo run -p garwarpctl -- inspect req-1

Runtime Tuning

  1. GARWARP_REQUEST_TIMEOUT_MS: timeout before in-flight requests are marked expired.
  2. GARWARP_TERMINAL_RETENTION_MS: retention window before terminal requests are pruned.

Control Protocol Compatibility

  1. Protocol version is reported by status protocol=<n> and currently fixed at v1.
  2. Unknown or duplicate request fields are rejected as invalid_request (fail-closed parsing).
  3. Stable error reasons are part of the control contract; new reasons may be added, existing reasons should not be repurposed.
  4. Sender identity for begin/transition is derived from Unix peer credentials; payload sender is ignored for ownership.
View source
1 # garwarp
2
3 `garwarp` is the Gardesk XDG desktop portal backend project.
4
5 Primary scope for the first implementation track:
6 1. Screenshot portal backend flows.
7 2. OpenURI/OpenFile portal backend flows.
8 3. App chooser and app-integration portal flows.
9
10 Planning documents live in `docs/` and are currently local-only.
11
12 ## Current Status
13 1. Sprint 01 complete: workspace, daemon lifecycle, control protocol scaffold, activation files.
14 2. Sprint 02 complete: control-plane hardening (idempotence, parser strictness, trusted peers, store durability/fallback, health recovery policy).
15 3. Sprint 03 in progress: screenshot/filechooser/appchooser interfaces export method skeletons at `/org/freedesktop/portal/desktop`.
16 4. Request-handle parsing and deterministic request-id derivation are implemented (`/org/freedesktop/portal/desktop/request/<sender>/<token>` model).
17 5. DBus method handling derives caller identity from message headers and rejects mismatched request-handle ownership.
18 6. Typed option parsing foundations are in place for screenshot/filechooser/appchooser known keys.
19 7. DBus method dispatch now registers request lifecycle state through an internal portal dispatcher (current placeholder path ends in `failed`).
20
21 ## Local Commands
22 1. Start daemon: `cargo run -p garwarp -- daemon`
23 2. Check health and request counters: `cargo run -p garwarpctl -- status`
24 3. Stop daemon: `cargo run -p garwarpctl -- stop`
25 4. Verify D-Bus activation: `./scripts/test-dbus-activation.sh`
26 5. Verify DBus interfaces are exported: `./scripts/test-dbus-interfaces.sh`
27 6. Verify DBus method dispatch: `./scripts/test-dbus-method-dispatch.sh`
28 7. Verify request-store fallback: `./scripts/test-request-store-fallback.sh`
29 8. Run direct portal smoke calls: `cargo run -p garwarpctl -- portal-smoke`
30 9. Create mock request: `cargo run -p garwarpctl -- begin req-1 :1.2 - x11:0x2a`
31 10. Transition mock request: `cargo run -p garwarpctl -- transition req-1 :1.2 awaiting_user`
32 11. List known requests: `cargo run -p garwarpctl -- list`
33 12. Inspect request snapshot: `cargo run -p garwarpctl -- inspect req-1`
34
35 ## Runtime Tuning
36 1. `GARWARP_REQUEST_TIMEOUT_MS`: timeout before in-flight requests are marked `expired`.
37 2. `GARWARP_TERMINAL_RETENTION_MS`: retention window before terminal requests are pruned.
38
39 ## Control Protocol Compatibility
40 1. Protocol version is reported by `status protocol=<n>` and currently fixed at `v1`.
41 2. Unknown or duplicate request fields are rejected as `invalid_request` (fail-closed parsing).
42 3. Stable error reasons are part of the control contract; new reasons may be added, existing reasons should not be repurposed.
43 4. Sender identity for begin/transition is derived from Unix peer credentials; payload `sender` is ignored for ownership.