[Azure App Configuration] - Normalize the query parameters in request url

sdk/appconfiguration/app-configuration/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added internal pipeline policy to normalize (case-insensitive alphabetical) ordering of query parameters for deterministic request URLs.
+
 ### Breaking Changes
 
 ### Bugs Fixed
@@ -13,11 +15,12 @@
 ## 1.9.0 (2025-04-08)
 
 ### Features Added
- - Include all the changes from 1.9.0-beta.1 version
-
+
+- Include all the changes from 1.9.0-beta.1 version
+
 ### Other Changes
 
-- Update README with a link to [*`@azure/app-configuration-provider`*](https://www.npmjs.com/package/@azure/app-configuration-provider). [#33152](https://github.com/Azure/azure-sdk-for-js/pull/33152)
+- Update README with a link to [_`@azure/app-configuration-provider`_](https://www.npmjs.com/package/@azure/app-configuration-provider). [#33152](https://github.com/Azure/azure-sdk-for-js/pull/33152)
 
 ## 1.9.0-beta.1 (2025-03-11)
 
@@ -144,7 +147,6 @@ See [`listConfigurationSettings.ts`](https://github.com/Azure/azure-sdk-for-js/t
 ### Other Changes
 
 - Updated our `@azure/core-tracing` dependency to the latest version (1.0.0).
-
   - Notable changes include Removal of `@opentelemetry/api` as a transitive dependency and ensuring that the active context is properly propagated.
   - Customers who would like to continue using OpenTelemetry driven tracing should visit our [OpenTelemetry Instrumentation](https://www.npmjs.com/package/@azure/opentelemetry-instrumentation-azure-sdk) package for instructions.
 
@@ -181,7 +183,6 @@ See [`listConfigurationSettings.ts`](https://github.com/Azure/azure-sdk-for-js/t
 ### Features Added
 
 - Special configuration settings - feature flag and secret reference are now supported. 🎉
-
   - For types, use `ConfigurationSetting<FeatureFlagValue>` and `ConfigurationSetting<SecretReferenceValue>`.
   - Use `parseFeatureFlag` and `parseSecretReference` methods to parse the configuration settings into feature flag and secret reference respectively.
 

sdk/appconfiguration/app-configuration/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "js",
   "TagPrefix": "js/appconfiguration/app-configuration",
-  "Tag": "js/appconfiguration/app-configuration_bdaf29d71a"
+  "Tag": "js/appconfiguration/app-configuration_55c63bcf25"
 }

sdk/appconfiguration/app-configuration/src/appConfigurationClient.ts

@@ -56,7 +56,8 @@ import type { PagedAsyncIterableIterator, PagedResult } from "@azure/core-paging
 import { getPagedAsyncIterator } from "@azure/core-paging";
 import type { PipelinePolicy, RestError } from "@azure/core-rest-pipeline";
 import { bearerTokenAuthenticationPolicy } from "@azure/core-rest-pipeline";
-import { SyncTokens, syncTokenPolicy } from "./internal/synctokenpolicy.js";
+import { SyncTokens, syncTokenPolicy } from "./internal/syncTokenPolicy.js";
+import { queryParamPolicy } from "./internal/queryParamPolicy.js";
 import type { TokenCredential } from "@azure/core-auth";
 import { isTokenCredential } from "@azure/core-auth";
 import type {
@@ -195,6 +196,7 @@ export class AppConfigurationClient {
       internalClientPipelineOptions,
     );
     this.client.pipeline.addPolicy(authPolicy, { phase: "Sign" });
+    this.client.pipeline.addPolicy(queryParamPolicy());
     this.client.pipeline.addPolicy(syncTokenPolicy(this._syncTokens), { afterPhase: "Retry" });
   }
 

sdk/appconfiguration/app-configuration/src/internal/queryParamPolicy.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type {
+  PipelinePolicy,
+  PipelineRequest,
+  PipelineResponse,
+  SendRequest,
+} from "@azure/core-rest-pipeline";
+
+/**
+ * Creates a PipelinePolicy that normalizes query parameters:
+ *  - Lowercase names
+ *  - Sort by lowercase name
+ *  - Preserve the relative order of duplicates
+ */
+export function queryParamPolicy(): PipelinePolicy {
+  return {
+    name: "queryParamPolicy",
+    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
+      try {
+        const originalUrl: string = request.url;
+        const url = new URL(originalUrl);
+
+        if (url.search === "") {
+          return next(request);
+        }
+
+        const params: ParamEntry[] = [];
+        for (const [name, value] of url.searchParams.entries()) {
+          params.push({ lowercaseName: name.toLowerCase(), value });
+        }
+
+        // Modern JavaScript Array.prototype.sort is stable
+        // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#sort_stability
+        params.sort((a, b) => {
+          if (a.lowercaseName < b.lowercaseName) {
+            return -1;
+          } else if (a.lowercaseName > b.lowercaseName) {
+            return 1;
+          }
+          return 0;
+        });
+
+        const newSearchParams = new URLSearchParams();
+        for (const p of params) {
+          newSearchParams.append(p.lowercaseName, p.value);
+        }
+
+        const newUrl = url.origin + url.pathname + "?" + newSearchParams.toString() + url.hash;
+        if (newUrl !== originalUrl) {
+          request.url = newUrl;
+        }
+      } catch {
+        // If anything goes wrong, fall back to sending the original request.
+        console.log("Failed to normalize query parameters.");
+      }
+
+      return next(request);
+    },
+  };
+}
+
+interface ParamEntry {
+  lowercaseName: string;
+  value: string;
+}

sdk/appconfiguration/app-configuration/test/internal/node/http.spec.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { SyncTokens, parseSyncToken } from "../../../src/internal/synctokenpolicy.js";
+import { SyncTokens, parseSyncToken } from "../../../src/internal/syncTokenPolicy.js";
 import {
   assertThrowsRestError,
   createAppConfigurationClientForTests,

sdk/appconfiguration/app-configuration/test/internal/queryParamPolicy.spec.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { describe, it, expect } from "vitest";
+import { queryParamPolicy } from "../../src/internal/queryParamPolicy.js";
+import { createPipelineRequest, createHttpHeaders } from "@azure/core-rest-pipeline";
+import type { PipelineRequest, PipelineResponse } from "@azure/core-rest-pipeline";
+
+function mockNext(returnStatus: number = 200) {
+  return async (request: PipelineRequest): Promise<PipelineResponse> => {
+    return {
+      request,
+      headers: createHttpHeaders({ "url-lookup": request.url }),
+      status: returnStatus,
+    } as PipelineResponse;
+  };
+}
+
+describe("urlQueryParamsNormalizationPolicy", () => {
+  it("normalizes query parameters", async () => {
+    const policy = queryParamPolicy();
+    const request = createPipelineRequest({
+      url: "https://example.azconfig.io/kv?api-version=2023-11-01&After=abcdefg&tags=tag3%3Dvalue3&key=*&label=dev&$Select=key&tags=tag2%3Dvalue2&tags=tag1%3Dvalue1",
+    });
+    const response = await policy.sendRequest(request, mockNext());
+    const finalUrl = response.headers.get("url-lookup")!;
+    console.log(finalUrl);
+    expect(
+      finalUrl.endsWith(
+        "?%24select=key&after=abcdefg&api-version=2023-11-01&key=*&label=dev&tags=tag3%3Dvalue3&tags=tag2%3Dvalue2&tags=tag1%3Dvalue1",
+      ),
+    ).toBe(true);
+  });
+
+  it("keeps original order of query parameters", async () => {
+    const policy = queryParamPolicy();
+    const request = createPipelineRequest({
+      url: "https://example.azconfig.io/kv?tags=tag2&api-version=2023-11-01&tags=tag1",
+    });
+    const response = await policy.sendRequest(request, mockNext());
+    const finalUrl = response.headers.get("url-lookup")!;
+    expect(finalUrl.endsWith("?api-version=2023-11-01&tags=tag2&tags=tag1")).toBe(true);
+  });
+
+  it("keeps key with no value", async () => {
+    const policy = queryParamPolicy();
+    const request = createPipelineRequest({
+      url: "https://example.azconfig.io/kv?tags&api-version=2023-11-01",
+    });
+    const response = await policy.sendRequest(request, mockNext());
+    const finalUrl = response.headers.get("url-lookup")!;
+    expect(finalUrl.endsWith("?api-version=2023-11-01&tags=")).toBe(true);
+  });
+
+  it("removes redundant &", async () => {
+    const policy = queryParamPolicy();
+    const request = createPipelineRequest({
+      url: "https://example.azconfig.io/kv?&&&",
+    });
+    const response = await policy.sendRequest(request, mockNext());
+    const finalUrl = response.headers.get("url-lookup")!;
+    expect(finalUrl.endsWith("?")).toBe(true);
+  });
+});

sdk/appconfiguration/app-configuration/test/public/queryParam.spec.ts

@@ -0,0 +1,179 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { AppConfigurationClient } from "../../src/index.js";
+import type { Recorder } from "@azure-tools/test-recorder";
+import { isLiveMode } from "@azure-tools/test-recorder";
+import type { PipelinePolicy } from "@azure/core-rest-pipeline";
+import { createAppConfigurationClientForTests, startRecorder } from "./utils/testHelpers.js";
+import { describe, it, assert, beforeEach, afterEach } from "vitest";
+
+describe("request url query parameters", () => {
+  let recorder: Recorder;
+
+  beforeEach(async (ctx) => {
+    recorder = await startRecorder(ctx);
+  });
+
+  afterEach(async () => {
+    await recorder.stop();
+  });
+
+  describe("normalize query parameters", () => {
+    it("sort query params in alphabetical order", async () => {
+      const key = recorder.variable(
+        "sortQueryParams",
+        `sortQueryParams${Math.floor(Math.random() * 1000)}`,
+      );
+
+      const { getCapturedUrl, client } = createClientWithUrlCapturePolicy();
+
+      await client.addConfigurationSetting({
+        key,
+        label: "dev",
+        value: "some value",
+        tags: { tag1: "value1" },
+      });
+
+      const configurationSetting = await client.getConfigurationSetting(
+        { key, label: "dev" },
+        { fields: ["key"] },
+      );
+
+      assert.ok(
+        getCapturedUrl(),
+        "Expected to have captured a request URL for getConfigurationSetting",
+      );
+      // Regex enforces exact ordering of query params: $select (or %24select), api-version, label
+      let queryOrderRegex = /\?(?:\$|%24)select=key&api-version=[^&]+&label=dev$/;
+      assert.match(
+        getCapturedUrl()!,
+        queryOrderRegex,
+        `Query parameters not in expected order or values. URL: ${getCapturedUrl()}`,
+      );
+
+      assert.equal(configurationSetting.key, key);
+
+      const listResult = client.listConfigurationSettings({ keyFilter: "*", labelFilter: "dev" });
+
+      for await (const _ of listResult.byPage()) {
+        // do nothing, just drain the iterator
+      }
+
+      // Regex enforces exact ordering of query params: api-version, key, label
+      queryOrderRegex = /\?api-version=[^&]+&key=\*&label=dev$/;
+      assert.match(
+        getCapturedUrl()!,
+        queryOrderRegex,
+        `Query parameters not in expected order or values. URL: ${getCapturedUrl()}`,
+      );
+
+      const listWithTagsResult = client.listConfigurationSettings({
+        keyFilter: "*",
+        labelFilter: "dev",
+        tagsFilter: ["tag2=value2", "tag1=value1", "tag3=value3"],
+      });
+
+      for await (const _ of listWithTagsResult.byPage()) {
+        // do nothing, just drain the iterator
+      }
+
+      // Regex enforces exact ordering of query params: api-version, key, label, tags
+      queryOrderRegex =
+        /\?api-version=[^&]+&key=\*&label=dev&tags=tag2%3Dvalue2&tags=tag1%3Dvalue1&tags=tag3%3Dvalue3$/;
+      assert.match(
+        getCapturedUrl()!,
+        queryOrderRegex,
+        `Query parameters not in expected order or values. URL: ${getCapturedUrl()}`,
+      );
+
+      await client.deleteConfigurationSetting({ key, label: "dev" });
+    });
+
+    // This occasionally hits 429 error (throttling) since we are making 100s of requests in the test to create, get and delete keys.
+    // To avoid hitting the service with too many requests, skipping the test in live.
+    // More details at https://github.com/Azure/azure-sdk-for-js/issues/16743
+    //
+    // Remove the following line if you want to hit the live service.
+    it(
+      "sort query params in alphabetical order - continuation token",
+      { skip: isLiveMode() },
+      async () => {
+        const key = recorder.variable(
+          "sortQueryParamsMultiplePages",
+          `sortQueryParamsMultiplePages${Math.floor(Math.random() * 1000)}`,
+        );
+
+        const { getCapturedUrl, client } = createClientWithUrlCapturePolicy();
+
+        // this number is arbitrarily chosen to match the size of a page + 1
+        const expectedNumberOfLabels = 101;
+
+        let addSettingPromises = [];
+
+        for (let i = 0; i < expectedNumberOfLabels; i++) {
+          addSettingPromises.push(
+            client.addConfigurationSetting({
+              key,
+              value: `the value for ${i}`,
+              label: i.toString(),
+            }),
+          );
+
+          if (i !== 0 && i % 2 === 0) {
+            await Promise.all(addSettingPromises);
+            addSettingPromises = [];
+          }
+        }
+
+        const listResult = client.listConfigurationSettings({
+          keyFilter: key,
+        });
+
+        for await (const _ of listResult.byPage()) {
+          // do nothing, just drain the iterator
+        }
+
+        // Regex enforces exact ordering of query params for continuation page: after, api-version, key
+        // Note that only the request for the second page has the 'after' query param
+        const queryOrderRegex = new RegExp(`\\?after=[^&]+&api-version=[^&]+&key=[^&]+$`);
+
+        assert.match(
+          getCapturedUrl()!,
+          queryOrderRegex,
+          `Query parameters not in expected order or values. URL: ${getCapturedUrl()}`,
+        );
+
+        for (let i = 0; i < expectedNumberOfLabels; i++) {
+          await client.deleteConfigurationSetting({ key, label: i.toString() });
+        }
+      },
+    );
+
+    function createClientWithUrlCapturePolicy(): {
+      getCapturedUrl: () => string | undefined;
+      client: AppConfigurationClient;
+    } {
+      let capturedUrl: string | undefined;
+      const urlCapturePolicy: PipelinePolicy = {
+        name: "UrlCapturePolicy",
+        async sendRequest(request, next) {
+          capturedUrl = request.url;
+          return next(request);
+        },
+      };
+
+      const client = createAppConfigurationClientForTests(
+        recorder.configureClientOptions({
+          additionalPolicies: [
+            {
+              policy: urlCapturePolicy,
+              position: "perRetry",
+            },
+          ],
+        }),
+      );
+      return { getCapturedUrl: () => capturedUrl, client };
+    }
+  });
+});