castle-web-sdk 0.4.4 → 0.4.5

package/src/storage.ts

@@ -1,42 +1,15 @@
-import { getAuth, requireAuthToken } from "./auth";
-import { getDeckContext, requireDeckId } from "./context";
+import {
+  type SharedScope,
+  type StorageBlob,
+  type StorageUpdate,
+} from "./commands";
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
+import { hostRequest } from "./transport";
 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;
@@ -44,7 +17,9 @@ interface PendingRead {
 }
 
 interface ReadBatch {
-  bucket: Bucket;
+  bucketKey: string;
+  scope: SharedScope;
+  userId?: string;
   reads: Map<string, PendingRead[]>;
   scheduled: boolean;
 }
@@ -67,22 +42,24 @@ export interface SharedStorageApi {
   remove(scope: SharedScope, key: string): void;
 }
 
+// Per-player private storage. The host stamps deckId/sessionId, so one deck
+// session = one stable blob: load once, then serve reads from cache and batch
+// writes on a 2s flush. Dirty writes overlay the server blob so an in-flight
+// write isn't clobbered by the flush response.
 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");
+    await this.ensureLoaded();
     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.dirty.set(key, encodeStorageValue(value, "Storage.set"));
     this.scheduleFlush();
   }
 
@@ -92,30 +69,9 @@ class PrivateStorageImpl implements StorageApi {
     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> {
+  private ensureLoaded(): Promise<void> {
     if (!this.loadPromise) {
-      this.loadPromise = this.load(operation).catch((error: unknown) => {
+      this.loadPromise = this.load().catch((error: unknown) => {
         this.loadPromise = null;
         throw error;
       });
@@ -123,32 +79,27 @@ class PrivateStorageImpl implements StorageApi {
     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;
+  private async load(): Promise<void> {
+    const { blob } = await hostRequest("deckStorage.load", {});
+    this.cache = decodeStorageBlob(blob, "Storage.get");
     this.overlayDirty();
   }
 
-  private applyServerBlob(blob: StorageBlob, loadedContextKey: string): void {
+  private async flush(): Promise<void> {
+    if (this.dirty.size === 0) return;
+    const snapshot = new Map(this.dirty);
+    const { blob } = await hostRequest("deckStorage.update", {
+      updates: updatesFromDirty(snapshot),
+    });
     this.cache = decodeStorageBlob(blob, "Storage.flush");
-    this.loadedContextKey = loadedContextKey;
+    clearAcknowledgedDirty(this.dirty, snapshot);
+    this.overlayDirty();
   }
 
   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"));
-      }
+      if (encoded === null) this.cache.delete(key);
+      else this.cache.set(key, decodeStorageValue(encoded, "Storage.dirty"));
     }
   }
 
@@ -161,12 +112,14 @@ class PrivateStorageImpl implements StorageApi {
   }
 }
 
+// Cross-player storage. Writes always target the current player (the host
+// forces 'user'-scope writes to whoever is signed in), so dirty writes bucket
+// under a fixed key; reads of another player's 'user' bucket take an explicit
+// userId and never have pending writes. Reads coalesce per microtask into one
+// command with a keys[] array.
 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>(
@@ -174,54 +127,30 @@ class SharedStorageImpl implements SharedStorageApi {
     userOrKey: string,
     maybeKey?: string,
   ): Promise<T | null> {
-    const bucket = await readBucket(
-      scope,
-      userOrKey,
-      maybeKey,
-      "SharedStorage.get",
-    );
+    assertScope(scope, "SharedStorage.get");
+    const userId = scope === "user" && maybeKey ? userOrKey : undefined;
     const key = maybeKey ?? userOrKey;
-    await this.awaitPendingWrites("SharedStorage.get");
-    const dirty = this.peekDirty(bucket, key);
+    const dirty = this.peekDirty(scope, userId, key);
     if (dirty !== undefined) {
       return (
         dirty === null ? null : decodeStorageValue(dirty, "SharedStorage.get")
       ) as T | null;
     }
-    return this.queueRead<T>(bucket, key);
+    return this.queueRead<T>(scope, userId, key);
   }
 
   set(scope: SharedScope, key: string, value: Json): void {
-    this.enqueueWrite(
-      scope,
-      key,
-      encodeStorageValue(value, "SharedStorage.set"),
-      "SharedStorage.set",
-    );
+    assertScope(scope, "SharedStorage.set");
+    this.write(scope, key, encodeStorageValue(value, "SharedStorage.set"));
   }
 
   remove(scope: SharedScope, key: string): void {
-    this.enqueueWrite(scope, key, null, "SharedStorage.remove");
+    assertScope(scope, "SharedStorage.remove");
+    this.write(scope, key, null);
   }
 
-  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);
+  private write(scope: SharedScope, key: string, encoded: EncodedValue): void {
+    const bucketKey = writeBucketKey(scope);
     const dirty =
       this.dirtyBuckets.get(bucketKey) ?? new Map<string, EncodedValue>();
     dirty.set(key, encoded);
@@ -229,45 +158,24 @@ class SharedStorageImpl implements SharedStorageApi {
     this.scheduleFlush();
   }
 
-  private enqueueWrite(
+  private peekDirty(
     scope: SharedScope,
+    userId: string | undefined,
     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,
-      );
-    }
+  ): EncodedValue | undefined {
+    if (scope === "user" && userId) return undefined;
+    return this.dirtyBuckets.get(writeBucketKey(scope))?.get(key);
   }
 
-  private async queueRead<T extends Json>(
-    bucket: Bucket,
+  private queueRead<T extends Json>(
+    scope: SharedScope,
+    userId: string | undefined,
     key: string,
   ): Promise<T | null> {
-    const bucketKey = makeBucketKey(bucket);
+    const bucketKey = readBucketKey(scope, userId);
     let batch = this.readBatches.get(bucketKey);
     if (!batch) {
-      batch = { bucket, reads: new Map(), scheduled: false };
+      batch = { bucketKey, scope, userId, reads: new Map(), scheduled: false };
       this.readBatches.set(bucketKey, batch);
     }
     const reads = batch.reads.get(key) ?? [];
@@ -277,11 +185,9 @@ class SharedStorageImpl implements SharedStorageApi {
     });
     if (!batch.scheduled) {
       batch.scheduled = true;
-      queueMicrotask(() => {
-        void this.flushReadBatch(bucketKey);
-      });
+      queueMicrotask(() => void this.flushReadBatch(bucketKey));
     }
-    return (await promise) as T | null;
+    return promise as Promise<T | null>;
   }
 
   private async flushReadBatch(bucketKey: string): Promise<void> {
@@ -290,13 +196,12 @@ class SharedStorageImpl implements SharedStorageApi {
     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);
+      const { blob } = await hostRequest("sharedDeckStorage.load", {
+        scope: batch.scope,
+        userId: batch.userId ?? null,
+        keys,
+      });
+      this.resolveReadBatch(batch, blob);
     } catch (error) {
       rejectReadBatch(batch, error);
     }
@@ -304,7 +209,8 @@ class SharedStorageImpl implements SharedStorageApi {
 
   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 encoded =
+        this.peekDirty(batch.scope, batch.userId, key) ?? blob[key] ?? null;
       const value =
         encoded === null
           ? null
@@ -313,36 +219,34 @@ class SharedStorageImpl implements SharedStorageApi {
     }
   }
 
+  private async flush(): Promise<void> {
+    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 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",
-    );
+    await hostRequest("sharedDeckStorage.update", {
+      scope: scopeFromWriteKey(bucketKey),
+      updates: updatesFromDirty(snapshot),
+    });
     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();
+      void this.flush().catch(reportSharedStorageError);
     }, FLUSH_INTERVAL_MS);
   }
 }
@@ -350,130 +254,19 @@ class SharedStorageImpl implements SharedStorageApi {
 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 });
+// 'user'-scope writes/self-reads share one bucket (the host resolves the
+// current player); a 'user' read of someone else keys by their id.
+function writeBucketKey(scope: SharedScope): string {
+  return scope === "deck" ? "deck" : "user:self";
 }
 
-async function withSession(bucket: Bucket): Promise<Bucket> {
-  const context = await getDeckContext();
-  return { ...bucket, sessionId: context.sessionId ?? undefined };
+function readBucketKey(scope: SharedScope, userId: string | undefined): string {
+  if (scope === "deck") return "deck";
+  return userId ? `user:other:${userId}` : "user:self";
 }
 
-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 scopeFromWriteKey(bucketKey: string): SharedScope {
+  return bucketKey === "deck" ? "deck" : "user";
 }
 
 function updatesFromDirty(dirty: Map<string, EncodedValue>): StorageUpdate[] {
@@ -562,13 +355,7 @@ function assertJsonArray(
   seen: Set<object>,
   operation: string,
 ): void {
-  if (seen.has(values)) {
-    throw storageError(
-      "CASTLE_STORAGE_SERIALIZE_FAILED",
-      "Castle storage values cannot be cyclic.",
-      operation,
-    );
-  }
+  assertNotCyclic(values, seen, operation);
   seen.add(values);
   for (const value of values) assertJsonValue(value, seen, operation);
   seen.delete(values);
@@ -579,14 +366,8 @@ function assertJsonObject(
   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);
+  assertNotCyclic(value, seen, operation);
+  const prototype = Object.getPrototypeOf(value) as unknown;
   if (prototype !== Object.prototype && prototype !== null) {
     throw storageError(
       "CASTLE_STORAGE_SERIALIZE_FAILED",
@@ -600,12 +381,18 @@ function assertJsonObject(
   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 assertNotCyclic(
+  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,
+    );
+  }
 }
 
 function assertScope(
@@ -627,6 +414,10 @@ function rejectReadBatch(batch: ReadBatch, error: unknown): void {
   }
 }
 
+function reportSharedStorageError(error: unknown): void {
+  console.warn("Castle shared storage write failed", error);
+}
+
 function storageError(
   code: string,
   message: string,

package/src/time.ts

@@ -1,5 +1,5 @@
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
+import { hostRequest } from "./transport";
 import type { Json } from "./types";
 
 export type CastleClockZone = "player" | "Castle";
@@ -21,30 +21,12 @@ export interface CastleTimeApi {
   getServerDate(timezone?: CastleClockZone): Promise<CastleDateParts>;
 }
 
-interface ServerTimeQueryData {
-  serverTime: {
-    timestamp: number;
-    timezoneOffset: number;
-    castleEpochData: Json;
-  };
-}
-
 interface ServerTimeSnapshot {
   offsetSeconds: number;
   castleTimezoneOffsetMinutes: number;
   daysSinceCastleEpoch: Record<CastleClockZone, number>;
 }
 
-const SERVER_TIME_QUERY = `
-  query CastleServerTime {
-    serverTime {
-      timestamp
-      timezoneOffset
-      castleEpochData
-    }
-  }
-`;
-
 let serverTimeSnapshot: ServerTimeSnapshot | null = null;
 let serverTimePromise: Promise<ServerTimeSnapshot> | null = null;
 
@@ -84,25 +66,19 @@ async function syncServerTime(): Promise<ServerTimeSnapshot> {
 
 async function fetchServerTime(): Promise<ServerTimeSnapshot> {
   const operation = "Time.getServerTime";
-  const data = await graphqlRequest<ServerTimeQueryData>(
-    SERVER_TIME_QUERY,
-    undefined,
-    {
-      operation,
-    },
-  );
+  const data = await hostRequest("time.getServerTime", {});
   const timestamp = numberField(
-    data.serverTime.timestamp,
+    data.timestamp,
     "serverTime.timestamp",
     operation,
   );
   const timezoneOffset = numberField(
-    data.serverTime.timezoneOffset,
+    data.timezoneOffset,
     "serverTime.timezoneOffset",
     operation,
   );
   const epochData = jsonObject(
-    data.serverTime.castleEpochData,
+    data.castleEpochData,
     "serverTime.castleEpochData",
     operation,
   );