⚡ Bolt: 대용량 파일 업로드 청크 크기 증가로 컨텍스트 스위칭 오버헤드 감소

.jules/bolt.md

@@ -63,3 +63,7 @@
 ## 2024-07-30 - Avoid chained string replace when checking character sets
 **Learning:** Using chained `.replace(a, "").replace(b, "")` to check if a string consists entirely of specific characters requires intermediate string allocations for every call. In benchmarks, using `.strip("ab")` is ~30% faster and avoids multiple allocations in the hot path.
 **Action:** When checking if a string is solely composed of specific characters, use `.strip(chars)` instead of chained `.replace()` calls to improve performance.
+
+## 2026-09-01 - Avoid small chunk sizes in asynchronous file uploads
+**Learning:** Small chunk sizes (e.g., 8192 bytes) with `await file.read()` create massive threadpool and context-switching overhead in FastAPI/Starlette, severely limiting parsing throughput on large PDFs.
+**Action:** Improve performance by using larger chunk sizes (e.g., 1MB) defined as a named constant (`UPLOAD_READ_CHUNK_SIZE_BYTES`) and ensure tests use this constant instead of hardcoded equivalent values.

src/newsdom_api/main.py

@@ -42,6 +42,7 @@
 from .service import parse_pdf
 
 MAX_PARSE_UPLOAD_BYTES = 20 * 1024 * 1024
+UPLOAD_READ_CHUNK_SIZE_BYTES = 1024 * 1024
 MAX_AUTHORIZATION_HEADER_BYTES = MAX_BEARER_HEADER_BYTES
 UNSUPPORTED_MEDIA_DETAIL = "Unsupported Media Type"
 PAYLOAD_TOO_LARGE_DETAIL = "Payload Too Large"
@@ -252,7 +253,7 @@ async def parse(
             temporary_file.write(header)
 
             bytes_read = len(header)
-            while chunk := await file.read(8192):
+            while chunk := await file.read(UPLOAD_READ_CHUNK_SIZE_BYTES):
                 bytes_read += len(chunk)
                 if bytes_read > MAX_PARSE_UPLOAD_BYTES:
                     LOGGER.warning(

tests/test_parse_endpoint.py

@@ -9,6 +9,7 @@
 from newsdom_api import mineru_runner
 from newsdom_api.main import (
     MAX_PARSE_UPLOAD_BYTES,
+    UPLOAD_READ_CHUNK_SIZE_BYTES,
     app,
     parse,
     _validate_pdf_structure,
@@ -30,7 +31,7 @@ def __exit__(self, exc_type, exc, tb):
 class _ReadTrackingUpload:
     content_type = "application/pdf"
     filename = "fixture.pdf"
-    size = 10 * 1024 * 1024
+    size = 10 * UPLOAD_READ_CHUNK_SIZE_BYTES
 
     def __init__(self, payload: bytes):
         self._payload = payload
@@ -385,7 +386,7 @@ def test_parse_endpoint_rejects_missing_magic_bytes():
 
 @pytest.mark.asyncio
 async def test_parse_endpoint_rejects_magic_bytes_before_full_read():
-    upload = _ReadTrackingUpload(b"MZ\x90\x00\x03" + (b"x" * 1024 * 1024))
+    upload = _ReadTrackingUpload(b"MZ\x90\x00\x03" + (b"x" * UPLOAD_READ_CHUNK_SIZE_BYTES))
 
     with pytest.raises(HTTPException) as exc_info:
         await parse(upload)