@dcl/sdk 7.28.1-34901226656.commit-44656ea → 7.28.1-34955459026.commit-7db2d46

package/src/server/storage/scene.ts

@@ -0,0 +1,270 @@
+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 { createWriteQueue } 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.
+   * @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
+   */
+  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
+   */
+  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 A promise that resolves to true if deleted, false if not found
+   */
+  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
+   */
+  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: set()/delete() drop the wrapper, detaching the pending GET so
+  // its stale response cannot overwrite the newer cache entry.
+  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> {
+    const baseUrl = await getStorageServerUrl()
+    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)
+      console.error(`Failed to set storage value '${key}': ${error}`)
+      return false
+    }
+
+    cache.set(key, { body })
+    return true
+  }
+
+  async function executeDelete(key: string): Promise<boolean> {
+    const baseUrl = await getStorageServerUrl()
+    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)
+      console.error(`Failed to delete storage value '${key}': ${error}`)
+      return false
+    }
+
+    cache.setAbsent(key)
+    return true
+  }
+
+  return {
+    async get<T = unknown>(key: string, options?: GetOptions): Promise<T | null> {
+      assertIsServer(MODULE_NAME)
+
+      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 {
+          const baseUrl = await getStorageServerUrl()
+          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
+            }
+            console.error(`Failed to get storage value '${key}': ${error}`)
+            return null
+          }
+
+          if (data && data.value !== undefined) {
+            // 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
+          }
+
+          // 200 with a missing value is ambiguous: neither a confirmed value
+          // nor a confirmed absence, so cache nothing.
+          return null
+        } 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)
+
+      const body = JSON.stringify({ value })
+      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)
+
+      // Invalidate immediately — even while the DELETE waits behind other
+      // writes, reads must not serve the doomed value, and a stale
+      // "unchanged" skip would lose a future write.
+      cache.delete(key)
+      inflightGets.delete(key)
+
+      return writes.enqueue(key, null, () => executeDelete(key), true)
+    },
+
+    async getValues(options?: GetValuesOptions): Promise<GetValuesResult> {
+      assertIsServer(MODULE_NAME)
+
+      const { prefix, limit, offset } = options ?? {}
+      const baseUrl = await getStorageServerUrl()
+      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 [error, response] = await wrapSignedFetch<GetValuesResult>({ url })
+
+      if (error) {
+        console.error(`Failed to get storage values: ${error}`)
+        return { data: [], pagination: { offset: 0, total: 0 } }
+      }
+
+      const data = response?.data ?? []
+
+      // 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 (entry.value !== undefined && !writes.isPending(entry.key) && 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/value-cache.ts

@@ -0,0 +1,92 @@
+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
+}
+
+/**
+ * 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 }>()
+
+  function insert(key: string, entry: CacheEntry): void {
+    // 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.isFinite(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.isFinite(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 {
+      entries.delete(key)
+    }
+  }
+}

package/src/server/storage/write-queue.ts

@@ -0,0 +1,131 @@
+/**
+ * A pending write operation. `body` is the serialized PUT payload, or null
+ * for a DELETE. Callers coalesced into the op share its promise.
+ * @internal
+ */
+interface PendingOp {
+  body: string | null
+  execute: (body: string | null) => Promise<boolean>
+  promise: Promise<boolean>
+  resolve: (result: boolean) => void
+}
+
+interface KeyState {
+  /** The op currently on the network. */
+  active: PendingOp
+  /** At most one queued op; later writes replace its payload (latest wins). */
+  queued?: PendingOp
+}
+
+/**
+ * Serializes writes per key so the service commits them in issue order.
+ * Overlapping PUTs from the single scene server would otherwise race: the
+ * server keeps whichever request it processes last, while the local cache
+ * keeps whichever response arrives last — either can disagree with the last
+ * set() issued. With at most one in-flight op per key and a single queued
+ * "latest value" slot, the server's final state always matches the last
+ * write issued, and N rapid writes collapse into at most 2 network calls.
+ * @internal
+ */
+export interface WriteQueue {
+  /**
+   * Body of the latest issued write for the key (the queued op if present,
+   * else the in-flight one): a string for a PUT, null for a DELETE,
+   * undefined when no write is pending.
+   */
+  pending(key: string): string | null | undefined
+  /** True while any write for the key is in flight or queued. */
+  isPending(key: string): boolean
+  /**
+   * Issues a write. If one is in flight, the new op is queued — replacing any
+   * already-queued op, whose callers then follow this op's outcome (their
+   * value was superseded before it could ever be observed). An op identical
+   * to the queued one joins it; `joinActive` additionally allows joining an
+   * identical in-flight op (only valid for dedup-tolerant callers, since that
+   * op was issued before this call).
+   */
+  enqueue(
+    key: string,
+    body: string | null,
+    execute: (body: string | null) => Promise<boolean>,
+    joinActive: boolean
+  ): Promise<boolean>
+}
+
+/**
+ * Creates the per-key write serializer shared by a storage scope.
+ * @internal
+ */
+export function createWriteQueue(): WriteQueue {
+  const keys = new Map<string, KeyState>()
+
+  function makeOp(body: string | null, execute: PendingOp['execute']): PendingOp {
+    let resolve!: (result: boolean) => void
+    const promise = new Promise<boolean>((r) => (resolve = r))
+    return { body, execute, promise, resolve }
+  }
+
+  async function drain(key: string, state: KeyState): Promise<void> {
+    for (;;) {
+      const op = state.active
+      let result = false
+      try {
+        result = await op.execute(op.body)
+      } catch {
+        // Executors report failures via their boolean result; a throw is
+        // unexpected but must not wedge the queue.
+      }
+      op.resolve(result)
+
+      if (state.queued) {
+        state.active = state.queued
+        state.queued = undefined
+      } else {
+        keys.delete(key)
+        return
+      }
+    }
+  }
+
+  return {
+    pending(key: string): string | null | undefined {
+      const state = keys.get(key)
+      if (!state) return undefined
+      return (state.queued ?? state.active).body
+    },
+
+    isPending(key: string): boolean {
+      return keys.has(key)
+    },
+
+    enqueue(key: string, body: string | null, execute: PendingOp['execute'], joinActive: boolean): Promise<boolean> {
+      const state = keys.get(key)
+
+      if (!state) {
+        const op = makeOp(body, execute)
+        const newState: KeyState = { active: op }
+        keys.set(key, newState)
+        void drain(key, newState)
+        return op.promise
+      }
+
+      if (state.queued) {
+        // A queued op has not started, so it is issued "after" this caller
+        // either way: join it when identical, supersede it otherwise.
+        if (state.queued.body !== body) {
+          state.queued.body = body
+          state.queued.execute = execute
+        }
+        return state.queued.promise
+      }
+
+      if (joinActive && state.active.body === body) {
+        return state.active.promise
+      }
+
+      const op = makeOp(body, execute)
+      state.queued = op
+      return op.promise
+    }
+  }
+}

