Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Record bounded buffered HTTP/2 request policy

Rach Pradhan67b42d367fbb
diff --git a/docs/adr/0189-bounded-buffered-http2-posts.md b/docs/adr/0189-bounded-buffered-http2-posts.md
new file mode 100644
index 00000000..180813d4
--- /dev/null
+++ b/docs/adr/0189-bounded-buffered-http2-posts.md
@@ -0,0 +1,34 @@
+# 0189. Buffered HTTP/2 posts bound memory and own their lifetime
+
+Status: accepted 2026-09-23
+
+## Context
+
+An optional JSON request needs a complete response before parsing. A line-based
+reader can grow without a limit when a peer sends JSON without newlines. A
+pooled connection also outlives the request arena that owns the parsed result;
+allocating the connection from that arena leaves a dangling idle session.
+
+## Decision
+
+Read response DATA in chunks into a fixed 64 KiB buffer, rejecting growth
+before copying. Inspect the status before accepting the body. Hold an exclusive
+HTTP/2 session lease through the response and return it to the pool only after
+END_STREAM. Allocate pooled transport state with an allocator that lives until
+pool shutdown, and copy completed response bytes into the caller's result
+allocator.
+
+Join the request worker before returning on the deadline or cancellation, so
+its input, credentials, and buffers can be released safely. Fall back to
+HTTP/1.1 only when connection setup or ALPN fails before sending the POST.
+After an ambiguous send, return the error without replaying the request.
+
+## Consequences
+
+Oversized or stalled responses fail the optional request instead of growing
+memory or holding its caller indefinitely. A successful pooled session remains
+valid after the result arena is destroyed. This helper buffers only small JSON
+responses; larger payloads need a separate streaming contract.
+
+`scripts/test-jev-http2.py` exercises the local TLS cancellation, ambiguous
+send, and pool-reuse paths without a remote service.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 1f997fbe..41da4957 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -214,6 +214,7 @@ record only when you need the evidence or the edge cases.
| [0186](0186-tool-previews-use-original-source-ranges.md) | Tool previews select whole diagnostic lines from original omitted ranges within byte and line budgets. |
| [0187](0187-optional-judgments-preserve-usage-uncertainty.md) | Optional judgments use an independent gateway login; tokens and unsettled cost remain distinct in CLI and ACP usage. |
| [0188](0188-streamed-tool-calls-retain-identity.md) | Streamed tool calls use explicit IDs; reused indexes keep incomplete predecessors invalid, and prose is not execution evidence. |
+| [0189](0189-bounded-buffered-http2-posts.md) | Buffered HTTP/2 posts cap body growth, use exclusive pooled leases with durable transport allocation, join deadlines, and never replay ambiguous sends. |
## When to write one