NextPDF — panoramica di Gotenberg

In breve

NextPDF Gotenberg è un bridge leggero tra NextPDF e un servizio Gotenberg esterno. Riceve un documento Office che NextPDF non è in grado di renderizzare nativamente, lo invia a un’istanza Gotenberg via HTTP, ottiene in risposta un PDF e lo consegna all’applicazione. Da lì, le altre funzionalità di NextPDF si occupano del post-processing.

Il pacchetto è compatto ed esplicito. Non incorpora un motore di rendering, non avvia LibreOffice e non esegue un browser. Ogni conversione consiste in una singola richiesta HTTP multipart verso un endpoint Gotenberg. L’endpoint deve essere gestito separatamente e il bridge va indirizzato a quell’endpoint tramite la configurazione.

Usare questo bridge quando si dispone di file sorgente .docx, .xlsx, .pptx, .odt, .ods o .odp e si vuole ottenerli come PDF all’interno di un flusso NextPDF. Una volta generato il PDF, tutto il resto — firma, conversione PDF/A, filigrana, unione — passa attraverso NextPDF stesso o il pacchetto nextpdf/premium.

Da cosa dipende il bridge

Il bridge ha una dipendenza di runtime che non è un pacchetto PHP: un servizio Gotenberg in esecuzione che il bridge può raggiungere via HTTPS.

Il bridge non installa, gestisce o supervisiona Gotenberg. Gotenberg va distribuito separatamente (il progetto upstream pubblica un’immagine container) ed è necessario gestirne disponibilità, capacità ed esposizione di rete.
Il bridge comunica con la route di conversione LibreOffice di Gotenberg. L’URL della richiesta viene costruito come <apiUrl>/forms/libreoffice/convert, dove <apiUrl> è l’URL di base che configuri. Questa route fornisce al bridge il suo insieme di formati supportati.
La sonda di integrità interroga <apiUrl>/health con una richiesta HTTP HEAD e considera disponibile qualsiasi stato inferiore a 500.

La conversione avviene in un servizio gestito da chi integra il bridge, quindi il comportamento del bridge dipende dalla versione di Gotenberg in esecuzione. Il bridge invia una struttura di richiesta multipart fissa, e il percorso della route (/forms/libreoffice/convert) e il percorso di integrità (/health) sono il solo contratto lato Gotenberg su cui fa affidamento. Consultare /integrations/gotenberg/install/ per la baseline di distribuzione e /integrations/gotenberg/security-and-operations/ per l’hardening del servizio.

Formati di documento supportati

Il bridge converte esattamente i formati enumerati nel suo tipo OfficeFormat. Ogni formato viene rilevato dall’estensione del file (senza distinzione tra maiuscole e minuscole, ed è accettato anche un punto iniziale). Ogni formato viene quindi inviato a Gotenberg con un tipo MIME fisso:

Formato	Estensione	Tipo MIME inviato a Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Questo è l’elenco completo. Un’estensione al di fuori di questo insieme solleva un ValueError prima di qualsiasi richiesta di rete, così il bridge non tenta mai una conversione che non sia in grado di descrivere. Il bridge non dichiara di supportare “qualsiasi file Office” o “tutti i formati di documento”. Supporta i sei formati indicati sopra, perché sono i sei che il codice riconosce e i sei che la suite di test esercita.

I formati binari legacy (.doc, .xls, .ppt), il rich text (.rtf), il testo semplice, il CSV e i formati immagine non fanno parte dell’insieme riconosciuto dal bridge. La route LibreOffice di Gotenberg potrebbe, di per sé, accettare una gamma più ampia di input. Il bridge si limita deliberatamente all’insieme enumerato, in modo che il rilevamento del formato, il tipo MIME e i metadati del risultato siano sempre coerenti e verificabili.

Come procede una conversione

Una conversione segue un flusso lineare in un unico passaggio. La convalida avviene a ogni passo prima che qualsiasi byte lasci il processo:

