moby/client
Sebastiaan van Stijn 7e7e100be0
Add HEAD support for /_ping endpoint
Monitoring systems and load balancers are usually configured to use HEAD
requests for health monitoring. The /_ping endpoint currently does not
support this type of request, which means that those systems have fallback
to GET requests.

This patch adds support for HEAD requests on the /_ping endpoint.

Although optional, this patch also returns `Content-Type` and `Content-Length`
headers in case of a HEAD request; Refering to RFC 7231, section 4.3.2:

    The HEAD method is identical to GET except that the server MUST NOT
    send a message body in the response (i.e., the response terminates at
    the end of the header section).  The server SHOULD send the same
    header fields in response to a HEAD request as it would have sent if
    the request had been a GET, except that the payload header fields
    (Section 3.3) MAY be omitted.  This method can be used for obtaining
    metadata about the selected representation without transferring the
    representation data and is often used for testing hypertext links for
    validity, accessibility, and recent modification.

    A payload within a HEAD request message has no defined semantics;
    sending a payload body on a HEAD request might cause some existing
    implementations to reject the request.

    The response to a HEAD request is cacheable; a cache MAY use it to
    satisfy subsequent HEAD requests unless otherwise indicated by the
    Cache-Control header field (Section 5.2 of [RFC7234]).  A HEAD
    response might also have an effect on previously cached responses to
    GET; see Section 4.3.5 of [RFC7234].

With this patch applied, either `GET` or `HEAD` requests work; the only
difference is that the body is empty in case of a `HEAD` request;

    curl -i --unix-socket /var/run/docker.sock http://localhost/_ping
    HTTP/1.1 200 OK
    Api-Version: 1.40
    Cache-Control: no-cache, no-store, must-revalidate
    Docker-Experimental: false
    Ostype: linux
    Pragma: no-cache
    Server: Docker/dev (linux)
    Date: Mon, 14 Jan 2019 12:35:16 GMT
    Content-Length: 2
    Content-Type: text/plain; charset=utf-8

    OK

    curl --head -i --unix-socket /var/run/docker.sock http://localhost/_ping
    HTTP/1.1 200 OK
    Api-Version: 1.40
    Cache-Control: no-cache, no-store, must-revalidate
    Content-Length: 0
    Content-Type: text/plain; charset=utf-8
    Docker-Experimental: false
    Ostype: linux
    Pragma: no-cache
    Server: Docker/dev (linux)
    Date: Mon, 14 Jan 2019 12:34:15 GMT

