API-Docker
view release on metacpan or search on metacpan
misc/agent-context/.claude/skills/docker-engine-api/references/streams/multiplexed-output.md view on Meta::CPAN
# Docker multiplexed output and defensive decoding
> Read when: logs contain binary headers or implementing non-TTY attach/exec/log streams.
When the endpoint uses Docker's non-TTY multiplexed output, each frame has an eight-byte header: one stream byte, three reserved bytes, then an unsigned big-endian 32-bit payload length. This is application framing **inside** HTTP; HTTP chunks and so...
```text
01 00 00 00 00 00 00 04 4f 55 54 0a stdout: OUT\n
02 00 00 00 00 00 00 04 45 52 52 0a stderr: ERR\n
```
The usual output types are stdout=1 and stderr=2. Pinned Moby `stdcopy` also recognizes stdin=0 and system-error=3. Type 3 must not be silently displayed as ordinary application output. Treat unknown frame kinds as a protocol/compatibility event.
With TTY enabled, output is a raw PTY byte stream: no Docker multiplex headers and no recoverable stdout/stderr separation. Do not decide framing by sniffing the first bytes of arbitrary application output. Use known TTY configuration and endpoint be...
## Defensive decoder requirements
Read exactly eight header bytes across partial reads. Validate header/type according to your compatibility policy. Bound payload allocation and total buffering. Read the announced payload fully; distinguish clean EOF at a frame boundary from truncati...
The included helper intentionally rejects truncated frames and oversized payloads. Those are **client safety choices**, not a promise that every upstream decoder rejects them identically. Its default size cap is configurable and must be sized for the...
Test single-byte reads, multiple frames per read, zero-length frames, split UTF-8, system errors, invalid headers, truncated payloads, and TTY bypass. A clean interactive TTY test alone cannot validate a non-TTY log client.
## Primary sources
- [Pinned Moby stdcopy framing implementation](https://raw.githubusercontent.com/moby/moby/v28.5.2/pkg/stdcopy/stdcopy.go)
- [Docker Python SDK multiplexed streams](https://docker-py.readthedocs.io/en/stable/user_guides/multiplex.html)
- [Pinned Moby 28.5.2 API 1.51 schema (compatibility evidence, not latest)](https://raw.githubusercontent.com/moby/moby/v28.5.2/docs/api/v1.51.yaml)
( run in 0.508 second using v1.01-cache-2.11-cpan-234fa220139 )