@dcl/sdk 7.30.1 → 7.30.2-37807847179.commit-24c42ea

package/src/server/storage/scene.ts

@@ -0,0 +1,324 @@
+import { getStorageServerUrl } from '../storage-url'
+import { assertIsServer, wrapSignedFetch } from '../utils'
+import {
+  createStorageConfig,
+  GetOptions,
+  GetValuesOptions,
+  GetValuesResult,
+  MODULE_NAME,
+  SetOptions,
+  StorageConfigState
+} from './constants'
+import { createValueCache } from './value-cache'
+import { errorMessage } from './error-message'
+import { assertStorageKey, serializeStorageValue } from './serialize'
+import { createWriteQueue, SupersedingWriteFailed } from './write-queue'
+
+/**
+ * Scene-scoped storage interface for key-value pairs from the Server Side Storage service.
+ * This is NOT filesystem storage - data is stored in the remote storage service.
+ */
+export interface ISceneStorage {
+  /**
+   * Retrieves a value from scene storage by key from the Server Side Storage service.
+   *
+   * By default (cacheReads), values read or written during the last cacheMaxAgeMs
+   * are served from a local cache without a network request, including confirmed
+   * "not found" results. Concurrent gets for the same key share one request.
+   * Out-of-band writers (e.g. CLI storage commands) may not be visible for up to
+   * cacheMaxAgeMs — pass { fresh: true } to force a network read.
+   * A read first waits for writes to the same key that were pending when it was
+   * issued, so it reflects every write issued before it.
+   * @param key - The key to retrieve
+   * @param options - Optional { fresh } to bypass the read cache
+   * @returns A promise that resolves to the parsed JSON value, or null if not found
+   * @throws Error if the read fails, so a failure is never mistaken for a missing key
+   * @throws TypeError if the key is invalid
+   */
+  get<T = unknown>(key: string, options?: GetOptions): Promise<T | null>
+
+  /**
+   * Stores a value in scene storage in the Server Side Storage service.
+   * @param key - The key to store the value under
+   * @param value - The value to store (will be JSON serialized)
+   * @param options - Optional { skipIfUnchanged } to skip the network write when the value is already stored
+   * @returns true once stored, or once a newer write that replaced this one lands
+   * (rapid writes coalesce); false if the write, or its replacement, fails
+   * @throws TypeError if the key is invalid, or the value cannot be stored unchanged: undefined,
+   * circular, a BigInt, or containing a function, a symbol, a non-finite number, an undefined array
+   * element or hole, a Map, Set, typed array or other built-in with no JSON form, or text with an
+   * unpaired surrogate or a NUL character. An undefined object property is dropped; a Date is
+   * stored as its ISO string and a class instance as its own enumerable data.
+   */
+  set<T = unknown>(key: string, value: T, options?: SetOptions): Promise<boolean>
+
+  /**
+   * Deletes a value from scene storage in the Server Side Storage service.
+   * @param key - The key to delete
+   * @returns true once applied, or once a newer write that replaced it lands;
+   * false only for a confirmed 404
+   * @throws Error if the delete, or its replacement, fails; a failure is never reported as absence
+   * @throws TypeError if the key is invalid
+   */
+  delete(key: string): Promise<boolean>
+
+  /**
+   * Returns key-value entries from scene storage, optionally filtered by prefix.
+   * Supports pagination via limit and offset.
+   * @param options - Optional { prefix, limit, offset } for filtering and pagination.
+   * @returns A promise that resolves to { data, pagination: { offset, total } } for pagination UI
+   * @throws Error if the read fails, so a failure is never mistaken for an empty page
+   */
+  getValues(options?: GetValuesOptions): Promise<GetValuesResult>
+}
+
+/**
+ * Creates scene-scoped storage that provides methods to interact with
+ * scene-specific key-value pairs from the Server Side Storage service.
+ * This module only works when running on server-side scenes.
+ * @internal
+ */
+export const createSceneStorage = (config: StorageConfigState = createStorageConfig()): ISceneStorage => {
+  const cache = createValueCache(config)
+  // Each in-flight GET is tracked by a wrapper object whose identity marks
+  // ownership: a landed write detaches the pending GET so its stale response is not cached.
+  const inflightGets = new Map<string, { promise: Promise<unknown> }>()
+  // Writes to the same key are serialized (and rapid ones coalesced to the
+  // latest value) so the service commits them in issue order — overlapping
+  // PUTs would otherwise leave both the kept value and the cached value to
+  // response-order chance.
+  const writes = createWriteQueue()
+
+  async function executeSet(key: string, body: string): Promise<boolean> {
+    let baseUrl: string
+    try {
+      baseUrl = await getStorageServerUrl()
+    } catch (error) {
+      cache.delete(key)
+      console.error(`Failed to set storage value '${key}': ${errorMessage(error)}`)
+      return false
+    }
+    const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+    const [error] = await wrapSignedFetch({
+      url,
+      init: {
+        method: 'PUT',
+        headers: {
+          'content-type': 'application/json'
+        },
+        body
+      }
+    })
+
+    // Either way the entry changed server-side (or may have): detach any
+    // overlapping in-flight GET so its stale response is not cached.
+    inflightGets.delete(key)
+
+    if (error) {
+      // The PUT may have reached the server, so the cached body is no
+      // longer reliable.
+      cache.delete(key)
+      return false
+    }
+
+    cache.set(key, { body })
+    return true
+  }
+
+  async function executeDelete(key: string): Promise<boolean> {
+    let baseUrl: string
+    try {
+      baseUrl = await getStorageServerUrl()
+    } catch (error) {
+      cache.delete(key)
+      throw new Error(`Failed to delete storage value '${key}': ${errorMessage(error)}`)
+    }
+    const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+    const [error, , status] = await wrapSignedFetch({
+      url,
+      init: {
+        method: 'DELETE',
+        headers: {}
+      }
+    })
+
+    // Detach again: a GET may have started while the DELETE was in flight.
+    inflightGets.delete(key)
+
+    if (error) {
+      // A 404 still confirms the key is absent server-side.
+      if (status === 404) {
+        cache.setAbsent(key)
+        return false
+      }
+      // The DELETE may have reached the server, so the cached body is unreliable.
+      cache.delete(key)
+      throw new Error(`Failed to delete storage value '${key}': ${errorMessage(error)}`)
+    }
+
+    cache.setAbsent(key)
+    return true
+  }
+
+  return {
+    async get<T = unknown>(key: string, options?: GetOptions): Promise<T | null> {
+      assertIsServer(MODULE_NAME)
+      assertStorageKey(key, 'Storage.get()')
+
+      if (writes.isPending(key)) await writes.settled(key)
+
+      if (config.cacheReads && !options?.fresh) {
+        const entry = cache.get(key)
+        if (entry?.absent) return null
+        // Parse per hit so each caller gets a fresh object (no shared mutation).
+        if (entry?.body !== undefined) return JSON.parse(entry.body).value as T
+      }
+
+      // Coalesce concurrent gets (even fresh ones: an in-flight response is
+      // milliseconds old, not TTL-stale) into a single network request.
+      const joined = inflightGets.get(key)
+      if (joined) return joined.promise as Promise<T | null>
+
+      const inflight = {} as { promise: Promise<T | null> }
+      inflight.promise = (async () => {
+        try {
+          let baseUrl: string
+          try {
+            baseUrl = await getStorageServerUrl()
+          } catch (error) {
+            throw new Error(`Failed to get storage value '${key}': ${errorMessage(error)}`)
+          }
+          const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+          const [error, data, status] = await wrapSignedFetch<{ value: T }>({ url })
+
+          const isOwner = inflightGets.get(key) === inflight
+
+          if (error) {
+            // A confirmed 404 is a first-class "absent" outcome, not a failure.
+            if (status === 404) {
+              if (isOwner) cache.setAbsent(key)
+              return null
+            }
+            throw new Error(`Failed to get storage value '${key}': ${errorMessage(error)}`)
+          }
+
+          // wrapSignedFetch parses an empty 2xx body as {}: a missing value is a fault, not an absence.
+          if (!data || data.value === undefined) {
+            throw new Error(`Failed to get storage value '${key}': response carried no value`)
+          }
+
+          // Same serialization shape as set()'s PUT body, so a read followed by
+          // an unchanged write can be skipped.
+          const body = JSON.stringify({ value: data.value })
+          if (isOwner) cache.set(key, { body })
+          return data.value
+        } finally {
+          if (inflightGets.get(key) === inflight) inflightGets.delete(key)
+        }
+      })()
+
+      inflightGets.set(key, inflight)
+      return inflight.promise
+    },
+
+    async set<T = unknown>(key: string, value: T, options?: SetOptions): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+      assertStorageKey(key, 'Storage.set()')
+
+      const body = serializeStorageValue(value, `Storage.set('${key}')`)
+      const skipIfUnchanged = options?.skipIfUnchanged ?? config.skipIfUnchanged
+
+      // Dedup against confirmed state only while no write is pending — a
+      // pending write makes the cache momentarily stale; enqueue() coalesces
+      // against pending writes instead.
+      if (skipIfUnchanged && writes.pending(key) === undefined && cache.get(key)?.body === body) {
+        return true
+      }
+
+      return writes.enqueue(key, body, (b) => executeSet(key, b as string), skipIfUnchanged)
+    },
+
+    async delete(key: string): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+      assertStorageKey(key, 'Storage.delete()')
+
+      return writes
+        .enqueue(key, null, () => executeDelete(key), true)
+        .catch((error: unknown) => {
+          if (error instanceof SupersedingWriteFailed) {
+            throw new Error(`Failed to delete storage value '${key}': ${error.message}`)
+          }
+          throw error
+        })
+    },
+
+    async getValues(options?: GetValuesOptions): Promise<GetValuesResult> {
+      assertIsServer(MODULE_NAME)
+
+      const { prefix, limit, offset } = options ?? {}
+      let baseUrl: string
+      try {
+        baseUrl = await getStorageServerUrl()
+      } catch (error) {
+        throw new Error(`Failed to get storage values: ${errorMessage(error)}`)
+      }
+      const parts: string[] = []
+
+      if (!!prefix) {
+        parts.push(`prefix=${encodeURIComponent(prefix)}`)
+      }
+
+      if (!!limit) {
+        parts.push(`limit=${limit}`)
+      }
+
+      if (!!offset) {
+        parts.push(`offset=${offset}`)
+      }
+
+      const query = parts.join('&')
+      const url = query ? `${baseUrl}/values?${query}` : `${baseUrl}/values`
+
+      const watcher = cache.watch()
+      const [error, response] = await wrapSignedFetch<GetValuesResult>({ url })
+      watcher.stop()
+
+      if (error) {
+        throw new Error(`Failed to get storage values: ${errorMessage(error)}`)
+      }
+
+      const data = response?.data
+      if (!Array.isArray(data)) {
+        throw new Error('Failed to get storage values: response carried no data array')
+      }
+      if (data.some((entry) => typeof entry?.key !== 'string' || entry.value === undefined)) {
+        throw new Error('Failed to get storage values: response carried a malformed entry')
+      }
+
+      // Seed the per-key cache so subsequent get()/set() on returned keys can
+      // skip the network. Only keys with no live entry and no pending write
+      // are seeded: existing per-key state comes from a confirmed operation
+      // that this page snapshot — whose request started earlier — must not
+      // clobber with stale data. Absence is never seeded (prefix/pagination
+      // make it non-authoritative). A page larger than cacheMaxEntries churns
+      // the cache; entries repopulate lazily.
+      for (const entry of data) {
+        if (watcher.mutated(entry.key) || writes.isPending(entry.key) || inflightGets.has(entry.key)) continue
+        if (cache.get(entry.key) === undefined) {
+          cache.set(entry.key, { body: JSON.stringify({ value: entry.value }) })
+        }
+      }
+
+      const requestedOffset = offset ?? 0
+      const pagination = {
+        offset: response!.pagination?.offset ?? requestedOffset,
+        total: response!.pagination?.total ?? data.length
+      }
+
+      return { data, pagination }
+    }
+  }
+}

