@dcl/sdk 7.26.0 → 7.26.1-31714079767.commit-96e9a29

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]
+}