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

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

@@ -28,7 +28,7 @@ import {
   TriggerAreaResult,
   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,
@@ -79,9 +79,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)
     })
   }
 
@@ -103,7 +103,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,12 @@
+export { EnvVar } from './env-var'
+export {
+  Storage,
+  IStorage,
+  ISceneStorage,
+  IPlayerStorage,
+  GetOptions,
+  GetValuesOptions,
+  GetValuesResult,
+  SetOptions,
+  StorageOptions
+} from './storage'

package/src/server/storage/constants.ts

@@ -0,0 +1,111 @@
+export const MODULE_NAME = 'Storage'
+
+/**
+ * Options for getValues pagination and filtering.
+ */
+export interface GetValuesOptions {
+  prefix?: string
+  limit?: number
+  offset?: number
+}
+
+/**
+ * Result of getValues with pagination metadata.
+ */
+export interface GetValuesResult {
+  /** Key-value entries for the current page. */
+  data: Array<{ key: string; value: unknown }>
+  pagination: {
+    offset: number
+    total: number
+  }
+}
+
+/**
+ * Per-call options for Storage get().
+ */
+export interface GetOptions {
+  /**
+   * When true, bypasses the read cache and forces a network read (the result
+   * still refreshes the cache). Concurrent gets for the same key still share
+   * one in-flight request. Default: false.
+   */
+  fresh?: boolean
+}
+
+/**
+ * Per-call options for Storage set().
+ */
+export interface SetOptions {
+  /**
+   * When true, skips the network write if the serialized value matches the
+   * last value known to be stored for this key (from a previous successful
+   * set() or get()). Overrides the configured default. Default: true.
+   */
+  skipIfUnchanged?: boolean
+}
+
+/**
+ * Module-wide configuration for Storage, applied to both scene-scoped and
+ * player-scoped storage via Storage.configure().
+ */
+export interface StorageOptions {
+  /**
+   * Default for set()'s skipIfUnchanged when not passed per call. A skip only
+   * suppresses a proven no-op: the exact serialized value was confirmed stored
+   * by a previous network round-trip within cacheMaxAgeMs. Default: true.
+   */
+  skipIfUnchanged?: boolean
+  /**
+   * When true, get() serves values from the local cache within cacheMaxAgeMs,
+   * including confirmed "not found" results, without a network request.
+   * Out-of-band writers (e.g. CLI storage commands) may not be visible for up
+   * to cacheMaxAgeMs; pass { fresh: true } per call to force a network read.
+   * Default: true.
+   */
+  cacheReads?: boolean
+  /**
+   * Max cache entries per scope (scene / player) before oldest entries are
+   * evicted. Entries hold the serialized value body, so memory scales with
+   * value size — this bounds entry count, not bytes. Default: 512.
+   */
+  cacheMaxEntries?: number
+  /**
+   * Max age of a cache entry in milliseconds, bounding both read-cache
+   * staleness and write-dedup trust; older entries are treated as unknown.
+   * The default is deliberately short so out-of-band writers (CLI storage
+   * commands, dashboards) become visible within a minute, while still
+   * absorbing hot per-frame reads. Default: 60000 (1 minute).
+   */
+  cacheMaxAgeMs?: number
+}
+
+/**
+ * Fully-resolved storage configuration shared by scene and player storage.
+ * @internal
+ */
+export interface StorageConfigState {
+  skipIfUnchanged: boolean
+  cacheReads: boolean
+  cacheMaxEntries: number
+  cacheMaxAgeMs: number
+}
+
+/**
+ * Default values for the resolved storage configuration.
+ * @internal
+ */
+export const DEFAULT_STORAGE_CONFIG: Readonly<StorageConfigState> = {
+  skipIfUnchanged: true,
+  cacheReads: true,
+  cacheMaxEntries: 512,
+  cacheMaxAgeMs: 60 * 1000
+}
+
+/**
+ * Creates a mutable config object, later mutated by Storage.configure().
+ * @internal
+ */
+export function createStorageConfig(overrides?: StorageOptions): StorageConfigState {
+  return { ...DEFAULT_STORAGE_CONFIG, ...overrides }
+}

package/src/server/storage/index.ts

@@ -0,0 +1,74 @@
+import { createStorageConfig, StorageOptions } from './constants'
+import { createSceneStorage, ISceneStorage } from './scene'
+import { createPlayerStorage, IPlayerStorage } from './player'
+
+// Re-export interfaces and types
+export { GetOptions, GetValuesOptions, GetValuesResult, SetOptions, StorageOptions } from './constants'
+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
+
+  /**
+   * Sets module-wide defaults for both scene-scoped and player-scoped storage.
+   * Merges the given partial options into the current configuration.
+   * Note: cacheMaxEntries applies per scope (scene and player each keep their
+   * own cache) and bounds entry count, not bytes (entries hold serialized
+   * value bodies).
+   */
+  configure(options: StorageOptions): void
+}
+
+/**
+ * Creates the Storage module with scene-scoped and player-scoped storage.
+ */
+const createStorage = (): IStorage => {
+  const config = createStorageConfig()
+  const sceneStorage = createSceneStorage(config)
+  const playerStorage = createPlayerStorage(config)
+
+  return {
+    // Spread scene storage methods at top level
+    get: sceneStorage.get,
+    set: sceneStorage.set,
+    delete: sceneStorage.delete,
+    getValues: sceneStorage.getValues,
+    // Keep player as nested property
+    player: playerStorage,
+    configure(options: StorageOptions): void {
+      for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined) (config as unknown as Record<string, unknown>)[key] = value
+      }
+    }
+  }
+}
+
+/**
+ * Storage provides methods to store and retrieve key-value data from the
+ * Server Side Storage service.
+ *
+ * - Use Storage.get/set/delete/getValues for scene-scoped storage
+ * - Use Storage.player.get/set/delete/getValues for player-scoped storage
+ * - Use Storage.configure to change module-wide defaults (e.g. skipIfUnchanged, cacheReads)
+ *
+ * Reads are cached by default: get() serves values known from a network
+ * round-trip within the last cacheMaxAgeMs (including confirmed "not found"
+ * results) without hitting the service, and concurrent gets for the same key
+ * share one request. Overlapping writes to the same key are serialized so the
+ * service commits them in issue order, and rapid writes coalesce to the
+ * latest value; every set()/delete() resolves once its value (or the newer
+ * value that superseded it) is durably applied. By default (skipIfUnchanged)
+ * an unchanged set is skipped, but only when a previous confirmed round-trip
+ * proved the exact value is already stored. Out-of-band writers (e.g. CLI storage commands)
+ * may not be visible for up to cacheMaxAgeMs; use get(key, { fresh: true })
+ * for an authoritative read or Storage.configure({ cacheReads: false }) to
+ * disable read caching.
+ *
+ * This module only works when running on server-side scenes.
+ */
+export const Storage: IStorage = createStorage()