Học từ web lớn #37: Cache client theo version (Similarweb, Telegram, Udemy)

/**
 * Cache dữ liệu khởi động (từ điển i18n, settings, user data…) trong IndexedDB.
 * Ý tưởng từ CacheService của Similarweb Pro:
 * - Dữ liệu nặng có "version" riêng: mỗi lần mở app chỉ hỏi server version (rất nhẹ),
 *   khớp với bản đã lưu thì dùng luôn, lệch thì tải bản mới rồi ghi đè.
 * - Dữ liệu không có version: trả bản cũ ngay, tải bản mới ở nền (stale-while-revalidate).
 * - Không có IndexedDB (một số chế độ riêng tư, webview cũ) thì cứ gọi mạng như bình thường.
 */

export interface CacheRecord<T = unknown> {
  key: string;
  /** null với dữ liệu không có version (stale-while-revalidate) */
  version: string | null;
  value: T;
  savedAt: number;
}

export interface KVStore {
  get<T>(key: string): Promise<CacheRecord<T> | undefined>;
  put<T>(record: CacheRecord<T>): Promise<void>;
  delete(key: string): Promise<void>;
  clear(): Promise<void>;
  keys(): Promise<string[]>;
  close(): void;
}

const STORE = 'cache';

export function hasIndexedDB() {
  try {
    return typeof indexedDB !== 'undefined' && indexedDB !== null;
  } catch {
    // Firefox cũ ném SecurityError khi chặn cookie mà chỉ đọc biến `indexedDB`
    return false;
  }
}

function promisify<T>(req: IDBRequest<T>): Promise<T> {
  return new Promise((resolve, reject) => {
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

function transactionDone(tx: IDBTransaction): Promise<void> {
  return new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error);
    tx.onabort = () => reject(tx.error ?? new DOMException('Transaction aborted', 'AbortError'));
  });
}

/**
 * Mở một object store dạng key-value. `dbVersion` là version của SCHEMA (cấu trúc store),
 * khác với version của dữ liệu bên trong từng bản ghi.
 */
export function openKV(dbName: string, dbVersion = 1, blockedTimeout = 3000): Promise<KVStore> {
  return new Promise((resolve, reject) => {
    let settled = false;
    const open = indexedDB.open(dbName, dbVersion);

    open.onupgradeneeded = () => {
      const db = open.result;
      if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE, { keyPath: 'key' });
    };

    // Tab khác còn giữ kết nối tới schema cũ thì lệnh nâng cấp bị "blocked" và chờ vô hạn.
    // Đừng để app treo ở màn hình tải: hết giờ thì báo lỗi, phía gọi sẽ đi mạng.
    const timer = setTimeout(() => {
      settled = true;
      reject(new Error('IndexedDB đang bị tab khác chặn nâng cấp'));
    }, blockedTimeout);

    open.onerror = () => {
      clearTimeout(timer);
      if (!settled) reject(open.error);
      settled = true;
    };

    open.onsuccess = () => {
      clearTimeout(timer);
      const db = open.result;
      if (settled) {
        db.close(); // đã báo lỗi vì quá giờ, đừng để kết nối mồ côi
        return;
      }
      settled = true;
      // Chiều ngược lại: tab khác (bản app mới hơn) cần nâng schema thì ta nhả kết nối ra.
      db.onversionchange = () => db.close();

      const store = (mode: IDBTransactionMode) => db.transaction(STORE, mode).objectStore(STORE);
      const write = async (fn: (s: IDBObjectStore) => void) => {
        const tx = db.transaction(STORE, 'readwrite');
        fn(tx.objectStore(STORE));
        await transactionDone(tx);
      };

      resolve({
        get: <T>(key: string) => promisify(store('readonly').get(key)) as Promise<CacheRecord<T> | undefined>,
        put: (record) => write((s) => s.put(record)),
        delete: (key) => write((s) => s.delete(key)),
        clear: () => write((s) => s.clear()),
        keys: async () => (await promisify(store('readonly').getAllKeys())).map(String),
        close: () => db.close(),
      });
    };
  });
}

