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

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

@@ -0,0 +1,174 @@
+/**
+ * Rejection of a superseded delete when the write that replaced it did not apply.
+ * @internal
+ */
+export class SupersedingWriteFailed extends Error {
+  constructor() {
+    super('a write that replaced it did not apply')
+    this.name = 'SupersedingWriteFailed'
+  }
+}
+
+/**
+ * A pending write operation. `body` is the serialized PUT payload, or null
+ * for a DELETE. Callers that join the op share its promise.
+ */
+interface PendingOp {
+  body: string | null
+  execute: (body: string | null) => Promise<boolean>
+  promise: Promise<boolean>
+  resolve: (result: boolean) => void
+  reject: (error: unknown) => void
+}
+
+interface KeyState {
+  /** The op currently on the network. */
+  active: PendingOp
+  /** At most one queued op; a later write replaces it (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
+  /**
+   * Resolves once the in-flight op settles and, if one was queued at call time,
+   * the op that runs next. At most two, so writes cannot starve a waiter. Never rejects.
+   */
+  settled(key: string): Promise<void>
+  /**
+   * Issues a write, queued behind any in-flight one and replacing any queued one
+   * (see settleSuperseded). An identical queued op is joined; `joinActive` also
+   * joins an identical in-flight op, which only dedup-tolerant callers may do.
+   * Rejects with the executor's error; see settleSuperseded for replaced ops.
+   */
+  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
+    let reject!: (error: unknown) => void
+    const promise = new Promise<boolean>((res, rej) => {
+      resolve = res
+      reject = rej
+    })
+    return { body, execute, promise, resolve, reject }
+  }
+
+  /**
+   * A replaced op resolves true when its replacement lands. On failure a set
+   * resolves false and a delete rejects, in its own terms.
+   */
+  function settleSuperseded(superseded: PendingOp, by: PendingOp): void {
+    by.promise.then(
+      (result) => {
+        const applied = by.body === null || result
+        if (superseded.body !== null) superseded.resolve(applied)
+        else if (applied) superseded.resolve(true)
+        else superseded.reject(new SupersedingWriteFailed())
+      },
+      (error) => {
+        if (superseded.body === null) superseded.reject(error)
+        else superseded.resolve(false)
+      }
+    )
+  }
+
+  async function drain(key: string, state: KeyState): Promise<void> {
+    for (;;) {
+      const op = state.active
+      try {
+        op.resolve(await op.execute(op.body))
+      } catch (error) {
+        op.reject(error)
+      }
+
+      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)
+    },
+
+    async settled(key: string): Promise<void> {
+      const state = keys.get(key)
+      if (!state) return
+      const hadQueued = state.queued !== undefined
+      await state.active.promise.catch(() => undefined)
+      // drain() promotes the queued op (or its replacement) in place before this resumes.
+      if (hadQueued) await state.active.promise.catch(() => undefined)
+    },
+
+    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) return state.queued.promise
+        const op = makeOp(body, execute)
+        settleSuperseded(state.queued, op)
+        state.queued = op
+        return op.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,83 @@
+import { signedFetch, SignedFetchRequest } from '~system/SignedFetch'
+import { isServer } from '../network'
+import { errorMessage } from './storage/error-message'
+
+/**
+ * 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. Never rejects.
+ * 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>> {
+  let response: Awaited<ReturnType<typeof signedFetch>> | undefined
+  try {
+    response = await signedFetch(signedFetchBody)
+  } catch (error) {
+    console.error(`Error in ${signedFetchBody.url} endpoint`, { error })
+    return [errorMessage(error, 'signedFetch failed'), null, undefined]
+  }
+
+  if (!response) {
+    console.error(`Error in ${signedFetchBody.url} endpoint: no response`)
+    return ['signedFetch returned no response', 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]
+}