Skip to content

Commit 356482a

Browse files
committed
docs(jsonrpc): document wort-case memory scenario for responses
The memory model now documents: - 64 MiB of JSON-RPC request buffers. - Up to 640 MiB of response buffers. - Approximately 704 MiB combined. - Additional unbounded working memory from repository rows and decoded objects materialized before response-size enforcement.
1 parent 136841f commit 356482a

1 file changed

Lines changed: 14 additions & 6 deletions

File tree

docs/http-posture.md

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -243,13 +243,21 @@ pipeline additional requests on the same connection. This behavior
243243
depends on the internal `responseWriterTap.Unwrap()` cooperating with
244244
`http.MaxBytesReader`; see the hardening v3 plan for the design note.
245245

246-
**Worst-case body buffer memory under saturation.**
246+
**Worst-case request and response memory under saturation.**
247247
Each admitted request pins its body buffer for the full request lifetime
248-
(up to `InspectMaxDeadline + 30s` for inspect (typically ~210s with the default 180s deadline), 30s for JSON-RPC). At default concurrency this
249-
means `CARTESI_INSPECT_MAX_INFLIGHT × 2 MiB = 128 MiB` for inspect and
250-
`CARTESI_JSONRPC_MAX_INFLIGHT × 1 MiB = 64 MiB` for JSON-RPC. Operators
251-
should size process RAM headroom accordingly, on top of machine state,
252-
database connections, and other working memory.
248+
(up to `InspectMaxDeadline + 30s` for inspect (typically ~210s with the default
249+
180s deadline), 30s for JSON-RPC). At default concurrency this means
250+
`CARTESI_INSPECT_MAX_INFLIGHT × 2 MiB = 128 MiB` for inspect and
251+
`CARTESI_JSONRPC_MAX_INFLIGHT × 1 MiB = 64 MiB` for JSON-RPC request bodies.
252+
253+
The dominant JSON-RPC term is response buffering: each of the 64 admitted
254+
requests has a 10 MiB response budget, for up to `64 × 10 MiB = 640 MiB` of
255+
response buffers under saturation, or approximately 704 MiB including request
256+
bodies. The budget is enforced while encoding the response, after repository
257+
rows and decoded response objects have already been materialized; that working
258+
set is additional and is not bounded by the 10 MiB serialized-response limit.
259+
Operators should size process RAM headroom accordingly, on top of machine
260+
state, database connections, and other working memory.
253261

254262
## PostgreSQL pool sizing
255263

0 commit comments

Comments
 (0)