NextPDF Connect en producción

De un vistazo

Un despliegue de NextPDF Connect en producción expone varias superficies operativas: sondas de salud y disponibilidad, rutas de renderizado síncronas y asíncronas, control de idempotencia, limitación de tasa por cliente y por IP, y sesiones con estado opcionales. Esta página explica cómo operarlas.

Instalación

composer require nextpdf/server

Visión general conceptual

El transporte REST es una canalización de middleware PSR-15. Cada solicitud atraviesa el middleware en orden: asignación de identificador de solicitud, límites de tamaño de cuerpo, CORS, autenticación, autorización de capacidades, limitación de tasa, idempotencia y tiempo de espera. A continuación, llega a un manejador. El transporte gRPC reutiliza los mismos servicios de aplicación detrás del trabajador gRPC de RoadRunner.

El renderizado admite dos modalidades. Una solicitud síncrona a POST /api/v1/render ejecuta las operaciones y devuelve el PDF en la respuesta. Un trabajo asíncrono usa POST /api/v1/jobs. Devuelve de inmediato un identificador de trabajo, y el resultado se recupera más tarde desde GET /api/v1/jobs/{id}/result. Los trabajos persisten en un almacén SQLite compartido, de modo que cualquier trabajador puede atender una consulta de estado o de resultado.

Superficie de la API

Salud y disponibilidad

Endpoint	Autenticación	Significado
`GET /healthz`	ninguna	El proceso está vivo
`GET /readyz`	ninguna	El servidor está listo para aceptar solicitudes

Conectar /healthz a una sonda de vivacidad y /readyz a una sonda de disponibilidad. Ambos endpoints son anónimos, por lo que los orquestadores no necesitan credenciales.

Trabajos asíncronos

Endpoint	Método	Propósito
`/api/v1/jobs`	`POST`	Enviar un trabajo de renderizado
`/api/v1/jobs/{id}`	`GET`	Estado del trabajo
`/api/v1/jobs/{id}/result`	`GET`	Resultado del trabajo (el PDF)
`/api/v1/jobs/{id}`	`DELETE`	Cancelar un trabajo

Sesiones (opcionales)

Cuando NEXTPDF_SESSIONS_ENABLED es true y las herramientas están disponibles, los endpoints de sesión exponen un recurso con estado. Permiten crear una sesión, agregar páginas, texto, imágenes, tablas y HTML, definir la fuente y, después, renderizar. Las sesiones tienen un límite por cliente y un tiempo de espera por inactividad. Están desactivadas de forma predeterminada.

Ejemplo de código — Inicio rápido

Enviar un trabajo asíncrono y consultar el resultado periódicamente:

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

Ejemplo de código — Producción

Para que un envío pueda reintentarse de forma segura, enviar una clave de idempotencia:

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 solicitud repetida con la misma clave de idempotencia devuelve el resultado original en lugar de crear un segundo trabajo. Esto hace que el envío pueda repetirse de forma segura tras un fallo de comunicación. Esa seguridad corresponde a la propiedad que aporta un método idempotente: repetir la solicitud tiene el mismo efecto previsto que enviarla una sola vez (RFC 9110 §9.2.2), de modo que la solicitud puede reintentarse automáticamente cuando una conexión se cae antes de leer la respuesta (RFC 9110 §9.2.2).

Casos límite y trampas

La limitación de tasa necesita Redis para ser correcta entre varios trabajadores. Los limitadores por cliente y por IP usan el almacén configurado. Con el almacén en memoria y más de un trabajador, cada trabajador cuenta de forma independiente, y el límite efectivo se multiplica por la cantidad de trabajadores. Usar el almacén Redis para cualquier grupo con varios trabajadores.
Una solicitud sujeta a límite devuelve 429. Cuando se supera un límite, el servidor responde con 429 Too Many Requests y una cabecera Retry-After, según la semántica del estado de limitación de tasa (RFC 6585 §4). Respetar Retry-After en lugar de reintentar de inmediato.
Los resultados de los trabajos no son infinitos. El almacén de trabajos elimina las entradas antiguas después de NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Recuperar los resultados antes de que caduquen.
Las sesiones consumen memoria. Una sesión retiene un documento en curso. El límite de sesiones por cliente y el tiempo de espera por inactividad acotan este costo. No aumentar estos valores sin dimensionar la memoria para el peor caso.

Rendimiento

La ruta síncrona retiene un trabajador durante todo el renderizado. Para renderizados grandes o lentos, conviene preferir la ruta de trabajo asíncrono: libera el trabajador de inmediato y el cliente consulta el resultado periódicamente. Dimensionar el grupo de trabajadores según la latencia de renderizado y la concurrencia observadas. Vigilar el endpoint de métricas de RoadRunner.

Notas de seguridad

Todos los endpoints, excepto las sondas de salud, requieren una clave de API válida. El nivel del cliente acota qué operaciones y tamaños de carga útil se permiten. El cliente proporciona las claves de idempotencia. Deben tratarse como opacas y únicas por operación lógica. Consultar /connect/security-and-operations/.

Conformidad

Afirmación	Fuente	`reference_id`
Idempotente: solicitudes repetidas = un solo efecto	RFC 9110 §9.2.2
Solicitudes idempotentes reintentables tras un fallo	RFC 9110 §9.2.2
`429` + `Retry-After` para la limitación de tasa	RFC 6585 §4

Contexto comercial

Los topes de carga útil y de tiempo de espera por nivel aumentan para las claves Pro y Enterprise cuando esas herramientas están instaladas. Los topes del nivel base se aplican a un despliegue predeterminado.

Consulta también

/connect/deployment/ — grupos de trabajadores, Redis, perfiles de RoadRunner
/transports/rest/ — la canalización de middleware completa y el contrato OpenAPI
/connect/troubleshooting/ — diagnóstico de 401/403/413/429/5xx y fallos del almacén
/connect/security-and-operations/ — postura de autenticación y de limitación de tasa