webmail-client/docs/open-questions.md

Open Questions

Per the setup rules, deviations and unresolved decisions are recorded here rather than guessed silently.

OQ-6 — Appendix C needs SDK surfaces the frozen §11 API does not have

Status: resolved by additive SDK extension; recorded here because C.8.1 says "zero core diffs".

Problem. C1 cannot be written against the M3 SDK as frozen:

1. §C.4 step 4 requires moving a message to Junk "through the existing move machinery, so the verdict propagates to the IMAP server". PluginActions exposed only set_flags and trash. trash moves the whole thread, which is right for Delete and wrong for a spam verdict — one spam reply would drag a legitimate conversation into Junk. (The filters plugin had already noted the same gap: "a move action would follow the same pattern".)
2. §C.4 step 3 posts the raw blob to Rspamd. PluginMessages exposed envelope() and header() — no way to get the whole RFC822.
3. §C.4 step 1 processes "only messages landing in special_use='inbox' mailboxes". Neither the message.new payload nor envelope() said where a message landed.

Resolution. Three additive changes to app/plugins/, no change to any core mail path:

• PluginActions.move_to_special(user_id, message_id, special_use) — per-message move wrapping the same optimistic-update + move_job path as the core endpoint. Returns False (never raises) when the account has no such folder.
• PluginMessages.raw(user_id, message_id) -> bytes | None.
• envelope() now also returns account_id and mailbox_special_use.

C2 needed two more, on the same reasoning:

4. §C.5 passive learning reads the user's own filing as a verdict, which needs the transition — "now in Junk" and "moved out of Junk" are different facts. message.changed carried only the destination, so move_job now also publishes previous_mailbox_id, special_use and previous_special_use.
5. §C.5 provider bootstrap samples up to 500 provider-Junk messages and 500 aged Inbox messages. The SDK could fetch a message by id but not enumerate a folder, so PluginMessages.sample(account_id, special_use, limit, older_than_days) returns ids only — the caller pulls bodies one at a time, so a 500-message sample never materialises 500 bodies.

Reading of "zero core diffs": taken to mean the plugin must not require changes to core mail flow or behaviour — with the plugin absent, mail handling is byte-identical, which remains true. Extending the plugin SDK is what the SDK is for, and all three additions are useful beyond antispam. If the intent was literally "no file under app/ changes", C1 is not implementable and the spec needs amending instead.

Also note: §C.2 itself mandates compose additions (rspamd, redis-rspamd), which are core-repo diffs by any reading. They are placed behind a compose profile so a deployment that does not want the engine is unaffected.

OQ-7 — Rspamd cannot be reached through the SDK's guarded HTTP

Status: resolved, deliberate.

sdk.http applies the §10.6 SSRF guard, which rejects private addresses. That is correct for user-supplied CalDAV/CardDAV URLs, but Rspamd lives at http://rspamd:11333 on the compose network — a private address by definition. The guard would forbid the only address that works.

The antispam plugin therefore uses httpx directly for engine calls. This is safe for the reason the guard exists: the URL comes from RSPAMD_URL in the operator's environment, never from user input, so there is no request-forgery surface to protect. User-supplied URLs in this plugin (there are none today) would still have to go through sdk.http.

OQ-1 — Meilisearch container healthcheck reports unhealthy (IPv6 localhost)

Status: resolved — approved deviation applied. The healthcheck URL in docker/docker-compose.yml was changed from localhost to 127.0.0.1; the container now reports healthy.

