@itd-api/cache 0.0.1 → 0.0.2

package/README.md

@@ -70,9 +70,10 @@ await itd.posts.get(postId, { cache: 'no-store' });
 
 После успешной мутации плагин удаляет связанные читающие маршруты. Например, реакция на
 пост сбрасывает кэш постов и статистики, но не затрагивает профили, файлы и настройки
-платформы. Маршруты с общими данными инвалидируются во всех разделах экземпляра: изменение
-поста одним аккаунтом должно быть видно остальным. Персональные настройки, уведомления и
-сессии затрагивают только свой раздел.
+платформы. Маршруты с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
+поста одним аккаунтом должно быть видно остальным. Персональные настройки и уведомления
+инвалидируются у всех копий клиента с тем же пользователем. Изменение сессий сбрасывает все
+варианты `auth.sessions` этого аккаунта, включая варианты других сессий.
 
 Известные запросы без зависимостей, включая telemetry и создание жалобы, кэш не меняют.
 
@@ -102,9 +103,13 @@ detachCache();
 stream.disconnect();
 ```
 
-Привязка сразу очищает `notifications.list` и `notifications.count`. Новое уведомление
-сбрасывает оба маршрута, событие `unreadCount` — счётчик. Другие разделы кэша поток не
-изменяет.
+Привязка сразу очищает `notifications.list` и `notifications.count` аккаунта, который
+создал поток. Новое уведомление сбрасывает оба маршрута во всех копиях клиента с тем же
+пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные маршруты
+поток не изменяет.
+
+У стороннего realtime-объекта без доступных идентификатора пользователя и базового URL
+используется безопасный fallback: маршруты уведомлений инвалидируются во всех аккаунтах.
 
 ## Несколько клиентов
 
@@ -125,21 +130,26 @@ clientB.use(shared);
 // либо accounts.use(shared)
 ```
 
-Каждая установка получает собственный раздел. Ответы и одновременные запросы разных
-клиентов не пересекаются: даже публичные профили и посты содержат персонализированные
-поля `isLiked`, `isFollowing` и `isReposted`. Инвалидация общей сущности применяется ко
-всем разделам, а персонального состояния — только к клиенту, который его изменил.
+Копии клиента с одинаковыми базовым URL и пользователем используют общий раздел: готовые
+ответы и одновременные запросы между ними объединяются. Это безопасно для персонализированных
+полей `isLiked`, `isFollowing` и `isReposted`, потому что их значения принадлежат аккаунту,
+а не конкретному access token.
+
+Разные пользователи изолированы. Только `auth.sessions` дополнительно разделяется по сессии,
+поскольку ответ отмечает текущую серверную сессию. Если идентификаторов пользователя или
+сессии в токене нет, плагин использует безопасный уникальный раздел установки и ничего между
+копиями не объединяет.
 
-`maxEntries` ограничивает весь экземпляр `shared`, а `clear()`, `invalidate()` и
-`attachRealtime()` управляют всеми его разделами. При `setSession()`, входе или выходе
-раздел клиента меняется автоматически.
+`maxEntries` ограничивает весь экземпляр `shared`, а `clear()` и `invalidate()` управляют
+всеми его разделами. `attachRealtime()` затрагивает аккаунт создавшего поток клиента.
+Смена сессии сохраняет общий кэш, смена пользователя автоматически выбирает другой раздел.
 
 ## Ключ
 
 В ключ входят:
 
 - имя маршрута, HTTP-метод и path;
-- непрозрачная область клиента и его текущей сессии;
+- базовый URL и идентификатор пользователя; для `auth.sessions` также идентификатор сессии;
 - `service` или разовый `baseUrl`;
 - query и JSON-body;
 - режим `raw`, `skipAuth` и опции других плагинов, влияющие на ответ.

package/dist/index.cjs

