Add comments linking to relevent docs

Author: nickrobinson251

test/azure_blobs_exception_tests.jl

@@ -152,6 +152,15 @@
     end
 end # @testitem
 
+### See Azure Blob Storage docs: https://learn.microsoft.com/en-us/rest/api/storageservices
+### - "Common REST API error codes":
+###   https://learn.microsoft.com/en-us/rest/api/storageservices/common-rest-api-error-codes
+### - "Azure Blob Storage error codes":
+###   https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-error-codes
+### - "Get Blob"
+###  https://learn.microsoft.com/en-us/rest/api/storageservices/get-blob
+### - "Put Blob"
+###  https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob
 @testitem "BlobStorage retries" setup=[InitializeRustStore] begin
     using CloudBase.CloudTest: Azurite
     import CloudBase
@@ -198,11 +207,11 @@ end # @testitem
         return nrequests[]
     end
 
-    # See https://learn.microsoft.com/en-us/rest/api/searchservice/http-status-codes
-
     @testset "400: Bad Request" begin
         # Returned when there's an error in the request URI, headers, or body. The response body
         # contains an error message explaining what the specific problem is.
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-error-codes
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.400
         nrequests = test_status(:GET, 400)
         @test nrequests == 1
         nrequests = test_status(:PUT, 400)
@@ -211,18 +220,23 @@ end # @testitem
 
     @testset "403: Forbidden" begin
         # Returned when you pass an invalid api-key.
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.403
         nrequests = test_status(:GET, 403)
         @test nrequests == 1
         nrequests = test_status(:PUT, 403)
         @test nrequests == 1
     end
 
     @testset "404: Not Found" begin
+        # Returned when container not found or blob not found
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-error-codes
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.404
         nrequests = test_status(:GET, 404)
         @test nrequests == 1
     end
 
     @testset "405: Method Not Supported" begin
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.405
         nrequests = test_status(:GET, 405, ["Allow" => "PUT"])
         @test nrequests == 1
         nrequests = test_status(:PUT, 405, ["Allow" => "GET"])
@@ -231,7 +245,9 @@ end # @testitem
 
     @testset "409: Conflict" begin
         # Returned when write operations conflict.
-        # NOTE: We currently don't retry but maybe we should? This is probably a case where the
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-error-codes
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.409
+        # TODO: We currently don't retry but maybe we should? This is probably a case where the
         # retry logic should add more noise to the backoff so that multiple writers don't collide on retry.
         nrequests = test_status(:GET, 409)
         @test nrequests == 1 + max_retries broken=true
@@ -241,22 +257,32 @@ end # @testitem
 
     @testset "412: Precondition Failed" begin
         # Returned when an If-Match or If-None-Match header's condition evaluates to false
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob#blob-custom-properties
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.412
         nrequests = test_status(:GET, 412)
         @test nrequests == 1
         nrequests = test_status(:PUT, 412)
         @test nrequests == 1
     end
 
     @testset "413: Content Too Large" begin
-        # https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob?tabs=shared-access-signatures#remarks
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob#remarks
+        #   If you attempt to upload either a block blob that's larger than the maximum
+        #   permitted size for that service version or a page blob that's larger than 8 TiB,
+        #   the service returns status code 413 (Request Entity Too Large). Blob Storage also
+        #   returns additional information about the error in the response, including the
+        #   maximum permitted blob size, in bytes.
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.413
         nrequests = test_status(:PUT, 413)
         @test nrequests == 1
     end
 
     @testset "429: Too Many Requests" begin
+        # See https://www.rfc-editor.org/rfc/rfc6585#section-4
+        # See https://www.rfc-editor.org/rfc/rfc9110#field.retry-after
         # TODO: We probably should respect the Retry-After header, but we currently don't
         # (and we don't know if Azure actually sets it)
-        # NOTE: This can happen when Azure is throttling us, so it might be a good idea to retry with some
+        # This can happen when Azure is throttling us, so it might be a good idea to retry with some
         # larger initial backoff (very eager retries probably only make the situation worse).
         nrequests = test_status(:GET, 429, ["Retry-After" => 10])
         @test nrequests == 1 + max_retries broken=true
@@ -265,24 +291,42 @@ end # @testitem
     end
 
     @testset "502: Bad Gateway" begin
-        # This error occurs when you enter HTTP instead of HTTPS in the connection.
+        # https://www.rfc-editor.org/rfc/rfc9110#status.502
+        #   The 502 (Bad Gateway) status code indicates that the server, while acting as a
+        #   gateway or proxy, received an invalid response from an inbound server it accessed
+        #   while attempting to fulfill the request.
+        # This error can occur when you enter HTTP instead of HTTPS in the connection.
         nrequests = test_status(:GET, 502)
         @test nrequests == 1 broken=true
         nrequests = test_status(:PUT, 502)
         @test nrequests == 1 broken=true
     end
 
     @testset "503: Service Unavailable" begin
-        # NOTE: This seems similar to 429 and the Azure docs specifically say:
-        #    Important: In this case, we highly recommend that your client code back off and wait before retrying
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.503
+        #   The 503 (Service Unavailable) status code indicates that the server is currently
+        #   unable to handle the request due to a temporary overload or scheduled maintenance,
+        #   which will likely be alleviated after some delay. The server MAY send a Retry-After
+        #   header field (Section 10.2.3) to suggest an appropriate amount of time for the
+        #   client to wait before retrying the request.
+        # See https://learn.microsoft.com/en-us/rest/api/storageservices/common-rest-api-error-codes
+        #   An operation on any of the Azure Storage services can return the following error codes:
+        #   Error code 	HTTP status code 	        User message
+        #   ServerBusy 	Service Unavailable (503) 	The server is currently unable to receive requests. Please retry your request.
+        #   ServerBusy 	Service Unavailable (503) 	Ingress is over the account limit.
+        #   ServerBusy 	Service Unavailable (503) 	Egress is over the account limit.
+        #   ServerBusy 	Service Unavailable (503) 	Operations per second is over the account limit.
         nrequests = test_status(:GET, 503)
         @test nrequests == 1 + max_retries
         nrequests = test_status(:PUT, 503)
         @test nrequests == 1 + max_retries
     end
 
     @testset "504: Gateway Timeout" begin
-        # Azure AI Search listens on HTTPS port 443. If your search service URL contains HTTP instead of HTTPS, a 504 status code is returned.
+        # See https://www.rfc-editor.org/rfc/rfc9110#status.504
+        #   The 504 (Gateway Timeout) status code indicates that the server, while acting as
+        #   a gateway or proxy, did not receive a timely response from an upstream server it
+        #   needed to access in order to complete the request
         nrequests = test_status(:GET, 504)
         @test nrequests == 1 broken=true
         nrequests = test_status(:PUT, 504)