NextPDF Connect in productie

In een oogopslag

Een productie-uitrol van NextPDF Connect biedt verschillende operationele mogelijkheden: health- en readiness-probes, synchrone en asynchrone weergavepaden, idempotentie, snelheidslimieten per client en per Internet Protocol (IP)-adres, en optionele stateful sessies. Gebruik deze pagina om deze onderdelen voorspelbaar te configureren.

Installeren

composer require nextpdf/server

Conceptueel overzicht

Het Representational State Transfer (REST)-transport is een PHP Standards Recommendation (PSR)-15-middlewarepijplijn. Elk verzoek doorloopt de middleware in volgorde: toewijzing van request-id, limieten op de bodygrootte, Cross-Origin Resource Sharing (CORS), authenticatie, capability-autorisatie, snelheidsbeperking, idempotentie en time-out. Daarna bereikt het verzoek een handler. Het gRPC-transport hergebruikt dezelfde applicatieservices achter de RoadRunner gRPC-worker.

Weergave heeft twee paden. Een synchrone POST /api/v1/render voert de bewerkingen uit en geeft het Portable Document Format (PDF)-bestand terug in het antwoord. Een asynchrone taak loopt via POST /api/v1/jobs. Die call geeft onmiddellijk een job-id terug, waarna je het resultaat later ophaalt via GET /api/v1/jobs/{id}/result. Taken worden bewaard in een gedeelde SQLite-store, zodat elke worker een status- of resultaatquery kan beantwoorden.

API-oppervlak

Health en readiness

Endpoint	Auth	Betekenis
`GET /healthz`	geen	Het proces draait
`GET /readyz`	geen	De server is klaar om verzoeken te accepteren

Koppel /healthz aan een liveness-probe en /readyz aan een readiness-probe. Beide endpoints zijn anoniem, zodat orchestrators geen credentials nodig hebben.

Asynchrone taken

Endpoint	Methode	Doel
`/api/v1/jobs`	`POST`	Een weergavetaak indienen
`/api/v1/jobs/{id}`	`GET`	Taakstatus
`/api/v1/jobs/{id}/result`	`GET`	Taakresultaat (de PDF)
`/api/v1/jobs/{id}`	`DELETE`	Een taak annuleren

Sessies (opt-in)

Wanneer NEXTPDF_SESSIONS_ENABLED op true staat en er tools beschikbaar zijn, bieden de sessie-endpoints een stateful build-flow. Je maakt een sessie aan, voegt pagina’s, tekst, afbeeldingen, tabellen en HyperText Markup Language (HTML) toe, stelt het lettertype in en voert daarna de weergave uit. Sessies hebben een limiet per client en een time-out bij inactiviteit. Ze staan standaard uit.

Codevoorbeeld — Snelstart

Dien een asynchrone taak in en haal het resultaat op:

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

Codevoorbeeld — Productie

Zorg dat je een indiening veilig opnieuw kunt proberen door een idempotentiesleutel mee te sturen:

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"}]}'

Een verzoek dat met dezelfde idempotentiesleutel opnieuw wordt verstuurd, geeft het oorspronkelijke resultaat terug in plaats van een tweede taak aan te maken. Daardoor is het veilig om de indiening na een communicatiestoring te herhalen. Dit komt overeen met de eigenschap van een idempotente methode: hetzelfde verzoek opnieuw versturen heeft hetzelfde beoogde effect als het verzoek één keer versturen (RFC 9110 §9.2.2). Het verzoek kan daarom automatisch opnieuw worden geprobeerd als de verbinding wegvalt voordat de client het antwoord leest (RFC 9110 §9.2.2).

Randgevallen en valkuilen

Snelheidsbeperking heeft Redis nodig om correct te werken over meerdere workers heen. De begrenzers per client en per IP gebruiken de geconfigureerde store. Met de in-memory store en meer dan één worker telt elke worker verzoeken onafhankelijk en wordt de effectieve limiet vermenigvuldigd met het aantal workers. Gebruik de Redis-store voor elke pool met meerdere workers.
Een verzoek dat door snelheidsbeperking wordt geweigerd, geeft 429 terug. Wanneer een limiet wordt overschreden, antwoordt de server met 429 Too Many Requests en een Retry-After-header, volgens de statussemantiek voor snelheidsbeperking (RFC 6585 §4). Respecteer Retry-After; probeer het niet onmiddellijk opnieuw.
Taakresultaten blijven niet onbeperkt beschikbaar. De taak-store ruimt oude vermeldingen op na NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Haal resultaten op voordat ze verlopen.
Sessies kosten geheugen. Een sessie houdt een document in bewerking vast. De sessielimiet per client en de time-out bij inactiviteit begrenzen deze kosten. Verhoog ze niet zonder het geheugen af te stemmen op het slechtste geval.

Prestaties

Het synchrone pad houdt een worker bezet gedurende de volledige weergave. Gebruik voor grote of trage weergaven het pad voor asynchrone taken. Dat maakt de worker onmiddellijk vrij, waarna de client het resultaat ophaalt. Stem de omvang van de worker-pool af op de waargenomen weergavelatentie en gelijktijdigheid. Houd het RoadRunner-metrics-endpoint in de gaten.

Beveiligingsnotities

Elk endpoint behalve de health-probes vereist een geldige application programming interface (API)-sleutel. Het niveau van de client bepaalt welke bewerkingen en payload-groottes zijn toegestaan. Clients leveren idempotentiesleutels aan. Behandel elke sleutel als opaak en uniek voor één logische bewerking. Zie /connect/security-and-operations/.

Conformiteit

Bewering	Bron	`reference_id`
Idempotent: herhaalde verzoeken = één effect	RFC 9110 §9.2.2
Idempotente verzoeken zijn opnieuw te proberen na een storing	RFC 9110 §9.2.2
`429` + `Retry-After` voor snelheidsbeperking	RFC 6585 §4

Commerciële context

Pro- en Enterprise-sleutels krijgen hogere payload- en time-outlimieten per niveau wanneer die tools zijn geïnstalleerd. Een standaarduitrol gebruikt de limieten van het core-niveau.

Zie ook

/connect/deployment/ — worker-pools, Redis, RoadRunner-profielen
/transports/rest/ — de volledige middlewarepijplijn en het OpenAPI-contract
/connect/troubleshooting/ — diagnose van 401/403/413/429/5xx en storefouten
/connect/security-and-operations/ — authenticatie en de configuratie rond snelheidsbeperking