NextPDF Gotenberg in produzione

In breve

Il bridge è un singolo round-trip HTTP sincrono protetto da controlli di validazione. Non esegue ritentativi, non accoda, non memorizza in cache e non applica rate-limit. Questi comportamenti spettano all’applicazione che usa il bridge. Questa pagina indica dove collocarli e che cosa garantisce il bridge, così da progettare correttamente il resto.

Trattare ogni conversione come una chiamata remota a un servizio che si gestisce, ma che non si controlla in-process. Progettare tenendo conto della sua latenza e dei suoi possibili fallimenti.

Origine di configurazione e segreti

GotenbergConfig contiene l’URL dell’API e, quando l’autenticazione è abilitata, un bearer token. Il campo del token è contrassegnato con #[\SensitiveParameter], quindi viene oscurato negli stack trace. La responsabilità della sua provenienza resta comunque dell’applicazione.

• Recuperare il token dal proprio secret manager o da una variabile d’ambiente iniettata all’avvio del processo. Non eseguirne il commit e non collocarlo in un file di configurazione distribuito nell’immagine.
• Costruire la configurazione una volta per scope di richiesta o una volta per worker, non per ogni conversione. È immutabile e poco costosa da mantenere.
• GotenbergConfig::fromArray() tollera intenzionalmente input malformati: sostituisce silenziosamente i valori predefiniti. In produzione, validare autonomamente l’array di origine prima di chiamare fromArray(). Un URL mancante emerge così come errore di configurazione nel percorso di avvio, anziché come eccezione Invalid Gotenberg configuration: apiUrl is empty in un secondo momento, per ogni conversione.

Timeout

timeout (secondi, predefinito 30) è il timeout rigido di trasferimento, applicato dal trasporto vincolato a cURL. La conversione Office tramite LibreOffice non è istantanea; i documenti grandi o complessi richiedono più tempo. Impostare il timeout in base alla latenza di conversione misurata sui documenti reali, con un margine. Mantenerlo al di sotto del timeout di qualsiasi gateway a monte o del max_execution_time di PHP. In questo modo il bridge va in timeout per primo e si ottiene un’eccezione tipizzata invece di un processo terminato.

Se si usa il percorso del client PSR-18 iniettato (nessun responseFactory iniettato, o un URL con IP nudo senza pin), il bridge non impone il valore di timeout a quel client. Configurare il timeout anche sul client PSR-18 stesso, in modo che entrambi i trasporti siano vincolati.

Ritentativi

Il bridge invia esattamente una richiesta per chiamata e non effettua mai ritentativi. Aggiungere la logica di ritentativo nel chiamante e renderla sicura:

• Ritentare solo in caso di fallimento a livello di trasporto (una GotenbergConvertException la cui causa è un’eccezione del client PSR-18) e in caso di errori server idempotenti (HTTP 502, 503, 504). Non ritentare ogni GotenbergConvertException indiscriminatamente. Una risposta di classe 400 di solito indica che l’input è errato e un ritentativo fallirà nello stesso modo.
• Usare un backoff esponenziale vincolato con jitter. Un servizio di conversione sotto carico restituisce 503; continuare a sollecitarlo aggrava l’interruzione.
• Limitare il numero totale di tentativi e il tempo complessivo trascorso. La conversione è già lenta, perciò ritentativi non vincolati moltiplicano la latenza di coda.
• La validazione viene ripetuta automaticamente: ogni chiamata ritentata riesegue la validazione dell’URL e il ricontrollo dell’indirizzo, perciò un ritentativo non può aggirare accidentalmente la protezione SSRF.

Concorrenza e capacità

Ogni conversione occupa una connessione e un worker LibreOffice sul lato Gotenberg per tutta la durata della richiesta. Il bridge stesso è stateless e può essere usato in sicurezza da molti worker contemporaneamente. Il servizio Gotenberg, tuttavia, ha una capacità di conversione finita.

