test(amqp): use pinned CFSClean broker

sdk/core/azure_core_amqp/.cspell.json

@@ -4,10 +4,14 @@
   ],
   "ignoreWords": [
     "amqps",
+    "cfsclean",
+    "configfile",
+    "JOBID",
     "mgmt",
     "sasl",
     "sastoken",
+    "setvariable",
     "smalluint",
     "smallulong"
   ]
-}
+}

sdk/core/azure_core_amqp/README.md

@@ -1,3 +1,4 @@
+
 # Azure AMQP library for Rust
 
 Azure AMQP crate for consumption of AMQP based packages in the Azure SDK for Rust and C++.
@@ -14,61 +15,76 @@ The AMQP package is tested using the standard `cargo test` command line:
 cargo test --package azure_core_amqp --all-features
 ```
 
-Certain AMQP tests requires that there be a running AMQP broker on the machine at the time of the test (the tests will run without the broker, the relevant tests will just be skipped).
+Certain AMQP tests require a running AMQP broker. The tests without a broker still run, and the broker-dependent tests are skipped.
+
+Set `TEST_BROKER_REQUIRED` to make a missing broker an error instead of a skip. The broker-dependent tests then fail when `TEST_BROKER_ADDRESS` is absent. The CI pipeline sets `TEST_BROKER_REQUIRED`, so a broker that stops running turns the build red.
 
 One existing AMQP broker is the "TestAMQPBroker" from the azure-amqp GitHub repository.
 
-To launch the TestAMQPBroker, there are two ways of installing and running the TestAmqpBroker, Scripted and Manual.
+The broker can be installed and run through the setup script or through the manual steps below.
 
-### Scripted Broker Install
+### Scripted broker install
 
-Running the broker from a script requires that you first [install Powershell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.4).
-From a running powershell instance,  run the powershell script in the sdk/core/azure_core_amqp directory:
+Install [PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell), the [.NET 10 SDK](https://dot.net/download), and [Git](https://git-scm.com/downloads) 2.49 or later. Git 2.49 added the `git clone --revision` option that the setup script uses. Run the setup script from the repository root.
 
 ```pwsh
 ./sdk/core/azure_core_amqp/Test-Setup.ps1
 ```
 
-This will download the TestAmqpBroker, build it and launch the executable in the background.
+The script clones Azure/azure-amqp at the commit that `Test-Setup.ps1` pins, restores through `eng/templates/NuGet.config.template`, builds `TestAmqpBroker` for .NET 10, and launches it in the background. Run the package tests in the same PowerShell process so `TEST_BROKER_ADDRESS` remains available.
 
-Note that this requires that you have the [.NET SDK](https://dot.net/download) installed on your machine.
-
-You can then run the azure_core_amqp package tests.
+```pwsh
+cargo test --package azure_core_amqp --all-features
+```
 
-Once you have finished running your tests, you run:
+Stop the broker after the tests finish.
 
 ```pwsh
 ./sdk/core/azure_core_amqp/Test-Cleanup.ps1
 ```
 
-which will terminate the test broker.
+#### Updating the broker pin
 
-### Manual Broker Install
+Update the pin to any azure-amqp commit that builds `TestAmqpBroker` for `net10.0`. The commit does not need to carry a restore configuration. Change `$repositoryHash` in `Test-Setup.ps1` to the full 40-character SHA, run the setup and cleanup scripts, and make sure that setup reports a clean azure-amqp clone. The pin stays a bare SHA. A tag is not safe here, because azure-amqp uses lightweight tags and has no tag ruleset, so a maintainer can move a tag to a different commit without a trace.
 
-For Manual testing, first clone the azure-amqp repository to a local directory:
+Set `TEST_BROKER_COMMIT` to try a different commit without a code change.
+
+```pwsh
+$env:TEST_BROKER_COMMIT = '<full 40-character SHA>'
+```
+
+Setup also asks the GitHub compare API whether the pinned commit is reachable from azure-amqp `master`. A reachable pin says nothing. An unreachable pin writes a warning, and `TEST_BROKER_REQUIRE_MERGED` turns that warning into an error. A check that could not run writes a warning and always continues, because the unauthenticated rate limit is 60 requests each hour for each IP address.
+
+`Test-Setup.ps1` holds the pin, and it is the only place that needs an update. The pin sits on `master` in Azure/azure-amqp today, so no warning appears. Azure/azure-amqp squash-merges its pull requests, so the commit that lands on `master` is the `merge_commit_sha` of a merged pull request and never the head commit of that pull request.
+
+### Manual broker install
+
+Clone the pinned azure-amqp commit to a local directory.
 
 ```pwsh
 cd <Test Working Directory>
-git clone https://github.com/Azure/azure-amqp
+git clone https://github.com/Azure/azure-amqp --revision <the commit that Test-Setup.ps1 pins>
 ```
 
-Alternately, you can clone to a specific release in the azure-amqp repository:
+Normal external developer builds use the repository's standard NuGet configuration.
 
 ```pwsh
-git clone https://github.com/Azure/azure-amqp.git --branch hotfix
+cd azure-amqp
+dotnet build .\test\TestAmqpBroker\TestAmqpBroker.csproj --configuration Debug --framework net10.0
 ```
 
-Set an environment variable the test AMQP broker should listen on:
+CFSClean builds restore from the `azure-sdk-for-net` Azure Artifacts feed. The feed is public and answers anonymous reads, so an external developer needs no credentials to restore a package that the feed has already cached. The CFSClean environment supplies credentials because a cache miss makes the feed fetch the package from upstream, and that fetch needs an authenticated caller. Run this restore and build sequence from the clone root.
 
 ```pwsh
-$env:TEST_BROKER_ADDRESS = 'amqp://127.0.0.1:25672'
+dotnet restore .\test\TestAmqpBroker\TestAmqpBroker.csproj --configfile <repo root>\eng\templates\NuGet.config.template
+dotnet build .\test\TestAmqpBroker\TestAmqpBroker.csproj --configuration Debug --framework net10.0 --no-restore
 ```
 
-And launch the test broker:
+Set the broker address and launch the built assembly.
 
 ```pwsh
-cd azure-amqp/test/TestAmqpBroker
-dotnet run -- $env:TEST_BROKER_ADDRESS
+$env:TEST_BROKER_ADDRESS = 'amqp://127.0.0.1:25672'
+dotnet exec .\bin\Debug\TestAmqpBroker\net10.0\TestAmqpBroker.dll $env:TEST_BROKER_ADDRESS /headless
 ```
 
 Now, when you run the cargo tests, the networking functionality of the AMQP APIs will be executed.

sdk/core/azure_core_amqp/Test-Cleanup.ps1

@@ -1,6 +1,5 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
-# cspell: ignore JOBID
 
 . "$PSScriptRoot\..\..\..\eng\common\scripts\common.ps1"
 
@@ -9,12 +8,13 @@ if ($IsMacOS) {
   exit 0
 }
 
-if ($true) {
-  Write-Host "AMQP Test Broker tests disabled until test broker is updated."
+# Test-Setup.ps1 clears TEST_BROKER_JOBID when it stops the broker itself, so
+# there is nothing to clean up.
+if ([string]::IsNullOrWhiteSpace($env:TEST_BROKER_JOBID)) {
+  Write-Host "TEST_BROKER_JOBID is not set. The test broker is not running."
   exit 0
 }
 
-
 Write-Host "Test Broker output:"
 Receive-Job -Id $env:TEST_BROKER_JOBID