Added new rule LroAzureAsyncOperationHeader

docs/lro-azure-async-operation-header.md

@@ -0,0 +1,67 @@
+# LroAzureAsyncOperationHeader
+
+## Category
+
+ARM Error
+
+## Applies to
+
+ARM OpenAPI(swagger) specs
+
+## Related ARM Guideline Code
+
+- RPC-Async-V1-06
+
+## Output Message
+
+All long-running operations must include an Azure-AsyncOperation response header.
+
+## Description
+
+Azure-AsyncOperation header must be supported for all async long-running operations.
+
+## CreatedAt
+
+Oct 11, 2024
+
+## How to fix the violation
+
+Adding the Azure-AsyncOperation header to the response..
+
+## Good Example
+
+```json
+  "/api/configServers": {
+    "put": {
+      "operationId": "ConfigServers_Update",
+      "responses": {
+        "202": {
+          "description": "Accepted",
+          "headers": {
+            "Azure-AsyncOperation": {
+              "type": "string",
+            },
+          },
+        },
+      },
+    },
+  },
+```
+
+## Bad Example
+
+```json
+  "/api/configServers": {
+    "put": {
+      "operationId": "ConfigServers_Update",
+      "responses": {
+        "202": {
+          "description": "Success",
+          "headers": {
+            //No Azure-AsyncOperation header 
+          },
+        },
+      },
+    },
+  },
+```

docs/rules.md

@@ -495,6 +495,12 @@ For Data plane spec, the allowed response status codes for a long DELETE operati
 
 Please refer to [long-running-response-status-code-data-plane.md](./long-running-response-status-code-data-plane.md) for details.
 
+### LroAzureAsyncOperationHeader
+
+Azure-AsyncOperation header must be supported for all async long-running operations.
+
+Please refer to [lro-azure-async-operation-header.md](./lro-azure-async-operation-header.md) for details.
+
 ### LroErrorContent
 
 Error response content of long running operations must follow the error schema provided in the common types v2 and above.

packages/rulesets/generated/spectral/az-arm.js

@@ -3311,6 +3311,17 @@ const ruleset = {
                 function: provisioningState,
             },
         },
+        LroAzureAsyncOperationHeader: {
+            rpcGuidelineCode: "RPC-Async-V1-06",
+            description: "Azure-AsyncOperation header must be supported for all async long-running operations.",
+            message: "{{description}}",
+            severity: "error",
+            formats: [oas2],
+            given: "$[paths,'x-ms-paths'].*.*[?(@property === 'x-ms-long-running-operation' && @ === true)]^.responses.*.headers[?(@property !== 'Azure-AsyncOperation')]",
+            then: {
+                function: falsy,
+            },
+        },
         LroLocationHeader: {
             rpcGuidelineCode: "RPC-Async-V1-07",
             description: "Location header must be supported for all async operations that return 202.",

packages/rulesets/src/spectral/az-arm.ts

@@ -158,6 +158,20 @@ const ruleset: any = {
       },
     },
 
+    // RPC Code: RPC-Async-V1-06
+    LroAzureAsyncOperationHeader: {
+      rpcGuidelineCode: "RPC-Async-V1-06",
+      description: "Azure-AsyncOperation header must be supported for all async long-running operations.",
+      message: "{{description}}",
+      severity: "error",
+      formats: [oas2],
+      given:
+        "$[paths,'x-ms-paths'].*.*[?(@property === 'x-ms-long-running-operation' && @ === true)]^.responses.*.headers[?(@property !== 'Azure-AsyncOperation')]",
+      then: {
+        function: falsy,
+      },
+    },
+
     // RPC Code: RPC-Async-V1-07
     LroLocationHeader: {
       rpcGuidelineCode: "RPC-Async-V1-07",

packages/rulesets/src/spectral/test/lro-azure-async-operation-header.test.ts

@@ -0,0 +1,186 @@
+import { Spectral } from "@stoplight/spectral-core"
+import linterForRule from "./utils"
+
+let linter: Spectral
+
+beforeAll(async () => {
+  linter = await linterForRule("LroAzureAsyncOperationHeader")
+  return linter
+})
+
+const ERROR_MESSAGE = "Azure-AsyncOperation header must be supported for all async long-running operations."
+
+test("LroAzureAsyncOperationHeader should find no errors", () => {
+  const myOpenApiDocument = {
+    swagger: "2.0",
+    paths: {
+      "/foo1/operations": {
+        get: {
+          operationId: "foo_get",
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              // no header scenario
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        post: {
+          operationId: "foo_post",
+          "x-ms-long-running-operation": true,
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                "Azure-AsyncOperation": {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        put: {
+          operationId: "foo_put",
+          "x-ms-long-running-operation": true,
+          responses: {
+            204: {
+              description: "Accepted",
+              headers: {
+                "Azure-AsyncOperation": {
+                  description: "The URL where the status of the asynchronous operation can be checked.",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        delete: {
+          operationId: "foo_put",
+          responses: {
+            204: {
+              description: "No x-ms-long-running-operation ",
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+      },
+    },
+  }
+  return linter.run(myOpenApiDocument).then((results) => {
+    expect(results.length).toBe(0)
+  })
+})
+
+test("LroAzureAsyncOperationHeader should find errors with no Azure-AsyncOperation header", () => {
+  const myOpenApiDocument = {
+    swagger: "2.0",
+    paths: {
+      "/foo1/operations": {
+        get: {
+          operationId: "foo_get",
+          "x-ms-long-running-operation": true,
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                Location: {
+                  description: "No Azure-AsyncOperation header",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        post: {
+          operationId: "foo_post",
+          "x-ms-long-running-operation": false,
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Empty header case",
+              headers: {
+                Location: {
+                  description: "No Azure-AsyncOperation header",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        put: {
+          operationId: "foo_put",
+          "x-ms-long-running-operation": true,
+          responses: {
+            200: {
+              description: "Success",
+            },
+            202: {
+              description: "Accepted",
+              headers: {
+                "azure-asyncOperation1": {
+                  description: "check the wrong wording",
+                  type: "string",
+                },
+              },
+            },
+            default: {
+              description: "Error",
+            },
+          },
+        },
+        delete: {
+          operationId: "foo_put",
+          "x-ms-long-running-operation": true,
+          responses: {
+            202: {
+              description: "Accepted",
+              headers: {
+                "azure-asyncOperation": {
+                  description: "Check case sensitive scenario",
+                  type: "string",
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }
+  return linter.run(myOpenApiDocument).then((results) => {
+    expect(results.length).toBe(3)
+    expect(results[0].path.join(".")).toBe("paths./foo1/operations.get.responses.202.headers.Location")
+    expect(results[0].message).toEqual(ERROR_MESSAGE)
+    expect(results[1].path.join(".")).toBe("paths./foo1/operations.put.responses.202.headers.azure-asyncOperation1")
+    expect(results[1].message).toEqual(ERROR_MESSAGE)
+    expect(results[2].path.join(".")).toBe("paths./foo1/operations.delete.responses.202.headers.azure-asyncOperation")
+    expect(results[2].message).toEqual(ERROR_MESSAGE)
+  })
+})