package/src/server/storage/serialize.ts

@@ -0,0 +1,132 @@
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/
+const UNSTORABLE_TEXT = /\u0000/
+const MAX_KEY_LENGTH = 255
+
+/**
+ * JSON.stringify always writes NUL as `\u0000` and an unpaired surrogate as a `\udXXX` escape (ES2019),
+ * while paired surrogates stay raw; an escaped backslash in front means the text is literal.
+ */
+const ESCAPED_UNSTORABLE_TEXT = /(?<!\\)(?:\\\\)*\\u(?:0000|d[89a-f][0-9a-f]{2})/i
+
+/** Raised from inside the replacer, so it is not mistaken for an engine error. */
+class UnstorableValueError extends TypeError {}
+
+type Reason = (holder: Record<string, unknown>, property: string, item: unknown) => string | undefined
+
+/**
+ * The `{ value }` PUT body. Rejects, at any depth, what JSON would drop or change: functions,
+ * symbols, non-finite numbers, `undefined` array elements and holes, built-ins with no JSON form
+ * (Map, Set, typed arrays, RegExp, Error, ...), and text the service cannot store. An `undefined`
+ * object property is dropped, as it reads back the same.
+ * @internal
+ */
+export function serializeStorageValue(value: unknown, callSite: string): string {
+  const body = stringify(value, callSite, fastReason)
+  // Text is checked once on the output; only a rejection pays for locating the offending item.
+  if (ESCAPED_UNSTORABLE_TEXT.test(body)) {
+    stringify(value, callSite, unstorable)
+    throw new TypeError(`${callSite}: value must not contain an unpaired surrogate or a NUL character.`)
+  }
+  if (body === '{}') {
+    throw new TypeError(`${callSite}: value must be JSON-serializable. Use delete() to remove a key.`)
+  }
+  return body
+}
+
+function stringify(value: unknown, callSite: string, reason: Reason): string {
+  const envelope = { value }
+  try {
+    return JSON.stringify(envelope, function (this: Record<string, unknown>, property, item) {
+      const why = reason(this, property, item)
+      if (why) {
+        const where = this === envelope ? 'the value' : `"${property}"`
+        throw new UnstorableValueError(
+          `${callSite}: value must be JSON-serializable, but ${where} ${why}. Use delete() to remove a key.`
+        )
+      }
+      return item
+    })
+  } catch (error) {
+    if (error instanceof UnstorableValueError) throw error
+    const cause = error instanceof Error ? error.message.split('\n')[0] : String(error)
+    throw new TypeError(`${callSite}: value must be JSON-serializable (${cause}). Use delete() to remove a key.`)
+  }
+}
+
+/** Everything but the text checks, with plain objects and arrays skipping the built-in check. */
+function fastReason(holder: Record<string, unknown>, property: string, item: unknown): string | undefined {
+  switch (typeof item) {
+    case 'function':
+    case 'symbol':
+      return `is a ${typeof item}`
+    case 'number':
+      return Number.isFinite(item) ? undefined : `is the non-finite number ${item}`
+    case 'undefined':
+      if (Array.isArray(holder)) return 'is undefined or a hole in an array'
+      return holder[property] !== undefined ? 'has a toJSON() that returns undefined' : undefined
+    case 'object': {
+      if (item === null || Array.isArray(item)) return undefined
+      const prototype = Object.getPrototypeOf(item)
+      return prototype === Object.prototype || prototype === null ? undefined : builtInReason(item)
+    }
+    default:
+      return undefined
+  }
+}
+
+/** Every check, per item: used to name the item a text rejection comes from. */
+function unstorable(holder: Record<string, unknown>, property: string, item: unknown): string | undefined {
+  const fast = fastReason(holder, property, item)
+  if (fast) return fast
+  if (typeof item === 'string' && (LONE_SURROGATE.test(item) || UNSTORABLE_TEXT.test(item))) {
+    return 'contains an unpaired surrogate or a NUL character'
+  }
+  if (!Array.isArray(holder) && (LONE_SURROGATE.test(property) || UNSTORABLE_TEXT.test(property))) {
+    return 'is a key with an unpaired surrogate or a NUL character'
+  }
+  return undefined
+}
+
+function builtInReason(item: unknown): string | undefined {
+  const builtIn = builtInName(item)
+  return builtIn ? `is ${/^[AEIO]/.test(builtIn) ? 'an' : 'a'} ${builtIn}, which has no JSON form` : undefined
+}
+
+function builtInName(item: unknown): string | undefined {
+  if (item === null || typeof item !== 'object') return undefined
+  if (item instanceof Map) return 'Map'
+  if (item instanceof Set) return 'Set'
+  if (item instanceof WeakMap) return 'WeakMap'
+  if (item instanceof WeakSet) return 'WeakSet'
+  if (item instanceof RegExp) return 'RegExp'
+  if (item instanceof Error) return 'Error'
+  if (item instanceof Promise) return 'Promise'
+  if (item instanceof ArrayBuffer) return 'ArrayBuffer'
+  if (ArrayBuffer.isView(item)) return item.constructor?.name ?? 'typed array'
+  return undefined
+}
+
+/**
+ * Keys and player addresses go into the request path, where `.`, `..` and an empty segment are
+ * resolved away by URL parsing, so they would address a different resource.
+ * @internal
+ */
+export function assertStorageKey(key: unknown, callSite: string): void {
+  if (typeof key !== 'string' || key === '' || key === '.' || key === '..') {
+    throw new TypeError(`${callSite}: key must be a non-empty string other than "." and "..".`)
+  }
+  if (LONE_SURROGATE.test(key) || UNSTORABLE_TEXT.test(key)) {
+    throw new TypeError(`${callSite}: key must not contain an unpaired surrogate or a NUL character.`)
+  }
+  // Counted in characters, as the service counts them.
+  if ([...key].length > MAX_KEY_LENGTH) {
+    throw new TypeError(`${callSite}: key must be at most ${MAX_KEY_LENGTH} characters.`)
+  }
+}
+
+/** @internal */
+export function assertPlayerAddress(address: unknown, callSite: string): void {
+  if (typeof address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    throw new TypeError(`${callSite}: address must be a 0x-prefixed 20-byte hex address.`)
+  }
+}