The client is also updated to use `HEAD` by default, but fallback to `GET`
if the daemon does not support this method.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2019-01-31 18:18:24 +01:00
..
testdata Move engine-api client package 2016-09-07 11:05:58 -07:00
build_cancel.go Remove stray uses of "golang.org/x/net/context" 2018-07-13 09:53:36 +02:00
build_prune.go builder: add prune options to the API 2018-09-01 22:01:17 +00:00
checkpoint_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
checkpoint_create_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
checkpoint_delete.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
checkpoint_delete_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
checkpoint_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
checkpoint_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
client.go Move deprecated client constructors to a separate file 2019-01-21 15:27:52 +01:00
client_deprecated.go Move deprecated client constructors to a separate file 2019-01-21 15:27:52 +01:00
client_mock_test.go Add canonical import comment 2018-02-05 16:51:57 -05:00
client_test.go Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
client_unix.go Introduce NewClientWithOpts func to build custom client easily 2018-02-08 15:26:24 +01:00
client_windows.go Introduce NewClientWithOpts func to build custom client easily 2018-02-08 15:26:24 +01:00
config_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
config_create_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
config_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
config_inspect_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
config_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
config_list_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
config_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
config_remove_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
config_update.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
config_update_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
container_attach.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_commit.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_commit_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_copy.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_copy_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_create_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_diff.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_diff_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_exec.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_exec_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_export.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_export_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_inspect.go Unify the defer syntax 2018-12-02 04:09:47 +01:00
container_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_kill.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_kill_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
container_logs_test.go Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
container_pause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_pause_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_prune.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_prune_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
container_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_remove_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
container_rename.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_rename_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_resize.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_resize_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_restart.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_restart_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_start.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_start_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_stats.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_stats_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_stop.go Merge pull request #36874 from kolyshkin/stop-timeout 2018-05-30 13:38:42 -04:00
container_stop_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_top.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_top_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_unpause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_unpause_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_update.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_update_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_wait.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_wait_test.go Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
disk_usage.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
disk_usage_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
distribution_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
distribution_inspect_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
errors.go Various code-cleanup 2018-05-23 17:50:54 +02:00
events.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
events_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
hijack.go client: add WithDialContext() and client.Dialer() 2018-07-28 23:35:47 +09:00
hijack_test.go Remove use of deprecated client.NewClient() 2019-01-28 17:08:54 +01:00
image_build.go api: Change Platform field back to string (temporary workaround) 2018-07-03 22:33:42 +00:00
image_build_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_create_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_history.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_history_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_import.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_import_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_load.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_load_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_prune.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_prune_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
image_pull.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_pull_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_push.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_push_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_remove_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
image_save.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_save_test.go Various code-cleanup 2018-05-23 17:50:54 +02:00
image_search.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_search_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_tag.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_tag_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
info.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
info_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
interface.go builder: add prune options to the API 2018-09-01 22:01:17 +00:00
interface_experimental.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
interface_stable.go Add canonical import comment 2018-02-05 16:51:57 -05:00
login.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_connect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_connect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_create_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_disconnect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_disconnect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_inspect_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
network_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_prune.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_prune_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
network_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_remove_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_remove.go Various code-cleanup 2018-05-23 17:50:54 +02:00
node_remove_test.go Various code-cleanup 2018-05-23 17:50:54 +02:00
node_update.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
node_update_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
options.go Move client-opts to a separate file 2019-01-21 14:52:46 +01:00
ping.go Add HEAD support for /_ping endpoint 2019-01-31 18:18:24 +01:00
ping_test.go Add HEAD support for /_ping endpoint 2019-01-31 18:18:24 +01:00
plugin_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_disable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_disable_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_enable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_enable_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_install.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_push.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_push_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_remove_test.go Various code-cleanup 2018-05-23 17:50:54 +02:00
plugin_set.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_set_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_upgrade.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
README.md Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
request.go Add HEAD support for /_ping endpoint 2019-01-31 18:18:24 +01:00
request_test.go client: use io.LimitedReader for reading HTTP error 2018-10-11 01:37:39 +09:00
secret_create.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
secret_create_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
secret_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
secret_inspect_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
secret_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
secret_list_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
secret_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
secret_remove_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
secret_update.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
secret_update_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
service_create.go Various code-cleanup 2018-05-23 17:50:54 +02:00
service_create_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
service_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
service_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
service_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
service_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
service_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
service_logs_test.go Remove use of deprecated client.NewEnvClient() 2019-01-03 22:49:00 +01:00
service_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
service_remove_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
service_update.go Update documentation for ServiceUpdate 2018-10-23 13:16:51 +11:00
service_update_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
session.go client: add WithDialContext() and client.Dialer() 2018-07-28 23:35:47 +09:00
swarm_get_unlock_key.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_get_unlock_key_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
swarm_init.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_init_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_join.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_join_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_leave.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_leave_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_unlock.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_unlock_test.go Fix some linting issues 2018-05-17 19:28:27 +02:00
swarm_update.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_update_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
task_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
task_inspect_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
task_list.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
task_list_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
task_logs.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
transport.go Add canonical import comment 2018-02-05 16:51:57 -05:00
utils.go Add canonical import comment 2018-02-05 16:51:57 -05:00
version.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
volume_create.go Fix swagger volume type generation 2018-05-14 13:46:20 -04:00
volume_create_test.go Fix swagger volume type generation 2018-05-14 13:46:20 -04:00
volume_inspect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
volume_inspect_test.go Update tests to use gotest.tools 👼 2018-06-13 09:04:30 +02:00
volume_list.go Fix swagger volume type generation 2018-05-14 13:46:20 -04:00
volume_list_test.go Fix swagger volume type generation 2018-05-14 13:46:20 -04:00
volume_prune.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
volume_remove.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
volume_remove_test.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00

Go client for the Docker Engine API

The docker command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does  running containers, pulling images, managing swarms, etc.

For example, to list running containers (the equivalent of docker ps):

package main

import (
	"context"
	"fmt"

	"github.com/docker/docker/api/types"
	"github.com/docker/docker/client"
)

func main() {
	cli, err := client.NewClientWithOpts(client.FromEnv)
	if err != nil {
		panic(err)
	}

	containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
	if err != nil {
		panic(err)
	}

	for _, container := range containers {
		fmt.Printf("%s %s\n", container.ID[:10], container.Image)
	}
}

Full documentation is available on GoDoc.