Boot e descoberta do Gotenberg no NextPDF

Em resumo

A ponte não tem mecanismo de descoberta automática. Você a constrói como um serviço comum, com injeção explícita pelo construtor: um value object de configuração e colaboradores Hypertext Transfer Protocol (HTTP) definidos pela PHP Standard Recommendation (PSR). Este pacote não inclui service provider, bundle nem extensão de container, e também não lê variáveis de ambiente por conta própria. Aqui, “descoberta” significa a forma como um framework hospedeiro fornece esses colaboradores. Essa responsabilidade é do framework, não deste pacote.

Como a ponte é descoberta

Ela não é descoberta automaticamente; você a constrói. GotenbergBridge exige quatro argumentos e aceita três opcionais:

• Obrigatórios: um GotenbergConfig, um cliente PSR-18, uma request factory PSR-17 e uma stream factory PSR-17.
• Opcionais: um logger PSR-3, uma política de segurança Hypertext Markup Language (HTML) (que usa por padrão a política padrão do core do NextPDF) e uma response factory PSR-17.

A response factory ativa o transporte com pinning via cURL. Ao fornecê-la, quando a ponte tiver algo para fixar (endereços resolvidos ou pins SubjectPublicKeyInfo (SPKI) configurados), ela usará o transporte com pinning. Se você omiti-la, o cliente PSR-18 injetado será sempre usado. O contrato completo dos argumentos está em /integrations/gotenberg/configuration/.

Sequência de boot

Não há etapa de registro. O ciclo de vida é:

1. O host resolve um cliente PSR-18 e as factories PSR-17. O container do host faz isso; o pacote não.
2. A aplicação constrói um GotenbergConfig a partir de sua fonte de configuração. GotenbergConfig::fromArray() aceita um array em snake_case e substitui valores malformados pelos padrões. Valide a fonte no caminho de boot, para que um valor Uniform Resource Locator (URL) ausente falhe no boot, e não a cada conversão.
3. A aplicação constrói o GotenbergBridge com a config e os colaboradores.
4. A primeira chamada de conversão executa a validação da URL, a triagem de server-side request forgery (SSRF), a triagem do nome do arquivo e a requisição. Nada é executado no momento da construção; a ponte permanece inerte até que você a chame.

Bindings de container

Este pacote não inclui binding de container. Para tornar a ponte injetável, registre-a no container da aplicação hospedeira da seguinte forma:

• Faça o bind de GotenbergConfig a partir da fonte de configuração.
• Faça o bind do cliente PSR-18 e das factories PSR-17 com as implementações escolhidas.
• Faça o bind de GotenbergBridge como um serviço que recebe essas dependências.

O auto-wiring nativo do framework, a publicação de configuração e o registro de service-provider ou bundle pertencem aos pacotes dedicados de integração com cada framework, não aqui. Este pacote é agnóstico em relação a framework por design. Ele depende apenas das interfaces PSR; portanto, funciona com qualquer container.

Ordem de resolução da configuração

O pacote não lê configuração por conta própria. A ordem de resolução é a que a aplicação implementar antes de chamar GotenbergConfig::fromArray() ou o construtor. Uma ordem comum é: variáveis de ambiente, depois um arquivo de config publicado e, por fim, os padrões do código. Essa ordem é o contrato da aplicação, não deste pacote. O que o pacote de fato define é o valor padrão de cada campo omitido pelo array passado para fromArray(): URL de application programming interface (API) vazia, timeout de 30 segundos, limite de tamanho de 50 MiB, chave de API vazia e listas de pins vazias.

Diagnósticos

Dois sinais embutidos confirmam a ligação:

• isAvailable() valida a URL sem tráfego de rede, depois envia uma requisição HEAD para <apiUrl>/health e reporta disponibilidade quando o status é inferior a 500. Ele retorna false em vez de lançar exceção diante de qualquer falha. Chame-o a partir de uma verificação de readiness.
• Uma conversão de smoke de um documento pequeno e reconhecidamente válido confirma o caminho completo de ponta a ponta. Isso inclui a requisição multipart para <apiUrl>/forms/libreoffice/convert e a validação da resposta.

Veja também

• /integrations/gotenberg/integration/ — conduzir um pipeline do NextPDF por meio do serviço.
• /integrations/gotenberg/install/ — instalação do pacote e do serviço.
• /integrations/gotenberg/configuration/ — o contrato completo do construtor e da config.
• /integrations/gotenberg/overview/ — o fluxo de conversão e o modelo de dependências.