Repository Public
1// File durable des actions hors ligne : lu, favori, épinglage, libellé (mot-clé), déplacement et leur annulation deviennent des2// correctifs JMAP idempotents, conservés dans IndexedDB, rejoués dans l'ordre à la reconnexion. Le serveur gagne en cas de conflit.3//4// Garanties :5// - liée à l'utilisateur : une file écrite pour quelqu'un d'autre n'est jamais rejouée ; elle vit dans la base du cache local, qui6// est effacée à toute perte de session (déconnexion, expiration, révocation) ;7// - idempotente : chaque correctif pose une valeur absolue (« ce mot-clé est présent », « ce message est dans ces dossiers ») ;8// le rejouer deux fois donne le même état, et une réponse perdue ne crée pas de doublon ;9// - le serveur gagne : avant d'envoyer, l'état courant est relu ; un champ modifié sur le serveur depuis l'action locale n'est10// pas écrasé. Après le rejeu, les lignes touchées sont relues ;11// - un refus définitif est retiré de la file, signalé une seule fois, et la ligne est rétablie.12// Ni l'envoi ni la suppression définitive ne passent par ici : ils exigent une connexion (le brouillon reste sur l'appareil).13import { addMessages, t } from "../i18n"14import { enOffline } from "../i18n/en.offline"15import { frOffline } from "../i18n/fr.offline"16import type { JmapClient } from "../jmap/client"17import { HttpError, NetworkError } from "../jmap/errors"18import { SUMMARY_PROPS, type EmailSummary, type Id } from "../jmap/types"19import { S, folderOfView, toast } from "./app"20import { cacheGet, cachePut } from "./cache"2122addMessages("fr", frOffline)23addMessages("en", enOffline)2425// ================================================================ modèle (pur, testé sans navigateur)26/** Correctif JMAP d'un message : `keywords/<mot-clé>` → true | null, `mailboxIds` → ensemble complet des dossiers. */27export type JmapPatch = Record<string, unknown>2829export interface QueuedOp {30 /** rang d'entrée dans la file : le rejeu suit cet ordre */31 seq: number32 user: string33 mb: string34 id: Id35 /** valeurs voulues */36 patch: JmapPatch37 /** valeurs que ces champs avaient AVANT la première action locale (détection de conflit, annulation) */38 base: JmapPatch39 at: number40}41export interface QueueState {42 user: string | null43 seq: number44 ops: QueuedOp[]45}46export const emptyQueue = (user: string | null = null): QueueState => ({ user, seq: 0, ops: [] })4748const KEYWORD = "keywords/"49const idSet = (v: unknown): string[] => (v && typeof v === "object" ? Object.keys(v as object).filter((k) => (v as Record<string, unknown>)[k]) : []).sort()50/** Égalité des valeurs d'un champ : présence d'un mot-clé (true contre null / absent), même ensemble de dossiers. */51export function sameValue(key: string, a: unknown, b: unknown): boolean {52 if (key === "mailboxIds") return idSet(a).join("\n") === idSet(b).join("\n")53 if (key.startsWith(KEYWORD)) return !!a === !!b54 return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)55}5657/** Retire d'une opération les champs revenus à leur valeur d'origine ; `null` si plus rien n'est à faire. */58function compact(op: QueuedOp): QueuedOp | null {59 const patch: JmapPatch = {}60 const base: JmapPatch = {}61 for (const k of Object.keys(op.patch)) {62 if (sameValue(k, op.patch[k], op.base[k])) continue63 patch[k] = op.patch[k]64 base[k] = op.base[k]65 }66 return Object.keys(patch).length ? { ...op, patch, base } : null67}6869/**70 * Ajoute des actions à la file. Une seule opération par message : l'action suivante sur le même message fusionne dans la71 * première (elle garde son rang), la dernière valeur l'emporte champ par champ, et deux actions opposées s'annulent (favori puis72 * retrait du favori = rien à envoyer). `bases` porte les valeurs d'avant l'action (le correctif inverse).73 */74export function enqueueOps(state: QueueState, user: string, mb: string, patches: Record<Id, JmapPatch>, bases: Record<Id, JmapPatch> = {}, now = Date.now()): QueueState {75 // file d'un autre utilisateur : elle est abandonnée, jamais mêlée76 let { seq, ops } = state.user === user ? state : emptyQueue(user)77 ops = [...ops]78 for (const [id, patch] of Object.entries(patches)) {79 if (!Object.keys(patch).length) continue80 const at = ops.findIndex((o) => o.mb === mb && o.id === id)81 if (at < 0) {82 const op = compact({ seq: ++seq, user, mb, id, patch: { ...patch }, base: { ...(bases[id] ?? {}) }, at: now })83 if (op) ops.push(op)84 continue85 }86 const prev = ops[at]87 // la base la plus ancienne fait foi : c'est l'état que le serveur avait avant toute action locale88 const merged = compact({ ...prev, patch: { ...prev.patch, ...patch }, base: { ...(bases[id] ?? {}), ...prev.base }, at: now })89 if (merged) ops[at] = merged90 else ops.splice(at, 1)91 }92 return { user, seq, ops }93}9495/** Opérations rejouables pour cet utilisateur, dans l'ordre d'entrée. Une file d'un autre utilisateur ne rend rien. */96export function opsFor(state: QueueState, user: string | null, mb?: string): QueuedOp[] {97 if (!user || state.user !== user) return []98 return state.ops.filter((o) => o.user === user && (mb === undefined || o.mb === mb)).sort((a, b) => a.seq - b.seq)99}100101/** File relue du stockage : rendue telle quelle si elle appartient à l'utilisateur connecté, vide sinon. */102export function bindUser(state: QueueState | null | undefined, user: string): QueueState {103 if (!state || state.user !== user || !Array.isArray(state.ops)) return emptyQueue(user)104 const ops = state.ops.filter((o) => o && o.user === user && typeof o.mb === "string" && typeof o.id === "string" && o.patch && typeof o.patch === "object")105 return { user, seq: Math.max(state.seq || 0, ...ops.map((o) => o.seq || 0)), ops }106}107108export interface ServerEmail {109 keywords?: Record<string, boolean> | null110 mailboxIds?: Record<string, boolean> | null111}112const serverValue = (e: ServerEmail, key: string): unknown => (key === "mailboxIds" ? (e.mailboxIds ?? {}) : key.startsWith(KEYWORD) ? (e.keywords?.[key.slice(KEYWORD.length)] ? true : null) : undefined)113114export interface Resolution {115 /** ce qu'il reste à envoyer */116 send: JmapPatch117 /** champs que le serveur a modifiés entre-temps : il gagne, l'action locale est abandonnée pour ces champs */118 conflicts: string[]119 /** champs déjà à la valeur voulue (rejeu après une réponse perdue) */120 applied: string[]121 /** le message n'existe plus : l'opération est refusée définitivement */122 gone: boolean123}124/** Fusion à trois voies d'une opération avec l'état courant du serveur (le serveur gagne). */125export function resolveOp(op: Pick<QueuedOp, "patch" | "base">, server: ServerEmail | null): Resolution {126 const out: Resolution = { send: {}, conflicts: [], applied: [], gone: !server }127 if (!server) return out128 for (const k of Object.keys(op.patch)) {129 const cur = serverValue(server, k)130 if (sameValue(k, cur, op.patch[k])) out.applied.push(k)131 else if (k in op.base && !sameValue(k, cur, op.base[k])) out.conflicts.push(k)132 else out.send[k] = op.patch[k]133 }134 return out135}136137/** Retire de la file les opérations traitées (identité d'objet : une opération modifiée pendant le rejeu reste). */138export function settleOps(state: QueueState, done: readonly QueuedOp[]): QueueState {139 const gone = new Set(done)140 return { ...state, ops: state.ops.filter((o) => !gone.has(o)) }141}142143/**144 * Une action est venue fusionner dans une opération pendant qu'elle était rejouée : sa base devient ce que le serveur vient145 * d'accepter (sinon le prochain rejeu y verrait, à tort, un conflit).146 */147export function rebaseOps(state: QueueState, sent: ReadonlyMap<string, JmapPatch>): QueueState {148 const ops: QueuedOp[] = []149 for (const o of state.ops) {150 const s = sent.get(`${o.mb}\n${o.id}`)151 const next = s ? compact({ ...o, base: { ...o.base, ...s } }) : o152 if (next) ops.push(next)153 }154 return { ...state, ops }155}156157/** Délai avant le prochain essai : 2 s, 4 s, 8 s… plafonné à une minute. */158export const backoffMs = (attempt: number): number => Math.min(60_000, 2000 * 2 ** Math.max(0, Math.min(attempt, 10)))159160/** Applique un correctif en attente à la copie locale d'un message ; rend le même objet si rien ne change. */161export function overlayEmail<T extends { keywords: Record<string, boolean>; mailboxIds: Record<Id, boolean> }>(e: T, patch: JmapPatch): T {162 let keywords = e.keywords163 let mailboxIds = e.mailboxIds164 for (const [k, v] of Object.entries(patch)) {165 if (k === "mailboxIds") {166 if (!sameValue(k, mailboxIds, v)) mailboxIds = Object.fromEntries(idSet(v).map((id) => [id, true]))167 } else if (k.startsWith(KEYWORD)) {168 const kw = k.slice(KEYWORD.length)169 if (!!keywords[kw] === !!v) continue170 keywords = { ...keywords }171 if (v) keywords[kw] = true172 else delete keywords[kw]173 }174 }175 return keywords === e.keywords && mailboxIds === e.mailboxIds ? e : { ...e, keywords, mailboxIds }176}177178/** Panne de transport (réseau coupé, passerelle ou serveur de courrier injoignable) : l'action attend au lieu d'échouer. */179export function isTransportFailure(e: unknown): boolean {180 return e instanceof NetworkError || (e instanceof HttpError && (e.status === 502 || e.status === 503 || e.status === 504))181}182183// ================================================================ exécution184export interface OfflineBindings {185 /** envoi direct (Email/set) : lève en cas d'échec */186 send(mb: string, patches: Record<Id, JmapPatch>): Promise<void>187 /** client JMAP d'une boîte connectée, s'il y en a un */188 client(mb: string): Pick<JmapClient, "call"> | undefined189 /** relit ce qui est affiché pour cette boîte après un rejeu (le serveur fait foi) */190 refresh(mb: string): Promise<void> | void191 /** des actions attendent pour une boîte qui n'est pas connectée : demande une nouvelle tentative de connexion */192 reconnect?(mb: string): void193}194195const STORE_KEY = "offline-queue"196let state: QueueState = emptyQueue()197let bound: OfflineBindings | null = null198let active = false199let unsubscribe: (() => void) | null = null200let timer: ReturnType<typeof setTimeout> | null = null201let attempt = 0202let replaying = false203let writing: Promise<void> = Promise.resolve()204205const isOnline = (): boolean => typeof navigator === "undefined" || navigator.onLine !== false206const currentUser = (): string | null => S.get().me?.user.id ?? null207208/** @internal Branché par state/mail.ts (qui possède les clients JMAP) : évite une dépendance circulaire. */209export function bindOffline(b: OfflineBindings) {210 bound = b211}212/** Nombre d'actions en attente pour l'utilisateur connecté (indicateur « Hors ligne · N en attente »). */213export const queuedCount = (): number => opsFor(state, currentUser()).length214/** @internal Tests : état courant de la file. */215export const queueSnapshot = (): QueueState => state216217function publish() {218 const queued = queuedCount()219 S.set((s) => ((s.sync.queued ?? 0) === queued ? {} : { sync: { ...s.sync, queued } }))220}221function persist() {222 if (!active) return223 const snapshot = state224 writing = writing.then(() => (active ? cachePut(STORE_KEY, snapshot) : undefined)).catch(() => undefined)225}226function commit(next: QueueState) {227 state = next228 persist()229 publish()230}231232/** Connexion établie : la file de CET utilisateur est relue ; celle de tout autre est abandonnée. */233export async function startOffline(user: string): Promise<void> {234 active = true235 attempt = 0236 state = emptyQueue(user)237 const stored = await cacheGet<QueueState>(STORE_KEY)238 if (!active || currentUser() !== user) return239 // des actions ont pu être mises en file pendant la lecture : elles sont rejouées après celles du stockage240 const fresh = state.ops241 state = bindUser(stored, user)242 for (const o of fresh) state = enqueueOps(state, user, o.mb, { [o.id]: o.patch }, { [o.id]: o.base }, o.at)243 if (stored && stored.user !== user) persist()244 publish()245 unsubscribe?.()246 unsubscribe = S.subscribe(onStateChange)247 if (typeof window !== "undefined") window.addEventListener("online", onOnline)248 onStateChange()249}250251/** Perte de session : plus rien en mémoire, plus aucun rejeu. Le stockage est effacé avec le cache local (state/cache.ts). */252export function stopOffline() {253 active = false254 state = emptyQueue()255 unsubscribe?.()256 unsubscribe = null257 if (timer) clearTimeout(timer)258 timer = null259 attempt = 0260 if (typeof window !== "undefined") window.removeEventListener("online", onOnline)261}262263function onOnline() {264 attempt = 0265 schedule(300)266}267function schedule(delay: number) {268 if (timer || !active) return269 timer = setTimeout(() => {270 timer = null271 void replay()272 }, delay)273}274275let overlaying = false276/** À chaque changement d'état : les actions en attente restent visibles (listes et fils relus du cache), et le rejeu est planifié. */277function onStateChange() {278 if (overlaying || !state.ops.length) return279 const s = S.get()280 const user = s.me?.user.id ?? null281 const ops = s.mb ? opsFor(state, user, s.mb) : []282 if (ops.length) {283 let emails = s.emails284 let open = s.open285 for (const op of ops) {286 const e = emails[op.id]287 if (e) {288 const next = overlayEmail(e, op.patch)289 if (next !== e) emails = { ...emails, [op.id]: next }290 }291 const oe = open?.emails[op.id]292 if (open && oe) {293 const next = overlayEmail(oe, op.patch)294 if (next !== oe) open = { ...open, emails: { ...open.emails, [op.id]: next } }295 }296 }297 // une ligne déplacée hors du dossier affiché (archive, corbeille) n'y reparaît pas, même après un rechargement hors ligne298 let list = s.list299 const folder = s.all ? undefined : folderOfView(s.accounts[s.mb!], s.view)300 if (folder) {301 const moved = new Set(ops.filter((o) => "mailboxIds" in o.patch && !idSet(o.patch.mailboxIds).includes(folder.id)).map((o) => o.id))302 if (moved.size && list.ids.some((id) => id && moved.has(id))) {303 const ids = list.ids.filter((id) => !id || !moved.has(id))304 list = { ...list, ids, total: list.total === null ? null : Math.max(0, list.total - (list.ids.length - ids.length)) }305 }306 }307 if (emails !== s.emails || open !== s.open || list !== s.list) {308 overlaying = true309 try {310 S.set({ emails, open, list })311 } finally {312 overlaying = false313 }314 }315 }316 if (isOnline() && !replaying) schedule(attempt ? backoffMs(attempt) : 400)317}318319/**320 * Point d'entrée des actions sur les messages (state/mail.ts `act()` et tout autre appelant) : envoie les correctifs tout de321 * suite si c'est possible ; sinon (hors ligne, panne de transport, ou actions déjà en attente pour cette boîte — l'ordre est322 * préservé) les met en file. `bases` : valeurs d'avant l'action, champ par champ (le correctif inverse).323 * Lève toute autre erreur (refus du serveur) : l'appelant annule alors son affichage optimiste.324 */325export async function queueOrSend(mb: string, patches: Record<Id, JmapPatch>, bases: Record<Id, JmapPatch> = {}): Promise<"sent" | "queued"> {326 if (!Object.keys(patches).length) return "sent"327 const user = currentUser()328 const waiting = opsFor(state, user, mb).length > 0329 if (isOnline() && !waiting) {330 if (!bound) throw new NetworkError("offline queue not bound")331 try {332 await bound.send(mb, patches)333 return "sent"334 } catch (e) {335 if (!isTransportFailure(e) || !user) throw e336 }337 }338 if (!user) throw new NetworkError()339 commit(enqueueOps(state, user, mb, patches, bases))340 // L'appelant a déjà affiché son action, mais le recouvrement ci-dessus a pu la contredire avec l'ANCIENNE file (ex. retrait341 // d'un favori encore en attente) : la valeur voulue est reposée maintenant que la file est à jour — dans le même tour, sans342 // scintillement.343 showPatches(mb, patches)344 if (isOnline()) schedule(backoffMs(attempt))345 return "queued"346}347348function showPatches(mb: string, patches: Record<Id, JmapPatch>) {349 const s = S.get()350 if (s.mb !== mb) return351 let emails = s.emails352 let open = s.open353 for (const [id, patch] of Object.entries(patches)) {354 const e = emails[id]355 if (e) {356 const next = overlayEmail(e, patch)357 if (next !== e) emails = { ...emails, [id]: next }358 }359 const oe = open?.emails[id]360 if (open && oe) {361 const next = overlayEmail(oe, patch)362 if (next !== oe) open = { ...open, emails: { ...open.emails, [id]: next } }363 }364 }365 if (emails !== s.emails || open !== s.open) S.set({ emails, open })366}367368/** Relit les messages touchés et corrige l'affichage (le serveur fait foi) ; un message disparu quitte l'écran. */369async function restoreRows(mb: string, client: Pick<JmapClient, "call">, ids: Id[]) {370 if (!ids.length) return371 const r = await client.call("Email/get", { ids, properties: SUMMARY_PROPS })372 if (S.get().mb !== mb) return373 const found = new Map((r.list as EmailSummary[]).map((e) => [e.id, e]))374 S.set((s) => {375 const emails = { ...s.emails }376 let open = s.open377 for (const id of ids) {378 const e = found.get(id)379 if (e && emails[id]) emails[id] = e380 else if (!e) delete emails[id]381 if (e && open?.emails[id]) open = { ...open, emails: { ...open.emails, [id]: { ...open.emails[id], keywords: e.keywords, mailboxIds: e.mailboxIds } } }382 }383 return { emails, open }384 })385}386387/** Rejoue la file, boîte par boîte, dans l'ordre. @internal Exportée pour les tests. */388export async function replay(): Promise<void> {389 const user = currentUser()390 if (replaying || !bound || !active || !user || !isOnline()) return391 replaying = true392 let rejected = 0393 let superseded = 0394 let waitingForAccount = false395 try {396 const boxes = [...new Set(opsFor(state, user).map((o) => o.mb))]397 for (const mb of boxes) {398 if (!S.get().me?.mailboxes.some((m) => m.id === mb)) {399 // boîte retirée du compte entre-temps : ses actions n'ont plus d'objet400 commit(settleOps(state, opsFor(state, user, mb)))401 continue402 }403 const client = bound.client(mb)404 if (!client) {405 // le compte n'est pas connecté (serveur injoignable au démarrage) : on redemande la connexion, puis essai suivant406 waitingForAccount = true407 bound.reconnect?.(mb)408 continue409 }410 const ops = opsFor(state, user, mb)411 for (let i = 0; i < ops.length; i += 200) {412 const chunk = ops.slice(i, i + 200)413 const got = await client.call("Email/get", { ids: chunk.map((o) => o.id), properties: ["id", "keywords", "mailboxIds"] })414 if (currentUser() !== user || !active) return415 const server = new Map((got.list as (ServerEmail & { id: Id })[]).map((e) => [e.id, e]))416 const update: Record<Id, JmapPatch> = {}417 const refused = new Set<QueuedOp>()418 const lost = new Set<QueuedOp>()419 for (const op of chunk) {420 const r = resolveOp(op, server.get(op.id) ?? null)421 if (r.gone) refused.add(op)422 else if (Object.keys(r.send).length) update[op.id] = r.send423 if (!r.gone && r.conflicts.length) lost.add(op)424 }425 if (Object.keys(update).length) {426 const res = await client.call("Email/set", { update })427 if (currentUser() !== user || !active) return428 for (const id of Object.keys(res.notUpdated ?? {})) {429 const op = chunk.find((o) => o.id === id)430 if (op) refused.add(op)431 delete update[id]432 }433 }434 rejected += refused.size435 superseded += [...lost].filter((o) => !refused.has(o)).length436 const sent = new Map(Object.entries(update).map(([id, p]) => [`${mb}\n${id}`, p]))437 // d'abord la file (les correctifs en attente ne recouvrent plus l'affichage), puis la vérité du serveur438 // (une opération modifiée pendant l'envoi reste en file : sa base devient ce que le serveur vient d'accepter)439 commit(rebaseOps(settleOps(state, chunk), sent))440 await restoreRows(mb, client, chunk.map((o) => o.id)).catch(() => undefined)441 }442 await Promise.resolve(bound.refresh(mb)).catch(() => undefined)443 }444 attempt = waitingForAccount ? attempt + 1 : 0445 } catch (e) {446 if (e instanceof HttpError && e.status === 401) return // session perdue : la file part avec le cache local447 if (isTransportFailure(e)) attempt++448 else {449 // erreur de protocole inattendue : ces actions ne passeront jamais — retirées et signalées, l'affichage est relu450 const dropped = opsFor(state, user)451 rejected += dropped.length452 commit(settleOps(state, dropped))453 for (const mb of new Set(dropped.map((o) => o.mb))) void Promise.resolve(bound.refresh(mb)).catch(() => undefined)454 }455 } finally {456 replaying = false457 if (rejected) toast({ kind: "error", text: t("offline.rejected", { n: rejected }) })458 if (superseded) toast({ kind: "info", text: t("offline.superseded", { n: superseded }) })459 if (active && opsFor(state, user).length && isOnline()) schedule(backoffMs(Math.max(0, attempt - 1)))460 }461}462