Release 4.5.12

.github/workflows/nightly-performance.yml

@@ -1,11 +1,12 @@
 name: Nightly Performance
 
-# Runs the on-premise performance examples, writes their throughput figures into
-# results_<name>.json in the common-ci schema, and uploads them so the shared
-# steps/compare-performance.ps1 can chart them on the documentation performance
-# graphs. The Rust on-premise engines call the device-detection-cxx and
-# ip-intelligence-cxx libraries through FFI, so the figures track native
-# performance.
+# Runs the on-premise performance examples against this checkout's crates. Each
+# example writes its results JSON, the shared
+# steps/publish-performance-results.ps1 validates it and puts it at
+# results_<name>.json, and the shared steps/compare-performance.ps1 charts it on
+# the documentation performance graphs. The Rust on-premise engines call the
+# device-detection-cxx and ip-intelligence-cxx libraries through FFI, so the
+# figures track native performance.
 #
 # This mirrors the per-language performance steps in common-ci's nightly
 # workflows. It is kept self-contained here (rather than calling the shared
@@ -56,14 +57,14 @@ jobs:
         with:
           path: rust
           submodules: recursive
-
-      # 2. common-ci, checked out for the shared comparison step
-      #    (steps/compare-performance.ps1). The Rust performance adapter itself
-      #    now lives in this repo at ci/run-performance-tests.ps1 (see
-      #    ci/missing-ci-scripts.md), because it serves only this repository and
-      #    a folder named rust in common-ci collides with the clone of a
-      #    repository named rust (51Degrees/rust#50); only the comparison step
-      #    is shared.
+          # The adapter versions the crates from the release tags.
+          fetch-depth: 0
+
+      # 2. common-ci, checked out for the shared steps that publish and compare
+      #    the results (steps/publish-performance-results.ps1 and
+      #    steps/compare-performance.ps1). The Rust performance adapter lives in
+      #    this repo at ci/run-performance-tests.ps1 (see
+      #    ci/missing-ci-scripts.md), because it serves only this repository.
       - name: Checkout common-ci
         uses: actions/checkout@v4
         with:
@@ -132,8 +133,9 @@ jobs:
         with:
           workspaces: rust
 
-      # 5. Run the performance examples and write results_<name>.json files under
-      #    rust/test-results/performance-summary in the common-ci schema.
+      # 5. Run the performance examples against this checkout's crates and
+      #    publish each results_<name>.json under
+      #    rust/test-results/performance-summary through the shared step.
       - name: Run performance and write results
         shell: pwsh
         run: ./rust/ci/run-performance-tests.ps1 -RepoName rust
@@ -183,15 +185,6 @@ jobs:
             @{ Name = "DeviceDetection-OnPremise"; RunPerformance = $true },
             @{ Name = "IpIntelligence-OnPremise";  RunPerformance = $true }
           )
