From 4d301c8c4f3301bc99a55752b387ef4f7be9de5f Mon Sep 17 00:00:00 2001 From: Jhon Honce Date: Mon, 3 Feb 2020 11:57:54 -0700 Subject: Update /_ping support * Add swagger support and documentation * Promote handler as there can only ever be one * Update swagger tags Between verbs and paths there are four endpoints for /_ping. I've attempted to document them well without four copies of the details. Time will tell. Clients will use the headers `Libpod-API-Version` and `Libpod-Buildha-Version` to determine if they are connecting to a Podman service or some other compatible engine. Client calls GET(/_ping): * VARLINK engines will fail with error message * Compatible engines will return 200 without Libpod headers * Podman engines will return 200 and Libpod headers Signed-off-by: Jhon Honce --- pkg/api/handlers/generic/ping.go | 27 ------------------ pkg/api/handlers/ping.go | 30 ++++++++++++++++++++ pkg/api/handlers/types.go | 4 --- pkg/api/server/register_images.go | 5 ++-- pkg/api/server/register_ping.go | 60 +++++++++++++++++++++++++++++++++++---- pkg/api/tags.yaml | 4 +++ 6 files changed, 92 insertions(+), 38 deletions(-) delete mode 100644 pkg/api/handlers/generic/ping.go create mode 100644 pkg/api/handlers/ping.go diff --git a/pkg/api/handlers/generic/ping.go b/pkg/api/handlers/generic/ping.go deleted file mode 100644 index 00afd86bc..000000000 --- a/pkg/api/handlers/generic/ping.go +++ /dev/null @@ -1,27 +0,0 @@ -package generic - -import ( - "fmt" - "net/http" - - "github.com/containers/libpod/pkg/api/handlers" -) - -func PingGET(w http.ResponseWriter, _ *http.Request) { - setHeaders(w) - fmt.Fprintln(w, "OK") -} - -func PingHEAD(w http.ResponseWriter, _ *http.Request) { - setHeaders(w) - fmt.Fprintln(w, "") -} - -func setHeaders(w http.ResponseWriter) { - w.Header().Set("API-Version", handlers.DefaultApiVersion) - w.Header().Set("BuildKit-Version", "") - w.Header().Set("Docker-Experimental", "true") - w.Header().Set("Cache-Control", "no-cache") - w.Header().Set("Pragma", "no-cache") - w.WriteHeader(http.StatusOK) -} diff --git a/pkg/api/handlers/ping.go b/pkg/api/handlers/ping.go new file mode 100644 index 000000000..d41da60f3 --- /dev/null +++ b/pkg/api/handlers/ping.go @@ -0,0 +1,30 @@ +package handlers + +import ( + "fmt" + "net/http" + + "github.com/containers/buildah" +) + +// Ping returns headers to client about the service +// +// This handler must always be the same for the compatibility and libpod URL trees! +// Clients will use the Header availability to test which backend engine is in use. +func Ping(w http.ResponseWriter, r *http.Request) { + w.Header().Set("API-Version", DefaultApiVersion) + w.Header().Set("BuildKit-Version", "") + w.Header().Set("Docker-Experimental", "true") + w.Header().Set("Cache-Control", "no-cache") + w.Header().Set("Pragma", "no-cache") + + // API-Version and Libpod-API-Version may not always be equal + w.Header().Set("Libpod-API-Version", DefaultApiVersion) + w.Header().Set("Libpod-Buildha-Version", buildah.Version) + w.WriteHeader(http.StatusOK) + + if r.Method == http.MethodGet { + fmt.Fprint(w, "OK") + } + fmt.Fprint(w, "\n") +} diff --git a/pkg/api/handlers/types.go b/pkg/api/handlers/types.go index 9c8562744..34b428852 100644 --- a/pkg/api/handlers/types.go +++ b/pkg/api/handlers/types.go @@ -70,10 +70,6 @@ type ContainerStats struct { docker.ContainerStats } -type Ping struct { - docker.Ping -} - type Version struct { docker.Version } diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go index f1cc0574c..18a90dc3d 100644 --- a/pkg/api/server/register_images.go +++ b/pkg/api/server/register_images.go @@ -300,8 +300,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // swagger:operation POST /commit/ compat commitContainer // --- // tags: - // - commit (compat) - // summary: Create a new image from a container + // - containers (compat) + // summary: New Image + // description: Create a new image from a container // parameters: // - in: query // name: container diff --git a/pkg/api/server/register_ping.go b/pkg/api/server/register_ping.go index 4956f9822..086e674a1 100644 --- a/pkg/api/server/register_ping.go +++ b/pkg/api/server/register_ping.go @@ -3,15 +3,65 @@ package server import ( "net/http" - "github.com/containers/libpod/pkg/api/handlers/generic" + "github.com/containers/libpod/pkg/api/handlers" "github.com/gorilla/mux" ) func (s *APIServer) registerPingHandlers(r *mux.Router) error { - r.Handle("/_ping", APIHandler(s.Context, generic.PingGET)).Methods(http.MethodGet) - r.Handle("/_ping", APIHandler(s.Context, generic.PingHEAD)).Methods("HEAD") - // libpod - r.Handle("/libpod/_ping", APIHandler(s.Context, generic.PingGET)).Methods(http.MethodGet) + r.Handle("/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodGet) + r.Handle("/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodHead) + + // swagger:operation GET /libpod/_ping libpod libpodPingGet + // --- + // summary: Ping service + // description: | + // Return protocol information in response headers. + // `HEAD /libpod/_ping` is also supported. + // `/_ping` is available for compatibility with other engines. + // tags: + // - system (compat) + // - system + // produces: + // - text/plain + // responses: + // 200: + // description: Success + // schema: + // description: OK + // type: string + // example: "OK" + // headers: + // API-Version: + // type: string + // description: Max compatibility API Version the server supports + // BuildKit-Version: + // type: string + // description: Default version of docker image builder + // Docker-Experimental: + // type: boolean + // description: If the server is running with experimental mode enabled, always true + // Cache-Control: + // type: string + // description: always no-cache + // Pragma: + // type: string + // description: always no-cache + // Libpod-API-Version: + // type: string + // description: | + // Max Podman API Version the server supports. + // Available if service is backed by Podman, therefore may be used to + // determine if talking to Podman engine or another engine + // Libpod-Buildha-Version: + // type: string + // description: | + // Default version of libpod image builder. + // Available if service is backed by Podman, therefore may be used to + // determine if talking to Podman engine or another engine + // 500: + // $ref: "#/responses/InternalError" + r.Handle("/libpod/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodGet) + r.Handle("/libpod/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodHead) return nil } diff --git a/pkg/api/tags.yaml b/pkg/api/tags.yaml index ad0de656f..be70fb3d8 100644 --- a/pkg/api/tags.yaml +++ b/pkg/api/tags.yaml @@ -7,7 +7,11 @@ tags: description: Actions related to pods - name: volumes description: Actions related to volumes + - name: system + description: Actions related to Podman engine - name: containers (compat) description: Actions related to containers for the compatibility endpoints - name: images (compat) description: Actions related to images for the compatibility endpoints + - name: system (compat) + description: Actions related to Podman and compatiblity engines -- cgit v1.2.3-54-g00ecf