From 85234c39abbd4c1f841022250736342d5328473e Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 07:52:43 +0000 Subject: [PATCH 1/2] docs(protocol): catalogue the -32016 PUSH_PENDING_LIMITED push-bound error Add the cache.pushCapsule in-flight pending-reassembly bound error to the dig-rpc catalog, mirroring how -32015 METADATA_TOO_LARGE is represented, and regenerate the derived static specs. Co-Authored-By: Claude --- docs/support/error-codes.md | 3 ++- package.json | 2 +- scripts/dig-spec.mjs | 6 ++++++ static/error-codes.json | 14 ++++++++++++++ static/openrpc-node.json | 9 ++++++++- static/openrpc.json | 9 ++++++++- 6 files changed, 39 insertions(+), 4 deletions(-) diff --git a/docs/support/error-codes.md b/docs/support/error-codes.md index f0fd548..d748583 100644 --- a/docs/support/error-codes.md +++ b/docs/support/error-codes.md @@ -27,7 +27,7 @@ This catalog is also published as [`error-codes.json`](https://docs.dig.net/erro ## dig RPC (JSON-RPC) -The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) error codes plus the protocol-specific `-32004`, `-32005`, the node-profile `-32006` / `-32007` / `-32008` / `-32009`, the shell/staging codes `-32010` (upstream) and `-32011`–`-32014` (`dig.stage`), the metadata-response bound `-32015` (`dig.getMetadata`), the [private-retrieval](../protocol/onion-routing.md) codes `-32020` / `-32021` / `-32022`, the local control-plane codes `-32030` / `-32031` / `-32032`, and the wallet-balance read codes `-32040`–`-32043`. A content **miss is never an error** — the capsule returns its own indistinguishable, non-verifying response (there is no `decoy` field on the wire), and the client discovers the miss by inclusion-proof and/or decryption failure (see [the blind host model](../protocol/blind-host-model.md)). For any well-formed body the HTTP status is `200`; the error is carried in the JSON envelope. +The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) error codes plus the protocol-specific `-32004`, `-32005`, the node-profile `-32006` / `-32007` / `-32008` / `-32009`, the shell/staging codes `-32010` (upstream) and `-32011`–`-32014` (`dig.stage`), the metadata-response bound `-32015` (`dig.getMetadata`), the push-reassembly bound `-32016` (`cache.pushCapsule`), the [private-retrieval](../protocol/onion-routing.md) codes `-32020` / `-32021` / `-32022`, the local control-plane codes `-32030` / `-32031` / `-32032`, and the wallet-balance read codes `-32040`–`-32043`. A content **miss is never an error** — the capsule returns its own indistinguishable, non-verifying response (there is no `decoy` field on the wire), and the client discovers the miss by inclusion-proof and/or decryption failure (see [the blind host model](../protocol/blind-host-model.md)). For any well-formed body the HTTP status is `200`; the error is carried in the JSON envelope. | Code | Meaning | What to do | |---|---|---| @@ -48,6 +48,7 @@ The [dig RPC](../protocol/dig-rpc.md) uses the standard [JSON-RPC 2.0](https://w | `-32013` | **Stage: content exceeds the capsule size cap** — the staged content is over the size limit. | Reduce the content to within the capsule size cap. | | `-32014` | **Stage: compile/IO failure** — building the module hit a compile or IO error. | Check the source + disk; re-run with `--verbose` for detail. | | `-32015` | **Metadata too large** — a [`dig.getMetadata`](../rpc/methods.md#diggetmetadata) capsule's publisher metadata section is larger than the 3 MiB response ceiling. This section is returned whole (it cannot be paged like content), and its `custom`/`links` fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling. | Read the store's public file surface with [`dig.getManifest`](../rpc/methods.md#diggetmanifest) / individual files with [`dig.getContent`](../protocol/dig-rpc.md) instead of the whole metadata blob; if you publish, keep the metadata `custom`/`links` fields small. | +| `-32016` | **Push pending-reassembly limit reached** — [`cache.pushCapsule`](../run-a-node/manage.md#cache-pushcapsule) refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor or global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). | Wait for your in-flight pushes to complete, then retry the window. | | `-32020` | **Onion circuit unavailable** — a [`mode:"privacy"`](../protocol/onion-routing.md) content read could not be served privately (no circuit could be built, or one died mid-fetch). The node **fails closed** rather than downgrading to a direct fetch — a silent downgrade would deanonymize the very reader who asked for privacy. | Retry (a fresh circuit may build); or explicitly choose a fast `mode:"speed"` fetch if you accept revealing the read. | | `-32021` | **Privacy requires a local node** — [`mode:"privacy"`](../protocol/onion-routing.md#toggle-placement) was requested but the caller is not the node's own trusted local originator. A node will not fetch privately for a remote/anonymous caller (that would hand it the caller's identity and query). | Run a local DIG node (in-process browser node or the OS-service node on loopback) and issue the private read to it. | | `-32022` | **Onion hop count out of range** — the requested [`privacy.hops`](../protocol/onion-routing.md#modes) (circuit length) is outside the allowed range `[2, 5]` (default 3). | Request a hop count within `[2, 5]`. | diff --git a/package.json b/package.json index 605529b..0f23a89 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs-dig-net", - "version": "0.14.0", + "version": "0.14.1", "private": true, "scripts": { "docusaurus": "docusaurus", diff --git a/scripts/dig-spec.mjs b/scripts/dig-spec.mjs index 34014bc..fe2c33e 100644 --- a/scripts/dig-spec.mjs +++ b/scripts/dig-spec.mjs @@ -1010,6 +1010,12 @@ export const rpcErrors = { meaning: "dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling.", }, + PUSH_PENDING_LIMITED: { + code: -32016, + message: "Push pending-reassembly limit reached", + meaning: + "cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete.", + }, ONION_CIRCUIT_UNAVAILABLE: { code: -32020, message: "Onion circuit unavailable", diff --git a/static/error-codes.json b/static/error-codes.json index 6501844..5870e68 100644 --- a/static/error-codes.json +++ b/static/error-codes.json @@ -129,6 +129,13 @@ "http_or_exit": 200, "description": "Metadata too large — dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling." }, + { + "surface": "dig-rpc", + "code": -32016, + "name": "PUSH_PENDING_LIMITED", + "http_or_exit": 200, + "description": "Push pending-reassembly limit reached — cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete." + }, { "surface": "dig-rpc", "code": -32020, @@ -584,6 +591,13 @@ "http_or_exit": 200, "description": "Metadata too large — dig.getMetadata refused: the capsule's publisher metadata section renders larger than the 3 MiB response ceiling. The section is returned WHOLE (it cannot be paged like content) and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling." }, + { + "surface": "dig-rpc", + "code": -32016, + "name": "PUSH_PENDING_LIMITED", + "http_or_exit": 200, + "description": "Push pending-reassembly limit reached — cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor concurrent-push cap, a global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). Returned by the node-profile cache.pushCapsule. Retriable once in-flight pushes complete." + }, { "surface": "dig-rpc", "code": -32020, diff --git a/static/openrpc-node.json b/static/openrpc-node.json index e12f28e..b27d364 100644 --- a/static/openrpc-node.json +++ b/static/openrpc-node.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "dig RPC — node profile (local dig-node / in-process DIG Browser)", - "version": "0.13.0", + "version": "0.14.0", "description": "The NODE PROFILE: a distinct, smaller surface than the network profile. Of the byte methods it implements ONLY dig.getContent (local-first, else proxy); everything else proxies upstream or returns -32601. It ADDS node-only methods the security model depends on — chiefly dig.getAnchoredRoot (the CHIP-0035 on-chain head, the trusted root for mandatory root-pinning), dig.stage, and cache.*. Gate on dig.methods rather than assuming one uniform surface. See https://docs.dig.net/docs/protocol/dig-rpc#node-profile.", "license": { "name": "GPL-2.0", @@ -1120,6 +1120,13 @@ "type": "object" } }, + "PUSH_PENDING_LIMITED": { + "code": -32016, + "message": "Push pending-reassembly limit reached", + "data": { + "type": "object" + } + }, "ONION_CIRCUIT_UNAVAILABLE": { "code": -32020, "message": "Onion circuit unavailable", diff --git a/static/openrpc.json b/static/openrpc.json index e9ee625..a726f96 100644 --- a/static/openrpc.json +++ b/static/openrpc.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "dig RPC — DIG Network Content Interface (network profile)", - "version": "0.13.0", + "version": "0.14.0", "description": "The network-wide read interface for DIG content over JSON-RPC 2.0 — the NETWORK PROFILE served by the canonical node at rpc.dig.net. Blind by construction (the node holds no URN and no key), verifiable without trust (merkle inclusion proofs against the chain-anchored root), and streamable at any size. There is no `decoy` field on the wire and no CDN. See https://docs.dig.net/docs/protocol/dig-rpc.", "license": { "name": "GPL-2.0", @@ -1054,6 +1054,13 @@ "type": "object" } }, + "PUSH_PENDING_LIMITED": { + "code": -32016, + "message": "Push pending-reassembly limit reached", + "data": { + "type": "object" + } + }, "ONION_CIRCUIT_UNAVAILABLE": { "code": -32020, "message": "Onion circuit unavailable", From 08579f5d02941f7e8029bcb9e83b67dda1642f25 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 08:04:53 +0000 Subject: [PATCH 2/2] docs: regenerate openrpc specs with the bumped 0.14.1 version stamp Co-Authored-By: Claude --- static/openrpc-node.json | 2 +- static/openrpc.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/static/openrpc-node.json b/static/openrpc-node.json index b27d364..13c9866 100644 --- a/static/openrpc-node.json +++ b/static/openrpc-node.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "dig RPC — node profile (local dig-node / in-process DIG Browser)", - "version": "0.14.0", + "version": "0.14.1", "description": "The NODE PROFILE: a distinct, smaller surface than the network profile. Of the byte methods it implements ONLY dig.getContent (local-first, else proxy); everything else proxies upstream or returns -32601. It ADDS node-only methods the security model depends on — chiefly dig.getAnchoredRoot (the CHIP-0035 on-chain head, the trusted root for mandatory root-pinning), dig.stage, and cache.*. Gate on dig.methods rather than assuming one uniform surface. See https://docs.dig.net/docs/protocol/dig-rpc#node-profile.", "license": { "name": "GPL-2.0", diff --git a/static/openrpc.json b/static/openrpc.json index a726f96..16977b9 100644 --- a/static/openrpc.json +++ b/static/openrpc.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "dig RPC — DIG Network Content Interface (network profile)", - "version": "0.14.0", + "version": "0.14.1", "description": "The network-wide read interface for DIG content over JSON-RPC 2.0 — the NETWORK PROFILE served by the canonical node at rpc.dig.net. Blind by construction (the node holds no URN and no key), verifiable without trust (merkle inclusion proofs against the chain-anchored root), and streamable at any size. There is no `decoy` field on the wire and no CDN. See https://docs.dig.net/docs/protocol/dig-rpc.", "license": { "name": "GPL-2.0",