From 6d38b7a71aeae06861ed97365fb7f6cc2b475642 Mon Sep 17 00:00:00 2001 From: Matteo Panzeri Date: Sat, 9 May 2026 23:00:51 +0200 Subject: [PATCH] docs: clarify 64 KiB response-body buffer in authz plugin docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Response body size and partial buffering" subsection to docs/extend/plugins_authorization.md documenting the 64 KiB maxBufferSize constant in the daemon's internal responseModifier (pkg/authorization/response.go in moby/moby) and the practical implications for plugins that use ResponseBody inspection. The existing docs (lines 81-87) say streaming endpoints such as logs and events send only the HTTP request to plugins, but don't explain the underlying mechanism. Plugin authors building response-body redaction or content-filtering can be surprised when the same effect happens on non-listed endpoints whose response is produced through multiple writes exceeding the buffer or via an io.WriteFlusher. The 64 KiB buffer is observable from the public moby source, so this PR is documentation catching up to existing behavior — not a contract change. Signed-off-by: Matteo Panzeri --- docs/extend/plugins_authorization.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index b8678debd59d..232d5f1e6d06 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -86,6 +86,31 @@ passed to the authorization plugins. For commands that return chunked HTTP response, such as `logs` and `events`, only the HTTP request is sent to the authorization plugins. +### Response body size and partial buffering + +The internal buffer that holds the response body between the daemon's HTTP +handler and the plugin's response authorization callback (`responseModifier`, +defined in [`pkg/authorization/response.go`](https://github.com/moby/moby/blob/master/pkg/authorization/response.go)) +has a fixed capacity of 64 KiB (`maxBufferSize`). + +For most non-streaming endpoints the full response is buffered for plugin +inspection regardless of total size, because Go's `encoding/json` encoder +serializes the complete payload into a single underlying write. The +streaming-response exclusion noted above (for example, `logs` and `events`) +is the practical effect of this 64 KiB threshold combined with the +`io.WriteFlusher` write pattern used by streaming handlers, where each write +is immediately drained to the client and is therefore no longer available +for plugin inspection by the time the handler returns. + +> [!NOTE] +> Plugins that depend on `ResponseBody` inspection for redaction or +> content-filtering should restrict their policies to endpoints whose +> response is produced as a single write (typical of REST-style API +> responses). For commands whose responses are streamed or are likely to +> exceed the buffer through multiple writes, do not rely on `ResponseBody` +> for security-relevant decisions; perform the filtering in a separate +> layer in front of the daemon. + During request/response processing, some authorization flows might need to do additional queries to the Docker daemon. To complete such flows, plugins can call the daemon API similar to a regular user. To enable these