Symptom: docker compose ps shows meilisearch as unhealthy, even though the service is fully up and reachable from the host (curl http://127.0.0.1:7700/health returns {"status":"available"}).

Root cause: the spec's healthcheck is wget -qO- http://localhost:7700/health | grep -q available. Inside the getmeili/meilisearch:v1.8 container, /etc/hosts maps localhost to both 127.0.0.1 and ::1, and busybox wget tries the IPv6 ::1 first. Meilisearch listens IPv4-only on 0.0.0.0:7700 (MEILI_HTTP_ADDR=0.0.0.0:7700), so the ::1 connection is refused and the healthcheck fails. wget http://127.0.0.1:7700/health from inside the container succeeds.

Impact: cosmetic for direct use (the service works), but real for automation: docker compose up --wait (used by the reset-db Make target) and the "all must be healthy" verification step will hang/fail on this host.

Proposed minimal fix (one word): change the healthcheck URL from localhost to 127.0.0.1: test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:7700/health | grep -q available"]. This is a deviation from the frozen setup doc, so it is left for explicit approval.

OQ-5 — Relative BLOB_ROOT breaks across processes with different CWDs

Status: resolved in dev by using an absolute path.

BLOB_ROOT=./var/blobs (relative) resolves against each process's working directory. Per the dev-setup doc the API runs from the repo root (uvicorn --app-dir backend) while the worker runs "from backend/", so blobs written by the worker land in backend/var/blobs but the API reads ./var/blobs at the repo root — a different, empty directory. This only surfaced once the API began reading blobs (M1 re-sanitize-on-render / attachments); before that the API only served sanitized HTML from Postgres.

Fix: .env.dev now sets an absolute BLOB_ROOT. Additionally GET /messages/{id}/html falls back to the stored (possibly stale) sanitized HTML if a blob is unreadable, so a path/permission issue degrades gracefully instead of 500-ing. .env.example keeps the relative default with a note; production should always use an absolute path or run both processes from the same CWD.

OQ-4 — Duplicate Message-ID / bulk-sender over-merging (threading)

Status: resolved with two refinements (both consistent with §7.1's stated intent).

Symptom (found while testing): home.pl's welcome mailer reuses one static Message-ID (and Date) for every recipient. Two welcome mails — one per test account, 104 days apart, byte-identical — collapsed into a single thread.

Cause & fixes:

1. Duplicate Message-ID (§7.1, was only half-implemented). The indexer now synthesizes a non-authoritative id when a Message-ID is already present in a different account (a separate delivery). A same-account duplicate keeps the real id, so Gmail-style INBOX + All Mail copies of one message still thread together. Implemented in app/indexer/indexer.py::_resolve_message_id; new index ix_messages_user_msgid (migration 0002).
2. Subject fallback (§7.3 refinement). The literal rule ("same subject + within 7 days + shares ≥1 participant") over-merges bulk mail, because the shared participant can be just the common sender. Subject joining now keys on the incoming message's recipients (To/Cc) overlapping the thread — a genuine reply is always addressed to someone in the thread, a bulk blast to another account is not. app/threading_/threader.py::_find_by_subject.

Both are minor tightenings of the spec's anti-over-merge intent, not behavior the spec forbids. Covered by tests/indexer/test_duplicate_msgid.py and updated threading vectors.

OQ-3 — __Host- session cookie vs. plain-HTTP dev

Status: resolved with a documented dev fallback.

SPEC §6.1/§10.3 mandate the __Host-session cookie prefix, which the browser only accepts when the cookie is Secure and sent over HTTPS. The dev setup (dev-environment-setup.md) serves the API over plain HTTP (uvicorn :8000 behind the Vite HTTP proxy), so a __Host-/Secure cookie would be silently dropped and login could never work in dev.

Decision: cookie naming/flags are derived per-request from the scheme (app/identity/cookies.py): over HTTPS we emit the spec-mandated __Host-session + Secure; over plain HTTP (dev only) we fall back to session without Secure. Production (behind TLS) is fully spec-compliant. SameSite=Lax, HttpOnly, Path=/ always. The CSRF cookie follows the same scheme rule but is readable by JS (double-submit, SPEC §10.3).

OQ-2 — Repository was not a git repo (resolved)

Status: resolved.

The setup doc's conda activate.d hook locates .env.dev via git rev-parse --show-toplevel, and the overall workflow (commit-per-increment, per-plugin alembic branches) assumes git. The working directory was not a git repo, so .env.dev did not auto-load on conda activate. Ran git init (branch main); the hook now loads the env correctly. No spec deviation — the doc already assumes git.