@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/react-native/storage-discovery.ts

@@ -0,0 +1,92 @@
+import type {
+  StorageDiscoverStoragesRequestEvent,
+  StorageDiscoverStoragesResponseEvent,
+  StorageRequestErrorEvent,
+} from '../shared/messaging';
+import type { StorageDescriptor } from '../shared/types';
+import type { StorageView } from './storage-view';
+
+type DiscoveryResult = StorageDiscoverStoragesResponseEvent | StorageRequestErrorEvent;
+
+const getRequestId = (payload: unknown) => {
+  if (
+    typeof payload === 'object' &&
+    payload != null &&
+    !Array.isArray(payload) &&
+    typeof (payload as { requestId?: unknown }).requestId === 'string'
+  ) {
+    return (payload as { requestId: string }).requestId;
+  }
+
+  return '';
+};
+
+const validateRequest = (payload: unknown): payload is StorageDiscoverStoragesRequestEvent =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  (payload as { type?: unknown }).type === 'discover-storages' &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string' &&
+  (payload as { requestId: string }).requestId.trim().length > 0;
+
+const toDescriptor = async (view: StorageView): Promise<StorageDescriptor> => ({
+  target: view.target,
+  adapterName: view.adapterName,
+  storageName: view.storageName,
+  entryCount: (await view.getAllKeys()).length,
+  capabilities: view.capabilities,
+  supportsSubscriptions: view.supportsSubscriptions,
+});
+
+const hasDuplicateTargets = (views: readonly Pick<StorageView, 'target'>[]) => {
+  const targets = new Set<string>();
+
+  return views.some(({ target }) => {
+    const id = `${target.adapterId}:${target.storageId}`;
+
+    if (targets.has(id)) {
+      return true;
+    }
+
+    targets.add(id);
+    return false;
+  });
+};
+
+export const handleStorageDiscoveryRequest = async (
+  views: readonly StorageView[],
+  payload: unknown,
+): Promise<DiscoveryResult> => {
+  const requestId = getRequestId(payload);
+
+  if (!validateRequest(payload)) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'INVALID_REQUEST',
+      message: 'Storage discovery requires a non-empty request ID.',
+    };
+  }
+
+  try {
+    if (hasDuplicateTargets(views)) {
+      return {
+        type: 'storage-request-error',
+        requestId,
+        code: 'INVALID_REQUEST',
+        message: 'Configured storages must have unique targets.',
+      };
+    }
+
+    const storages = await Promise.all(views.map(toDescriptor));
+
+    return { type: 'storage-descriptors', requestId, storages };
+  } catch {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'READ_FAILED',
+      message: 'Failed to discover configured storages.',
+    };
+  }
+};

package/src/react-native/storage-view.ts

@@ -12,27 +12,11 @@ import {
   type SyncStorage,
 } from '../shared/types';
 
-const POLLING_INTERVAL_MS = 1500;
-
-type StorageSnapshotMap = Map<string, StorageEntry>;
-
 type AsyncStorageLike = SyncStorage | AsyncStorage;
 
 const isAsyncStorage = (storage: AsyncStorageLike): storage is AsyncStorage =>
   storage.kind === 'async';
 
