Skip to content

The agent that grows with you

16.8 KB
Raw Blame
import type { UiPreferencesSnapshot, UiPreferencesWrite } from '../../../electron/ui-preferences'
import { markProvisionalPreference, onPersistenceEvent, previousValueOf, provisionalPreferenceKeys } from '../storage'

import { isSharedPreferenceKey } from './keys'
import { rebaseWrite } from './merge'
import { adoptOrphanedOutboxes, outboxTakenOver, readOutbox, saveOutbox, siblingPendingKeys, watchOutbox } from './outbox'

export type { UiPreferencesSnapshot, UiPreferencesWrite }

/** The host's door to the machine store: preload IPC natively, `/api/ui-preferences` in a browser. */
export interface UiPreferencesBridge {
  /** Native only: the store as main read it before this window painted. */
  snapshot?: null | UiPreferencesSnapshot
  read(): Promise<UiPreferencesSnapshot>
  write(payload: UiPreferencesWrite): Promise<UiPreferencesSnapshot>
  /** Pushes (native) or polls (browser) the store after another writer changed it. */
  onChanged?(callback: (snapshot: UiPreferencesSnapshot) => void): () => void
}

const FLUSH_DELAY_MS = 150
// The store generation this origin has joined (imported its own values into).
// Until then a key the store lacks is never removed here: it may be this
// client's data the store has not received yet, not a peer's deletion.
const JOINED_KEY = 'hermes:ui-preferences:generation'
const RETRY_DELAY_MS = 5000
const MAX_RETRY_DELAY_MS = 60_000

// The shared keys this window held before the app's module graph evaluated
// (`captureOwnPreferences`, run by boot.ts): this client's own data. Stores
// that persist their default the moment their module loads add keys after
// that, and a first-contact import must not offer those defaults as data, or
// a fresh browser's defaults would fill the store before the client that has
// real values (native Desktop's keybinds, themes) imports them.
let ownKeys: null | ReadonlySet<string> = null

/** Record this window's own shared keys; boot.ts calls it before anything loads. */
export function captureOwnPreferences(): void {
  const provisional = provisionalPreferenceKeys()

  ownKeys = new Set(localSharedKeys().filter(key => !provisional.has(key)))
}

/** Cache one store value here. A key the store lacks is removed only once
 *  this origin joined (`prune`), and never while its value here is
 *  provisional; a value the store has replaces a provisional one for good. */
function adopt(key: string, value: null | string, prune: boolean, live: boolean) {
  if (value === null && (!prune || provisionalPreferenceKeys().has(key))) {
    return
  }

  if (value !== null) {
    markProvisionalPreference(key, false)
  }

  const previous = readRaw(key)

  if (writeRaw(key, value) && live) {
    announce(key, previous, value)
  }
}

/** `mine`, a change made from `base`, rebased onto `current` (see merge.ts);
 *  the cache takes the result, announced, when it differs from `mine`. */
function rebaseLocal(key: string, base: null | string, current: null | string, mine: null | string): null | string {
  const rebased = rebaseWrite(base, current, mine)

  if (rebased !== mine && writeRaw(key, rebased)) {
    announce(key, mine, rebased)
  }

  return rebased
}

const generationOf = (snapshot: UiPreferencesSnapshot) => snapshot.generation ?? ''

/** True once this origin imported its values into the snapshot's generation. */
function hasJoined(snapshot: UiPreferencesSnapshot): boolean {
  return snapshot.exists && readRaw(JOINED_KEY) === generationOf(snapshot)
}

function localSharedKeys(): string[] {
  const keys: string[] = []

  try {
    for (let index = 0; index < window.localStorage.length; index += 1) {
      const key = window.localStorage.key(index)

      if (key && isSharedPreferenceKey(key)) {
        keys.push(key)
      }
    }
  } catch {
    // Restricted storage reads as empty.
  }

  return keys
}

function readRaw(key: string): null | string {
  try {
    return window.localStorage.getItem(key)
  } catch {
    return null
  }
}

/** Set one cached key to the store's value; true when localStorage changed. Raw on
 *  purpose: the choke point would echo it back up as a local write. */
