@dcl/sdk 7.20.0 → 7.20.1-21975617794.commit-7189140

package/src/network/server/utils.ts

@@ -0,0 +1,189 @@
+import { Entity } from '@dcl/ecs/dist/engine'
+import { CrdtMessageProtocol, NetworkParent } from '@dcl/ecs'
+import { ReceiveMessage } from '@dcl/ecs/dist/runtime/types'
+import { ReceiveNetworkMessage } from '@dcl/ecs/dist/systems/crdt/types'
+import { ByteBuffer, ReadWriteByteBuffer } from '@dcl/ecs/dist/serialization/ByteBuffer'
+import { AuthoritativePutComponentOperation, PutComponentOperation } from '@dcl/ecs/dist/serialization/crdt'
+import {
+  CrdtMessage,
+  CrdtMessageBody,
+  CrdtMessageHeader,
+  CrdtMessageType,
+  DeleteComponentMessage,
+  DeleteComponentNetworkMessage,
+  DeleteEntityMessage,
+  DeleteEntityNetworkMessage,
+  PutComponentMessage,
+  AuthoritativePutComponentMessage,
+  PutNetworkComponentMessage
+} from '@dcl/ecs/dist/serialization/crdt/types'
+import { DeleteComponent } from '@dcl/ecs/dist/serialization/crdt/deleteComponent'
+import { DeleteEntity } from '@dcl/ecs/dist/serialization/crdt/deleteEntity'
+import { INetowrkEntityType } from '@dcl/ecs/dist/components/types'
+import { PutNetworkComponentOperation } from '@dcl/ecs/dist/serialization/crdt/network/putComponentNetwork'
+import { DeleteComponentNetwork } from '@dcl/ecs/dist/serialization/crdt/network/deleteComponentNetwork'
+import { DeleteEntityNetwork } from '@dcl/ecs/dist/serialization/crdt/network/deleteEntityNetwork'
+import { TransformSchema, COMPONENT_ID as TransformComponentId } from '@dcl/ecs/dist/components/manual/Transform'
+
+export type NetworkMessage = (
+  | PutNetworkComponentMessage
+  | DeleteComponentNetworkMessage
+  | DeleteEntityNetworkMessage
+) & { messageBuffer: Uint8Array }
+
+export type RegularMessage = (
+  | PutComponentMessage
+  | AuthoritativePutComponentMessage
+  | DeleteComponentMessage
+  | DeleteEntityMessage
+) & {
+  messageBuffer: Uint8Array
+}
+export function readMessages(data: Uint8Array): (NetworkMessage | RegularMessage)[] {
+  const buffer = new ReadWriteByteBuffer(data)
+  const messages: (NetworkMessage | RegularMessage)[] = []
+  let header: CrdtMessageHeader | null
+  while ((header = CrdtMessageProtocol.getHeader(buffer))) {
+    const offset = buffer.currentReadOffset()
+    let message: CrdtMessage | undefined = undefined
+
+    // Network messages
+    if (header.type === CrdtMessageType.DELETE_COMPONENT_NETWORK) {
+      message = DeleteComponentNetwork.read(buffer)!
+    } else if (header.type === CrdtMessageType.PUT_COMPONENT_NETWORK) {
+      message = PutNetworkComponentOperation.read(buffer)!
+    } else if (header.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
+      message = DeleteEntityNetwork.read(buffer)!
+    }
+    // Regular messages
+    else if (header.type === CrdtMessageType.PUT_COMPONENT) {
+      message = PutComponentOperation.read(buffer)!
+    } else if (header.type === CrdtMessageType.AUTHORITATIVE_PUT_COMPONENT) {
+      message = AuthoritativePutComponentOperation.read(buffer)!
+    } else if (header.type === CrdtMessageType.DELETE_COMPONENT) {
+      message = DeleteComponent.read(buffer)!
+    } else if (header.type === CrdtMessageType.DELETE_ENTITY) {
+      message = DeleteEntity.read(buffer)!
+    } else {
+      // consume unknown messages
+      buffer.incrementReadOffset(header.length)
+    }
+
+    if (message) {
+      messages.push({
+        ...message,
+        messageBuffer: buffer.buffer().subarray(offset, buffer.currentReadOffset())
+      })
+    }
+  }
+  return messages
+}
+
+export function isNetworkMessage(message: ReceiveMessage): message is ReceiveNetworkMessage {
+  return [
+    CrdtMessageType.DELETE_COMPONENT_NETWORK,
+    CrdtMessageType.DELETE_ENTITY_NETWORK,
+    CrdtMessageType.PUT_COMPONENT_NETWORK
+  ].includes(message.type)
+}
+
+export function networkMessageToLocal(
+  message: ReceiveNetworkMessage,
+  localEntityId: Entity,
+  destinationBuffer: ByteBuffer,
+  // Optional network parent component for transform fixing
+  networkParentComponent?: typeof NetworkParent,
+  // Force corrections - converts PUT_COMPONENT_NETWORK to authoritative_PUT_COMPONENT
+  forceCorrections = false
+): CrdtMessageBody {
+  if (message.type === CrdtMessageType.PUT_COMPONENT_NETWORK) {
+    let messageData = message.data
+
+    // Fix transform parent if needed for Unity/engine processing
+    if (message.componentId === TransformComponentId && networkParentComponent) {
+      const parentNetwork = networkParentComponent.getOrNull(localEntityId)
+      messageData = fixTransformParent(message, parentNetwork?.entityId)
+    }
+    if (forceCorrections) {
+      // Use AUTHORITATIVE_PUT_COMPONENT for forced state updates
+      AuthoritativePutComponentOperation.write(
+        localEntityId,
+        message.timestamp,
+        message.componentId,
+        messageData,
+        destinationBuffer
+      )
+      return {
+        type: CrdtMessageType.AUTHORITATIVE_PUT_COMPONENT,
+        componentId: message.componentId,
+        timestamp: message.timestamp,
+        data: messageData,
+        entityId: localEntityId
+      }
+    } else {
+      // Normal PUT_COMPONENT conversion
+      PutComponentOperation.write(localEntityId, message.timestamp, message.componentId, messageData, destinationBuffer)
+      return {
+        type: CrdtMessageType.PUT_COMPONENT,
+        componentId: message.componentId,
+        timestamp: message.timestamp,
+        data: messageData,
+        entityId: localEntityId
+      }
+    }
+  } else if (message.type === CrdtMessageType.DELETE_COMPONENT_NETWORK) {
+    DeleteComponent.write(localEntityId, message.componentId, message.timestamp, destinationBuffer)
+    return {
+      type: CrdtMessageType.DELETE_COMPONENT,
+      componentId: message.componentId,
+      timestamp: message.timestamp,
+      entityId: localEntityId
+    }
+  } else if (message.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
+    DeleteEntity.write(localEntityId, destinationBuffer)
+    return {
+      type: CrdtMessageType.DELETE_ENTITY,
+      entityId: localEntityId
+    }
+  }
+  throw 1
+}
+
+export function localMessageToNetwork(
+  message: ReceiveMessage,
+  network: INetowrkEntityType,
+  destinationBuffer: ByteBuffer
+) {
+  if (message.type === CrdtMessageType.PUT_COMPONENT) {
+    PutNetworkComponentOperation.write(
+      network.entityId,
+      message.timestamp,
+      message.componentId,
+      network.networkId,
+      message.data,
+      destinationBuffer
+    )
+  } else if (message.type === CrdtMessageType.DELETE_COMPONENT) {
+    DeleteComponentNetwork.write(
+      network.entityId,
+      message.componentId,
+      message.timestamp,
+      network.networkId,
+      destinationBuffer
+    )
+  } else if (message.type === CrdtMessageType.DELETE_ENTITY) {
+    DeleteEntityNetwork.write(network.entityId, network.networkId, destinationBuffer)
+  }
+}
+
+export function fixTransformParent(message: ReceiveMessage, parent?: Entity): Uint8Array {
+  const buffer = new ReadWriteByteBuffer()
+  const transform = 'data' in message && TransformSchema.deserialize(new ReadWriteByteBuffer(message.data))
+
+  if (!transform) throw new Error('Invalid parent transform')
+
+  // Generate new transform raw data with the parent
+  const newTransform = { ...transform, parent }
+  TransformSchema.serialize(newTransform, buffer)
+  return buffer.toBinary()
+}

