Add an API for Attach over HTTP API

The new APIv2 branch provides an HTTP-based remote API to Podman.
The requirements of this are, unfortunately, incompatible with
the existing Attach API. For non-terminal attach, we need append
a header to what was copied from the container, to multiplex
STDOUT and STDERR; to do this with the old API, we'd need to copy
into an intermediate buffer first, to handle the headers.

To avoid this, provide a new API to handle all aspects of
terminal and non-terminal attach, including closing the hijacked
HTTP connection. This might be a bit too specific, but for now,
it seems to be the simplest approach.

At the same time, add a Resize endpoint. This needs to be a
separate endpoint, so our existing channel approach does not work
here.

I wanted to rework the rest of attach at the same time (some
parts of it, particularly how we start the Attach session and how
we do resizing, are (in my opinion) handled much better here.
That may still be on the table, but I wanted to avoid breaking
existing APIs in this already massive change.

Signed-off-by: Matthew Heon <matthew.heon@pm.me>

1 files changed, 29 insertions, 0 deletions

diff --git a/libpod/oci.go b/libpod/oci.go
index 05a2f37db..2ea61851f 100644
--- a/libpod/oci.go
+++ b/libpod/oci.go
@@ -1,6 +1,9 @@
 package libpod
 
 import (
+	"bufio"
+	"net"
+
 	"k8s.io/client-go/tools/remotecommand"
 )
 
@@ -47,6 +50,23 @@ type OCIRuntime interface {
 	// UnpauseContainer unpauses the given container.
 	UnpauseContainer(ctr *Container) error
 
+	// HTTPAttach performs an attach intended to be transported over HTTP.
+	// For terminal attach, the container's output will be directly streamed
+	// to output; otherwise, STDOUT and STDERR will be multiplexed, with
+	// a header prepended as follows: 1-byte STREAM (0, 1, 2 for STDIN,
+	// STDOUT, STDERR), 3 null (0x00) bytes, 4-byte big endian length.
+	// If a cancel channel is provided, it can be used to asyncronously
+	// termninate the attach session. Detach keys, if given, will also cause
+	// the attach session to be terminated if provided via the STDIN
+	// channel. If they are not provided, the default detach keys will be
+	// used instead. Detach keys of "" will disable detaching via keyboard.
+	// The streams parameter may be passed for containers that did not
+	// create a terminal and will determine which streams to forward to the
+	// client.
+	HTTPAttach(ctr *Container, httpConn net.Conn, httpBuf *bufio.ReadWriter, streams *HTTPAttachStreams, detachKeys *string, cancel <-chan bool) error
+	// AttachResize resizes the terminal in use by the given container.
+	AttachResize(ctr *Container, newSize remotecommand.TerminalSize) error
+
 	// ExecContainer executes a command in a running container.
 	// Returns an int (exit code), error channel (errors from attach), and
 	// error (errors that occurred attempting to start the exec session).
@@ -130,3 +150,12 @@ type ExecOptions struct {
 	// detach from the container.
 	DetachKeys string
 }
+
+// HTTPAttachStreams informs the HTTPAttach endpoint which of the container's
+// standard streams should be streamed to the client. If this is passed, at
+// least one of the streams must be set to true.
+type HTTPAttachStreams struct {
+	Stdin  bool
+	Stdout bool
+	Stderr bool
+}