/** Bản ghi có đúng hình dạng mong đợi không (Similarweb cũng kiểm tra kỹ trước khi tin cache). */
function isUsable<T>(record: CacheRecord<T> | undefined): record is CacheRecord<T> {
  return typeof record === 'object' && record !== null && 'value' in record && record.value !== undefined;
}

export type VersionedOutcome = 'hit' | 'miss' | 'stale-version' | 'bypass' | 'no-idb';

export interface VersionedSource<T> {
  key: string;
  /** gọi endpoint nhẹ chỉ trả version, vd { version: '2026-10-27.3' } */
  fetchVersion: () => Promise<string>;
  /** tải bản đầy đủ của đúng version đó */
  fetchData: (version: string) => Promise<T>;
}

export async function getVersioned<T>(
  kv: KVStore | null,
  source: VersionedSource<T>,
  { bypass = false } = {},
): Promise<{ value: T; version: string; outcome: VersionedOutcome }> {
  const version = await source.fetchVersion();
  if (!kv) return { value: await source.fetchData(version), version, outcome: 'no-idb' };

  let cached: CacheRecord<T> | undefined;
  if (!bypass) {
    cached = await kv.get<T>(source.key).catch(() => undefined);
    if (isUsable(cached) && cached.version === version) {
      return { value: cached.value, version, outcome: 'hit' };
    }
  }

  const value = await source.fetchData(version);
  // Version và dữ liệu nằm chung MỘT bản ghi: không bao giờ có cảnh version mới đi với dữ liệu cũ.
  // Ghi lỗi (hết quota…) thì bỏ qua: lần tải này vẫn thành công, lần sau tải lại.
  await kv.put<T>({ key: source.key, version, value, savedAt: Date.now() }).catch(() => undefined);
  return { value, version, outcome: bypass ? 'bypass' : cached ? 'stale-version' : 'miss' };
}

/**
 * Trả bản đã lưu ngay lập tức (nếu có), đồng thời tải bản mới ở nền.
 * Bản mới về thì ghi vào cache và gọi `onFresh` để giao diện cập nhật.
 */
export async function staleWhileRevalidate<T>(
  kv: KVStore | null,
  key: string,
  fetchData: () => Promise<T>,
  onFresh: (value: T) => void,
  { bypass = false } = {},
): Promise<{ value: T; fromCache: boolean }> {
  const cached = kv && !bypass ? await kv.get<T>(key).catch(() => undefined) : undefined;

  const refresh = async () => {
    const value = await fetchData();
    await kv?.put<T>({ key, version: null, value, savedAt: Date.now() }).catch(() => undefined);
    return value;
  };

  if (isUsable(cached)) {
    refresh().then(onFresh, () => {
      /* mạng lỗi: vẫn dùng bản cũ, lần mở sau thử lại */
    });
    return { value: cached.value, fromCache: true };
  }
  return { value: await refresh(), fromCache: false };
}

/**
 * Cửa thoát hiểm khi debug/hỗ trợ khách hàng: thêm `?clear-cache` vào URL để bỏ qua cache
 * một lần. Đọc xong thì xoá tham số khỏi URL (giữ nguyên hash) để F5 lần sau không bỏ qua nữa.
 */
export function consumeBypassFlag(param = 'clear-cache'): boolean {
  const params = new URLSearchParams(location.search);
  if (!params.has(param)) return false;
  params.delete(param);
  const search = params.toString();
  history.replaceState(history.state, '', `${location.pathname}${search ? `?${search}` : ''}${location.hash}`);
  return true;
}

/**
 * Dùng Cache Storage (`caches`) làm kho key-value ngay từ trang chính, không cần service worker.
 * Ý tưởng từ src/util/cacheApi.ts của Telegram Web: lưu sticker, ảnh nền, gói ngôn ngữ.
 * Hợp với dữ liệu nhị phân lớn (Blob) hơn localStorage (chỉ lưu chuỗi, vài MB, chặn main thread).
 */

