NextPDF Connect in der Produktion

Auf einen Blick

Ein produktives NextPDF Connect-Deployment stellt mehrere Schnittstellen und Funktionen für den Betrieb bereit: Health- und Readiness-Probes, synchrone und asynchrone Renderpfade, Idempotenzsteuerung, Ratenbegrenzung pro Client und pro IP sowie optionale zustandsbehaftete Sessions. Diese Seite zeigt, wie Sie diese Funktionen im Betrieb nutzen.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Der REST-Transport ist eine PSR-15-Middleware-Pipeline. Jeder Request durchläuft die Middleware der Reihe nach: Zuweisung der Request-ID, Begrenzung der Body-Größe, CORS, Authentifizierung, Capability-Autorisierung, Ratenbegrenzung, Idempotenz und Timeout. Anschließend erreicht er einen Handler. Der gRPC-Transport nutzt hinter dem RoadRunner-gRPC-Worker dieselben Application-Services.

Das Rendering steht in zwei Varianten zur Verfügung. Ein synchroner Aufruf von POST /api/v1/render führt die Operationen aus und gibt das PDF in der Response zurück. Für einen asynchronen Job verwenden Sie POST /api/v1/jobs. Der Aufruf gibt sofort eine Job-ID zurück; das Ergebnis rufen Sie später über GET /api/v1/jobs/{id}/result ab. Jobs werden in einem gemeinsamen SQLite-Store persistiert, sodass jeder Worker Status- oder Ergebnisabfragen bedienen kann.

API-Oberfläche

Health und Readiness

Endpunkt	Auth	Bedeutung
`GET /healthz`	keine	Der Prozess läuft
`GET /readyz`	keine	Der Server kann Requests annehmen

Verbinden Sie /healthz mit einer Liveness-Probe und /readyz mit einer Readiness-Probe. Beide Endpunkte sind anonym, sodass Orchestratoren keine Zugangsdaten benötigen.

Asynchrone Jobs

Endpunkt	Methode	Zweck
`/api/v1/jobs`	`POST`	Einen Render-Job einreichen
`/api/v1/jobs/{id}`	`GET`	Job-Status
`/api/v1/jobs/{id}/result`	`GET`	Job-Ergebnis (das PDF)
`/api/v1/jobs/{id}`	`DELETE`	Einen Job abbrechen

Sessions (opt-in)

Wenn NEXTPDF_SESSIONS_ENABLED auf true gesetzt ist und die Tools verfügbar sind, stellen die Session-Endpunkte einen zustandsbehafteten Build bereit. Sie erstellen eine Session, fügen Seiten, Text, Bilder, Tabellen und HTML hinzu, legen die Schriftart fest und rendern anschließend. Sessions haben ein Limit pro Client und ein Idle-Timeout. Standardmäßig sind sie deaktiviert.

Codebeispiel — Schnellstart

Reichen Sie einen asynchronen Job ein und fragen Sie das Ergebnis per Polling ab:

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

Codebeispiel — Produktion

Machen Sie eine Einreichung wiederholungssicher, indem Sie einen Idempotenzschlüssel mitsenden:

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

Ein erneut gesendeter Request mit demselben Idempotenzschlüssel gibt das ursprüngliche Ergebnis zurück, statt einen zweiten Job zu erzeugen. Dadurch lässt sich die Einreichung nach einem Kommunikationsfehler gefahrlos wiederholen. Diese Sicherheit entspricht der Eigenschaft einer idempotenten Methode: Die Wiederholung des Requests hat dieselbe beabsichtigte Wirkung wie das einmalige Senden (RFC 9110 §9.2.2), sodass der Request automatisch erneut gesendet werden kann, wenn die Verbindung abbricht, bevor die Response gelesen wurde (RFC 9110 §9.2.2).

Sonderfälle und Stolperfallen

Ratenbegrenzung benötigt Redis, um über mehrere Worker hinweg korrekt zu sein. Die Limiter pro Client und pro IP nutzen den konfigurierten Store. Mit dem In-Memory-Store und mehr als einem Worker zählt jeder Worker unabhängig, und das effektive Limit multipliziert sich mit der Anzahl der Worker. Verwenden Sie für jeden Pool mit mehreren Workern den Redis-Store.
Ein gedrosselter Request gibt 429 zurück. Wird ein Limit überschritten, antwortet der Server mit 429 Too Many Requests und einem Retry-After-Header, entsprechend der Statussemantik für Ratenbegrenzung (RFC 6585 §4). Beachten Sie Retry-After, statt sofort erneut zu versuchen.
Job-Ergebnisse sind nicht unbegrenzt verfügbar. Der Job-Store räumt alte Einträge nach NEXTPDF_JOB_GC_MAX_AGE_SECONDS per Garbage Collection auf. Rufen Sie die Ergebnisse ab, bevor sie verfallen.
Sessions kosten Arbeitsspeicher. Eine Session hält ein in Bearbeitung befindliches Dokument. Das Session-Limit pro Client und das Idle-Timeout begrenzen diese Kosten. Erhöhen Sie diese Werte nicht, ohne den Arbeitsspeicher für den schlimmsten Fall zu dimensionieren.

Performance

Der synchrone Pfad belegt einen Worker während des gesamten Rendervorgangs. Bei großen oder langsamen Rendervorgängen ist der asynchrone Job-Pfad vorzuziehen: Er gibt den Worker sofort frei, und der Client fragt das Ergebnis per Polling ab. Dimensionieren Sie den Worker-Pool anhand der beobachteten Render-Latenz und Nebenläufigkeit. Behalten Sie den RoadRunner-Metrics-Endpunkt im Auge.

Sicherheitshinweise

Jeder Endpunkt außer den Health-Probes erfordert einen gültigen API-Schlüssel. Die Client-Stufe begrenzt, welche Operationen und Payload-Größen erlaubt sind. Idempotenzschlüssel werden vom Client bereitgestellt. Behandeln Sie sie als opak und pro logischer Operation eindeutig. Siehe /connect/security-and-operations/.

Konformität

Zusicherung	Quelle	`reference_id`
Idempotent: wiederholte Requests = eine Wirkung	RFC 9110 §9.2.2
Idempotente Requests nach einem Fehler wiederholbar	RFC 9110 §9.2.2
`429` + `Retry-After` für Ratenbegrenzung	RFC 6585 §4

Kommerzieller Kontext

Die Payload- und Timeout-Obergrenzen je Stufe fallen für Pro- und Enterprise-Schlüssel höher aus, wenn diese Tools installiert sind. Die Obergrenzen der Core-Stufe gelten für ein Standard-Deployment.

Siehe auch

/connect/deployment/ — Worker-Pools, Redis, RoadRunner-Profile
/transports/rest/ — die vollständige Middleware-Pipeline und der OpenAPI-Vertrag
/connect/troubleshooting/ — Diagnose von 401/403/413/429/5xx und Store-Fehlern
/connect/security-and-operations/ — Authentifizierung und Ratenbegrenzungsrichtlinie