package/src/server/storage-url.ts

@@ -0,0 +1,49 @@
+import { getRealm } from '~system/Runtime'
+
+const STORAGE_SERVER_ORG = 'https://storage.decentraland.org'
+const STORAGE_SERVER_ZONE = 'https://storage.decentraland.zone'
+
+async function resolveStorageServerUrl(): Promise<string> {
+  const { realmInfo } = await getRealm({})
+
+  if (!realmInfo) {
+    throw new Error('Unable to retrieve realm information')
+  }
+
+  // Local development / preview mode
+  if (realmInfo.isPreview) {
+    return realmInfo.baseUrl
+  }
+
+  // Staging / testing environment
+  if (realmInfo.baseUrl.includes('.zone')) {
+    return STORAGE_SERVER_ZONE
+  }
+
+  // Production environment
+  return STORAGE_SERVER_ORG
+}
+
+let memoizedUrl: Promise<string> | null = null
+
+/**
+ * Determines the correct storage server URL based on the current realm.
+ *
+ * - If `isPreview` is true, uses the realm's baseUrl (localhost)
+ * - If the realm's baseUrl contains `.zone`, uses storage.decentraland.zone
+ * - Otherwise, uses storage.decentraland.org (production)
+ *
+ * The realm never changes mid-session, so the result is memoized; a failed
+ * resolution is not memoized so transient getRealm errors can be retried.
+ *
+ * @returns The storage server base URL
+ */
+export function getStorageServerUrl(): Promise<string> {
+  if (!memoizedUrl) {
+    memoizedUrl = resolveStorageServerUrl()
+    memoizedUrl.catch(() => {
+      memoizedUrl = null
+    })
+  }
+  return memoizedUrl
+}

package/src/server/utils.ts

@@ -0,0 +1,76 @@
+import { signedFetch, SignedFetchRequest } from '~system/SignedFetch'
+import { isServer } from '../network'
+
+/**
+ * Validates that the code is running on a server-side scene.
+ * Throws an error if called from a client-side context.
+ *
+ * @param moduleName - The name of the module for the error message
+ * @throws Error if not running on a server-side scene
+ */
+export function assertIsServer(moduleName: string): void {
+  if (!isServer()) {
+    throw new Error(`${moduleName} is only available on server-side scenes`)
+  }
+}
+
+/**
+ * Result type for operations that can fail.
+ * Returns a tuple of [error, null] on failure or [null, data] on success.
+ */
+export type Result<T, E = string> = [E, null] | [null, T]
+
+/**
+ * Extended result type that includes HTTP status code information.
+ */
+export type FetchResult<T> = [string, null, number?] | [null, T, number]
+
+/**
+ * Wraps a promise to catch errors and return a Result tuple.
+ * This allows for cleaner error handling without try-catch blocks.
+ *
+ * @param promise - The promise to wrap
+ * @returns A tuple of [error, null] on failure or [null, data] on success
+ */
+export async function tryCatch<T, E = Error>(promise: Promise<T>): Promise<Result<T, E>> {
+  try {
+    const data = await promise
+    return [null, data]
+  } catch (error) {
+    return [error as E, null]
+  }
+}
+
+/**
+ * Wraps signedFetch with automatic error handling and JSON parsing.
+ * Returns a FetchResult tuple with parsed JSON data or error message and status code.
+ *
+ * @param signedFetchBody - The signedFetch request configuration
+ * @returns A tuple of [error, null, statusCode?] on failure or [null, data, statusCode] on success
+ */
+export async function wrapSignedFetch<T = unknown>(signedFetchBody: SignedFetchRequest): Promise<FetchResult<T>> {
+  const [error, response] = await tryCatch(signedFetch(signedFetchBody))
+
+  if (error) {
+    console.error(`Error in ${signedFetchBody.url} endpoint`, { error })
+    return [error.message, null, undefined]
+  }
+
+  if (!response.ok) {
+    const errorMessage = `${response.status} ${response.statusText}`
+    console.error(`Error in ${signedFetchBody.url} endpoint`, { response })
+    return [errorMessage, null, response.status]
+  }
+
+  let body: T
+  try {
+    // JSON.parse throws synchronously, so it can't be wrapped with tryCatch (the
+    // throw would happen while evaluating the argument, rejecting this promise).
+    body = JSON.parse(response.body || '{}')
+  } catch {
+    console.error(`Failed to parse response from ${signedFetchBody.url}`)
+    return ['Failed to parse response', null, response.status]
+  }
+
+  return [null, (body ?? {}) as T, response.status]
+}

package/src/testing/runtime.ts

@@ -50,6 +50,7 @@ export function createTestRuntime(testingModule: TestingModule, engine: IEngine)
   // continue to run until it reaches a yield point
   function scheduleValue(value: any, env: RunnerEnvironment) {
     if (value && typeof value === 'object' && typeof value.then === 'function') {
+      console.log('⏱️ yield promise')
       // if the value is a promise, schedule it to be awaited after the current frame is finished
       nextTickFuture.push(async () => {
         try {
@@ -59,12 +60,14 @@ export function createTestRuntime(testingModule: TestingModule, engine: IEngine)
         }
       })
     } else if (typeof value === 'function') {
+      console.log('⏱️ yield function')
       // if the value is a function, schedule it to be called on the next frame
       nextTickFuture.push(() => {
         scheduleValue(value(), env)
       })
       return
     } else if (typeof value === 'undefined' || value === null) {
+      console.log('⏱️ yield')
       // if the value is undefined or null, continue processing the generator the next frame
       nextTickFuture.push(() => {
         consumeGenerator(env)