@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/react-native/entry-preview-pagination.ts

@@ -0,0 +1,261 @@
+import { toStorageEntryPreview } from '../shared/entry-preview';
+import type {
+  StorageListEntryPreviewsRequestEvent,
+  StorageListEntryPreviewsResponseEvent,
+  StorageRequestErrorEvent,
+} from '../shared/messaging';
+import type { StorageEntryPreview, StorageTarget } from '../shared/types';
+import type { StorageView } from './storage-view';
+
+export const MAX_ENTRY_PREVIEW_PAGE_SIZE = 100;
+export const ENTRY_PREVIEW_READ_CONCURRENCY = 4;
+
+type PaginationResult = StorageListEntryPreviewsResponseEvent | StorageRequestErrorEvent;
+
+type Cursor = {
+  version: 1;
+  target: StorageTarget;
+  search: string;
+  keySortDirection: 'ascending' | 'descending';
+  boundaryKey: string;
+  direction: 'next' | 'previous';
+};
+
+type ValidRequest = Omit<
+  StorageListEntryPreviewsRequestEvent,
+  'search' | 'keySortDirection' | 'limit'
+> & {
+  search: string;
+  keySortDirection: 'ascending' | 'descending';
+  limit: number;
+};
+
+const getRequestId = (payload: unknown) =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string'
+    ? (payload as { requestId: string }).requestId
+    : '';
+
+const isTarget = (value: unknown): value is StorageTarget =>
+  typeof value === 'object' &&
+  value != null &&
+  !Array.isArray(value) &&
+  typeof (value as { adapterId?: unknown }).adapterId === 'string' &&
+  (value as { adapterId: string }).adapterId.trim().length > 0 &&
+  typeof (value as { storageId?: unknown }).storageId === 'string' &&
+  (value as { storageId: string }).storageId.trim().length > 0;
+
+const normalizeSearch = (search: string | undefined) => (search ?? '').trim().toLowerCase();
+
+const validateRequest = (payload: unknown): ValidRequest | undefined => {
+  if (
+    typeof payload !== 'object' ||
+    payload == null ||
+    Array.isArray(payload) ||
+    (payload as { type?: unknown }).type !== 'list-entry-previews' ||
+    typeof (payload as { requestId?: unknown }).requestId !== 'string' ||
+    (payload as { requestId: string }).requestId.trim().length === 0 ||
+    !isTarget((payload as { target?: unknown }).target) ||
+    ((payload as { search?: unknown }).search !== undefined &&
+      typeof (payload as { search?: unknown }).search !== 'string') ||
+    ((payload as { cursor?: unknown }).cursor !== undefined &&
+      typeof (payload as { cursor?: unknown }).cursor !== 'string') ||
+    !Number.isFinite((payload as { limit?: unknown }).limit) ||
+    !Number.isInteger((payload as { limit: number }).limit) ||
+    (payload as { limit: number }).limit < 1
+  ) {
+    return undefined;
+  }
+
+  const keySortDirection = (payload as { keySortDirection?: unknown }).keySortDirection;
+  if (
+    keySortDirection !== undefined &&
+    keySortDirection !== 'ascending' &&
+    keySortDirection !== 'descending'
+  ) {
+    return undefined;
+  }
+
+  const request = payload as StorageListEntryPreviewsRequestEvent;
+  return {
+    ...request,
+    search: normalizeSearch(request.search),
+    keySortDirection: keySortDirection ?? 'ascending',
+    limit: Math.min(request.limit, MAX_ENTRY_PREVIEW_PAGE_SIZE),
+  };
+};
+
+// Cursor contents are intentionally private to the device protocol. Callers only
+// receive and return this opaque token; its representation may change freely.
+const encodeCursor = (cursor: Cursor) => btoa(encodeURIComponent(JSON.stringify(cursor)));
+
+const decodeCursor = (value: string): Cursor | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(decodeURIComponent(atob(value)));
+    if (
+      typeof parsed !== 'object' ||
+      parsed == null ||
+      Array.isArray(parsed) ||
+      (parsed as { version?: unknown }).version !== 1 ||
+      !isTarget((parsed as { target?: unknown }).target) ||
+      typeof (parsed as { search?: unknown }).search !== 'string' ||
+      ((parsed as { keySortDirection?: unknown }).keySortDirection !== 'ascending' &&
+        (parsed as { keySortDirection?: unknown }).keySortDirection !== 'descending') ||
+      typeof (parsed as { boundaryKey?: unknown }).boundaryKey !== 'string' ||
+      ((parsed as { direction?: unknown }).direction !== 'next' &&
+        (parsed as { direction?: unknown }).direction !== 'previous')
+    ) {
+      return undefined;
+    }
+
+    return parsed as Cursor;
+  } catch {
+    return undefined;
+  }
+};
+
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
+
+const compareKeys = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+
+const readPreviews = async (
+  view: StorageView,
+  keys: readonly string[],
+): Promise<StorageEntryPreview[]> => {
+  const previews: StorageEntryPreview[] = new Array(keys.length);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    while (nextIndex < keys.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const entry = await view.get(keys[index]);
+      if (entry) {
+        previews[index] = toStorageEntryPreview(entry);
+      }
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.min(ENTRY_PREVIEW_READ_CONCURRENCY, keys.length) }, worker),
+  );
+  return previews.filter((preview): preview is StorageEntryPreview => preview != null);
+};
+
+export const handleListEntryPreviewsRequest = async (
+  views: readonly StorageView[],
+  payload: unknown,
+): Promise<PaginationResult> => {
+  const requestId = getRequestId(payload);
+  const request = validateRequest(payload);
+  if (!request) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'INVALID_REQUEST',
+      message:
+        'Entry preview requests require a valid target, request ID, and positive integer limit.',
+    };
+  }
+
+  const view = views.find((candidate) => isSameTarget(candidate.target, request.target));
+  if (!view) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'TARGET_NOT_FOUND',
+      message: 'The requested storage target was not found.',
+    };
+  }
+
+  let cursor: Cursor | undefined;
+  if (request.cursor !== undefined) {
+    cursor = decodeCursor(request.cursor);
+    if (
+      !cursor ||
+      !isSameTarget(cursor.target, request.target) ||
+      cursor.search !== request.search ||
+      cursor.keySortDirection !== request.keySortDirection
+    ) {
+      return {
+        type: 'storage-request-error',
+        requestId,
+        code: 'INVALID_CURSOR',
+        message: 'The entry preview cursor is invalid or belongs to a different query.',
+        resetPagination: true,
+      };
+    }
+  }
+
+  try {
+    const keys = (await view.getAllKeys())
+      .filter((key) => key.toLowerCase().includes(request.search))
+      .sort(compareKeys);
+    if (request.keySortDirection === 'descending') {
+      keys.reverse();
+    }
+
+    let start = 0;
+    if (cursor) {
+      const boundaryIndex = keys.indexOf(cursor.boundaryKey);
+      if (boundaryIndex === -1) {
+        return {
+          type: 'storage-request-error',
+          requestId,
+          code: 'INVALID_CURSOR',
+          message: 'The entry preview cursor is stale after storage changes.',
+          resetPagination: true,
+        };
+      }
+      start =
+        cursor.direction === 'next'
+          ? boundaryIndex + 1
+          : Math.max(0, boundaryIndex - request.limit);
+    }
+
+    const pageKeys = keys.slice(start, start + request.limit);
+    const items = await readPreviews(view, pageKeys);
+    const end = start + pageKeys.length;
+    const cursorBase = {
+      version: 1 as const,
+      target: request.target,
+      search: request.search,
+      keySortDirection: request.keySortDirection,
+    };
+
+    return {
+      type: 'entry-previews',
+      requestId,
+      target: request.target,
+      items,
+      ...(end < keys.length && pageKeys.length > 0
+        ? {
+            nextCursor: encodeCursor({
+              ...cursorBase,
+              boundaryKey: pageKeys.at(-1)!,
+              direction: 'next',
+            }),
+          }
+        : {}),
+      ...(start > 0 && pageKeys.length > 0
+        ? {
+            previousCursor: encodeCursor({
+              ...cursorBase,
+              boundaryKey: pageKeys[0],
+              direction: 'previous',
+            }),
+          }
+        : {}),
+    };
+  } catch {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'READ_FAILED',
+      message: 'Failed to read entry previews from the requested storage.',
+    };
+  }
+};

