[dmccoystephenson]

Summary

• README "The wire format" now states that redirects are not followed: the body is streamed with a fixed length, so HttpURLConnection cannot re-send it, a redirect is logged at FINE and the report is dropped, and baseUrl must be the final URL (https:// when the server redirects http:// there).
• The TraceClient.builder(...) Javadoc says the same, so the class docs and the README agree.
• No behaviour change. The documentation-only option from A base URL that redirects drops every report; the README does not say redirects are not followed #25 was taken; following 307/308 would change send() and remains a maintainer decision. A new issue can be opened if that behaviour change is wanted.

The documented behaviour is already pinned by report_aRedirectIsNotFollowedAndIsLoggedFine (added in #24), which asserts that the redirect target is never requested and that a FINE could not deliver ... HttpRetryException line is logged. The README wording says "a redirect" rather than "any 3xx" on purpose: codes that HttpURLConnection does not try to follow (e.g. 304, or 308 on Java 8) come back as a status and are logged as trace server answered <code>. They are still dropped at FINE.

Test plan

• mvn -B verify run locally on Java 21: 81 tests, 0 failures
• CI matrix (Java 8, 17, 21) green on the PR head

Closes #25

Deferred issues

• A quoted enabled: "false" in the server-wide config does not turn reporting off #15 (quoted enabled: "false") touches the opt-out contract and needs a maintainer decision.
• withVersion pushes an event already at MAX_TAGS over the server's tag limit #13 (withVersion exceeding MAX_TAGS) changes what is sent on the wire and needs a maintainer decision.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (CI: build (8), build (17), build (21) green on the head commit):

• Scope: PASS. Only README.md ("The wire format") and the builder(...) Javadoc changed, and both are the documentation option of A base URL that redirects drops every report; the README does not say redirects are not followed #25.
• Tests-new: PASS (not applicable). No new public members were added.
• Tests-fix: PASS (not applicable). There is no behaviour change. The documented behaviour is already pinned by report_aRedirectIsNotFollowedAndIsLoggedFine.
• Sibling structure / renames: PASS (not applicable). No new files and no renames.
• Docs: PASS. The README and the builder(...) Javadoc now say the same thing. The wording "a redirect" was checked against send(): HttpRetryException is thrown for followable codes, and other codes come back as a status logged as trace server answered. Both paths are FINE and drop the report.
• Issue resolution: PASS. A base URL that redirects drops every report; the README does not say redirects are not followed #25 asks the README to say that redirects are not followed, and it now does. The behaviour-change option is left to the maintainer.
• No dependencies / single file / Java 8: PASS. pom.xml is untouched, git ls-files src/main lists only TraceClient.java, and the Java 8 leg is green.
• Never throws / non-blocking / environment seam / version / opt-out contract: PASS (not applicable). The only change in TraceClient.java is a comment.
• CI: PASS. All three matrix legs are green.

Finding fixed during review: README.md:235. The new paragraph had a stray line break before `baseUrl`. It was reflowed in a follow-up commit, and CI was re-run green.

Do-not-auto-merge check: the paths are README.md "The wire format" (not "Opting out" or "Keys") and a Javadoc-only change in TraceClient.java. No wire-format, REASON_*, timeout, or version change is involved, so no listed path matches.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson