La funzionalità Signed URL File Upload ti permette di inviare file direttamente dal client a Google Cloud Storage (GCS) tramite URL sicuri e con scadenza temporale. Questo migliora la velocità e l'affidabilità dell'upload, elimina la pressione sulla memoria del server e supporta file multimediali di grandi dimensioni — fino a 100MB su WhatsApp e 5MB sugli altri canali. Scopri come funziona, le principali misure di sicurezza e come implementare il flusso in tre step.

INDICE

Cos'è il Signed URL File Upload?

Signed URL File Upload è un aggiornamento infrastrutturale che sostituisce gli upload con buffer lato server con uno streaming diretto e sicuro dal client a GCS. Invece di inviare i byte del file attraverso i server applicativi, il client carica direttamente su un URL firmato a breve scadenza emesso da HITLEAD. Questa architettura riduce il rischio di Out-Of-Memory (OOM), velocizza i trasferimenti e applica validazione dei file e controlli di accesso.

Vantaggi principali

Conoscere i vantaggi ti aiuta a decidere quando adottare questo flusso per casi d'uso di messaggistica e media, in particolare scenari ad alto volume o con file di grandi dimensioni come WhatsApp.

  • Stabilità: i file non vengono mai bufferizzati nella memoria del server, eliminando i crash OOM.
  • Upload più grandi: supporto per file fino a 100MB su WhatsApp; altri canali fino a 5MB.
  • Performance: il trasferimento diretto client-GCS accorcia il percorso di upload e riduce la latenza.
  • Affidabilità: i Signed URL scadono dopo 15 minuti con gestione chiara degli errori alla scadenza.
  • Sicurezza: validazione del percorso, controllo degli accessi e verifica del content-type in più fasi.

Flusso di upload in tre step

Il pattern con Signed URL suddivide l'upload in fasi distinte — richiesta, upload e completamento — in modo che ogni step possa validare i metadati, applicare i limiti e restituire errori utili senza rischiare la memoria del server.

1. Avvio — POST /conversations/messages/upload/initiate

Invia i metadati del file per richiedere un Signed URL a scadenza temporale e il percorso dell'oggetto.

2. Upload — Client → PUT del file direttamente al Signed URL (GCS)

Invia i byte del file a GCS utilizzando l'URL fornito prima che scada.

3. Completamento — POST /conversations/messages/upload/complete

HITLEAD verifica l'oggetto memorizzato e restituisce l'URL pubblico da usare nei messaggi.

Limiti di dimensione per canale

I diversi canali di messaggistica hanno dimensioni massime diverse per i file multimediali. Applicare i limiti in anticipo evita sprechi di banda e fornisce un feedback di errore più rapido.

  • WhatsApp: fino a 100MB
  • Tutti gli altri canali: fino a 5MB

Pre-validazione: i file troppo grandi vengono rifiutati prima che l'upload inizi, per risparmiare tempo e dati.

Validazione del Content-Type

I tipi MIME corretti garantiscono che gli upload siano sicuri e compatibili. La validazione a doppio livello blocca file falsificati o non corrispondenti che potrebbero compromettere la consegna.

  • All'avvio: verifica che il contentType dichiarato corrisponda all'estensione del file.
  • Al completamento: verifica che il contentType memorizzato in GCS corrisponda al nome del file.
  • Risultato: previene lo spoofing del content-type e le discrepanze di tipo file.

Sicurezza e controllo degli accessi

Misure di sicurezza robuste proteggono i namespace di storage e garantiscono che solo gli utenti autorizzati possano caricare file nella conversazione e nella posizione corretta.

  • Verifica che la conversazione esista e appartenga alla location specificata.
  • Controlla che l'utente abbia accesso a quella location.
  • Garantisce che il percorso del file corrisponda al formato atteso per la location/conversazione.
  • I Signed URL hanno scadenza temporale (15 minuti) per ridurre i rischi di utilizzo improprio.

Gestione degli errori e scadenza

Sapere come emergono gli errori in ogni fase ti aiuta a implementare client resilienti che si riprendono correttamente da errori di validazione o URL scaduti.

  • URL scaduto: richiedi un nuovo Signed URL ripetendo l'avvio.
  • File troppo grande: ridimensiona il file o passa a un canale con un limite più alto (es. WhatsApp fino a 100MB).
  • Mismatch del content-type: assicurati che l'estensione del file e il Content-Type rappresentino accuratamente il file.
  • Errori di permesso/percorso: verifica l'accesso alla location e gli identificatori della conversazione.

Consigli di implementazione

Questi suggerimenti pratici riducono le difficoltà durante l'integrazione e migliorano il tasso di successo per gli upload di file di grandi dimensioni.

  • Avvia la fase di inizializzazione vicino al momento effettivo dell'upload per massimizzare la finestra di 15 minuti.
  • Imposta sempre un header Content-Type esplicito nella richiesta PUT corrispondente al file.
  • Acquisisci e registra il percorso dell'oggetto restituito dall'avvio per il troubleshooting.
  • Per file di grandi dimensioni (es. video WhatsApp), evita retry non necessari; se l'upload si blocca vicino alla scadenza, ripeti l'inizializzazione.
  • Valida dimensione e MIME lato client prima dell'avvio per mostrare errori più rapidi agli utenti.

Domande frequenti

D. La chiamata di completamento è obbligatoria?

Sì. Il completamento verifica l'oggetto in storage e restituisce l'URL finale per la messaggistica.

D. Cosa succede se il Signed URL scade durante l'upload?

Riavvia il flusso: ripeti l'avvio per ottenere un nuovo Signed URL, poi carica e completa.

D. Gli oggetti sono pubblici dopo il completamento?

Lo step di completamento restituisce un URL pubblico da usare nei messaggi. Segui le policy della tua organizzazione sulla gestione dei dati quando condividi.

D. Posso caricare qualsiasi tipo di file se rientra nel limite di dimensione?

No. La validazione del content-type blocca le discrepanze; assicurati che l'estensione del file e il Content-Type siano corretti.

D. Gli altri canali oltre a WhatsApp supportano i 100MB?

No. Gli altri canali sono limitati a 5MB.

D. Come migliora la stabilità?

I file vengono trasmessi direttamente a GCS; il server applicativo non bufferizza mai il contenuto del file, eliminando il rischio OOM.

D. Qual è la durata del Signed URL?

I Signed URL scadono dopo 15 minuti.

D. Posso riutilizzare lo stesso Signed URL per più file?

No. Ogni chiamata di avvio emette un URL per un file/percorso e finestra temporale specifici.