S3Client breaking change: DEFAULT requests must pass operation_name

awscrt/s3.py

@@ -314,10 +314,25 @@ def make_request(
             request (HttpRequest): The overall outgoing API request for S3 operation.
                 If the request body is a file, set send_filepath for better performance.
 
-            operation_name(Optional[str]): Optional S3 operation name (e.g. "CreateBucket").
-                This will only be used when `type` is :attr:`~S3RequestType.DEFAULT`;
-                it is automatically populated for other types.
+            operation_name(Optional[str]): S3 operation name (e.g. "CreateBucket").
+                This MUST be set when `type` is :attr:`~S3RequestType.DEFAULT`.
+                It is ignored for other types, since the operation is implicitly known.
+                See `S3 API documentation
+                <https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html>`_
+                for the canonical list of names.
+
                 This name is used to fill out details in metrics and error reports.
+                It also drives some operation-specific behavior.
+                If you pass the wrong name, you risk getting the wrong behavior.
+
+                For example, every operation except "GetObject" has its response checked
+                for error, even if the HTTP status-code was 200 OK
+                (see `knowledge center <https://repost.aws/knowledge-center/s3-resolve-200-internalerror>`_).
+                If you used the :attr:`~S3RequestType.DEFAULT` type to do
+                `GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_,
+                but mis-named it "Download", and the object looked like XML with an error code,
+                then the request would fail. You risk logging the full response body,
+                and leaking sensitive data.
 
             recv_filepath (Optional[str]): Optional file path. If set, the
                 response body is written directly to a file and the
@@ -499,6 +514,9 @@ def __init__(
         assert isinstance(part_size, int) or part_size is None
         assert isinstance(multipart_upload_threshold, int) or multipart_upload_threshold is None
 
+        if type == S3RequestType.DEFAULT and not operation_name:
+            raise ValueError("'operation_name' must be set when using S3RequestType.DEFAULT")
+
         super().__init__()
 
         self._finished_future = Future()
@@ -567,12 +585,11 @@ class S3ResponseError(awscrt.exceptions.AwsCrtError):
         headers (list[tuple[str, str]]): Headers from HTTP response.
         body (Optional[bytes]): Body of HTTP response (if any).
             This is usually XML. It may be None in the case of a HEAD response.
-        operation_name (Optional[str]): Name of the S3 operation that failed (if known).
+        operation_name: Name of the S3 operation that failed.
             For example, if a :attr:`~S3RequestType.PUT_OBJECT` fails
             this could be "PutObject", "CreateMultipartUpload", "UploadPart",
             "CompleteMultipartUpload", or others. For :attr:`~S3RequestType.DEFAULT`,
             this is the `operation_name` passed to :meth:`S3Client.make_request()`.
-            If the S3 operation name is unknown, this will be None.
         code (int): CRT error code.
         name (str): CRT error name.
         message (str): CRT error message.