function writeRaw(key: string, value: null | string): boolean {
  const previous = readRaw(key)

  if (previous === value) {
    return false
  }

  try {
    if (value === null) {
      window.localStorage.removeItem(key)
    } else {
      window.localStorage.setItem(key, value)
    }
  } catch {
    return false
  }

  return true
}

/**
 * Make this window's localStorage cache match the store, before any store
 * module has read it (`boot.ts` runs this ahead of the app's module graph).
 * A store that does not exist yet changes nothing (the sync seeds it from this
 * cache instead), and until this origin joined the store's generation a key
 * the store lacks is kept: the store may simply not have it yet. Every change
 * is announced, so anything already listening follows it.
 */
export function hydrateFromSnapshot(snapshot: null | undefined | UiPreferencesSnapshot): void {
  if (!snapshot?.exists) {
    return
  }

  const outbox = new Set([...readOutbox().values.keys(), ...siblingPendingKeys()])
  const prune = hasJoined(snapshot)

  for (const key of new Set([...localSharedKeys(), ...Object.keys(snapshot.values)])) {
    if (isSharedPreferenceKey(key) && !outbox.has(key)) {
      adopt(key, snapshot.values[key] ?? null, prune, true)
    }
  }
}

/** A write the store answered "no" to (HTTP 400 / validation), as opposed to
 *  one that could not reach it; only the latter is worth retrying. */
function isRefusal(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return /^400:|unsupported preference|unsupported value|store is full/.test(message)
}

function announce(key: string, oldValue: null | string, newValue: null | string) {
  // Existing cross-window listeners (theme, translucency, haptics, persistent
  // atoms) already follow `storage` events; a same-window apply fires one too.
  window.dispatchEvent(new StorageEvent('storage', { key, newValue, oldValue }))
}

/**
 * Keep this window's shared preferences and the machine store in step:
 * - first contact with a store generation (or with no store) imports this
 *   origin's existing values (`seed`: only keys the store lacks, so nothing is
 *   overwritten); until then no local key is removed for being absent there;
 * - a local change to a shared key is merged into the store per key, last
 *   write wins, debounced and retried while the store is unreachable;
 * - a change another window, tab or device made lands here live;
 * - a provisional value (a write marked `provisional`) never leaves this origin.
 */
