Skip to content

Add original-message export for Outlook and IMAP - #3

Merged
latentoperator merged 21 commits into
mainfrom
task/E03-export-ui
Oct 1, 2026
Merged

latentoperator merged 21 commits into
mainfrom
task/E03-export-ui

Conversation

@latentoperator

@latentoperator latentoperator commented Sep 29, 2026 •

Copy link
Copy Markdown
Owner

Outcome

Add Save as .eml to the message menu and Ctrl+Shift+S in the list and reader. Outlook and IMAP messages save to Downloads with their original headers, MIME parts, and attachments. Existing files receive a numbered alternative name. The status bar shows saving, success, and failure messages.

The request captures the owning account and message, including conversation members. Export requires provider support and an advertised mail.exportEml method. Retrieval uses EXAMINE and BODY.PEEK[] to preserve mail state.

The backend refuses IMAP literals above 25 MiB before reading their payloads, allows one active export per account and two overall, and checks the 25-second deadline before file creation. Equivalent UID spellings share an admission slot. Unix file creation rechecks cancellation and the deadline on every filename-collision retry. A broken output pipe cancels pending work even when the request or response queues are full. Failed raw fetches discard their connection so unread message bytes cannot enter the next request. Clean stdin EOF and quit still drain accepted requests.

Status

Draft until the spelling change (#4) has had its last hands-on check on a real desktop; the two have been built and tested together (below). Base: 4d5e0f0; head: 00453f6.

Verification

  • Rust targets passed on the latest candidate with integration-test-credentials: library 594 passed, 11 ignored. The real-pipe observer regression and all four stdio tests passed, including on macOS.
  • Independent focused review: 46 tests passed, including full queues, blocked response delivery, rejected-literal reconnection, and clean EOF.
  • A real backend process with a synthetic account saved the exact multipart MIME bytes with mode 0600. Closing stdin during FETCH still completed the save. Closing all pipes during FETCH closed the fetch socket and left no file.
  • make validate: QML 1009 passed, 8 failed, no skips. The same eight keyboard-navigation failures reproduce at the pinned baseline. The Rust, JS, and shell stages passed; the later app-QML, lint, plugin validation, and diff checks were run separately and passed.
  • Backend API contract: passed, with 31 methods and 179 advertised methods. Real backend-process checks passed; native agent bridge tests passed 22/22.
  • Clippy: only the three existing warnings, none in changed code. QML lint retains existing warnings.

Tests use synthetic mail and isolated directories. The fresh independent reviewer found no remaining must-fix Linux defect. The earlier macOS run caught a pipe-observer portability defect. The fix requests closure events explicitly and adds a regression for idle and closed pipes. All 14 GitHub checks passed for this candidate, including the macOS host and production-archive checks.

Combined build with #4

Merged with #4 on top of 4d5e0f0 and run on an Arch/Omarchy laptop (Qt 6.11.2, Quickshell 0.3.1, Rust 1.98.1, Sonnet 6.29.0), with isolated home and config directories:

  • make test-rust: 667 passed, 11 ignored. test-js, test-shell, test-backend-process, test-app-qml, and qml-check passed.
  • make test-qml: 1066 passed, 8 failed. The failures are the same eight KeyboardReaderNavigation cases that fail on untouched main with this Qt.
  • End to end, the real omamail serve with a synthetic IMAP account on a loopback server saved a multipart message with an 8-bit body and a binary attachment. The file was byte-identical, mode 0600, and parsed independently with the subject, body, and attachment intact. A second save got (2) added to the name. The server saw only EXAMINE and UID FETCH … BODY.PEEK[]. Missing messages, unknown accounts, and a missing account were refused.
  • With Sonnet hidden from the QML import path, the spelling suites skip and the export suites pass. With Sonnet present, they all pass.

Screenshots

Reviewed captures show the message menu before and after, plus saving, success, and error notices in light and dark themes. Images are hosted as GitHub attachments.

The previews use a synthetic account and message with simulated export replies; no mail is fetched or file written. The success notice is held open for capture. The light menu pair uses identical dimensions. The dark menu widths differ by four pixels, and the dark error capture is wider so the entire message is readable.

The menu gains Save as .eml. The status bar reports saving, the saved path, or a failure.

Before, light theme After, light theme
before export menu light after export menu light
Status messages and dark-theme captures
Theme Before menu After menu Saving Saved Error
Light before export menu light after export menu light after export busy light after export success light after export error light
Dark before export menu dark after export menu dark after export busy dark after export success dark after export error dark

The export notices are new states. They have no counterpart in the baseline menu.

Security

Reviewed and passed for the Linux account routing, raw-byte retrieval, private storage, resource limits, and cancellation changes. Independent review and synthetic process tests cover those boundaries. Windows and macOS runtime behavior is not verified.

Release Notes

  • Save an Outlook or IMAP message as an .eml file from its menu or with Ctrl+Shift+S.
  • See whether the save is in progress, completed, or failed in the status bar.

- 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
- 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
- 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
- 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
- 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
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.
…rols

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.
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.
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.
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.
@latentoperator
latentoperator marked this pull request as ready for review October 1, 2026 15:14
@latentoperator
latentoperator merged commit 0a9eb90 into main Oct 1, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant