Repository navigation
docs: add adr 325 for partial (batched) scene deployments - #325
Open
LautaroPetaccio wants to merge 10 commits into
Open
LautaroPetaccio wants to merge 10 commits into
LautaroPetaccio wants to merge 10 commits into
Conversation
Specifies the consumer-facing protocol for deploying a scene across
several POST /entities requests with partial=true, shared by Catalyst
and the Worlds content server: the signed entity id identifies the
upload, 202 { missing } acknowledges storage, and the completing request
publishes. Overlapping uploads coexist and publication follows entity
timestamp order. Also covers response semantics, quotas, expiry,
visibility to sync, the reference client algorithm and compatibility
with servers that predate the protocol.
Deploying adr with
|
| Latest commit: |
dadcb88
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1a171a06.adr-cvq.pages.dev |
| Branch Preview URL: | https://feat-adr-partial-deployments.adr-cvq.pages.dev |
Quota rejections (upload count, staged bytes, byte rate) are 400 on both servers, and 429 with Retry-After is limited to Catalyst's per-pointer rate limit and concurrent-pointer conflicts. Both servers share the quota defaults, with expired uploads still counting until cleanup. Replay is guaranteed to the original signer only, and the open question now covers moving quota rejections to 429 together.
This was referenced Sep 23, 2026
Both servers now reject batches from another signer for a live upload, since its reservations are charged to its creator.
Batches may also declare partial=true in the URL so a server can tell a batch from a regular deployment before reading the body. Clients should send both; a query flag without the matching form field is a 400. The form field alone stays accepted. Also clarify that the replay guarantee covers the entity's latest publication.
An upload's lifetime and its freshness check now start when the first batch arrives, before its body is read, and servers must not store or publish after expiry even for a batch that arrived in time. Servers may bound uploads in progress per client and answer 429 when exceeded.
Servers may abort a batch whose body is not received in time or arrives below a minimum receive rate, answering 408.
A batch over a quota is now rejected with 429 and a Retry-After of the earliest time a retry can succeed: the end of the byte-rate window, or no earlier than the oldest charged upload's expiry. Clients stop and surface the error when Retry-After exceeds what they will wait. Resolves the open question about quota status codes.
Servers bound batch bodies with an overall upload timeout; no server enforces a minimum receive rate, since both sit behind proxies that buffer request bodies.
Any batch for an entity that is currently published now answers 200 with its creationTimestamp on both servers, since the entity id pins the exact entity. Uploads expire 1 hour after their first batch by default, and servers should reclaim expired uploads within minutes.
Size and count limit violations answer 413 and clients stop on them. A batch or upload that alone exceeds a quota answers 400. Only content an upload stores counts against its staging quotas, and already-stored files sent in a batch are dropped.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds ADR-325, a Standards Track draft specifying how clients deploy a scene too large for one request by splitting it across several
POST /entitiesrequests withpartial=true. The protocol is shared by Catalyst and the Worlds content server.Summary
202 { missing }acknowledges storage only; the request that completes the content set validates and publishes, answering200.Open points for review
429withRetry-After. The Worlds server currently answers byte rate and budget rejections with400and would need to change.202missinglist is authoritative;/available-contentis only for planning the first batch.400; an/aboutfield is proposed as a follow-up.Implementations: decentraland/worlds-content-server#504, decentraland/catalyst#1949, decentraland/catalyst-client#491.