NextPDF Connect en production

En un coup d’œil

Un déploiement NextPDF Connect en production expose plusieurs surfaces opérationnelles : sondes de santé et de disponibilité, chemins de rendu synchrone et asynchrone, contrôle d’idempotence, limitation de débit par client et par IP, et sessions avec état optionnelles. Cette page t’explique comment les utiliser.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Le transport REST s’appuie sur un pipeline de middlewares PSR-15. Chaque requête traverse les middlewares dans l’ordre suivant : attribution de l’identifiant de requête, limites de taille du corps, CORS, authentification, autorisation des capacités, limitation de débit, idempotence et délai d’expiration. Elle arrive ensuite dans un gestionnaire. Le transport gRPC réutilise les mêmes services applicatifs derrière le worker gRPC de RoadRunner.

Le rendu prend deux formes. Un appel synchrone POST /api/v1/render exécute les opérations et renvoie le PDF dans la réponse. Pour un job asynchrone, utilise POST /api/v1/jobs. L’appel renvoie immédiatement un identifiant de job, et tu récupères le résultat plus tard depuis GET /api/v1/jobs/{id}/result. Les jobs sont persistés dans un store SQLite partagé ; n’importe quel worker peut donc répondre à une requête de statut ou de résultat.

Surface de l’API

Santé et disponibilité

Point de terminaison	Authentification	Signification
`GET /healthz`	aucune	Le processus est vivant
`GET /readyz`	aucune	Le serveur est prêt à accepter des requêtes

Configure /healthz comme sonde de vivacité et /readyz comme sonde de disponibilité. Les deux points de terminaison sont anonymes : les orchestrateurs n’ont donc besoin d’aucune information d’authentification.

Jobs asynchrones

Point de terminaison	Méthode	Objectif
`/api/v1/jobs`	`POST`	Soumettre un job de rendu
`/api/v1/jobs/{id}`	`GET`	Statut du job
`/api/v1/jobs/{id}/result`	`GET`	Résultat du job (le PDF)
`/api/v1/jobs/{id}`	`DELETE`	Annuler un job

Sessions (optionnelles)

Quand NEXTPDF_SESSIONS_ENABLED vaut true et que les outils sont disponibles, les points de terminaison de session exposent un mode de construction avec état. Tu crées une session, tu ajoutes des pages, du texte, des images, des tableaux et du HTML, tu définis la police, puis tu lances le rendu. Les sessions ont un plafond par client et un délai d’inactivité. Elles sont désactivées par défaut.

Exemple de code — Démarrage rapide

Soumets un job asynchrone et récupère le résultat :

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

Exemple de code — Production

Pour pouvoir réessayer une soumission en toute sécurité, envoie une clé d’idempotence :

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

Une requête rejouée avec la même clé d’idempotence renvoie le résultat d’origine au lieu de créer un second job. Cela permet de répéter la soumission sans risque après un échec de communication. Cette sûreté correspond à la propriété offerte par une méthode idempotente : répéter la requête a le même effet voulu que l’envoyer une seule fois (RFC 9110 §9.2.2), donc la requête peut être réessayée automatiquement quand une connexion tombe avant que la réponse ne soit lue (RFC 9110 §9.2.2).

Cas limites et pièges

La limitation de débit a besoin de Redis pour rester correcte entre les workers. Les limiteurs par client et par IP utilisent le store configuré. Avec un store en mémoire et plus d’un worker, chaque worker compte de façon indépendante, et la limite effective est multipliée par le nombre de workers. Utilise le store Redis pour tout pool multi-worker.
Une requête limitée renvoie 429. Lorsqu’une limite est dépassée, le serveur répond avec 429 Too Many Requests et un en-tête Retry-After, selon la sémantique de statut de limitation de débit (RFC 6585 §4). Honore Retry-After au lieu de réessayer immédiatement.
Les résultats des jobs ne sont pas conservés indéfiniment. Le store de jobs supprime les anciennes entrées par ramasse-miettes après NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Récupère les résultats avant qu’ils n’expirent.
Les sessions consomment de la mémoire. Une session conserve un document en cours. Le plafond de sessions par client et le délai d’inactivité encadrent ce coût. Ne les augmente pas sans dimensionner la mémoire pour le pire cas.

Performances

Le chemin synchrone monopolise un worker pendant tout le rendu. Pour les rendus volumineux ou lents, préfère le chemin de job asynchrone : il libère immédiatement le worker, et le client interroge le résultat. Dimensionne le pool de workers en fonction de la latence de rendu et de la concurrence observées. Surveille le point de terminaison de métriques de RoadRunner.

Notes de sécurité

Chaque point de terminaison, à l’exception des sondes de santé, exige une clé d’API valide. Le niveau du client limite les opérations et les tailles de charge utile autorisées. Les clés d’idempotence sont fournies par le client ; traite-les comme opaques et uniques par opération logique. Consulte /connect/security-and-operations/.

Conformité

Affirmation	Source	`reference_id`
Idempotent : des requêtes répétées = un seul effet	RFC 9110 §9.2.2
Requêtes idempotentes réessayables après un échec	RFC 9110 §9.2.2
`429` + `Retry-After` pour la limitation de débit	RFC 6585 §4

Contexte commercial

Les plafonds de charge utile et de délai d’expiration par niveau sont plus élevés pour les clés Pro et Enterprise quand ces outils sont installés. Les plafonds du niveau Core s’appliquent au déploiement par défaut.

Voir aussi

/connect/deployment/ — pools de workers, Redis, profils RoadRunner
/transports/rest/ — le pipeline complet de middlewares et le contrat OpenAPI
/connect/troubleshooting/ — diagnostiquer les 401/403/413/429/5xx et les échecs de store
/connect/security-and-operations/ — authentification et politique de limitation de débit