From b9bd7cb7105ee0eb8776427c91f789942c2c6936 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Wed, 14 Oct 2026 02:22:20 -0600 Subject: [PATCH 1/2] Say what the server-id, value and event name rules actually are The README and parseServerWideConfig Javadoc allowed any server-id made of [A-Za-z0-9_.-], but the parser also wants a letter or digit first; the wire-format section said value is only omitted when not given, but NaN and infinities are dropped too; and report's Javadoc did not say a null or blank name sends nothing. A test now pins the server-id rule. Co-Authored-By: Claude Opus 5.5 --- README.md | 8 +++++--- .../java/software/stephenson/trace/TraceClient.java | 10 ++++++---- .../software/stephenson/trace/TraceClientTest.java | 8 ++++++++ 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d547a74..c540344 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,9 @@ kept byte for byte. If the file cannot be read or written, a fresh ID is used in memory for that run only — `build()` still never throws. **Resetting it.** Delete the `server-id:` line; the next start writes a new -one. Or set your own value (letters, digits, `_`, `.`, `-`; at most 255 -characters). +one. Or set your own value (letters, digits, `_`, `.`, `-`, starting with a +letter or digit; at most 255 characters). A `server-id:` line whose value is +anything else is ignored, and the next start appends a new one below it. **Opting out.** Every [opt-out](#opting-out) below also stops the ID: a disabled client never generates one, never writes one, and sends nothing. @@ -223,7 +224,8 @@ Shade it into a plugin jar; it is one class. {"application":"MyPlugin","name":"command","value":1.0,"tags":{"name":"home","version":"1.4.0","install":"0f8b6c1e-3a52-4c8e-9a0d-6e2f1b7c4d90"}} ``` -`value` is omitted when not given; `tags` always holds at least `version`, and +`value` is omitted when not given, and when it is NaN or infinite (neither +is JSON); `tags` always holds at least `version`, and `install` whenever the client has an [installation ID](#every-event-carries-a-random-server-id). The server assigns the timestamp. A `201` is success; anything else is logged at `FINE` and dropped. diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index fd71ff0..02ab1c3 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -488,9 +488,10 @@ private ServerWideConfig readServerWideConfig(File pluginsDirectory) { * double- or single-quoted. Entries the trace server would reject -- and * anything this reader does not understand -- are dropped, one by one, * and at most {@link #MAX_TAGS} are kept. The first {@code server-id:} - * line at column 0, outside a {@code tags:} block, whose value is a valid - * tag value made of {@code [A-Za-z0-9_.-]} is the installation's ID; any - * other is ignored. Nothing here throws. + * line at column 0, outside a {@code tags:} block, whose value is at most + * {@value #MAX_TAG_LENGTH} characters of {@code [A-Za-z0-9_.-]} starting + * with a letter or digit is the installation's ID; any other is ignored. + * Nothing here throws. */ static ServerWideConfig parseServerWideConfig(List lines) { Boolean disables = null; @@ -703,7 +704,8 @@ public void report(String name) { /** * Reports that {@code name} happened, with an optional numeric value and - * optional string tags. Returns immediately; see the class comment. + * optional string tags. Returns immediately; see the class comment. A + * {@code null} or blank name sends nothing. */ public void report(String name, Double value, Map tags) { if (executor == null || name == null || name.trim().isEmpty()) { diff --git a/src/test/java/software/stephenson/trace/TraceClientTest.java b/src/test/java/software/stephenson/trace/TraceClientTest.java index ae7ec75..88f837c 100644 --- a/src/test/java/software/stephenson/trace/TraceClientTest.java +++ b/src/test/java/software/stephenson/trace/TraceClientTest.java @@ -1183,6 +1183,14 @@ void installId_anExistingServerIdIsUsedAndAnUnusableOneIsIgnored() { assertEquals("abc-123", TraceClient.parseServerWideConfig(Arrays.asList("server-id: \"abc-123\" # mine")).serverId); assertEquals("first", TraceClient.parseServerWideConfig(Arrays.asList("server-id: first", "server-id: second")).serverId); assertEquals("good", TraceClient.parseServerWideConfig(Arrays.asList("server-id:", "server-id: has space", "server-id: good")).serverId); + assertNull(TraceClient.parseServerWideConfig(Arrays.asList("server-id: _mine")).serverId, "starts with a letter or digit"); + assertEquals("good", TraceClient.parseServerWideConfig(Arrays.asList("server-id: -mine", "server-id: good")).serverId); + StringBuilder overlong = new StringBuilder(); + for (int i = 0; i <= TraceClient.MAX_TAG_LENGTH; i++) { + overlong.append('a'); + } + assertNull(TraceClient.parseServerWideConfig(Arrays.asList("server-id: " + overlong)).serverId, + "at most MAX_TAG_LENGTH characters"); assertNull(TraceClient.parseServerWideConfig(Arrays.asList(" server-id: indented")).serverId, "column 0 only"); assertNull(TraceClient.parseServerWideConfig(Arrays.asList("# server-id: commented")).serverId); TraceClient.ServerWideConfig inTags = TraceClient.parseServerWideConfig(Arrays.asList("tags:", " server-id: x")); From 6fecafee2b539ddeab8b034b41de2ae1447ee3d4 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Wed, 14 Oct 2026 02:23:42 -0600 Subject: [PATCH 2/2] Say the replacement server-id goes to the end of the file resolveInstallId appends, so it does not land below the unusable line unless that line was last. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c540344..6d54261 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,8 @@ in memory for that run only — `build()` still never throws. **Resetting it.** Delete the `server-id:` line; the next start writes a new one. Or set your own value (letters, digits, `_`, `.`, `-`, starting with a letter or digit; at most 255 characters). A `server-id:` line whose value is -anything else is ignored, and the next start appends a new one below it. +anything else is ignored, and the next start appends a new one to the end of +the file. **Opting out.** Every [opt-out](#opting-out) below also stops the ID: a disabled client never generates one, never writes one, and sends nothing.