feat: global error refactoring

Fixes #2123
Fixes #2120
Fixes #2116
Fixes #2111
Fixes #2108
Fixes #2086
Fixes #2085
Fixes #2083
Fixes #2081
Fixes #2080
Fixes #2073
Fixes #2072
Fixes #2071
Fixes #2069
Fixes #2044
Fixes #2043
Fixes #2042
Fixes #2041
Fixes #2040
Fixes #2039
Fixes #2036
Fixes #2035
Fixes #2034
Fixes #2028
Fixes #2020
Fixes #1842
Fixes #1810
Fixes #1780
Fixes #1775
Fixes #1736
Fixes #1705
Fixes #1663
Fixes #1645
Fixes #1583
Fixes #1526
Fixes #1514
Fixes #1493
Fixes #1487
Fixes #959
Fixes #779
Closes #823
Closes #85

Refactor global S3 error handling around structured error types and centralized XML response generation.

All S3 errors now share the common APIError base for the fields every error has: Code, HTTP status code, and Message. Non-traditional errors that need AWS-compatible XML fields now have dedicated typed errors in the s3err package. Each typed error implements the shared S3Error behavior so controllers and middleware can handle errors consistently while still emitting error-specific XML fields.

Add a dedicated InvalidArgumentError type because InvalidArgument is used widely across request validation, auth, copy source handling, object lock validation, multipart validation, and header parsing. The new InvalidArgument path uses explicit InvalidArgErrorCode constants with predefined descriptions and ArgumentName values, keeping call sites readable while preserving the correct InvalidArgument XML shape and optional ArgumentValue.

New structured errors added in s3err:
- `AccessForbiddenError`: Method, ResourceType
- `BadDigestError`: CalculatedDigest, ExpectedDigest
- `BucketError`: BucketName
- `ContentSHA256MismatchError`: ClientComputedContentSHA256, S3ComputedContentSHA256
- `EntityTooLargeError`: ProposedSize, MaxSizeAllowed
- `EntityTooSmallError`: ProposedSize, MinSizeAllowed
- `ExpiredPresignedURLError`: ServerTime, XAmzExpires, Expires
- `InvalidAccessKeyIdError`: AWSAccessKeyId
- `InvalidArgumentError`: Description, ArgumentName, ArgumentValue
- `InvalidChunkSizeError`: Chunk, BadChunkSize
- `InvalidDigestError`: ContentMD5
- `InvalidLocationConstraintError`: LocationConstraint
- `InvalidPartError`: UploadId, PartNumber, ETag
- `InvalidRangeError`: RangeRequested, ActualObjectSize
- `InvalidTagError`: TagKey, TagValue
- `KeyTooLongError`: Size, MaxSizeAllowed
- `MetadataTooLargeError`: Size, MaxSizeAllowed
- `MethodNotAllowedError`: Method, ResourceType, AllowedMethods
- `NoSuchUploadError`: UploadId
- `NoSuchVersionError`: Key, VersionId
- `NotImplementedError`: Header, AdditionalMessage
- `PreconditionFailedError`: Condition
- `RequestTimeTooSkewedError`: RequestTime, ServerTime, MaxAllowedSkewMilliseconds
- `SignatureDoesNotMatchError`: AWSAccessKeyId, StringToSign, SignatureProvided, StringToSignBytes, CanonicalRequest, CanonicalRequestBytes

Fix CompleteMultipartUpload validation in the Azure backend so missing or empty `ETag` values return the appropriate S3 error instead of allowing a gateway panic.

Fix presigned authentication expiration validation to compare server time in `UTC`, matching the `UTC` timestamp used by presigned URL signing.

Add request ID and host ID support across S3 requests. Each request now receives AWS S3-like identifiers, returned in response headers as `x-amz-request-id` and `x-amz-id-2` and included in all XML error responses as RequestId and HostId. The generated ID structure is designed to resemble AWS S3 request IDs and host IDs.

The request signature calculation/validation for streaming uploads was previously delayed until the request body was fully read, both for Authorization header authentication and presigned URLs.
Now, the signature is validated immediately in the authorization middlewares without reading the request body, since the signature calculation itself does not depend on the request body. Instead, only the `x-amz-content-sha256` SHA-256 hash calculation is delayed.

auth/access-control.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"net/http"
 	"net/url"
 	"strings"
 
@@ -44,11 +45,11 @@ func VerifyObjectCopyAccess(ctx context.Context, be backend.Backend, copySource
 	// Callers are expected to have already stripped any leading '/'.
 	decodedSrc, err := url.QueryUnescape(copySource)
 	if err != nil {
-		return s3err.GetAPIError(s3err.ErrInvalidCopySourceEncoding)
+		return s3err.GetInvalidArgumentErr(s3err.InvalidArgCopySourceEncoding, copySource)
 	}
 	srcBucket, srcObject, found := strings.Cut(decodedSrc, "/")
 	if !found {
-		return s3err.GetAPIError(s3err.ErrInvalidCopySourceBucket)
+		return s3err.GetInvalidArgumentErr(s3err.InvalidArgCopySourceBucket, copySource)
 	}
 
 	// Get source bucket ACL
@@ -123,13 +124,6 @@ func VerifyAccess(ctx context.Context, be backend.Backend, opts AccessOptions) e
 	return nil
 }
 
-// Detects if the action is policy related
-// e.g.
-// 'GetBucketPolicy', 'PutBucketPolicy'
-func isPolicyAction(action Action) bool {
-	return action == GetBucketPolicyAction || action == PutBucketPolicyAction
-}
-
 // VerifyPublicAccess checks if the bucket is publically accessible by ACL or Policy
 func VerifyPublicAccess(ctx context.Context, be backend.Backend, action Action, permission Permission, bucket, object string) error {
 	// ACL disabled
@@ -142,8 +136,13 @@ func VerifyPublicAccess(ctx context.Context, be backend.Backend, action Action,
 		if err == nil {
 			// if ACLs are disabled, and the bucket grants public access,
 			// policy actions should return 'MethodNotAllowed'
-			if isPolicyAction(action) {
-				return s3err.GetAPIError(s3err.ErrMethodNotAllowed)
+			switch action {
+			case GetBucketPolicyAction:
+				return s3err.GetMethodNotAllowedErr(http.MethodGet, s3err.ResourceTypeBucketPolicy, nil)
+			case PutBucketPolicyAction:
+				return s3err.GetMethodNotAllowedErr(http.MethodPut, s3err.ResourceTypeBucketPolicy, nil)
+			case DeleteBucketPolicyAction:
+				return s3err.GetMethodNotAllowedErr(http.MethodDelete, s3err.ResourceTypeBucketPolicy, nil)
 			}
 
 			return nil

auth/acl.go

@@ -512,6 +512,6 @@ func ValidateCannedACL(acl types.BucketCannedACL) error {
 		return nil
 	default:
 		debuglogger.Logf("invalid bucket canned acl: %v", acl)
-		return s3err.GetAPIError(s3err.ErrInvalidArgument)
+		return s3err.GetInvalidArgumentErr(s3err.InvalidArgCannedAcl, string(acl))
 	}
 }

auth/bucket_cors.go

@@ -122,12 +122,12 @@ type CORSAllowanceConfig struct {
 
 // IsAllowed walks through the CORS rules and finds the first one allowing access.
 // If no rule grants access, returns 'AccessForbidden'
-func (cc *CORSConfiguration) IsAllowed(origin string, method CORSHTTPMethod, headers []CORSHeader) (*CORSAllowanceConfig, error) {
+func (cc *CORSConfiguration) IsAllowed(origin string, method CORSHTTPMethod, headers []CORSHeader, rt s3err.ResourceType) (*CORSAllowanceConfig, error) {
 	// if method is empty, anyways cors is forbidden
 	// skip, without going through the rules
 	if method.IsEmpty() {
 		debuglogger.Logf("empty Access-Control-Request-Method")
-		return nil, s3err.GetAPIError(s3err.ErrCORSForbidden)
+		return nil, s3err.GetAccessForbiddenErr(s3err.ErrCORSForbidden, http.MethodOptions, rt)
 	}
 	for _, rule := range cc.Rules {
 		// find the first rule granting access
@@ -151,7 +151,7 @@ func (cc *CORSConfiguration) IsAllowed(origin string, method CORSHTTPMethod, hea
 	}
 
 	// if no matching rule is found, return AccessForbidden
-	return nil, s3err.GetAPIError(s3err.ErrCORSForbidden)
+	return nil, s3err.GetAccessForbiddenErr(s3err.ErrCORSForbidden, http.MethodOptions, rt)
 }
 
 type CORSRule struct {

auth/bucket_cors_test.go

@@ -279,7 +279,7 @@ func TestCORSConfiguration_IsAllowed(t *testing.T) {
 			},
 			output: output{
 				result: nil,
-				err:    s3err.GetAPIError(s3err.ErrCORSForbidden),
+				err:    s3err.GetAccessForbiddenErr(s3err.ErrCORSForbidden, http.MethodOptions, s3err.ResourceTypeBucket),
 			},
 		},
 		{
@@ -296,7 +296,7 @@ func TestCORSConfiguration_IsAllowed(t *testing.T) {
 			},
 			output: output{
 				result: nil,
-				err:    s3err.GetAPIError(s3err.ErrCORSForbidden),
+				err:    s3err.GetAccessForbiddenErr(s3err.ErrCORSForbidden, http.MethodOptions, s3err.ResourceTypeBucket),
 			},
 		},
 		{
@@ -313,14 +313,14 @@ func TestCORSConfiguration_IsAllowed(t *testing.T) {
 			},
 			output: output{
 				result: nil,
-				err:    s3err.GetAPIError(s3err.ErrCORSForbidden),
+				err:    s3err.GetAccessForbiddenErr(s3err.ErrCORSForbidden, http.MethodOptions, s3err.ResourceTypeBucket),
 			},
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got, err := tt.input.cfg.IsAllowed(tt.input.origin, tt.input.method, tt.input.headers)
+			got, err := tt.input.cfg.IsAllowed(tt.input.origin, tt.input.method, tt.input.headers, s3err.ResourceTypeBucket)
 			assert.EqualValues(t, tt.output.err, err)
 			assert.EqualValues(t, tt.output.result, got)
 		})

auth/object_lock.go

@@ -60,10 +60,10 @@ func ParseBucketLockConfigurationInput(input []byte) ([]byte, error) {
 		}
 
 		if retention.Days != nil && *retention.Days <= 0 {
-			return nil, s3err.GetAPIError(s3err.ErrObjectLockInvalidRetentionPeriod)
+			return nil, s3err.GetInvalidArgumentErr(s3err.InvalidArgObjectLockRetentionDays, fmt.Sprint(*retention.Days))
 		}
 		if retention.Years != nil && *retention.Years <= 0 {
-			return nil, s3err.GetAPIError(s3err.ErrObjectLockInvalidRetentionPeriod)
+			return nil, s3err.GetInvalidArgumentErr(s3err.InvalidArgObjectLockRetentionYears, fmt.Sprint(*retention.Years))
 		}
 
 		config.DefaultRetention = retention
@@ -102,7 +102,7 @@ func ParseObjectLockRetentionInput(input []byte) (*s3response.PutObjectRetention
 
 	if retention.RetainUntilDate.Before(time.Now()) {
 		debuglogger.Logf("object lock retain until date must be in the future")
-		return nil, s3err.GetAPIError(s3err.ErrPastObjectLockRetainDate)
+		return nil, s3err.GetInvalidArgumentErr(s3err.InvalidArgPastObjectLockRetainDate, retention.RetainUntilDate.Format(time.RFC3339))
 	}
 	switch retention.Mode {
 	case types.ObjectLockRetentionModeCompliance:

auth/post_policy.go

@@ -299,11 +299,11 @@ func (c contentLengthRangeCondition) validate() error {
 func (c contentLengthRangeCondition) match(in PostPolicyEvalInput) error {
 	if in.ContentLength > c.max {
 		debuglogger.Logf("POST policy content length %d exceeds max %d", in.ContentLength, c.max)
-		return s3err.GetAPIError(s3err.ErrEntityTooLarge)
+		return s3err.GetEntityTooLargeErr(in.ContentLength, c.max)
 	}
 	if in.ContentLength < c.min {
 		debuglogger.Logf("POST policy content length %d is smaller than min %d", in.ContentLength, c.min)
-		return s3err.GetAPIError(s3err.ErrEntityTooSmall)
+		return s3err.GetEntityTooSmallErr(in.ContentLength, c.min)
 	}
 
 	return nil

auth/post_policy_test.go

@@ -288,7 +288,7 @@ func TestPOSTPolicyEvaluate_ConcretePolicyRejections(t *testing.T) {
 					"x-amz-algorithm": "AWS4-HMAC-SHA256",
 				},
 			},
-			expected: s3err.GetAPIError(s3err.ErrEntityTooLarge),
+			expected: s3err.GetEntityTooLargeErr(10, 4),
 		},
 		{
 			name: "content too small",
@@ -300,7 +300,7 @@ func TestPOSTPolicyEvaluate_ConcretePolicyRejections(t *testing.T) {
 					"x-amz-algorithm": "AWS4-HMAC-SHA256",
 				},
 			},
-			expected: s3err.GetAPIError(s3err.ErrEntityTooSmall),
+			expected: s3err.GetEntityTooSmallErr(1, 2),
 		},
 	}