Arranque y descubrimiento de Gotenberg en NextPDF

De un vistazo

El puente no cuenta con ningún mecanismo propio de descubrimiento automático. Es un servicio sencillo que se construye mediante inyección explícita en el constructor: un objeto de valor de configuración y colaboradores HTTP PSR. Este paquete no incluye proveedores de servicios, bundles ni extensiones de contenedor, y tampoco lee variables de entorno por sí mismo. Aquí, «descubrimiento» se refiere a cómo un framework anfitrión proporciona esos colaboradores; esa responsabilidad corresponde al framework, no a este paquete.

Cómo se descubre el puente

No se descubre automáticamente. Hay que construirlo explícitamente. GotenbergBridge requiere cuatro argumentos y acepta tres opcionales:

• Obligatorios: un GotenbergConfig, un cliente PSR-18, una factoría de peticiones PSR-17 y una factoría de flujos PSR-17.
• Opcionales: un registrador PSR-3, una política de seguridad HTML (por defecto, la política predeterminada del núcleo de NextPDF) y una factoría de respuestas PSR-17.

La factoría de respuestas activa el transporte de fijación basado en cURL. Al proporcionarla, cuando haya algo que fijar (direcciones resueltas o pines SPKI configurados), el puente utiliza el transporte de fijación. Si se omite, siempre se utiliza el cliente PSR-18 inyectado. El contrato completo de argumentos está en /integrations/gotenberg/configuration/.

Secuencia de arranque

No hay ningún paso de registro. El ciclo de vida es:

1. El anfitrión resuelve un cliente PSR-18 y las factorías PSR-17. Esto lo hace el contenedor del anfitrión; el paquete no.
2. La aplicación construye un GotenbergConfig a partir de su fuente de configuración. GotenbergConfig::fromArray() acepta un array en snake_case y tolera los valores malformados sustituyéndolos por valores predeterminados. La fuente debe validarse en la ruta de arranque para que una URL ausente falle al arrancar, no en cada conversión.
3. La aplicación construye GotenbergBridge con la configuración y los colaboradores.
4. La primera llamada de conversión ejecuta la validación de la URL, el filtrado de SSRF y de nombres de archivo, y la petición. No se realiza ningún trabajo durante la construcción; el puente permanece inerte hasta que se invoca.

Vinculaciones del contenedor

Este paquete no incluye vinculaciones de contenedor. Para que el puente pueda inyectarse, debe registrarse en el contenedor de la aplicación anfitriona de la siguiente manera:

• Vincular GotenbergConfig a partir de la fuente de configuración.
• Vincular el cliente PSR-18 y las factorías PSR-17 a las implementaciones elegidas.
• Vincular GotenbergBridge como un servicio que recibe lo anterior.

El autoconexionado nativo del framework, la publicación de la configuración y el registro de proveedores de servicios o bundles pertenecen a los paquetes de integración de framework dedicados, no a este paquete. Este paquete se mantiene intencionadamente agnóstico respecto al framework. Depende únicamente de interfaces PSR, por lo que funciona con cualquier contenedor.

Orden de resolución de la configuración

El paquete no lee ninguna configuración por sí mismo. El orden de resolución es el que implemente la aplicación antes de llamar a GotenbergConfig::fromArray() o al constructor. Un orden habitual es: variables de entorno, luego un archivo de configuración publicado y, por último, los valores predeterminados del código. Ese orden forma parte del contrato de la aplicación, no de este paquete. Lo que el paquete sí define es el valor predeterminado de cada campo que omite el array pasado a fromArray(): URL de API vacía, tiempo de espera de 30 segundos, límite de tamaño de 50 MiB, clave de API vacía y listas de pines vacías.

Diagnósticos

Dos señales integradas permiten confirmar la conexión:

• isAvailable() valida la URL sin tráfico de red; luego envía una petición HEAD a <apiUrl>/health e informa de disponibilidad cuando el estado es inferior a 500. Devuelve false en lugar de lanzar una excepción ante cualquier fallo. Debe invocarse desde una comprobación de disponibilidad.
• Una conversión de prueba con un documento pequeño y comprobado confirma la ruta completa de extremo a extremo. Esto incluye la petición multipart a <apiUrl>/forms/libreoffice/convert y la validación de la respuesta.

Véase también

• /integrations/gotenberg/integration/ — controlar una canalización de NextPDF a través del servicio.
• /integrations/gotenberg/install/ — instalación del paquete y del servicio.
• /integrations/gotenberg/configuration/ — el contrato completo del constructor y de la configuración.
• /integrations/gotenberg/overview/ — el flujo de conversión y el modelo de dependencias.