export type CacheValueType = 'text' | 'json' | 'blob';

function hasCacheStorage() {
  try {
    return typeof caches !== 'undefined';
  } catch {
    return false;
  }
}

/**
 * Cache API chỉ nhận Request http(s). Key kiểu "sticker:123" sẽ bị hiểu là URL có scheme "sticker"
 * và bị từ chối. Telegram thay ':' bằng '_' (nên "a:b" và "a_b" đụng nhau); ở đây mã hoá cả key
 * vào một đường dẫn giả cùng origin.
 */
function toRequest(key: string) {
  return new Request(`${self.location.origin}/__kv__/${encodeURIComponent(key)}`);
}

export async function cacheGet(cacheName: string, key: string, type: 'text'): Promise<string | undefined>;
export async function cacheGet<T = unknown>(cacheName: string, key: string, type: 'json'): Promise<T | undefined>;
export async function cacheGet(cacheName: string, key: string, type: 'blob'): Promise<Blob | undefined>;
export async function cacheGet(cacheName: string, key: string, type: CacheValueType) {
  if (!hasCacheStorage()) return undefined;
  try {
    const cache = await caches.open(cacheName);
    const response = await cache.match(toRequest(key));
    if (!response) return undefined;
    if (type === 'text') return await response.text();
    if (type === 'json') return await response.json();
    const blob = await response.blob();
    // iOS Safari có lúc trả Blob mất `type`; lấy lại từ header đã lưu (Telegram cũng vá như vậy)
    if (!blob.type) {
      const contentType = response.headers.get('Content-Type');
      if (contentType) return new Blob([blob], { type: contentType });
    }
    return blob;
  } catch (error) {
    console.warn('cacheGet', error);
    return undefined;
  }
}

export async function cacheSet(cacheName: string, key: string, data: string | Blob | object): Promise<boolean> {
  if (!hasCacheStorage()) return false;
  try {
    let response: Response;
    if (data instanceof Blob) {
      // ghi rõ Content-Type, đừng trông vào việc trình duyệt tự suy ra từ blob.type
      response = new Response(data, { headers: { 'Content-Type': data.type || 'application/octet-stream' } });
    } else if (typeof data === 'string') {
      response = new Response(data, { headers: { 'Content-Type': 'text/plain;charset=utf-8' } });
    } else {
      response = new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } });
    }
    const cache = await caches.open(cacheName);
    await cache.put(toRequest(key), response);
    return true;
  } catch (error) {
    // QuotaExceededError, chế độ riêng tư… cache chỉ là phần phụ, đừng làm hỏng tính năng chính
    console.warn('cacheSet', error);
    return false;
  }
}

export async function cacheDelete(cacheName: string) {
  if (!hasCacheStorage()) return false;
  return caches.delete(cacheName).catch(() => false);
}

/**
 * Đặt version vào TÊN cache ("lang-packs-v5"): đổi format dữ liệu thì đổi tên, rồi xoá mọi cache
 * cùng tiền tố mà không phải tên hiện tại. Gọi lúc khởi động app.
 * (Telegram chỉ dọn các bản cũ khi người dùng đăng xuất, nên bản cũ nằm lại tới lúc đó.)
 */
export async function cleanupOldCaches(prefix: string, current: string): Promise<string[]> {
  if (!hasCacheStorage()) return [];
  const names = await caches.keys();
  const stale = names.filter((name) => name.startsWith(prefix) && name !== current);
  await Promise.all(stale.map((name) => caches.delete(name)));
  return stale;
}

/**
 * localStorage có hạn dùng (TTL) cho từng key, an toàn khi nhiều tab cùng ghi.
 * Ý tưởng từ ud-expiring-local-storage(-with-key-ttls) của Udemy:
 * - mỗi mục lưu kèm thời điểm hết hạn, đọc thấy hết hạn thì coi như không có;
 * - giới hạn số mục để một namespace không phình mãi;
 * - TRƯỚC khi ghi thì đọc lại bản mới nhất trong localStorage, để không đè mất thứ tab khác vừa ghi.
 */

