SPB Git

Repository Public

offline.ts 20.6 KB 462 lines typescript

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
Files main
Menu

Theme