0009. Storage S3 basato su AWS SDK v3 (+ lib-storage)

• Stato: Accettata
• Data: 2026-06-04
• Decisori: Team BI/ETL

Contesto

Serve uno StorageProvider per Amazon S3 (e S3-compatibili come MinIO), che si compone con i codec del File connector. Deve elencare/leggere in streaming e caricare in streaming oggetti di dimensione non nota a priori.

Decisione

Adottiamo @aws-sdk/client-s3 (v3, modulare, tipi inclusi) e @aws-sdk/lib-storage per l'upload multipart in streaming.

• list: ListObjectsV2Command con paginazione (ContinuationToken).
• get: GetObjectCommand → Body come stream di byte.
• put: Upload (lib-storage) con Body = Readable.from(stream) → multipart automatico.
• Il S3Client è iniettato (DI, come pool pg/mssql); loadS3ClientConfig(prefix) lo costruisce da env (S3_REGION, opzionale S3_ENDPOINT + forcePathStyle per MinIO, credenziali opzionali S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY, altrimenti catena AWS standard).
• Test: config pura in unit (CI); I/O via integrazione contro MinIO (docker compose, servizio minio-test), auto-skip senza env. s3.ts escluso dalla coverage unitaria.

Alternative considerate

• PutObjectCommand diretto — richiede Content-Length nota: non adatto allo streaming. Scartato per put.
• aws-sdk v2 (monolitico) — deprecato, bundle grande. Scartato.
• minio SDK — legherebbe al vendor; l'SDK AWS funziona sia con S3 sia con MinIO (endpoint + path-style).

Conseguenze

• Positive: upload streaming senza conoscere la dimensione, paginazione corretta, stesso codice per AWS e MinIO, DI testabile.
• Costi: due dipendenze AWS (modulari, ma non piccolissime). I/O coperto da integrazione (richiede MinIO/LocalStack o un bucket reale).