La configurazione viene verificata. Un URL API vuoto fallisce subito con un’eccezione di conversione.
L’URL API viene convalidato: è richiesto HTTPS e l’host viene risolto e filtrato in modo che non possa puntare a un indirizzo privato o riservato. L’insieme di indirizzi risolti viene catturato per il pinning successivo.
L’input viene letto (per le conversioni di file, il percorso viene prima canonicalizzato per bloccare il traversal) e la sua estensione viene mappata su un OfficeFormat.
La lunghezza in byte viene verificata rispetto al limite massimo configurato, e il nome del file viene filtrato per rilevare sequenze di traversal, slash, byte null e caratteri di controllo.
L’insieme di indirizzi viene ricontrollato immediatamente prima della richiesta, per chiudere la finestra tra convalida e connessione.
Un corpo multipart/form-data viene costruito e inviato in POST alla route LibreOffice, con un bearer token se ne è configurato uno.
La risposta viene analizzata: lo stato deve essere 200, il Content-Type deve contenere application/pdf e il corpo deve iniziare con la firma %PDF. Solo a quel punto viene restituito un risultato.

Qualsiasi errore nei passi 1–7 solleva un’eccezione tipizzata anziché restituire un risultato parziale o non verificato. Le eccezioni esatte e le relative cause sono catalogate in /integrations/gotenberg/troubleshooting/.

Cosa si ottiene in risposta

Una conversione riuscita restituisce un oggetto risultato. L’oggetto contiene i byte PDF grezzi, il formato di origine convertito e una misurazione facoltativa del tempo di rendering, ed espone un controllo di validità (un corpo non vuoto che inizia con %PDF) insieme a un accessor per la dimensione in byte. I byte sono un normale flusso PDF, quindi possono essere scritti su disco, inviati in streaming a un client o passati a un documento NextPDF per un’ulteriore elaborazione.

Dove il bridge si ferma

Il bridge converte e convalida. Non:

Firma, cifra, linearizza o converte in PDF/A l’output. Sono attività di post-processing gestite dal core di NextPDF o da nextpdf/premium.
Ritenta le richieste fallite, accoda il lavoro o memorizza i risultati in cache. Sono aspetti a livello di applicazione. /integrations/gotenberg/production-usage/ mostra dove aggiungerli attorno al bridge.
Gestisce il ciclo di vita del servizio Gotenberg. La distribuzione e le operazioni sono trattate in /integrations/gotenberg/security-and-operations/.

Edizioni e post-processing

Il core OSS può scrivere il PDF convertito così com’è. Se occorre firmare il documento convertito, produrre un profilo di archiviazione PDF/A o applicare una filigrana, il pacchetto nextpdf/premium aggiunge queste capacità. Il bridge in sé è neutrale rispetto all’edizione: produce un PDF. L’uso che se ne fa determina se serve un’edizione commerciale.

La baseline PAdES disponibile nell’edizione Pro è solo B-B. I profili di convalida a lungo termine (B-T, B-LT, B-LTA) non fanno parte dell’edizione Pro e non sono forniti da questo bridge. Non dedurre capacità di marca temporale o LTV dalla presenza di questo pacchetto.

Vedi anche

/integrations/gotenberg/install/ — installa il pacchetto e predispone una baseline Gotenberg.
/integrations/gotenberg/configuration/ — ogni opzione di configurazione, il suo tipo, il valore predefinito e l’effetto.
/integrations/gotenberg/quickstart/ — una prima conversione eseguibile.
/integrations/gotenberg/production-usage/ — il cablaggio del bridge in un’applicazione reale.
/integrations/gotenberg/troubleshooting/ — il catalogo delle eccezioni e il significato di ciascuna.
/integrations/gotenberg/security-and-operations/ — il modello di sicurezza e come gestire in sicurezza il servizio dipendente.
/integrations/gotenberg/boot-and-discovery/ — come i framework host scoprono e cablano il bridge.
/integrations/gotenberg/integration/ — guidare il rendering di NextPDF attraverso il servizio.