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, 170 insertions, 0 deletions

diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go
index b275fa4d1..dbe194cd4 100644
--- a/pkg/api/server/register_containers.go
+++ b/pkg/api/server/register_containers.go
@@ -428,6 +428,91 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '500':
 	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name:..*}/wait"), APIHandler(s.Context, generic.WaitContainer)).Methods(http.MethodPost)
+	// swagger:operation POST /containers/{nameOrID}/attach compat attach
+	// ---
+	// tags:
+	//   - containers (compat)
+	// summary: Attach to a container
+	// description: Hijacks the connection to forward the container's standard streams to the client.
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the container
+	//  - in: query
+	//    name: detachKeys
+	//    required: false
+	//    type: string
+	//    description: keys to use for detaching from the container
+	//  - in: query
+	//    name: logs
+	//    required: false
+	//    type: bool
+	//    description: Not yet supported
+	//  - in: query
+	//    name: stream
+	//    required: false
+	//    type: bool
+	//    default: true
+	//    description: If passed, must be set to true; stream=false is not yet supported
+	//  - in: query
+	//    name: stdout
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDOUT
+	//  - in: query
+	//    name: stderr
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDERR
+	//  - in: query
+	//    name: stdin
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDIN
+	// produces:
+	// - application/json
+	// responses:
+	//   '101':
+	//     description: No error, connection has been hijacked for transporting streams.
+	//   '400':
+	//       "$ref": "#/responses/BadParamError"
+	//   '404':
+	//       "$ref": "#/responses/NoSuchContainer"
+	//   '500':
+	//       "$ref": "#/responses/InternalError"
+	r.HandleFunc(VersionedPath("/containers/{name:..*}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost)
+	// swagger:operation POST /containers/{nameOrID}/resize compat resize
+	// ---
+	// tags:
+	//  - containers (compat)
+	// summary: Resize a container's TTY
+	// description: Resize the terminal attached to a container (for use with Attach).
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the container
+	//  - in: query
+	//    name: h
+	//    type: int
+	//    required: false
+	//    description: Height to set for the terminal, in characters
+	//  - in: query
+	//    name: w
+	//    type: int
+	//    required: false
+	//    description: Width to set for the terminal, in characters
+	// produces:
+	// - application/json
+	// responses:
+	//   '200':
+	//        description: no error
+	//   '404':
+	//       "$ref": "#/responses/NoSuchContainer"
+	//   '500':
+	//       "$ref": "#/responses/InternalError"
+	r.HandleFunc(VersionedPath("/containers/{name:..*}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost)
 
 	/*
 		libpod endpoints
@@ -823,5 +908,90 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '500':
 	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/containers/{nameOrID}/attach libpod attach
+	// ---
+	// tags:
+	//   - containers
+	// summary: Attach to a container
+	// description: Hijacks the connection to forward the container's standard streams to the client.
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the container
+	//  - in: query
+	//    name: detachKeys
+	//    required: false
+	//    type: string
+	//    description: keys to use for detaching from the container
+	//  - in: query
+	//    name: logs
+	//    required: false
+	//    type: bool
+	//    description: Not yet supported
+	//  - in: query
+	//    name: stream
+	//    required: false
+	//    type: bool
+	//    default: true
+	//    description: If passed, must be set to true; stream=false is not yet supported
+	//  - in: query
+	//    name: stdout
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDOUT
+	//  - in: query
+	//    name: stderr
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDERR
+	//  - in: query
+	//    name: stdin
+	//    required: false
+	//    type: bool
+	//    description: Attach to container STDIN
+	// produces:
+	// - application/json
+	// responses:
+	//   '101':
+	//     description: No error, connection has been hijacked for transporting streams.
+	//   '400':
+	//       "$ref": "#/responses/BadParamError"
+	//   '404':
+	//       "$ref": "#/responses/NoSuchContainer"
+	//   '500':
+	//       "$ref": "#/responses/InternalError"
+	r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/containers/{nameOrID}/resize libpod resize
+	// ---
+	// tags:
+	//  - containers
+	// summary: Resize a container's TTY
+	// description: Resize the terminal attached to a container (for use with Attach).
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the container
+	//  - in: query
+	//    name: h
+	//    type: int
+	//    required: false
+	//    description: Height to set for the terminal, in characters
+	//  - in: query
+	//    name: w
+	//    type: int
+	//    required: false
+	//    description: Width to set for the terminal, in characters
+	// produces:
+	// - application/json
+	// responses:
+	//   '200':
+	//        description: no error
+	//   '404':
+	//       "$ref": "#/responses/NoSuchContainer"
+	//   '500':
+	//       "$ref": "#/responses/InternalError"
+	r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost)
 	return nil
 }