-const fingerprintEntry = (entry: StorageEntry) => {
-  if (entry.type === 'buffer') {
-    return `${entry.type}:${entry.value.join(',')}`;
-  }
-
-  return `${entry.type}:${String(entry.value)}`;
-};
-
-const toSnapshotMap = (entries: StorageEntry[]) => {
-  return new Map(entries.map((entry) => [entry.key, entry]));
-};
-
 const shouldFilterKey = (storage: StorageNode, key: string) => {
   if (storage.shouldFilterKey?.(key)) {
     return true;
@@ -94,83 +78,25 @@ const deleteEntry = async (storage: AsyncStorageLike, key: string) => {
   storage.delete(key);
 };
 
+const clearStorage = async (storage: AsyncStorageLike) => {
+  await storage.clear();
+};
+
 export type StorageView = {
   id: string;
   target: StorageTarget;
   adapterName: string;
   storageName: string;
   capabilities: StorageCapabilities;
+  supportsSubscriptions: boolean;
   blacklist?: RegExp;
   get: (key: string) => Promise<StorageEntry | undefined>;
   set: (entry: StorageEntry) => Promise<void>;
   delete: (key: string) => Promise<void>;
+  purge: () => Promise<void>;
   getAllKeys: () => Promise<readonly string[]>;
   getAllEntries: () => Promise<StorageEntry[]>;
-  watch: (callbacks: {
-    onSet: (entry: StorageEntry) => void;
-    onDelete: (key: string) => void;
-  }) => Promise<StorageSubscription>;
-};
-
-const buildSnapshotMap = async (
-  getAllEntries: () => Promise<StorageEntry[]>,
-): Promise<StorageSnapshotMap> => {
-  const entries = await getAllEntries();
-  return toSnapshotMap(entries);
-};
-
-const diffSnapshots = (
-  previous: StorageSnapshotMap,
-  next: StorageSnapshotMap,
-  handlers: {
-    onSet: (entry: StorageEntry) => void;
-    onDelete: (key: string) => void;
-  },
-) => {
-  next.forEach((nextEntry, key) => {
-    const previousEntry = previous.get(key);
-
-    if (!previousEntry) {
-      handlers.onSet(nextEntry);
-      return;
-    }
-
-    if (fingerprintEntry(previousEntry) !== fingerprintEntry(nextEntry)) {
-      handlers.onSet(nextEntry);
-    }
-  });
-
-  previous.forEach((_value, key) => {
-    if (!next.has(key)) {
-      handlers.onDelete(key);
-    }
-  });
-};
-
-const createPollingSubscription = async (
-  getAllEntries: () => Promise<StorageEntry[]>,
-  handlers: {
-    onSet: (entry: StorageEntry) => void;
-    onDelete: (key: string) => void;
-  },
-): Promise<StorageSubscription> => {
-  let previousSnapshot = await buildSnapshotMap(getAllEntries);
-
-  const interval = setInterval(async () => {
-    try {
-      const nextSnapshot = await buildSnapshotMap(getAllEntries);
-      diffSnapshots(previousSnapshot, nextSnapshot, handlers);
-      previousSnapshot = nextSnapshot;
-    } catch {
-      // Silently ignore polling errors and try again on next tick.
-    }
-  }, POLLING_INTERVAL_MS);
-
-  return {
-    remove: () => {
-      clearInterval(interval);
-    },
-  };
+  watch?: (onChange: (key: string) => void) => Promise<StorageSubscription>;
 };
 
 export const createStorageView = (
@@ -178,6 +104,9 @@ export const createStorageView = (
   storageNode: StorageNode,
 ): StorageView => {
   const storage = storageNode.storage;
+  const subscribe = storage.subscribe;
+  const locallyMutatingKeys = new Set<string>();
+  let isLocallyPurging = false;
   const target: StorageTarget = {
     adapterId: adapter.id,
     storageId: storageNode.id,
@@ -194,9 +123,7 @@ export const createStorageView = (
   const getAllEntries = async () => {
     const keys = await getAllKeys(storage);
     const visibleEntries = await Promise.all(
-      keys
-        .filter((key) => !shouldFilterKey(storageNode, key))
-        .map((key) => getEntry(storage, key)),
+      keys.filter((key) => !shouldFilterKey(storageNode, key)).map((key) => getEntry(storage, key)),
     );
 
     return visibleEntries.filter((entry): entry is StorageEntry => !!entry);
@@ -208,46 +135,57 @@ export const createStorageView = (
     adapterName: adapter.name,
     storageName: storageNode.name,
     capabilities: storageNode.capabilities,
+    supportsSubscriptions: subscribe != null,
     blacklist: storageNode.blacklist,
     get,
     set: async (entry) => {
       checkTypeSupport(storageNode.capabilities, entry.type, target);
-      await setEntry(storage, entry);
+      locallyMutatingKeys.add(entry.key);
+      try {
+        await setEntry(storage, entry);
+      } finally {
+        locallyMutatingKeys.delete(entry.key);
+      }
     },
     delete: async (key) => {
-      await deleteEntry(storage, key);
+      locallyMutatingKeys.add(key);
+      try {
+        await deleteEntry(storage, key);
+      } finally {
+        locallyMutatingKeys.delete(key);
+      }
+    },
+    purge: async () => {
+      isLocallyPurging = true;
+      try {
+        await clearStorage(storage);
+      } finally {
+        isLocallyPurging = false;
+      }
     },
     getAllKeys: async () => {
       const keys = await getAllKeys(storage);
       return keys.filter((key) => !shouldFilterKey(storageNode, key));
     },
     getAllEntries,
-    watch: async ({ onSet, onDelete }) => {
-      if (storage.subscribe) {
-        return storage.subscribe(async (key) => {
-          try {
-            const entry = await get(key);
-
-            if (!entry) {
-              onDelete(key);
-              return;
-            }
-
-            onSet(entry);
-          } catch {
-            // Ignore runtime callback errors; polling fallback is not needed when subscribe exists.
-          }
-        });
-      }
-
-      return createPollingSubscription(getAllEntries, { onSet, onDelete });
-    },
+    ...(subscribe
+      ? {
+          watch: async (onChange) =>
+            subscribe((key) => {
+              if (
+                !isLocallyPurging &&
+                !locallyMutatingKeys.has(key) &&
+                !shouldFilterKey(storageNode, key)
+              ) {
+                onChange(key);
+              }
+            }),
+        }
+      : {}),
   };
 };
 
 export const createStorageViews = (storages: StorageAdapter[]) =>
   storages.flatMap((adapter) =>
-    adapter.storages.map((storageNode) =>
-      createStorageView(adapter, storageNode),
-    ),
+    adapter.storages.map((storageNode) => createStorageView(adapter, storageNode)),
   );

package/src/react-native/useRozeniteStoragePlugin.ts

@@ -2,13 +2,23 @@ import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
 import { useEffect, useMemo } from 'react';
 import type {
   StorageDeleteEntryEvent,
+  StorageDiscoverStoragesRequestEvent,
   StorageEventMap,
-  StorageGetSnapshotEvent,
+  StorageExportSnapshotRequestEvent,
+  StorageGetEntryRequestEvent,
   StorageImportEntriesEvent,
+  StorageImportPreviewRequestEvent,
+  StorageInvalidationOperation,
+  StorageListEntryPreviewsRequestEvent,
   StorageSetEntryEvent,
+  StoragePurgeEvent,
 } from '../shared/messaging';
 import type { StorageAdapter } from '../shared/types';
-import { handleImportEntries } from './import';
+import { handleImportEntries, handleImportPreviewRequest } from './import';
+import { handleStorageDiscoveryRequest } from './storage-discovery';
+import { handleListEntryPreviewsRequest } from './entry-preview-pagination';
+import { handleFullEntryRequest } from './full-entry-request';
+import { handleExportSnapshotRequest } from './export-snapshot';
 import { createStorageViews } from './storage-view';
 import { useStorageAgentTools } from './useStorageAgentTools';
 
@@ -16,9 +26,7 @@ export type RozeniteStoragePluginOptions = {
   storages: StorageAdapter[];
 };
 
-export const useRozeniteStoragePlugin = ({
-  storages,
-}: RozeniteStoragePluginOptions) => {
+export const useRozeniteStoragePlugin = ({ storages }: RozeniteStoragePluginOptions) => {
   const views = useMemo(() => createStorageViews(storages), [storages]);
 
   useStorageAgentTools(views);
@@ -32,153 +40,169 @@ export const useRozeniteStoragePlugin = ({
       return;
     }
 
-    const pushSnapshot = async (viewId?: string) => {
-      const selectedViews = viewId
-        ? views.filter((view) => view.id === viewId)
-        : views;
+    const viewSubscriptions: { remove: () => void }[] = [];
+    let disposed = false;
+
+    const sendInvalidation = async (
+      target: StorageSetEntryEvent['target'],
+      key?: string,
+      operation?: StorageInvalidationOperation,
+    ) => {
+      const view = views.find(
+        (candidate) =>
+          candidate.target.adapterId === target.adapterId &&
+          candidate.target.storageId === target.storageId,
+      );
+      const entryCount = view ? (await view.getAllKeys()).length : 0;
+      client.send('storage-invalidated', {
+        type: 'storage-invalidated',
+        target,
+        key,
+        operation,
+        entryCount,
+      });
+    };
+
+    // Prevent one storage watcher failure from breaking the whole plugin.
+    void Promise.all(
+      views
+        .filter((view) => view.supportsSubscriptions && view.watch)
+        .map(async (view) => {
+          try {
+            const watch = view.watch;
+            if (!watch) {
+              return;
+            }
+
+            const subscription = await watch((key) => {
+              void sendInvalidation(view.target, key);
+            });
+
+            if (disposed) {
+              subscription.remove();
+              return;
+            }
+
+            viewSubscriptions.push(subscription);
+          } catch (error) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Failed to attach watcher for ${view.target.adapterId}/${view.target.storageId}.`,
+              error,
+            );
+          }
+        }),
+    );
+
+    const messageSubscriptions = [
+      client.onMessage('set-entry', async ({ target, entry }: StorageSetEntryEvent) => {
+        const view = views.find(
+          (candidate) =>
+            candidate.target.adapterId === target.adapterId &&
+            candidate.target.storageId === target.storageId,
+        );
+
+        if (!view) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
+          );
+          return;
+        }
 
-      for (const view of selectedViews) {
         try {
-          const entries = await view.getAllEntries();
-          client.send('snapshot', {
-            type: 'snapshot',
-            target: view.target,
-            adapterName: view.adapterName,
-            storageName: view.storageName,
-            capabilities: view.capabilities,
-            blacklist: view.blacklist
-              ? { source: view.blacklist.source, flags: view.blacklist.flags }
-              : undefined,
-            entries,
-          });
+          await view.set(entry);
+          await sendInvalidation(view.target, entry.key, 'set');
         } catch (error) {
           console.warn(
-            `[Rozenite] Storage Plugin: Failed to snapshot ${view.target.adapterId}/${view.target.storageId}.`,
+            `[Rozenite] Storage Plugin: Failed to set entry in ${target.adapterId}/${target.storageId}.`,
             error,
           );
         }
-      }
-    };
-
-    void pushSnapshot();
-
-    const viewSubscriptions: { remove: () => void }[] = [];
-    let disposed = false;
+      }),
+      client.onMessage('delete-entry', async ({ target, key }: StorageDeleteEntryEvent) => {
+        const view = views.find(
+          (candidate) =>
+            candidate.target.adapterId === target.adapterId &&
+            candidate.target.storageId === target.storageId,
+        );
+
+        if (!view) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
+          );
+          return;
+        }
 
-    // Prevent one storage watcher failure from breaking the whole plugin.
-    void Promise.all(
-      views.map(async (view) => {
         try {
-          const subscription = await view.watch({
-            onSet: (entry) => {
-              client.send('set-entry', {
-                type: 'set-entry',
-                target: view.target,
-                entry,
-              });
-            },
-            onDelete: (key) => {
-              client.send('delete-entry', {
-                type: 'delete-entry',
-                target: view.target,
-                key,
-              });
-            },
-          });
-
-          if (disposed) {
-            subscription.remove();
-            return;
-          }
-
-          viewSubscriptions.push(subscription);
+          await view.delete(key);
+          await sendInvalidation(view.target, key, 'delete');
         } catch (error) {
           console.warn(
-            `[Rozenite] Storage Plugin: Failed to attach watcher for ${view.target.adapterId}/${view.target.storageId}.`,
+            `[Rozenite] Storage Plugin: Failed to delete entry in ${target.adapterId}/${target.storageId}.`,
             error,
           );
         }
       }),
-    );
-
-    const messageSubscriptions = [
-      client.onMessage(
-        'set-entry',
-        async ({ target, entry }: StorageSetEntryEvent) => {
-          const view = views.find(
-            (candidate) =>
-              candidate.target.adapterId === target.adapterId &&
-              candidate.target.storageId === target.storageId,
+      client.onMessage('purge-storage', async ({ target }: StoragePurgeEvent) => {
+        const view = views.find(
+          (candidate) =>
+            candidate.target.adapterId === target.adapterId &&
+            candidate.target.storageId === target.storageId,
+        );
+
+        if (!view) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
           );
+          return;
+        }
 
-          if (!view) {
-            console.warn(
-              `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
-            );
-            return;
-          }
-
-          try {
-            await view.set(entry);
-          } catch (error) {
-            console.warn(
-              `[Rozenite] Storage Plugin: Failed to set entry in ${target.adapterId}/${target.storageId}.`,
-              error,
-            );
-          }
-        },
-      ),
-      client.onMessage(
-        'delete-entry',
-        async ({ target, key }: StorageDeleteEntryEvent) => {
-          const view = views.find(
-            (candidate) =>
-              candidate.target.adapterId === target.adapterId &&
-              candidate.target.storageId === target.storageId,
+        try {
+          await view.purge();
+          await sendInvalidation(view.target, undefined, 'purge');
+        } catch (error) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Failed to purge storage in ${target.adapterId}/${target.storageId}.`,
+            error,
           );
-
-          if (!view) {
-            console.warn(
-              `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`,
-            );
-            return;
-          }
-
-          try {
-            await view.delete(key);
-          } catch (error) {
-            console.warn(
-              `[Rozenite] Storage Plugin: Failed to delete entry in ${target.adapterId}/${target.storageId}.`,
-              error,
-            );
-          }
-        },
-      ),
-      client.onMessage(
-        'get-snapshot',
-        async ({ target }: StorageGetSnapshotEvent) => {
-          if (target === 'all') {
-            await pushSnapshot();
-            return;
-          }
-
-          await pushSnapshot(`${target.adapterId}:${target.storageId}`);
-        },
-      ),
+        }
+      }),
+      client.onMessage('discover-storages', async (event: StorageDiscoverStoragesRequestEvent) => {
+        const response = await handleStorageDiscoveryRequest(views, event);
+        client.send(response.type, response);
+      }),
       client.onMessage(
-        'import-entries',
-        async (event: StorageImportEntriesEvent) => {
-          await handleImportEntries(views, event, (out) => {
-            if (out.type === 'set-entry') {
-              client.send('set-entry', out);
-            } else {
-              client.send('import-result', out);
-            }
-          });
+        'list-entry-previews',
+        async (event: StorageListEntryPreviewsRequestEvent) => {
+          const response = await handleListEntryPreviewsRequest(views, event);
+          client.send(response.type, response);
         },
       ),
+      client.onMessage('get-entry', async (event: StorageGetEntryRequestEvent) => {
+        const response = await handleFullEntryRequest(views, event);
+        client.send(response.type, response);
+      }),
+      client.onMessage('export-snapshot', async (event: StorageExportSnapshotRequestEvent) => {
+        const response = await handleExportSnapshotRequest(views, event);
+        client.send(response.type, response);
+      }),
+      client.onMessage('preview-import', async (event: StorageImportPreviewRequestEvent) => {
+        const response = await handleImportPreviewRequest(views, event);
+        client.send(response.type, response);
+      }),
+      client.onMessage('import-entries', async (event: StorageImportEntriesEvent) => {
+        await handleImportEntries(views, event, (out) => {
+          client.send(out.type, out);
+        });
+      }),
     ];
 
+    // Sent last, so a panel that reacts to it is guaranteed to find the
+    // handlers above already listening. The panel is recreated on every app
+    // reload and asks for storages as soon as it boots, which usually beats the
+    // app's React tree to the punch; without this the panel's only request is
+    // dropped and it waits for storages forever.
+    client.send('device-ready', { type: 'device-ready' });
+
     return () => {
       disposed = true;
       viewSubscriptions.forEach((subscription) => subscription.remove());