[jwrosewell]

Brings the usage sharing record in line with the Processing section of the Usage Sharing Element page and the record decisions in specifications#122 (merged into rc). Both were read in full on rc.

The page says that "escaped - Indicates that the original evidence value included invalid characters, which have been replaced with escaped ones." and "truncated - Indicates that the original evidence value was too long." The record on rc shows them as <PREFIX [escaped="true"] [truncated="true"] Name="FIELD">VALUE</PREFIX>.

What changed

• A value that had characters replaced is marked escaped="true", where shareUsage.js wrote replaced="true".
• A character XML 1.0 does not allow is written as a backslash, x and the four lower case hexadecimal digits of its code, for example \x001f, as the .NET and Go elements do. The code wrote U+FFFD, and its list of allowed characters was wrong (it treated tab and line feed as invalid, and every character above U+00FF as invalid). XML 1.0 allows tab, line feed, carriage return, U+0020 to U+D7FF, U+E000 to U+FFFD and U+10000 to U+10FFFF, and a surrogate pair is one allowed character. A lone surrogate is written as \x and its four digits.
• The limit is 10,000 Unicode code points, where it was 512 characters counted after escaping. It counts the value as supplied and cuts first, then escapes, so the escapes do not count towards it and a character made of two UTF-16 units is never cut in two. A value cut is marked truncated="true". The constant is SHARE_USAGE_MAX_EVIDENCE_CODE_POINTS, so its name gives the unit.
• No CDATA and no BadSchema element are written, as before.
• SessionId, Sequence, ClientIP and the Name attribute go through the same escaping as evidence values (addToShareUsage). The session id comes from query.session-id, which the browser sends, and the client IP from the request, so a value holding < or & made the whole batch invalid XML.
• A request with no client IP has an empty <ClientIP></ClientIP>, where it had <ClientIP>undefined</ClientIP>, because ShareUsageData set clientIp and the writer read clientIP. The record says "Things in [square brackets] are optional", and <ClientIP>IP_ADDRESS</ClientIP> has no brackets. .NET writes the element empty when there is no value (WriteElementString("ClientIP", data.ClientIP)).
• Every record now has <ServerIP>, which the record lists without brackets and which .NET (ShareUsageBase.cs, HostAddress) and Java (getHostAddress) write and Node did not. As in .NET, serverAddress gives the first address of this server that is not a loopback address, an IPv4 address before an IPv6 one, or an empty string where there is none. Node reads the addresses with os.networkInterfaces(), where .NET resolves the host name, and the value is worked out once with the rest of the fixed part of the record.
• ReplacedString writes a value that is not a string as its text, and undefined and null as nothing. Evidence values already reach it as text, because tryAddToData calls value.toString(), so the tests that a number, zero and false are shared as their text pass on the old code too, as guards. The change matters for Sequence, which is a number and now goes through ReplacedString.

Open draft #45 changes shareUsage.js and its tests in the evidence handling, and neither it nor #36 touches the lines changed here. The web integration draft #53 adds one test to shareUsage.test.js away from the lines changed here.

Tests

The invalid character, long value, emoji at the limit, escapes-do-not-count and escaped-and-truncated cases are in tests/shareUsage.test.js. The test server decoded each chunk of the body on its own and split an emoji in two, so it now decodes as the chunks arrive. New since the last review are the XML characters in the session id, the client IP and an evidence name, an empty ClientIP for a request with no client IP, ServerIP for a server with IPv4 and IPv6 addresses, with IPv6 alone and with loopback addresses alone, and a number, zero and false as evidence.

• Red, first set (the attribute name): https://github.com/51Degrees/51degrees-node/actions/runs/42668671893
• Red, the \x form and the 10,000 limit (9 of 29 fail): https://github.com/51Degrees/51degrees-node/actions/runs/42693233607
• Red, code points at the limit (3 of 32 fail): https://github.com/51Degrees/51degrees-node/actions/runs/42693712307
• Red, the new tests on the previous head 3de4c0b (3 of 48 fail). The session id was written as <SessionId>a<b&c"d</SessionId>, the name as Name="x"y&z<", and a request with no client IP had <ClientIP>undefined</ClientIP>. The number, zero and false tests pass, as above: https://github.com/51Degrees/51degrees-node/actions/runs/42796755603
• Green, lint and the usage sharing package tests on 833b56a (48 passed): https://github.com/51Degrees/51degrees-node/actions/runs/42796772772
• Red, the empty ClientIP and ServerIP tests on 833b56a (4 of 51 fail). The record had no <ClientIP></ClientIP> and no <ServerIP>: https://github.com/51Degrees/51degrees-node/actions/runs/42803236764
• Green, lint and the usage sharing package tests on the head 160d1c6 (51 passed): https://github.com/51Degrees/51degrees-node/actions/runs/42803254512
• Full build on the head 160d1c6. Configure and the Ubuntu, Ubuntu ARM and Windows jobs on Node 22 and 24 pass, Configure printed "Left out 2 macOS entries", and all 7 Setting 'PullRequestSha' lines are 160d1c6aff57992cc95ce5379172ccd2486e8735: https://github.com/51Degrees/51degrees-node/actions/runs/42829954329

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

Not done here

An evidence key with no prefix, such as foo rather than header.foo, is written with its name as the element name, and an element name cannot be escaped. That is unchanged here. The elements are also written in a different order from the record, the fixed part first, as .NET writes its fixed part after ClientIP rather than in the record's order. Nothing else on the page differs from the Node code that was checked.