Avvio e individuazione di NextPDF Gotenberg

In sintesi

Il bridge non dispone di un proprio meccanismo di individuazione automatica. È un semplice servizio che viene costruito tramite injection esplicita nel costruttore: un value object di configurazione più i collaboratori HTTP PSR. Questo pacchetto non include alcun service provider, bundle o estensione del container, e non legge direttamente alcuna variabile d’ambiente. Qui per «individuazione» si intende il modo in cui un framework ospitante fornisce i collaboratori: è responsabilità del framework, non di questo pacchetto.

Come viene individuato il bridge

Non viene individuato automaticamente: lo si costruisce. GotenbergBridge richiede quattro argomenti e ne accetta tre facoltativi:

• Obbligatori: un GotenbergConfig, un client PSR-18, una request factory PSR-17, una stream factory PSR-17.
• Facoltativi: un logger PSR-3, un criterio di sicurezza HTML (per impostazione predefinita il criterio predefinito del core di NextPDF) e una response factory PSR-17.

La response factory è l’interruttore di attivazione del trasporto cURL con pinning. Quando viene fornita e c’è qualcosa da bloccare tramite pinning (indirizzi risolti o pin SPKI configurati), il bridge usa il trasporto con pinning. Se viene omessa, viene sempre usato il client PSR-18 iniettato. Il contratto completo degli argomenti è in /integrations/gotenberg/configuration/.

Sequenza di avvio

Non esiste un passaggio di registrazione. Il ciclo di vita è il seguente:

1. L’host risolve un client PSR-18 e le factory PSR-17. A farlo è il container ospitante, non il pacchetto.
2. L’applicazione costruisce un GotenbergConfig dalla propria sorgente di configurazione. GotenbergConfig::fromArray() accetta un array in snake_case e tollera i valori malformati sostituendoli con i valori predefiniti. Convalidare la sorgente nel percorso di avvio, in modo che un URL mancante faccia fallire l’avvio, non ogni conversione.
3. L’applicazione costruisce GotenbergBridge con la configurazione e i collaboratori.
4. La prima chiamata di conversione esegue la convalida dell’URL, lo screening SSRF e quello dei nomi dei file, quindi la richiesta. Al momento della costruzione non avviene alcuna elaborazione; il bridge resta inerte finché non viene chiamato.

Binding del container

Questo pacchetto non include alcun binding del container. Per rendere il bridge iniettabile, registrarlo nel container dell’applicazione ospitante come segue:

• Effettuare il binding di GotenbergConfig dalla propria sorgente di configurazione.
• Effettuare il binding del client PSR-18 e delle factory PSR-17 alle implementazioni scelte.
• Effettuare il binding di GotenbergBridge come servizio che riceve quanto sopra.

L’auto-wiring nativo del framework, la pubblicazione della configurazione e la registrazione del service provider o del bundle risiedono nei pacchetti di integrazione dedicati al framework, non qui. Questo pacchetto resta volutamente agnostico rispetto al framework. Dipende solo dalle interfacce PSR, quindi funziona con qualsiasi container.

Ordine di risoluzione della configurazione

Il pacchetto non legge direttamente alcuna configurazione. L’ordine di risoluzione è quello implementato dall’applicazione prima di chiamare GotenbergConfig::fromArray() o il costruttore. Un ordine comune è: variabili d’ambiente, poi un file di configurazione pubblicato, infine i valori predefiniti nel codice. Quell’ordine è il contratto dell’applicazione, non di questo pacchetto. Ciò che il pacchetto definisce è il valore predefinito per ciascun campo omesso dall’array passato a fromArray(): URL dell’API vuoto, timeout di 30 secondi, limite di dimensione di 50 MiB, chiave API vuota, elenchi di pin vuoti.

Diagnostica

Due segnali integrati confermano il collegamento:

• isAvailable() convalida l’URL senza traffico di rete, poi invia una richiesta HEAD a <apiUrl>/health e segnala la disponibilità quando lo stato è inferiore a 500. In caso di qualsiasi errore restituisce false anziché sollevare un’eccezione. Chiamarlo da un controllo di prontezza.
• Una conversione di prova di un piccolo documento noto come valido conferma l’intero percorso end-to-end. Include la richiesta multipart a <apiUrl>/forms/libreoffice/convert e la convalida della risposta.

Vedere anche

• /integrations/gotenberg/integration/ — pilotare un flusso NextPDF attraverso il servizio.
• /integrations/gotenberg/install/ — installazione del pacchetto e del servizio.
• /integrations/gotenberg/configuration/ — il contratto completo del costruttore e della configurazione.
• /integrations/gotenberg/overview/ — il flusso di conversione e il modello delle dipendenze.