From 42b2cbd86e2f812c389c7a750cca6d4e4e85783e Mon Sep 17 00:00:00 2001
From: Daniel McCoy Stephenson <dmccoystephenson@gmail.com>
Date: Tue, 6 Oct 2026 01:51:39 -0600
Subject: [PATCH] Document the installId ArgumentException; test Json's name
 and tag-value limits

The constructor summary said it throws only for baseUrl, application and
version problems, but an installId longer than MaxLength throws too. The
MaxLength summary now says the version and installation ID are held to it.

Json's name-too-long and tag-value-too-long reasons had no direct test;
two characterization tests pin their wording and the at-the-limit case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/TraceClient/TraceClient.cs             | 10 ++++---
 tests/TraceClient.Tests/TraceClientTest.cs | 32 ++++++++++++++++++++++
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/src/TraceClient/TraceClient.cs b/src/TraceClient/TraceClient.cs
index 06241b6..4b48f7a 100644
--- a/src/TraceClient/TraceClient.cs
+++ b/src/TraceClient/TraceClient.cs
@@ -76,7 +76,8 @@ public sealed class TraceClient : IDisposable
         /// <summary>The most tags the server accepts on one report.</summary>
         public const int MaxTags = 32;
 
-        /// <summary>The longest application, name, tag key or tag value the server accepts, in UTF-16 chars.</summary>
+        /// <summary>The longest application, name, tag key or tag value the server accepts, in UTF-16 chars.
+        /// The program's version and installation ID are tag values too, so the constructor rejects either past it.</summary>
         public const int MaxLength = 255;
 
         /// <summary>Environment variable that turns reporting off: <c>off</c>, <c>false</c>, <c>0</c>, <c>no</c>.</summary>
@@ -122,9 +123,10 @@ public sealed class TraceClient : IDisposable
         /// <paramref name="version"/>, reporting to the trace server at
         /// <paramref name="baseUrl"/>. Throws <see cref="ArgumentException"/> only for a
         /// missing or malformed <paramref name="baseUrl"/>, a missing
-        /// <paramref name="application"/>, or a missing <paramref name="version"/> or
-        /// one longer than <see cref="MaxLength"/> characters -- programming errors,
-        /// not runtime ones.
+        /// <paramref name="application"/>, a missing <paramref name="version"/> or
+        /// one longer than <see cref="MaxLength"/> characters, or an
+        /// <paramref name="installId"/> longer than <see cref="MaxLength"/> characters --
+        /// programming errors, not runtime ones.
         /// </summary>
         /// <param name="baseUrl">The trace server, e.g. <c>https://trace.danielstephenson.dev</c>.</param>
         /// <param name="application">The program's name, exactly as its key was issued for.</param>
diff --git a/tests/TraceClient.Tests/TraceClientTest.cs b/tests/TraceClient.Tests/TraceClientTest.cs
index 6dbd83f..92b6300 100644
--- a/tests/TraceClient.Tests/TraceClientTest.cs
+++ b/tests/TraceClient.Tests/TraceClientTest.cs
@@ -453,6 +453,38 @@ public void Json_RejectsATagKeyLongerThanTheLimitAndNamesOnlyItsStart()
             Assert.Null(body);
         }
 
+        [Fact]
+        public void Json_RejectsANameLongerThanTheLimitButNotOneAtIt()
+        {
+            string longest = new string('n', TraceClient.MaxLength);
+            string tooLong = new string('n', TraceClient.MaxLength + 1);
+
+            string problem = TraceClient.Json("App", tooLong, null, null, out string rejected);
+
+            Assert.Equal("name longer than " + TraceClient.MaxLength + " characters", problem);
+            Assert.Null(rejected);
+            Assert.Null(TraceClient.Json("App", longest, null, null, out string accepted));
+            Assert.Contains(longest, accepted);
+        }
+
+        [Fact]
+        public void Json_RejectsATagValueLongerThanTheLimitAndNamesItsKey()
+        {
+            // The reason names the key, not the value: the value is what ran
+            // away, and the key is what the program can find in its source.
+            string tooLongValue = new string('v', TraceClient.MaxLength + 1);
+            string longestValue = new string('v', TraceClient.MaxLength);
+
+            string problem = TraceClient.Json("App", "n", null,
+                new Dictionary<string, string> { { "level", tooLongValue } }, out string body);
+
+            Assert.Equal("tag level longer than " + TraceClient.MaxLength + " characters", problem);
+            Assert.Null(body);
+            Assert.Null(TraceClient.Json("App", "n", null,
+                new Dictionary<string, string> { { "level", longestValue } }, out string accepted));
+            Assert.Contains("\"level\":\"" + longestValue + "\"", accepted);
+        }
+
         [Fact]
         public void Quote_EscapesCarriageReturnAndEveryOtherControlCharacter()
         {