package/src/network/state.ts

@@ -25,7 +25,7 @@ import {
   UiTransform,
   ComponentDefinition
 } from '@dcl/ecs'
-import { LIVEKIT_MAX_SIZE } from '@dcl/ecs/dist/systems/crdt'
+import { LIVEKIT_MAX_SIZE } from './server'
 
 export const NOT_SYNC_COMPONENTS: ComponentDefinition<unknown>[] = [
   VideoEvent,
@@ -72,9 +72,9 @@ export function engineToCrdt(engine: IEngine): Uint8Array[] {
     if (!shouldSyncComponent(itComponentDefinition)) {
       continue
     }
+
     itComponentDefinition.dumpCrdtStateToBuffer(crdtBuffer, (entity) => {
-      const isNetworkEntity = NetworkEntity.has(entity)
-      return isNetworkEntity
+      return NetworkEntity.has(entity)
     })
   }
 
@@ -96,7 +96,6 @@ export function engineToCrdt(engine: IEngine): Uint8Array[] {
         }
 
         // If the message itself is larger than the limit, we need to handle it specially
-        // For now, we'll skip it to prevent infinite loops
         if (messageSize / 1024 > LIVEKIT_MAX_SIZE) {
           console.error(
             `Message too large (${messageSize} bytes), skipping component ${message.componentId} for entity ${message.entityId}`

package/src/server/env-var.ts

@@ -0,0 +1,36 @@
+import { getStorageServerUrl } from './storage-url'
+import { assertIsServer, wrapSignedFetch } from './utils'
+
+const MODULE_NAME = 'EnvVar'
+
+/**
+ * EnvVar provides methods to fetch environment variables from the
+ * Server Side Storage service. This module only works when running
+ * on server-side scenes.
+ */
+export const EnvVar = {
+  /**
+   * Fetches a specific environment variable by key as plain text.
+   *
+   * @param key - The name of the environment variable to fetch
+   * @returns A promise that resolves to the plain text value, or empty string if not found
+   * @throws Error if not running on a server-side scene
+   */
+  async get(key: string): Promise<string> {
+    assertIsServer(MODULE_NAME)
+
+    const baseUrl = await getStorageServerUrl()
+    const url = `${baseUrl}/env/${encodeURIComponent(key)}`
+
+    const [error, data] = await wrapSignedFetch<{ value: string }>({
+      url
+    })
+
+    if (error) {
+      console.error(`Failed to fetch environment variable '${key}': ${error}`)
+      return ''
+    }
+
+    return data?.value ?? ''
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export { EnvVar } from './env-var'
+export { Storage, IStorage, ISceneStorage, IPlayerStorage } from './storage'

package/src/server/storage/constants.ts

@@ -0,0 +1 @@
+export const MODULE_NAME = 'Storage'

package/src/server/storage/index.ts

@@ -0,0 +1,42 @@
+import { createSceneStorage, ISceneStorage } from './scene'
+import { createPlayerStorage, IPlayerStorage } from './player'
+
+// Re-export interfaces
+export { ISceneStorage } from './scene'
+export { IPlayerStorage } from './player'
+
+/**
+ * Storage interface with methods for scene-scoped and player-scoped storage.
+ */
+export interface IStorage extends ISceneStorage {
+  /** Player-scoped storage for key-value pairs */
+  player: IPlayerStorage
+}
+
+/**
+ * Creates the Storage module with scene-scoped and player-scoped storage.
+ */
+const createStorage = (): IStorage => {
+  const sceneStorage = createSceneStorage()
+  const playerStorage = createPlayerStorage()
+
+  return {
+    // Spread scene storage methods at top level
+    get: sceneStorage.get,
+    set: sceneStorage.set,
+    delete: sceneStorage.delete,
+    // Keep player as nested property
+    player: playerStorage
+  }
+}
+
+/**
+ * Storage provides methods to store and retrieve key-value data from the
+ * Server Side Storage service.
+ *
+ * - Use Storage.get/set/delete for scene-scoped storage
+ * - Use Storage.player.get/set/delete for player-scoped storage
+ *
+ * This module only works when running on server-side scenes.
+ */
+export const Storage: IStorage = createStorage()

package/src/server/storage/player.ts

@@ -0,0 +1,106 @@
+import { getStorageServerUrl } from '../storage-url'
+import { assertIsServer, wrapSignedFetch } from '../utils'
+import { MODULE_NAME } from './constants'
+
+/**
+ * Player-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 IPlayerStorage {
+  /**
+   * Retrieves a value from a player's storage by key from the Server Side Storage service.
+   * @param address - The player's wallet address
+   * @param key - The key to retrieve
+   * @returns A promise that resolves to the parsed JSON value, or null if not found
+   */
+  get<T = unknown>(address: string, key: string): Promise<T | null>
+
+  /**
+   * Stores a value in a player's storage in the Server Side Storage service.
+   * @param address - The player's wallet address
+   * @param key - The key to store the value under
+   * @param value - The value to store (will be JSON serialized)
+   * @returns A promise that resolves to true if successful, false otherwise
+   */
+  set<T = unknown>(address: string, key: string, value: T): Promise<boolean>
+
+  /**
+   * Deletes a value from a player's storage in the Server Side Storage service.
+   * @param address - The player's wallet address
+   * @param key - The key to delete
+   * @returns A promise that resolves to true if deleted, false if not found
+   */
+  delete(address: string, key: string): Promise<boolean>
+}
+
+/**
+ * Creates player-scoped storage that provides methods to interact with
+ * player-specific key-value pairs from the Server Side Storage service.
+ * This module only works when running on server-side scenes.
+ */
+export const createPlayerStorage = (): IPlayerStorage => {
+  return {
+    async get<T = unknown>(address: string, key: string): Promise<T | null> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+
+      const [error, data] = await wrapSignedFetch<{ value: T }>({ url })
+
+      if (error) {
+        console.error(`Failed to get player storage value '${key}' for '${address}': ${error}`)
+        return null
+      }
+
+      return data?.value ?? null
+    },
+
+    async set<T = unknown>(address: string, key: string, value: T): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+
+      const [error] = await wrapSignedFetch({
+        url,
+        init: {
+          method: 'PUT',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify({ value })
+        }
+      })
+
+      if (error) {
+        console.error(`Failed to set player storage value '${key}' for '${address}': ${error}`)
+        return false
+      }
+
+      return true
+    },
+
+    async delete(address: string, key: string): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/players/${encodeURIComponent(address)}/values/${encodeURIComponent(key)}`
+
+      const [error] = await wrapSignedFetch({
+        url,
+        init: {
+          method: 'DELETE',
+          headers: {}
+        }
+      })
+
+      if (error) {
+        console.error(`Failed to delete player storage value '${key}' for '${address}': ${error}`)
+        return false
+      }
+
+      return true
+    }
+  }
+}

package/src/server/storage/scene.ts

@@ -0,0 +1,102 @@
+import { getStorageServerUrl } from '../storage-url'
+import { assertIsServer, wrapSignedFetch } from '../utils'
+import { MODULE_NAME } from './constants'
+
+/**
+ * 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.
+   * @param key - The key to retrieve
+   * @returns A promise that resolves to the parsed JSON value, or null if not found
+   */
+  get<T = unknown>(key: string): 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)
+   */
+  set<T = unknown>(key: string, value: T): 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>
+}
+
+/**
+ * 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.
+ */
+export const createSceneStorage = (): ISceneStorage => {
+  return {
+    async get<T = unknown>(key: string): Promise<T | null> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+      const [error, data] = await wrapSignedFetch<{ value: T }>({ url })
+
+      if (error) {
+        console.error(`Failed to get storage value '${key}': ${error}`)
+        return null
+      }
+
+      return data?.value ?? null
+    },
+
+    async set<T = unknown>(key: string, value: T): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+      const [error] = await wrapSignedFetch({
+        url,
+        init: {
+          method: 'PUT',
+          headers: {
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify({ value })
+        }
+      })
+
+      if (error) {
+        console.error(`Failed to set storage value '${key}': ${error}`)
+        return false
+      }
+
+      return true
+    },
+
+    async delete(key: string): Promise<boolean> {
+      assertIsServer(MODULE_NAME)
+
+      const baseUrl = await getStorageServerUrl()
+      const url = `${baseUrl}/values/${encodeURIComponent(key)}`
+
+      const [error] = await wrapSignedFetch({
+        url,
+        init: {
+          method: 'DELETE',
+          headers: {}
+        }
+      })
+
+      if (error) {
+        console.error(`Failed to delete storage value '${key}': ${error}`)
+        return false
+      }
+
+      return true
+    }
+  }
+}

package/src/server/storage-url.ts

@@ -0,0 +1,34 @@
+import { getRealm } from '~system/Runtime'
+
+const STORAGE_SERVER_ORG = 'https://storage.decentraland.org'
+const STORAGE_SERVER_ZONE = 'https://storage.decentraland.zone'
+
+/**
+ * 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)
+ *
+ * @returns The storage server base URL
+ */
+export async function getStorageServerUrl(): 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
+}

package/src/server/utils.ts

@@ -0,0 +1,73 @@
+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]
+  }
+
+  const [parseError, body] = await tryCatch<T>(JSON.parse(response.body || '{}'))
+
+  if (parseError) {
+    console.error(`Failed to parse response from ${signedFetchBody.url}`)
+    return ['Failed to parse response', null, response.status]
+  }
+
+  return [null, (body ?? {}) as T, response.status]
+}