-          # The performance run resolves examples/Cargo.lock against source.toml
-          # (the local-path patch), which rewrites this tracked lockfile. The
-          # shared compare step publishes graphs by switching to an orphan images
-          # branch, and git aborts that switch while a tracked file has
-          # uncommitted changes. Restore the committed lockfile so the tree is
-          # clean before the switch. Only this one file is touched by the run;
-          # git's "changes would be overwritten" error enumerates every colliding
-          # tracked file, and it lists only examples/Cargo.lock.
-          git -C rust checkout -- examples/Cargo.lock
           ./common-ci/steps/compare-performance.ps1 `
             -RepoName 'rust' `
             -OrgName '51Degrees' `

AGENTS.md

@@ -161,9 +161,12 @@ is ignored by git and listed in the `fodid` manifest's `include`, so
   the bundled asset and `UPSTREAM_PINNED_REF` to the same commit in one pull
   request.
 - `nightly-performance.yml` — nightly (and on-demand) on-premise throughput
-  run that feeds the documentation performance graphs. Its Rust adapter lives
-  in this repo at `ci/run-performance-tests.ps1`; only the shared comparison
-  step (`compare-performance.ps1`) comes from common-ci. See
+  run that feeds the documentation performance graphs. Its adapter,
+  `ci/run-performance-tests.ps1`, runs the performance examples against this
+  checkout's crates through `ci/test-examples-against-source.ps1`. Each
+  example writes its own results JSON, and common-ci provides the steps that
+  validate and compare it (`steps/publish-performance-results.ps1` and
+  `steps/compare-performance.ps1`). See
   [ci/missing-ci-scripts.md](ci/missing-ci-scripts.md) for how this relates to
   the org-standard reusable-workflow contract and the planned direction.
 

README.md

@@ -115,10 +115,12 @@ path, so cloud-only users and most of CI build without a C compiler.
   `.data_update_license_keys(..)`, and that refreshes the engine when the data
   file changes on disk. The Distributor serves nothing without a licence key,
   so a build with polling on and no key fails with an error that says so, as
-  it does in .NET, and a deployment of the free Lite file turns polling off
-  with `.auto_update(false)`. `.file_system_watcher(false)` turns the watcher
-  off, and `pipeline.resource::<DataUpdateService>()` reaches the service for
-  a check on demand.
+  it does in .NET, and a deployment of the free Lite file turns automatic
+  updates off with `.auto_update(false)`, which stops the polling and the file
+  watcher together, as the specification's master switch does.
+  `.file_system_watcher(false)` turns only the watcher off, and
+  `pipeline.resource::<DataUpdateService>()` reaches the service for a check
+  on demand.
 - JavaScript minification in `fiftyone-javascript-builder` is opt-in behind the
   `minify` feature and off by default. See ARCHITECTURE.md for why.
 

ci/missing-ci-scripts.md

@@ -60,9 +60,9 @@ Rust consumer, so there is nothing to share. Every other language keeps its
 - Repoints `nightly-performance.yml` to run `./rust/ci/run-performance-tests.ps1`
   (the workflow checks this repo out into a `rust/` subdirectory) instead of
   `./common-ci/rust/run-performance-tests.ps1`.
-- Keeps the `Checkout common-ci` step, because the comparison step
-  `steps/compare-performance.ps1` is genuinely shared and still comes from
-  common-ci.
+- Keeps the `Checkout common-ci` step, because the steps that publish and
+  compare the results, `steps/publish-performance-results.ps1` and
+  `steps/compare-performance.ps1`, are shared and come from common-ci.
 
 Moving the adapter's home is the structural part of the change. Alongside it,
 this repo's copy has since diverged from the common-ci original with
@@ -71,11 +71,8 @@ repository-specific fixes (the ASN data fetch, the `dryrun` input, the
 fail the job), so the behaviour of the nightly run is not identical to the old
 `common-ci/rust` path.
 
-The copy in `common-ci/rust/run-performance-tests.ps1` is intentionally **left
-in place** for now and will be removed in a separate, manually raised common-ci
-PR. This repo's copy is the one CI uses, and it is now the source of truth: the
-two copies are no longer identical, so the common-ci copy should not be edited
-in place — it is only awaiting deletion.
+common-ci no longer carries a `rust` folder, so this repo's copy is the only
+one.
 
 ## The remaining gap (Phase 2, deferred)
 

ci/run-performance-tests.ps1

@@ -5,11 +5,21 @@ param(
     [string]$RepoName = ".",
     # Where the results files are written, relative to the repo directory. This is
     # the path the nightly workflow uploads and the compare-performance step reads.
-    [string]$OutputDir = "test-results/performance-summary"
+    [string]$OutputDir = "test-results/performance-summary",
+    # The common-ci checkout whose steps/publish-performance-results.ps1
+    # validates each results file and copies it to $OutputDir. CI checks it out
+    # beside this repository.
+    [string]$CommonCi = (Join-Path $RepoName "../common-ci")
 )
 $ErrorActionPreference = "Stop"
 $PSNativeCommandUseErrorActionPreference = $true
 
+# Checked first, so a missing checkout fails before the long build.
+$publishStep = Join-Path $CommonCi "steps/publish-performance-results.ps1"
+if (!(Test-Path -Path $publishStep -PathType Leaf)) {
+    Write-Error "'$publishStep' was not found. Check out 51Degrees/common-ci beside this repository, or pass -CommonCi."
+}
+
 # The ip-intelligence-cxx checkout is a sibling of the repo directory (CI
 # checks this repo out into $RepoName next to it; a local run passes "." from
 # the repo root, whose parent is the workspace holding the sibling checkout).
@@ -39,83 +49,41 @@ try {
     Pop-Location
 }
 
-# Runs the 51Degrees Rust on-premise performance examples in release and writes
-# their throughput figures into results_<Name>.json files, in the same
-# `{ HigherIsBetter = @{ metric = value } }` shape the shared
-# steps/compare-performance.ps1 consumes. The Rust on-premise engines call the
+# Runs the 51Degrees Rust on-premise performance examples in release. Each
+# example writes its own results JSON, in the shape the shared
+# steps/compare-performance.ps1 reads, and the shared
+# steps/publish-performance-results.ps1 validates it and copies it to
+# results_<Name>.json under $OutputDir. The Rust on-premise engines call the
 # device-detection-cxx and ip-intelligence-cxx libraries through FFI, so the
 # figures track the native C/C++ performance.
+#
+# Name is the configuration the graph history is keyed on, and the metric
+# names inside each file are its series, so neither may change.
+$performanceExamples = @(
+    @{ Name = "DeviceDetection-OnPremise"; Package = "device-detection-examples"; Bin = "dd-onprem-performance" }
+    @{ Name = "IpIntelligence-OnPremise"; Package = "ip-intelligence-examples"; Bin = "ipi-onprem-performance" }
+)
 
-Push-Location $RepoName
-try {
-    $summaryDir = Join-Path (Get-Location) $OutputDir
-    New-Item -ItemType Directory -Force -Path $summaryDir | Out-Null
-
-    # The example crates live in their own workspace under examples/ and depend
-    # on the published crates from crates.io by default. The nightly must
-    # benchmark this checkout's engine code, not the released packages, so the
-    # cargo commands run from examples/ with `--config source.toml`, the patch
-    # file that points every fiftyone-* dependency at its local path.
-    $examplesDir = Join-Path (Get-Location) "examples"
+# Absolute, because the examples run from the examples directory.
+$resultsDir = Join-Path (Resolve-Path $RepoName).Path "test-results/performance"
+foreach ($example in $performanceExamples) {
+    $example.Results = Join-Path $resultsDir "results_$($example.Name).json"
+    # A file left by an earlier run would otherwise pass for this run's figures.
+    Remove-Item -Path $example.Results -Force -ErrorAction SilentlyContinue
+}
 
-    # Run one performance example and parse the throughput it prints. The
-    # examples take the highest throughput figure they report (the multi-threaded
-    # pass), which is the headline number for the product.
-    function Get-Throughput {
-        param(
-            [Parameter(Mandatory)][string]$Package,
-            [Parameter(Mandatory)][string]$Bin,
-            [Parameter(Mandatory)][string]$Pattern
-        )
-        Write-Host "Running performance example '$Bin'..."
-        Push-Location $examplesDir
-        try {
-            # The native exit code check is turned off for this one call so the
-            # example output is printed before any failure is raised. With it on,
-            # a non-zero cargo exit threw at the assignment, Write-Host below
-            # never ran, and the job log showed only that cargo ended
-            # with a non-zero exit code, with nothing the example or the
-            # compiler had said. That is what hid why ipi-onprem-performance was
-            # failing every night.
-            $PSNativeCommandUseErrorActionPreference = $false
-            $output = cargo run --release --config source.toml -p $Package --bin $Bin 2>&1 | Out-String
-            $exitCode = $LASTEXITCODE
-        } finally {
-            Pop-Location
-        }
-        Write-Host $output
-        if ($exitCode -ne 0) {
-            Write-Error "'$Bin' exited with code $exitCode. Its output is above."
-        }
-        $found = [regex]::Matches($output, $Pattern)
-        if ($found.Count -eq 0) {
-            Write-Error "Could not parse a throughput figure from '$Bin' output"
-        }
-        # Take the last match so the multi-threaded figure wins where an example
-        # prints both a single- and a multi-threaded result.
-        return [double]$found[$found.Count - 1].Groups[1].Value
+# The examples depend on the published crates. ci/test-examples-against-source.ps1
+# points them at this checkout for the run and puts the manifests and the lock
+# back afterwards, so the figures are for the code being tested and not for the
+# last release. The closure carries the list above into that script.
+$runExamples = {
+    foreach ($example in $performanceExamples) {
+        Write-Host "Running performance example '$($example.Bin)'..."
+        cargo run --release --config source.toml -p $example.Package --bin $example.Bin -- --json-output $example.Results
     }
+}.GetNewClosure()
+& (Join-Path $PSScriptRoot "test-examples-against-source.ps1") -Command $runExamples
 
-    # Device Detection on-premise (Hash): detections per second.
-    $ddDetectionsPerSecond = Get-Throughput `
-        -Package "device-detection-examples" `
-        -Bin "dd-onprem-performance" `
-        -Pattern "Detections per second\s*:\s*(\d+)"
-    @{ HigherIsBetter = @{ DetectionsPerSecond = $ddDetectionsPerSecond } } |
-        ConvertTo-Json -Depth 5 |
-        Out-File (Join-Path $summaryDir "results_DeviceDetection-OnPremise.json") -Encoding utf8
-
-    # IP Intelligence on-premise (IP graph): lookups per second.
-    $ipiLookupsPerSecond = Get-Throughput `
-        -Package "ip-intelligence-examples" `
-        -Bin "ipi-onprem-performance" `
-        -Pattern "Throughput:\s*(\d+)\s*lookups/sec"
-    @{ HigherIsBetter = @{ LookupsPerSecond = $ipiLookupsPerSecond } } |
-        ConvertTo-Json -Depth 5 |
-        Out-File (Join-Path $summaryDir "results_IpIntelligence-OnPremise.json") -Encoding utf8
-
-    Write-Host "Wrote performance results to '$summaryDir':"
-    Get-ChildItem $summaryDir -Filter "results_*.json" | ForEach-Object { Write-Host " - $($_.Name)" }
-} finally {
-    Pop-Location
+foreach ($example in $performanceExamples) {
+    & $publishStep -SourceFile $example.Results -Name $example.Name -RepoName $RepoName -SummaryDir $OutputDir
 }

ci/test-examples-against-source.ps1

@@ -8,7 +8,8 @@ The examples depend on the published crates, and examples/source.toml patches
 each one to its path in this tree. Cargo uses a patch only when its version is
 the one it would pick, so this first writes a version above every published
 release into the crates, then moves each patched crate in the examples' lock to
-the copy in this tree, then checks the lock and runs the tests.
+the copy in this tree, then checks the lock and runs the command, which by
+default builds and tests every example.
 
 The manifests and the lock are put back as they were when the script ends, so a
 run leaves the working tree unchanged.
@@ -20,10 +21,16 @@ such as 4.5.9 after 4.5.8.
 
 .PARAMETER Root
 The workspace root. Defaults to the repository this script sits in.
+
+.PARAMETER Command
+What to run in examples/ while the crates point at this tree. Each cargo
+command in it needs `--config source.toml`. ci/run-performance-tests.ps1 passes
+the performance examples here, so the nightly figures are for this tree.
 #>
 param (
     [string]$Version,
-    [string]$Root = (Join-Path $PSScriptRoot "..")
+    [string]$Root = (Join-Path $PSScriptRoot ".."),
+    [scriptblock]$Command = { cargo test --config source.toml }
 )
 $ErrorActionPreference = "Stop"
 $PSNativeCommandUseErrorActionPreference = $true
@@ -41,7 +48,7 @@ if (-not $Version) {
     }
     $Version = "$($released.Major).$($released.Minor).$($released.Build + 1)"
 }
-Write-Output "Testing the examples against this tree's crates at $Version."
+Write-Output "Running the examples against this tree's crates at $Version."
 
 $examples = Join-Path $Root "examples"
 $patched = Get-Content -Path (Join-Path $examples "source.toml") |
@@ -94,7 +101,7 @@ try {
         throw "These crates still come from crates.io, not this tree:`n$($fromRegistry -join "`n")"
     }
 
-    cargo test --config source.toml
+    & $Command
 } finally {
     Pop-Location
     foreach ($path in $originals.Keys) {

cloud-request-engine/src/constants.rs

@@ -98,3 +98,10 @@ pub const PROCESS_STARTED_KEY: &str = "process-started";
 /// The element-data field holding the advisory warning messages, if any, that
 /// the cloud service returned in the response's `warnings` array.
 pub const WARNINGS_KEY: &str = "warnings";
+
+/// The top-level member of a data response that carries 51Did values.
+///
+/// The cloud creates each 51Did afresh for the request that asked for it, so a
+/// response carrying this member answers that one request and is never shared
+/// with another through the response cache.
+pub const IDENTIFIER_MEMBER: &str = "fodid";