• Vincolare dal proprio lato il numero di conversioni in corso (una coda, un semaforo o un pool di worker) alla capacità che Gotenberg può sostenere. Il dimensionamento è una proprietà del proprio deployment Gotenberg, non di questo pacchetto — vedere /integrations/gotenberg/security-and-operations/.
• Il limite di dimensione dell’input (maxFileSize, predefinito 50 MiB) è l’unico vincolo di risorse incorporato nel bridge. Viene applicato in-process prima che la richiesta venga inviata, perciò un file sovradimensionato non consuma mai la capacità del servizio. Abbassarlo per allinearlo alle effettive esigenze dei propri documenti; un limite più basso è un controllo denial-of-service più economico di uno più alto.
• Non esiste alcuna cache in-process. Se lo stesso documento viene convertito più volte, memorizzare in cache il file PDF risultante nella propria applicazione, usando come chiave un hash del contenuto dell’input.

Osservabilità

Iniettare un logger PSR-3 per ottenere una voce debug per ogni richiesta di conversione. La voce contiene l’URL della richiesta, il nome del file, il formato rilevato e la lunghezza del contenuto della richiesta. Non contiene il contenuto del file né il bearer token.

• Trasformare quel segnale in metriche: contare le conversioni per formato ed esito e registrare il tempo complessivo trascorso per ogni chiamata a convertFile() / convertString() come istogramma di latenza. Il bridge non emette metriche autonomamente.
• L’oggetto risultato espone un campo renderTimeMs che è 0.0 a meno che la propria integrazione non lo misuri e lo imposti; il bridge non lo popola dalla risposta di Gotenberg. Cronometrare autonomamente la chiamata se serve il valore.
• Registrare le eccezioni con il relativo tipo. Il tipo di eccezione è il segnale primario di ciò che è fallito; il catalogo si trova in /integrations/gotenberg/troubleshooting/.
• Chiamare isAvailable() dal proprio endpoint di readiness o di health, non a ogni conversione. È una HEAD verso /health. Eseguirla prima di ogni conversione raddoppia il numero di richieste verso il servizio senza alcun vantaggio.

Contratto di gestione dei fallimenti

Il bridge espone i fallimenti come eccezioni tipizzate e non restituisce mai un risultato parziale o non validato. Le garanzie rilevanti sono:

• Uno stato diverso da 200, un Content-Type senza application/pdf o un corpo che non inizia con %PDF sollevano ciascuno una GotenbergConvertException. Un oggetto risultato viene restituito solo quando tutti e tre i controlli vengono superati.
• Un fallimento del client PSR-18 (incluso un guasto di rete o un timeout) viene avvolto in una GotenbergConvertException con l’eccezione originale come causa e il codice del client come codice dell’eccezione.
• I fallimenti di validazione (URL non HTTPS, indirizzo private/reserved, input sovradimensionato, nome di file non sicuro) sollevano RuntimeException prima di qualsiasi traffico di rete.
• Un’estensione di file non riconosciuta solleva ValueError prima di qualsiasi traffico di rete.

Catturare i tipi specifici. Il programma di esempio in examples/convert-office-to-pdf.php mostra l’ordine di cattura completo. /integrations/gotenberg/troubleshooting/ spiega ciascun trigger.

Il confine del post-processing

Il bridge produce un file PDF e si ferma. Una pipeline di produzione tipica è:

1. Convertire il documento Office con questo bridge.
2. Caricare i byte risultanti in un documento NextPDF.
3. Applicare il post-processing — assemblaggio delle pagine, applicazione di filigrane, conversione PDF/A, firme digitali.

Il passo 3 è responsabilità di NextPDF, non del bridge. La firma, i profili PDF/A e l’applicazione di filigrane sono forniti da nextpdf/premium. Mantenere la conversione e il post-processing come fasi distinte, in modo che un fallimento di conversione e uno di firma siano diagnosticabili in modo indipendente.

Il supporto PAdES dell’edizione Pro copre solo la baseline B-B. Non fornisce B-T, B-LT o B-LTA, e tali profili non sono impliciti nella conversione di un documento attraverso questo bridge. La capacità di long-term-validation è una funzionalità di edizione distinta ed è fuori ambito per questo pacchetto.

Vedere anche

• /integrations/gotenberg/configuration/ — regole di selezione del trasporto e modello dei pin.
• /integrations/gotenberg/security-and-operations/ — distribuzione e hardening della dipendenza Gotenberg.
• /integrations/gotenberg/troubleshooting/ — il catalogo delle eccezioni.
• /integrations/gotenberg/integration/ — come inserire il file PDF convertito in una pipeline NextPDF.