interface Entry {
  v: unknown;
  /** thời điểm hết hạn, ms */
  exp: number;
}

type Data = Record<string, Entry>;

export interface ExpiringStorageOptions {
  /** TTL mặc định cho mỗi key, ms */
  ttl: number;
  maxItems?: number;
  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
  now?: () => number;
}

/** localStorage có thể ném lỗi ngay khi truy cập (Safari riêng tư đời cũ, cookie bị chặn…). */
export function safeLocalStorage(): Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {
  try {
    const probe = '__probe__';
    localStorage.setItem(probe, '1');
    localStorage.removeItem(probe);
    return localStorage;
  } catch {
    const memory = new Map<string, string>();
    return {
      getItem: (k) => memory.get(k) ?? null,
      setItem: (k, v) => void memory.set(k, v),
      removeItem: (k) => void memory.delete(k),
    };
  }
}

export function createExpiringStorage(
  namespace: string,
  { ttl, maxItems = 1000, storage = safeLocalStorage(), now = Date.now }: ExpiringStorageOptions,
) {
  const storageKey = `expiring:${namespace}`;

  // Luôn đọc từ storage, không giữ bản sao trong bộ nhớ: bản sao sẽ cũ đi ngay khi tab khác ghi.
  // Đổi lại mỗi lần đọc là một lần JSON.parse; namespace nhỏ thì không đáng kể.
  const read = (): Data => {
    try {
      const raw = storage.getItem(storageKey);
      const parsed: unknown = raw ? JSON.parse(raw) : {};
      return parsed && typeof parsed === 'object' ? (parsed as Data) : {};
    } catch {
      return {}; // JSON hỏng (ai đó sửa tay, bản app cũ…): bắt đầu lại
    }
  };

  const write = (data: Data) => {
    try {
      if (Object.keys(data).length === 0) storage.removeItem(storageKey);
      else storage.setItem(storageKey, JSON.stringify(data));
      return true;
    } catch {
      return false; // QuotaExceededError: không làm hỏng luồng chính
    }
  };

  const prune = (data: Data) => {
    const t = now();
    for (const key of Object.keys(data)) if (!(data[key]?.exp > t)) delete data[key];
    return data;
  };

  return {
    get<T = unknown>(key: string): T | null {
      const entry = read()[key];
      if (!entry) return null;
      if (entry.exp <= now()) {
        this.delete(key);
        return null;
      }
      return entry.v as T;
    },

    /** Trả về false nếu không ghi được (hết quota). */
    set(key: string, value: unknown, itemTtl = ttl): boolean {
      const data = prune(read()); // đọc lại NGAY TRƯỚC khi ghi
      if (!(key in data) && Object.keys(data).length >= maxItems) {
        // Udemy ném lỗi khi đầy; ở đây đẩy mục sắp hết hạn nhất ra để chỗ cho mục mới
        const oldest = Object.keys(data).reduce((a, b) => (data[a].exp <= data[b].exp ? a : b));
        delete data[oldest];
      }
      data[key] = { v: value, exp: now() + itemTtl };
      return write(data);
    },

    delete(key: string) {
      const data = read();
      if (key in data) {
        delete data[key];
        write(data);
      }
    },

    clear() {
      storage.removeItem(storageKey);
    },

    /** Dọn mục hết hạn, nên gọi một lần sau khi app khởi động xong. */
    sweep() {
      const data = read();
      const before = Object.keys(data).length;
      prune(data);
      if (Object.keys(data).length !== before) write(data);
      return before - Object.keys(data).length;
    },

    /** Dùng cho debug/demo: mọi mục còn hạn kèm số ms còn lại. */
    entries() {
      const t = now();
      return Object.entries(prune(read())).map(([key, e]) => ({ key, value: e.v, remaining: e.exp - t }));
    },
  };
}

export type ExpiringStorage = ReturnType<typeof createExpiringStorage>;