package/src/react-native/export-snapshot.ts

@@ -0,0 +1,88 @@
+import { buildSnapshot } from '../shared/snapshot';
+import type {
+  StorageExportSnapshotRequestEvent,
+  StorageExportSnapshotResponseEvent,
+  StorageRequestErrorEvent,
+} from '../shared/messaging';
+import type { StorageTarget } from '../shared/types';
+import type { StorageView } from './storage-view';
+
+type ExportSnapshotResult = StorageExportSnapshotResponseEvent | StorageRequestErrorEvent;
+
+const getRequestId = (payload: unknown) =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string'
+    ? (payload as { requestId: string }).requestId
+    : '';
+
+const isTarget = (value: unknown): value is StorageTarget =>
+  typeof value === 'object' &&
+  value != null &&
+  !Array.isArray(value) &&
+  typeof (value as { adapterId?: unknown }).adapterId === 'string' &&
+  (value as { adapterId: string }).adapterId.trim().length > 0 &&
+  typeof (value as { storageId?: unknown }).storageId === 'string' &&
+  (value as { storageId: string }).storageId.trim().length > 0;
+
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
+
+const validateRequest = (payload: unknown): payload is StorageExportSnapshotRequestEvent =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  (payload as { type?: unknown }).type === 'export-snapshot' &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string' &&
+  (payload as { requestId: string }).requestId.trim().length > 0 &&
+  isTarget((payload as { target?: unknown }).target);
+
+export const handleExportSnapshotRequest = async (
+  views: readonly StorageView[],
+  payload: unknown,
+): Promise<ExportSnapshotResult> => {
+  const requestId = getRequestId(payload);
+  if (!validateRequest(payload)) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'INVALID_REQUEST',
+      message: 'Export requests require a valid target and request ID.',
+    };
+  }
+
+  const view = views.find((candidate) => isSameTarget(candidate.target, payload.target));
+  if (!view) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'TARGET_NOT_FOUND',
+      message: 'The requested storage target was not found.',
+    };
+  }
+
+  try {
+    // getAllEntries applies the storage view's blacklist before reading values.
+    const entries = await view.getAllEntries();
+    return {
+      type: 'export-snapshot-result',
+      requestId,
+      target: view.target,
+      snapshot: buildSnapshot({
+        target: view.target,
+        adapterName: view.adapterName,
+        storageName: view.storageName,
+        capabilities: view.capabilities,
+        entries,
+      }),
+    };
+  } catch {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'READ_FAILED',
+      message: 'Failed to export the requested storage.',
+    };
+  }
+};

