docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy #50119

PowerPixel · 2025-05-31T17:11:12Z

Add a mention to stdcopy.StdCopy to the documentation, as the stream returned in the HijackedResponse is multiplexed.

- What I did
I added a mention to stdcopy.StdCopy to the documentation of the client.ContainerExecAttach method.

- How I did it
I simply added a few lines of documentation under the existing one for the client.ContainerExecAttach method.

- How to verify it

- Human readable description for the release notes

- A picture of a cute animal (not mandatory but encouraged)

vvoland

Thanks!

vvoland · 2025-06-02T08:56:47Z

client/container_exec.go

+// The Reader contained in the hijacked connection should be read using
+// the stdcopy.StdCopy function.


If I remember correctly (to make things even less intuitive) this is only true if the container was created with Tty = false.

Not 100% sure, so needs double checking 🙈

It seems this way, I'll add an additional comment later today. Thanks for the catch ! :)

moby/api/server/router/container/exec.go

Lines 130 to 135 in 829b695

if options.Tty {

stdout = outStream

} else {

stderr = stdcopy.NewStdWriter(outStream, stdcopy.Stderr)

stdout = stdcopy.NewStdWriter(outStream, stdcopy.Stdout)

}

Looks like we have a similar doc on the ContainerAttach function:

moby/client/container_attach.go

Lines 12 to 36 in b6669f1

// ContainerAttach attaches a connection to a container in the server.

// It returns a types.HijackedConnection with the hijacked connection

// and the a reader to get output. It's up to the called to close

// the hijacked connection by calling types.HijackedResponse.Close.

//

// The stream format on the response will be in one of two formats:

//

// If the container is using a TTY, there is only a single stream (stdout), and

// data is copied directly from the container output stream, no extra

// multiplexing or headers.

//

// If the container is *not* using a TTY, streams for stdout and stderr are

// multiplexed.

// The format of the multiplexed stream is as follows:

//

// [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}[]byte{OUTPUT}

//

// STREAM_TYPE can be 1 for stdout and 2 for stderr

//

// SIZE1, SIZE2, SIZE3, and SIZE4 are four bytes of uint32 encoded as big endian.

// This is the size of OUTPUT.

//

// You can use github.com/docker/docker/pkg/stdcopy.StdCopy to demultiplex this

// stream.

func (cli *Client) ContainerAttach(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error) {

I think we could partially reuse it here too (but spare the technical details and link to ContainerAttach for more details).

@vvoland Hey ! Sorry it took me a while to copy those few lines. :p This should be good, I copied the non-technical part of the documentation of ContainerExec and added a reference to it in the documentation for those who'd like to dwelve deeper in the technical details.

vvoland

Thanks!

One last step: could you please rebase your branch on top of master and then squash your commits into one?

PowerPixel · 2025-06-16T16:52:32Z

Sorry, took me a while, this should be good now :)

Add a mention to stdcopy.StdCopy to the documentation, as the stream returned in the HijackedResponse is multiplexed when tty is disabled. Signed-off-by: Medhy DOHOU <52136144+PowerPixel@users.noreply.github.com>

vvoland

Thanks!

vvoland reviewed Jun 2, 2025

View reviewed changes

vvoland added status/3-docs-review area/docs area/go-sdk labels Jun 2, 2025

vvoland added this to the 28.2.3 milestone Jun 2, 2025

PowerPixel force-pushed the 50118-add-stdcopy-containerexecattach branch from 7528df3 to f65407d Compare June 10, 2025 21:06

vvoland modified the milestones: 28.2.3, 28.3.0 Jun 11, 2025

vvoland reviewed Jun 11, 2025

View reviewed changes

PowerPixel force-pushed the 50118-add-stdcopy-containerexecattach branch 2 times, most recently from d71b6cc to 0de362a Compare June 16, 2025 16:51

docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy

4891396

Add a mention to stdcopy.StdCopy to the documentation, as the stream returned in the HijackedResponse is multiplexed when tty is disabled. Signed-off-by: Medhy DOHOU <52136144+PowerPixel@users.noreply.github.com>

PowerPixel force-pushed the 50118-add-stdcopy-containerexecattach branch from 0de362a to 4891396 Compare June 16, 2025 16:53

vvoland approved these changes Jun 16, 2025

View reviewed changes

vvoland merged commit a9c0420 into moby:master Jun 17, 2025
189 of 191 checks passed

yashuatla mentioned this pull request Jun 25, 2025

Feature implementation from commits 6ec6e09..9b4f68d yashuatla/moby#1

Open

dmcgowan mentioned this pull request Aug 5, 2025

Prepare release notes for client/v0.1.0-alpha.0 #50637

Merged

austinvazquez mentioned this pull request Aug 5, 2025

Bump api version in client and main module to v1.52.0-alpha.1 #50641

Merged

dmcgowan mentioned this pull request Sep 5, 2025

Prepare release notes for client/v0.1.0-beta.0 #50913

Merged

PowerPixel deleted the 50118-add-stdcopy-containerexecattach branch September 13, 2025 20:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy #50119

docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy #50119

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

		// The Reader contained in the hijacked connection should be read using
		// the stdcopy.StdCopy function.

	if options.Tty {
	stdout = outStream
	} else {
	stderr = stdcopy.NewStdWriter(outStream, stdcopy.Stderr)
	stdout = stdcopy.NewStdWriter(outStream, stdcopy.Stdout)
	}

	// ContainerAttach attaches a connection to a container in the server.
	// It returns a types.HijackedConnection with the hijacked connection
	// and the a reader to get output. It's up to the called to close
	// the hijacked connection by calling types.HijackedResponse.Close.
	//
	// The stream format on the response will be in one of two formats:
	//
	// If the container is using a TTY, there is only a single stream (stdout), and
	// data is copied directly from the container output stream, no extra
	// multiplexing or headers.
	//
	// If the container is not using a TTY, streams for stdout and stderr are
	// multiplexed.
	// The format of the multiplexed stream is as follows:
	//
	// [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}[]byte{OUTPUT}
	//
	// STREAM_TYPE can be 1 for stdout and 2 for stderr
	//
	// SIZE1, SIZE2, SIZE3, and SIZE4 are four bytes of uint32 encoded as big endian.
	// This is the size of OUTPUT.
	//
	// You can use github.com/docker/docker/pkg/stdcopy.StdCopy to demultiplex this
	// stream.
	func (cli *Client) ContainerAttach(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error) {

docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy #50119

docs(client/ContainerExecAttach): add a mention to stdcopy.StdCopy #50119

Conversation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!