0011. Storage SFTP basato su ssh2-sftp-client

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

Contesto

I gestionali depositano spesso i file di scambio su SFTP. Serve uno StorageProvider SFTP che si componga con i codec del File connector: elenco directory, download/upload in streaming, autenticazione con password o chiave privata.

Decisione

Adottiamo ssh2-sftp-client (wrapper di alto livello su ssh2).

• list(prefix): elenca i file della directory prefix (non ricorsivo).
• get: download in streaming verso un PassThrough (no file interi in memoria).
• put: upload in streaming (Readable.from(data)), creando le directory mancanti (mkdir -p).
• Il client è iniettato (DI, come pool/connessioni degli altri connettori); loadSftpConfig(prefix) costruisce la config da env (SFTP_HOST/PORT/USER + una tra SFTP_PASSWORD/SFTP_PRIVATE_KEY).
• Test: config pura in unit (CI); I/O via integrazione contro un server SFTP (docker compose, servizio sftp-test con atmoz/sftp), auto-skip senza env. sftp.ts escluso dalla coverage unitaria.

Alternative considerate

• ssh2 diretto — più verboso (gestione manuale dello SFTPStream). ssh2-sftp-client semplifica list/get/put.
• basic-ftp — è per FTP/FTPS, non SFTP (protocollo diverso). Sarà il connettore FTP (#30).

Conseguenze

• Positive: list/get/put SFTP con streaming, auth password o chiave, API allineata allo StorageProvider.
• Costi/limiti: list non ricorsivo (sufficiente per il drop-dir tipico dei gestionali); I/O coperto da integrazione (richiede un server SFTP).