package/src/server/storage/value-cache.ts

@@ -0,0 +1,119 @@
+import { DEFAULT_STORAGE_CONFIG, StorageConfigState } from './constants'
+
+/**
+ * A cached fact about a key's server-side state.
+ * @internal
+ */
+export interface CacheEntry {
+  /**
+   * Serialized `{ value }` body; absent for negative entries. Parsed per read
+   * hit so callers never share object references, and compared verbatim for
+   * write dedup (exact equality — no hash-collision risk).
+   */
+  body?: string
+  /** True when the server confirmed the key does not exist (GET 404 or successful DELETE). */
+  absent?: boolean
+}
+
+/**
+ * Bounded, lazily-expiring cache of key states, backing both write dedup
+ * (skip storage writes whose value is already known to be stored) and read
+ * caching (serve get() without a network request within the TTL).
+ * @internal
+ */
+export interface ValueCache {
+  /** Returns the entry if present and fresh; lazily evicts expired entries. */
+  get(key: string): CacheEntry | undefined
+  /** Stores or refreshes a known value (serialized body); overwrites negative entries. */
+  set(key: string, entry: { body: string }): void
+  /** Stores a confirmed-absent (negative) entry, replacing any value entry. */
+  setAbsent(key: string): void
+  delete(key: string): void
+  /** Starts recording mutated keys, so a read issued earlier can tell its snapshot went stale. */
+  watch(): CacheWatcher
+}
+
+/**
+ * Keys mutated since the watch started. Always stop() it, or it keeps collecting.
+ * @internal
+ */
+export interface CacheWatcher {
+  mutated(key: string): boolean
+  stop(): void
+}
+
+/**
+ * Creates the bounded value cache shared by a storage scope.
+ * @internal
+ */
+export function createValueCache(config: StorageConfigState): ValueCache {
+  const entries = new Map<string, CacheEntry & { storedAt: number }>()
+  const watchers = new Set<Set<string>>()
+
+  function noteMutation(key: string): void {
+    for (const seen of watchers) seen.add(key)
+  }
+
+  function insert(key: string, entry: CacheEntry): void {
+    noteMutation(key)
+    // Delete + re-insert moves refreshed keys to the end of the Map's
+    // insertion order, so eviction below drops the least-recently-written.
+    entries.delete(key)
+    entries.set(key, { ...entry, storedAt: Date.now() })
+
+    // Guard against misconfiguration: a negative bound would loop forever on
+    // an empty map, and a NaN bound would silently disable eviction.
+    const maxEntries = !Number.isNaN(config.cacheMaxEntries)
+      ? Math.max(0, config.cacheMaxEntries)
+      : DEFAULT_STORAGE_CONFIG.cacheMaxEntries
+
+    while (entries.size > maxEntries) {
+      entries.delete(entries.keys().next().value!)
+    }
+  }
+
+  return {
+    get(key: string): CacheEntry | undefined {
+      const entry = entries.get(key)
+      if (!entry) return undefined
+
+      // Guard against misconfiguration, mirroring cacheMaxEntries: a NaN
+      // bound would silently disable expiry (NaN comparisons are false).
+      // Negative values need no guard — they just expire everything.
+      const maxAgeMs = !Number.isNaN(config.cacheMaxAgeMs) ? config.cacheMaxAgeMs : DEFAULT_STORAGE_CONFIG.cacheMaxAgeMs
+
+      // Lazy max-age expiry: storedAt is never refreshed on hits, so the age
+      // bounds the time since the last actual network confirmation.
+      if (Date.now() - entry.storedAt > maxAgeMs) {
+        entries.delete(key)
+        return undefined
+      }
+
+      return entry
+    },
+
+    set(key: string, entry: { body: string }): void {
+      insert(key, entry)
+    },
+
+    setAbsent(key: string): void {
+      insert(key, { absent: true })
+    },
+
+    delete(key: string): void {
+      noteMutation(key)
+      entries.delete(key)
+    },
+
+    watch(): CacheWatcher {
+      const seen = new Set<string>()
+      watchers.add(seen)
+      return {
+        mutated: (key: string) => seen.has(key),
+        stop: () => {
+          watchers.delete(seen)
+        }
+      }
+    }
+  }
+}