How all and the per-method block are combined

For each request, HttpConfiguration.getMethodConfiguration(HttpUriRequest) looks at the method name and merges all with the matching block. Anything that is not GET, PUT, HEAD or MKCOL gets all alone.

The merge, in ConfigurationUtils.merge(base, local):

• if only one of the two is present, it is used as-is;
• otherwise all is copied and then the per-method block is layered on top: headers and params are merged key by key (the per-method value wins); useDefaultHeaders is taken from the per-method block if it was set explicitly; connectionTimeout and readTimeout are taken from the per-method block only if they differ from Wagon.DEFAULT_CONNECTION_TIMEOUT and Wagon.DEFAULT_READ_TIMEOUT respectively.

That last rule has a consequence worth knowing in Wagon 3.5.3: you cannot use a per-method block to set a timeout back to the default value. Writing <readTimeout>1800000</readTimeout> inside <get> is indistinguishable from not writing it at all, and the value from <all> survives.

Wagon 3.5.3: usePreemptive is not carried through the merge at all. The copy step does not copy it and the merge step does not apply it, so if both <all> and the block for the method in question are present, the effective usePreemptive is always false. Set it in <all> and leave that method's own block out, or set it only in the method block and leave <all> out. This is what HttpWagonPreemptiveTest does — it configures nothing but setAll(new HttpMethodConfiguration().setUsePreemptive(true)).

Writing headers and params

Both are java.util.Properties, and Plexus accepts two spellings for those. The short form uses the key as the element name:

<headers>
  <User-Agent>my-build/1.0</User-Agent>
</headers>

The long form spells out each entry and works with every Plexus component configurator:

<headers>
  <property>
    <name>User-Agent</name>
    <value>my-build/1.0</value>
  </property>
</headers>

Use the long form for keys that are not valid XML element names — most of the params keys below contain dots, which is fine, but nothing stops a header name from containing characters that are not.

headers

Headers from the configuration are applied with setHeader, so they replace any header of the same name that the provider had already added.

User-Agent gets special handling: getUserAgent(HttpUriRequest) looks it up in httpHeaders first, then in the merged method configuration's headers, and the result is set on the request. If nothing supplies one, no User-Agent is added by Wagon.

useDefaultHeaders

When true — the default — every request gets

Cache-control: no-cache
Pragma: no-cache

before your own headers are applied. Set it to false to suppress them.

params

<params> is an escape hatch onto HttpClient's RequestConfig. Only the keys below are recognised; anything else is silently ignored. Values may optionally be prefixed with a legacy type coercion of the form %type,value — for example %Integer,3 — in which case only the part after the comma is used.

Two of these interact with settings applied elsewhere. params are applied after the request has already been given the Wagon's own connect and read timeouts, so http.socket.timeout and http.connection.timeout take precedence over connectionTimeout/readTimeout and over setTimeout/setReadTimeout. Also, the cookie policy is set to CookieSpecs.BROWSER_COMPATIBILITY before params are applied, so http.protocol.cookie-policy overrides that default.

Expect: 100-continue is enabled unconditionally for PUT requests, before params are applied; http.protocol.expect-continue can therefore turn it off. It is deliberately not enabled for MKCOL, which has no body.

Ignoring cookies

Some repositories send session cookies, often by mistake, alongside HTTP redirection. The cookie's Path can then disagree with the path the client uses, and requests fail. If you know you do not need the session cookie, ignore cookies for the server:

<configuration>
  <httpConfiguration>
    <all>
      <params>
        <http.protocol.cookie-policy>ignore</http.protocol.cookie-policy>
      </params>
    </all>
  </httpConfiguration>
</configuration>

Target server credentials

At connect time, if the AuthenticationInfo has a non-empty user name and a non-empty password, a UsernamePasswordCredentials is registered in the CredentialsProvider under an AuthScope derived from the repository's host and port. A user name without a password registers nothing.

The client is built with an auth scheme registry containing exactly three schemes:

Basic and Digest both work against the target server with a plain user name and password, negotiated in response to the server's challenge. Use http.auth.target-scheme-pref if you need to force the order in which schemes are tried.

NTLM against the target server is not supported. The target credentials are always UsernamePasswordCredentials, never NTCredentials, so the registered NTLM scheme has nothing usable to offer. NTLM is only wired up for proxies — see below.

Preemptive authentication

By default HttpClient waits for a 401 challenge before sending credentials. With usePreemptive set, a BasicScheme is placed in the AuthCache for the target host before the request goes out, provided credentials for that scope exist — so the first request already carries an Authorization: Basic header:

<configuration>
  <httpConfiguration>
    <all>
      <usePreemptive>true</usePreemptive>
    </all>
  </httpConfiguration>
</configuration>

Note the merge caveat above: adding a <get> block alongside this would switch preemptive authentication back off.

Without Expect: 100-continue, a PUT that needs authentication would send its whole payload before the server issues the challenge, and then send it again with credentials: twice the bandwidth and time per artifact. Preemptive authentication avoids that by sending the credentials with the first request, at a price. An unused <server> entry with a wrong user name or password can make some servers answer 401 Unauthorized even for requests that need no authentication, and sending credentials blindly can leak them to paths the server does not protect.

Preemptive Basic authentication is only ever Basic — the cache entry is a BasicScheme. It has no effect on Digest or NTLM.

PUT is a special case in Wagon 3.5.3: AbstractHttpClientWagon.put primes the AuthCache with a BasicScheme for the target host whenever credentials exist, regardless of usePreemptive. Uploads are therefore preemptively authenticated by default. The source marks this as a known wart (“FIXME Perform only when preemptive has been configured”).

basicAuth and proxyAuth — overriding the authentication scope

By default the AuthScope for the target is built from the repository's own host and port with AuthScope.ANY_REALM, and a port of -1 becomes AuthScope.ANY_PORT. BasicAuthScope lets you override host, port and realm.

host and port accept the literal string ANY to mean “match anything”, and setting host, port and realm all to ANY yields AuthScope.ANY.

realm does not work that way, and it is worth being explicit about it because the asymmetry is easy to trip over in Wagon 3.5.3. Omitting realm gives you AuthScope.ANY_REALM, which is what “match any realm” means. Setting it to any value — including ANY, unless host and port are ANY too — matches that string verbatim, so <realm>ANY</realm> on its own produces a scope that only matches a server whose realm is literally ANY. Leave realm out unless you mean to pin it.

This is the setting to reach for when credentials are not being sent because the server's realm or port does not match what Wagon derived from the URL — for instance a repository fronted by a redirect to another host, or one that delegates authentication to an external system that challenges from a different host.

The two scopes are held in fields named basicAuth (for the target) and proxyAuth (for the proxy), reachable through setBasicAuthScope and setProxyBasicAuthScope.

<configuration>
  <basicAuth>
    <host>ANY</host>
    <port>ANY</port>
    <realm>ANY</realm>
  </basicAuth>
</configuration>

That is the all-ANY case, which short-circuits to AuthScope.ANY and so does match any realm. To widen only the host and port, omit realm rather than setting it to ANY:

<configuration>
  <basicAuth>
    <host>ANY</host>
    <port>ANY</port>
  </basicAuth>
</configuration>

Connection pool

Timeouts

TLS

Without maven.wagon.http.ssl.insecure, the default JSSE socket factory is used with HttpClient's browser-compatible hostname verifier.

Retries

A retry handler only reacts to failures while sending the request and reading the response head. It cannot recover a response body that fails part-way through.

Backoff