NextPDF Connect in produzione

In breve

Un deployment di NextPDF Connect in produzione espone diverse superfici operative: probe di integrità e prontezza, percorsi di rendering sincroni e asincroni, controllo di idempotenza, limitazione della frequenza per client e per IP e sessioni con stato facoltative. Questa pagina mostra come gestirle in esercizio.

Installazione

composer require nextpdf/server

Panoramica concettuale

Il trasporto REST è una pipeline di middleware PSR-15. Ogni richiesta attraversa il middleware nell’ordine seguente: assegnazione dell’ID della richiesta, limiti sulla dimensione del corpo, CORS, autenticazione, autorizzazione delle funzionalità, limitazione della frequenza, idempotenza e timeout. Solo dopo raggiunge un handler. Il trasporto gRPC riutilizza gli stessi servizi applicativi tramite il worker gRPC di RoadRunner.

Il rendering può avvenire in due modalità. Una chiamata sincrona POST /api/v1/render esegue le operazioni e restituisce il PDF nella risposta. Un processo asincrono utilizza POST /api/v1/jobs. Restituisce subito un ID del processo e il risultato viene recuperato in seguito da GET /api/v1/jobs/{id}/result. I processi vengono mantenuti in un archivio SQLite condiviso, quindi qualsiasi worker può rispondere a una richiesta di stato o di risultato.

Superficie API

Integrità e prontezza

Endpoint	Autenticazione	Significato
`GET /healthz`	nessuna	Il processo è in esecuzione
`GET /readyz`	nessuna	Il server è pronto ad accettare richieste

Associare /healthz a una probe di liveness e /readyz a una probe di readiness. Entrambi gli endpoint sono anonimi, quindi gli orchestratori non hanno bisogno di credenziali.

Processi asincroni

Endpoint	Metodo	Scopo
`/api/v1/jobs`	`POST`	Avviare un processo di rendering
`/api/v1/jobs/{id}`	`GET`	Stato del processo
`/api/v1/jobs/{id}/result`	`GET`	Risultato del processo (il PDF)
`/api/v1/jobs/{id}`	`DELETE`	Annullare un processo

Sessioni (attivazione facoltativa)

Quando NEXTPDF_SESSIONS_ENABLED è true e gli strumenti sono disponibili, gli endpoint di sessione espongono una modalità di costruzione con stato. Si crea una sessione, si aggiungono pagine, testo, immagini, tabelle e HTML, si imposta il font e infine si esegue il rendering. Le sessioni sono soggette a un limite per client e a un timeout di inattività. Sono disattivate per impostazione predefinita.

Esempio di codice — Avvio rapido

Inviare un processo asincrono e fare il polling del risultato:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Esempio di codice — Produzione

Rendere un invio ritentabile in sicurezza inviando una chiave di idempotenza:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Una richiesta ripetuta con la stessa chiave di idempotenza restituisce il risultato originale invece di creare un secondo processo. In questo modo l’invio può essere ritentato in sicurezza dopo un errore di comunicazione. Questa sicurezza deriva dalla proprietà di un metodo idempotente: ripetere la richiesta produce lo stesso effetto previsto di un singolo invio (RFC 9110 §9.2.2), quindi la richiesta può essere ritentata automaticamente quando una connessione cade prima che la risposta venga letta (RFC 9110 §9.2.2).

Casi limite e insidie

La limitazione della frequenza richiede Redis per essere corretta tra i worker. I limitatori per client e per IP utilizzano l’archivio configurato. Con l’archivio in memoria e più di un worker, ogni worker conteggia in modo indipendente e il limite effettivo viene moltiplicato per il numero di worker. Usare l’archivio Redis per qualsiasi pool multi-worker.
Una richiesta soggetta a throttling restituisce 429. Quando un limite viene superato, il server risponde con 429 Too Many Requests e un’intestazione Retry-After, secondo la semantica dello stato di limitazione della frequenza (RFC 6585 §4). Rispettare Retry-After invece di ritentare immediatamente.
I risultati dei processi non restano disponibili indefinitamente. L’archivio dei processi rimuove tramite garbage collection le voci obsolete dopo NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Recuperare i risultati prima che scadano.
Le sessioni consumano memoria. Una sessione mantiene in memoria un documento in corso di elaborazione. Il limite di sessioni per client e il timeout di inattività contengono questo costo. Non aumentarli senza dimensionare la memoria per il caso peggiore.

Prestazioni

Il percorso sincrono occupa un worker per l’intero rendering. Per rendering grandi o lenti, preferire il percorso asincrono basato su processi: libera immediatamente il worker e il client esegue il polling del risultato. Dimensionare il pool di worker in base alla latenza di rendering e alla concorrenza osservate. Monitorare l’endpoint delle metriche di RoadRunner.

Note sulla sicurezza

Ogni endpoint, eccetto le probe di integrità, richiede una chiave API valida. Il livello del client determina quali operazioni e dimensioni del payload sono consentite. Le chiavi di idempotenza sono fornite dal client. Trattarle come opache e univoche per ogni operazione logica. Vedere /connect/security-and-operations/.

Conformità

Dichiarazione	Origine	`reference_id`
Idempotente: richieste ripetute = un unico effetto	RFC 9110 §9.2.2
Richieste idempotenti ritentabili dopo un errore	RFC 9110 §9.2.2
`429` + `Retry-After` per la limitazione della frequenza	RFC 6585 §4

Contesto commerciale

I limiti massimi di payload e timeout di ciascun livello aumentano per le chiavi Pro ed Enterprise quando tali strumenti sono installati. I limiti massimi del livello core si applicano a un deployment predefinito.

Vedere anche

/connect/deployment/ — pool di worker, Redis, profili RoadRunner
/transports/rest/ — la pipeline di middleware completa e il contratto OpenAPI
/connect/troubleshooting/ — diagnosi di 401/403/413/429/5xx ed errori dell’archivio
/connect/security-and-operations/ — autenticazione e configurazione della limitazione della frequenza