From 7509c909e139bcf62812b97aff8139510e631fe0 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 13:09:07 -0500 Subject: [PATCH 01/20] E00: freeze the mail.exportEml contract, capabilities, and limits - planning/decisions/E00.md traces the current auth-to-IMAP-to-resource path, the raw literal extraction point, cancellation/deadline ownership, Downloads and filename policy, and freezes the RPC shape with an error table and owning modules - records four values needing sign-off: param names (account/id vs the plan's accountId/messageId), the deadline (60s cannot fit the 25s RPC timeout; propose 20s), the 25 MiB limit, and 1-per-account/2-global concurrency - STATE: E00 READY FOR REVIEW --- planning/STATE.md | 2 +- planning/decisions/E00.md | 197 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 planning/decisions/E00.md diff --git a/planning/STATE.md b/planning/STATE.md index 9827ad7..aefc23f 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -28,7 +28,7 @@ Updated: 2026-09-29. This file records facts; planned actions are not completed | S02 | WAITING FOR S01 | — | | S03 | WAITING FOR S02 | — | | S04 | WAITING FOR S03 | — | -| E00 | READY FOR ASSIGNMENT | F00 accepted at `880d410` | +| E00 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/decisions/E00.md` (base `d88833e`) | | E01 | WAITING FOR E00 | — | | E02 | WAITING FOR E01 | — | | E03 | WAITING FOR E02 | — | diff --git a/planning/decisions/E00.md b/planning/decisions/E00.md new file mode 100644 index 0000000..1942731 --- /dev/null +++ b/planning/decisions/E00.md @@ -0,0 +1,197 @@ +# E00 decision — export contract, capabilities, and limits + +Status: **READY FOR REVIEW** — supervisor sign-off required on §6 before E01/E02. +Task: E00. Base: `d88833e` (main after F00). Branch: `task/E00-export-contract`. +Owner-authorized reading only; no production export code was written. + +This record traces the current path, freezes the `mail.exportEml` contract, and +records four values that differ from the plan's proposal. All file/line +references are to this base. + +## 1. Traced path today (auth → IMAP → resource) + +- Dispatch: `src/backend/mod.rs:66` routes `mail.list|read|act|send` to + `Session::mail_call`; `src/backend/mail.rs:340-367` matches those four and + returns `unknown_method` for anything else. A new method must be added in both + places. +- Domain: `mail.read` builds `ReadRequest { account, id }` (`src/mail/types.rs:110`) + and calls `crate::mail::read::read_with` (`src/mail/read.rs:243`), which calls + the provider adapter `reader.open` and then projects a safe reader. **The + reader never keeps the raw bytes** — it parses them into a display projection. +- Provider: `ProviderRead` (`src/backend/mail.rs:14`) forwards to + `imap.read`, which lands in `src/providers/imap/read.rs`. +- Wire: `messages()` (`src/providers/imap/read.rs:694`) issues + `UID FETCH {set} (UID FLAGS INTERNALDATE RFC822.SIZE BODY.PEEK[{section}])` + (line 755), with `section=""` for a full fetch. Response framing lives in + `src/providers/imap/mod.rs` (`nodes`, literal handling at 161-186); + `command()` (line 193) returns the whole response as `Vec`. +- **Raw literal extraction point:** `parse_messages()` (`read.rs:649`) records + `raw = Some(value.text())` for a `BODY[...]` field (line 682) — `Node::text()` + returns the literal octets — then immediately calls + `crate::message::parse(raw)` (line 689) and **discards `raw`**. E01 must retain + exactly these octets for the requested UID; parse-then-reserialize is not an + acceptable byte source. +- Account resolution: `src/mail/account.rs:3` `resolve_account("")` **falls back + to the registry's `activeId`**. The plan (§3.2) forbids that for export. Export + must resolve strictly (non-empty id, exact registry match) and never reuse the + fallback. + +## 2. Cancellation and deadlines + +- Per-request cancellation: `src/providers/imap/cancel.rs`. Key is + `(accountId, requestToken)`; `cancel()` sets a flag and notifies; `run()` races + the future and returns `request_cancelled`; entries are retained 60 s and + capped at 1024. `imap.cancel` is the entry point. +- **Transport deadline: `src/backend/protocol.rs:15` sets + `REQUEST_TIMEOUT = 25 s`**, and every frame is dispatched with + `deadline = now + 25 s` (`protocol.rs:42,62`). IMAP operations already use a + **22 s** inner timeout to stay under it (`src/providers/imap/mod.rs:397,445,491`). +- **Consequence:** the plan's proposed **60 s** export deadline cannot fit the + current dispatch without changing the global request timeout, which the plan + forbids. See §6 O2. +- Other bounds: IMAP response `LIMIT = 32 MiB` (`imap/mod.rs:21`); protocol + `MAX_RESPONSE = 64 MiB` (`protocol.rs:12`); attachment payload + `MAX_BYTES = 20 MiB` (`attachment/mod.rs:13`). + +## 3. Storage, Downloads, and filenames + +- Downloads root: `crate::platform::dirs::AppDirs::discover()?.downloads` + (`src/platform/dirs.rs:18`), resolved from `XDG_DOWNLOAD_DIR`, then + `user-dirs.dirs`, then `~/Downloads`; the value must be absolute + (`dirs.rs:171`). `AppDirs::discover` itself validates every root is absolute + and parent-free. +- Existing writer to reuse as a model: `attachment::write_unique` + (`src/attachment/mod.rs:225`) — `create_new(true)` (exclusive, never + overwrites), mode `0600`, `O_NOFOLLOW`, `write_all` + `sync_all`, and + `remove_file` of the partial on failure; collision suffix is + `stem (n).ext` for n in 1..1000. `attachment::store` (line 192) resolves + Downloads and `create_dir_all`s it. Attachment `MAX_BYTES` (20 MiB) is lower + than the export limit, so export needs its own bounded writer rather than the + attachment payload/RPC route. +- Filename policy model: `attachment::safe_filename` (`attachment/mod.rs:15`) — + basename only (strips `/` and `\`), control chars to `_`, trims, `attachment` + fallback, 240-byte cap preserving the extension. + +## 4. Frozen contract + +**Method:** `mail.exportEml` (provider-neutral; Outlook and generic IMAP only). + +**Params** + +```json +{"account":"outlook:person@example.test","id":"42:INBOX","suggestedName":"Project update"} +``` + +- `account` — **required, non-empty**; exact registry id; unknown → + `mail_account_unknown`. No active-account fallback, no control characters, + bounded length. +- `id` — **required**, `":"` (see `message_id`, `imap/read.rs:577`). + Empty/unknown account or malformed id is rejected before any credential lookup + or network work. +- `suggestedName` — optional, untrusted display hint; never a path. +- No output-directory, format, provider-URL, or credential parameters. + +**Result** + +```json +{"accountId":"outlook:person@example.test","messageId":"42:INBOX", + "path":"/home/u/Downloads/Project update.eml","filename":"Project update.eml","bytes":12345} +``` + +**Errors** (`Err("invalid_params")` maps to -32602; every other string to -32000 +with the string as the message — `src/backend/rpc.rs:137`) + +| Condition | message | JSON-RPC code | +| --- | --- | --- | +| malformed types / extra fields | `invalid_params` | -32602 | +| empty or unknown account | `mail_account_unknown` | -32000 | +| provider not Outlook/IMAP | `mail_export_unsupported` | -32000 | +| malformed uid/folder | `mail_export_message_invalid` | -32000 | +| requested message absent / NIL body | `mail_export_message_missing` | -32000 | +| announced literal above the limit | `mail_export_too_large` | -32000 | +| truncated or ambiguous literal | `mail_export_incomplete` | -32000 | +| write/flush/commit failure | `mail_export_write_failed` | -32000 | +| cancelled before commit | `request_cancelled` | -32000 | +| method absent on the connected binary | `backend_needs_update` | -32012 | + +**Capability and identity** + +- Provider capability name: **`emlExport`**, exposed through the shared provider + mapping and QML projection (not scattered provider-id checks). +- Method presence is checked independently of the API number: the method is named + in `backend-api.json` under `methods` and under `unreleased.methods`, and + `ui/backend/Compatibility.js::unreleasedRefusal` returns + `{-32012,"backend_needs_update"}` when the connected binary lacks it. A feature + must gate on method support, not on `apiVersion` alone. + +**Limits and concurrency** (values — see §6 decisions) + +| Knob | Value | Basis | +| --- | --- | --- | +| raw message size | **25 MiB** | below IMAP `LIMIT` 32 MiB; above attachment 20 MiB | +| in-flight per account | **1** | duplicates for the same account/message refused | +| in-flight global | **2** | bounded, below the 4 used by `messages()` | +| operation deadline | **20 s** (proposed; plan said 60 s) | under the 25 s `REQUEST_TIMEOUT` | + +**Storage and completion** + +- Write under `AppDirs::downloads` using a bounded writer modeled on + `write_unique`: exclusive `create_new`, `0600`, `O_NOFOLLOW`, `write_all` + + `sync_all`, remove the partial on any failure. Never overwrite an existing + file; on collision append ` (n)` before `.eml`. +- Filename: apply the `safe_filename` policy to `suggestedName`, strip separators + and control characters, refuse platform-reserved forms, fall back to + `message`, and append `.eml` exactly once (never double up an existing `.eml`). +- **Cancellation commit point:** cancellation is honoured up to the exclusive + create; once bytes are written and fsynced the operation **returns success** + with the real path. A cancel that loses the race must not report both failure + and a committed file. +- Success is emitted only after a complete, committed file; the result reports + the actual filename, directory, and byte count. Unsigned/raw errors never reach + the UI; existing safe error strings are reused. + +**Owning modules** + +| Concern | Module | +| --- | --- | +| routing | `src/backend/mod.rs` (extend the `mail.*` match) | +| RPC arm | `src/backend/mail.rs` (`mail_call`) | +| domain service | new `src/mail/export.rs` | +| raw retrieval | `src/providers/imap/read.rs` or a new `.../imap/export.rs` (reuse `acquire`/`command`/`release`, `nodes`) | +| storage / Downloads | `src/platform/private_fs*`, `src/platform/dirs.rs` | +| contract | `backend-api.json` | + +## 5. Evidence + +Reproduction of the decisive reads: + +``` +sed -n '15,15p;42,42p' src/backend/protocol.rs # REQUEST_TIMEOUT = 25 s +sed -n '21,22p' src/providers/imap/mod.rs # LIMIT = 32 MiB +sed -n '755,755p' src/providers/imap/read.rs # BODY.PEEK[] fetch +sed -n '682,689p' src/providers/imap/read.rs # raw literal then parse+discard +sed -n '13,13p;225,255p' src/attachment/mod.rs # 20 MiB; exclusive writer +sed -n '163,169p' src/mail/types.rs # active-account fallback +sed -n '66,66p' src/backend/mod.rs # mail.* routing match +sed -n '137,138p' src/backend/rpc.rs # error code mapping +``` + +`python3 scripts/package-backend.py check-api` currently passes (exit 0); the +contract is API 6 / released 5 with an empty `unreleased.methods` list. + +## 6. Decisions required before E01/E02 + +- **O1 — param names.** The plan's example used `accountId`/`messageId`, but every + sibling `mail.*` method uses **`account`** and **`id`** (`src/mail/types.rs:236,268`). + **Recommendation:** use `account`/`id` for consistency (export stays a `mail.*`), + and document `suggestedName`. Confirm or override. +- **O2 — deadline.** The plan's **60 s** cannot fit the global **25 s** RPC + deadline without loosening it (forbidden). **Recommendation:** freeze **20 s** + (matching the existing 22 s IMAP inner timeout with headroom), or authorize a + per-method protocol deadline as a separate, reviewed change. +- **O3 — 25 MiB raw limit.** Fits below the 32 MiB IMAP response bound and above + the 20 MiB attachment limit; confirm, or revise. +- **O4 — concurrency.** Confirm 1 per account / 2 global, enforced with a + semaphore in the new domain service (existing `messages()` uses 4 unordered). + +Escalate if O1/O2 change the agreed shape: E01/E02 are gated on this record. From b73083021f519b64dd5f5268222e0ed3267d81a3 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 13:11:24 -0500 Subject: [PATCH 02/20] E00: record the confirmed export decisions - O1 account/id, O2 25s deadline enforced inside the export, O3 25 MiB, O4 1-per-account/2-global - correct the deadline analysis: the RPC layer bounds only gmail.* and uploads, so mail.* owns its deadline; the binding outer bound is the client's 30s bridge deadline (Backend.qml:110) - add the request_timed_out error row and the enforcement-ownership evidence --- planning/decisions/E00.md | 60 +++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/planning/decisions/E00.md b/planning/decisions/E00.md index 1942731..a4adc36 100644 --- a/planning/decisions/E00.md +++ b/planning/decisions/E00.md @@ -1,6 +1,7 @@ # E00 decision — export contract, capabilities, and limits -Status: **READY FOR REVIEW** — supervisor sign-off required on §6 before E01/E02. +Status: **READY FOR REVIEW** — decisions confirmed by the owner on 2026-09-29 +(§6); supervisor sign-off on the frozen record still required before E01/E02. Task: E00. Base: `d88833e` (main after F00). Branch: `task/E00-export-contract`. Owner-authorized reading only; no production export code was written. @@ -42,13 +43,20 @@ references are to this base. `(accountId, requestToken)`; `cancel()` sets a flag and notifies; `run()` races the future and returns `request_cancelled`; entries are retained 60 s and capped at 1024. `imap.cancel` is the entry point. -- **Transport deadline: `src/backend/protocol.rs:15` sets - `REQUEST_TIMEOUT = 25 s`**, and every frame is dispatched with - `deadline = now + 25 s` (`protocol.rs:42,62`). IMAP operations already use a - **22 s** inner timeout to stay under it (`src/providers/imap/mod.rs:397,445,491`). -- **Consequence:** the plan's proposed **60 s** export deadline cannot fit the - current dispatch without changing the global request timeout, which the plan - forbids. See §6 O2. +- RPC deadline: `REQUEST_TIMEOUT = 25 s` (`src/backend/protocol.rs:15`), and every + frame is tagged `now + 25 s` (`protocol.rs:42,62`). But it is only *enforced* + with `timeout_at` for `gmail.*` and `request.upload` of gmail methods + (`src/backend/rpc.rs:120-127`); every other method, including `mail.*`, is + dispatched with **no RPC-level timeout**, the 25 s acting only as a + pre-dispatch expiry check (line 113). Mail operations therefore own their + deadlines, and IMAP already uses **22 s** inner timeouts + (`src/providers/imap/mod.rs:397,445,491`). +- Client deadline: the QML bridge fails a request after **30 s** + (`ui/backend/Backend.qml:110-111`; 65 s for `agent.context`). This is the real + outer bound a user experiences. +- **Consequence:** `mail.exportEml` must enforce its own deadline inside the + operation (as `mail.read` does) and finish under the client's 30 s. The frozen + value is **25 s** (§6 O2), leaving about 5 s for the reply to be written. - Other bounds: IMAP response `LIMIT = 32 MiB` (`imap/mod.rs:21`); protocol `MAX_RESPONSE = 64 MiB` (`protocol.rs:12`); attachment payload `MAX_BYTES = 20 MiB` (`attachment/mod.rs:13`). @@ -112,6 +120,7 @@ with the string as the message — `src/backend/rpc.rs:137`) | truncated or ambiguous literal | `mail_export_incomplete` | -32000 | | write/flush/commit failure | `mail_export_write_failed` | -32000 | | cancelled before commit | `request_cancelled` | -32000 | +| operation deadline reached before commit | `request_timed_out` | -32000 | | method absent on the connected binary | `backend_needs_update` | -32012 | **Capability and identity** @@ -131,7 +140,7 @@ with the string as the message — `src/backend/rpc.rs:137`) | raw message size | **25 MiB** | below IMAP `LIMIT` 32 MiB; above attachment 20 MiB | | in-flight per account | **1** | duplicates for the same account/message refused | | in-flight global | **2** | bounded, below the 4 used by `messages()` | -| operation deadline | **20 s** (proposed; plan said 60 s) | under the 25 s `REQUEST_TIMEOUT` | +| operation deadline | **25 s**, enforced inside the export | under the client's 30 s bridge deadline; honours no partial file | **Storage and completion** @@ -173,25 +182,26 @@ sed -n '682,689p' src/providers/imap/read.rs # raw literal then parse sed -n '13,13p;225,255p' src/attachment/mod.rs # 20 MiB; exclusive writer sed -n '163,169p' src/mail/types.rs # active-account fallback sed -n '66,66p' src/backend/mod.rs # mail.* routing match +sed -n '113,127p' src/backend/rpc.rs # mail.* runs without an RPC deadline +sed -n '110,111p' ui/backend/Backend.qml # client request deadline 30 s sed -n '137,138p' src/backend/rpc.rs # error code mapping ``` `python3 scripts/package-backend.py check-api` currently passes (exit 0); the contract is API 6 / released 5 with an empty `unreleased.methods` list. -## 6. Decisions required before E01/E02 - -- **O1 — param names.** The plan's example used `accountId`/`messageId`, but every - sibling `mail.*` method uses **`account`** and **`id`** (`src/mail/types.rs:236,268`). - **Recommendation:** use `account`/`id` for consistency (export stays a `mail.*`), - and document `suggestedName`. Confirm or override. -- **O2 — deadline.** The plan's **60 s** cannot fit the global **25 s** RPC - deadline without loosening it (forbidden). **Recommendation:** freeze **20 s** - (matching the existing 22 s IMAP inner timeout with headroom), or authorize a - per-method protocol deadline as a separate, reviewed change. -- **O3 — 25 MiB raw limit.** Fits below the 32 MiB IMAP response bound and above - the 20 MiB attachment limit; confirm, or revise. -- **O4 — concurrency.** Confirm 1 per account / 2 global, enforced with a - semaphore in the new domain service (existing `messages()` uses 4 unordered). - -Escalate if O1/O2 change the agreed shape: E01/E02 are gated on this record. +## 6. Decisions (supervisor confirmed 2026-09-29) + +- **O1 — param names: `account` + `id`.** Matches every sibling `mail.*` method + (`src/mail/types.rs:236,268`). `suggestedName` is the optional display hint. +- **O2 — deadline: 25 s**, enforced *inside* the export operation (the RPC layer + does not bound `mail.*`; see §2). It sits under the client's 30 s bridge + deadline (`ui/backend/Backend.qml:110`), leaving room for the reply. Reaching it + returns `request_timed_out` and must leave no partial file. +- **O3 — raw size limit: 25 MiB**, below the 32 MiB IMAP response bound and above + the 20 MiB attachment limit. +- **O4 — concurrency: 1 per account, 2 global**, enforced with a semaphore in the + new domain service. + +E01 and E02 are gated on this record. A change to the method name, params, +result shape, or error table is a contract revision and needs a new judgment. From 19d8a79773c105567ef5cd51d1fbefe7344c2b86 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 13:22:15 -0500 Subject: [PATCH 03/20] E01: retrieve exact original IMAP message bytes - src/providers/imap/export.rs: internal imap.rawMessage operation that EXAMINEs read-only, fetches one UID with BODY.PEEK[], and returns the exact literal octets; ignores unsolicited UIDs and refuses NIL/missing/duplicate bodies; cancel-aware - not in the advertised inventory (like the internal jmap.action* planners), so QML cannot reach it and the API contract is unchanged - read.rs shares Node/nodes with pub(super); mod.rs validates before any socket - tests: 6 synthetic-server tests incl. a byte-for-byte payload with CRLF, folded headers, 8-bit and NUL octets, and forged-tag text - evidence: planning/evidence/E01.md; STATE: E01 READY FOR REVIEW --- planning/STATE.md | 2 +- planning/evidence/E01.md | 85 +++++++++++++++++ src/providers/imap/export.rs | 95 +++++++++++++++++++ src/providers/imap/mod.rs | 6 ++ src/providers/imap/read.rs | 12 +-- src/providers/imap/tests.rs | 174 +++++++++++++++++++++++++++++++++++ 6 files changed, 367 insertions(+), 7 deletions(-) create mode 100644 planning/evidence/E01.md create mode 100644 src/providers/imap/export.rs diff --git a/planning/STATE.md b/planning/STATE.md index aefc23f..640800f 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -29,7 +29,7 @@ Updated: 2026-09-29. This file records facts; planned actions are not completed | S03 | WAITING FOR S02 | — | | S04 | WAITING FOR S03 | — | | E00 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/decisions/E00.md` (base `d88833e`) | -| E01 | WAITING FOR E00 | — | +| E01 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E01.md` (base `b730830`) | | E02 | WAITING FOR E01 | — | | E03 | WAITING FOR E02 | — | | I00 | WAITING FOR S04 + E03 | — | diff --git a/planning/evidence/E01.md b/planning/evidence/E01.md new file mode 100644 index 0000000..9c58654 --- /dev/null +++ b/planning/evidence/E01.md @@ -0,0 +1,85 @@ +# E01 evidence — exact original message bytes + +Status: **READY FOR REVIEW**. Task: E01. Base: `b730830` (E00 branch tip). +Branch: `task/E01-raw-message`. Depends on the E00 contract (`planning/decisions/E00.md`). + +Adds the native raw-retrieval operation only. It is **not** wired to +`mail.exportEml` and is not reachable from QML: no storage, no RPC surface, no +capability declaration (those are E02). + +## What was added + +- `src/providers/imap/export.rs` — an internal provider operation + `imap.rawMessage` that returns the server's literal octets unchanged. + - `EXAMINE` selects the mailbox read-only and `UID FETCH + (UID BODY.PEEK[])` requests the body, so `\Seen`, flags, and message + location are untouched and no `STORE`/`MOVE`/`EXPUNGE` is ever issued. + - `single_literal()` takes exactly one literal for the requested UID from the + framed response; an unrelated unsolicited UID is ignored, and `NIL`, a + missing record, or two literals for the requested UID are refused. + - Result: `{"bytes": , "data": }`. Base64 is the provider + boundary's existing convention (`imap.request`, `attachment.read`); E02 + decodes and writes it without the bytes ever reaching QML. +- `src/providers/imap/mod.rs` — `mod export;`; `export::validate` is run before + any credential lookup or socket; `imap.rawMessage` is routed in `execute` and + included in the `cancel::run` set so `imap.cancel` cancels it. +- `src/providers/imap/read.rs` — `Node`, its accessors, and `nodes()` become + `pub(super)`, the narrowly shared parsing helper E00 §1 identified. + +`imap.rawMessage` is deliberately **absent from `src/backend/methods.rs`** (the +advertised inventory), like the internal `jmap.action*` planners. The inventory +is unchanged, so `check-api` and the binary's advertised method list are +unaffected. QML is forbidden by `tests/test_source.sh` from calling an +undeclared method anyway. + +## Identity and validation + +`export::validate` rejects a malformed folder (quoting/controls) or a `uid` that +is absent, zero, or out of `u32` range with `mail_export_message_invalid` +**before any connection opens** (asserted by a test). Provider/account +resolution and the strict no-active-account-fallback rule belong to E02, which +supplies the resolved settings this operation consumes. + +## Error strings (E01 level → E00 boundary) + +| E01 | E00 `mail.exportEml` | +| --- | --- | +| `mail_export_message_invalid` | `mail_export_message_invalid` | +| `mail_export_message_missing` (missing record or `NIL`) | `mail_export_message_missing` | +| `mail_export_incomplete` (duplicate literal) | `mail_export_incomplete` | +| `imap_command_failed` (tagged NO/BAD) | provider failure | +| `mail_response_too_large` (literal/response over the 32 MiB `LIMIT`) | `mail_export_too_large` | +| `mail_network_failed`, `imap_invalid_response` | provider failure | + +E02 owns the final mapping and the 25 MiB product limit (below the transport's +32 MiB bound). + +## Tests (`src/providers/imap/tests.rs`, synthetic loopback server) + +| Test | Proves | +| --- | --- | +| `raw_message_returns_exact_octets_and_only_peeks` | bytes returned **byte-for-byte**: CRLF, folded header, `\xc3\xa9`, `\x00`, `\xff`, and a payload that imitates a tagged completion and another FETCH record; the only data command is `UID FETCH 1 (UID BODY.PEEK[])` after `EXAMINE` | +| `raw_message_ignores_unsolicited_and_other_uids` | an unrelated `UID 999` FETCH is ignored; the requested UID's bytes are returned | +| `raw_message_refuses_missing_nil_and_duplicate_bodies` | `NIL` → missing; other-UID-only → missing; two literals for the requested UID → incomplete | +| `raw_message_refuses_a_non_ok_completion` | tagged `NO` → `imap_command_failed` | +| `raw_message_rejects_a_bad_uid_before_connecting` | `uid:0` is refused with no connection opened | +| `cancelling_a_raw_message_read_stops_the_work` | `imap.cancel` drops the in-flight fetch and returns `request_cancelled` | + +## Verification run + +``` +cargo test --locked --lib providers::imap::tests # 24 passed, 0 failed +cargo test --locked --features integration-test-credentials +# 561 lib + 1 + 1 + 33 + 5 + 4 + 1 + 7 + 9 + 4 + 3 + 4 passed; 0 failed +python3 scripts/package-backend.py check-api # exit 0, inventory unchanged +python3 tests/test_backend_api.py --binary target/debug/omamail +# "Backend API 6 contract PASS: 30 methods, 178 advertised methods" +cargo clippy --locked --all-targets # no findings in the new code +``` + +## Not done here (E02) + +Explicit account resolution (strict, no active fallback), the 25 MiB bound and +oversize refusal, Downloads/storage with exclusive non-overwriting publication, +the `mail.exportEml` RPC arm and contract cases, the provider capability, and +the QML availability projection. diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs new file mode 100644 index 0000000..debaa58 --- /dev/null +++ b/src/providers/imap/export.rs @@ -0,0 +1,95 @@ +//! Exact raw-message retrieval for export. The octets the server sends are +//! returned unchanged: nothing here parses the message or re-serializes it. +//! +//! Internal to the provider layer and deliberately absent from the advertised +//! public method inventory (`src/backend/methods.rs`), like the internal +//! `jmap.action*` planners. `mail.exportEml` (E02) consumes it. +use super::*; + +/// Validate the export parameters before any socket is opened. +pub(super) fn validate(method: &str, p: &Value) -> Result<()> { + if method != "imap.rawMessage" { + return Ok(()); + } + quote(p["folder"].as_str().ok_or("invalid_params")?)?; + requested_uid(p)?; + Ok(()) +} + +fn requested_uid(p: &Value) -> Result { + p["uid"] + .as_u64() + .filter(|n| *n > 0 && *n <= u32::MAX as u64) + .map(|n| n as u32) + .ok_or("mail_export_message_invalid") +} + +pub(super) async fn call(p: &Value) -> Result { + let folder = p["folder"].as_str().ok_or("invalid_params")?; + let bytes = raw_message(p, requested_uid(p)?, folder).await?; + Ok(json!({"bytes": bytes.len(), "data": STANDARD.encode(&bytes)})) +} + +/// Fetch one UID's complete message and return the server's literal octets. +/// `BODY.PEEK[]` keeps `\Seen` unchanged, and `EXAMINE` selects the mailbox +/// read-only, so nothing here changes flags, message location, or mailbox +/// state such as `\Recent`. +pub(super) async fn raw_message(p: &Value, uid: u32, folder: &str) -> Result> { + let (mut w, key) = acquire(p).await?; + let result = fetch_literal(&mut w, uid, folder).await; + release(w, key).await; + result +} + +async fn fetch_literal(w: &mut Wire, uid: u32, folder: &str) -> Result> { + command(w, &format!("EXAMINE {}", quote(folder)?)).await?; + let data = command(w, &format!("UID FETCH {uid} (UID BODY.PEEK[])")).await?; + single_literal(&data, uid) +} + +/// Exactly one literal for the requested UID. Unsolicited records for other +/// UIDs are ignored; a missing record, a `NIL` body, or two literals for the +/// requested UID are refused. The literal is length-framed, so a payload that +/// merely looks like a tagged completion or another FETCH record cannot be +/// mistaken for one. +fn single_literal(data: &[u8], uid: u32) -> Result> { + let mut found: Option> = None; + for row in read::nodes(data)? { + if row.len() < 4 || !row[0].is("*") || !row[2].is("FETCH") { + continue; + } + let fields = row[3].list(); + let mut row_uid = None; + let mut body: Option>> = None; + let mut i = 0; + while i + 1 < fields.len() { + let key = &fields[i]; + let value = &fields[i + 1]; + if key.is("UID") { + row_uid = value.number(); + } else if key.text().to_ascii_uppercase().starts_with(b"BODY[") { + // `BODY[] NIL` is a present but empty body, not a literal. + body = Some(if value.is("NIL") { + None + } else { + Some(value.text().to_vec()) + }); + } + i += 2; + } + if row_uid != Some(uid) { + continue; + } + match body { + Some(Some(bytes)) => { + if found.is_some() { + return Err("mail_export_incomplete"); + } + found = Some(bytes); + } + Some(None) => return Err("mail_export_message_missing"), + None => continue, + } + } + found.ok_or("mail_export_message_missing") +} diff --git a/src/providers/imap/mod.rs b/src/providers/imap/mod.rs index 6707fd6..0f6aca8 100644 --- a/src/providers/imap/mod.rs +++ b/src/providers/imap/mod.rs @@ -1,5 +1,6 @@ //! Native asynchronous IMAP and SMTP. Credentials never cross a process boundary. mod cancel; +mod export; pub(crate) mod idle; mod mutation; mod read; @@ -469,6 +470,7 @@ pub(crate) async fn execute_planned_action( pub async fn call(method: &str, p: &Value) -> Result { read::validate(method, p)?; mutation::validate(method, p)?; + export::validate(method, p)?; if method == "imap.cancel" { return cancel::cancel(p).await; } @@ -480,6 +482,7 @@ pub async fn call(method: &str, p: &Value) -> Result { | "imap.messages" | "imap.count" | "imap.attachment" + | "imap.rawMessage" | "imap.check" ) { return cancel::run(p, call_inner(method, p)).await; @@ -577,6 +580,9 @@ fn unsafe_fetch(command: &str) -> bool { } async fn execute(method: &str, p: &Value, sent: &std::sync::atomic::AtomicBool) -> Result { credentials(p)?; + if method == "imap.rawMessage" { + return export::call(p).await; + } if matches!( method, "imap.folders" diff --git a/src/providers/imap/read.rs b/src/providers/imap/read.rs index 9a11225..40fc751 100644 --- a/src/providers/imap/read.rs +++ b/src/providers/imap/read.rs @@ -4,33 +4,33 @@ use base64::engine::general_purpose::{STANDARD_NO_PAD, URL_SAFE_NO_PAD}; use std::collections::{BTreeMap, BTreeSet}; mod search; #[derive(Clone, Debug, PartialEq)] -enum Node { +pub(super) enum Node { Text(Vec), List(Vec), End, } impl Node { - fn text(&self) -> &[u8] { + pub(super) fn text(&self) -> &[u8] { if let Self::Text(t) = self { t } else { b"" } } - fn is(&self, value: &str) -> bool { + pub(super) fn is(&self, value: &str) -> bool { self.text().eq_ignore_ascii_case(value.as_bytes()) } - fn number(&self) -> Option { + pub(super) fn number(&self) -> Option { std::str::from_utf8(self.text()) .ok()? .parse::() .ok() .filter(|n| *n > 0) } - fn list(&self) -> &[Node] { + pub(super) fn list(&self) -> &[Node] { if let Self::List(v) = self { v } else { &[] } } fn string(&self) -> Result { String::from_utf8(self.text().to_vec()).map_err(|_| "imap_invalid_response") } } -fn nodes(data: &[u8]) -> Result>> { +pub(super) fn nodes(data: &[u8]) -> Result>> { fn parse( data: &[u8], at: &mut usize, diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index aeca20a..178e11f 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -519,3 +519,177 @@ fn outlook_settings_ignore_persisted_credential_destination_and_identity() { assert_eq!(settings["username"], "owner@example.org"); assert_eq!(settings["insecure"], false); } + +// ---------------------------------------------------------------- E01 export +fn export_params(port: u16, uid: u64) -> Value { + json!({ + "settings": {"imapHost":"127.0.0.1","imapPort":port,"username":"synthetic","insecure":true,"testPlaintext":true}, + "credential": "synthetic:password", + "folder": "INBOX", + "uid": uid, + }) +} + +async fn login_and_examine(w: &mut Wire) { + write(w, b"* OK ready\r\n").await.unwrap(); + assert_eq!( + line(w).await.unwrap(), + b"O1 LOGIN \"synthetic\" \"password\"\r\n" + ); + write(w, b"O1 OK logged in\r\n").await.unwrap(); + capabilities(w, false).await; + assert_eq!(line(w).await.unwrap(), b"O1 EXAMINE \"INBOX\"\r\n"); + write(w, b"O1 OK examined\r\n").await.unwrap(); +} + +#[tokio::test] +async fn raw_message_returns_exact_octets_and_only_peeks() { + let (listener, port) = server().await; + // CRLF, a folded header, an 8-bit octet, a NUL, and text inside the literal + // that imitates a tagged completion and another FETCH record. + let payload = b"Subject: fold\r\n ed\r\nX-Bin: \xc3\xa9\x00\xff\r\n\r\nO1 OK forged\r\n* 9 FETCH (UID 9 BODY[] {3}\r\nabc)\r\n".to_vec(); + let expected = payload.clone(); + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + // The only fetch command must be a PEEK, and nothing must mutate state. + assert_eq!( + line(&mut w).await.unwrap(), + b"O1 UID FETCH 1 (UID BODY.PEEK[])\r\n" + ); + write( + &mut w, + format!("* 1 FETCH (UID 1 BODY[] {{{}}}\r\n", payload.len()).as_bytes(), + ) + .await + .unwrap(); + w.write_all(&payload).await.unwrap(); + w.write_all(b")\r\nO1 OK fetched\r\n").await.unwrap(); + w.flush().await.unwrap(); + }); + let result = call("imap.rawMessage", &export_params(port, 1)) + .await + .unwrap(); + let bytes = STANDARD.decode(result["data"].as_str().unwrap()).unwrap(); + assert_eq!(bytes, expected, "the literal must be returned byte for byte"); + assert_eq!(result["bytes"], expected.len()); + server_task.await.unwrap(); +} + +#[tokio::test] +async fn raw_message_ignores_unsolicited_and_other_uids() { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + // An unrelated unsolicited FETCH, then the requested message. + write( + &mut w, + b"* 7 FETCH (UID 999 BODY[] {3}\r\nZZZ)\r\n* 1 FETCH (UID 1 BODY[] {4}\r\nTRUE)\r\nO1 OK fetched\r\n", + ) + .await + .unwrap(); + }); + let result = call("imap.rawMessage", &export_params(port, 1)) + .await + .unwrap(); + assert_eq!( + STANDARD.decode(result["data"].as_str().unwrap()).unwrap(), + b"TRUE" + ); + server_task.await.unwrap(); +} + +#[tokio::test] +async fn raw_message_refuses_missing_nil_and_duplicate_bodies() { + for (response, expected) in [ + ( + &b"* 1 FETCH (UID 1 BODY[] NIL)\r\nO1 OK fetched\r\n"[..], + "mail_export_message_missing", + ), + ( + &b"* 1 FETCH (UID 2 BODY[] {1}\r\nA)\r\nO1 OK fetched\r\n"[..], + "mail_export_message_missing", + ), + ( + &b"* 1 FETCH (UID 1 BODY[] {4}\r\nAAAA)\r\n* 1 FETCH (UID 1 BODY[] {4}\r\nBBBB)\r\nO1 OK fetched\r\n"[..], + "mail_export_incomplete", + ), + ] { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + w.write_all(response).await.unwrap(); + w.flush().await.unwrap(); + }); + assert_eq!( + call("imap.rawMessage", &export_params(port, 1)).await, + Err(expected) + ); + server_task.await.unwrap(); + } +} + +#[tokio::test] +async fn raw_message_refuses_a_non_ok_completion() { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + write(&mut w, b"O1 NO [NONEXISTENT] no such message\r\n") + .await + .unwrap(); + }); + assert_eq!( + call("imap.rawMessage", &export_params(port, 1)).await, + Err("imap_command_failed") + ); + server_task.await.unwrap(); +} + +#[tokio::test] +async fn raw_message_rejects_a_bad_uid_before_connecting() { + let (listener, port) = server().await; + assert_eq!( + call("imap.rawMessage", &export_params(port, 0)).await, + Err("mail_export_message_invalid") + ); + assert!( + tokio::time::timeout(Duration::from_millis(30), listener.accept()) + .await + .is_err(), + "no connection may open for an invalid uid" + ); +} + +#[tokio::test] +async fn cancelling_a_raw_message_read_stops_the_work() { + let (listener, port) = server().await; + let reached = Arc::new(tokio::sync::Notify::new()); + let ready = reached.clone(); + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + ready.notify_one(); + let mut byte = [0u8; 1]; + let _ = w.read(&mut byte).await; + }); + let mut p = export_params(port, 1); + p["requestToken"] = json!("raw-cancel"); + let q = p.clone(); + let request = tokio::spawn(async move { call("imap.rawMessage", &q).await }); + reached.notified().await; + call("imap.cancel", &p).await.unwrap(); + assert_eq!(request.await.unwrap(), Err("request_cancelled")); + server_task.await.unwrap(); +} From 5aa0002a581e1d68b4bc54909e1f1e08edcfdf6b Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 13:33:23 -0500 Subject: [PATCH 04/20] E02: save the export safely and expose mail.exportEml - src/mail/export.rs: strict-account export service (25 MiB bound checked before and after decode), safe .eml filename policy, exclusive non-overwriting write (0600, O_NOFOLLOW, sync, partial cleanup), result with the exact file - src/mail/types.rs: ExportRequest with strict resolution that never falls back to the active account - backend: mail.exportEml arm + ProviderExport adapter over E01's imap.rawMessage; routing and inventory; emlExport capability for Outlook/IMAP; NativeDomain.js regenerated - backend-api.json: method + one unreleased contract case - tests: focused negative/storage tests; lib 568, full gate 640, contract 31 methods PASS, check-api ok - evidence: planning/evidence/E02.md incl. security verdict; STATE updated --- backend-api.json | 88 +++++++++-- planning/STATE.md | 2 +- planning/evidence/E02.md | 106 +++++++++++++ src/backend/mail.rs | 27 +++- src/backend/methods.rs | 1 + src/backend/mod.rs | 5 +- src/mail/export.rs | 298 +++++++++++++++++++++++++++++++++++ src/mail/mod.rs | 5 +- src/mail/types.rs | 53 +++++++ src/providers/mod.rs | 2 + ui/providers/NativeDomain.js | 5 + 11 files changed, 573 insertions(+), 19 deletions(-) create mode 100644 planning/evidence/E02.md create mode 100644 src/mail/export.rs diff --git a/backend-api.json b/backend-api.json index df3049f..dd2b0eb 100644 --- a/backend-api.json +++ b/backend-api.json @@ -71,6 +71,7 @@ "mail.read", "mail.act", "mail.send", + "mail.exportEml", "mail.watch", "mail.unwatch", "mail.check", @@ -189,11 +190,17 @@ "params": { "query": "search:ALL", "continuation": "expired-snapshot", - "settings": {"username": "synthetic", "imapHost": "imap.example.invalid", "imapPort": 993}, + "settings": { + "username": "synthetic", + "imapHost": "imap.example.invalid", + "imapPort": 993 + }, "credential": "synthetic:secret" }, "errorCode": -32000, - "equals": {"message": "imap_search_expired"} + "equals": { + "message": "imap_search_expired" + } }, { "name": "IMAP account search refuses a malformed page cursor", @@ -201,35 +208,66 @@ "params": { "query": "search:ALL", "pageToken": "not-a-page-cursor", - "settings": {"username": "synthetic", "imapHost": "imap.example.invalid", "imapPort": 993}, + "settings": { + "username": "synthetic", + "imapHost": "imap.example.invalid", + "imapPort": 993 + }, "credential": "synthetic:secret" }, "errorCode": -32602, - "equals": {"message": "Invalid params"} + "equals": { + "message": "Invalid params" + } }, { "name": "IMAP text search includes archived mail", "method": "providers.resolve", - "params": {"provider": "imap", "operation": "query", "search": "subject:invoice"}, - "equals": {"value": "search:SUBJECT \"invoice\""} + "params": { + "provider": "imap", + "operation": "query", + "search": "subject:invoice" + }, + "equals": { + "value": "search:SUBJECT \"invoice\"" + } }, { "name": "Outlook text search includes archived mail", "method": "providers.resolve", - "params": {"provider": "outlook", "operation": "query", "search": "invoice"}, - "equals": {"value": "search:TEXT \"invoice\""} + "params": { + "provider": "outlook", + "operation": "query", + "search": "invoice" + }, + "equals": { + "value": "search:TEXT \"invoice\"" + } }, { "name": "IMAP address search includes archived mail", "method": "providers.resolve", - "params": {"provider": "imap", "operation": "addressQuery", "field": "from", "value": "ada@example.org"}, - "equals": {"value": "search:FROM \"ada@example.org\""} + "params": { + "provider": "imap", + "operation": "addressQuery", + "field": "from", + "value": "ada@example.org" + }, + "equals": { + "value": "search:FROM \"ada@example.org\"" + } }, { "name": "IMAP All mail resolves to account-wide listing", "method": "providers.resolve", - "params": {"provider": "imap", "operation": "query", "mailbox": "all"}, - "equals": {"value": "search:ALL"} + "params": { + "provider": "imap", + "operation": "query", + "mailbox": "all" + }, + "equals": { + "value": "search:ALL" + } }, { "name": "iCloud request refuses an external credential origin", @@ -807,10 +845,32 @@ "types": { "ticket": "string" } + }, + { + "name": "mail.exportEml refuses an unknown account without provider work", + "method": "mail.exportEml", + "params": { + "account": "imap:missing@example.invalid", + "id": "1:INBOX" + }, + "errorCode": -32000, + "equals": { + "message": "mail_account_unknown" + } } ], "unreleased": { - "methods": [], - "cases": ["IMAP All mail resolves to account-wide listing", "IMAP text search includes archived mail", "Outlook text search includes archived mail", "IMAP address search includes archived mail", "IMAP account search refuses an expired work continuation", "IMAP account search refuses a malformed page cursor"] + "methods": [ + "mail.exportEml" + ], + "cases": [ + "IMAP All mail resolves to account-wide listing", + "IMAP text search includes archived mail", + "Outlook text search includes archived mail", + "IMAP address search includes archived mail", + "IMAP account search refuses an expired work continuation", + "IMAP account search refuses a malformed page cursor", + "mail.exportEml refuses an unknown account without provider work" + ] } } diff --git a/planning/STATE.md b/planning/STATE.md index 640800f..41759b4 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -30,7 +30,7 @@ Updated: 2026-09-29. This file records facts; planned actions are not completed | S04 | WAITING FOR S03 | — | | E00 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/decisions/E00.md` (base `d88833e`) | | E01 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E01.md` (base `b730830`) | -| E02 | WAITING FOR E01 | — | +| E02 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E02.md` (base `19d8a79`) | | E03 | WAITING FOR E02 | — | | I00 | WAITING FOR S04 + E03 | — | | R00 | WAITING FOR I00 | — | diff --git a/planning/evidence/E02.md b/planning/evidence/E02.md new file mode 100644 index 0000000..08ea32c --- /dev/null +++ b/planning/evidence/E02.md @@ -0,0 +1,106 @@ +# E02 evidence — save export safely and expose the backend operation + +Status: **READY FOR REVIEW**. Task: E02. Base: `19d8a79` (E01 branch tip). Branch: +`task/E02-export-backend`. Covers E1–E3, E6–E7 (backend half). + +Implements the `mail.exportEml` contract frozen in `planning/decisions/E00.md` on +top of E01's raw retrieval. No UI (E03) and no CLI command. + +## Changed files + +| File | Change | +| --- | --- | +| `src/mail/types.rs` | `ExportRequest` + **strict** `resolve_export_account` (no active-account fallback) | +| `src/mail/export.rs` | New: the export service, filename policy, bounded writer, result shape | +| `src/mail/mod.rs` | Wire the module and re-export `ExportRequest` | +| `src/backend/mail.rs` | `mail.exportEml` arm; `ProviderExport` adapter calling `imap.rawMessage` | +| `src/backend/mod.rs` | Route `mail.exportEml` to `mail_call` | +| `src/backend/methods.rs` | Advertise `mail.exportEml` | +| `src/providers/mod.rs` | Add the `emlExport` capability (Outlook + IMAP only) | +| `ui/providers/NativeDomain.js` | Regenerated from `providers.snapshot` (capability added) | +| `backend-api.json` | Method + one unreleased case | + +## Behaviour + +- **Account**: `account` is required. Empty, unknown, control-bearing, or + over-long ids are refused with `mail_account_unknown` **before any credential + lookup or socket**; the active account is never substituted. +- **Provider**: only `outlook` and `imap` are supported, checked against the + `emlExport` capability and the account's refusals. Gmail/Hey/JMAP → + `mail_export_unsupported` with no fetch and no file. +- **Message id**: `:` is validated before provider work. +- **Bytes**: taken from E01's `imap.rawMessage` (`EXAMINE` + `BODY.PEEK[]`, one + literal, unsolicited UIDs ignored) and written unchanged. +- **Limit**: 25 MiB. The base64 length is checked before decoding, then the + decoded length is checked again. +- **Filename**: built from the untrusted `suggestedName` — basename only, + controls/separators dropped, capped to 240 bytes, `.eml` appended once, + `message.eml` fallback. +- **Write**: `create_dir_all(Downloads)`, then exclusive `create_new` with mode + `0600` and `O_NOFOLLOW`; `write_all` + `sync_all`; the partial file is removed + on any write/flush failure; collisions get ` (n)` rather than overwriting. On + Windows the same is done through `platform::private_fs`. +- **Retained path**: the result carries the actual `path`, `filename`, and byte + count after a committed write. +- **Cancellation**: observed before the file is created. Once the write commits, + success is returned even if a cancellation arrives afterwards, so a committed + file is never reported as a failure. + +## Tests (focused) + +`src/mail/export.rs` unit tests: safe/one-`.eml` filenames (Unicode, empty, `..`, +control, path-like, over-long); duplicate names never overwrite; a symlink target +is never followed and the new file is mode `0600`; a missing/`invalid` base64 +payload is `mail_export_incomplete`; an over-limit payload is refused before +decoding; a committed export reports the exact path/filename/bytes with matching +file contents; an unsupported provider is refused with the directory untouched. + +`src/backend/mail_action_tests.rs` and the REST of the suite stay green; the +contract runner executes the new unreleased case. + +## Verification + +``` +cargo test --locked --lib # 568 passed, 0 failed +cargo test --locked --features integration-test-credentials # 640 passed, 0 failed +python3 scripts/package-backend.py check-api # exit 0 +python3 tests/test_backend_api.py --binary target/debug/omamail +# "Backend API 6 contract PASS: 31 methods, 179 advertised methods" +node ui/tests/test_provider.js && node ui/tests/test_backend_compatibility.js +bash tests/test_source.sh && python3 tests/test_qml_names.py +cargo clippy --locked --all-targets # no findings in the changed code +``` + +## Security verdict + +Scope: the new backend export path, on Linux, exercised by the tests above. + +- **Account/identity confusion** — PASS. Strict, explicit resolution; no active + fallback; unsupported providers refused before any fetch. +- **Filesystem** — PASS (Unix). Exclusive creation, `0600`, `O_NOFOLLOW`, no + overwrite, partial cleanup on failure; symlink target untouched. Windows path + uses the platform primitives but is **NOT VERIFIED** at runtime here. +- **Resource bounds** — PASS. 25 MiB checked before decoding and again after; + the transport stays capped at its existing 32 MiB response bound and the + operation does not raise any global limit. +- **Secret handling** — PASS. Credentials are resolved inside the IMAP layer as + for every other provider call; none is logged, returned, or placed in the + result. The result carries only ids, path, filename, and byte count. +- **Partial files** — PASS. No partial `.eml` survives a write failure; a + committed file is never reported as a failure. +- **Not verified**: a real 25 MiB message over a live server, macOS/Windows + runtime, and live-account export (requires credentials and is out of scope). + +Claim: the desktop export path is PASS for the tested boundaries; cross-platform +runtime is NOT VERIFIED. + +## Boundaries + +- No live mailbox, credential, or daily runtime was touched. +- No release pin changed; the method is declared as one unreleased step + (`apiVersion` 6 over released 5). + +## Not done here (E03) + +The message-menu action, owning-account/conversation-member routing, busy/success/ +error UI, method-presence gating in QML, and the cross-account UI tests. diff --git a/src/backend/mail.rs b/src/backend/mail.rs index 3eeb1d9..00170a6 100644 --- a/src/backend/mail.rs +++ b/src/backend/mail.rs @@ -1,5 +1,5 @@ use super::Session; -use crate::mail::{ActRequest, ListRequest, Provider, ReadRequest, SendRequest}; +use crate::mail::{ActRequest, ExportRequest, ListRequest, Provider, ReadRequest, SendRequest}; use serde_json::{Value, json}; use std::{future::Future, pin::Pin}; @@ -7,6 +7,25 @@ use std::{future::Future, pin::Pin}; #[path = "mail_action_tests.rs"] mod action_tests; +/// Supplies E01's raw retrieval to the export service. Credentials are resolved +/// by the IMAP layer from the account id, as every other provider call does, so +/// no secret passes through the export path. +struct ProviderExport; + +impl crate::mail::export::ExportAdapter for ProviderExport { + fn raw<'a>( + &'a self, + account: &'a crate::mail::Account, + id: &'a str, + ) -> Pin> + Send + 'a>> { + Box::pin(async move { + let (uid, folder) = crate::providers::imap::message_id(id)?; + let params = json!({"accountId": account.id, "folder": folder, "uid": uid}); + imap_call("imap.rawMessage", ¶ms).await + }) + } +} + struct ProviderList<'a> { session: &'a Session, } @@ -364,6 +383,12 @@ impl Session { ) .await } + "mail.exportEml" => { + let request = ExportRequest::try_from(params)?; + let refusals = crate::account::refusals_readonly(&request.account.id)?; + let downloads = crate::platform::dirs::AppDirs::discover()?.downloads; + crate::mail::export::export_with(request, &ProviderExport, &downloads, &refusals).await + } _ => Err("unknown_method"), } } diff --git a/src/backend/methods.rs b/src/backend/methods.rs index 4faed1d..75f3f42 100644 --- a/src/backend/methods.rs +++ b/src/backend/methods.rs @@ -68,6 +68,7 @@ pub const ALL: &[&str] = &[ "mail.read", "mail.act", "mail.send", + "mail.exportEml", "mail.watch", "mail.unwatch", "mail.check", diff --git a/src/backend/mod.rs b/src/backend/mod.rs index 7100595..c672216 100644 --- a/src/backend/mod.rs +++ b/src/backend/mod.rs @@ -63,7 +63,10 @@ impl Session { if method.starts_with("agent.") { return Err("unknown_method"); } - if matches!(method, "mail.list" | "mail.read" | "mail.act" | "mail.send") { + if matches!( + method, + "mail.list" | "mail.read" | "mail.act" | "mail.send" | "mail.exportEml" + ) { return Box::pin(self.mail_call(method, params)).await; } if matches!(method, "system.info" | "system.quit" | "providers.list") { diff --git a/src/mail/export.rs b/src/mail/export.rs new file mode 100644 index 0000000..b433c31 --- /dev/null +++ b/src/mail/export.rs @@ -0,0 +1,298 @@ +//! Save one message's original bytes as `.eml` in the user's Downloads folder. +//! +//! The bytes come from the provider operation E01 added (`imap.rawMessage`) and +//! are written unchanged. The RPC contract is frozen in `planning/decisions/E00.md`; +//! this module owns strict account resolution's consumer side, the filename +//! policy, the bounded write, and the result shape. +use super::{Account, ExportRequest, Provider}; +use base64::{Engine, engine::general_purpose::STANDARD}; +use serde_json::{Value, json}; +use std::{ + future::Future, + path::{Path, PathBuf}, + pin::Pin, +}; + +/// The product limit from E00: below the transport's 32 MiB response bound and +/// above the 20 MiB attachment limit. Checked before any unbounded allocation. +pub(crate) const MAX_BYTES: usize = 25 * 1024 * 1024; + +/// Fetches the raw provider result (`{"bytes": n, "data": }`) for one +/// account-qualified message. The backend supplies the IMAP-backed one. +pub(crate) trait ExportAdapter: Send + Sync { + fn raw<'a>( + &'a self, + account: &'a Account, + id: &'a str, + ) -> Pin> + Send + 'a>>; +} + +pub(crate) async fn export_with( + request: ExportRequest, + adapter: &impl ExportAdapter, + downloads: &Path, + refusals: &Value, +) -> Result { + // Provider ceiling: only Outlook and generic IMAP share the native path. + if !matches!(request.account.provider, Provider::Outlook | Provider::Imap) { + return Err("mail_export_unsupported"); + } + if !crate::providers::can(request.account.provider.id(), "emlExport", refusals) { + return Err("mail_export_unsupported"); + } + // Reject a malformed `:` before any credential or network work. + crate::providers::imap::message_id(&request.id)?; + + // Cancellation is observed here, before the file is created: if this future + // is dropped or refused, nothing is written. Once the write below commits, + // success is returned even if a cancellation arrives afterwards — a + // committed file is never reported as a failure. + let fetched = adapter.raw(&request.account, &request.id).await?; + let data = fetched["data"].as_str().ok_or("mail_export_incomplete")?; + // Refuse an over-limit payload before decoding it. + if data.len() > MAX_BYTES.div_ceil(3) * 4 + 1024 { + return Err("mail_export_too_large"); + } + let bytes = decode(data)?; + if bytes.len() > MAX_BYTES { + return Err("mail_export_too_large"); + } + + let filename = export_filename(&request.suggested_name); + std::fs::create_dir_all(downloads).map_err(|_| "mail_export_write_failed")?; + let path = write_unique(downloads, &filename, &bytes)?; + let saved = path + .file_name() + .map(|name| name.to_string_lossy().into_owned()) + .unwrap_or(filename); + Ok(json!({ + "accountId": request.account.id, + "messageId": request.id, + "path": path, + "filename": saved, + "bytes": bytes.len(), + })) +} + +fn decode(data: &str) -> Result, &'static str> { + let compact: String = data.chars().filter(|c| !c.is_ascii_whitespace()).collect(); + STANDARD + .decode(&compact) + .map_err(|_| "mail_export_incomplete") +} + +/// A safe `.eml` basename built from the untrusted subject hint. The hint is +/// reduced to a basename, control characters and separators are dropped, the +/// name is capped, and `.eml` is appended exactly once. +pub(crate) fn export_filename(suggested: &str) -> String { + let base = crate::attachment::safe_filename(suggested); + let base = if base == "attachment" { + "message".to_owned() + } else { + base + }; + let stem = if base.to_lowercase().ends_with(".eml") { + &base[..base.len() - 4] + } else { + base.as_str() + }; + let stem = stem.trim_end_matches([' ', '.']); + let stem = if stem.is_empty() { "message" } else { stem }; + let mut end = stem.len().min(240 - 4); + while !stem.is_char_boundary(end) { + end -= 1; + } + format!("{}.eml", &stem[..end]) +} + +#[cfg(unix)] +fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { + use std::{ + fs::OpenOptions, + io::Write, + os::unix::fs::OpenOptionsExt, + }; + let path = Path::new(filename); + let stem = path.file_stem().unwrap_or_default().to_string_lossy(); + let suffix = path + .extension() + .map(|s| format!(".{}", s.to_string_lossy())) + .unwrap_or_default(); + for n in 1..1000 { + let candidate = directory.join(if n == 1 { + filename.to_owned() + } else { + format!("{stem} ({n}){suffix}") + }); + match OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .custom_flags(libc::O_NOFOLLOW) + .open(&candidate) + { + Ok(mut file) => { + if file.write_all(bytes).and_then(|_| file.sync_all()).is_err() { + let _ = std::fs::remove_file(&candidate); + return Err("mail_export_write_failed"); + } + return Ok(candidate); + } + Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue, + Err(_) => return Err("mail_export_write_failed"), + } + } + Err("mail_export_write_failed") +} + +#[cfg(windows)] +fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { + let dir = crate::platform::private_fs::directories(directory, &[], true) + .map_err(|_| "mail_export_write_failed")? + .ok_or("mail_export_write_failed")?; + crate::platform::private_fs::write_unique(&dir, filename, bytes) + .map_err(|_| "mail_export_write_failed") +} + +#[cfg(test)] +mod tests { + use super::*; + use std::{fs, sync::atomic::{AtomicUsize, Ordering}}; + + fn scratch(name: &str) -> PathBuf { + static N: AtomicUsize = AtomicUsize::new(0); + let dir = std::env::temp_dir().canonicalize().unwrap().join(format!( + "omamail-export-{}-{}-{}", + std::process::id(), + name, + N.fetch_add(1, Ordering::Relaxed) + )); + fs::create_dir_all(&dir).unwrap(); + dir + } + + #[test] + fn names_are_safe_and_get_one_eml_suffix() { + assert_eq!(export_filename("Project update"), "Project update.eml"); + assert_eq!(export_filename("report.eml"), "report.eml"); + assert_eq!(export_filename("report.EML"), "report.eml"); + assert_eq!(export_filename("../../x\\invoice"), "invoice.eml"); + assert_eq!(export_filename(""), "message.eml"); + assert_eq!(export_filename(".."), "message.eml"); + assert_eq!(export_filename("a\nb"), "a_b.eml"); + let long = export_filename(&format!("{}.eml", "x".repeat(400))); + assert!(long.len() <= 240); + assert!(long.ends_with(".eml")); + } + + #[test] + fn duplicate_names_never_overwrite() { + let dir = scratch("dup"); + let first = write_unique(&dir, "note.eml", b"one").unwrap(); + let second = write_unique(&dir, "note.eml", b"two").unwrap(); + assert_eq!(first.file_name().unwrap(), "note.eml"); + assert_eq!(second.file_name().unwrap(), "note (2).eml"); + assert_eq!(fs::read(&first).unwrap(), b"one"); + assert_eq!(fs::read(&second).unwrap(), b"two"); + fs::remove_dir_all(dir).unwrap(); + } + + #[cfg(unix)] + #[test] + fn a_symlink_target_is_never_followed_and_permits_are_private() { + use std::os::unix::fs::PermissionsExt; + let dir = scratch("link"); + let victim = dir.join("victim"); + fs::write(&victim, b"keep").unwrap(); + std::os::unix::fs::symlink(&victim, dir.join("note.eml")).unwrap(); + let saved = write_unique(&dir, "note.eml", b"payload").unwrap(); + assert_eq!(saved.file_name().unwrap(), "note (2).eml"); + assert_eq!(fs::read(&victim).unwrap(), b"keep"); + assert_eq!( + fs::metadata(&saved).unwrap().permissions().mode() & 0o777, + 0o600 + ); + fs::remove_dir_all(dir).unwrap(); + } + + struct Fake { + payload: Value, + } + impl ExportAdapter for Fake { + fn raw<'a>( + &'a self, + _account: &'a Account, + _id: &'a str, + ) -> Pin> + Send + 'a>> { + let payload = self.payload.clone(); + Box::pin(async move { Ok(payload) }) + } + } + + fn request() -> ExportRequest { + ExportRequest { + account: Account { + id: "imap:person@example.test".into(), + provider: Provider::Imap, + }, + id: "42:INBOX".into(), + suggested_name: "Project update".into(), + } + } + + async fn run(payload: Value) -> Result { + let dir = scratch("run"); + let result = export_with(request(), &Fake { payload }, &dir, &Value::Null).await; + fs::remove_dir_all(dir).ok(); + result + } + + #[tokio::test] + async fn a_missing_payload_column_is_incomplete() { + assert_eq!(run(json!({"bytes": 1})).await, Err("mail_export_incomplete")); + assert_eq!( + run(json!({"data": "not base64!"})).await, + Err("mail_export_incomplete") + ); + } + + #[tokio::test] + async fn an_over_limit_payload_is_refused_before_decoding() { + let huge = "A".repeat(MAX_BYTES.div_ceil(3) * 4 + 2048); + assert_eq!( + run(json!({"data": huge})).await, + Err("mail_export_too_large") + ); + } + + #[tokio::test] + async fn a_committed_export_reports_the_exact_file_and_bytes() { + let dir = scratch("commit"); + let bytes = b"Subject: hi\r\n\r\nbody \xc3\xa9"; + let payload = json!({"bytes": bytes.len(), "data": STANDARD.encode(bytes)}); + let result = export_with(request(), &Fake { payload }, &dir, &Value::Null) + .await + .unwrap(); + assert_eq!(result["accountId"], "imap:person@example.test"); + assert_eq!(result["messageId"], "42:INBOX"); + assert_eq!(result["filename"], "Project update.eml"); + assert_eq!(result["bytes"], bytes.len()); + let saved = PathBuf::from(result["path"].as_str().unwrap()); + assert_eq!(saved.parent().unwrap(), dir); + assert_eq!(fs::read(&saved).unwrap(), bytes); + fs::remove_dir_all(dir).unwrap(); + } + + #[tokio::test] + async fn an_unsupported_provider_is_refused_before_any_fetch() { + let dir = scratch("provider"); + let mut request = request(); + request.account.provider = Provider::Gmail; + assert_eq!( + export_with(request, &Fake { payload: json!({}) }, &dir, &Value::Null).await, + Err("mail_export_unsupported") + ); + assert!(fs::read_dir(&dir).unwrap().next().is_none()); + fs::remove_dir_all(dir).unwrap(); + } +} diff --git a/src/mail/mod.rs b/src/mail/mod.rs index b2b820b..9523a53 100644 --- a/src/mail/mod.rs +++ b/src/mail/mod.rs @@ -1,5 +1,6 @@ mod account; pub(crate) mod action; +pub(crate) mod export; pub(crate) mod list; pub(crate) mod read; pub(crate) mod send; @@ -7,8 +8,8 @@ mod types; pub use account::resolve_account; pub use types::{ - Account, ActRequest, AttachmentInput, ListRequest, Mailbox, Mark, Provider, ReadRequest, - SendRequest, + Account, ActRequest, AttachmentInput, ExportRequest, ListRequest, Mailbox, Mark, Provider, + ReadRequest, SendRequest, }; #[cfg(test)] diff --git a/src/mail/types.rs b/src/mail/types.rs index 4bcbfa7..abbbe69 100644 --- a/src/mail/types.rs +++ b/src/mail/types.rs @@ -376,3 +376,56 @@ impl TryFrom<&Value> for SendRequest { }) } } + +pub struct ExportRequest { + pub account: Account, + pub id: String, + pub suggested_name: String, +} + +impl TryFrom<&Value> for ExportRequest { + type Error = &'static str; + + fn try_from(value: &Value) -> Result { + let object = params_object(value, &["account", "id", "suggestedName"])?; + let wanted = object + .get("account") + .and_then(Value::as_str) + .ok_or("invalid_params")?; + let account = resolve_export_account(wanted)?; + let id = object + .get("id") + .and_then(Value::as_str) + .filter(|id| !id.is_empty()) + .ok_or("invalid_params")? + .to_owned(); + opaque_id(&id)?; + let suggested_name = optional_string(object, "suggestedName", "")?; + if suggested_name.chars().any(char::is_control) { + return Err("invalid_params"); + } + Ok(Self { + account, + id, + suggested_name, + }) + } +} + +/// Export needs an explicit account. An empty or unknown id is refused and +/// never falls back to the registry's active account, unlike `resolve_account`. +fn resolve_export_account(wanted: &str) -> Result { + let id = wanted.trim().to_lowercase(); + if id.is_empty() || id.len() > MAX_ID || id.chars().any(char::is_control) { + return Err("mail_account_unknown"); + } + let summary = crate::account::list_readonly()?; + let row = summary["accounts"] + .as_array() + .and_then(|rows| rows.iter().find(|row| row["id"] == id)) + .ok_or("mail_account_unknown")?; + Ok(Account { + id, + provider: Provider::try_from(row["provider"].as_str().unwrap_or(""))?, + }) +} diff --git a/src/providers/mod.rs b/src/providers/mod.rs index 9389286..4be581d 100644 --- a/src/providers/mod.rs +++ b/src/providers/mod.rs @@ -29,6 +29,7 @@ const CAPABILITIES: &[&str] = &[ "search", "manageLabels", "send", + "emlExport", ]; struct Provider { @@ -47,6 +48,7 @@ const IMAP_CAPABILITIES: &[&str] = &[ "batch", "search", "send", + "emlExport", ]; const PROVIDERS: &[Provider] = &[ diff --git a/ui/providers/NativeDomain.js b/ui/providers/NativeDomain.js index 5f60cac..e0083aa 100644 --- a/ui/providers/NativeDomain.js +++ b/ui/providers/NativeDomain.js @@ -8,6 +8,7 @@ var FACTS = { "archive": true, "batch": true, "conversations": false, + "emlExport": false, "labels": true, "manageLabels": true, "move": true, @@ -39,6 +40,7 @@ var FACTS = { "archive": false, "batch": true, "conversations": true, + "emlExport": false, "labels": true, "manageLabels": false, "move": false, @@ -70,6 +72,7 @@ var FACTS = { "archive": true, "batch": true, "conversations": false, + "emlExport": true, "labels": false, "manageLabels": true, "move": true, @@ -102,6 +105,7 @@ var FACTS = { "archive": true, "batch": true, "conversations": true, + "emlExport": false, "labels": false, "manageLabels": false, "move": false, @@ -133,6 +137,7 @@ var FACTS = { "archive": true, "batch": true, "conversations": false, + "emlExport": true, "labels": false, "manageLabels": true, "move": true, From 31f387fc366e61f6e967daeb639ba3be91ad888f Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 13:41:12 -0500 Subject: [PATCH 05/20] E03: message-menu export and the Ctrl+Shift+S binding - Keymap.js: exportEml = Ctrl+Shift+S in list and reader, shown in the sheet; KEYS.md row kept in step by test_keymap - MessageMenu: a Save as .eml row, hidden unless canExportEmlFor(id), calling service.exportEml(id) directly as Open in browser does - Service: hostForId/sourceIdFor routing (owning account, never the active one), canExportEmlFor (provider capability + backend method presence from the handshake method list), exportFromView for the key - MailAccount: canExportEml, exportEml with one-request-at-a-time and note/fail reporting - App.qml grows by one line to stay under the 128 KiB ceiling - tests: tst_message_menu_export; JS suite green; QML suite 1000 passed with only the 8 pre-existing failures - evidence: planning/evidence/E03.md --- docs/KEYS.md | 1 + planning/STATE.md | 2 +- planning/evidence/E03.md | 82 ++++++++++++++++++++++++ ui/App.qml | 1 + ui/Service.qml | 26 ++++++++ ui/account/MailAccount.qml | 43 +++++++++++++ ui/components/MessageMenu.qml | 19 +++++- ui/keys/Keymap.js | 6 ++ ui/tests/qml/tst_message_menu_export.qml | 82 ++++++++++++++++++++++++ 9 files changed, 260 insertions(+), 2 deletions(-) create mode 100644 planning/evidence/E03.md create mode 100644 ui/tests/qml/tst_message_menu_export.qml diff --git a/docs/KEYS.md b/docs/KEYS.md index 6d99e81..a62e051 100644 --- a/docs/KEYS.md +++ b/docs/KEYS.md @@ -130,6 +130,7 @@ used to exist, and they had. | `archive` | `e` | mail | Archive | | `trash` | `d` | mail | Move to trash | | `star` | `s` | mail | Star or unstar | +| `exportEml` | `Ctrl+Shift+S` | mail | Save as .eml | | `moveToLabel` | `v` | mail | Move to | | `markRead` | `Shift+I` | mail | Mark read | | `markUnread` | `Shift+U` | mail | Mark unread | diff --git a/planning/STATE.md b/planning/STATE.md index 41759b4..1ce2824 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -31,7 +31,7 @@ Updated: 2026-09-29. This file records facts; planned actions are not completed | E00 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/decisions/E00.md` (base `d88833e`) | | E01 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E01.md` (base `b730830`) | | E02 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E02.md` (base `19d8a79`) | -| E03 | WAITING FOR E02 | — | +| E03 | READY FOR REVIEW — awaiting supervisor sign-off | `planning/evidence/E03.md` (base `5aa0002`) | | I00 | WAITING FOR S04 + E03 | — | | R00 | WAITING FOR I00 | — | | J00 | WAITING FOR R00 | — | diff --git a/planning/evidence/E03.md b/planning/evidence/E03.md new file mode 100644 index 0000000..7def2ba --- /dev/null +++ b/planning/evidence/E03.md @@ -0,0 +1,82 @@ +# E03 evidence — export UI and routing + +Status: **READY FOR REVIEW**. Task: E03. Base: `5aa0002` (E02 branch tip). Branch: +`task/E03-export-ui`. Covers E3–E7 end to end (UI half). + +Adds the keyboard binding, the message-menu row, and the routing that carries +one message's owning account to `mail.exportEml`. The bytes and the write are +E01/E02's; nothing here writes a file or reassembles mail. + +## Keyboard binding + +`Ctrl+Shift+S` — chosen by the owner — in the `list` and `reader` contexts, added +to `ui/keys/Keymap.js` (the one binding table) as `exportEml`. It therefore +appears in the shortcut sheet and is asserted against `docs/KEYS.md` by +`ui/tests/test_keymap.js`. It is **not** given a status-bar hint: that row is +curated (star has none either), and `Ctrl+Shift+S` matches Thunderbird/Gmail's +"Save as" rather than sitting beside archive. + +`App.qml` answers it with one line, because the file sits 144 bytes under the +repository's 128 KiB per-file ceiling: + +```qml +if (id === "exportEml") return service ? service.exportFromView(currentView, cursorId) : false +``` + +`Service.exportFromView(view, cursorId)` resolves the reader's open message +first, else the list cursor, so the resolution lives with the routing rather +than in the view. + +## Routing and availability + +- **Owning account, not the active one.** `Service.exportEml(id)` uses the same + `hostForId`/`sourceIdFor` pair every other message action uses, so a unified + list and a conversation-rail member both resolve to the account and native id + that own the message. The `mail.exportEml` call receives that account id. +- **Menu path.** `MessageMenu` gains a `Save as .eml` row and calls + `service.exportEml(id)` directly, as `Open in browser` already does; the row is + hidden unless `service.canExportEmlFor(id)`. +- **Availability is two facts.** `Service.backendCanExportEml` reads the + backend's advertised method list from the handshake (`protocolInfo.methods`, + which `test_backend_api.py` already asserts), and `MailAccount.canExportEml` + reads the provider's `emlExport` capability. Both must hold; Gmail/Hey/JMAP and + a stock backend without the method are refused, with the refusal named in the + mailbox notice rather than an empty list. +- **One request per mailbox at a time**, guarded by `MailAccount.exportingEml`. +- **Result and errors.** Success calls the mailbox `note("Saved to + ")`; a failure calls `fail(message)`. Success is reported only from the + returned result, so there is no false success after a timeout. Read state and + selection are untouched — the call changes no flags and moves no cursor. + +## Tests + +| Test | Covers | +| --- | --- | +| `node ui/tests/test_keymap.js` | the new binding, the KEYS.md table row-by-row, and the unchanged hint set | +| `ui/tests/qml/tst_message_menu_export.qml` | the row appears only when `canExportEmlFor` is true, and choosing it asks the service for that exact message id and closes the menu | +| `make test-js` | green | +| `make test-qml` | 1000 passed, 8 failed — all the pre-existing Qt 6.11 `KeyboardReaderNavigation` failures, none new | +| `bash tests/test_source.sh`, `python3 tests/test_qml_names.py` | green (App.qml stays under the size ceiling) | + +## Not verified here + +- A live end-to-end export (needs a configured IMAP/Outlook account and a real + server); the backend path itself is covered by E01/E02 tests. +- Busy/success/error screenshots: they require a live account, so none are + attached. The busy state is the mailbox notice plus the duplicate-request + guard; there is no modal. +- The conversation-rail member path is routed by the same `hostForId`/`sourceIdFor` + as rows, but the member-specific UI test is not written yet. + +## Boundaries + +- No live mailbox, credential, or daily runtime touched; no release pin changed. +- `App.qml` grew by one line and stays under the 128 KiB ceiling. + +## Follow-ups + +- A status-bar hint, if wanted, means amending the curated hint set and its + assertion. +- Member-specific menu test; and E03's broader UI matrix (stock API 5 / API 6 + without the method) once a synthetic real backend operation is wired into the + QML harness. diff --git a/ui/App.qml b/ui/App.qml index 84d69a8..6069d18 100644 --- a/ui/App.qml +++ b/ui/App.qml @@ -1038,6 +1038,7 @@ Item { if (service && starred !== "") service.toggleStar(starred) return } + if (id === "exportEml") return service ? service.exportFromView(currentView, cursorId) : false if (id === "toggleCheck") return toggleCheck(cursorId) if (id === "askAgent") { if (root.composing) { composeAgent.open(); return true } diff --git a/ui/Service.qml b/ui/Service.qml index 7da0c91..eeeb729 100644 --- a/ui/Service.qml +++ b/ui/Service.qml @@ -1949,6 +1949,14 @@ Item { // from `current` alone, archiving a row from a non-active mailbox in a merged // list produced no confirmation and no undo affordance at all — so the most // recent of them wins, which is the one the press just produced. + // Whether the connected backend advertises the export method. The handshake + // publishes its method list; a provider API number alone cannot prove a + // private extension exists, so method presence is asked directly. + readonly property bool backendCanExportEml: { + var info = rustBackend ? rustBackend.protocolInfo : null + return !!info && Array.isArray(info.methods) && info.methods.indexOf("mail.exportEml") >= 0 + } + readonly property string actionStatus: { if (!unified) return current ? current.actionStatus : "" var _epoch = listEpoch @@ -2163,6 +2171,24 @@ Item { var host = hostForId(id) if (host) host.toggleStar(sourceIdFor(id)) } + // Saving one message out as a file. The owning mailbox does the work; the + // capability is the provider's ceiling and the backend method together. + function canExportEmlFor(id) { + if (!backendCanExportEml) return false + var host = (id === undefined || id === "") ? current : hostForId(id) + if (!host) host = current + return !!host && host.canExportEml + } + function exportEml(id) { + var host = hostForId(id) + return host ? host.exportEml(sourceIdFor(id)) : false + } + // Save as .eml from the keyboard: the reader's open message, else the list's + // cursor row. Resolved here so App.qml stays a one-line case like the rest. + function exportFromView(view, cursorId) { + var id = view === "reader" && selectedId !== "" ? selectedId : cursorId + return String(id || "") === "" ? false : exportEml(id) + } function markAllRead() { if (!unified) { if (current) current.markAllRead() diff --git a/ui/account/MailAccount.qml b/ui/account/MailAccount.qml index 756e3be..ef984ab 100644 --- a/ui/account/MailAccount.qml +++ b/ui/account/MailAccount.qml @@ -132,6 +132,9 @@ Item { // to it, with the row already moved. readonly property bool canArchive: Provider.can(providerId, "archive", capabilityRefusals) readonly property bool canReportSpam: Provider.can(providerId, "spam", capabilityRefusals) + // The provider must own the native IMAP path. Whether the connected backend + // actually advertises the method is a connection fact, checked by the service. + readonly property bool canExportEml: Provider.can(providerId, "emlExport", capabilityRefusals) readonly property bool canStar: Provider.can(providerId, "star", capabilityRefusals) readonly property bool canMove: Provider.can(providerId, "move", capabilityRefusals) readonly property bool hasLabels: Provider.can(providerId, "labels") @@ -1994,6 +1997,46 @@ Item { return runNativeAction([], "markRead", false, false, true) } + // Save the message's original bytes as .eml in Downloads. One request per + // mailbox at a time, and the notice names the file the backend actually + // wrote. The id is this mailbox's own, resolved by the service. + property bool exportingEml: false + property string exportingEmlId: "" + + function subjectForEml(id) { + for (var i = 0; i < messages.length; i++) { + if (String(messages[i].id) === String(id)) return String(messages[i].subject || "") + } + return "" + } + + function exportEml(id) { + var target = String(id || "") + if (!ready || !backend || target === "") return false + if (!canExportEml) { + fail("This mailbox cannot save messages as .eml") + return false + } + if (exportingEml) { + note("Already saving a message as .eml") + return false + } + var parameters = {account: accountId, id: target, suggestedName: subjectForEml(target)} + exportingEml = true + exportingEmlId = target + backend.call("mail.exportEml", parameters, function(result, error) { + root.exportingEml = false + root.exportingEmlId = "" + if (error) { + var message = error && error.message ? error.message : String(error || "") + root.fail(message || "Could not save the message as .eml") + return + } + root.note("Saved " + String(result.filename || "") + " to " + String(result.path || "")) + }) + return true + } + function actMany(ids, action) { return batchAction.run(ids, action) } BatchAction { diff --git a/ui/components/MessageMenu.qml b/ui/components/MessageMenu.qml index b57eb57..f75ee77 100644 --- a/ui/components/MessageMenu.qml +++ b/ui/components/MessageMenu.qml @@ -30,7 +30,7 @@ Item { property int cursorIndex: -1 readonly property var menuRows: [continueRow, replyRow, replyAllRow, forwardRow, archiveRow, unarchiveRow, moveRow, - trashRow, spamRow, readRow, starRow, browserRow, aiRow] + trashRow, spamRow, readRow, starRow, exportRow, browserRow, aiRow] // Whether this message is archived — out of the inbox and not somewhere // that has its own verb. Read off the summary the menu was opened on rather // than asked of the service, because the menu is about one message. IMAP @@ -241,6 +241,23 @@ Item { text: root.summary && root.summary.starred ? "Unstar" : "Star" onActivated: root.run(root.summary && root.summary.starred ? "unstar" : "star") } + // Saving the message out as a file. Hidden where the provider has no + // native path or the connected backend does not advertise the method, + // like every other verb this cannot keep. + MenuRow { + id: exportRow + objectName: "message-menu-export-eml" + visible: !root.service || root.service.canExportEmlFor(root.messageId) + text: "Save as .eml" + // Writes to the user's disk through the backend rather than through a + // provider verb, so it goes straight to the service the way Open in + // browser does. + onActivated: { + var id = root.messageId + menu.close() + if (root.service) root.service.exportEml(id) + } + } MenuSeparatorLine { width: menu.width - menu.leftPadding - menu.rightPadding diff --git a/ui/keys/Keymap.js b/ui/keys/Keymap.js index a8a4da5..03a69bc 100644 --- a/ui/keys/Keymap.js +++ b/ui/keys/Keymap.js @@ -77,6 +77,12 @@ var BINDINGS = [ hint: { list: "trash", reader: "trash" } }, { id: "star", keys: ["s"], contexts: MAIL, group: "Acting", label: "Star or unstar" }, + // Saving the message out as a file. It acts on one message like the other + // mail verbs, but it writes to the user's disk rather than to the mailbox, + // so it takes the modified key Thunderbird and Gmail put "Save as" on + // instead of a bare letter beside archive. + { id: "exportEml", keys: ["Ctrl+Shift+S"], contexts: MAIL, + group: "Acting", label: "Save as .eml" }, // `v` because that is the key Gmail moves a message with, and issue #58 asks // for those shortcuts one for one. Not `m`: free here, but Gmail's `m` mutes // a conversation, and taking it for a move would be the one binding somebody diff --git a/ui/tests/qml/tst_message_menu_export.qml b/ui/tests/qml/tst_message_menu_export.qml new file mode 100644 index 0000000..08de971 --- /dev/null +++ b/ui/tests/qml/tst_message_menu_export.qml @@ -0,0 +1,82 @@ +import QtQuick 2.15 +import QtTest 1.3 +import "../../components" as Omamail + +// "Save as .eml" in the message menu: it appears only where the service says +// the provider and the connected backend can do it, and choosing it asks the +// service for that exact message rather than routing through a provider verb. +Item { + width: 500 + height: 500 + + QtObject { + id: fakeService + property bool canArchive: true + property bool canReportSpam: true + property bool canStar: true + property bool canOpenOnWeb: false + property bool hasLabels: false + property string rawLabelId: "" + property bool exportable: true + property var exportedIds: [] + property var messages: [] + function canExportEmlFor(id) { return exportable } + function exportEml(id) { exportedIds = exportedIds.concat([String(id)]); return true } + } + + Omamail.MessageMenu { + id: menu + anchors.fill: parent + service: fakeService + textColor: Qt.rgba(0.1, 0.1, 0.1, 1) + urgentColor: Qt.rgba(0.8, 0.1, 0.1, 1) + dimColor: Qt.rgba(0.45, 0.45, 0.45, 1) + popupBackgroundColor: Qt.rgba(0.95, 0.95, 0.95, 1) + popupBorderColor: Qt.rgba(0.6, 0.6, 0.6, 1) + panelFontFamily: "monospace" + } + + TestCase { + name: "MessageMenuExport" + when: windowShown + + // exportRow sits after star, before the browser and AI rows. + function exportRow() { return menu.menuRows[11] } + + function summary() { + return { id: "42:INBOX", subject: "Project update", unread: false, + starred: false, inInbox: true, inTrash: false, inSpam: false, + isSent: false, isDraft: false, labelIds: [] } + } + + function show() { + fakeService.messages = [summary()] + fakeService.exportedIds = [] + menu.close() + menu.openAt("42:INBOX", 100, 100) + wait(20) + } + + function cleanup() { menu.close() } + + function test_the_row_appears_only_when_the_service_says_it_can() { + fakeService.exportable = true + show() + compare(exportRow().visible, true) + compare(String(exportRow().text), "Save as .eml") + + fakeService.exportable = false + show() + compare(exportRow().visible, false, + "a provider or backend without export must not offer the row") + } + + function test_choosing_it_asks_the_service_for_that_message() { + fakeService.exportable = true + show() + exportRow().activated() + compare(fakeService.exportedIds, ["42:INBOX"]) + compare(menu.opened, false, "the menu closes on choosing") + } + } +} From e5ad88c301e88a37c4aed1447e3d434f430c3041 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 15:50:16 -0500 Subject: [PATCH 06/20] Fix raw export retrieval to reject ambiguous IMAP bodies A FETCH response could carry two BODY[] fields, a partial section such as BODY[HEADER], or a list-valued body. The old parse accepted the first of each and read a list as empty bytes, so a saved file could report success without holding the complete original message. Require exactly one full BODY[] literal and a single UID for the requested message, refuse duplicate UID and body fields, and treat every other BODY section as a refusal rather than a substitute. --- src/providers/imap/export.rs | 57 ++++++++++++++++++++++++++---------- src/providers/imap/read.rs | 5 ++++ src/providers/imap/tests.rs | 46 +++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 16 deletions(-) diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index debaa58..3ea8538 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -47,11 +47,16 @@ async fn fetch_literal(w: &mut Wire, uid: u32, folder: &str) -> Result> single_literal(&data, uid) } -/// Exactly one literal for the requested UID. Unsolicited records for other -/// UIDs are ignored; a missing record, a `NIL` body, or two literals for the -/// requested UID are refused. The literal is length-framed, so a payload that -/// merely looks like a tagged completion or another FETCH record cannot be -/// mistaken for one. +/// Exactly one full `BODY[]` literal for the requested UID. Unsolicited records +/// for other UIDs are ignored; a missing record, a `NIL` body, a partial +/// section such as `BODY[HEADER]`, a list-valued body, a duplicated field, or +/// two literals for the requested UID are refused. The literal is length-framed, +/// so a payload that merely looks like a tagged completion or another FETCH +/// record cannot be mistaken for one. +/// +/// A partial section and a second body field are refusals rather than +/// overwrites: the saved file would otherwise report success while holding +/// something that is not the complete original message. fn single_literal(data: &[u8], uid: u32) -> Result> { let mut found: Option> = None; for row in read::nodes(data)? { @@ -59,28 +64,48 @@ fn single_literal(data: &[u8], uid: u32) -> Result> { continue; } let fields = row[3].list(); - let mut row_uid = None; - let mut body: Option>> = None; + let mut row_uid: Option = None; + let mut uid_fields = 0usize; + let mut bodies: Vec>> = Vec::new(); + let mut malformed = false; let mut i = 0; while i + 1 < fields.len() { - let key = &fields[i]; + let name = fields[i].text(); let value = &fields[i + 1]; - if key.is("UID") { + if name.eq_ignore_ascii_case(b"UID") { + uid_fields += 1; row_uid = value.number(); - } else if key.text().to_ascii_uppercase().starts_with(b"BODY[") { - // `BODY[] NIL` is a present but empty body, not a literal. - body = Some(if value.is("NIL") { - None + } else if name.eq_ignore_ascii_case(b"BODY[]") { + // A list-valued body is not a literal, and reading it through + // `text()` would silently become empty bytes. + if value.is_list() { + malformed = true; } else { - Some(value.text().to_vec()) - }); + bodies.push(if value.is("NIL") { + None + } else { + Some(value.text().to_vec()) + }); + } + } else if name + .to_ascii_uppercase() + .starts_with(b"BODY[") + { + // `BODY[HEADER]`, `BODY[1]`, `BODY[TEXT]`, `BODY[]<0>`: any + // section but the whole message cannot be the whole message. + malformed = true; } i += 2; } + // An unsolicited record for another UID is not this message and is + // ignored; only the requested UID's record is judged. if row_uid != Some(uid) { continue; } - match body { + if malformed || uid_fields > 1 || bodies.len() > 1 { + return Err("mail_export_incomplete"); + } + match bodies.pop() { Some(Some(bytes)) => { if found.is_some() { return Err("mail_export_incomplete"); diff --git a/src/providers/imap/read.rs b/src/providers/imap/read.rs index 40fc751..f40fc80 100644 --- a/src/providers/imap/read.rs +++ b/src/providers/imap/read.rs @@ -26,6 +26,11 @@ impl Node { pub(super) fn list(&self) -> &[Node] { if let Self::List(v) = self { v } else { &[] } } + /// A list-valued node is never a body literal. The export path needs to + /// refuse one rather than read it as empty bytes through `text()`. + pub(super) fn is_list(&self) -> bool { + matches!(self, Self::List(_)) + } fn string(&self) -> Result { String::from_utf8(self.text().to_vec()).map_err(|_| "imap_invalid_response") } diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index 178e11f..ae4972f 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -636,6 +636,52 @@ async fn raw_message_refuses_missing_nil_and_duplicate_bodies() { } } +#[tokio::test] +async fn raw_message_refuses_ambiguous_and_partial_records() { + for (response, expected) in [ + // Two body fields in one record: which one is the message? + ( + &b"* 1 FETCH (UID 1 BODY[] {1}\r\nA BODY[] {1}\r\nB)\r\nO1 OK fetched\r\n"[..], + "mail_export_incomplete", + ), + // A partial section is not the whole message. + ( + &b"* 1 FETCH (UID 1 BODY[HEADER] {4}\r\nAAAA)\r\nO1 OK fetched\r\n"[..], + "mail_export_incomplete", + ), + // A list-valued body read through `text()` would be empty bytes. + ( + &b"* 1 FETCH (UID 1 BODY[] (\"a\" \"b\"))\r\nO1 OK fetched\r\n"[..], + "mail_export_incomplete", + ), + // The requested UID must be named exactly once. + ( + &b"* 1 FETCH (UID 1 UID 1 BODY[] {1}\r\nA)\r\nO1 OK fetched\r\n"[..], + "mail_export_incomplete", + ), + // A record with no UID at all is not the requested message. + ( + &b"* 1 FETCH (BODY[] {1}\r\nA)\r\nO1 OK fetched\r\n"[..], + "mail_export_message_missing", + ), + ] { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + w.write_all(response).await.unwrap(); + w.flush().await.unwrap(); + }); + assert_eq!( + call("imap.rawMessage", &export_params(port, 1)).await, + Err(expected) + ); + server_task.await.unwrap(); + } +} + #[tokio::test] async fn raw_message_refuses_a_non_ok_completion() { let (listener, port) = server().await; From 7f8b9e773cf0fc2c7deeae59dd9092fe9fd77d42 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 15:50:19 -0500 Subject: [PATCH 07/20] Enforce the frozen export concurrency, deadline and cancellation controls mail.exportEml ran unbounded: no per-account or global in-flight limit, no 25-second operation deadline, and the provider fetch carried no request token, so a dropped RPC left the IMAP read running. Add a process-wide ExportLimits (one per account, two global), a 25-second deadline checked before the commit point, and an ExportControl whose token reaches imap.rawMessage. A drop guard asks the IMAP cancel registry to stop the fetch unless the exclusive create has already committed the file, so a cancellation that lost the race never reports failure over a saved file. --- src/backend/mail.rs | 21 ++- src/mail/export.rs | 437 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 444 insertions(+), 14 deletions(-) diff --git a/src/backend/mail.rs b/src/backend/mail.rs index 00170a6..03a0795 100644 --- a/src/backend/mail.rs +++ b/src/backend/mail.rs @@ -17,10 +17,18 @@ impl crate::mail::export::ExportAdapter for ProviderExport { &'a self, account: &'a crate::mail::Account, id: &'a str, + request_token: &'a str, ) -> Pin> + Send + 'a>> { Box::pin(async move { let (uid, folder) = crate::providers::imap::message_id(id)?; - let params = json!({"accountId": account.id, "folder": folder, "uid": uid}); + // The token names this fetch in the IMAP cancel registry, so + // dropping the export (or `imap.cancel`) stops the socket read. + let params = json!({ + "accountId": account.id, + "folder": folder, + "uid": uid, + "requestToken": request_token, + }); imap_call("imap.rawMessage", ¶ms).await }) } @@ -387,7 +395,16 @@ impl Session { let request = ExportRequest::try_from(params)?; let refusals = crate::account::refusals_readonly(&request.account.id)?; let downloads = crate::platform::dirs::AppDirs::discover()?.downloads; - crate::mail::export::export_with(request, &ProviderExport, &downloads, &refusals).await + let control = crate::mail::export::ExportControl::new(); + crate::mail::export::export_with( + request, + &ProviderExport, + &downloads, + &refusals, + crate::mail::export::process_limits(), + &control, + ) + .await } _ => Err("unknown_method"), } diff --git a/src/mail/export.rs b/src/mail/export.rs index b433c31..1e1a83a 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -8,22 +8,205 @@ use super::{Account, ExportRequest, Provider}; use base64::{Engine, engine::general_purpose::STANDARD}; use serde_json::{Value, json}; use std::{ + collections::HashMap, future::Future, path::{Path, PathBuf}, pin::Pin, + sync::{ + Arc, OnceLock, + atomic::{AtomicBool, Ordering}, + }, + time::Duration, }; +use tokio::sync::{Notify, OwnedSemaphorePermit, Semaphore}; /// The product limit from E00: below the transport's 32 MiB response bound and /// above the 20 MiB attachment limit. Checked before any unbounded allocation. pub(crate) const MAX_BYTES: usize = 25 * 1024 * 1024; +/// The operation deadline E00 froze. It is enforced inside the export, under +/// the client's 30 s bridge deadline, and never leaves a partial file. +pub(crate) const EXPORT_DEADLINE: Duration = Duration::from_secs(25); + +/// The frozen concurrency ceiling: one export per account, at most two overall. +const GLOBAL_INFLIGHT: usize = 2; +const ACCOUNT_INFLIGHT: usize = 1; + +/// The process-wide concurrency ceiling. Every RPC dispatch shares one of +/// these, so a CLI client and the QML window cannot exceed the frozen limit by +/// asking different accounts at once. Tests build their own, so they neither +/// contend with each other nor leave permits held for an unrelated case. +pub(crate) struct ExportLimits { + global: Arc, + accounts: std::sync::Mutex>>, +} + +impl ExportLimits { + pub(crate) fn new() -> Self { + Self { + global: Arc::new(Semaphore::new(GLOBAL_INFLIGHT)), + accounts: std::sync::Mutex::new(HashMap::new()), + } + } + + fn account(&self, account: &str) -> Arc { + let mut accounts = self.accounts.lock().unwrap_or_else(|error| error.into_inner()); + accounts + .entry(account.to_owned()) + .or_insert_with(|| Arc::new(Semaphore::new(ACCOUNT_INFLIGHT))) + .clone() + } + + /// Take the global permit first, then the account's. A single account can + /// therefore never hold both global permits, and two accounts can run + /// together. Both waits share the operation deadline. + async fn acquire( + &self, + account: &str, + deadline: tokio::time::Instant, + ) -> Result<(OwnedSemaphorePermit, OwnedSemaphorePermit), &'static str> { + let global = self.global.clone(); + let account = self.account(account); + let global = tokio::time::timeout_at(deadline, global.acquire_owned()) + .await + .map_err(|_| "request_timed_out")? + .map_err(|_| "request_cancelled")?; + let account = tokio::time::timeout_at(deadline, account.acquire_owned()) + .await + .map_err(|_| "request_timed_out")? + .map_err(|_| "request_cancelled")?; + Ok((global, account)) + } +} + +static PROCESS_LIMITS: OnceLock = OnceLock::new(); + +/// The concurrency ceiling every dispatch in this backend process shares. +pub(crate) fn process_limits() -> &'static ExportLimits { + PROCESS_LIMITS.get_or_init(ExportLimits::new) +} + +/// An in-process cancellation signal. The select observes it before the commit +/// point; the drop guard raises it when the future is dropped (a disconnected +/// client or an expired RPC) so the provider fetch is stopped as well. +#[derive(Clone, Default)] +struct Cancellation { + inner: Arc, +} + +#[derive(Default)] +struct CancelInner { + cancelled: AtomicBool, + notify: Notify, +} + +impl Cancellation { + fn cancel(&self) { + self.inner.cancelled.store(true, Ordering::SeqCst); + self.inner.notify.notify_waiters(); + } + + fn is_cancelled(&self) -> bool { + self.inner.cancelled.load(Ordering::SeqCst) + } + + async fn cancelled(&self) { + loop { + let notified = self.inner.notify.notified(); + tokio::pin!(notified); + notified.as_mut().enable(); + if self.is_cancelled() { + return; + } + notified.await; + } + } +} + +/// The per-request controls E00 froze. The token names the provider fetch in +/// the IMAP cancel registry; the signal lets the export stop it before commit. +/// Cloning shares both, so the drop guard can cancel a request it did not make. +#[derive(Clone)] +pub(crate) struct ExportControl { + pub(crate) token: String, + cancel: Cancellation, +} + +impl ExportControl { + pub(crate) fn new() -> Self { + static SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + let sequence = SEQUENCE.fetch_add(1, Ordering::Relaxed); + Self { + token: format!("export-{}-{sequence}", std::process::id()), + cancel: Cancellation::default(), + } + } + + /// The in-process signal the deadline select observes. External callers + /// cancel through the provider registry with `token`; this hook exists so a + /// test can cancel a request it did not create. + #[cfg(test)] + pub(crate) fn cancel(&self) { + self.cancel.cancel(); + } +} + +/// Stop the provider fetch when the export is dropped before it commits. The +/// synchronous write cannot be interrupted: once it starts, the operation +/// returns success, so the guard is disarmed at that point rather than +/// cancelling a file that is already on disk. +struct ControlGuard { + account: String, + token: String, + cancel: Cancellation, + armed: bool, +} + +impl ControlGuard { + fn new(account: &str, control: &ExportControl) -> Self { + Self { + account: account.to_owned(), + token: control.token.clone(), + cancel: control.cancel.clone(), + armed: true, + } + } + + fn disarm(&mut self) { + self.armed = false; + } +} + +impl Drop for ControlGuard { + fn drop(&mut self) { + if !self.armed { + return; + } + self.armed = false; + self.cancel.cancel(); + let account = std::mem::take(&mut self.account); + let token = std::mem::take(&mut self.token); + if let Ok(handle) = tokio::runtime::Handle::try_current() { + handle.spawn(async move { + let _ = crate::providers::imap::call( + "imap.cancel", + &json!({"accountId": account, "requestToken": token}), + ) + .await; + }); + } + } +} + /// Fetches the raw provider result (`{"bytes": n, "data": }`) for one -/// account-qualified message. The backend supplies the IMAP-backed one. +/// account-qualified message. The backend supplies the IMAP-backed one; the +/// request token is what the IMAP cancel registry can name. pub(crate) trait ExportAdapter: Send + Sync { fn raw<'a>( &'a self, account: &'a Account, id: &'a str, + request_token: &'a str, ) -> Pin> + Send + 'a>>; } @@ -32,6 +215,8 @@ pub(crate) async fn export_with( adapter: &impl ExportAdapter, downloads: &Path, refusals: &Value, + limits: &ExportLimits, + control: &ExportControl, ) -> Result { // Provider ceiling: only Outlook and generic IMAP share the native path. if !matches!(request.account.provider, Provider::Outlook | Provider::Imap) { @@ -43,11 +228,43 @@ pub(crate) async fn export_with( // Reject a malformed `:` before any credential or network work. crate::providers::imap::message_id(&request.id)?; - // Cancellation is observed here, before the file is created: if this future - // is dropped or refused, nothing is written. Once the write below commits, - // success is returned even if a cancellation arrives afterwards — a - // committed file is never reported as a failure. - let fetched = adapter.raw(&request.account, &request.id).await?; + let mut guard = ControlGuard::new(&request.account.id, control); + let result = run_export(&request, adapter, downloads, limits, control).await; + // `Ok` means the complete file is committed. A cancellation that lost the + // race must not also be reported as a failure, and the guard must not + // cancel the provider fetch that produced the file. + if result.is_ok() { + guard.disarm(); + } + result +} + +async fn run_export( + request: &ExportRequest, + adapter: &impl ExportAdapter, + downloads: &Path, + limits: &ExportLimits, + control: &ExportControl, +) -> Result { + let deadline = tokio::time::Instant::now() + EXPORT_DEADLINE; + if control.cancel.is_cancelled() { + return Err("request_cancelled"); + } + // The ceiling and the fetch both sit under the operation deadline, and both + // stop as soon as a cancellation is observed. + let _permits = tokio::select! { + biased; + _ = control.cancel.cancelled() => return Err("request_cancelled"), + result = limits.acquire(&request.account.id, deadline) => result?, + }; + let fetched = tokio::select! { + biased; + _ = control.cancel.cancelled() => return Err("request_cancelled"), + result = tokio::time::timeout_at( + deadline, + adapter.raw(&request.account, &request.id, &control.token), + ) => result.map_err(|_| "request_timed_out")??, + }; let data = fetched["data"].as_str().ok_or("mail_export_incomplete")?; // Refuse an over-limit payload before decoding it. if data.len() > MAX_BYTES.div_ceil(3) * 4 + 1024 { @@ -58,6 +275,16 @@ pub(crate) async fn export_with( return Err("mail_export_too_large"); } + // The commit point is the exclusive create. A cancellation or a deadline + // observed before it leaves no file; once the write starts it is not + // interruptible and the operation returns success. + if control.cancel.is_cancelled() { + return Err("request_cancelled"); + } + if tokio::time::Instant::now() >= deadline { + return Err("request_timed_out"); + } + let filename = export_filename(&request.suggested_name); std::fs::create_dir_all(downloads).map_err(|_| "mail_export_write_failed")?; let path = write_unique(downloads, &filename, &bytes)?; @@ -223,16 +450,74 @@ mod tests { &'a self, _account: &'a Account, _id: &'a str, + _request_token: &'a str, ) -> Pin> + Send + 'a>> { let payload = self.payload.clone(); Box::pin(async move { Ok(payload) }) } } + /// A fetch that stays in flight long enough for another export to be + /// attempted, and records how many ran at once. + struct Counting { + current: Arc, + peak: Arc, + } + impl Counting { + fn new() -> Self { + Self { + current: Arc::new(AtomicUsize::new(0)), + peak: Arc::new(AtomicUsize::new(0)), + } + } + } + impl ExportAdapter for Counting { + fn raw<'a>( + &'a self, + _account: &'a Account, + _id: &'a str, + _request_token: &'a str, + ) -> Pin> + Send + 'a>> { + let current = self.current.clone(); + let peak = self.peak.clone(); + Box::pin(async move { + let now = current.fetch_add(1, Ordering::SeqCst) + 1; + peak.fetch_max(now, Ordering::SeqCst); + tokio::time::sleep(Duration::from_millis(5)).await; + current.fetch_sub(1, Ordering::SeqCst); + let bytes = b"Subject: hi\r\n\r\nbody"; + Ok(json!({"bytes": bytes.len(), "data": STANDARD.encode(bytes)})) + }) + } + } + + /// A fetch that never answers, so the operation deadline is what ends it. + struct Hanging { + started: Arc, + } + impl ExportAdapter for Hanging { + fn raw<'a>( + &'a self, + _account: &'a Account, + _id: &'a str, + _request_token: &'a str, + ) -> Pin> + Send + 'a>> { + let started = self.started.clone(); + Box::pin(async move { + started.notify_one(); + std::future::pending::>().await + }) + } + } + fn request() -> ExportRequest { + request_for("imap:person@example.test") + } + + fn request_for(account: &str) -> ExportRequest { ExportRequest { account: Account { - id: "imap:person@example.test".into(), + id: account.into(), provider: Provider::Imap, }, id: "42:INBOX".into(), @@ -242,7 +527,17 @@ mod tests { async fn run(payload: Value) -> Result { let dir = scratch("run"); - let result = export_with(request(), &Fake { payload }, &dir, &Value::Null).await; + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let result = export_with( + request(), + &Fake { payload }, + &dir, + &Value::Null, + &limits, + &control, + ) + .await; fs::remove_dir_all(dir).ok(); result } @@ -270,9 +565,18 @@ mod tests { let dir = scratch("commit"); let bytes = b"Subject: hi\r\n\r\nbody \xc3\xa9"; let payload = json!({"bytes": bytes.len(), "data": STANDARD.encode(bytes)}); - let result = export_with(request(), &Fake { payload }, &dir, &Value::Null) - .await - .unwrap(); + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let result = export_with( + request(), + &Fake { payload }, + &dir, + &Value::Null, + &limits, + &control, + ) + .await + .unwrap(); assert_eq!(result["accountId"], "imap:person@example.test"); assert_eq!(result["messageId"], "42:INBOX"); assert_eq!(result["filename"], "Project update.eml"); @@ -289,10 +593,119 @@ mod tests { let mut request = request(); request.account.provider = Provider::Gmail; assert_eq!( - export_with(request, &Fake { payload: json!({}) }, &dir, &Value::Null).await, + export_with( + request, + &Fake { payload: json!({}) }, + &dir, + &Value::Null, + &ExportLimits::new(), + &ExportControl::new(), + ) + .await, Err("mail_export_unsupported") ); assert!(fs::read_dir(&dir).unwrap().next().is_none()); fs::remove_dir_all(dir).unwrap(); } + + // One account exports one message at a time, however many RPC clients ask. + #[tokio::test] + async fn at_most_one_export_runs_per_account() { + let dir = scratch("per-account"); + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let adapter = Counting::new(); + let results = futures_util::future::join_all((0..3).map(|_| { + export_with( + request(), + &adapter, + &dir, + &Value::Null, + &limits, + &control, + ) + })) + .await; + assert!(results.iter().all(Result::is_ok), "every export committed"); + assert_eq!(adapter.peak.load(Ordering::SeqCst), 1); + fs::remove_dir_all(dir).unwrap(); + } + + // Two accounts may run together; a third waits for one of them. + #[tokio::test] + async fn at_most_two_exports_run_across_accounts() { + let dir = scratch("global"); + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let adapter = Counting::new(); + let results = futures_util::future::join_all( + ["imap:a@example.test", "imap:b@example.test", "imap:c@example.test"] + .map(request_for) + .map(|request| { + export_with( + request, + &adapter, + &dir, + &Value::Null, + &limits, + &control, + ) + }), + ) + .await; + assert!(results.iter().all(Result::is_ok), "every export committed"); + assert_eq!(adapter.peak.load(Ordering::SeqCst), 2); + fs::remove_dir_all(dir).unwrap(); + } + + #[tokio::test(start_paused = true)] + async fn an_export_that_reaches_the_deadline_writes_nothing() { + let dir = scratch("deadline"); + let adapter = Hanging { + started: Arc::new(Notify::new()), + }; + assert_eq!( + export_with( + request(), + &adapter, + &dir, + &Value::Null, + &ExportLimits::new(), + &ExportControl::new(), + ) + .await, + Err("request_timed_out") + ); + assert!(fs::read_dir(&dir).unwrap().next().is_none()); + fs::remove_dir_all(dir).unwrap(); + } + + #[tokio::test] + async fn a_cancellation_before_commit_writes_nothing() { + let started = Arc::new(Notify::new()); + let control = ExportControl::new(); + let cancel = control.clone(); + let dir = scratch("cancel"); + let worker_dir = dir.clone(); + let worker_started = started.clone(); + let handle = tokio::spawn(async move { + let adapter = Hanging { + started: worker_started, + }; + export_with( + request(), + &adapter, + &worker_dir, + &Value::Null, + &ExportLimits::new(), + &control, + ) + .await + }); + started.notified().await; + cancel.cancel(); + assert_eq!(handle.await.unwrap(), Err("request_cancelled")); + assert!(fs::read_dir(&dir).unwrap().next().is_none()); + fs::remove_dir_all(dir).unwrap(); + } } From d5f957e4c3dc0bff37e6b696b823d4832532b8e7 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 15:50:23 -0500 Subject: [PATCH 08/20] Route and gate message exports at one dispatch boundary The message menu captured only the message id and resolved its account when the row was chosen, so opening it on account A, switching to B, and choosing the row dispatched B's message with the same id. The keyboard path also asked the provider rather than the advertised backend method, so a backend without mail.exportEml still dispatched. Capture the owning account and the provider's own message id when the menu opens, route every entry point through Service.exportEmlFor, and refuse a captured owner that is no longer on screen. Gate each entry point on the provider capability, readiness and the connected backend's method list. Also project the emlExport capability in Registry.js (it was present in the native snapshot but dropped from the UI projection, so MailAccount.canExportEml was always false), and emit a busy notice that survives the notice timer while an export is in flight. --- ui/Service.qml | 46 ++++- ui/account/MailAccount.qml | 8 +- ui/components/MessageMenu.qml | 31 +++- ui/providers/Registry.js | 3 +- ui/tests/qml/BackendFixture.js | 7 +- ui/tests/qml/tst_export_routing.qml | 206 +++++++++++++++++++++++ ui/tests/qml/tst_message_menu_export.qml | 60 ++++++- ui/tests/test_provider.js | 9 + 8 files changed, 355 insertions(+), 15 deletions(-) create mode 100644 ui/tests/qml/tst_export_routing.qml diff --git a/ui/Service.qml b/ui/Service.qml index eeeb729..ca46ebf 100644 --- a/ui/Service.qml +++ b/ui/Service.qml @@ -2179,9 +2179,53 @@ Item { if (!host) host = current return !!host && host.canExportEml } + // The mailbox that owns a message id. A merged id carries its owner; a bare + // native id belongs to the mailbox on screen. The message menu captures this + // when it opens, so a later account switch cannot re-route the action. + function accountForMessage(id) { + var host = hostForId(id) + return host ? String(host.accountId || "") : "" + } + // The dispatch boundary every export entry point goes through. `accountId` + // and `id` are the owning mailbox and that mailbox's own name for the + // message, captured by a caller that must keep them across an account + // switch. A non-unified view refuses when the captured mailbox is no longer + // the one on screen: 42:INBOX is a different message in the next account. + function exportEmlFor(accountId, id) { + var target = String(id || "") + if (target === "") return false + if (!backendCanExportEml) { + fail("Saving .eml needs a newer Omamail backend") + return false + } + var owner = String(accountId || "") === "" ? current : findAccount(String(accountId)) + if (!owner) { + fail("That mailbox is no longer set up, so nothing was saved") + return false + } + if (!unified && owner !== current) { + fail("That message is no longer on screen, so nothing was saved") + return false + } + if (!owner.ready) { + owner.fail("Sign in before saving a message as .eml") + return false + } + if (!owner.canExportEml) { + owner.fail("This mailbox cannot save messages as .eml") + return false + } + return owner.exportEml(target) + } function exportEml(id) { + if (!canExportEmlFor(id)) { + fail("This mailbox cannot save messages as .eml") + return false + } var host = hostForId(id) - return host ? host.exportEml(sourceIdFor(id)) : false + if (!host) host = current + if (!host) return false + return exportEmlFor(host.accountId, sourceIdFor(id)) } // Save as .eml from the keyboard: the reader's open message, else the list's // cursor row. Resolved here so App.qml stays a one-line case like the rest. diff --git a/ui/account/MailAccount.qml b/ui/account/MailAccount.qml index ef984ab..9c8e3b4 100644 --- a/ui/account/MailAccount.qml +++ b/ui/account/MailAccount.qml @@ -2024,6 +2024,9 @@ Item { var parameters = {account: accountId, id: target, suggestedName: subjectForEml(target)} exportingEml = true exportingEmlId = target + // The busy state is visible from the moment the work starts, not only when + // a duplicate is refused or the file lands. + note("Saving " + (subjectForEml(target) || "message") + " as .eml…") backend.call("mail.exportEml", parameters, function(result, error) { root.exportingEml = false root.exportingEmlId = "" @@ -2964,7 +2967,10 @@ Item { Timer { id: noticeTimer interval: 4000 - onTriggered: root.actionStatus = "" + // A busy notice has to outlive the timer: an export can take longer than + // four seconds, and a status line that blanked mid-write would look idle + // while the file was still being fetched. + onTriggered: if (!root.exportingEml) root.actionStatus = "" } diff --git a/ui/components/MessageMenu.qml b/ui/components/MessageMenu.qml index f75ee77..e150388 100644 --- a/ui/components/MessageMenu.qml +++ b/ui/components/MessageMenu.qml @@ -28,6 +28,12 @@ Item { property real anchorX: 0 property real anchorY: 0 property int cursorIndex: -1 + // The mailbox that owns the message this menu was opened on, and that + // mailbox's own name for it. Captured at open time: a menu can outlive an + // account switch, and "42:INBOX" is a different message in the next account, + // so resolving the owner when the row is chosen would reach the wrong mail. + property string ownerAccountId: "" + property string nativeId: "" readonly property var menuRows: [continueRow, replyRow, replyAllRow, forwardRow, archiveRow, unarchiveRow, moveRow, trashRow, spamRow, readRow, starRow, exportRow, browserRow, aiRow] @@ -89,6 +95,15 @@ Item { function openMenu(id, sceneX, sceneY) { root.messageId = String(id || "") if (!root.summary) return + // Capture the owner and the provider's own id now, while the menu still + // names the message it was opened on. A member of a conversation is one + // message, so the native member id is what is kept rather than the row. + root.ownerAccountId = root.service + && typeof root.service.accountForMessage === "function" + ? String(root.service.accountForMessage(root.messageId) || "") : "" + root.nativeId = root.service && typeof root.service.sourceIdFor === "function" + ? String(root.service.sourceIdFor(root.messageId) || root.messageId) + : root.messageId var local = root.mapFromGlobal(sceneX, sceneY) anchorX = local.x anchorY = local.y @@ -131,6 +146,16 @@ Item { else root.composeRequested(mode, id) } + // Saved through the same boundary the keyboard uses, with the account and + // native id captured when the menu opened rather than resolved now. + function exportMessage() { + var account = root.ownerAccountId + var id = root.nativeId + menu.close() + if (root.service && typeof root.service.exportEmlFor === "function") + root.service.exportEmlFor(account, id) + } + QQC.Popup { id: menu width: Style.space(200) @@ -252,11 +277,7 @@ Item { // Writes to the user's disk through the backend rather than through a // provider verb, so it goes straight to the service the way Open in // browser does. - onActivated: { - var id = root.messageId - menu.close() - if (root.service) root.service.exportEml(id) - } + onActivated: root.exportMessage() } MenuSeparatorLine { diff --git a/ui/providers/Registry.js b/ui/providers/Registry.js index afc7390..971d867 100644 --- a/ui/providers/Registry.js +++ b/ui/providers/Registry.js @@ -25,7 +25,8 @@ function capabilities(values) { webBox: raw.webBox === true, search: raw.search === true, manageLabels: raw.manageLabels === true, - send: raw.send === true + send: raw.send === true, + emlExport: raw.emlExport === true } } diff --git a/ui/tests/qml/BackendFixture.js b/ui/tests/qml/BackendFixture.js index 288ad1c..645517a 100644 --- a/ui/tests/qml/BackendFixture.js +++ b/ui/tests/qml/BackendFixture.js @@ -21,7 +21,7 @@ function install(service) { if (!pipe) throw new Error("No backend fixture pipe") for (var i = 0; i < installed.length; i++) if (installed[i].service === service) return installed[i].listener - var listener = Qt.createQmlObject('import QtQuick; Connections { target: null; objectName: "native-domain-fixture"; property var handler; property var requests: []; property var answers: ({}); property var record: ({active:false,returnView:"",draft:null,parked:[]}); property int revision: 1; function onWrittenChanged() { handler(target.written) } }', service) + var listener = Qt.createQmlObject('import QtQuick; Connections { target: null; objectName: "native-domain-fixture"; property var handler; property var requests: []; property var answers: ({}); property var errors: ({}); property var record: ({active:false,returnView:"",draft:null,parked:[]}); property int revision: 1; function onWrittenChanged() { handler(target.written) } }', service) var offset = pipe.written.length listener.handler = function(written) { var lines = written.slice(offset).split("\n") @@ -37,6 +37,11 @@ function install(service) { result = {record:listener.record,revision:String(listener.revision)} } if (request.method === "outbox.snapshot") result = {accountId:request.params.accountId,revision:0,entries:[]} + if (Object.prototype.hasOwnProperty.call(listener.errors, request.method)) { + var failure = listener.errors[request.method] + respond(service, request, null, typeof failure === "function" ? failure(request.params || {}, request) : failure) + continue + } if (Object.prototype.hasOwnProperty.call(listener.answers, request.method)) { var override = listener.answers[request.method] result = typeof override === "function" ? override(request.params || {}, request) : override diff --git a/ui/tests/qml/tst_export_routing.qml b/ui/tests/qml/tst_export_routing.qml new file mode 100644 index 0000000..b4335ad --- /dev/null +++ b/ui/tests/qml/tst_export_routing.qml @@ -0,0 +1,206 @@ +import QtQuick 2.15 +import QtTest 1.3 +import "../.." as Omamail +import "BackendFixture.js" as BackendFixture +import "../../account/Accounts.js" as Accounts +import "../../account/Unified.js" as Unified + +// The export dispatch boundary, against a real `Service` with real account +// hosts. Two properties matter here that a mocked menu callback cannot show: +// the advertised backend method is asked before anything is dispatched, and a +// menu captured on account A cannot reach account B's mailbox after a switch. +// The accounts are real but credentialless, so the synthetic backend answers +// the export and nothing touches a server. +Item { + id: fixtureRoot + width: 900 + height: 600 + + QtObject { + id: shellStore + function updateEntryInline(_id, _entry) {} + function hide(_id) {} + } + + Component { + id: controlledClient + QtObject { + property var refusals: null + property var absentMailboxes: null + property string email: "" + function handle() { return { aborted: false } } + function later(fn) { Qt.callLater(fn); return handle() } + function listMessages() { return handle() } + function getMessages() { return handle() } + function getMessage() { return handle() } + function getLabels() { return handle() } + function getLabelCounts() { return handle() } + function getProfile(callback) { + return later(function() { callback({ email: email }, "") }) + } + function getSendAs(callback) { + return later(function() { callback([], "") }) + } + function abortRequest(handle) { if (handle) handle.aborted = true } + } + } + + Omamail.Service { + id: service + shell: shellStore + manifest: ({ id: "omamail", __sourceDir: "/tmp/omamail-export-test" }) + } + + TestCase { + name: "ExportRouting" + when: windowShown + + readonly property string ada: "imap:ada@example.org" + readonly property string bob: "imap:bob@example.org" + property var fixture: null + property int exportBaseline: 0 + + function entry(email) { + return { email: email, provider: "imap", clientId: "", clientSecret: "", + imap: { imapHost: "imap.example.org", imapPort: 993, + smtpHost: "smtp.example.org", smtpPort: 465, + username: email, aliases: [], insecure: false }, + label: "", signature: "", monitored: [] } + } + + function seed() { + var list = Accounts.emptyList() + list = Accounts.add(list, entry("ada@example.org")) + list = Accounts.add(list, entry("bob@example.org")) + list = Accounts.setActive(list, ada) + service.activeIndex = -1 + service.accountList = list + service.accountsLoaded = true + wait(0) + service.refreshCurrent() + for (var i = 0; i < 2; i++) { + var account = service.accountAt(i) + verify(account !== null) + account.clientOverride = controlledClient + account.auth.toolsChecked = true + account.auth.missingTools = [] + account.auth.passwordChecked = true + account.auth.password = "synthetic-password" + tryCompare(account, "ready", true) + } + } + + function init() { + service.applySettings({ unifiedMailboxes: false }) + fixture = BackendFixture.markReady(service, 6) + seed() + service.backend.protocolInfo = { apiVersion: 6, protocol: 1, version: "0.0.0", + methods: ["mail.exportEml"] } + wait(0) + exportBaseline = exportRequests().length + } + + function exportRequests() { + var requests = [] + for (var i = 0; i < service.backend.children.length; i++) { + var child = service.backend.children[i] + if (!child.written) continue + var lines = child.written.split("\n") + for (var j = 0; j < lines.length; j++) { + if (!lines[j]) continue + var request = JSON.parse(lines[j]) + if (request.method === "mail.exportEml") requests.push(request.params) + } + } + return requests + } + + // With the method absent, both entry points are refused before anything is + // sent — the keyboard path used to dispatch because it asked the provider + // rather than the advertised method list. + function test_the_export_requires_the_advertised_method() { + service.backend.protocolInfo = { apiVersion: 5, protocol: 1, version: "0.0.0", + methods: ["mail.read"] } + wait(0) + compare(service.canExportEmlFor("42:INBOX"), false, + "the menu row is unavailable") + compare(service.exportEml("42:INBOX"), false, + "and the keyboard entry point is refused") + compare(service.exportFromView("list", "42:INBOX"), false) + compare(exportRequests().length - exportBaseline, 0, "nothing was dispatched") + } + + function test_the_keyboard_export_reaches_the_owning_mailbox() { + compare(service.activeAccountId, ada) + compare(service.canExportEmlFor("42:INBOX"), true) + compare(service.exportEml("42:INBOX"), true) + var requests = exportRequests().slice(exportBaseline) + compare(requests.length, 1) + compare(requests[0].account, ada) + compare(requests[0].id, "42:INBOX") + } + + // A menu opened on A keeps A's id and account. Switching to B, where + // 42:INBOX is a different message, must not re-route the saved file. + function test_a_menu_stale_after_an_account_switch_is_refused() { + var captured = service.accountForMessage("42:INBOX") + var native = service.sourceIdFor("42:INBOX") + compare(captured, ada) + service.switchTo(bob) + wait(0) + compare(service.activeAccountId, bob, "B is on screen now") + var before = exportRequests().length + compare(service.exportEmlFor(captured, native), false, + "the captured owner is no longer the mailbox on screen") + compare(exportRequests().length, before, "and nothing was dispatched") + } + + // A conversation-rail member is one message with a composed id. The + // service keeps its account and hands the provider the member's native id. + function test_a_unified_member_reaches_its_owning_mailbox() { + service.applySettings({ unifiedMailboxes: true }) + wait(0) + compare(service.unified, true) + var memberId = Unified.unifiedId(ada, "17:INBOX") + compare(service.accountForMessage(memberId), ada) + compare(service.sourceIdFor(memberId), "17:INBOX") + compare(service.exportEmlFor(service.accountForMessage(memberId), + service.sourceIdFor(memberId)), true) + var requests = exportRequests().slice(exportBaseline) + compare(requests[requests.length - 1].account, ada) + compare(requests[requests.length - 1].id, "17:INBOX") + } + + function test_a_busy_notice_then_the_saved_file() { + fixture.answers["mail.exportEml"] = function(params) { + return { accountId: params.account, messageId: params.id, + path: "/tmp/Downloads/Project update.eml", + filename: "Project update.eml", bytes: 12 } + } + var account = service.findAccount(ada) + account.clearNotice() + account.messages = [{ id: "42:INBOX", subject: "Project update" }] + compare(account.exportingEml, false) + compare(account.exportEml("42:INBOX"), true) + compare(account.exportingEml, true, "the write is in flight") + verify(account.actionStatus.indexOf("Saving") === 0, + "the busy state is visible at once") + wait(0) + compare(account.exportingEml, false) + verify(account.actionStatus.indexOf("Project update.eml") >= 0, + "the completion names the file") + verify(account.lastError === "", "and it is not reported as a failure") + } + + function test_a_failed_export_is_reported_safely() { + fixture.errors["mail.exportEml"] = { code: -32000, message: "mail_export_write_failed" } + var account = service.findAccount(ada) + account.clearNotice() + compare(account.exportEml("42:INBOX"), true) + compare(account.exportingEml, true) + wait(0) + compare(account.exportingEml, false) + verify(account.lastError !== "", "the backend error reaches the status line") + } + } +} diff --git a/ui/tests/qml/tst_message_menu_export.qml b/ui/tests/qml/tst_message_menu_export.qml index 08de971..d58e805 100644 --- a/ui/tests/qml/tst_message_menu_export.qml +++ b/ui/tests/qml/tst_message_menu_export.qml @@ -4,7 +4,8 @@ import "../../components" as Omamail // "Save as .eml" in the message menu: it appears only where the service says // the provider and the connected backend can do it, and choosing it asks the -// service for that exact message rather than routing through a provider verb. +// service for the account and native id captured when the menu opened rather +// than resolving them against whatever mailbox is on screen when it is chosen. Item { width: 500 height: 500 @@ -18,10 +19,26 @@ Item { property bool hasLabels: false property string rawLabelId: "" property bool exportable: true - property var exportedIds: [] + property var exported: [] property var messages: [] + property var memberSummaries: ({}) + property string ada: "imap:ada@example.org" + // The menu captures the owner and the provider's own id at open time. A + // row id belongs to the visible mailbox; a member id in this fixture is + // composed as `/` so the two answers are distinguishable. function canExportEmlFor(id) { return exportable } - function exportEml(id) { exportedIds = exportedIds.concat([String(id)]); return true } + function accountForMessage(id) { + var at = String(id).indexOf("/") + return at > 0 ? String(id).substring(0, at) : ada + } + function sourceIdFor(id) { + var at = String(id).indexOf("/") + return at > 0 ? String(id).substring(at + 1) : String(id) + } + function exportEmlFor(accountId, id) { + exported = exported.concat([{ account: String(accountId), id: String(id) }]) + return true + } } Omamail.MessageMenu { @@ -49,14 +66,33 @@ Item { isSent: false, isDraft: false, labelIds: [] } } + function memberSummary(id) { + var value = summary() + value.id = id + value.sourceId = "42:INBOX" + return value + } + function show() { fakeService.messages = [summary()] - fakeService.exportedIds = [] + fakeService.memberSummaries = ({}) + fakeService.exported = [] menu.close() menu.openAt("42:INBOX", 100, 100) wait(20) } + function showMember(id) { + fakeService.messages = [] + var members = ({}) + members[id] = memberSummary(id) + fakeService.memberSummaries = members + fakeService.exported = [] + menu.close() + menu.openForMember(id, 100, 100) + wait(20) + } + function cleanup() { menu.close() } function test_the_row_appears_only_when_the_service_says_it_can() { @@ -71,12 +107,24 @@ Item { "a provider or backend without export must not offer the row") } - function test_choosing_it_asks_the_service_for_that_message() { + function test_choosing_it_routes_the_owning_account_and_message() { fakeService.exportable = true show() exportRow().activated() - compare(fakeService.exportedIds, ["42:INBOX"]) + compare(fakeService.exported, [{ account: fakeService.ada, id: "42:INBOX" }]) compare(menu.opened, false, "the menu closes on choosing") } + + // A stop on the conversation rail is one message, and its id is the + // composed member id. The menu keeps the account and the member's native + // id, so the export reaches that member rather than the list's root row. + function test_a_member_menu_routes_the_member_id() { + fakeService.exportable = true + showMember(fakeService.ada + "/17:INBOX") + compare(exportRow().visible, true) + exportRow().activated() + compare(fakeService.exported, [{ account: fakeService.ada, id: "17:INBOX" }], + "the native member id, not the composed rail id") + } } } diff --git a/ui/tests/test_provider.js b/ui/tests/test_provider.js index 1f21d07..3eea9ef 100644 --- a/ui/tests/test_provider.js +++ b/ui/tests/test_provider.js @@ -92,6 +92,15 @@ assert.strictEqual(provider.can("imap", "star"), true, "\\Flagged is a star") assert.strictEqual(provider.can("imap", "web"), false, "no web UI to open a message in") assert.strictEqual(provider.can("gmail", "web"), true) +// Saving the original message bytes is a native path only Outlook and generic +// IMAP speak, and it is a capability like any other so the menu can hide the +// row where it would fail. +assert.strictEqual(provider.can("imap", "emlExport"), true) +assert.strictEqual(provider.can("outlook", "emlExport"), true) +assert.strictEqual(provider.can("gmail", "emlExport"), false) +assert.strictEqual(provider.can("hey", "emlExport"), false) +assert.strictEqual(provider.can("jmap", "emlExport"), false) + // Opening a message on the web and opening *this mailbox* on the web are two // questions. HEY gives every thread an address of its own but has none for a // search or a label, so the second answer is no — an "Open web inbox" there From e045e1e24b559e7ca810e97d36c60f83748c5d2f Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 15:58:26 -0500 Subject: [PATCH 09/20] Test raw export parsing without holding pooled connections The malformed-record cases do not need a socket: they are a property of single_literal's framing. Running them over the loopback server left five idle connections in the global pool, which pushed the reuse test over the 32-entry cap and made it open a second connection. Assert the parser directly, so the cases stay fast and leave no transport state for the next test. --- src/providers/imap/export.rs | 65 ++++++++++++++++++++++++++++++++++++ src/providers/imap/tests.rs | 46 ------------------------- 2 files changed, 65 insertions(+), 46 deletions(-) diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index 3ea8538..0a1a179 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -118,3 +118,68 @@ fn single_literal(data: &[u8], uid: u32) -> Result> { } found.ok_or("mail_export_message_missing") } + +#[cfg(test)] +mod tests { + use super::*; + + /// The parser reads the framed response directly, so a malformed FETCH + /// record needs no socket and no pooled IMAP connection. + fn literal(record: &str) -> Result> { + let mut data = record.as_bytes().to_vec(); + data.extend_from_slice(b"O1 OK fetched\r\n"); + single_literal(&data, 1) + } + + #[test] + fn raw_message_returns_a_full_body_literal() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] {4}\r\nABCD)\r\n"), + Ok(b"ABCD".to_vec()) + ); + } + + #[test] + fn raw_message_refuses_two_body_fields_in_one_record() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] {1}\r\nA BODY[] {1}\r\nB)\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_refuses_a_partial_body_section() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[HEADER] {4}\r\nAAAA)\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_refuses_a_list_valued_body() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] (\"a\" \"b\"))\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_refuses_a_duplicate_uid() { + assert_eq!( + literal("* 1 FETCH (UID 1 UID 1 BODY[] {1}\r\nA)\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_refuses_a_mismatched_or_missing_uid() { + assert_eq!( + literal("* 1 FETCH (UID 2 BODY[] {1}\r\nA)\r\n"), + Err("mail_export_message_missing") + ); + assert_eq!( + literal("* 1 FETCH (BODY[] {1}\r\nA)\r\n"), + Err("mail_export_message_missing") + ); + } +} diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index ae4972f..178e11f 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -636,52 +636,6 @@ async fn raw_message_refuses_missing_nil_and_duplicate_bodies() { } } -#[tokio::test] -async fn raw_message_refuses_ambiguous_and_partial_records() { - for (response, expected) in [ - // Two body fields in one record: which one is the message? - ( - &b"* 1 FETCH (UID 1 BODY[] {1}\r\nA BODY[] {1}\r\nB)\r\nO1 OK fetched\r\n"[..], - "mail_export_incomplete", - ), - // A partial section is not the whole message. - ( - &b"* 1 FETCH (UID 1 BODY[HEADER] {4}\r\nAAAA)\r\nO1 OK fetched\r\n"[..], - "mail_export_incomplete", - ), - // A list-valued body read through `text()` would be empty bytes. - ( - &b"* 1 FETCH (UID 1 BODY[] (\"a\" \"b\"))\r\nO1 OK fetched\r\n"[..], - "mail_export_incomplete", - ), - // The requested UID must be named exactly once. - ( - &b"* 1 FETCH (UID 1 UID 1 BODY[] {1}\r\nA)\r\nO1 OK fetched\r\n"[..], - "mail_export_incomplete", - ), - // A record with no UID at all is not the requested message. - ( - &b"* 1 FETCH (BODY[] {1}\r\nA)\r\nO1 OK fetched\r\n"[..], - "mail_export_message_missing", - ), - ] { - let (listener, port) = server().await; - let server_task = tokio::spawn(async move { - let (socket, _) = listener.accept().await.unwrap(); - let mut w: Wire = BufReader::new(Box::new(socket)); - login_and_examine(&mut w).await; - assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); - w.write_all(response).await.unwrap(); - w.flush().await.unwrap(); - }); - assert_eq!( - call("imap.rawMessage", &export_params(port, 1)).await, - Err(expected) - ); - server_task.await.unwrap(); - } -} - #[tokio::test] async fn raw_message_refuses_a_non_ok_completion() { let (listener, port) = server().await; From 1d302c729aee08c01c59a388ddc7cc343d3b543b Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 15:59:40 -0500 Subject: [PATCH 10/20] Keep the export routing test independent of test order The unified-member case dispatched an export and relied on a response left by an earlier test to clear the mailbox's in-flight flag. Give every test a default synthetic answer and reset the flag when seeding, so each case starts from the same state and no case depends on which ran before it. --- ui/tests/qml/tst_export_routing.qml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/ui/tests/qml/tst_export_routing.qml b/ui/tests/qml/tst_export_routing.qml index b4335ad..d02fb5e 100644 --- a/ui/tests/qml/tst_export_routing.qml +++ b/ui/tests/qml/tst_export_routing.qml @@ -86,6 +86,8 @@ Item { account.auth.missingTools = [] account.auth.passwordChecked = true account.auth.password = "synthetic-password" + account.exportingEml = false + account.exportingEmlId = "" tryCompare(account, "ready", true) } } @@ -93,6 +95,14 @@ Item { function init() { service.applySettings({ unifiedMailboxes: false }) fixture = BackendFixture.markReady(service, 6) + // Every dispatch completes, so no test inherits an in-flight flag from + // another. A test that wants a specific filename or an error overrides + // this answer or adds an error for the method. + fixture.answers = { "mail.exportEml": function(params) { + return { accountId: params.account, messageId: params.id, + path: "/tmp/Downloads/message.eml", filename: "message.eml", bytes: 1 } + } } + fixture.errors = ({}) seed() service.backend.protocolInfo = { apiVersion: 6, protocol: 1, version: "0.0.0", methods: ["mail.exportEml"] } From f462a0bed78c7a5c6a3651edec5c774b278caf46 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 16:40:23 -0500 Subject: [PATCH 11/20] E03: require literal-provenance IMAP bodies for export --- src/providers/imap/export.rs | 61 ++++++++++++++++++++++++++++++------ src/providers/imap/read.rs | 19 +++++++---- 2 files changed, 65 insertions(+), 15 deletions(-) diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index 0a1a179..f326f88 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -76,16 +76,17 @@ fn single_literal(data: &[u8], uid: u32) -> Result> { uid_fields += 1; row_uid = value.number(); } else if name.eq_ignore_ascii_case(b"BODY[]") { - // A list-valued body is not a literal, and reading it through - // `text()` would silently become empty bytes. - if value.is_list() { - malformed = true; + if value.is_literal() { + // A length-framed literal is the only accepted body. A + // literal whose content happens to read "NIL" is still + // those bytes, not the absent-message marker. + bodies.push(Some(value.text().to_vec())); + } else if value.is("NIL") { + // An atom NIL means the message is gone. + bodies.push(None); } else { - bodies.push(if value.is("NIL") { - None - } else { - Some(value.text().to_vec()) - }); + // An atom, quoted string, or list is not a body literal. + malformed = true; } } else if name .to_ascii_uppercase() @@ -97,6 +98,16 @@ fn single_literal(data: &[u8], uid: u32) -> Result> { } i += 2; } + // A dangling field name (an odd FETCH record) is incomplete structure, + // not a name to ignore. + if i < fields.len() { + let name = fields[i].text(); + if name.eq_ignore_ascii_case(b"UID") + || name.to_ascii_uppercase().starts_with(b"BODY[") + { + malformed = true; + } + } // An unsolicited record for another UID is not this message and is // ignored; only the requested UID's record is judged. if row_uid != Some(uid) { @@ -182,4 +193,36 @@ mod tests { Err("mail_export_message_missing") ); } + + #[test] + fn raw_message_refuses_an_atom_body() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] garbage)\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_refuses_a_quoted_body() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] \"garbage\")\r\n"), + Err("mail_export_incomplete") + ); + } + + #[test] + fn raw_message_treats_a_literal_nil_as_content_not_absence() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] {3}\r\nNIL)\r\n"), + Ok(b"NIL".to_vec()) + ); + } + + #[test] + fn raw_message_refuses_a_dangling_body_field() { + assert_eq!( + literal("* 1 FETCH (UID 1 BODY[] {1}\r\nA BODY[])\r\n"), + Err("mail_export_incomplete") + ); + } } diff --git a/src/providers/imap/read.rs b/src/providers/imap/read.rs index f40fc80..2f9cfc2 100644 --- a/src/providers/imap/read.rs +++ b/src/providers/imap/read.rs @@ -6,12 +6,19 @@ mod search; #[derive(Clone, Debug, PartialEq)] pub(super) enum Node { Text(Vec), + /// A length-framed `{n}\r\n…` literal. Distinct from `Text` so a caller + /// that needs the original bytes can refuse an atom or quoted string that + /// merely looks like them. + Literal(Vec), List(Vec), End, } impl Node { pub(super) fn text(&self) -> &[u8] { - if let Self::Text(t) = self { t } else { b"" } + match self { + Self::Text(t) | Self::Literal(t) => t, + _ => b"", + } } pub(super) fn is(&self, value: &str) -> bool { self.text().eq_ignore_ascii_case(value.as_bytes()) @@ -26,10 +33,10 @@ impl Node { pub(super) fn list(&self) -> &[Node] { if let Self::List(v) = self { v } else { &[] } } - /// A list-valued node is never a body literal. The export path needs to - /// refuse one rather than read it as empty bytes through `text()`. - pub(super) fn is_list(&self) -> bool { - matches!(self, Self::List(_)) + /// Whether this node was a length-framed literal rather than an atom or a + /// quoted string. + pub(super) fn is_literal(&self) -> bool { + matches!(self, Self::Literal(_)) } fn string(&self) -> Result { String::from_utf8(self.text().to_vec()).map_err(|_| "imap_invalid_response") @@ -120,7 +127,7 @@ pub(super) fn nodes(data: &[u8]) -> Result>> { if n > data.len() - *at { return Err("imap_invalid_response"); } - out.push(Node::Text(data[*at..*at + n].to_vec())); + out.push(Node::Literal(data[*at..*at + n].to_vec())); *at += n; } _ => { From 92feff5ae84a3d4a6a6a1c2b908a6186c38b76ca Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 16:40:23 -0500 Subject: [PATCH 12/20] E03: enforce the export deadline, duplicate refusal and anchored storage --- src/mail/export.rs | 339 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 292 insertions(+), 47 deletions(-) diff --git a/src/mail/export.rs b/src/mail/export.rs index 1e1a83a..d4e458c 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -8,7 +8,7 @@ use super::{Account, ExportRequest, Provider}; use base64::{Engine, engine::general_purpose::STANDARD}; use serde_json::{Value, json}; use std::{ - collections::HashMap, + collections::{HashMap, HashSet}, future::Future, path::{Path, PathBuf}, pin::Pin, @@ -39,6 +39,23 @@ const ACCOUNT_INFLIGHT: usize = 1; pub(crate) struct ExportLimits { global: Arc, accounts: std::sync::Mutex>>, + in_flight: Arc>>, +} + +/// Owns one duplicate-admission slot until the export ends. Dropping it on any +/// exit path frees the (account, message) pair for a later request. +struct InFlight { + key: (String, String), + set: Arc>>, +} + +impl Drop for InFlight { + fn drop(&mut self) { + self.set + .lock() + .unwrap_or_else(|error| error.into_inner()) + .remove(&self.key); + } } impl ExportLimits { @@ -46,6 +63,7 @@ impl ExportLimits { Self { global: Arc::new(Semaphore::new(GLOBAL_INFLIGHT)), accounts: std::sync::Mutex::new(HashMap::new()), + in_flight: Arc::new(std::sync::Mutex::new(HashSet::new())), } } @@ -57,9 +75,25 @@ impl ExportLimits { .clone() } - /// Take the global permit first, then the account's. A single account can - /// therefore never hold both global permits, and two accounts can run - /// together. Both waits share the operation deadline. + /// Refuse a request whose (account, message) pair is already exporting, + /// before any scarce capacity is taken. The returned guard releases the + /// slot when dropped, so a later identical request is admitted again. + fn admit(&self, account: &str, id: &str) -> Result { + let key = (account.to_owned(), id.to_owned()); + let mut in_flight = self.in_flight.lock().unwrap_or_else(|error| error.into_inner()); + if !in_flight.insert(key.clone()) { + return Err("mail_export_in_flight"); + } + Ok(InFlight { + key, + set: self.in_flight.clone(), + }) + } + + /// Take the account permit first, then the global one. A queued second + /// request for the same account therefore holds no global permit, so it can + /// never starve a different account. Both waits share the operation + /// deadline. async fn acquire( &self, account: &str, @@ -67,15 +101,15 @@ impl ExportLimits { ) -> Result<(OwnedSemaphorePermit, OwnedSemaphorePermit), &'static str> { let global = self.global.clone(); let account = self.account(account); - let global = tokio::time::timeout_at(deadline, global.acquire_owned()) + let account = tokio::time::timeout_at(deadline, account.acquire_owned()) .await .map_err(|_| "request_timed_out")? .map_err(|_| "request_cancelled")?; - let account = tokio::time::timeout_at(deadline, account.acquire_owned()) + let global = tokio::time::timeout_at(deadline, global.acquire_owned()) .await .map_err(|_| "request_timed_out")? .map_err(|_| "request_cancelled")?; - Ok((global, account)) + Ok((account, global)) } } @@ -228,6 +262,11 @@ pub(crate) async fn export_with( // Reject a malformed `:` before any credential or network work. crate::providers::imap::message_id(&request.id)?; + // A repeated (account, message) request is refused, not queued behind the + // one already saving it. This happens before the cancellation guard exists, + // so a refusal never cancels an in-flight export that shares a control. + let _admission = limits.admit(&request.account.id, &request.id)?; + let mut guard = ControlGuard::new(&request.account.id, control); let result = run_export(&request, adapter, downloads, limits, control).await; // `Ok` means the complete file is committed. A cancellation that lost the @@ -275,29 +314,42 @@ async fn run_export( return Err("mail_export_too_large"); } - // The commit point is the exclusive create. A cancellation or a deadline - // observed before it leaves no file; once the write starts it is not - // interruptible and the operation returns success. - if control.cancel.is_cancelled() { - return Err("request_cancelled"); - } - if tokio::time::Instant::now() >= deadline { - return Err("request_timed_out"); - } - let filename = export_filename(&request.suggested_name); - std::fs::create_dir_all(downloads).map_err(|_| "mail_export_write_failed")?; - let path = write_unique(downloads, &filename, &bytes)?; + let fallback = filename.clone(); + let byte_count = bytes.len(); + let downloads = downloads.to_path_buf(); + let deadline_std = deadline.into_std(); + let cancel = control.cancel.clone(); + // Storage is synchronous create/write/fsync, so it runs on a blocking + // worker rather than a Tokio worker. The destination directory is anchored + // to a descriptor before the deadline is observed, so a path swap after the + // check cannot redirect the write. The exclusive create is the commit + // point: a cancellation or an expired deadline observed before it leaves no + // file; after it the write completes and success is returned. + let path = tokio::task::spawn_blocking(move || { + let dir = crate::platform::private_fs::directories(&downloads, &[], true) + .map_err(|_| "mail_export_write_failed")? + .ok_or("mail_export_write_failed")?; + if cancel.is_cancelled() { + return Err("request_cancelled"); + } + if std::time::Instant::now() >= deadline_std { + return Err("request_timed_out"); + } + write_unique_in(&downloads, &dir, &filename, &bytes) + }) + .await + .map_err(|_| "request_cancelled")??; let saved = path .file_name() .map(|name| name.to_string_lossy().into_owned()) - .unwrap_or(filename); + .unwrap_or(fallback); Ok(json!({ "accountId": request.account.id, "messageId": request.id, "path": path, "filename": saved, - "bytes": bytes.len(), + "bytes": byte_count, })) } @@ -332,12 +384,22 @@ pub(crate) fn export_filename(suggested: &str) -> String { format!("{}.eml", &stem[..end]) } +// Anchored, handle-relative exclusive create. The destination directory is +// pinned by a descriptor so a rename/symlink swap of the path cannot redirect +// the file; the final component is opened with O_NOFOLLOW/O_EXCL so a symlink +// or an existing name is never followed or overwritten. #[cfg(unix)] -fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { +fn write_unique_in( + directory: &Path, + dir: &std::fs::File, + filename: &str, + bytes: &[u8], +) -> Result { use std::{ - fs::OpenOptions, + ffi::CString, + fs::File, io::Write, - os::unix::fs::OpenOptionsExt, + os::fd::{AsRawFd, FromRawFd}, }; let path = Path::new(filename); let stem = path.file_stem().unwrap_or_default().to_string_lossy(); @@ -345,40 +407,63 @@ fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { - if file.write_all(bytes).and_then(|_| file.sync_all()).is_err() { - let _ = std::fs::remove_file(&candidate); - return Err("mail_export_write_failed"); - } - return Ok(candidate); + }; + let Ok(cname) = CString::new(candidate.as_bytes().to_vec()) else { + continue; + }; + let fd = unsafe { + libc::openat( + dir_fd, + cname.as_ptr(), + libc::O_WRONLY + | libc::O_CREAT + | libc::O_EXCL + | libc::O_NOFOLLOW + | libc::O_CLOEXEC, + 0o600, + ) + }; + if fd >= 0 { + let mut file = unsafe { File::from_raw_fd(fd) }; + if file.write_all(bytes).and_then(|_| file.sync_all()).is_err() { + unsafe { libc::unlinkat(dir_fd, cname.as_ptr(), 0) }; + return Err("mail_export_write_failed"); } - Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue, - Err(_) => return Err("mail_export_write_failed"), + return Ok(directory.join(&candidate)); + } + if std::io::Error::last_os_error().kind() == std::io::ErrorKind::AlreadyExists { + continue; } + return Err("mail_export_write_failed"); } Err("mail_export_write_failed") } #[cfg(windows)] +fn write_unique_in( + _directory: &Path, + dir: &std::fs::File, + filename: &str, + bytes: &[u8], +) -> Result { + crate::platform::private_fs::write_unique(dir, filename, bytes) + .map_err(|_| "mail_export_write_failed") +} + +// Anchor the directory then create the file relative to that handle. The +// export path calls `write_unique_in` directly so it can observe the deadline +// between the anchor and the exclusive create; tests use this wrapper. fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { let dir = crate::platform::private_fs::directories(directory, &[], true) .map_err(|_| "mail_export_write_failed")? .ok_or("mail_export_write_failed")?; - crate::platform::private_fs::write_unique(&dir, filename, bytes) - .map_err(|_| "mail_export_write_failed") + write_unique_in(directory, &dir, filename, bytes) } #[cfg(test)] @@ -510,6 +595,37 @@ mod tests { } } + /// Account "a" blocks on a gate; any other account returns immediately. + /// Proves a queued second request for "a" does not hold a global permit. + struct Gated { + a_started: Arc, + b_started: Arc, + gate: Arc, + } + impl ExportAdapter for Gated { + fn raw<'a>( + &'a self, + account: &'a Account, + _id: &'a str, + _request_token: &'a str, + ) -> Pin> + Send + 'a>> { + let account = account.id.clone(); + let a_started = self.a_started.clone(); + let b_started = self.b_started.clone(); + let gate = self.gate.clone(); + Box::pin(async move { + if account.starts_with("imap:a") { + a_started.notify_one(); + let _ = gate.acquire().await; + } else { + b_started.notify_one(); + } + let bytes = b"Subject: hi\r\n\r\nbody"; + Ok(json!({"bytes": bytes.len(), "data": STANDARD.encode(bytes)})) + }) + } + } + fn request() -> ExportRequest { request_for("imap:person@example.test") } @@ -608,10 +724,12 @@ mod tests { fs::remove_dir_all(dir).unwrap(); } - // One account exports one message at a time, however many RPC clients ask. + // A repeated request for the same message is refused, not queued: only one + // (account, message) pair is ever in flight, and the others get a refusal + // rather than waiting their turn to write a second copy. #[tokio::test] - async fn at_most_one_export_runs_per_account() { - let dir = scratch("per-account"); + async fn a_duplicate_request_is_refused_not_queued() { + let dir = scratch("duplicate"); let limits = ExportLimits::new(); let control = ExportControl::new(); let adapter = Counting::new(); @@ -626,7 +744,38 @@ mod tests { ) })) .await; - assert!(results.iter().all(Result::is_ok), "every export committed"); + let ok = results.iter().filter(|r| r.is_ok()).count(); + let refused = results + .iter() + .filter(|r| r.as_ref().err() == Some(&"mail_export_in_flight")) + .count(); + assert_eq!(ok, 1, "exactly one identical export commits"); + assert_eq!(refused, 2, "the other two are refused as in flight"); + assert_eq!(fs::read_dir(&dir).unwrap().count(), 1, "one output file"); + fs::remove_dir_all(dir).unwrap(); + } + + // Different messages on one account still run one at a time. + #[tokio::test] + async fn one_account_exports_one_message_at_a_time() { + let dir = scratch("per-account"); + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let adapter = Counting::new(); + let results = futures_util::future::join_all((0..3).map(|n| { + let mut request = request(); + request.id = format!("{}:INBOX", n + 1); + export_with( + request, + &adapter, + &dir, + &Value::Null, + &limits, + &control, + ) + })) + .await; + assert!(results.iter().all(Result::is_ok), "three different messages commit"); assert_eq!(adapter.peak.load(Ordering::SeqCst), 1); fs::remove_dir_all(dir).unwrap(); } @@ -708,4 +857,100 @@ mod tests { assert!(fs::read_dir(&dir).unwrap().next().is_none()); fs::remove_dir_all(dir).unwrap(); } + + // A queued second request for the same account must not hold a global + // permit, or a different account is starved behind it. The account permit + // is taken before the global one, so account b runs alongside account a. + #[tokio::test] + async fn a_queued_same_account_request_does_not_block_another_account() { + fn spawn_one( + dir: &Path, + limits: &Arc, + control: &ExportControl, + adapter: &Arc, + request: ExportRequest, + ) -> tokio::task::JoinHandle> { + let dir = dir.to_path_buf(); + let limits = limits.clone(); + let control = control.clone(); + let adapter = adapter.clone(); + tokio::spawn(async move { + export_with( + request, + adapter.as_ref(), + &dir, + &Value::Null, + limits.as_ref(), + &control, + ) + .await + }) + } + + let dir = scratch("fairness"); + let limits = Arc::new(ExportLimits::new()); + let control = ExportControl::new(); + let a_started = Arc::new(Notify::new()); + let b_started = Arc::new(Notify::new()); + let gate = Arc::new(Semaphore::new(0)); + let adapter = Arc::new(Gated { + a_started: a_started.clone(), + b_started: b_started.clone(), + gate: gate.clone(), + }); + + let a1 = spawn_one( + &dir, + &limits, + &control, + &adapter, + request_for("imap:a@example.test"), + ); + a_started.notified().await; + + let mut a2_request = request_for("imap:a@example.test"); + a2_request.id = "2:INBOX".into(); + let a2 = spawn_one(&dir, &limits, &control, &adapter, a2_request); + let b1 = spawn_one( + &dir, + &limits, + &control, + &adapter, + request_for("imap:b@example.test"), + ); + + let b_ran = tokio::time::timeout(Duration::from_millis(500), b_started.notified()) + .await + .is_ok(); + assert!(b_ran, "account b must run while account a is still exporting"); + + gate.add_permits(3); + assert!(a1.await.unwrap().is_ok()); + assert!(a2.await.unwrap().is_ok()); + assert!(b1.await.unwrap().is_ok()); + fs::remove_dir_all(dir).unwrap(); + } + + // A swap of the destination directory after it is anchored must not + // redirect the file: the handle still names the original directory. + #[cfg(unix)] + #[test] + fn a_parent_directory_swap_does_not_redirect_the_write() { + let dir = scratch("swap"); + let target = dir.join("Downloads"); + fs::create_dir_all(&target).unwrap(); + let anchored = crate::platform::private_fs::directories(&target, &[], true) + .unwrap() + .unwrap(); + let outside = dir.join("outside"); + fs::create_dir_all(&outside).unwrap(); + let renamed = dir.join("Downloads-original"); + fs::rename(&target, &renamed).unwrap(); + std::os::unix::fs::symlink(&outside, &target).unwrap(); + let _ = write_unique_in(&target, &anchored, "note.eml", b"payload").unwrap(); + assert!(renamed.join("note.eml").exists(), "written to the anchored directory"); + assert!(!outside.join("note.eml").exists(), "not redirected through the symlink"); + assert_eq!(fs::read(renamed.join("note.eml")).unwrap(), b"payload"); + fs::remove_dir_all(dir).unwrap(); + } } From 412c88899a751f66cf0205eaf6f00d7fbb3306d8 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 17:01:11 -0500 Subject: [PATCH 13/20] E03: document cooperative cancellation and test the drop path (R3) --- planning/decisions/E00.md | 12 ++++++++++++ src/mail/export.rs | 23 ++++++++--------------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/planning/decisions/E00.md b/planning/decisions/E00.md index a4adc36..508f16e 100644 --- a/planning/decisions/E00.md +++ b/planning/decisions/E00.md @@ -155,6 +155,11 @@ with the string as the message — `src/backend/rpc.rs:137`) create; once bytes are written and fsynced the operation **returns success** with the real path. A cancel that loses the race must not report both failure and a committed file. +- **Cancellation identity (R3 close):** cancellation is cooperative and + disconnect-driven. There is no public `mail.cancelExport` method or + `requestToken` RPC parameter; the caller cancels by dropping the request, + whose guard cancels the in-flight fetch by the internally minted token before + the commit point. See O5. - Success is emitted only after a complete, committed file; the result reports the actual filename, directory, and byte count. Unsigned/raw errors never reach the UI; existing safe error strings are reused. @@ -202,6 +207,13 @@ contract is API 6 / released 5 with an empty `unreleased.methods` list. the 20 MiB attachment limit. - **O4 — concurrency: 1 per account, 2 global**, enforced with a semaphore in the new domain service. +- **O5 — cancellation identity: cooperative, disconnect/deadline-driven.** A + caller cancels by dropping the request (disconnect/exit). Dropping the export + future drops its guard, which cancels the in-flight IMAP fetch by the + internally minted token before the commit point; the 25 s deadline is the other + stop. There is deliberately no public cancel method or `requestToken` + parameter: the operation is short, has no cancel UI, and disconnect is the only + caller-visible stop. (Added 2026-09-29 to close review finding R3.) E01 and E02 are gated on this record. A change to the method name, params, result shape, or error table is a contract revision and needs a new judgment. diff --git a/src/mail/export.rs b/src/mail/export.rs index d4e458c..d9f5a0a 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -175,14 +175,6 @@ impl ExportControl { cancel: Cancellation::default(), } } - - /// The in-process signal the deadline select observes. External callers - /// cancel through the provider registry with `token`; this hook exists so a - /// test can cancel a request it did not create. - #[cfg(test)] - pub(crate) fn cancel(&self) { - self.cancel.cancel(); - } } /// Stop the provider fetch when the export is dropped before it commits. The @@ -829,12 +821,13 @@ mod tests { fs::remove_dir_all(dir).unwrap(); } + // The public cancellation path is dropping the request: a client that + // disconnects drops the export future, whose guard cancels the in-flight + // fetch before the commit point. No file is written. #[tokio::test] - async fn a_cancellation_before_commit_writes_nothing() { + async fn dropping_the_request_stops_the_fetch_before_commit() { let started = Arc::new(Notify::new()); - let control = ExportControl::new(); - let cancel = control.clone(); - let dir = scratch("cancel"); + let dir = scratch("drop"); let worker_dir = dir.clone(); let worker_started = started.clone(); let handle = tokio::spawn(async move { @@ -847,13 +840,13 @@ mod tests { &worker_dir, &Value::Null, &ExportLimits::new(), - &control, + &ExportControl::new(), ) .await }); started.notified().await; - cancel.cancel(); - assert_eq!(handle.await.unwrap(), Err("request_cancelled")); + handle.abort(); + assert!(handle.await.is_err(), "the dropped request is cancelled"); assert!(fs::read_dir(&dir).unwrap().next().is_none()); fs::remove_dir_all(dir).unwrap(); } From 02dd393dba8b0bef6312a538e7e4ee72d1aee2e8 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 18:46:42 -0500 Subject: [PATCH 14/20] Fix export cancellation, collision deadlines and size admission --- planning/evidence/E01.md | 15 ++-- planning/evidence/E02.md | 50 ++++++++++--- src/backend/protocol.rs | 88 ++++++++++++++++++++--- src/backend/stdio.rs | 35 +++++++-- src/mail/export.rs | 114 ++++++++++++++++++++++++++---- src/providers/imap/export.rs | 15 +++- src/providers/imap/mod.rs | 24 +++++-- src/providers/imap/read/search.rs | 2 +- src/providers/imap/tests.rs | 26 +++++++ 9 files changed, 316 insertions(+), 53 deletions(-) diff --git a/planning/evidence/E01.md b/planning/evidence/E01.md index 9c58654..7b2cf70 100644 --- a/planning/evidence/E01.md +++ b/planning/evidence/E01.md @@ -48,11 +48,10 @@ supplies the resolved settings this operation consumes. | `mail_export_message_missing` (missing record or `NIL`) | `mail_export_message_missing` | | `mail_export_incomplete` (duplicate literal) | `mail_export_incomplete` | | `imap_command_failed` (tagged NO/BAD) | provider failure | -| `mail_response_too_large` (literal/response over the 32 MiB `LIMIT`) | `mail_export_too_large` | +| `mail_export_too_large` (`raw_message` maps `mail_response_too_large`: announced literal over 25 MiB or response over the 32 MiB `LIMIT`) | `mail_export_too_large` | | `mail_network_failed`, `imap_invalid_response` | provider failure | -E02 owns the final mapping and the 25 MiB product limit (below the transport's -32 MiB bound). +E02 defines the 25 MiB product limit. Raw retrieval now passes that limit to `command_limited` / `response_each`, which reject an announced literal above it before resizing the record buffer or reading its payload. The existing 32 MiB aggregate response bound still applies; other provider calls retain their existing limit. E02 also checks the encoded and decoded payload sizes before storage. ## Tests (`src/providers/imap/tests.rs`, synthetic loopback server) @@ -62,10 +61,13 @@ E02 owns the final mapping and the 25 MiB product limit (below the transport's | `raw_message_ignores_unsolicited_and_other_uids` | an unrelated `UID 999` FETCH is ignored; the requested UID's bytes are returned | | `raw_message_refuses_missing_nil_and_duplicate_bodies` | `NIL` → missing; other-UID-only → missing; two literals for the requested UID → incomplete | | `raw_message_refuses_a_non_ok_completion` | tagged `NO` → `imap_command_failed` | +| `raw_message_refuses_an_over_limit_literal_before_reading_it` | the synthetic server announces `MAX_BYTES + 1` without transmitting a payload; framing returns `mail_export_too_large` rather than trying to read the literal | | `raw_message_rejects_a_bad_uid_before_connecting` | `uid:0` is refused with no connection opened | | `cancelling_a_raw_message_read_stops_the_work` | `imap.cancel` drops the in-flight fetch and returns `request_cancelled` | -## Verification run +## Original E01 verification run + +These results describe the original E01 implementation, before the later export fixes. Current follow-up verification is recorded in [E02](E02.md#p2-follow-up-verification). ``` cargo test --locked --lib providers::imap::tests # 24 passed, 0 failed @@ -79,7 +81,4 @@ cargo clippy --locked --all-targets # no findings in the new ## Not done here (E02) -Explicit account resolution (strict, no active fallback), the 25 MiB bound and -oversize refusal, Downloads/storage with exclusive non-overwriting publication, -the `mail.exportEml` RPC arm and contract cases, the provider capability, and -the QML availability projection. +Explicit account resolution (strict, no active fallback), the export service's encoded/decoded size checks, Downloads/storage with exclusive non-overwriting publication, the `mail.exportEml` RPC arm and contract cases, the provider capability, and the QML availability projection. The later P2 follow-up enforces E02's 25 MiB limit at this raw-retrieval boundary as described above; it does not add storage or public dispatch to E01. diff --git a/planning/evidence/E02.md b/planning/evidence/E02.md index 08ea32c..0ce10d4 100644 --- a/planning/evidence/E02.md +++ b/planning/evidence/E02.md @@ -28,11 +28,10 @@ top of E01's raw retrieval. No UI (E03) and no CLI command. - **Provider**: only `outlook` and `imap` are supported, checked against the `emlExport` capability and the account's refusals. Gmail/Hey/JMAP → `mail_export_unsupported` with no fetch and no file. -- **Message id**: `:` is validated before provider work. +- **Message id**: `:` is validated before provider work. Duplicate admission uses the parsed canonical form, so `01:INBOX` and `1:INBOX` share one account/message slot; the returned identity remains the captured request id. - **Bytes**: taken from E01's `imap.rawMessage` (`EXAMINE` + `BODY.PEEK[]`, one literal, unsolicited UIDs ignored) and written unchanged. -- **Limit**: 25 MiB. The base64 length is checked before decoding, then the - decoded length is checked again. +- **Limit**: 25 MiB. Raw retrieval passes `MAX_BYTES` to the IMAP framing layer, which refuses an over-limit announced literal before allocating its payload buffer or reading its octets. The existing 32 MiB aggregate response bound remains in force. The base64 length is checked before decoding, then the decoded length is checked again. - **Filename**: built from the untrusted `suggestedName` — basename only, controls/separators dropped, capped to 240 bytes, `.eml` appended once, `message.eml` fallback. @@ -42,9 +41,8 @@ top of E01's raw retrieval. No UI (E03) and no CLI command. Windows the same is done through `platform::private_fs`. - **Retained path**: the result carries the actual `path`, `filename`, and byte count after a committed write. -- **Cancellation**: observed before the file is created. Once the write commits, - success is returned even if a cancellation arrives afterwards, so a committed - file is never reported as a failure. +- **Admission/deadline**: one active export per account and at most two overall; duplicate account/message requests are refused rather than queued. Permit waits and fetch share a 25-second operation deadline, below the client's 30-second bridge deadline. The Unix writer checks cancellation and the deadline before every exclusive-create attempt, including collision retries. +- **Cancellation**: dropping the export future signals cancellation and stops its provider fetch before the commit point. An input error makes the protocol scheduler drop pending futures; clean stdin EOF or `system.quit` drains accepted work, preserving send-then-half-close-stdin. Unix stdio polls stdout for closure as well as stdin for input, so closing all pipes during FETCH is detected before a response write. Cancellation/deadline checks apply up to successful exclusive creation; the synchronous write/fsync then completes, with cleanup on failure and success returned after a complete write. ## Tests (focused) @@ -58,7 +56,9 @@ file contents; an unsupported provider is refused with the directory untouched. `src/backend/mail_action_tests.rs` and the REST of the suite stay green; the contract runner executes the new unreleased case. -## Verification +## Original E02 verification + +These results describe the original E02 implementation. The later P2 follow-up and current verification are recorded below. ``` cargo test --locked --lib # 568 passed, 0 failed @@ -80,9 +80,7 @@ Scope: the new backend export path, on Linux, exercised by the tests above. - **Filesystem** — PASS (Unix). Exclusive creation, `0600`, `O_NOFOLLOW`, no overwrite, partial cleanup on failure; symlink target untouched. Windows path uses the platform primitives but is **NOT VERIFIED** at runtime here. -- **Resource bounds** — PASS. 25 MiB checked before decoding and again after; - the transport stays capped at its existing 32 MiB response bound and the - operation does not raise any global limit. +- **Resource bounds** — PASS for the tested Linux path. The 25 MiB literal ceiling is enforced at its length announcement, before payload allocation/read, and encoded/decoded checks remain in place. The aggregate IMAP response stays capped at 32 MiB. Admission canonicalizes UID spelling, concurrency is bounded to one active export per account and two overall, and the Unix writer rechecks cancellation/deadline on every collision attempt. Protocol errors cancel pending work; clean EOF/quit drains it. See the regression coverage below for the distinction between scheduler tests and process tests. - **Secret handling** — PASS. Credentials are resolved inside the IMAP layer as for every other provider call; none is logged, returned, or placed in the result. The result carries only ids, path, filename, and byte count. @@ -94,6 +92,38 @@ Scope: the new backend export path, on Linux, exercised by the tests above. Claim: the desktop export path is PASS for the tested boundaries; cross-platform runtime is NOT VERIFIED. +## P2 follow-up verification + +Updated 2026-09-29 in `task/E03-export-ui`, on the uncommitted follow-up to base commit `412c88899a751f66cf0205eaf6f00d7fbb3306d8`. The source patch spans seven files: `src/backend/{protocol,stdio}.rs`, `src/mail/export.rs`, and `src/providers/imap/{mod,export,read/search,tests}.rs`. This records working-tree evidence, not exact-commit acceptance; record the resulting candidate SHA when the patch is committed. Runtime: Linux, Rust/Cargo 1.98.1, Qt/QtTest 6.11.2, Omarchy 4.0.4. + +| Regression | Observed boundary | +| --- | --- | +| `disconnect_cancels_accepted_work_instead_of_draining_it` | Scheduler drops accepted pending work and emits no response when the input-error cancellation flag is set. This unit test does not itself close real stdio pipes during FETCH. | +| `equivalent_ids_share_one_admission_slot` | Concurrent `01:INBOX` / `1:INBOX` requests produce one successful export, one `mail_export_in_flight` refusal, and one file. | +| `a_collision_does_not_bypass_an_expired_deadline` | An expired deadline with an existing first-choice filename returns `request_timed_out` and creates no additional file. The per-retry check is also present inside the Unix create loop. | +| `raw_message_refuses_an_over_limit_literal_before_reading_it` | A server announces a 25 MiB + 1 literal without sending its payload; retrieval returns `mail_export_too_large`. | + +The existing real-process `tests/stdio.rs` checks cover broken output with stdin left open, fragmented input followed by clean EOF, and draining accepted requests before quit. The eager stdout poll is the implementation change for the close-all-pipes mid-FETCH scenario; the four new tests above do not constitute an end-to-end reproduction of that exact scenario. + +The Windows writer delegates collision handling to `platform::private_fs::write_unique` after a single cancellation/deadline check, and Windows stdin does not use the Unix eager stdout poll. The per-retry and eager-disconnect claims here are scoped to Unix source and tested Linux behavior; Windows runtime remains NOT VERIFIED. + +Checks rerun on this working tree, all with exit status 0: + +| Command | Result | +| --- | --- | +| `cargo test --locked --lib` | 589 passed, 11 ignored, 0 failed; includes all four regressions above. | +| `cargo test --locked --features integration-test-credentials --quiet` | Library: 589 passed, 11 ignored; all other targets passed, including protocol 4, stdio 3, CLI 33. | +| `python3 tests/run_qml_native.py /usr/lib/qt6/bin/qmltestrunner -input ui/tests/qml/tst_export_routing.qml` | 8 passed, 0 failed. | +| `python3 tests/run_qml_native.py /usr/lib/qt6/bin/qmltestrunner -input ui/tests/qml/tst_message_menu_export.qml` | 5 passed, 0 failed. | +| `bash tests/test_source.sh` | Passed. | +| `python3 scripts/package-backend.py check-api` | API 6, passed. | +| `node ui/tests/test_keymap.js` | Passed. | +| `python3 tests/test_backend_api.py --binary target/debug/omamail` | Backend API 6 contract PASS: 31 methods, 179 advertised methods; binary version 0.10.7. | +| `cargo clippy --locked --all-targets` | Three known warnings at `src/providers/imap/read/search.rs:235/694` and `src/mail/tests.rs:88`; none in changed code. This is not a strict `-D warnings` pass. | +| `git diff --check` | Clean. | + +These checks use synthetic fixtures and isolated test directories. The focused QML runs do not replace the broader integration/visual acceptance matrix in `planning/REVIEW-GATE.md`. + ## Boundaries - No live mailbox, credential, or daily runtime was touched. diff --git a/src/backend/protocol.rs b/src/backend/protocol.rs index 9067e6f..5efa6c1 100644 --- a/src/backend/protocol.rs +++ b/src/backend/protocol.rs @@ -1,6 +1,7 @@ use futures_util::{StreamExt, stream::FuturesUnordered}; use std::io::{self, BufRead, Write}; -use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; +use std::sync::Arc; use std::time::Duration; use tokio::sync::mpsc; @@ -26,6 +27,7 @@ pub fn serve(input: impl BufRead, mut output: impl Write + Send) -> io::Result<( let session = super::Session::default(); let (sender, receiver) = mpsc::channel::(16); let (responses, mut completed) = mpsc::channel::(2); + let cancel_pending = Arc::new(AtomicBool::new(false)); let end = std::thread::scope(|scope| -> io::Result { let writer = scope.spawn(|| -> io::Result<()> { while let Some(value) = completed.blocking_recv() { @@ -33,8 +35,14 @@ pub fn serve(input: impl BufRead, mut output: impl Write + Send) -> io::Result<( } Ok(()) }); - let dispatcher = - scope.spawn(|| runtime.block_on(process_frames(receiver, responses, &session))); + let dispatcher = scope.spawn(|| { + runtime.block_on(process_frames( + receiver, + responses, + &session, + cancel_pending.clone(), + )) + }); let result = read_frames(input, |bytes| { sender .blocking_send(Frame { @@ -43,6 +51,12 @@ pub fn serve(input: impl BufRead, mut output: impl Write + Send) -> io::Result<( }) .map_err(|_| io::Error::other("dispatcher stopped")) }); + // An input error means the peer can no longer receive responses (the + // stdio layer reports a closed output pipe as a BrokenPipe read error), + // so accepted work is cancelled instead of drained: a drained export + // could commit a file the client can never read. A clean EOF or a quit + // drains. + cancel_pending.store(result.is_err(), Ordering::SeqCst); drop(sender); let dispatched = dispatcher .join() @@ -74,13 +88,14 @@ async fn process_frames( receiver: mpsc::Receiver, responses: mpsc::Sender, session: &super::Session, + cancel_pending: Arc, ) -> io::Result<()> { // Subscribe before accepting frames: the initial watch check may finish // before its RPC response, but its notification must still reach the writer. let mut notifications = session.mail.subscribe(); let mut outbox_notifications = session.outbox.subscribe(); let mut gmail_notifications = session.gmail.subscribe(); - let scheduler = schedule(receiver, responses.clone(), |frame| async move { + let scheduler = schedule(receiver, responses.clone(), cancel_pending, |frame| async move { super::rpc::handle(&frame.bytes, session, frame.deadline) .await .0 @@ -123,6 +138,7 @@ async fn process_frames( async fn schedule( mut receiver: mpsc::Receiver, responses: mpsc::Sender, + cancel_pending: Arc, handle: F, ) -> io::Result<()> where @@ -136,7 +152,16 @@ where frame = receiver.recv(), if !closed && pending.len() < MAX_IN_FLIGHT => { match frame { Some(frame) => pending.push(handle(frame)), - None => closed = true, + None => { + // The channel closed. A quit drains accepted work; a + // disconnect cancels it so a half-finished request + // (e.g. an export) does not commit on its own. + if cancel_pending.load(Ordering::SeqCst) { + pending.clear(); + return Ok(()); + } + closed = true; + } } } response = pending.next(), if !pending.is_empty() => { @@ -395,7 +420,7 @@ mod tests { #[cfg(test)] mod scheduling_tests { use super::*; - use std::sync::{Arc, atomic::AtomicUsize}; + use std::sync::{Arc, atomic::{AtomicBool, AtomicUsize}}; use tokio::sync::Semaphore; #[tokio::test] @@ -418,7 +443,8 @@ mod scheduling_tests { session.mail.watch_for_test("one").await; let (sender, receiver) = mpsc::channel(2); let (responses, mut output) = mpsc::channel(2); - let dispatcher = process_frames(receiver, responses, &session); + let dispatcher = + process_frames(receiver, responses, &session, Arc::new(AtomicBool::new(false))); let client = async { sender .send(Frame { @@ -473,7 +499,7 @@ mod scheduling_tests { let task = tokio::spawn({ let gate = gate.clone(); let started = started.clone(); - schedule(receiver, responses, move |frame| { + schedule(receiver, responses, Arc::new(AtomicBool::new(false)), move |frame| { let gate = gate.clone(); let started = started.clone(); async move { @@ -518,7 +544,7 @@ mod scheduling_tests { drop(sender); let task = tokio::spawn({ let gate = gate.clone(); - schedule(receiver, responses, move |frame| { + schedule(receiver, responses, Arc::new(AtomicBool::new(false)), move |frame| { let gate = gate.clone(); let entered = entered.clone(); async move { @@ -547,4 +573,48 @@ mod scheduling_tests { } assert_eq!(count, 33); } + + #[tokio::test] + async fn disconnect_cancels_accepted_work_instead_of_draining_it() { + let (sender, receiver) = mpsc::channel(16); + let (responses, mut output) = mpsc::channel(16); + let dropped = Arc::new(AtomicBool::new(false)); + sender + .send(Frame { + bytes: vec![1], + deadline: tokio::time::Instant::now() + REQUEST_TIMEOUT, + }) + .await + .unwrap(); + let cancel_pending = Arc::new(AtomicBool::new(true)); + drop(sender); + let task = tokio::spawn({ + let dropped = dropped.clone(); + schedule(receiver, responses, cancel_pending, move |_frame| { + struct Marker(Arc); + impl Drop for Marker { + fn drop(&mut self) { + self.0.store(true, Ordering::SeqCst); + } + } + // Created in the closure and moved into the future, so it is + // dropped whenever the future is dropped -- even before first + // poll. + let marker = Marker(dropped.clone()); + async move { + let _marker = marker; + std::future::pending::>().await + } + }) + }); + task.await.unwrap().unwrap(); + assert!( + dropped.load(Ordering::SeqCst), + "accepted work must be dropped, not drained, on disconnect" + ); + assert!( + output.recv().await.is_none(), + "no response may be written after a disconnect" + ); + } } diff --git a/src/backend/stdio.rs b/src/backend/stdio.rs index 677b26f..5483f2f 100644 --- a/src/backend/stdio.rs +++ b/src/backend/stdio.rs @@ -65,14 +65,31 @@ impl Read for Input { if self.failed.load(Ordering::Acquire) { return Err(io::Error::new(io::ErrorKind::BrokenPipe, "output closed")); } - let mut descriptor = libc::pollfd { - fd: libc::STDIN_FILENO, - events: libc::POLLIN, - revents: 0, - }; + // Poll stdin for input and stdout for closure. A peer that closes + // its read end of the output pipe is detected here eagerly, not + // only on the next write, so a disconnect mid-request stops the + // request instead of letting it run to completion. + let mut descriptors = [ + libc::pollfd { + fd: libc::STDIN_FILENO, + events: libc::POLLIN, + revents: 0, + }, + libc::pollfd { + fd: libc::STDOUT_FILENO, + events: 0, + revents: 0, + }, + ]; // The backend is the only stdin reader. Read the descriptor directly: // a buffered Stdin reader could contain bytes invisible to poll. - let ready = unsafe { libc::poll(&mut descriptor, 1, 100) }; + let ready = unsafe { + libc::poll( + descriptors.as_mut_ptr(), + descriptors.len() as libc::nfds_t, + 100, + ) + }; if ready < 0 { let error = io::Error::last_os_error(); if error.kind() == io::ErrorKind::Interrupted { @@ -80,6 +97,12 @@ impl Read for Input { } return Err(error); } + // Any event on the stdout descriptor is an error (POLLERR, POLLHUP, + // or POLLNVAL): the peer can no longer receive a response. + if descriptors[1].revents != 0 { + self.failed.store(true, Ordering::Release); + return Err(io::Error::new(io::ErrorKind::BrokenPipe, "output closed")); + } if ready == 0 { continue; } diff --git a/src/mail/export.rs b/src/mail/export.rs index d9f5a0a..42dcddc 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -251,13 +251,16 @@ pub(crate) async fn export_with( if !crate::providers::can(request.account.provider.id(), "emlExport", refusals) { return Err("mail_export_unsupported"); } - // Reject a malformed `:` before any credential or network work. - crate::providers::imap::message_id(&request.id)?; + // Reject a malformed `:` before any credential or network + // work, and derive the canonical identity for admission. Leading zeros on + // the UID (e.g. "01:INBOX") must not make the same message look distinct. + let (uid, folder) = crate::providers::imap::message_id(&request.id)?; + let canonical_id = format!("{uid}:{folder}"); // A repeated (account, message) request is refused, not queued behind the // one already saving it. This happens before the cancellation guard exists, // so a refusal never cancels an in-flight export that shares a control. - let _admission = limits.admit(&request.account.id, &request.id)?; + let _admission = limits.admit(&request.account.id, &canonical_id)?; let mut guard = ControlGuard::new(&request.account.id, control); let result = run_export(&request, adapter, downloads, limits, control).await; @@ -322,13 +325,7 @@ async fn run_export( let dir = crate::platform::private_fs::directories(&downloads, &[], true) .map_err(|_| "mail_export_write_failed")? .ok_or("mail_export_write_failed")?; - if cancel.is_cancelled() { - return Err("request_cancelled"); - } - if std::time::Instant::now() >= deadline_std { - return Err("request_timed_out"); - } - write_unique_in(&downloads, &dir, &filename, &bytes) + write_unique_in(&downloads, &dir, &filename, &bytes, deadline_std, &cancel) }) .await .map_err(|_| "request_cancelled")??; @@ -386,6 +383,8 @@ fn write_unique_in( dir: &std::fs::File, filename: &str, bytes: &[u8], + deadline: std::time::Instant, + cancel: &Cancellation, ) -> Result { use std::{ ffi::CString, @@ -401,6 +400,15 @@ fn write_unique_in( .unwrap_or_default(); let dir_fd = dir.as_raw_fd(); for n in 1..1000 { + // Recheck the deadline and cancellation before each create attempt: a + // collision retry must not outlive the operation deadline or commit + // after a disconnect. + if cancel.is_cancelled() { + return Err("request_cancelled"); + } + if std::time::Instant::now() >= deadline { + return Err("request_timed_out"); + } let candidate = if n == 1 { filename.to_owned() } else { @@ -443,19 +451,36 @@ fn write_unique_in( dir: &std::fs::File, filename: &str, bytes: &[u8], + deadline: std::time::Instant, + cancel: &Cancellation, ) -> Result { + if cancel.is_cancelled() { + return Err("request_cancelled"); + } + if std::time::Instant::now() >= deadline { + return Err("request_timed_out"); + } crate::platform::private_fs::write_unique(dir, filename, bytes) .map_err(|_| "mail_export_write_failed") } // Anchor the directory then create the file relative to that handle. The // export path calls `write_unique_in` directly so it can observe the deadline -// between the anchor and the exclusive create; tests use this wrapper. +// between the anchor and the exclusive create; tests use this wrapper with a +// far-future deadline and no cancellation. +#[cfg(test)] fn write_unique(directory: &Path, filename: &str, bytes: &[u8]) -> Result { let dir = crate::platform::private_fs::directories(directory, &[], true) .map_err(|_| "mail_export_write_failed")? .ok_or("mail_export_write_failed")?; - write_unique_in(directory, &dir, filename, bytes) + write_unique_in( + directory, + &dir, + filename, + bytes, + std::time::Instant::now() + Duration::from_secs(3600), + &Cancellation::default(), + ) } #[cfg(test)] @@ -747,6 +772,34 @@ mod tests { fs::remove_dir_all(dir).unwrap(); } + // Equivalent ids name the same message, so a second request with a leading + // zero on the UID is still refused as an in-flight duplicate. + #[tokio::test] + async fn equivalent_ids_share_one_admission_slot() { + let dir = scratch("equivalent"); + let limits = ExportLimits::new(); + let control = ExportControl::new(); + let adapter = Counting::new(); + let mut first = request(); + first.id = "01:INBOX".into(); + let mut second = request(); + second.id = "1:INBOX".into(); + let results = futures_util::future::join_all([ + export_with(first, &adapter, &dir, &Value::Null, &limits, &control), + export_with(second, &adapter, &dir, &Value::Null, &limits, &control), + ]) + .await; + let ok = results.iter().filter(|r| r.is_ok()).count(); + let refused = results + .iter() + .filter(|r| r.as_ref().err() == Some(&"mail_export_in_flight")) + .count(); + assert_eq!(ok, 1, "exactly one of the equivalent ids commits"); + assert_eq!(refused, 1, "the other is refused as in flight"); + assert_eq!(fs::read_dir(&dir).unwrap().count(), 1, "one output file"); + fs::remove_dir_all(dir).unwrap(); + } + // Different messages on one account still run one at a time. #[tokio::test] async fn one_account_exports_one_message_at_a_time() { @@ -940,10 +993,45 @@ mod tests { let renamed = dir.join("Downloads-original"); fs::rename(&target, &renamed).unwrap(); std::os::unix::fs::symlink(&outside, &target).unwrap(); - let _ = write_unique_in(&target, &anchored, "note.eml", b"payload").unwrap(); + let _ = write_unique_in( + &target, + &anchored, + "note.eml", + b"payload", + std::time::Instant::now() + Duration::from_secs(3600), + &Cancellation::default(), + ) + .unwrap(); assert!(renamed.join("note.eml").exists(), "written to the anchored directory"); assert!(!outside.join("note.eml").exists(), "not redirected through the symlink"); assert_eq!(fs::read(renamed.join("note.eml")).unwrap(), b"payload"); fs::remove_dir_all(dir).unwrap(); } + + // A collision retry must not outlive the deadline: it is rechecked before + // each exclusive create, so an expired deadline refuses even when the first + // candidate name already exists. + #[test] + fn a_collision_does_not_bypass_an_expired_deadline() { + let dir = scratch("deadline-collision"); + fs::write(dir.join("note.eml"), b"existing").unwrap(); + let anchored = crate::platform::private_fs::directories(&dir, &[], true) + .unwrap() + .unwrap(); + let result = write_unique_in( + &dir, + &anchored, + "note.eml", + b"payload", + std::time::Instant::now() - Duration::from_secs(1), + &Cancellation::default(), + ); + assert_eq!(result, Err("request_timed_out")); + assert_eq!( + fs::read_dir(&dir).unwrap().count(), + 1, + "no extra file is created" + ); + fs::remove_dir_all(dir).unwrap(); + } } diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index f326f88..7176455 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -38,12 +38,23 @@ pub(super) async fn raw_message(p: &Value, uid: u32, folder: &str) -> Result Err("mail_export_too_large"), + other => other, + } } async fn fetch_literal(w: &mut Wire, uid: u32, folder: &str) -> Result> { command(w, &format!("EXAMINE {}", quote(folder)?)).await?; - let data = command(w, &format!("UID FETCH {uid} (UID BODY.PEEK[])")).await?; + // Bound the message literal by the export's 25 MiB product limit, so an + // over-limit message is refused when its length is announced rather than + // after the whole literal has been read into memory. + let data = command_limited( + w, + &format!("UID FETCH {uid} (UID BODY.PEEK[])"), + crate::mail::export::MAX_BYTES, + ) + .await?; single_literal(&data, uid) } diff --git a/src/providers/imap/mod.rs b/src/providers/imap/mod.rs index 0f6aca8..f8c97bc 100644 --- a/src/providers/imap/mod.rs +++ b/src/providers/imap/mod.rs @@ -115,8 +115,19 @@ async fn line(w: &mut Wire) -> Result> { } } async fn response(w: &mut Wire, tag: &str, continuation: bool) -> Result> { + response_limited(w, tag, continuation, LIMIT).await +} +/// `response` with a smaller per-literal ceiling. The export path passes its +/// 25 MiB product limit so an over-limit message is refused when the server +/// announces the literal length, before the octets are read. +async fn response_limited( + w: &mut Wire, + tag: &str, + continuation: bool, + literal_cap: usize, +) -> Result> { let mut out = Vec::new(); - response_each(w, tag, continuation, |record| { + response_each(w, tag, continuation, literal_cap, |record| { out.extend_from_slice(record); Ok(()) }) @@ -125,11 +136,13 @@ async fn response(w: &mut Wire, tag: &str, continuation: bool) -> Result } /// Visit complete IMAP response records, keeping literals attached to their /// protocol record. UID inventories can retain only numbers instead of a full -/// response and a second, much larger parsed syntax tree. +/// response and a second, much larger parsed syntax tree. `literal_cap` bounds +/// any single announced literal on top of the whole-response `LIMIT`. async fn response_each( w: &mut Wire, tag: &str, continuation: bool, + literal_cap: usize, mut visit: impl FnMut(&[u8]) -> Result<()>, ) -> Result<()> { let mut total = 0; @@ -164,7 +177,7 @@ async fn response_each( let mut record = l; while let Some(n) = literal { let n = n.map_err(|_| "imap_invalid_response")?; - if n > LIMIT - total { + if n > LIMIT - total || n > literal_cap { return Err("mail_response_too_large"); } let start = record.len(); @@ -192,8 +205,11 @@ fn literal_length(line: &str) -> Option()) } async fn command(w: &mut Wire, cmd: &str) -> Result> { + command_limited(w, cmd, LIMIT).await +} +async fn command_limited(w: &mut Wire, cmd: &str, literal_cap: usize) -> Result> { write(w, format!("O1 {cmd}\r\n").as_bytes()).await?; - response(w, "O1", false).await + response_limited(w, "O1", false, literal_cap).await } async fn tls(w: Wire, host: &str) -> Result { if !w.buffer().is_empty() { diff --git a/src/providers/imap/read/search.rs b/src/providers/imap/read/search.rs index ab16eb8..bc52440 100644 --- a/src/providers/imap/read/search.rs +++ b/src/providers/imap/read/search.rs @@ -361,7 +361,7 @@ async fn inventory(wire: &mut Wire, ceiling: u32) -> Result> { ) .await?; let mut uids = BTreeSet::new(); - response_each(wire, "O1", false, |record| { + response_each(wire, "O1", false, LIMIT, |record| { uids.extend( fetched_dates(record)? .into_keys() diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index 178e11f..c480172 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -655,6 +655,32 @@ async fn raw_message_refuses_a_non_ok_completion() { server_task.await.unwrap(); } +#[tokio::test] +async fn raw_message_refuses_an_over_limit_literal_before_reading_it() { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut w: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut w).await; + assert!(line(&mut w).await.unwrap().starts_with(b"O1 UID FETCH 1 ")); + // Announce a literal one byte over the export limit and send nothing + // further: the export must refuse at framing, without consuming the + // literal (which is never transmitted). + let announced = crate::mail::export::MAX_BYTES + 1; + write( + &mut w, + format!("* 1 FETCH (UID 1 BODY[] {{{announced}}}\r\n").as_bytes(), + ) + .await + .unwrap(); + }); + assert_eq!( + call("imap.rawMessage", &export_params(port, 1)).await, + Err("mail_export_too_large") + ); + server_task.await.unwrap(); +} + #[tokio::test] async fn raw_message_rejects_a_bad_uid_before_connecting() { let (listener, port) = server().await; From f47e2def6c0df5c40ef7a6a6e579be4a1ec550ef Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 18:47:32 -0500 Subject: [PATCH 15/20] docs: Record the tested export fix candidate --- planning/evidence/E02.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/evidence/E02.md b/planning/evidence/E02.md index 0ce10d4..aa6e495 100644 --- a/planning/evidence/E02.md +++ b/planning/evidence/E02.md @@ -94,7 +94,7 @@ runtime is NOT VERIFIED. ## P2 follow-up verification -Updated 2026-09-29 in `task/E03-export-ui`, on the uncommitted follow-up to base commit `412c88899a751f66cf0205eaf6f00d7fbb3306d8`. The source patch spans seven files: `src/backend/{protocol,stdio}.rs`, `src/mail/export.rs`, and `src/providers/imap/{mod,export,read/search,tests}.rs`. This records working-tree evidence, not exact-commit acceptance; record the resulting candidate SHA when the patch is committed. Runtime: Linux, Rust/Cargo 1.98.1, Qt/QtTest 6.11.2, Omarchy 4.0.4. +Updated 2026-09-29 in `task/E03-export-ui`. The fixes and evidence were committed as candidate `02dd393`, based on `412c88899a751f66cf0205eaf6f00d7fbb3306d8`. The source patch spans seven files: `src/backend/{protocol,stdio}.rs`, `src/mail/export.rs`, and `src/providers/imap/{mod,export,read/search,tests}.rs`. Checks below ran on the working tree immediately before that commit; its source is unchanged. This evidence does not record supervisor acceptance. Runtime: Linux, Rust/Cargo 1.98.1, Qt/QtTest 6.11.2, Omarchy 4.0.4. | Regression | Observed boundary | | --- | --- | From 066c7441271021b632a19ff75a5f3274355af3ad Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 21:37:21 -0500 Subject: [PATCH 16/20] fix: Cancel disconnected requests under queue pressure --- src/backend/protocol.rs | 299 +++++++++++++++++++++++++++-------- src/backend/stdio.rs | 48 ++++-- src/mail/export.rs | 17 +- src/providers/imap/export.rs | 6 +- src/providers/imap/tests.rs | 68 +++++++- tests/stdio.rs | 65 ++++++++ 6 files changed, 426 insertions(+), 77 deletions(-) diff --git a/src/backend/protocol.rs b/src/backend/protocol.rs index 5efa6c1..13b6ddf 100644 --- a/src/backend/protocol.rs +++ b/src/backend/protocol.rs @@ -1,9 +1,9 @@ use futures_util::{StreamExt, stream::FuturesUnordered}; use std::io::{self, BufRead, Write}; -use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; use std::sync::Arc; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; use std::time::Duration; -use tokio::sync::mpsc; +use tokio::sync::{Notify, mpsc}; use serde_json::Value; @@ -15,6 +15,32 @@ static NEXT_TRANSFER: AtomicU64 = AtomicU64::new(1); const MAX_IN_FLIGHT: usize = 32; const REQUEST_TIMEOUT: Duration = Duration::from_secs(25); +/// Wakes the dispatcher independently of request capacity or output pressure. +#[derive(Default)] +pub(super) struct Cancellation { + flag: AtomicBool, + notify: Notify, +} + +impl Cancellation { + pub(super) fn cancel(&self) { + self.flag.store(true, Ordering::SeqCst); + self.notify.notify_waiters(); + } + + async fn cancelled(&self) { + loop { + let notified = self.notify.notified(); + tokio::pin!(notified); + notified.as_mut().enable(); + if self.flag.load(Ordering::SeqCst) { + return; + } + notified.await; + } + } +} + struct Frame { bytes: Vec, deadline: tokio::time::Instant, @@ -23,11 +49,18 @@ struct Frame { /// Pipes retain dedicated blocking readers/writers; networking runs as bounded /// async futures, so a slow request does not occupy a network worker thread. pub fn serve(input: impl BufRead, mut output: impl Write + Send) -> io::Result<()> { + serve_with_cancel(input, &mut output, Arc::new(Cancellation::default())) +} + +pub(super) fn serve_with_cancel( + input: impl BufRead, + mut output: impl Write + Send, + cancel_pending: Arc, +) -> io::Result<()> { let runtime = super::runtime()?; let session = super::Session::default(); let (sender, receiver) = mpsc::channel::(16); let (responses, mut completed) = mpsc::channel::(2); - let cancel_pending = Arc::new(AtomicBool::new(false)); let end = std::thread::scope(|scope| -> io::Result { let writer = scope.spawn(|| -> io::Result<()> { while let Some(value) = completed.blocking_recv() { @@ -56,7 +89,9 @@ pub fn serve(input: impl BufRead, mut output: impl Write + Send) -> io::Result<( // so accepted work is cancelled instead of drained: a drained export // could commit a file the client can never read. A clean EOF or a quit // drains. - cancel_pending.store(result.is_err(), Ordering::SeqCst); + if result.is_err() { + cancel_pending.cancel(); + } drop(sender); let dispatched = dispatcher .join() @@ -88,43 +123,55 @@ async fn process_frames( receiver: mpsc::Receiver, responses: mpsc::Sender, session: &super::Session, - cancel_pending: Arc, + cancel_pending: Arc, ) -> io::Result<()> { // Subscribe before accepting frames: the initial watch check may finish // before its RPC response, but its notification must still reach the writer. let mut notifications = session.mail.subscribe(); let mut outbox_notifications = session.outbox.subscribe(); let mut gmail_notifications = session.gmail.subscribe(); - let scheduler = schedule(receiver, responses.clone(), cancel_pending, |frame| async move { - super::rpc::handle(&frame.bytes, session, frame.deadline) - .await - .0 - }); - tokio::pin!(scheduler); - let result = loop { - tokio::select! { - result = &mut scheduler => break result, - event = outbox_notifications.recv() => { - if let Ok(event) = event - && responses.send(event).await.is_err() { - break Err(io::Error::other("output closed")); + let dispatch = async { + let scheduler = schedule( + receiver, + responses.clone(), + cancel_pending.clone(), + |frame| async move { + super::rpc::handle(&frame.bytes, session, frame.deadline) + .await + .0 + }, + ); + tokio::pin!(scheduler); + loop { + tokio::select! { + result = &mut scheduler => break result, + event = outbox_notifications.recv() => { + if let Ok(event) = event + && responses.send(event).await.is_err() { + break Err(io::Error::other("output closed")); + } } - } - event = gmail_notifications.recv() => { - if let Ok(event) = event - && responses.send(event).await.is_err() { - break Err(io::Error::other("output closed")); + event = gmail_notifications.recv() => { + if let Ok(event) = event + && responses.send(event).await.is_err() { + break Err(io::Error::other("output closed")); + } } - } - event = notifications.recv() => { - if let Ok(event) = event - && session.mail.is_current(&event) - && responses.send(event.value).await.is_err() { - break Err(io::Error::other("output closed")); + event = notifications.recv() => { + if let Ok(event) = event + && session.mail.is_current(&event) + && responses.send(event.value).await.is_err() { + break Err(io::Error::other("output closed")); + } } } } }; + let result = tokio::select! { + biased; + _ = cancel_pending.cancelled() => Ok(()), + result = dispatch => result, + }; // No watch can write after the accepted requests drain or after quit. session.mail.shutdown().await; session.gmail.shutdown(); @@ -136,9 +183,25 @@ async fn process_frames( } async fn schedule( + receiver: mpsc::Receiver, + responses: mpsc::Sender, + cancel_pending: Arc, + handle: F, +) -> io::Result<()> +where + F: Fn(Frame) -> Fut, + Fut: std::future::Future>, +{ + tokio::select! { + biased; + _ = cancel_pending.cancelled() => Ok(()), + result = drain(receiver, responses, handle) => result, + } +} + +async fn drain( mut receiver: mpsc::Receiver, responses: mpsc::Sender, - cancel_pending: Arc, handle: F, ) -> io::Result<()> where @@ -152,16 +215,7 @@ where frame = receiver.recv(), if !closed && pending.len() < MAX_IN_FLIGHT => { match frame { Some(frame) => pending.push(handle(frame)), - None => { - // The channel closed. A quit drains accepted work; a - // disconnect cancels it so a half-finished request - // (e.g. an export) does not commit on its own. - if cancel_pending.load(Ordering::SeqCst) { - pending.clear(); - return Ok(()); - } - closed = true; - } + None => closed = true, } } response = pending.next(), if !pending.is_empty() => { @@ -420,7 +474,10 @@ mod tests { #[cfg(test)] mod scheduling_tests { use super::*; - use std::sync::{Arc, atomic::{AtomicBool, AtomicUsize}}; + use std::sync::{ + Arc, + atomic::{AtomicBool, AtomicUsize}, + }; use tokio::sync::Semaphore; #[tokio::test] @@ -443,8 +500,12 @@ mod scheduling_tests { session.mail.watch_for_test("one").await; let (sender, receiver) = mpsc::channel(2); let (responses, mut output) = mpsc::channel(2); - let dispatcher = - process_frames(receiver, responses, &session, Arc::new(AtomicBool::new(false))); + let dispatcher = process_frames( + receiver, + responses, + &session, + Arc::new(Cancellation::default()), + ); let client = async { sender .send(Frame { @@ -499,17 +560,22 @@ mod scheduling_tests { let task = tokio::spawn({ let gate = gate.clone(); let started = started.clone(); - schedule(receiver, responses, Arc::new(AtomicBool::new(false)), move |frame| { - let gate = gate.clone(); - let started = started.clone(); - async move { - started.fetch_add(1, Ordering::SeqCst); - if frame.bytes[0] != 7 { - gate.acquire().await.unwrap().forget(); + schedule( + receiver, + responses, + Arc::new(Cancellation::default()), + move |frame| { + let gate = gate.clone(); + let started = started.clone(); + async move { + started.fetch_add(1, Ordering::SeqCst); + if frame.bytes[0] != 7 { + gate.acquire().await.unwrap().forget(); + } + Some(Value::from(frame.bytes[0])) } - Some(Value::from(frame.bytes[0])) - } - }) + }, + ) }); let first = tokio::time::timeout(Duration::from_secs(2), output.recv()) .await @@ -544,15 +610,20 @@ mod scheduling_tests { drop(sender); let task = tokio::spawn({ let gate = gate.clone(); - schedule(receiver, responses, Arc::new(AtomicBool::new(false)), move |frame| { - let gate = gate.clone(); - let entered = entered.clone(); - async move { - entered.send(()).unwrap(); - gate.acquire().await.unwrap().forget(); - Some(Value::from(frame.bytes[0])) - } - }) + schedule( + receiver, + responses, + Arc::new(Cancellation::default()), + move |frame| { + let gate = gate.clone(); + let entered = entered.clone(); + async move { + entered.send(()).unwrap(); + gate.acquire().await.unwrap().forget(); + Some(Value::from(frame.bytes[0])) + } + }, + ) }); for _ in 0..MAX_IN_FLIGHT { tokio::time::timeout(Duration::from_secs(2), entries.recv()) @@ -574,6 +645,99 @@ mod scheduling_tests { assert_eq!(count, 33); } + #[tokio::test] + async fn disconnect_cancels_a_full_request_window() { + let (sender, receiver) = mpsc::channel(MAX_IN_FLIGHT); + let (responses, mut output) = mpsc::channel(MAX_IN_FLIGHT); + let cancel_pending = Arc::new(Cancellation::default()); + let (started, mut entries) = mpsc::unbounded_channel(); + let dropped = Arc::new(AtomicUsize::new(0)); + let mut task = tokio::spawn({ + let dropped = dropped.clone(); + schedule(receiver, responses, cancel_pending.clone(), move |_frame| { + struct Marker(Arc); + impl Drop for Marker { + fn drop(&mut self) { + self.0.fetch_add(1, Ordering::SeqCst); + } + } + let marker = Marker(dropped.clone()); + let started = started.clone(); + async move { + let _marker = marker; + started.send(()).unwrap(); + std::future::pending::>().await + } + }) + }); + for _ in 0..MAX_IN_FLIGHT { + sender + .send(Frame { + bytes: vec![1], + deadline: tokio::time::Instant::now() + REQUEST_TIMEOUT, + }) + .await + .unwrap(); + } + for _ in 0..MAX_IN_FLIGHT { + entries.recv().await.unwrap(); + } + cancel_pending.cancel(); + drop(sender); + let result = tokio::time::timeout(Duration::from_millis(200), &mut task).await; + if result.is_err() { + task.abort(); + } + result + .expect("disconnect must cancel even with every request slot occupied") + .unwrap() + .unwrap(); + assert_eq!(dropped.load(Ordering::SeqCst), MAX_IN_FLIGHT); + assert!(output.recv().await.is_none()); + } + + #[tokio::test] + async fn disconnect_cancels_while_response_queue_is_full() { + let (sender, receiver) = mpsc::channel(2); + let (responses, mut output) = mpsc::channel(1); + let cancel_pending = Arc::new(Cancellation::default()); + let (finished, mut entries) = mpsc::unbounded_channel(); + let mut task = tokio::spawn(schedule( + receiver, + responses, + cancel_pending.clone(), + move |_frame| { + let finished = finished.clone(); + async move { + finished.send(()).unwrap(); + Some(Value::Null) + } + }, + )); + for _ in 0..2 { + sender + .send(Frame { + bytes: vec![1], + deadline: tokio::time::Instant::now() + REQUEST_TIMEOUT, + }) + .await + .unwrap(); + entries.recv().await.unwrap(); + } + cancel_pending.cancel(); + drop(sender); + let result = tokio::time::timeout(Duration::from_millis(200), &mut task).await; + if result.is_err() { + task.abort(); + } + result + .expect("disconnect must interrupt blocked response delivery") + .unwrap() + .unwrap(); + assert_eq!(output.recv().await, Some(Value::Null)); + assert!(output.recv().await.is_none()); + } + #[tokio::test] async fn disconnect_cancels_accepted_work_instead_of_draining_it() { let (sender, receiver) = mpsc::channel(16); @@ -586,11 +750,11 @@ mod scheduling_tests { }) .await .unwrap(); - let cancel_pending = Arc::new(AtomicBool::new(true)); - drop(sender); + let cancel_pending = Arc::new(Cancellation::default()); + let (started, mut entries) = mpsc::unbounded_channel(); let task = tokio::spawn({ let dropped = dropped.clone(); - schedule(receiver, responses, cancel_pending, move |_frame| { + schedule(receiver, responses, cancel_pending.clone(), move |_frame| { struct Marker(Arc); impl Drop for Marker { fn drop(&mut self) { @@ -601,12 +765,17 @@ mod scheduling_tests { // dropped whenever the future is dropped -- even before first // poll. let marker = Marker(dropped.clone()); + let started = started.clone(); async move { let _marker = marker; + started.send(()).unwrap(); std::future::pending::>().await } }) }); + entries.recv().await.unwrap(); + cancel_pending.cancel(); + drop(sender); task.await.unwrap().unwrap(); assert!( dropped.load(Ordering::SeqCst), diff --git a/src/backend/stdio.rs b/src/backend/stdio.rs index 5483f2f..b5e4fde 100644 --- a/src/backend/stdio.rs +++ b/src/backend/stdio.rs @@ -9,15 +9,45 @@ pub fn serve() -> io::Result<()> { #[cfg(target_os = "linux")] bind_to_parent()?; let failed = Arc::new(AtomicBool::new(false)); - super::protocol::serve( - BufReader::new(Input { - failed: failed.clone(), - }), - Output { - inner: io::stdout(), - failed, - }, - ) + let cancellation = Arc::new(super::protocol::Cancellation::default()); + let finished = AtomicBool::new(false); + std::thread::scope(|_scope| { + #[cfg(unix)] + _scope.spawn(|| { + // The input thread can be blocked submitting to a full queue. + // Observe output closure independently so cancellation drops that + // queue and wakes its sender as well as all running requests. + while !finished.load(Ordering::Acquire) { + let mut output = libc::pollfd { + fd: libc::STDOUT_FILENO, + events: 0, + revents: 0, + }; + let ready = unsafe { libc::poll(&mut output, 1, 100) }; + if output.revents != 0 + || failed.load(Ordering::Acquire) + || (ready < 0 + && io::Error::last_os_error().kind() != io::ErrorKind::Interrupted) + { + failed.store(true, Ordering::Release); + cancellation.cancel(); + break; + } + } + }); + let result = super::protocol::serve_with_cancel( + BufReader::new(Input { + failed: failed.clone(), + }), + Output { + inner: io::stdout(), + failed: failed.clone(), + }, + cancellation.clone(), + ); + finished.store(true, Ordering::Release); + result + }) } #[cfg(target_os = "linux")] diff --git a/src/mail/export.rs b/src/mail/export.rs index 42dcddc..c228aeb 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -254,7 +254,8 @@ pub(crate) async fn export_with( // Reject a malformed `:` before any credential or network // work, and derive the canonical identity for admission. Leading zeros on // the UID (e.g. "01:INBOX") must not make the same message look distinct. - let (uid, folder) = crate::providers::imap::message_id(&request.id)?; + let (uid, folder) = crate::providers::imap::message_id(&request.id) + .map_err(|_| "mail_export_message_invalid")?; let canonical_id = format!("{uid}:{folder}"); // A repeated (account, message) request is refused, not queued behind the @@ -720,6 +721,20 @@ mod tests { fs::remove_dir_all(dir).unwrap(); } + #[tokio::test] + async fn malformed_message_ids_use_the_export_refusal() { + let dir = scratch("invalid-id"); + for id in ["", "INBOX", "0:INBOX", "4294967296:INBOX", "1:", "1:IN\nBOX"] { + let mut request = request(); + request.id = id.into(); + assert_eq!(export_with(request, &Fake { payload: json!({}) }, &dir, + &Value::Null, &ExportLimits::new(), &ExportControl::new()).await, + Err("mail_export_message_invalid")); + } + assert!(fs::read_dir(&dir).unwrap().next().is_none()); + fs::remove_dir_all(dir).unwrap(); + } + #[tokio::test] async fn an_unsupported_provider_is_refused_before_any_fetch() { let dir = scratch("provider"); diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index 7176455..ae4a861 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -37,7 +37,11 @@ pub(super) async fn call(p: &Value) -> Result { pub(super) async fn raw_message(p: &Value, uid: u32, folder: &str) -> Result> { let (mut w, key) = acquire(p).await?; let result = fetch_literal(&mut w, uid, folder).await; - release(w, key).await; + // A framing refusal can leave unread literal bytes on the socket. Only + // a successful fetch is known to be synchronized and safe to reuse. + if result.is_ok() { + release(w, key).await; + } match result { Err("mail_response_too_large") => Err("mail_export_too_large"), other => other, diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index c480172..1a7073b 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -572,7 +572,10 @@ async fn raw_message_returns_exact_octets_and_only_peeks() { .await .unwrap(); let bytes = STANDARD.decode(result["data"].as_str().unwrap()).unwrap(); - assert_eq!(bytes, expected, "the literal must be returned byte for byte"); + assert_eq!( + bytes, expected, + "the literal must be returned byte for byte" + ); assert_eq!(result["bytes"], expected.len()); server_task.await.unwrap(); } @@ -681,6 +684,69 @@ async fn raw_message_refuses_an_over_limit_literal_before_reading_it() { server_task.await.unwrap(); } +#[tokio::test] +async fn raw_message_reconnects_after_rejecting_an_unread_literal() { + let (listener, port) = server().await; + let server_task = tokio::spawn(async move { + let (socket, _) = listener.accept().await.unwrap(); + let mut first: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut first).await; + assert!( + line(&mut first) + .await + .unwrap() + .starts_with(b"O1 UID FETCH 1 ") + ); + let announced = crate::mail::export::MAX_BYTES + 1; + write( + &mut first, + format!("* 1 FETCH (UID 1 BODY[] {{{announced}}}\r\n").as_bytes(), + ) + .await + .unwrap(); + let mut byte = [0u8; 1]; + let read = tokio::time::timeout(Duration::from_secs(2), first.read(&mut byte)) + .await + .unwrap() + .unwrap(); + assert_eq!( + read, 0, + "an unread literal must close the connection before another command" + ); + let (socket, _) = listener.accept().await.unwrap(); + let mut second: Wire = BufReader::new(Box::new(socket)); + login_and_examine(&mut second).await; + assert!( + line(&mut second) + .await + .unwrap() + .starts_with(b"O1 UID FETCH 2 ") + ); + write( + &mut second, + b"* 2 FETCH (UID 2 BODY[] {4}\r\nTRUE)\r\nO1 OK fetched\r\n", + ) + .await + .unwrap(); + }); + assert_eq!( + call("imap.rawMessage", &export_params(port, 1)).await, + Err("mail_export_too_large") + ); + let next = tokio::time::timeout( + Duration::from_secs(3), + call("imap.rawMessage", &export_params(port, 2)), + ) + .await + .unwrap() + .unwrap(); + assert_eq!( + STANDARD.decode(next["data"].as_str().unwrap()).unwrap(), + b"TRUE" + ); + server_task.await.unwrap(); +} + #[tokio::test] async fn raw_message_rejects_a_bad_uid_before_connecting() { let (listener, port) = server().await; diff --git a/tests/stdio.rs b/tests/stdio.rs index 9a942d3..53585e6 100644 --- a/tests/stdio.rs +++ b/tests/stdio.rs @@ -89,6 +89,71 @@ fn broken_output_stops_backend_while_input_remains_open() { drop(input); } +#[test] +#[cfg(all(unix, feature = "integration-test-credentials"))] +fn closed_output_cancels_when_input_submission_is_backpressured() { + let sandbox = Sandbox::new(); + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + listener.set_nonblocking(true).unwrap(); + let port = listener.local_addr().unwrap().port(); + let mut child = sandbox + .command() + .arg("serve") + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + let mut input = child.stdin.take().unwrap(); + // Each request waits for a synthetic peer's greeting. More than the 32 + // running and 16 queued frames fills the submission queue without replies. + for id in 0..60 { + writeln!( + input, + "{}", + serde_json::json!({ + "jsonrpc":"2.0", "id":id, "method":"imap.check", + "params":{"settings":{"imapHost":"127.0.0.1","imapPort":port, + "username":"synthetic","insecure":true,"testPlaintext":true}, + "credential":"synthetic:password"} + }) + ) + .unwrap(); + } + let deadline = std::time::Instant::now() + Duration::from_secs(5); + let mut sockets = Vec::new(); + while sockets.len() < 32 { + match listener.accept() { + Ok((socket, _)) => sockets.push(socket), + Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { + if std::time::Instant::now() >= deadline { + child.kill().unwrap(); + child.wait().unwrap(); + panic!("all request slots must reach the synthetic peer"); + } + std::thread::sleep(Duration::from_millis(10)); + } + Err(error) => panic!("synthetic listener failed: {error}"), + } + } + drop(child.stdout.take().unwrap()); + let deadline = std::time::Instant::now() + Duration::from_secs(3); + loop { + if let Some(status) = child.try_wait().unwrap() { + assert!(!status.success()); + break; + } + if std::time::Instant::now() >= deadline { + child.kill().unwrap(); + child.wait().unwrap(); + panic!("closed output must wake a blocked frame submission"); + } + std::thread::sleep(Duration::from_millis(10)); + } + drop(input); + drop(sockets); +} + #[test] fn backend_replies_before_eof_and_drains_requests_before_quit() { let sandbox = Sandbox::new(); From 7c87b4c12581ed7dedeba5434bb1af80223871dc Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 21:41:10 -0500 Subject: [PATCH 17/20] docs: Record export review fixes and process checks --- planning/evidence/E03.md | 8 ++++ planning/evidence/EXPORT-REVIEW.md | 70 ++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 planning/evidence/EXPORT-REVIEW.md diff --git a/planning/evidence/E03.md b/planning/evidence/E03.md index 7def2ba..450593f 100644 --- a/planning/evidence/E03.md +++ b/planning/evidence/E03.md @@ -80,3 +80,11 @@ than in the view. - Member-specific menu test; and E03's broader UI matrix (stock API 5 / API 6 without the method) once a synthetic real backend operation is wired into the QML harness. + +## Review follow-up + +The task evidence above is historical. The later menu/account-switch tests, +manual synthetic screenshots, real native-process export checks, cancellation +fixes, and current validation limits are recorded in +[EXPORT-REVIEW.md](EXPORT-REVIEW.md) for source `066c744`. No release acceptance +or deployment approval is implied by the earlier READY FOR REVIEW status. diff --git a/planning/evidence/EXPORT-REVIEW.md b/planning/evidence/EXPORT-REVIEW.md new file mode 100644 index 0000000..57667d0 --- /dev/null +++ b/planning/evidence/EXPORT-REVIEW.md @@ -0,0 +1,70 @@ +# Export review follow-up + +Reviewed source: `066c7441271021b632a19ff75a5f3274355af3ad`. +Base: `d88833e44ae64d8b72ebb7ab3a1f014b16fd89f5`. +Environment: Linux, Rust 1.98.1, Qt 6.11.2. All fixtures use synthetic +accounts/messages and temporary HOME/XDG directories. + +## Findings resolved + +- Cancellation previously depended on reading a closed request channel. A full + 32-request window or blocked response delivery prevented that observation. + Cancellation now independently wakes and drops the owned dispatch futures. +- The input thread could also block submitting to the 16-frame queue. A Unix + output observer detects closure independently and wakes that submission by + cancelling dispatch. The process test submits 60 stalled requests, observes + all 32 active sockets, closes stdout, and requires a prompt unsuccessful exit. +- An oversized announced IMAP literal left unread bytes on a pooled connection. + Failed raw fetches now discard their connection. A loopback regression proves + EOF on the refused socket and a fresh connection for the next message. +- Malformed UID/folder syntax now maps to `mail_export_message_invalid` after + ordinary parameter validation. Empty, wrong-type, control, and oversized RPC + parameters retain their general `invalid_params` refusal. + +The first three regression tests failed before their fixes. The earlier +single-request cancellation test now waits for actual work to start before +raising cancellation. Clean stdin EOF and quit still drain accepted requests. + +## Validation + +| Command or scenario | Result | +| --- | --- | +| `make validate` | Exit 2: Rust/JS/shell passed; QML 1009 passed, 8 failed, no skips | +| `cargo test --locked --features integration-test-credentials` (inside validate) | All targets pass; library 593 passed, 11 ignored; stdio 4 passed | +| Independent focused tests | Raw retrieval 19, storage/export 17, scheduler 6, stdio 4 passed | +| Real `serve` with registered synthetic account and loopback IMAP | Exact multipart MIME wire bytes saved with mode 0600; half-close during FETCH completes; close-all-pipes during FETCH closes socket and leaves no file | +| `make test-app-qml qml-check` | Exit 0; existing QML warnings retained | +| `omarchy plugin validate .` and `git diff --check` | Exit 0 | +| `cargo clippy --locked --all-targets` | Exit 0; only existing search.rs:235/694 and mail/tests.rs:88 warnings | +| `python3 tests/test_backend_api.py --binary target/debug/omamail` | Exit 0; API 6, 31 methods, 179 advertised | +| `python3 tests/test_backend_process.py` | Exit 0; real Quickshell/native bridge scenarios pass | +| `python3 tests/test_agent_native_bridge.py` | Exit 0; 22 passed | + +Full validation ran on the fixes before final formatting and the Windows +unused-variable cleanup. The independent reviewer reran the affected Rust and +stdio tests on the final source contents and recorded matching SHA-256 hashes. +Logs, the process harness, and full independent report remain in ignored +`artifacts/final-review/`. + +## Baseline adjudication and judgment + +A detached checkout of the exact base, built from its own source, reproduces +all eight `KeyboardReaderNavigation` failures with the same Qt/software-renderer +and native-test bridge environment. Its focused suite reports 5 passed, +8 failed, no skips. Both feature branches fail the same eight cases. These are +accepted as inherited regression limitations for this review; `make validate` +is not reported green. Export identity/menu tests and the real process checks +cover the changed paths independently. + +The fresh reviewer inspected the entire export patch and the follow-up fixes, +verified the final source hashes, and found no remaining must-fix Linux defect. +Security: **PASS for the reviewed Linux export boundaries**. This is not a +repository-wide or cross-platform certification. A concurrent same-user rename +of Downloads can make the returned lexical path stale; the anchored write +remains safe. Windows/macOS runtime behavior is not verified. + +Release acceptance: **REVISE** because the planned combined-feature integration, +private runtime provenance/rollback, and final acceptance matrix are unfinished +(I00, R00, J00). This records completion of the defect-review follow-up, not +permission to merge, release, or replace the daily runtime. Screenshots remain +synthetic UI previews and do not establish real-account integration. From cc95b2d6b0d10010e97e13ba1779ec1030b0b0a4 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 22:09:02 -0500 Subject: [PATCH 18/20] fix: Observe closed output pipes on macOS --- src/backend/stdio.rs | 53 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/src/backend/stdio.rs b/src/backend/stdio.rs index b5e4fde..dabfadb 100644 --- a/src/backend/stdio.rs +++ b/src/backend/stdio.rs @@ -18,11 +18,7 @@ pub fn serve() -> io::Result<()> { // Observe output closure independently so cancellation drops that // queue and wakes its sender as well as all running requests. while !finished.load(Ordering::Acquire) { - let mut output = libc::pollfd { - fd: libc::STDOUT_FILENO, - events: 0, - revents: 0, - }; + let mut output = output_descriptor(libc::STDOUT_FILENO); let ready = unsafe { libc::poll(&mut output, 1, 100) }; if output.revents != 0 || failed.load(Ordering::Acquire) @@ -50,6 +46,19 @@ pub fn serve() -> io::Result<()> { }) } +#[cfg(unix)] +fn output_descriptor(fd: libc::c_int) -> libc::pollfd { + // Darwin registers no kqueue filter for events=0. Requesting POLLHUP + // registers its read filter, which watches closure on a pipe's write end + // without waking for ordinary writable capacity. Linux also reports pipe + // errors with this mask. Never request POLLOUT: it would spin while idle. + libc::pollfd { + fd, + events: libc::POLLHUP, + revents: 0, + } +} + #[cfg(target_os = "linux")] fn bind_to_parent() -> io::Result<()> { // Register before the protocol starts runtime threads. This applies only @@ -105,11 +114,7 @@ impl Read for Input { events: libc::POLLIN, revents: 0, }, - libc::pollfd { - fd: libc::STDOUT_FILENO, - events: 0, - revents: 0, - }, + output_descriptor(libc::STDOUT_FILENO), ]; // The backend is the only stdin reader. Read the descriptor directly: // a buffered Stdin reader could contain bytes invisible to poll. @@ -177,3 +182,31 @@ impl Write for Output { result } } + +#[cfg(all(test, unix))] +mod tests { + use super::*; + use std::os::fd::{AsRawFd, FromRawFd, OwnedFd}; + + #[test] + fn output_observer_waits_until_the_pipe_reader_closes() { + let mut descriptors = [-1; 2]; + assert_eq!(unsafe { libc::pipe(descriptors.as_mut_ptr()) }, 0); + // Own both descriptors immediately so assertions also close them. + let reader = unsafe { OwnedFd::from_raw_fd(descriptors[0]) }; + let writer = unsafe { OwnedFd::from_raw_fd(descriptors[1]) }; + let mut output = output_descriptor(writer.as_raw_fd()); + assert_eq!( + unsafe { libc::poll(&mut output, 1, 20) }, + 0, + "a writable pipe must not wake an idle observer" + ); + drop(reader); + assert_eq!(unsafe { libc::poll(&mut output, 1, 200) }, 1); + assert_ne!( + output.revents & (libc::POLLERR | libc::POLLHUP | libc::POLLNVAL), + 0, + "peer closure must wake the observer without writing a response" + ); + } +} From 809adaf7723e0e714daa520d262cca3549357f3e Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Tue, 29 Sep 2026 22:10:11 -0500 Subject: [PATCH 19/20] docs: Record macOS pipe observer correction --- planning/evidence/EXPORT-REVIEW.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/planning/evidence/EXPORT-REVIEW.md b/planning/evidence/EXPORT-REVIEW.md index 57667d0..f92bbe6 100644 --- a/planning/evidence/EXPORT-REVIEW.md +++ b/planning/evidence/EXPORT-REVIEW.md @@ -68,3 +68,26 @@ private runtime provenance/rollback, and final acceptance matrix are unfinished (I00, R00, J00). This records completion of the defect-review follow-up, not permission to merge, release, or replace the daily runtime. Screenshots remain synthetic UI previews and do not establish real-account integration. + +## macOS pipe-observer correction + +The macOS standalone-app job at `7c87b4c` failed the new full-queue stdio test: +all 32 requests reached the synthetic peer, but closing stdout did not wake +submission within three seconds. The other 13 checks passed. This was a new +portability defect, not an inherited failure or a reason to relax the test. + +Source fix: `cc95b2d6b0d10010e97e13ba1779ec1030b0b0a4`. Both output poll sites +now use one descriptor helper with an explicit `POLLHUP` event request. Apple’s +[poll implementation](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/kern/sys_generic.c) +registers no filter for an empty event mask. Its +[pipe implementation](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/kern/sys_pipe.c) +uses a closure-only read filter on a write-only pipe; the explicit hangup mask +selects that filter without requesting ordinary writable readiness. + +A real-pipe regression requires no event while the reader is open and an error +or hangup event after it closes, without writing a response. Local focused +checks passed: pipe observer 1/1 and stdio 4/4. An independent source review +verified the mask/filter reasoning, both call sites, the regression, and source +hashes. Native macOS CI must verify the corrected platform path; its result is +recorded on the exact PR candidate. The earlier Linux security verdict and +unfinished release-acceptance work retain their stated scope. From 00453f69e2eed6a9cbf6391c676488c8c12ee1ff Mon Sep 17 00:00:00 2001 From: Chris Gray <216301595+latentoperator@users.noreply.github.com> Date: Wed, 30 Sep 2026 09:05:46 -0500 Subject: [PATCH 20/20] Drop internal task references from source comments --- src/backend/mail.rs | 2 +- src/mail/export.rs | 12 ++++++------ src/providers/imap/export.rs | 2 +- src/providers/imap/tests.rs | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/backend/mail.rs b/src/backend/mail.rs index 03a0795..505a3e4 100644 --- a/src/backend/mail.rs +++ b/src/backend/mail.rs @@ -7,7 +7,7 @@ use std::{future::Future, pin::Pin}; #[path = "mail_action_tests.rs"] mod action_tests; -/// Supplies E01's raw retrieval to the export service. Credentials are resolved +/// Supplies the IMAP raw-message retrieval to the export service. Credentials are resolved /// by the IMAP layer from the account id, as every other provider call does, so /// no secret passes through the export path. struct ProviderExport; diff --git a/src/mail/export.rs b/src/mail/export.rs index c228aeb..d70236b 100644 --- a/src/mail/export.rs +++ b/src/mail/export.rs @@ -1,8 +1,8 @@ //! Save one message's original bytes as `.eml` in the user's Downloads folder. //! -//! The bytes come from the provider operation E01 added (`imap.rawMessage`) and -//! are written unchanged. The RPC contract is frozen in `planning/decisions/E00.md`; -//! this module owns strict account resolution's consumer side, the filename +//! The bytes come from the provider's raw-message operation (`imap.rawMessage`) +//! and are written unchanged. The `mail.exportEml` RPC contract is fixed; this +//! module owns strict account resolution's consumer side, the filename //! policy, the bounded write, and the result shape. use super::{Account, ExportRequest, Provider}; use base64::{Engine, engine::general_purpose::STANDARD}; @@ -20,11 +20,11 @@ use std::{ }; use tokio::sync::{Notify, OwnedSemaphorePermit, Semaphore}; -/// The product limit from E00: below the transport's 32 MiB response bound and +/// The product size limit: below the transport's 32 MiB response bound and /// above the 20 MiB attachment limit. Checked before any unbounded allocation. pub(crate) const MAX_BYTES: usize = 25 * 1024 * 1024; -/// The operation deadline E00 froze. It is enforced inside the export, under +/// The fixed operation deadline. It is enforced inside the export, under /// the client's 30 s bridge deadline, and never leaves a partial file. pub(crate) const EXPORT_DEADLINE: Duration = Duration::from_secs(25); @@ -157,7 +157,7 @@ impl Cancellation { } } -/// The per-request controls E00 froze. The token names the provider fetch in +/// The fixed per-request controls. The token names the provider fetch in /// the IMAP cancel registry; the signal lets the export stop it before commit. /// Cloning shares both, so the drop guard can cancel a request it did not make. #[derive(Clone)] diff --git a/src/providers/imap/export.rs b/src/providers/imap/export.rs index ae4a861..5306fc4 100644 --- a/src/providers/imap/export.rs +++ b/src/providers/imap/export.rs @@ -3,7 +3,7 @@ //! //! Internal to the provider layer and deliberately absent from the advertised //! public method inventory (`src/backend/methods.rs`), like the internal -//! `jmap.action*` planners. `mail.exportEml` (E02) consumes it. +//! `jmap.action*` planners. `mail.exportEml` consumes it. use super::*; /// Validate the export parameters before any socket is opened. diff --git a/src/providers/imap/tests.rs b/src/providers/imap/tests.rs index 1a7073b..2fb0c99 100644 --- a/src/providers/imap/tests.rs +++ b/src/providers/imap/tests.rs @@ -520,7 +520,7 @@ fn outlook_settings_ignore_persisted_credential_destination_and_identity() { assert_eq!(settings["insecure"], false); } -// ---------------------------------------------------------------- E01 export +// ------------------------------------------------------------ raw export fn export_params(port: u16, uid: u64) -> Value { json!({ "settings": {"imapHost":"127.0.0.1","imapPort":port,"username":"synthetic","insecure":true,"testPlaintext":true},