castle-web-sdk 0.4.0 → 0.4.2

package/src/storage.ts

@@ -0,0 +1,636 @@
+import { getAuth, requireAuthToken } from "./auth";
+import { getDeckContext, requireDeckId } from "./context";
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+import type { Json } from "./types";
+
+const FLUSH_INTERVAL_MS = 2000;
+
+type EncodedValue = string | null;
+type StorageBlob = Record<string, string>;
+type SharedScope = "deck" | "user";
+
+interface DeckStorageData {
+  deckStorage: StorageBlob;
+}
+
+interface UpdateDeckStorageData {
+  updateDeckStorage: StorageBlob;
+}
+
+interface SharedDeckStorageData {
+  sharedDeckStorage: StorageBlob;
+}
+
+interface UpdateSharedDeckStorageData {
+  updateSharedDeckStorage: boolean;
+}
+
+interface StorageUpdate {
+  [key: string]: Json;
+  key: string;
+  value: EncodedValue;
+}
+
+interface Bucket {
+  scope: SharedScope;
+  userId?: string;
+  sessionId?: string;
+}
+
+interface PendingRead {
+  resolve: (value: Json | null) => void;
+  reject: (error: unknown) => void;
+}
+
+interface ReadBatch {
+  bucket: Bucket;
+  reads: Map<string, PendingRead[]>;
+  scheduled: boolean;
+}
+
+export interface StorageApi {
+  get<T extends Json = Json>(key: string): Promise<T | null>;
+  set(key: string, value: Json): void;
+  remove(key: string): void;
+}
+
+export interface SharedStorageApi {
+  get<T extends Json = Json>(scope: "deck", key: string): Promise<T | null>;
+  get<T extends Json = Json>(scope: "user", key: string): Promise<T | null>;
+  get<T extends Json = Json>(
+    scope: "user",
+    userId: string,
+    key: string,
+  ): Promise<T | null>;
+  set(scope: SharedScope, key: string, value: Json): void;
+  remove(scope: SharedScope, key: string): void;
+}
+
+class PrivateStorageImpl implements StorageApi {
+  private cache = new Map<string, Json>();
+  private dirty = new Map<string, EncodedValue>();
+  private loadPromise: Promise<void> | null = null;
+  private loadedContextKey: string | null = null;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async get<T extends Json = Json>(key: string): Promise<T | null> {
+    await this.ensureLoaded("Storage.get");
+    return (this.cache.get(key) ?? null) as T | null;
+  }
+
+  set(key: string, value: Json): void {
+    const encoded = encodeStorageValue(value, "Storage.set");
+    this.cache.set(key, value);
+    this.dirty.set(key, encoded);
+    this.scheduleFlush();
+  }
+
+  remove(key: string): void {
+    this.cache.delete(key);
+    this.dirty.set(key, null);
+    this.scheduleFlush();
+  }
+
+  private async flush(): Promise<void> {
+    if (this.dirty.size === 0) return;
+    const context = await currentContext("Storage.flush");
+    const snapshot = new Map(this.dirty);
+    const data = await storageGraphql<UpdateDeckStorageData>(
+      UPDATE_DECK_STORAGE_MUTATION,
+      {
+        deckId: context.deckId,
+        sessionId: context.sessionId,
+        updates: updatesFromDirty(snapshot),
+      },
+      "updateDeckStorage",
+    );
+    this.applyServerBlob(
+      data.updateDeckStorage,
+      contextKey(context.deckId, context.sessionId),
+    );
+    clearAcknowledgedDirty(this.dirty, snapshot);
+    this.overlayDirty();
+  }
+
+  private ensureLoaded(operation: string): Promise<void> {
+    if (!this.loadPromise) {
+      this.loadPromise = this.load(operation).catch((error: unknown) => {
+        this.loadPromise = null;
+        throw error;
+      });
+    }
+    return this.loadPromise;
+  }
+
+  private async load(operation: string): Promise<void> {
+    const context = await currentContext(operation);
+    const key = contextKey(context.deckId, context.sessionId);
+    if (this.loadedContextKey === key) return;
+    const data = await storageGraphql<DeckStorageData>(
+      DECK_STORAGE_QUERY,
+      { deckId: context.deckId, sessionId: context.sessionId },
+      "deckStorage",
+    );
+    this.cache = decodeStorageBlob(data.deckStorage, operation);
+    this.loadedContextKey = key;
+    this.overlayDirty();
+  }
+
+  private applyServerBlob(blob: StorageBlob, loadedContextKey: string): void {
+    this.cache = decodeStorageBlob(blob, "Storage.flush");
+    this.loadedContextKey = loadedContextKey;
+  }
+
+  private overlayDirty(): void {
+    for (const [key, encoded] of this.dirty) {
+      if (encoded === null) {
+        this.cache.delete(key);
+      } else {
+        this.cache.set(key, decodeStorageValue(encoded, "Storage.dirty"));
+      }
+    }
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+}
+
+class SharedStorageImpl implements SharedStorageApi {
+  private dirtyBuckets = new Map<string, Map<string, EncodedValue>>();
+  private buckets = new Map<string, Bucket>();
+  private readBatches = new Map<string, ReadBatch>();
+  private pendingWrites = new Set<Promise<void>>();
+  private pendingWriteErrors: unknown[] = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async get<T extends Json = Json>(
+    scope: SharedScope,
+    userOrKey: string,
+    maybeKey?: string,
+  ): Promise<T | null> {
+    const bucket = await readBucket(
+      scope,
+      userOrKey,
+      maybeKey,
+      "SharedStorage.get",
+    );
+    const key = maybeKey ?? userOrKey;
+    await this.awaitPendingWrites("SharedStorage.get");
+    const dirty = this.peekDirty(bucket, key);
+    if (dirty !== undefined) {
+      return (
+        dirty === null ? null : decodeStorageValue(dirty, "SharedStorage.get")
+      ) as T | null;
+    }
+    return this.queueRead<T>(bucket, key);
+  }
+
+  set(scope: SharedScope, key: string, value: Json): void {
+    this.enqueueWrite(
+      scope,
+      key,
+      encodeStorageValue(value, "SharedStorage.set"),
+      "SharedStorage.set",
+    );
+  }
+
+  remove(scope: SharedScope, key: string): void {
+    this.enqueueWrite(scope, key, null, "SharedStorage.remove");
+  }
+
+  private async flush(): Promise<void> {
+    await this.awaitPendingWrites("SharedStorage.flush");
+    if (this.dirtyBuckets.size === 0) return;
+    const tasks = Array.from(this.dirtyBuckets, ([bucketKey, dirty]) =>
+      this.flushBucket(bucketKey, new Map(dirty)),
+    );
+    await Promise.all(tasks);
+  }
+
+  private async write(
+    scope: SharedScope,
+    key: string,
+    encoded: EncodedValue,
+    operation: string,
+  ): Promise<void> {
+    const bucket = await writeBucket(scope, operation);
+    const bucketKey = makeBucketKey(bucket);
+    this.buckets.set(bucketKey, bucket);
+    const dirty =
+      this.dirtyBuckets.get(bucketKey) ?? new Map<string, EncodedValue>();
+    dirty.set(key, encoded);
+    this.dirtyBuckets.set(bucketKey, dirty);
+    this.scheduleFlush();
+  }
+
+  private enqueueWrite(
+    scope: SharedScope,
+    key: string,
+    encoded: EncodedValue,
+    operation: string,
+  ): void {
+    const pending = this.write(scope, key, encoded, operation)
+      .catch((error: unknown) => {
+        this.pendingWriteErrors.push(error);
+      })
+      .finally(() => {
+        this.pendingWrites.delete(pending);
+      });
+    this.pendingWrites.add(pending);
+  }
+
+  private async awaitPendingWrites(operation: string): Promise<void> {
+    if (this.pendingWrites.size > 0) {
+      await Promise.all(this.pendingWrites);
+    }
+    const error = this.pendingWriteErrors.shift();
+    if (error instanceof Error) throw error;
+    if (error) {
+      throw storageError(
+        "CASTLE_STORAGE_WRITE_FAILED",
+        "Queued shared storage write failed.",
+        operation,
+      );
+    }
+  }
+
+  private async queueRead<T extends Json>(
+    bucket: Bucket,
+    key: string,
+  ): Promise<T | null> {
+    const bucketKey = makeBucketKey(bucket);
+    let batch = this.readBatches.get(bucketKey);
+    if (!batch) {
+      batch = { bucket, reads: new Map(), scheduled: false };
+      this.readBatches.set(bucketKey, batch);
+    }
+    const reads = batch.reads.get(key) ?? [];
+    batch.reads.set(key, reads);
+    const promise = new Promise<Json | null>((resolve, reject) => {
+      reads.push({ resolve, reject });
+    });
+    if (!batch.scheduled) {
+      batch.scheduled = true;
+      queueMicrotask(() => {
+        void this.flushReadBatch(bucketKey);
+      });
+    }
+    return (await promise) as T | null;
+  }
+
+  private async flushReadBatch(bucketKey: string): Promise<void> {
+    const batch = this.readBatches.get(bucketKey);
+    if (!batch) return;
+    this.readBatches.delete(bucketKey);
+    const keys = Array.from(batch.reads.keys());
+    try {
+      const context = await currentContext("SharedStorage.get");
+      const data = await storageGraphql<SharedDeckStorageData>(
+        SHARED_DECK_STORAGE_QUERY,
+        sharedVariables(context.deckId, batch.bucket, { keys }),
+        "sharedDeckStorage",
+      );
+      this.resolveReadBatch(batch, data.sharedDeckStorage);
+    } catch (error) {
+      rejectReadBatch(batch, error);
+    }
+  }
+
+  private resolveReadBatch(batch: ReadBatch, blob: StorageBlob): void {
+    for (const [key, reads] of batch.reads) {
+      const encoded = this.peekDirty(batch.bucket, key) ?? blob[key] ?? null;
+      const value =
+        encoded === null
+          ? null
+          : decodeStorageValue(encoded, "SharedStorage.get");
+      for (const read of reads) read.resolve(value);
+    }
+  }
+
+  private async flushBucket(
+    bucketKey: string,
+    snapshot: Map<string, EncodedValue>,
+  ): Promise<void> {
+    if (snapshot.size === 0) return;
+    const bucket = this.buckets.get(bucketKey);
+    if (!bucket) return;
+    const context = await currentContext("SharedStorage.flush");
+    await storageGraphql<UpdateSharedDeckStorageData>(
+      UPDATE_SHARED_DECK_STORAGE_MUTATION,
+      sharedVariables(context.deckId, bucket, {
+        updates: updatesFromDirty(snapshot),
+      }),
+      "updateSharedDeckStorage",
+    );
+    const dirty = this.dirtyBuckets.get(bucketKey);
+    if (!dirty) return;
+    clearAcknowledgedDirty(dirty, snapshot);
+    if (dirty.size === 0) this.dirtyBuckets.delete(bucketKey);
+  }
+
+  private peekDirty(bucket: Bucket, key: string): EncodedValue | undefined {
+    return this.dirtyBuckets.get(makeBucketKey(bucket))?.get(key);
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+}
+
+export const Storage: StorageApi = new PrivateStorageImpl();
+export const SharedStorage: SharedStorageApi = new SharedStorageImpl();
+
+const DECK_STORAGE_QUERY = `
+  query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
+    deckStorage(deckId: $deckId, sessionId: $sessionId)
+  }
+`;
+
+const UPDATE_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateDeckStorage(
+    $deckId: ID!,
+    $updates: [DeckStorageUpdateInput!]!,
+    $sessionId: ID
+  ) {
+    updateDeckStorage(deckId: $deckId, updates: $updates, sessionId: $sessionId)
+  }
+`;
+
+const SHARED_DECK_STORAGE_QUERY = `
+  query CastleSharedDeckStorage(
+    $deckId: ID!,
+    $keys: [String!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    sharedDeckStorage(deckId: $deckId, keys: $keys, sessionId: $sessionId, userId: $userId)
+  }
+`;
+
+const UPDATE_SHARED_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateSharedDeckStorage(
+    $deckId: ID!,
+    $updates: [SharedDeckStorageUpdateInput!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    updateSharedDeckStorage(
+      deckId: $deckId,
+      updates: $updates,
+      sessionId: $sessionId,
+      userId: $userId
+    )
+  }
+`;
+
+async function currentContext(
+  operation: string,
+): Promise<{ deckId: string; sessionId?: string }> {
+  const deckId = await storageDeckId(operation);
+  const context = await getDeckContext();
+  return { deckId, sessionId: context.sessionId ?? undefined };
+}
+
+async function storageDeckId(operation: string): Promise<string> {
+  try {
+    return await requireDeckId(operation);
+  } catch (error) {
+    if (error instanceof CastleError && error.code === "MISSING_DECK_ID") {
+      throw storageError(
+        "CASTLE_STORAGE_MISSING_DECK_ID",
+        "Save this deck before using Castle storage.",
+        operation,
+      );
+    }
+    throw error;
+  }
+}
+
+async function storageGraphql<TData>(
+  query: string,
+  variables: Record<string, Json | undefined>,
+  operation: string,
+): Promise<TData> {
+  const token = await requireAuthToken(operation);
+  return graphqlRequest<TData>(query, variables, {
+    operation,
+    requireAuth: true,
+    token,
+  });
+}
+
+async function readBucket(
+  scope: SharedScope,
+  userOrKey: string,
+  maybeKey: string | undefined,
+  operation: string,
+): Promise<Bucket> {
+  assertScope(scope, operation);
+  if (scope === "deck") return withSession({ scope });
+  if (maybeKey) return withSession({ scope, userId: userOrKey });
+  return writeBucket(scope, operation);
+}
+
+async function writeBucket(
+  scope: SharedScope,
+  operation: string,
+): Promise<Bucket> {
+  assertScope(scope, operation);
+  if (scope === "deck") return withSession({ scope });
+  const auth = await getAuth();
+  if (!auth.userId) {
+    throw storageError(
+      "CASTLE_STORAGE_MISSING_USER_ID",
+      "Castle user id is required for user-scoped shared storage.",
+      operation,
+    );
+  }
+  return withSession({ scope, userId: auth.userId });
+}
+
+async function withSession(bucket: Bucket): Promise<Bucket> {
+  const context = await getDeckContext();
+  return { ...bucket, sessionId: context.sessionId ?? undefined };
+}
+
+function sharedVariables(
+  deckId: string,
+  bucket: Bucket,
+  extra: Record<string, Json | undefined>,
+): Record<string, Json | undefined> {
+  return {
+    deckId,
+    sessionId: bucket.sessionId,
+    userId: bucket.userId,
+    ...extra,
+  };
+}
+
+function updatesFromDirty(dirty: Map<string, EncodedValue>): StorageUpdate[] {
+  return Array.from(dirty, ([key, value]) => ({ key, value }));
+}
+
+function clearAcknowledgedDirty(
+  dirty: Map<string, EncodedValue>,
+  acknowledged: Map<string, EncodedValue>,
+): void {
+  for (const [key, value] of acknowledged) {
+    if (dirty.get(key) === value) dirty.delete(key);
+  }
+}
+
+function decodeStorageBlob(
+  blob: StorageBlob,
+  operation: string,
+): Map<string, Json> {
+  return new Map(
+    Object.entries(blob).map(([key, value]) => [
+      key,
+      decodeStorageValue(value, operation),
+    ]),
+  );
+}
+
+function decodeStorageValue(encoded: string, operation: string): Json {
+  try {
+    return JSON.parse(encoded) as Json;
+  } catch {
+    throw storageError(
+      "CASTLE_STORAGE_PARSE_FAILED",
+      "Stored Castle value is not valid JSON.",
+      operation,
+    );
+  }
+}
+
+function encodeStorageValue(value: Json, operation: string): string {
+  try {
+    assertJsonValue(value, new Set(), operation);
+    return JSON.stringify(value);
+  } catch (error) {
+    if (error instanceof CastleError) throw error;
+    throw storageError(
+      "CASTLE_STORAGE_SERIALIZE_FAILED",
+      "Castle storage values must be JSON.",
+      operation,
+    );
+  }
+}
+
+function assertJsonValue(
+  value: unknown,
+  seen: Set<object>,
+  operation: string,
+): void {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return;
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return;
+    throw storageError(
+      "CASTLE_STORAGE_SERIALIZE_FAILED",
+      "Castle storage numbers must be finite.",
+      operation,
+    );
+  }
+  if (Array.isArray(value)) {
+    assertJsonArray(value, seen, operation);
+    return;
+  }
+  if (typeof value === "object") {
+    assertJsonObject(value, seen, operation);
+    return;
+  }
+  throw storageError(
+    "CASTLE_STORAGE_SERIALIZE_FAILED",
+    "Castle storage values must be JSON.",
+    operation,
+  );
+}
+
+function assertJsonArray(
+  values: unknown[],
+  seen: Set<object>,
+  operation: string,
+): void {
+  if (seen.has(values)) {
+    throw storageError(
+      "CASTLE_STORAGE_SERIALIZE_FAILED",
+      "Castle storage values cannot be cyclic.",
+      operation,
+    );
+  }
+  seen.add(values);
+  for (const value of values) assertJsonValue(value, seen, operation);
+  seen.delete(values);
+}
+
+function assertJsonObject(
+  value: object,
+  seen: Set<object>,
+  operation: string,
+): void {
+  if (seen.has(value)) {
+    throw storageError(
+      "CASTLE_STORAGE_SERIALIZE_FAILED",
+      "Castle storage values cannot be cyclic.",
+      operation,
+    );
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw storageError(
+      "CASTLE_STORAGE_SERIALIZE_FAILED",
+      "Castle storage objects must be plain JSON.",
+      operation,
+    );
+  }
+  seen.add(value);
+  for (const child of Object.values(value))
+    assertJsonValue(child, seen, operation);
+  seen.delete(value);
+}
+
+function makeBucketKey(bucket: Bucket): string {
+  return `${bucket.scope}:${bucket.userId ?? ""}:${bucket.sessionId ?? ""}`;
+}
+
+function contextKey(deckId: string, sessionId: string | undefined): string {
+  return `${deckId}:${sessionId ?? ""}`;
+}
+
+function assertScope(
+  scope: string,
+  operation: string,
+): asserts scope is SharedScope {
+  if (scope !== "deck" && scope !== "user") {
+    throw storageError(
+      "CASTLE_STORAGE_INVALID_SCOPE",
+      'SharedStorage scope must be "deck" or "user".',
+      operation,
+    );
+  }
+}
+
+function rejectReadBatch(batch: ReadBatch, error: unknown): void {
+  for (const reads of batch.reads.values()) {
+    for (const read of reads) read.reject(error);
+  }
+}
+
+function storageError(
+  code: string,
+  message: string,
+  operation: string,
+): CastleError {
+  return new CastleError({ code, message, operation });
+}