Cover JSON encoding edges, close/report lifecycle and request headers in tests

[dmccoystephenson]

Summary

Stage B cycle (unit-test expansion). Only characterization tests are added, and no production code is changed. Each new test pins behaviour of TraceClient that no existing test exercised:

• json_dropsInfiniteValuesAndKeepsFiniteOnes: ±Infinity values are omitted, the same way NaN already is.
• json_omitsTagsWhenNullOrEmpty: null or empty tags produce no tags key (README "The wire format").
• json_writesAnEmptyTagsObjectWhenEveryTagIsSkipped: characterizes current behaviour. A non-empty map that holds only null keys/values still emits "tags":{}. The result is valid JSON, and the behaviour is recorded here rather than changed.
• quote_escapesCarriageReturnAndEveryOtherControlCharacter / quote_passesPrintableAndNonAsciiCharactersThrough: covers \r, the \u00XX fallback (\0, \b, \f, \^_), the empty string, and pass-through of non-ASCII and DEL.
• close_isSafeToCallTwice and report_afterCloseIsDroppedWithoutThrowing: the close() Javadoc says "safe to call more than once", and a late report() reaches DiscardPolicy without throwing.
• report_sendsAUserAgentNamingTheClientAndTheApplication: the header must match trace-client/X.Y.Z (<application>). A pattern is used instead of the literal version, so version bumps still touch only the four existing places.
• report_logsASuccessStatusOtherThan201: a 200 counts as a drop and is logged at FINE ("A 201 is success; anything else is logged").
• builder_trimsTheBaseUrlAndApplicationAndDropsEveryTrailingSlash: surrounding whitespace is trimmed, and several trailing slashes collapse to one /api/metrics.

The test fixture's Received record now also captures the User-Agent header.

A documentation accuracy sweep ran during triage first. It checked the README tables, the class Javadoc, pom.xml and the build.yml comment against the code and found no drift, so this cycle moved to test expansion.

No open issues existed at triage, so none were skipped. No tracking issue exists for this change; the gaps were found during triage.

Deferred: #3 (moving the GitHub Actions off the deprecated v4 / Node.js 20 versions) was filed during this cycle's self-review. It is kept out of this PR because it is unrelated to test coverage, and because .github/workflows/* changes are do-not-auto-merge. It should go in a separate PR.

Test plan

• mvn -B verify run locally on Java 21: Tests run: 29, Failures: 0, Errors: 0, Skipped: 0 (19 existing + 10 new)
• CI matrix green on Java 8, 17 and 21 (run 35968474968 on head 16314ea; the Java 8 leg confirms that no post-8 API is used in the tests)

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 (anchored on CI run 35968474968 and the diff):

• Scope: PASS. git diff --stat origin/main shows one file, TraceClientTest.java (+144/−1). Every hunk is either a new test or the User-Agent capture that one of those tests needs.
• Tests-new: PASS (n/a). No public method was added. Ten tests were added for existing untested branches.
• Tests-fix: n/a. No bug fix is included; the tests characterize existing behaviour.
• Sibling structure: PASS. The tests use subject_behaviourInPlainWords names, Arrange/Act/Assert sections, the shared loopback HttpServer, and RecordingHandler on a uniquely named logger, the same as their neighbours.
• Sibling renames: n/a. Nothing was renamed.
• Docs: PASS. Production code and README are unchanged. The new tests assert the README's own claims ("value and tags are omitted when not given", "A 201 is success; anything else is logged at FINE") and the close() Javadoc's "Safe to call more than once".
• Issue resolution: n/a. No Closes #N; this is a Stage B cycle.
• CI: PASS. build (8), build (17) and build (21) are all green on the PR head. Locally, mvn -B verify on Java 21 reported Tests run: 29, Failures: 0.
• No dependencies / Single file / Java 8: PASS. pom.xml and src/main are untouched. The Java 8 leg is green, and the tests use only Java 8 APIs (Collections.emptyMap, String.matches).
• Never throws / Non-blocking / Environment seam / Version agreement / Opt-out contract: n/a. TraceClient.java is unchanged.

Judgment calls, left for the maintainer:

• src/test/java/software/stephenson/trace/TraceClientTest.java, json_writesAnEmptyTagsObjectWhenEveryTagIsSkipped: this test pins "tags":{} for a non-empty map whose entries all have a null key or null value. The output is valid JSON. Whether it drifts from the README ("tags ... omitted when not given") depends on whether such a map counts as "given". The behaviour was characterized, not changed. If the maintainer would rather omit the key, that is a wire-format change to make in json(), with this test updated alongside it.
• src/test/java/software/stephenson/trace/TraceClientTest.java, report_afterCloseIsDroppedWithoutThrowing: this adds one more await(300, MILLISECONDS) negative assertion. It follows the existing pattern and cannot flake toward a false failure (a slow runner only makes the negative more likely to hold), but it adds 300 ms to the suite.
• The User-Agent test matches trace-client/\d+\.\d+\.\d+ \(MyPlugin\) instead of the literal 0.2.0, so a future version bump does not gain a fifth place to edit. As a result, the test does not catch a User-Agent version that disagrees with pom.xml; that check stays in the self-review rubric.

Out-of-diff observation: CI annotations report that actions/checkout@v4 and actions/setup-java@v4 target the deprecated Node.js 20 runtime, and that setup-java@v4 is deprecated. A separate issue has been filed for this (#3), because workflow changes are do-not-auto-merge.

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

---

drafted by Claude on behalf of Daniel Stephenson