NextPDF Gotenberg en producción

De un vistazo

El puente ejecuta un único ciclo HTTP sincrónico de ida y vuelta, envuelto en validación. No reintenta, no encola, no almacena en caché ni limita la frecuencia. Esos comportamientos corresponden a la aplicación que lo rodea. Esta página muestra dónde encaja cada uno y qué garantiza el puente, para que el resto pueda construirse correctamente.

Cada conversión debe tratarse como una llamada remota a un servicio operado por su entorno, pero no controlado dentro del propio proceso. El diseño debe contemplar su latencia y sus fallos.

Obtención de la configuración y los secretos

GotenbergConfig contiene la URL de la API y, cuando la autenticación está habilitada, un token de portador. El campo del token está marcado como #[\SensitiveParameter], por lo que se censura en los seguimientos de pila. Aun así, el origen del token sigue siendo responsabilidad de la aplicación.

• Obtener el token del gestor de secretos o de una variable de entorno inyectada al iniciar el proceso. No registrarlo en el control de versiones ni colocarlo en un archivo de configuración distribuido dentro de la imagen.
• Construir la configuración una vez por ámbito de solicitud o una vez por trabajador, no por conversión. Es inmutable y económica de mantener.
• GotenbergConfig::fromArray() tolera entradas malformadas por diseño: aplica silenciosamente valores predeterminados. En producción, validar el arreglo de origen antes de llamar a fromArray(). Así, una URL ausente aparece como un error de configuración durante el arranque, en lugar de manifestarse más adelante en cada conversión como una excepción Invalid Gotenberg configuration: apiUrl is empty.

Tiempos de espera

timeout (en segundos, predeterminado 30) es el tiempo de espera estricto de transferencia, aplicado por el transporte anclado a cURL. La conversión de Office mediante LibreOffice no es instantánea; los documentos grandes o complejos requieren más tiempo. Definir el tiempo de espera a partir de la latencia de conversión medida con documentos reales, con un margen de holgura. Mantenerlo por debajo de cualquier pasarela ascendente o del max_execution_time de PHP. De ese modo, el puente expira primero y se obtiene una excepción tipada en lugar de un proceso terminado.

Si se depende de la ruta del cliente PSR-18 inyectado (sin responseFactory inyectado, o con una URL de IP simple sin anclajes), el puente no impone el valor de timeout sobre ese cliente. Configurar el tiempo de espera también en el propio cliente PSR-18, de modo que ambos transportes queden acotados.

Reintentos

El puente realiza exactamente una solicitud por llamada y nunca reintenta. Añadir la lógica de reintento en el llamador y hacerla segura:

• Reintentar solo ante un fallo de nivel de transporte (una GotenbergConvertException cuya causa sea una excepción del cliente PSR-18) y ante errores idempotentes del servidor (HTTP 502, 503, 504). No reintentar cada GotenbergConvertException de forma indiscriminada. Una respuesta de la clase 400 suele significar que la entrada es incorrecta, y un reintento fallará de forma idéntica.
• Usar una espera exponencial acotada con fluctuación. Un servicio de conversión bajo carga devuelve 503; seguir insistiendo empeora la interrupción.
• Limitar el total de intentos y el tiempo de reloj total. La conversión ya es lenta, por lo que los reintentos sin límite multiplican la latencia en la cola.
• La revalidación es automática: cada llamada reintentada vuelve a ejecutar la validación de la URL y la reverificación de la dirección, de modo que un reintento no puede eludir accidentalmente la protección contra SSRF.

Concurrencia y capacidad

Cada conversión mantiene ocupados una conexión y un trabajador de LibreOffice en el lado de Gotenberg durante toda la solicitud. El puente en sí no mantiene estado y es seguro usarlo desde muchos trabajadores de forma concurrente. El servicio de Gotenberg, sin embargo, tiene una capacidad de conversión finita.

• Acotar desde la aplicación el número de conversiones en curso (una cola, un semáforo o un grupo de trabajadores) a la capacidad que Gotenberg pueda sostener. El dimensionamiento depende de la implementación de Gotenberg, no de este paquete; consulte /integrations/gotenberg/security-and-operations/.
• El límite de tamaño de entrada (maxFileSize, predeterminado 50 MiB) es el único límite de recursos integrado en el puente. Se aplica dentro del propio proceso antes de enviar la solicitud, de modo que un archivo de tamaño excesivo nunca consume capacidad del servicio. Reducirlo para ajustarlo a lo que los documentos realmente necesitan; un límite más pequeño es un control de denegación de servicio más económico que uno más grande.
• No hay almacenamiento en caché dentro del proceso. Si el mismo documento se convierte repetidamente, almacenar en caché el PDF resultante en la aplicación, indexado por un hash de contenido de la entrada.

Observabilidad

Inyectar un registrador PSR-3 permite obtener una entrada debug por cada solicitud de conversión. La entrada contiene la URL de la solicitud, el nombre del archivo, el formato detectado y la longitud del contenido de la solicitud. No contiene el contenido del archivo ni el token de portador.

• Promover esa señal a una métrica: contar las conversiones por formato y resultado, y registrar el tiempo de reloj en torno a cada llamada a convertFile() / convertString() como un histograma de latencia. El puente no emite métricas por sí mismo.
• El objeto de resultado expone un campo renderTimeMs que vale 0.0 a menos que la integración mida y establezca ese valor; el puente no lo rellena a partir de la respuesta de Gotenberg. Medir el tiempo de la llamada si ese valor es necesario.
• Registrar las excepciones junto con su tipo. El tipo de excepción es la señal principal de qué falló; el catálogo está en /integrations/gotenberg/troubleshooting/.
• Sondear isAvailable() desde el punto de conexión de preparación o salud, no en cada conversión. Es una solicitud HEAD a /health. Ejecutarla antes de cada conversión duplica la frecuencia de solicitudes al servicio sin aportar beneficios.

Contrato de gestión de fallos

El puente expone los fallos como excepciones tipadas y nunca devuelve un resultado parcial ni sin validar. Las garantías relevantes:

• Un estado distinto de 200, un Content-Type sin application/pdf o un cuerpo que no comienza con %PDF generan, cada uno, una GotenbergConvertException. Solo se devuelve un objeto de resultado cuando las tres comprobaciones superan la validación.
• Un fallo del cliente PSR-18 (incluido un fallo de red o un tiempo de espera agotado) se envuelve como una GotenbergConvertException, con la excepción original como causa y el código del cliente como código de la excepción.
• Los fallos de validación (URL no HTTPS, dirección private/reserved, entrada de tamaño excesivo, nombre de archivo inseguro) generan una RuntimeException antes de cualquier tráfico de red.
• Una extensión de archivo no reconocida genera un ValueError antes de cualquier tráfico de red.

Capturar los tipos específicos. El programa de ejemplo en examples/convert-office-to-pdf.php muestra el orden exhaustivo de captura. /integrations/gotenberg/troubleshooting/ explica cada desencadenante.

El límite del posprocesamiento

El puente produce un PDF y se detiene. Un flujo de producción común es:

1. Convertir el documento de Office con este puente.
2. Cargar los bytes resultantes en un documento de NextPDF.
3. Aplicar el posprocesamiento: ensamblado de páginas, marcas de agua, conversión a PDF/A, firmas digitales.

El paso 3 es responsabilidad de NextPDF, no del puente. La firma, los perfiles PDF/A y las marcas de agua los proporciona nextpdf/premium. Mantener la conversión y el posprocesamiento como etapas distintas permite diagnosticar de forma independiente un fallo de conversión y un fallo de firma.

La compatibilidad PAdES de la edición Pro cubre únicamente la línea base B-B. No proporciona B-T, B-LT ni B-LTA, y esos perfiles no quedan implícitos por convertir un documento mediante este puente. La capacidad de validación a largo plazo corresponde a otra edición y queda fuera del alcance de este paquete.

Véase también

• /integrations/gotenberg/configuration/ — reglas de selección de transporte y modelo de anclajes.
• /integrations/gotenberg/security-and-operations/ — implementación y refuerzo de la dependencia de Gotenberg.
• /integrations/gotenberg/troubleshooting/ — catálogo de excepciones.
• /integrations/gotenberg/integration/ — conexión del PDF convertido a un flujo de NextPDF.