feat: added docs for custom HTTP client injection for S3 client creation

Author: Arjan Lankhaar

guides/hosting/infrastructure/filesystem.md

@@ -221,6 +221,82 @@ shopware:
 
 If your S3 provider does not use buckets as subdomain like Minio in default configuration, you need to set `use_path_style_endpoint` to `true` inside `config`.
 
+#### Custom HTTP client for S3
+
+By default, the underlying AsyncAws S3 client creates its own HTTP client internally, which includes a `RetryableHttpClient` with an AWS-specific retry strategy. This handles transient errors like throttling (HTTP 429), server errors (HTTP 5xx), and other AWS-specific error codes automatically.
+
+If you need to customize the HTTP behavior for S3 operations (e.g., timeouts, HTTP protocol version, or proxy settings), you can register a service with the ID `shopware.filesystem.s3.client`. When this service exists, Shopware injects it into both the filesystem adapter and presigned URL generation.
+
+::: info
+When you provide a custom HTTP client, AsyncAws will **not** wrap it in its own `RetryableHttpClient`. If you need retry behavior, you must configure it yourself as shown below.
+:::
+
+**Simple configuration** (custom timeouts, no retry handling):
+
+```yaml
+# config/packages/framework.yaml
+framework:
+    http_client:
+        scoped_clients:
+            s3.http_client:
+                base_uri: '{your-s3-endpoint}'
+                timeout: 30.0
+                http_version: '1.1'
+```
+
+```xml
+<!-- config/services.xml -->
+<service id="shopware.filesystem.s3.client" alias="s3.http_client"/>
+```
+
+**Recommended configuration** (custom settings with AWS retry support):
+
+```yaml
+# config/packages/framework.yaml
+framework:
+    http_client:
+        scoped_clients:
+            s3.http_client:
+                base_uri: '{your-s3-endpoint}'
+                timeout: 30.0
+                http_version: '1.1'
+```
+
+```xml
+<!-- config/services.xml -->
+<service id="AsyncAws\Core\HttpClient\AwsRetryStrategy"/>
+
+<service id="shopware.filesystem.s3.client" class="Symfony\Component\HttpClient\RetryableHttpClient">
+    <argument type="service" id="s3.http_client"/>
+    <argument type="service" id="AsyncAws\Core\HttpClient\AwsRetryStrategy"/>
+    <argument>3</argument><!-- max retries -->
+</service>
+```
+
+This wraps your scoped client in a `RetryableHttpClient` with the same `AwsRetryStrategy` that AsyncAws uses by default, preserving retry behavior for AWS-specific transient errors while allowing you to control timeouts, HTTP version, and other transport-level settings.
+
+**Without scoped clients** (standalone service definition with retry support):
+
+```yaml
+# config/services.yaml
+services:
+    s3.http_client:
+        class: Symfony\Contracts\HttpClient\HttpClientInterface
+        factory: ['Symfony\Component\HttpClient\HttpClient', 'create']
+        arguments:
+            -
+                timeout: 30
+
+    shopware.filesystem.s3.client:
+        class: Symfony\Component\HttpClient\RetryableHttpClient
+        arguments:
+            - '@s3.http_client'
+            - ~
+            - 3
+```
+
+This creates a plain HTTP client via `HttpClient::create()` with custom options and wraps it in a `RetryableHttpClient` with the default retry strategy.
+
 ### Google Cloud Platform
 
 In order to use the Google Cloud Platform adapter you need to install the `league/flysystem-google-cloud-storage` package.