moby/client
Sebastiaan van Stijn e6907243af
client: negotiate api version before handling version-specific code
We try to perform API-version negotiation as lazy as possible (and only execute
when we are about to make an API request). However, some code requires API-version
dependent handling (to set options, or remove options based on the version of the
API we're using).

Currently this code depended on the caller code to perform API negotiation (or
to configure the API version) first, which may not happen, and because of that
we may be missing options (or set options that are not supported on older API
versions).

This patch:

- splits the code that triggered API-version negotiation to a separate
  Client.checkVersion() function.
- updates NewVersionError to accept a context
- updates NewVersionError to perform API-version negotiation (if enabled)
- updates various Client functions to manually trigger API-version negotiation

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2023-09-20 15:23:27 +02:00
..
buildkit client/buildkit: ClientOpts: update docs to use doc-links, and inline 2023-08-01 16:19:36 +02:00
testdata Move engine-api client package 2016-09-07 11:05:58 -07:00
build_cancel.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
build_prune.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
checkpoint_create.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_create_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_delete.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_delete_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_list.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
checkpoint_list_test.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
client.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
client_deprecated.go client: deprecate NewClient properly 2023-03-31 16:15:01 -04:00
client_mock_test.go Add otel support 2023-09-07 18:38:19 +00:00
client_test.go Add otel support 2023-09-07 18:38:19 +00:00
client_unix.go remove pre-go1.17 build-tags 2023-05-19 20:38:51 +02:00
client_windows.go client: defaultHTTPClient() accept URL 2023-01-01 13:35:16 +01:00
config_create.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
config_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_inspect.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
config_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_list.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
config_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_remove.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
config_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
config_update.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
config_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_attach.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
container_commit.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
container_commit_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_copy.go client: CopyToContainer(), CopyFromContainer(): remove status-code handling 2022-04-19 08:28:20 +02:00
container_copy_test.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
container_create.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_diff.go api/types/container: create type for changes endpoint 2023-05-03 21:23:42 +02:00
container_diff_test.go client: slightly improve ContainerDiff tests 2023-05-03 21:25:07 +02:00
container_exec.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_exec_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_export.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_export_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
container_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_kill.go client: ContainerKill(): don't send signal query-param if none was set 2022-04-19 17:40:33 +02:00
container_kill_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_list.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
container_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_logs.go gofmt GoDoc comments with go1.19 2022-07-08 19:56:23 +02:00
container_logs_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_pause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_pause_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_prune.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
container_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_rename.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_rename_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_resize.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_resize_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_restart.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_restart_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_start.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_start_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_stats.go client: return explicit "nil" for no errors, and remove nil check 2023-07-17 12:24:28 +02:00
container_stats_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_stop.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_stop_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_top.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
container_top_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_unpause.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
container_unpause_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_update.go Fix grammar in client function comments 2021-02-16 10:07:44 -05:00
container_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
container_wait.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
container_wait_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
disk_usage.go API,daemon: support type URL parameter to /system/df 2021-07-27 12:17:45 +02:00
disk_usage_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
distribution_inspect.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
distribution_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
envvars.go client: add const for environment variables, and document them 2022-03-07 12:35:55 +01:00
errors.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
events.go client: fix empty-lines (revive) 2022-09-28 01:58:52 +02:00
events_test.go api/types/events: define "Action" type and consts 2023-08-29 00:38:08 +02:00
hijack.go Add otel support 2023-09-07 18:38:19 +00:00
hijack_test.go refactor: move from io/ioutil to io and os package 2021-08-27 14:56:57 +08:00
image_build.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
image_build_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_create.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_history.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
image_history_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_import.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_import_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
image_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_list.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
image_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_load.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
image_load_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_prune.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
image_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_pull.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_pull_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_push.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_push_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
image_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_save.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
image_save_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_search.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
image_search_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
image_tag.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
image_tag_test.go client: TestImageTagInvalidSourceImageName remove invalid test-case 2023-08-30 21:43:02 +02:00
info.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
info_test.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
interface.go api/types: move system info types to api/types/system 2023-07-07 13:01:36 +02:00
interface_experimental.go api/types: move checkpoint-types to api/types/checkpoint 2023-08-26 12:37:41 +02:00
interface_stable.go Add canonical import comment 2018-02-05 16:51:57 -05:00
login.go client: use types/registry.AuthConfig 2022-07-29 23:05:15 +02:00
network_connect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_connect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_create.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
network_create_test.go libnet: Make sure network names are unique 2023-09-12 10:40:13 +02:00
network_disconnect.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
network_disconnect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
network_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_list.go fix nolint comments for SA1019: filters.ToParamWithVersion is deprecated 2019-10-18 00:45:33 +02:00
network_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_prune.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
network_prune_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
network_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
network_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
node_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_list.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
node_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
node_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
node_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
node_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
options.go Add otel support 2023-09-07 18:38:19 +00:00
options_test.go client: add WithUserAgent() option 2023-06-09 09:59:29 +02:00
ping.go client: Client.buildRequest: use http.NewRequestWithContext 2023-08-09 20:30:25 +02:00
ping_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_create.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
plugin_disable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_disable_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_enable.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_enable_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_install.go migrate to new github.com/distribution/reference module 2023-09-05 12:09:26 +02:00
plugin_list.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_push.go client: remove custom "headers" type, and use "http.Header" instead 2023-07-11 13:14:28 +02:00
plugin_push_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
plugin_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_set.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
plugin_set_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
plugin_upgrade.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
README.md Update example in README.md to close cli object 2023-08-26 19:55:45 +02:00
request.go client: Client.buildRequest: use http.NewRequestWithContext 2023-08-09 20:30:25 +02:00
request_test.go client: define a "dummy" hostname to use for local connections 2023-07-14 18:57:53 +02:00
secret_create.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
secret_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_inspect.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
secret_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_list.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
secret_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_remove.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
secret_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
secret_update.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
secret_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_create.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
service_create_test.go client: format code with gofumpt 2023-06-29 00:25:21 +02:00
service_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
service_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_list.go Add support for sending down service Running and Desired task counts 2019-10-14 10:43:00 -05:00
service_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_logs.go Improve GetTimestamp parsing 2018-05-20 13:07:17 +02:00
service_logs_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_remove.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
service_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
service_update.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
service_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_get_unlock_key.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_get_unlock_key_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_init.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_init_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_inspect.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
swarm_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_join.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_join_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_leave.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_leave_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_unlock.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
swarm_unlock_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
swarm_update.go api/types/swarm: Version: implement stringer interface 2022-05-13 02:40:14 +02:00
swarm_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_inspect.go client: remove wrapResponseError() 2022-03-20 19:04:52 +01:00
task_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_list.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
task_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
task_logs.go Switch from x/net/context -> context 2018-04-23 13:52:44 -07:00
utils.go Add canonical import comment 2018-02-05 16:51:57 -05:00
version.go Client: always call ensureReaderClosed 2019-03-18 15:26:21 +01:00
volume_create.go api: rename volume.VolumeCreateBody to volume.CreateOptions 2022-04-28 22:39:14 +02:00
volume_create_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_inspect.go api/types: replace uses of deprecated types.Volume with volume.Volume 2022-04-21 19:50:59 +02:00
volume_inspect_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_list.go api: add types/volume.ListOptions for a more consistent API 2022-08-03 23:30:28 +02:00
volume_list_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_prune.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
volume_remove.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
volume_remove_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02:00
volume_update.go client: negotiate api version before handling version-specific code 2023-09-20 15:23:27 +02:00
volume_update_test.go client: update error-assertions in tests 2023-05-10 22:13:38 +02: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)
	}
	defer cli.Close()

	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.