From 8c1572d22dd567641856a6df4af3ff9c48b4c631 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sat, 14 Nov 2026 06:01:04 +0000 Subject: [PATCH 1/3] Say what usage sharing shares and how to hand it the web request The rules follow the usage sharing element specification. The element accepts no Evidence and reads the web request each web integration adds as server.http-request, never shares the Cookie header, compares keys without regard to letter case and always shares the Resource Key and License Key. A new section says how an application that builds its own Evidence hands over the request in each language. --- src/pipelineapi/features/usagesharing.md | 42 ++++++++++++++++++++---- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/src/pipelineapi/features/usagesharing.md b/src/pipelineapi/features/usagesharing.md index 01b7d7824f..ffc4a81e9d 100644 --- a/src/pipelineapi/features/usagesharing.md +++ b/src/pipelineapi/features/usagesharing.md @@ -61,15 +61,43 @@ control what is shared and how it is collected: ## Evidence shared -The **usage sharing** element will not be interested in all @evidence in the @flowdata. -These are the rules for whether or not a particular piece of evidence is shared: +The **usage sharing** element accepts no @evidence of its own, so it never changes what the @Pipeline accepts. It shares what it finds in two places instead: -- Any evidence named 'header.<name>', if <name> is **not** on a configured blocklist. -- Any evidence named 'query.<name>', if <name> **is** on a configured allowlist. -- Any evidence named 'cookie.<name>' is ignored, unless <name> starts with '51D_'. -- Any other evidence is shared if it is not on a configured blocklist. +- every @evidence value in the @flowdata, and +- the web request, which a @webintegration hands to the @Pipeline as `server.http-request`. From it the element reads every header other than `Cookie`, every cookie, query string and form parameter and session value, the client IP address, the protocol, and the method and path of the request line. This is how a header that no other element reads is still shared. -The various blocklists and allowlists can be configured using the **share usage** @elementbuilder. +A key found in both places is shared once, with the value from the @evidence. Keys are compared without regard to letter case. + +These are never shared, whatever the configuration, even when all @evidence is shared: + +- `id.email`, a raw email address, and `id.salt`, the salt used to make hashed email identifiers, under any prefix. +- `server.request-query`, the whole query string, and `server.request-path`, the path of the request. +- `header.cookie`, the `Cookie` header, which carries every cookie. The cookies whose names start `51D_` are shared as their own `cookie.` values instead. +- The `server.http-request` value itself. Only the values read from it are shared. + +Unless all @evidence is shared, these rules decide the rest: + +- 'header.<name>' is shared unless <name> is on the configured block list. +- 'cookie.<name>' and 'session.<name>' are shared only when <name> starts with '51D_'. +- 'query.<name>' is shared when <name> starts with '51D_' or is on the configured allow list. +- Any other @evidence is shared. + +The Resource Key and License Key, held as `fiftyone.resource-key` and `fiftyone.license-key`, are always shared, because usage is counted against them. + +The block list and the allow list can be configured using the **share usage** @elementbuilder, along with options to share all query string parameters or all @evidence. + +## Handing over the web request + +Each @webintegration adds `server.http-request` on every request, so a website that uses one has nothing to do. An application that adds @evidence itself, and adds a value only when the @Pipeline's @evidencekeyfilter accepts its key, leaves out every header that no element reads, because the **usage sharing** element accepts none. Such an application adds the request as well. + +| Language | Web integration | Adding @evidence yourself | +|----------|-----------------|---------------------------| +| .NET | `IWebRequestEvidenceService.AddEvidenceFromRequest` in ASP.NET Core, and the ASP.NET module, add the request. | Add an `IReadOnlyDictionary` holding each value of the request under its @evidence key, with the key `Constants.EVIDENCE_HTTPREQUEST_KEY`. | +| Java | The servlet filter adds the request. | Add a `Map` holding each value of the request under its @evidence key, with `flowData.addEvidence(ShareUsageEvidence.HTTP_REQUEST_KEY, request)`. | +| Node.js | `evidence.addFromRequest` adds the request. | Nothing to do. `evidence.add` keeps a value that the **usage sharing** element would share. | +| Python | `webevidence` adds the request. | Nothing to do. The **usage sharing** element finds every value given to the @flowdata. | +| Go | `web.Middleware` adds the request. | Add `core.NewWebRequest(r).WithClientIP(ip)` with the key `core.EvidenceHTTPRequest`, where `r` is the `*http.Request`. | +| Rust | `build_evidence` in `fiftyone_pipeline_web` adds the request. | Give the request with `EvidenceBuilder::http_request`, as a second @evidence holding each value under its @evidence key. | ### Evidence detail From 9d5952a0f143d5aefa992ced187a81942139f05c Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sun, 15 Nov 2026 00:28:47 +0000 Subject: [PATCH 2/3] Say every query value is shared by default, no cookie but 51D_ ones, and that records name each package's version Follows the usage sharing specification as changed on 14 November. The Evidence key filter page also stops saying the never-shared keys and session tracking are .NET or Java only. --- .../concepts/data/evidencekeyfilter.md | 16 ++++++++-------- src/pipelineapi/features/usagesharing.md | 11 ++++++++--- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/src/pipelineapi/concepts/data/evidencekeyfilter.md b/src/pipelineapi/concepts/data/evidencekeyfilter.md index 810fdda4e7..bebda3d6da 100644 --- a/src/pipelineapi/concepts/data/evidencekeyfilter.md +++ b/src/pipelineapi/concepts/data/evidencekeyfilter.md @@ -41,17 +41,17 @@ The filter aggregator includes an evidence key if any child filter includes it. The share usage filter is a specific implementation for 51Degrees @usagesharing. It will include anything that meets the following criteria: -1. Any HTTP header. +1. Any HTTP header other than `Cookie`. 2. Any cookie with a name that starts with '51D_'. -3. A user session cookie, in .NET and Java. It is used only to tell user sessions apart when session tracking is turned on, and it is never sent to 51Degrees. -4. Any session value with a name that starts with '51D_'. +3. Any session value with a name that starts with '51D_'. +4. Any query string or form parameter. 5. Any evidence that is not a header, cookie, session value or query string parameter. -In .NET, evidence named `id.email`, `id.salt`, `request-query` or `request-path` is never shared, whatever its prefix and however the filter is configured. +Some evidence is never shared, whatever the configuration. That includes `id.email`, `id.salt`, `request-query` and `request-path` under any prefix, and every cookie whose name does not start with '51D_'. The @ref PipelineApi_Features_UsageSharing page lists it all. Configuration options allow this to be tuned to meet your requirements: -1. A blacklist of HTTP header names to exclude from sharing can be supplied. -2. In .NET and Java, session tracking can be turned on and the name of the session cookie - can be changed. (The default is the ASP.NET session cookie in .NET and `JSESSIONID` in Java.) -3. A whitelist of query string parameters to share can be supplied. +1. A block list of HTTP header names to exclude from sharing can be supplied. +2. Sharing every query string and form parameter can be turned off. Only those whose names start with '51D_' are then shared, along with any on an allow list that can be supplied. +3. Session tracking can be turned on, so that a repeat of the same evidence from a new user session is shared again. It compares the session cookie, which is never sent to 51Degrees. By default .NET uses the ASP.NET session cookie and Java uses `JSESSIONID`. Node.js, Python, Go and Rust have no default, so give the cookie's name when turning session tracking on. +4. All evidence can be shared, apart from the evidence that is never shared. diff --git a/src/pipelineapi/features/usagesharing.md b/src/pipelineapi/features/usagesharing.md index ffc4a81e9d..d37ea6fb67 100644 --- a/src/pipelineapi/features/usagesharing.md +++ b/src/pipelineapi/features/usagesharing.md @@ -74,17 +74,22 @@ These are never shared, whatever the configuration, even when all @evidence is s - `server.request-query`, the whole query string, and `server.request-path`, the path of the request. - `header.cookie`, the `Cookie` header, which carries every cookie. The cookies whose names start `51D_` are shared as their own `cookie.` values instead. - The `server.http-request` value itself. Only the values read from it are shared. +- A cookie whose name does not start `51D_`. A cookie a site sets for itself, such as its session cookie, is never shared. Unless all @evidence is shared, these rules decide the rest: - 'header.<name>' is shared unless <name> is on the configured block list. -- 'cookie.<name>' and 'session.<name>' are shared only when <name> starts with '51D_'. -- 'query.<name>' is shared when <name> starts with '51D_' or is on the configured allow list. +- 'session.<name>' is shared only when <name> starts with '51D_'. +- 'query.<name>' is shared, for every query string and form parameter. When sharing all query string parameters is turned off, it is shared only when <name> starts with '51D_' or is on the configured allow list. - Any other @evidence is shared. The Resource Key and License Key, held as `fiftyone.resource-key` and `fiftyone.license-key`, are always shared, because usage is counted against them. -The block list and the allow list can be configured using the **share usage** @elementbuilder, along with options to share all query string parameters or all @evidence. +The block list and the allow list can be configured using the **share usage** @elementbuilder, along with options to share all query string parameters, which is on by default, or all @evidence. Sharing all @evidence still leaves out what is never shared, so it shares no cookie other than the '51D_' ones. + +## What else each record carries + +Each record also names the @flowelements in the @Pipeline, the language and its version, the platform, the server's IP address, and every 51Degrees package in use with its version, so that 51Degrees can see how far each release has spread. ## Handing over the web request From 3ce5f6ef67c8d55db0318c040b9c437a82cb2e13 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sun, 15 Nov 2026 00:54:42 +0000 Subject: [PATCH 3/3] Say the session cookie is sent only when its name starts with 51D_ The usage sharing specification shares a session cookie whose name starts 51D_, as it does any such cookie. --- src/pipelineapi/concepts/data/evidencekeyfilter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pipelineapi/concepts/data/evidencekeyfilter.md b/src/pipelineapi/concepts/data/evidencekeyfilter.md index bebda3d6da..d0e36b74f1 100644 --- a/src/pipelineapi/concepts/data/evidencekeyfilter.md +++ b/src/pipelineapi/concepts/data/evidencekeyfilter.md @@ -53,5 +53,5 @@ Configuration options allow this to be tuned to meet your requirements: 1. A block list of HTTP header names to exclude from sharing can be supplied. 2. Sharing every query string and form parameter can be turned off. Only those whose names start with '51D_' are then shared, along with any on an allow list that can be supplied. -3. Session tracking can be turned on, so that a repeat of the same evidence from a new user session is shared again. It compares the session cookie, which is never sent to 51Degrees. By default .NET uses the ASP.NET session cookie and Java uses `JSESSIONID`. Node.js, Python, Go and Rust have no default, so give the cookie's name when turning session tracking on. +3. Session tracking can be turned on, so that a repeat of the same evidence from a new user session is shared again. It compares the session cookie, which is not sent to 51Degrees unless its name starts with '51D_'. By default .NET uses the ASP.NET session cookie and Java uses `JSESSIONID`. Node.js, Python, Go and Rust have no default, so give the cookie's name when turning session tracking on. 4. All evidence can be shared, apart from the evidence that is never shared.