Skip to content

docs: clarify 64 KiB response-body buffer in authz plugin docs#6971

Open
matte1782 wants to merge 1 commit intodocker:masterfrom
matte1782:docs-authz-64kib-buffer-2026-05
Open

docs: clarify 64 KiB response-body buffer in authz plugin docs#6971
matte1782 wants to merge 1 commit intodocker:masterfrom
matte1782:docs-authz-64kib-buffer-2026-05

Conversation

@matte1782
Copy link
Copy Markdown

What

Adds a new "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 its practical implications for plugins that use ResponseBody inspection.

Why

The existing docs (lines 81–87) tell plugin authors that streaming endpoints such as logs and events send only the HTTP request to authorization plugins, but don't explain the underlying mechanism. As a result, 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 that exceed the buffer, or whose handler uses io.WriteFlusher.

This is not a behavior change — the 64 KiB buffer is observable from the public moby source. The PR is documentation catching up to existing behavior.

How

  • Inserts a new `###` subsection right after the existing "chunked HTTP response" paragraph (line 87 in `master`).
  • 25 lines added, 0 removed.
  • Uses the existing `> [!NOTE]` callout syntax (introduced to this file in `f1befab` on 2024-08-16).
  • No content removed, no other section modified.

Who's affected

Plugin authors and operations teams running authorization plugins that depend on `ResponseBody` for security decisions on large or streaming responses. For redaction-style plugins, the new section recommends performing filtering in a separate layer in front of the daemon when the endpoint is likely to exceed 64 KiB or stream chunked output.

Verification

The numbers and behaviors described in the new subsection were derived directly from a read of `pkg/authorization/response.go` at moby `master`:

  • `maxBufferSize = 64 * 1024` at `pkg/authorization/response.go` line 50.
  • `responseModifier.Write` at line 117–128 calls `Flush()` when `len(rm.body) + len(b) > maxBufferSize`.
  • `responseModifier.FlushAll` at line 167–197 writes the buffer to the underlying `http.ResponseWriter` and then drains the buffer slice.
  • `pkg/ioutils/writeflusher.go` `WriteFlusher.Write` calls `Flush()` after every underlying write.
  • `pkg/authorization/middleware.go` invokes `AuthZResponse` after the handler returns.

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 <matteo1782@gmail.com>
@matte1782 matte1782 requested review from a team and thaJeztah as code owners May 9, 2026 21:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant