slachiewicz opened a new pull request, #905: URL: https://github.com/apache/maven-wagon/pull/905
Three guides that have been requested for a long time. Closes #191 (WAGON-1, open since 2004). Closes #190 (WAGON-3, open since 2004). Closes #490 (WAGON-425, open since 2014). | Page | Covers | |---|---| | `user-guide.md` | What a Wagon is; provider → role hint → URL scheme for all eight providers; obtaining one as a build extension or by lookup; the connect/get/put/disconnect lifecycle with working code; a capability matrix; `Repository` URL parsing including credentials being stripped from `getUrl()`; `AuthenticationInfo`; proxies and `nonProxyHosts` globbing; the two timeouts; streaming versus file transfer; listeners, including that `transferProgress` runs synchronously on the transfer thread; the exception table with the actual message wording | | `developer-guide.md` | The SPI; what `AbstractWagon` provides and the two methods a provider must supply; `StreamWagon`'s contract and when it does not fit; both registration mechanisms — the `@plexus.component` tag and a hand-written `components.xml`; `wagon-provider-test` and what you inherit from `WagonTestCase`; the HTTP TCK, its use-case ids, and how to wire it in and mark a case unsupported; running the suites | | `http-configuration.md` | The `<server><configuration>` block for wagon-http; `httpConfiguration` and the six `HttpMethodConfiguration` properties; the merge semantics and their consequences; both XML spellings Plexus accepts; all 17 recognised `params` keys mapped to their `RequestConfig` setters; auth schemes, preemptive auth, scope overrides, proxy and NTLM; the deprecated `httpHeaders`; 429 backoff; the system-property reference | Everything is grounded in the source. Where something could not be verified from this repository it was left out rather than guessed — noted below. `mvn site` builds. The rendered HTML was checked rather than just the exit code, which caught one real defect: Doxia generates heading ids as `What_a_Wagon_is`, not the kebab-case GitHub form, so the cross-page anchors were dead until corrected. ### Deliberately not covered How `settings.xml` populates `ProxyInfo.ntlmHost`/`ntlmDomain` (that mapping lives in Maven core), how Resolver's wagon transport picks a provider (out of this repository), and which of wagon-http or wagon-http-lightweight wins when both are on the class path (the container decides, not Wagon). ### Things found in the code while writing this Documented where they affect the reader, not fixed here, and worth separate issues: - **`usePreemptive` never survives a merge.** `HttpMethodConfiguration.copy()` does not copy it and `ConfigurationUtils.merge()` never applies it, so whenever both `<all>` and the block for a method are present the effective value is always `false`. `HttpWagonPreemptiveTest` passes only because it sets `<all>` alone. - **NTLM against the target server cannot work.** `NTCredentials` is only ever constructed for a proxy, so the registered NTLM scheme has nothing usable to offer an NTLM-protected repository. This is the most likely way a reader of WAGON-425 would be misled. - **PUT is always preemptively authenticated**, regardless of configuration; the source carries `// FIXME Perform only when preemptive has been configured`. - **Per-method timeouts cannot be set back to the default value**, because the merge only takes them when they differ from `Wagon.DEFAULT_*`. - `BasicAuthScope`'s javadoc documents `/server/proxyBasicAuth`, which matches no field; the field is `proxyAuth`. - `README.md` tells contributors to run `mvn -Prun-its verify`. There is no `run-its` profile anywhere in this repository. - `wagon-tcks/wagon-tck-http/sample-tck-consumer` is in no `<modules>`, still 1.0-SNAPSHOT against decade-old dependencies, and is the only thing resembling "how to consume the TCK". The guide documents the real wiring from `wagon-http`'s `TckTest` instead. The four provider pages carrying the "removed in version 4.0.0" notice were left alone. The new pages describe what exists and do not repeat that claim. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