@@ -174,7 +174,7 @@ var CACHE_MUTATIONS = Object.freeze([
     method: "DELETE",
     path: /^\/api\/v1\/auth\/sessions(?:\/[^/]+)?$/,
     invalidates: ["auth.sessions"],
-    scope: "installation"
+    scope: "account"
   },
   // Посты и комментарии.
   { method: "POST", path: /^\/api\/posts$/, invalidates: POST_CONTENT },
@@ -216,13 +216,13 @@ var CACHE_MUTATIONS = Object.freeze([
     method: "POST",
     path: /^\/api\/notifications\/(?:[^/]+\/read|read-batch|read-all)$/,
     invalidates: NOTIFICATIONS,
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "PUT",
     path: /^\/api\/notifications\/settings$/,
     invalidates: ["notifications.getSettings"],
-    scope: "installation"
+    scope: "account"
   },
   // Файлы и настройки аккаунта.
   { method: "POST", path: /^\/api\/files\/upload$/, invalidates: NOTHING },
@@ -235,37 +235,37 @@ var CACHE_MUTATIONS = Object.freeze([
     method: "POST",
     path: /^\/api\/verification\/submit$/,
     invalidates: ["verification.status"],
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "POST",
     path: /^\/api\/v1\/subscription\/pay$/,
     invalidates: SUBSCRIPTION,
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "POST",
     path: /^\/api\/v1\/subscription\/auto-renewal$/,
     invalidates: SUBSCRIPTION,
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "POST",
     path: /^\/api\/v1\/subscription\/bind-card$/,
     invalidates: SUBSCRIPTION,
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "POST",
     path: /^\/api\/v1\/subscription\/methods\/[^/]+\/default$/,
     invalidates: SUBSCRIPTION,
-    scope: "installation"
+    scope: "account"
   },
   {
     method: "DELETE",
     path: /^\/api\/v1\/subscription\/methods\/[^/]+$/,
     invalidates: SUBSCRIPTION,
-    scope: "installation"
+    scope: "account"
   },
   // Эти запросы не меняют ни один доступный для кэширования ответ.
   { method: "POST", path: /^\/api\/reports$/, invalidates: NOTHING },
@@ -441,8 +441,16 @@ function cacheRoute(method, path) {
 }
 
 // src/plugin.ts
+var CacheModes = Object.freeze({
+  /** Отдать свежий кэш, иначе выполнить запрос и сохранить ответ. */
+  Default: "default",
+  /** Пропустить сохранённое значение, выполнить запрос и перезаписать кэш. */
+  Reload: "reload",
+  /** Не читать и не писать кэш для этого запроса. */
+  NoStore: "no-store"
+});
 var DEFAULT_MAX_ENTRIES = 500;
-var CACHE_MODES = /* @__PURE__ */ new Set(["default", "reload", "no-store"]);
+var CACHE_MODES = new Set(Object.values(CacheModes));
 function assertPositive(value, name, integer = false) {
   if (!Number.isFinite(value) || value <= 0 || integer && !Number.isInteger(value)) {
     throw new CacheError(
@@ -481,10 +489,10 @@ function cloneValue(value) {
   }
 }
 function cacheMode(request) {
-  const mode = request.cache ?? "default";
+  const mode = request.cache ?? CacheModes.Default;
   if (!CACHE_MODES.has(mode)) {
     throw new CacheError(
-      `cache \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C 'default', 'reload' \u0438\u043B\u0438 'no-store', \u043F\u043E\u043B\u0443\u0447\u0435\u043D\u043E: ${String(mode)}`
+      `cache \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C '${CacheModes.Default}', '${CacheModes.Reload}' \u0438\u043B\u0438 '${CacheModes.NoStore}', \u043F\u043E\u043B\u0443\u0447\u0435\u043D\u043E: ${String(mode)}`
     );
   }
   return mode;
@@ -499,12 +507,12 @@ function cache(options) {
   });
   const pending = /* @__PURE__ */ new Map();
   const routeGenerations = /* @__PURE__ */ new Map();
-  const installationGenerations = /* @__PURE__ */ new Map();
-  const installationRouteGenerations = /* @__PURE__ */ new Map();
+  const scopeGenerations = /* @__PURE__ */ new Map();
+  const scopeRouteGenerations = /* @__PURE__ */ new Map();
   const keyStates = /* @__PURE__ */ new Map();
   let generation = 0;
   let installationSequence = 0;
-  const installationRouteKey = (installation, route) => `${installation}:${route}`;
+  const scopeRouteKey = (accountScope, route) => JSON.stringify([accountScope, route]);
   const clear = () => {
     generation += 1;
     values.clear();
@@ -527,47 +535,48 @@ function cache(options) {
       if (selected.has(entry.route)) pending.delete(key);
     }
   };
-  const clearInstallation = (installation) => {
-    installationGenerations.set(installation, (installationGenerations.get(installation) ?? 0) + 1);
+  const clearScope = (accountScope) => {
+    scopeGenerations.set(accountScope, (scopeGenerations.get(accountScope) ?? 0) + 1);
     for (const [key, entry] of values.entries()) {
-      if (entry.installation === installation) values.delete(key);
+      if (entry.accountScope === accountScope) values.delete(key);
     }
     for (const [key, entry] of pending) {
-      if (entry.installation === installation) pending.delete(key);
+      if (entry.accountScope === accountScope) pending.delete(key);
     }
   };
-  const invalidateInstallation = (installation, routes) => {
+  const invalidateScope = (accountScope, routes) => {
     if (routes.length === 0) return;
     const selected = new Set(routes);
     for (const route of selected) {
-      const key = installationRouteKey(installation, route);
-      installationRouteGenerations.set(key, (installationRouteGenerations.get(key) ?? 0) + 1);
+      const key = scopeRouteKey(accountScope, route);
+      scopeRouteGenerations.set(key, (scopeRouteGenerations.get(key) ?? 0) + 1);
     }
     for (const [key, entry] of values.entries()) {
-      if (entry.installation === installation && selected.has(entry.route)) values.delete(key);
+      if (entry.accountScope === accountScope && selected.has(entry.route)) values.delete(key);
     }
     for (const [key, entry] of pending) {
-      if (entry.installation === installation && selected.has(entry.route)) pending.delete(key);
+      if (entry.accountScope === accountScope && selected.has(entry.route)) pending.delete(key);
     }
   };
-  const applyMutation = (installation, mutation) => {
+  const applyMutation = (accountScope, mutation) => {
     if (mutation.invalidates === "all") {
-      clearInstallation(installation);
-    } else if (mutation.scope === "installation") {
-      invalidateInstallation(installation, mutation.invalidates);
+      clearScope(accountScope);
+    } else if (mutation.scope === "account") {
+      invalidateScope(accountScope, mutation.invalidates);
     } else {
       invalidate(...mutation.invalidates);
     }
   };
-  const createTransformer = (installation, getAuthScope) => {
-    let observedAuthScope;
-    const resolveScope = () => {
-      const authScope = getAuthScope ? getAuthScope() : "default";
-      if (observedAuthScope !== void 0 && observedAuthScope !== authScope) {
-        clearInstallation(installation);
-      }
-      observedAuthScope = authScope;
-      return JSON.stringify([installation, authScope]);
+  const createTransformer = (installation, baseUrl, getAuthIdentity, getAuthScope) => {
+    const fallbackAuthScope = JSON.stringify([baseUrl, `installation:${installation}`]);
+    const resolveIdentity = async () => {
+      const identity = await getAuthIdentity?.();
+      const accountScope = identity?.userId ? JSON.stringify([baseUrl, identity.userId]) : getAuthScope ? JSON.stringify([baseUrl, getAuthScope()]) : fallbackAuthScope;
+      const sessionScope = identity?.userId && identity.sessionId ? JSON.stringify([baseUrl, identity.userId, identity.sessionId]) : JSON.stringify([
+        accountScope,
+        getAuthScope ? getAuthScope() : `installation:${installation}`
+      ]);
+      return { accountScope, sessionScope };
     };
     return async (rawRequest, next) => {
       const request = rawRequest;
@@ -575,27 +584,39 @@ function cache(options) {
       const method = request.method.toUpperCase();
       const isRead = route !== void 0 || method === "GET" || method === "HEAD";
       if (!isRead) {
-        const result = await next(request);
         const mutation = cacheMutation(method, request.path);
-        if (mutation) applyMutation(installation, mutation);
-        else clear();
+        const startedIdentity = mutation ? await resolveIdentity() : void 0;
+        const result = await next(request);
+        if (mutation && startedIdentity) {
+          applyMutation(startedIdentity.accountScope, mutation);
+          const currentIdentity = await resolveIdentity();
+          if (currentIdentity.accountScope !== startedIdentity.accountScope && (mutation.invalidates === "all" || mutation.scope === "account")) {
+            applyMutation(currentIdentity.accountScope, mutation);
+          }
+        } else {
+          clear();
+        }
         return result;
       }
       if (!route || !config.routes.has(route.id)) return next(request);
       const mode = cacheMode(request);
-      if (mode === "no-store") return next(request);
+      if (mode === CacheModes.NoStore) return next(request);
       const unscopedKey = buildCacheKey(route.id, request);
       if (unscopedKey === void 0) return next(request);
-      const scope = resolveScope();
+      const identity = await resolveIdentity();
+      const scope = route.id === "auth.sessions" ? identity.sessionScope : identity.accountScope;
       const key = JSON.stringify([scope, unscopedKey]);
-      if (mode === "reload") {
-        const state = keyStates.get(key) ?? { active: 0, generation: 0 };
+      if (mode === CacheModes.Reload) {
+        const state = keyStates.get(key) ?? {
+          active: 0,
+          generation: 0
+        };
         state.generation += 1;
         keyStates.set(key, state);
         values.delete(key);
         pending.delete(key);
       }
-      if (mode === "default") {
+      if (mode === CacheModes.Default) {
         const hit = values.get(key);
         if (hit) {
           const cloned = cloneValue(hit.value);
@@ -609,11 +630,14 @@ function cache(options) {
         }
       }
       const startedGeneration = generation;
-      const startedInstallationGeneration = installationGenerations.get(installation) ?? 0;
+      const startedScopeGeneration = scopeGenerations.get(identity.accountScope) ?? 0;
       const startedRouteGeneration = routeGenerations.get(route.id) ?? 0;
-      const scopedRouteKey = installationRouteKey(installation, route.id);
-      const startedInstallationRouteGeneration = installationRouteGenerations.get(scopedRouteKey) ?? 0;
-      const keyState = keyStates.get(key) ?? { active: 0, generation: 0 };
+      const scopedRouteKey = scopeRouteKey(identity.accountScope, route.id);
+      const startedScopeRouteGeneration = scopeRouteGenerations.get(scopedRouteKey) ?? 0;
+      const keyState = keyStates.get(key) ?? {
+        active: 0,
+        generation: 0
+      };
       keyState.active += 1;
       keyStates.set(key, keyState);
       const startedKeyGeneration = keyState.generation;
@@ -621,9 +645,14 @@ function cache(options) {
         try {
           const result = await next(request);
           const stored = cloneValue(result);
-          const currentScope = resolveScope();
-          if (stored.cacheable && currentScope === scope && generation === startedGeneration && (installationGenerations.get(installation) ?? 0) === startedInstallationGeneration && (routeGenerations.get(route.id) ?? 0) === startedRouteGeneration && (installationRouteGenerations.get(scopedRouteKey) ?? 0) === startedInstallationRouteGeneration && keyState.generation === startedKeyGeneration) {
-            values.set(key, { installation, route: route.id, value: stored.value });
+          const currentIdentity = await resolveIdentity();
+          const currentScope = route.id === "auth.sessions" ? currentIdentity.sessionScope : currentIdentity.accountScope;
+          if (stored.cacheable && currentScope === scope && generation === startedGeneration && (scopeGenerations.get(identity.accountScope) ?? 0) === startedScopeGeneration && (routeGenerations.get(route.id) ?? 0) === startedRouteGeneration && (scopeRouteGenerations.get(scopedRouteKey) ?? 0) === startedScopeRouteGeneration && keyState.generation === startedKeyGeneration) {
+            values.set(key, {
+              accountScope: identity.accountScope,
+              route: route.id,
+              value: stored.value
+            });
           }
           return { cacheable: stored.cacheable, value: result };
         } finally {
@@ -631,8 +660,12 @@ function cache(options) {
           if (keyState.active === 0 && keyStates.get(key) === keyState) keyStates.delete(key);
         }
       })();
-      const mayDeduplicate = mode === "default" && config.deduplicate && request.signal === void 0 && request.timeout === void 0;
-      const entry = { installation, route: route.id, promise: load };
+      const mayDeduplicate = mode === CacheModes.Default && config.deduplicate && request.signal === void 0 && request.timeout === void 0;
+      const entry = {
+        accountScope: identity.accountScope,
+        route: route.id,
+        promise: load
+      };
       if (mayDeduplicate) pending.set(key, entry);
       try {
         const loaded = await load;
@@ -655,26 +688,38 @@ function cache(options) {
       if (!stream || typeof stream.on !== "function") {
         throw new CacheError("attachRealtime() \u043F\u0440\u0438\u043D\u0438\u043C\u0430\u0435\u0442 \u043F\u043E\u0442\u043E\u043A \u0438\u0437 itd.realtime()");
       }
-      invalidate("notifications.list", "notifications.count");
+      const invalidateStream = (...routes) => {
+        const identity = typeof stream.getAuthIdentity === "function" ? stream.getAuthIdentity() : void 0;
+        const streamBaseUrl = typeof stream.baseUrl === "string" && stream.baseUrl.length > 0 ? stream.baseUrl : void 0;
+        const legacyScope = typeof stream.getAuthScope === "function" ? stream.getAuthScope() : void 0;
+        const accountScope = identity?.userId && streamBaseUrl ? JSON.stringify([streamBaseUrl, identity.userId]) : legacyScope !== void 0 && streamBaseUrl ? JSON.stringify([streamBaseUrl, legacyScope]) : void 0;
+        if (accountScope === void 0) invalidate(...routes);
+        else invalidateScope(accountScope, routes);
+      };
+      invalidateStream("notifications.list", "notifications.count");
       const offNotification = stream.on(
         "notification",
-        () => invalidate("notifications.list", "notifications.count")
+        () => invalidateStream("notifications.list", "notifications.count")
+      );
+      const offUnreadCount = stream.on(
+        "unreadCount",
+        () => invalidateStream("notifications.count")
       );
-      const offUnreadCount = stream.on("unreadCount", () => invalidate("notifications.count"));
       return () => {
         offNotification();
         offUnreadCount();
       };
     },
-    install({ use, getAuthScope }) {
+    install({ use, baseUrl, getAuthIdentity, getAuthScope }) {
       installationSequence += 1;
-      use(createTransformer(installationSequence, getAuthScope));
+      use(createTransformer(installationSequence, baseUrl, getAuthIdentity, getAuthScope));
     }
   };
 }
 
 exports.CACHE_ROUTES = CACHE_ROUTES;
 exports.CacheError = CacheError;
+exports.CacheModes = CacheModes;
 exports.buildCacheKey = buildCacheKey;
 exports.cache = cache;
 exports.cacheRoute = cacheRoute;