[jwrosewell]

Problem

The usage sharing page gives four rules for what is shared, and they no longer match what the packages do or what the specification says.

• It says nothing about the web request. Since specifications#99 the Usage Sharing Element accepts no Evidence and reads the request each web integration adds as server.http-request, which is how a header no other element reads is still shared. An application that builds its own Evidence through the Pipeline's filter has to hand that request over, and the page does not say so.
• It does not say that the Cookie header is never shared. The releases on Monday 16 November make every language agree on that. 51degrees-dotnet#172 blocks only Cookie by default, where .NET also blocked a header named Cookies, and 51degrees-rust#407 stops Rust sharing the Cookie header when all Evidence is shared.
• It does not say that keys are compared without regard to letter case and that a key found in the Evidence and the request is shared once, which 51degrees-dotnet#167 and 51degrees-python#120 put right in .NET and Python.
• It does not list the keys that are never shared, or say that the Resource Key and License Key always are.

What the specification says

Usage sharing element, Accepted Evidence and Shared Evidence, lines 6 to 90 at c8128ca4. Lines 8 and 18 to 29:

The Usage Sharing Element MUST NOT accept any Evidence.

It shares instead what it finds, from two places:

• every Evidence value in the Flow Data, and
• every header other than Cookie, every cookie, query string parameter and session value of the web request, with its client IP address, its protocol and the method and path of its request line, when the web integration supplies the request as server.http-request (see Populating Evidence). This is how a header that no other Flow Element accepts is still shared.

A key found in both places is shared once, with the value from the Evidence.

Lines 41 to 74 give the keys that are never shared (id.email, id.salt, request-query, request-path and header.cookie) and the rules for the rest, line 35 says "Keys are compared without regard to case", and lines 76 to 79 say the Resource Key and License Key are always shared. The options table, line 404, gives the default for blocked headers as "All HTTP headers are shared except Cookie".

What changed

src/pipelineapi/features/usagesharing.md only.

1. "Evidence shared" now follows the specification's two places, the keys that are never shared, the rules for the rest and the two keys that always are.
2. A new section, "Handing over the web request", says that every web integration adds the request, and how an application that builds its own Evidence adds it in each language. Each line was checked against the language's rc.

Language	Web integration	Adding the request yourself
.NET	IWebRequestEvidenceService.cs line 44, WebPipeline.cs line 322	Constants.cs line 164, EVIDENCE_HTTPREQUEST_KEY
Java	WebRequestEvidence.java line 67	ShareUsageEvidence.java line 44, HTTP_REQUEST_KEY
Node.js	evidence.js line 371, in addFromRequest	not needed, evidence.add keeps a value usage sharing would share
Python	web.py line 74, webevidence	not needed, usage sharing finds every value given to the Flow Data
Go	middleware.go line 218	evidence.go lines 108 to 130, EvidenceHTTPRequest, NewWebRequest and WithClientIP
Rust	request.rs line 244, build_evidence	evidence.rs line 362, EvidenceBuilder::http_request

The rest of the page, including the snippets that add server.client-ip, header.host and header.usage-from, is unchanged and still right.

When this merges

After the Monday 16 November releases reach main, because the Cookie rule in .NET and Rust is on their rc until then.

What remains

• specifications#146, a draft, says that query.session-id and query.sequence never take part in the repeat check and are always written to the record. The page's "Repeated evidence" section says nothing at that level of detail today, so it needs no change, and a sentence can follow once that draft merges.
• PHP has no usage sharing element, so it has no row.

Build

Checks on the head, 8c1572d, all green.

• Preview built the documentation with Doxygen, with no warning from src/pipelineapi/features/usagesharing.md.
• utm-link-lint found no campaign tag, as this repository's .utm-lint.json ({ "mode": "forbid" }) requires.
• Only rc into main passed.

[github-actions]

Documentation preview 👀