Add documentation

api.go

@@ -21,10 +21,12 @@ import (
 	"strings"
 )
 
-const APIVERSION = 1.5
+const (
-const DEFAULTHTTPHOST = "127.0.0.1"
+	APIVERSION        = 1.6
-const DEFAULTHTTPPORT = 4243
+	DEFAULTHTTPHOST   = "127.0.0.1"
-const DEFAULTUNIXSOCKET = "/var/run/docker.sock"
+	DEFAULTHTTPPORT   = 4243
+	DEFAULTUNIXSOCKET = "/var/run/docker.sock"
+)
 
 type HttpApiFunc func(srv *Server, version float64, w http.ResponseWriter, r *http.Request, vars map[string]string) error
 
@@ -794,7 +796,7 @@ func postContainersAttach(srv *Server, version float64, w http.ResponseWriter, r
 
 	fmt.Fprintf(outStream, "HTTP/1.1 200 OK\r\nContent-Type: application/vnd.docker.raw-stream\r\n\r\n")
 
-	if !c.Config.Tty && version >= 1.4 {
+	if !c.Config.Tty && version >= 1.6 {
 		errStream = utils.NewStdWriter(outStream, utils.Stderr)
 		outStream = utils.NewStdWriter(outStream, utils.Stdout)
 	} else {

docs/sources/api/attach_api_1.6.rst

@@ -0,0 +1,52 @@
+:title: Attach stream API
+:description: API Documentation for the Attach command in Docker
+:keywords: API, Docker, Attach, Stream, REST, documentation
+
+=================
+Docker Attach stream API
+=================
+
+.. contents:: Table of Contents
+
+1. Brief introduction
+=====================
+
+- This is the Attach stream API for Docker
+
+2. Format
+=========
+
+The attach format is a Header and a Payload (frame).
+
+2.1 Header
+^^^^^^^^^^
+
+The header will contain the information on which stream write
+the stream (stdout or stderr).
+It also contain the size of the associated frame encoded on the last 4 bytes (uint32).
+
+It is encoded on the first 8 bytes like this:
+header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
+
+STREAM_TYPE can be:
+- 0: stdin (will be writen on stdout)
+- 1: stdout
+- 2: stderr
+
+SIZE1, SIZE2, SIZE3, SIZE4 are the 4 bytes of the uint32 size.
+
+2.1 Payload (frame)
+^^^^^^^^^^^^^^^^^^^
+
+The payload is the raw stream.
+
+3. Implementation
+=================
+
+The simplest way to implement the Attach protocol is the following:
+
+1) Read 8 bytes
+2) chose stdout or stderr depending on the first byte
+3) Extract the frame size from the last 4 byets
+4) Read the extracted size and output it on the correct output
+5) Goto 1)

docs/sources/api/docker_remote_api.rst

@@ -27,14 +27,29 @@ Docker Remote API
 2. Versions
 ===========
 
-The current version of the API is 1.5
+The current version of the API is 1.6
 
 Calling /images/<name>/insert is the same as calling
-/v1.5/images/<name>/insert 
+/v1.6/images/<name>/insert
 
 You can still call an old version of the api using
 /v1.0/images/<name>/insert
 
+:doc:`docker_remote_api_v1.6`
+*****************************
+
+What's new
+----------
+
+.. http:post:: /containers/(id)/attach
+
+   **New!** You can now split stderr from stdout. This is done by prefixing
+   a header to each transmition. See :doc:`attach_api_1.6`.
+   The WebSocket attach is unchanged.
+   Note that attach calls on previous API version didn't change. Stdout and
+   stderr are merge.
+
+
 :doc:`docker_remote_api_v1.5`
 *****************************