feat: opt-in API version auto-negotiation#2630
Open
postalservice14 wants to merge 2 commits into
Open
Conversation
Adds DefaultDockerClientConfig.Builder.withApiVersionAutoNegotiation(boolean) (also exposed via DOCKER_API_VERSION_AUTO_NEGOTIATION env var and the api.version.auto.negotiation property). When enabled and no explicit api version is set, DockerClientImpl.getInstance(config, httpClient) queries the daemon's /version endpoint and pins the client to min(daemon ApiVersion, latest version known to docker-java). If that result is below the daemon's MinAPIVersion, the daemon's minimum is used and a WARN is logged - matching the behaviour of moby/client.NegotiateAPIVersion. Default is off; existing callers see no change. The new isApiVersionAutoNegotiationEnabled() method on DockerClientConfig is a default-returning-false interface method, which japicmp already tolerates via the project's METHOD_NEW_DEFAULT override. Fixes docker-java#2547
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an opt-in API version auto-negotiation flag, similar to
moby/client.NegotiateAPIVersion. When enabled, the client queriesGET /versiononce at construction and pins itself tomin(daemon ApiVersion, latest version supported by docker-java). If that result is below the daemon'sMinAPIVersion, the daemon's minimum is used and aWARNis logged.Fixes #2547.
Behaviour
DefaultDockerClientConfig.Builder.withApiVersionAutoNegotiation(boolean), env varDOCKER_API_VERSION_AUTO_NEGOTIATION, propertyapi.version.auto.negotiation(truthy values:truecase-insensitive,1).withApiVersion(...)always wins. If both are set, the explicit version is used and negotiation is skipped./versionresponse or transport exception throwsDockerClientException— the caller opted in, so loud failure is the right call.Implementation
DockerClientConfiggets a newdefault boolean isApiVersionAutoNegotiationEnabled() { return false; }. The project's japicmp config already toleratesMETHOD_NEW_DEFAULT, so this is binary-compatible against the 3.3.4 baseline.ApiVersionNegotiatoris a new public utility class that callsGET /versiondirectly viaDockerHttpClientand applies the moby negotiation formula. It deliberately does not reuseVersionCmdExecto avoid a circular dependency with the cmd-exec factory that's still being constructed.NegotiatedDockerClientConfigis a package-private decorator that overrides onlygetApiVersion(), soDefaultDockerClientConfigstays immutable.DockerClientImpl.getInstance(DockerClientConfig, DockerHttpClient), before the cmd-exec factory is built, so every subsequent command picks up the negotiated version.RemoteApiVersion'sVERSION_1_Xconstants — adding new constants in future bumps just works without touching the negotiator.Test plan
./mvnw -pl docker-java -am test -Dtest='ApiVersionNegotiatorTest,DefaultDockerClientConfigTest'— 30 tests, all green./mvnw clean install -DskipITs— full reactor build, japicmp clean ondocker-java-api+ every transport adapter, Checkstyle clean across all modulesApiVersionfailure pathswithDockerTlsVerify, env-var path, system-property pathOut of scope
NegotiateAPIVersion.This change is