stdcopy

func NewStdWriter ¶

func NewStdWriter(w io.Writer, streamType StdType) io.Writer

NewStdWriter instantiates a new writer using a custom format to multiplex multiple streams to a single writer. All messages written using this writer are encapsulated using a custom format, and written to the underlying stream "w".

Writers created through NewStdWriter allow for multiple write streams (e.g., stdout (Stdout) and stderr (Stderr) to be multiplexed into a single connection. "streamType" indicates the type of stream to encapsulate, commonly, Stdout or Stderr. The Systemerr stream can be used to include server-side errors in the stream. Information on this stream is returned as an error by StdCopy and terminates processing the stream.

The Stdin stream is present for completeness and should generally NOT be used. It is output on Stdout when reading the stream with StdCopy.

All streams must share the same underlying io.Writer to ensure proper multiplexing. Each call to NewStdWriter wraps that shared writer with a header indicating the target stream.

package main

import (
	"errors"
	"fmt"
	"io"
	"os"
	"time"

	"github.com/moby/moby/api/pkg/stdcopy"
)

func main() {
	muxReader, muxStream := io.Pipe()
	defer func() { _ = muxStream.Close() }()

	// Start demuxing before the daemon starts writing.
	done := make(chan error, 1)
	go func() {
		// using os.Stdout for both, otherwise output doesn't show up in the example.
		osStdout := os.Stdout
		osStderr := os.Stdout
		_, err := stdcopy.StdCopy(osStdout, osStderr, muxReader)
		done <- err
	}()

	// daemon writing to stdout, stderr, and systemErr.
	stdout := stdcopy.NewStdWriter(muxStream, stdcopy.Stdout)
	stderr := stdcopy.NewStdWriter(muxStream, stdcopy.Stderr)
	systemErr := stdcopy.NewStdWriter(muxStream, stdcopy.Systemerr)

	for range 10 {
		_, _ = fmt.Fprintln(stdout, "hello from stdout")
		_, _ = fmt.Fprintln(stderr, "hello from stderr")
		time.Sleep(50 * time.Millisecond)
	}
	_, _ = fmt.Fprintln(systemErr, errors.New("something went wrong"))

	// Wait for the demuxer to finish.
	if err := <-done; err != nil {
		fmt.Println(err)
	}

}

Output:

hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
hello from stdout
hello from stderr
error from daemon in stream: something went wrong

func StdCopy ¶

func StdCopy(destOut, destErr io.Writer, multiplexedSource io.Reader) (written int64, _ error)

StdCopy is a modified version of io.Copy to de-multiplex messages from "multiplexedSource" and copy them to destination streams "destOut" and "destErr".

StdCopy demultiplexes "multiplexedSource", assuming that it contains two streams, previously multiplexed using a writer created with NewStdWriter.

As it reads from "multiplexedSource", StdCopy writes Stdout messages to "destOut", and Stderr message to "destErr]. For backward-compatibility, Stdin messages are output to "destOut". The Systemerr stream provides errors produced by the daemon. It is returned as an error, and terminates processing the stream.

StdCopy it reads until it hits io.EOF on "multiplexedSource", after which it returns a nil error. In other words: any error returned indicates a real underlying error, which may be when an unknown StdType stream is received.

The "written" return holds the total number of bytes written to "destOut" and "destErr" combined.