package/src/react-native/full-entry-request.ts

@@ -0,0 +1,91 @@
+import type {
+  StorageGetEntryRequestEvent,
+  StorageGetEntryResponseEvent,
+  StorageRequestErrorEvent,
+} from '../shared/messaging';
+import type { StorageTarget } from '../shared/types';
+import type { StorageView } from './storage-view';
+
+type FullEntryResult = StorageGetEntryResponseEvent | StorageRequestErrorEvent;
+
+const getRequestId = (payload: unknown) =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string'
+    ? (payload as { requestId: string }).requestId
+    : '';
+
+const isTarget = (value: unknown): value is StorageTarget =>
+  typeof value === 'object' &&
+  value != null &&
+  !Array.isArray(value) &&
+  typeof (value as { adapterId?: unknown }).adapterId === 'string' &&
+  (value as { adapterId: string }).adapterId.trim().length > 0 &&
+  typeof (value as { storageId?: unknown }).storageId === 'string' &&
+  (value as { storageId: string }).storageId.trim().length > 0;
+
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
+
+const validateRequest = (payload: unknown): payload is StorageGetEntryRequestEvent =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  (payload as { type?: unknown }).type === 'get-entry' &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string' &&
+  (payload as { requestId: string }).requestId.trim().length > 0 &&
+  isTarget((payload as { target?: unknown }).target) &&
+  typeof (payload as { key?: unknown }).key === 'string';
+
+export const handleFullEntryRequest = async (
+  views: readonly StorageView[],
+  payload: unknown,
+): Promise<FullEntryResult> => {
+  const requestId = getRequestId(payload);
+  if (!validateRequest(payload)) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'INVALID_REQUEST',
+      message: 'Full entry requests require a valid target, request ID, and string key.',
+    };
+  }
+
+  const view = views.find((candidate) => isSameTarget(candidate.target, payload.target));
+  if (!view) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'TARGET_NOT_FOUND',
+      message: 'The requested storage target was not found.',
+    };
+  }
+
+  try {
+    // StorageView applies the same blacklist policy used by preview requests.
+    const entry = await view.get(payload.key);
+    if (!entry) {
+      return {
+        type: 'storage-request-error',
+        requestId,
+        code: 'ENTRY_NOT_FOUND',
+        message: 'The requested storage entry was not found.',
+      };
+    }
+
+    return {
+      type: 'entry',
+      requestId,
+      target: view.target,
+      entry,
+    };
+  } catch {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'READ_FAILED',
+      message: 'Failed to read the requested storage entry.',
+    };
+  }
+};

package/src/react-native/import.ts

@@ -1,28 +1,163 @@
 import type {
   StorageImportEntriesEvent,
+  StorageImportPreviewRequestEvent,
+  StorageImportPreviewResponseEvent,
+  StorageImportProgressEvent,
   StorageImportResultEvent,
-  StorageSetEntryEvent,
+  StorageInvalidatedEvent,
+  StorageRequestErrorEvent,
 } from '../shared/messaging';
+import { computePreview, parseSnapshot } from '../shared/snapshot';
+import { supportsType, type StorageEntry, type StorageTarget } from '../shared/types';
 import type { StorageView } from './storage-view';
 
 export type ImportEmittedEvent =
-  | StorageSetEntryEvent
-  | StorageImportResultEvent;
+  | StorageImportProgressEvent
+  | StorageImportResultEvent
+  | StorageInvalidatedEvent;
+
+type ImportPreviewResult = StorageImportPreviewResponseEvent | StorageRequestErrorEvent;
+
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
+
+const isTarget = (value: unknown): value is StorageTarget =>
+  typeof value === 'object' &&
+  value != null &&
+  !Array.isArray(value) &&
+  typeof (value as { adapterId?: unknown }).adapterId === 'string' &&
+  (value as { adapterId: string }).adapterId.trim().length > 0 &&
+  typeof (value as { storageId?: unknown }).storageId === 'string' &&
+  (value as { storageId: string }).storageId.trim().length > 0;
+
+const getRequestId = (payload: unknown) =>
+  typeof payload === 'object' &&
+  payload != null &&
+  !Array.isArray(payload) &&
+  typeof (payload as { requestId?: unknown }).requestId === 'string'
+    ? (payload as { requestId: string }).requestId
+    : '';
+
+const isEntry = (value: unknown): value is StorageEntry => {
+  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
+    return false;
+  }
+
+  const entry = value as { key?: unknown; type?: unknown; value?: unknown };
+  if (typeof entry.key !== 'string') return false;
+  if (entry.type === 'string') return typeof entry.value === 'string';
+  if (entry.type === 'number') return typeof entry.value === 'number';
+  if (entry.type === 'boolean') return typeof entry.value === 'boolean';
+  return (
+    entry.type === 'buffer' &&
+    Array.isArray(entry.value) &&
+    entry.value.every(
+      (byte) => typeof byte === 'number' && Number.isInteger(byte) && byte >= 0 && byte <= 255,
+    )
+  );
+};
+
+const isBlacklisted = (view: StorageView, key: string) => {
+  if (!view.blacklist) return false;
+  view.blacklist.lastIndex = 0;
+  return view.blacklist.test(key);
+};
+
+const findView = (views: readonly StorageView[], target: StorageTarget) =>
+  views.find((candidate) => isSameTarget(candidate.target, target));
+
+export const handleImportPreviewRequest = async (
+  views: readonly StorageView[],
+  payload: unknown,
+): Promise<ImportPreviewResult> => {
+  const requestId = getRequestId(payload);
+  const request = payload as Partial<StorageImportPreviewRequestEvent>;
+  const parsedSnapshot = parseSnapshot(request.snapshot);
+  if (
+    typeof request !== 'object' ||
+    request == null ||
+    request.type !== 'preview-import' ||
+    typeof request.requestId !== 'string' ||
+    request.requestId.trim().length === 0 ||
+    !isTarget(request.target) ||
+    !parsedSnapshot.ok
+  ) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'INVALID_REQUEST',
+      message: 'Import preview requests require a valid target, request ID, and snapshot.',
+    };
+  }
+
+  const view = findView(views, request.target);
+  if (!view) {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'TARGET_NOT_FOUND',
+      message: 'The requested storage target was not found.',
+    };
+  }
+
+  try {
+    const entryKeys = new Set(await view.getAllKeys());
+    return {
+      type: 'import-preview',
+      requestId,
+      target: view.target,
+      preview: computePreview(parsedSnapshot.snapshot, {
+        target: view.target,
+        capabilities: view.capabilities,
+        entryKeys,
+        isBlacklisted: (key) => isBlacklisted(view, key),
+      }),
+    };
+  } catch {
+    return {
+      type: 'storage-request-error',
+      requestId,
+      code: 'READ_FAILED',
+      message: 'Failed to inspect the requested storage for import.',
+    };
+  }
+};
 
 export const handleImportEntries = async (
   views: StorageView[],
-  event: StorageImportEntriesEvent,
+  payload: unknown,
   emit: (out: ImportEmittedEvent) => void,
 ): Promise<void> => {
-  const view = views.find(
-    (candidate) =>
-      candidate.target.adapterId === event.target.adapterId &&
-      candidate.target.storageId === event.target.storageId,
-  );
+  const requestId = getRequestId(payload);
+  const event = payload as Partial<StorageImportEntriesEvent>;
+  if (
+    typeof event !== 'object' ||
+    event == null ||
+    event.type !== 'import-entries' ||
+    typeof event.requestId !== 'string' ||
+    event.requestId.trim().length === 0 ||
+    !isTarget(event.target) ||
+    !Array.isArray(event.entries) ||
+    !event.entries.every(isEntry)
+  ) {
+    emit({
+      type: 'import-result',
+      requestId,
+      target: isTarget(event.target) ? event.target : { adapterId: '', storageId: '' },
+      ok: false,
+      written: 0,
+      total: 0,
+      error: 'Import requests require a valid target, request ID, and entries.',
+    });
+    return;
+  }
+
+  const view = findView(views, event.target);
 
   if (!view) {
     emit({
       type: 'import-result',
+      requestId: event.requestId,
       target: event.target,
       ok: false,
       written: 0,
@@ -32,18 +167,33 @@ export const handleImportEntries = async (
     return;
   }
 
-  for (let i = 0; i < event.entries.length; i++) {
-    const entry = event.entries[i];
+  // Recheck policy at apply time so a preview cannot bypass a changed target.
+  const entries = event.entries.filter(
+    (entry) => supportsType(view.capabilities, entry.type) && !isBlacklisted(view, entry.key),
+  );
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
 
     try {
       await view.set(entry);
     } catch (error) {
+      if (i > 0) {
+        const entryCount = (await view.getAllKeys()).length;
+        emit({
+          type: 'storage-invalidated',
+          target: event.target,
+          operation: 'import',
+          entryCount,
+        });
+      }
       emit({
         type: 'import-result',
+        requestId: event.requestId,
         target: event.target,
         ok: false,
         written: i,
-        total: event.entries.length,
+        total: entries.length,
         failedKey: entry.key,
         error: error instanceof Error ? error.message : String(error),
       });
@@ -51,17 +201,30 @@ export const handleImportEntries = async (
     }
 
     emit({
-      type: 'set-entry',
+      type: 'import-progress',
+      requestId: event.requestId,
+      target: event.target,
+      written: i + 1,
+      total: entries.length,
+    });
+  }
+
+  if (entries.length > 0) {
+    const entryCount = (await view.getAllKeys()).length;
+    emit({
+      type: 'storage-invalidated',
       target: event.target,
-      entry,
+      operation: 'import',
+      entryCount,
     });
   }
 
   emit({
     type: 'import-result',
+    requestId: event.requestId,
     target: event.target,
     ok: true,
-    written: event.entries.length,
-    total: event.entries.length,
+    written: entries.length,
+    total: entries.length,
   });
 };