dcl-catalyst-client 22.0.0 → 22.0.1-38482794215.commit-a4a4e71

package/README.md

@@ -15,3 +15,50 @@ npm install dcl-catalyst-client
 ### Examples
 
 Please check the [examples repository](https://github.com/decentraland/catalyst-client-examples)
+
+### Partial (batched) deployments
+
+For entities too large to upload in a single request, use `deployPartial`. It splits the content into
+size-bounded batches and uploads them across several `POST /entities` requests; the entity only becomes
+live once the server has all of it (the server finalizes automatically on the completing request).
+
+```ts
+const result = await client.deployPartial(
+  { entityId, authChain, files },
+  {
+    // default: 100 MiB per request — requests larger than ~200MB are timed out by the
+    // infrastructure in front of the content servers, so keep a margin under that.
+    maxBatchSizeBytes: 100 * 1024 * 1024,
+    concurrency: 2, // default: 2 parallel batch uploads (after the first)
+    maxResumeAttempts: 3, // default: 3 — resumes on network/5xx failures
+    onProgress: ({ uploadedBytes, totalBytes }) => console.log(`${uploadedBytes}/${totalBytes}`),
+    // byte-level progress, also accepted by deploy()
+    onUploadProgress: ({ phase, sentBytes, totalBytes }) => console.log(phase, `${sentBytes}/${totalBytes}`)
+  }
+)
+console.log(result.creationTimestamp)
+```
+
+Notes:
+
+- Use the regular `deploy()` for normal-sized deployments; it accepts `onUploadProgress` too.
+- `onUploadProgress` reports file bytes handed to the HTTP client across every request, in the phases
+  `checking` (asking the server which files it has), `uploading` and `processing` (every scheduled byte
+  sent, waiting for the server). Events are throttled to one every 200 ms, plus every phase change and the
+  latest count at the end of each window. A resolved deployment ends with `processing` and every byte sent.
+  Re-sent content (retries, the server's missing list) grows `totalBytes`.
+- By default a request's bytes count when its response arrives. For live progress, create the client with
+  `streamingUploads: true`: on Node the body is then streamed with an exact `Content-Length`, at the cost of
+  memory: each request in flight holds its form plus an encoded copy of it, about twice the batch size, so
+  `deployPartial` with the default `concurrency` (2) and 100 MiB batches holds up to ~400 MiB on top of the
+  scene's files. Only set it when the fetcher passes the body to the global
+  (undici) `fetch`, forwards the `duplex` option and headers unchanged, and never retries a POST with the
+  same options (the stream can only be read once). `@dcl/fetch-component` qualifies; node-fetch does not.
+- The target server must support partial deployments. Against an older server that does not, a
+  single-batch deployment still succeeds, but a multi-batch one rejects with
+  `PartialDeploymentNotSupportedError` — fall back to `deploy()` in that case.
+- A validation failure on the finalizing request (e.g. exceeding the size budget) rejects with
+  `PartialDeploymentValidationError`.
+- Files are never split across requests: a single file larger than the batch cap is sent alone in its
+  own request. Per-file server caps still apply to it, and a request beyond ~200MB may be timed out by
+  the infrastructure regardless of the configured cap.

package/dist/client/CatalystClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CatalystClient.d.ts","sourceRoot":"","sources":["../../src/client/CatalystClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAGvC,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAC5B,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1C,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;CAC3C,CAAA;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CA4D3E"}
+{"version":3,"file":"CatalystClient.d.ts","sourceRoot":"","sources":["../../src/client/CatalystClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAGvC,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAC5B,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1C,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;CAC3C,CAAA;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CA6D3E"}

package/dist/client/CatalystClient.js

@@ -28,7 +28,8 @@ function createCatalystClient(options) {
         }
         contentClient = (0, ContentClient_1.createContentClient)({
             url: about.content.publicUrl,
-            fetcher
+            fetcher,
+            streamingUploads: options.streamingUploads
         });
         return contentClient;
     }

package/dist/client/CatalystClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"CatalystClient.js","sourceRoot":"","sources":["../../src/client/CatalystClient.ts"],"names":[],"mappings":";;;AAAA,mDAAoE;AACpE,mDAAoE;AAGpE,2CAA4C;AAQ5C,SAAgB,oBAAoB,CAAC,OAAsB;IACzD,MAAM,WAAW,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC5C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAE3B,IAAI,aAAa,GAA8B,SAAS,CAAA;IACxD,IAAI,aAAa,GAA8B,SAAS,CAAA;IACxD,IAAI,KAAK,GAAsB,SAAS,CAAA;IAExC,KAAK,UAAU,UAAU;QACvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG,QAAQ,CAAC,CAAA;QAC1D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAEpC,IAAI,CAAC,QAAQ,EAAE;YACb,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;SAC1C;QAED,KAAK,GAAG,QAAQ,CAAA;QAEhB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,KAAK,UAAU,gBAAgB;QAC7B,IAAI,aAAa,EAAE;YACjB,OAAO,aAAa,CAAA;SACrB;QAED,IAAI,CAAC,KAAK,EAAE;YACV,KAAK,GAAG,MAAM,UAAU,EAAE,CAAA;SAC3B;QAED,aAAa,GAAG,IAAA,mCAAmB,EAAC;YAClC,GAAG,EAAE,KAAK,CAAC,OAAQ,CAAC,SAAS;YAC7B,OAAO;SACR,CAAC,CAAA;QAEF,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,KAAK,UAAU,gBAAgB;QAC7B,IAAI,aAAa,EAAE;YACjB,OAAO,aAAa,CAAA;SACrB;QAED,IAAI,CAAC,KAAK,EAAE;YACV,KAAK,GAAG,MAAM,UAAU,EAAE,CAAA;SAC3B;QAED,aAAa,GAAG,IAAA,mCAAmB,EAAC;YAClC,GAAG,EAAE,KAAK,CAAC,OAAQ,CAAC,SAAS;YAC7B,OAAO;SACR,CAAC,CAAA;QAEF,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,OAAO;QACL,UAAU;QACV,gBAAgB;QAChB,gBAAgB;KACjB,CAAA;AACH,CAAC;AA5DD,oDA4DC"}
+{"version":3,"file":"CatalystClient.js","sourceRoot":"","sources":["../../src/client/CatalystClient.ts"],"names":[],"mappings":";;;AAAA,mDAAoE;AACpE,mDAAoE;AAGpE,2CAA4C;AAQ5C,SAAgB,oBAAoB,CAAC,OAAsB;IACzD,MAAM,WAAW,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC5C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAE3B,IAAI,aAAa,GAA8B,SAAS,CAAA;IACxD,IAAI,aAAa,GAA8B,SAAS,CAAA;IACxD,IAAI,KAAK,GAAsB,SAAS,CAAA;IAExC,KAAK,UAAU,UAAU;QACvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG,QAAQ,CAAC,CAAA;QAC1D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAEpC,IAAI,CAAC,QAAQ,EAAE;YACb,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;SAC1C;QAED,KAAK,GAAG,QAAQ,CAAA;QAEhB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,KAAK,UAAU,gBAAgB;QAC7B,IAAI,aAAa,EAAE;YACjB,OAAO,aAAa,CAAA;SACrB;QAED,IAAI,CAAC,KAAK,EAAE;YACV,KAAK,GAAG,MAAM,UAAU,EAAE,CAAA;SAC3B;QAED,aAAa,GAAG,IAAA,mCAAmB,EAAC;YAClC,GAAG,EAAE,KAAK,CAAC,OAAQ,CAAC,SAAS;YAC7B,OAAO;YACP,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC,CAAA;QAEF,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,KAAK,UAAU,gBAAgB;QAC7B,IAAI,aAAa,EAAE;YACjB,OAAO,aAAa,CAAA;SACrB;QAED,IAAI,CAAC,KAAK,EAAE;YACV,KAAK,GAAG,MAAM,UAAU,EAAE,CAAA;SAC3B;QAED,aAAa,GAAG,IAAA,mCAAmB,EAAC;YAClC,GAAG,EAAE,KAAK,CAAC,OAAQ,CAAC,SAAS;YAC7B,OAAO;SACR,CAAC,CAAA;QAEF,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,OAAO;QACL,UAAU;QACV,gBAAgB;QAChB,gBAAgB;KACjB,CAAA;AACH,CAAC;AA7DD,oDA6DC"}

package/dist/client/ContentClient.d.ts

@@ -1,5 +1,5 @@
 import { Entity } from '@dcl/schemas';
-import { ClientOptions, DeploymentData, IFetchComponent, ParallelConfig, RequestOptions } from './types';
+import { ClientOptions, DeploymentData, IFetchComponent, ParallelConfig, PartialDeploymentOptions, PartialDeploymentResult, RequestOptions, UploadProgressOptions } from './types';
 export type AvailableContentResult = {
     cid: string;
     available: boolean;
@@ -21,7 +21,15 @@ export type ContentClient = {
     /**
      * Deploys an entity to the content server.
      */
-    deploy(deployData: DeploymentData, options?: RequestOptions): Promise<unknown>;
+    deploy(deployData: DeploymentData, options?: RequestOptions & UploadProgressOptions): Promise<unknown>;
+    /**
+     * Deploys an entity across multiple requests (partial deployment, ADR-325): content files are split into
+     * size-bounded batches and uploaded in several `POST /entities` requests, and the entity only becomes
+     * live once the server has all of it. Useful for scenes too large for a single request. The server
+     * must support the partial-deployment protocol; against one that doesn't, if everything fits in a
+     * single batch this still succeeds, otherwise it rejects with {@link PartialDeploymentNotSupportedError}.
+     */
+    deployPartial(deployData: DeploymentData, options?: RequestOptions & PartialDeploymentOptions): Promise<PartialDeploymentResult>;
     /**
      * Checks if a pointer is consistent across multiple content servers
      */

package/dist/client/ContentClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContentClient.d.ts","sourceRoot":"","sources":["../../src/client/ContentClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAIxG,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,OAAO,CAAA;CACnB,EAAE,CAAA;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,gCAAgC,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEzG,0BAA0B;IAC1B,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACxF,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9G,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE/G,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAE7F;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE9E;;OAEG;IACH,uBAAuB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GACvD,OAAO,CAAC;QACT,YAAY,EAAE,OAAO,CAAA;QACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;QAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAC5B,CAAC,CAAA;CACH,CAAA;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5D,OAAO,CAAC,UAAU,CAAC,CAuBrB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAoQzE"}
+{"version":3,"file":"ContentClient.d.ts","sourceRoot":"","sources":["../../src/client/ContentClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EACL,aAAa,EACb,cAAc,EAEd,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,uBAAuB,EACvB,cAAc,EAEd,qBAAqB,EACtB,MAAM,SAAS,CAAA;AAiHhB,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,OAAO,CAAA;CACnB,EAAE,CAAA;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,gCAAgC,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEzG,0BAA0B;IAC1B,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACxF,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9G,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE/G,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAE7F;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtG;;;;;;OAMG;IACH,aAAa,CACX,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,cAAc,GAAG,wBAAwB,GAClD,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAEnC;;OAEG;IACH,uBAAuB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GACvD,OAAO,CAAC;QACT,YAAY,EAAE,OAAO,CAAA;QACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;QAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAC5B,CAAC,CAAA;CACH,CAAA;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5D,OAAO,CAAC,UAAU,CAAC,CAuBrB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAwsBzE"}