export function startUiPreferencesSync(bridge: null | UiPreferencesBridge | undefined): () => void {
  if (!bridge) {
    return () => undefined
  }

  const known = new Map<string, null | string>()
  // Unsent changes and the cached value each was made on (kept in the outbox,
  // so a change carried over a reload or taken over from a closed tab is
  // rebased too), and what this window's stores last saw per key (read at
  // load, read again, or written): a store that never re-reads must not undo
  // the entries a newer value brought.
  const { bases: pendingBase, values: pending } = readOutbox()
  const loaded = new Map(localSharedKeys().map(key => [key, readRaw(key)]))
  const seen = new Map<string, null | string>()
  const seenOf = (key: string) => (seen.has(key) ? (seen.get(key) ?? null) : (loaded.get(key) ?? null))
  // Values the store refused, kept in this window until changed again.
  const refused = new Map<string, null | string>()
  let revision = -1
  let generation: null | string = null
  let flushTimer: ReturnType<typeof setTimeout> | null = null
  let stopped = false
  // Nothing is written until first contact: a write that created the store
  // ahead of the seed would make the seed see an existing store and skip the
  // rest of this window's values.
  let ready = false

  const apply = (snapshot: UiPreferencesSnapshot, { live }: { live: boolean }) => {
    // A replaced store (deleted, or corrupt and kept aside) starts a new
    // generation at a low revision: follow it rather than wait for the count.
    if (!snapshot.exists || (generationOf(snapshot) === generation && snapshot.revision < revision)) {
      return
    }

    revision = snapshot.revision
    generation = generationOf(snapshot)
    const prune = hasJoined(snapshot)

    if (prune) {
      // Joined: this window's cache mirrors the store, so all of it is data
      // worth re-importing should the store ever be replaced.
      ownKeys = null
    }

    const siblings = siblingPendingKeys()

    for (const key of new Set([...localSharedKeys(), ...Object.keys(snapshot.values), ...known.keys()])) {
      if (!isSharedPreferenceKey(key)) {
        continue
      }

      const value = snapshot.values[key] ?? null
      known.set(key, value)

      // A change made here and not yet stored outranks an older store value,
      // rebased onto it so the store's other entries survive; so does one a
      // sibling tab has not stored yet.
      if (rebasePending(key, value)) {
        save()
      } else if (!pending.has(key) && !siblings.has(key) && !(refused.has(key) && refused.get(key) === readRaw(key))) {
        adopt(key, value, prune, live)
      }
    }

    if (!prune && ready) {
      rejoin(snapshot)
    }
  }

  function rebasePending(key: string, current: null | string): boolean {
    if (!pending.has(key) || !pendingBase.has(key) || pendingBase.get(key) === current) {
      return false
    }

    pending.set(key, rebaseLocal(key, pendingBase.get(key) ?? null, current, pending.get(key) ?? null))
    pendingBase.set(key, current)

    return true
  }

  // Another tab took this tab's unsent changes over (this one was frozen past
  // the liveness bound) and may have sent newer ones since: drop them here,
  // never send or save them again, and follow the store instead.
  const takenOver = (): boolean => {
    if (pending.size === 0 || !outboxTakenOver()) {
      return false
    }

    pending.clear()
    pendingBase.clear()

    if (ready && !stopped) {
      void bridge.read().then(
        snapshot => !stopped && apply(snapshot, { live: true }),
        () => undefined
      )
    }

    return true
  }

  const save = (options: { closed?: boolean } = {}) => {
    if (!takenOver()) {
      saveOutbox(pending, { bases: pendingBase, ...options })
    }
  }

  let writing = false
  let writeDelay = RETRY_DELAY_MS

  const schedule = (delay: number) => {
    if (flushTimer === null && !writing && ready && !stopped) {
      flushTimer = setTimeout(() => void flush(), delay)
    }
  }

  // One write in flight at a time: two independent requests could commit out
  // of order, and the older batch's later revision would win.
  const flush = async () => {
    flushTimer = null

    if (takenOver() || pending.size === 0) {
      return
    }

    const batch = new Map(pending)
    let retryIn = FLUSH_DELAY_MS
    writing = true

    try {
      const snapshot = await bridge.write({ values: Object.fromEntries(batch) })

      settle(batch)
      writeDelay = RETRY_DELAY_MS
      apply(snapshot, { live: true })
    } catch (error) {
      if (isRefusal(error)) {
        // The store refused this batch outright (oversized value, full store):
        // it stays in this window only, and later changes are not held behind it.
        console.warn('[ui-preferences] the machine store refused these preferences', [...batch.keys()], error)
        batch.forEach((value, key) => refused.set(key, value))
        settle(batch)
      } else {
        retryIn = writeDelay
        writeDelay = Math.min(writeDelay * 2, MAX_RETRY_DELAY_MS)
      }
    } finally {
      writing = false
    }

    if (pending.size > 0) {
      schedule(retryIn)
    }
  }

  const settle = (batch: Map<string, null | string>) => {
    for (const [key, value] of batch) {
      if (pending.get(key) === value) {
        pending.delete(key)
        pendingBase.delete(key)
      }
    }

    save()
  }

  const stopListening = onPersistenceEvent(event => {
    if (!isSharedPreferenceKey(event.key)) {
      return
    }

    if (event.op === 'read') {
      seen.set(event.key, event.value)

      return
    }

    const base = seenOf(event.key)
    seen.set(event.key, event.value)

    // A provisional value (storage.ts keeps the mark) never leaves this origin.
    if (event.provisional) {
      return
    }

    if (!pending.has(event.key) && known.has(event.key) && known.get(event.key) === event.value) {
      return
    }

    takenOver()
    const current = previousValueOf(event) ?? null
    const value = rebaseLocal(event.key, base, current, event.value)

    if (!pendingBase.has(event.key)) {
      pendingBase.set(event.key, current)
    }

    refused.delete(event.key)
    pending.set(event.key, value)
    store()
  })

  // A tab that closed with changes unsent left its outbox: take it over (its
  // values are already this origin's cache). This tab's own outbox stays
  // stamped as alive while it holds changes; a page going away sends at once.
  const outbox = watchOutbox({
    hasPending: () => pending.size > 0 && !stopped,
    onLeave: () => {
      save()

      if (flushTimer !== null) {
        clearTimeout(flushTimer)
        flushTimer = null
      }

      if (ready && !writing) {
        void flush()
      }
    },
    onOrphans: () => {
      takenOver()
      const adopted = adoptOrphanedOutboxes()

      for (const [key, value] of adopted.values) {
        if (!pending.has(key)) {
          pending.set(key, value)

          if (adopted.bases.has(key)) {
            pendingBase.set(key, adopted.bases.get(key) ?? null)
          }

          if (ready && known.has(key)) {
            rebasePending(key, known.get(key) ?? null)
          }
        }
      }

      store()
    },
    onReturn: () => save()
  })

  function store() {
    save()
    outbox.touch()
    schedule(FLUSH_DELAY_MS)
  }

  outbox.touch()

  // First contact with a generation: add this origin's values the store lacks.
  const join = async (snapshot: UiPreferencesSnapshot) => {
    if (hasJoined(snapshot)) {
      return snapshot
    }

    const provisional = provisionalPreferenceKeys()

    const values = Object.fromEntries(
      localSharedKeys()
        .filter(key => (!ownKeys || ownKeys.has(key)) && !provisional.has(key))
        .map(key => [key, readRaw(key)])
    )

    // Nothing to import: an existing store is joined as it is, and no store is
    // created from nothing.
    const joinedSnapshot = Object.keys(values).length > 0 ? await bridge.write({ seed: true, values }) : snapshot

    if (joinedSnapshot.exists) {
      writeRaw(JOINED_KEY, generationOf(joinedSnapshot))
    }

    return joinedSnapshot
  }

  let joining = false
  let joinRefused = false

  // A live snapshot from a generation this origin has not joined (the store
  // was replaced while this window was open): import, then follow it.
  function rejoin(snapshot: UiPreferencesSnapshot) {
    if (joining || joinRefused || stopped) {
      return
    }

    joining = true
    join(snapshot).then(
      joinedSnapshot => {
        joining = false

        if (!stopped) {
          apply(joinedSnapshot, { live: true })
        }
      },
      error => {
        joining = false
        joinRefused = isRefusal(error)
      }
    )
  }

  let connectTimer: ReturnType<typeof setTimeout> | null = null
  let connectDelay = RETRY_DELAY_MS

  const connect = (initial: null | UiPreferencesSnapshot | undefined) => {
    connectTimer = null

    void (initial ? Promise.resolve(initial) : bridge.read())
      .then(join)
      .then(snapshot => {
        if (stopped) {
          return
        }

        ready = true
        apply(snapshot, { live: true })
        schedule(FLUSH_DELAY_MS)
      })
      .catch(error => {
        if (stopped) {
          return
        }

        if (isRefusal(error)) {
          // The store cannot take this origin's import (full): follow it
          // without removing anything here, and try the import on next load.
          joinRefused = true
          ready = true
          void bridge.read().then(
            snapshot => apply(snapshot, { live: true }),
            () => undefined
          )
          schedule(FLUSH_DELAY_MS)
        } else {
          // Unreachable store: this window keeps its cached values and local
          // changes stay pending until first contact succeeds.
          connectTimer = setTimeout(() => connect(null), connectDelay)
          connectDelay = Math.min(connectDelay * 2, MAX_RETRY_DELAY_MS)
        }
      })
  }

  connect(bridge.snapshot)

  const stopChanges = bridge.onChanged?.(snapshot => apply(snapshot, { live: true })) ?? (() => undefined)

  return () => {
    stopped = true
    stopListening()
    stopChanges()
    outbox.stop()
    // Nothing here sends it any more: the next tab adopts what is unsent.
    save({ closed: true })

    if (flushTimer !== null) {
      clearTimeout(flushTimer)
    }

    if (connectTimer !== null) {
      clearTimeout(connectTimer)
    }
  }
}