From 97ab200657dcc7d56df0a82b5bcd5c1c7fc2889c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Oct 2025 07:30:57 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20Add=20detailed=20comment?=
 =?UTF-8?q?s=20explaining=20S3=20proxy=20bypass=20fix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: GeorgeDong32 <98630204+GeorgeDong32@users.noreply.github.com>
---
 src/main/services/S3Storage.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/main/services/S3Storage.ts b/src/main/services/S3Storage.ts
index fd6af1e6f8..ae63e38745 100644
--- a/src/main/services/S3Storage.ts
+++ b/src/main/services/S3Storage.ts
@@ -59,15 +59,18 @@ export default class S3Storage {
       }
     })()
 
-    // Create a direct dispatcher for S3 to bypass proxy
-    // This prevents proxy interference with large file uploads that can cause incomplete transfers
+    // Fix for S3 backup failure when using proxy
+    // Issue: When proxy is enabled, S3 uploads can fail with incomplete writes
+    // Error: "Io error: put_object write size < data.size(), w_size=15728640, data.size=16396159"
+    // Root cause: AWS SDK uses global fetch/undici dispatcher which routes through proxy,
+    //             causing data corruption or incomplete transfers for large files
+    // Solution: Configure S3Client with a direct dispatcher that bypasses the global proxy
     const directDispatcher = new UndiciAgent({
       connect: {
         timeout: 60000 // 60 second connection timeout
       }
     })
 
-    // Use FetchHttpHandler with direct dispatcher to bypass global proxy settings
     const requestHandler = new FetchHttpHandler({
       requestTimeout: 300000, // 5 minute request timeout for large files
       dispatcher: directDispatcher