NextPDF Gotenberg: Boot und Discovery

Auf einen Blick

Die Bridge hat keinen eigenen Auto-Discovery-Mechanismus. Sie ist ein einfacher Service, den Sie per expliziter Konstruktorinjektion aufbauen: mit einem Konfigurations-Value-Object sowie PSR-HTTP-Kollaborateuren. Dieses Paket liefert keinen Service Provider, kein Bundle und keine Container-Erweiterung mit und liest selbst keine Umgebungsvariablen. „Discovery“ bedeutet hier, wie ein Host-Framework die Kollaborateure bereitstellt; das ist Aufgabe des Frameworks, nicht dieses Pakets.

Wie die Bridge erkannt wird

Die Bridge wird nicht automatisch erkannt; Sie konstruieren sie selbst. GotenbergBridge erfordert vier Argumente und akzeptiert drei optionale:

• Erforderlich: ein GotenbergConfig, ein PSR-18-Client, eine PSR-17-Request-Factory, eine PSR-17-Stream-Factory.
• Optional: ein PSR-3-Logger, eine HTML-Sicherheitsrichtlinie (standardmäßig die NextPDF-Core-Standardrichtlinie) und eine PSR-17-Response-Factory.

Die Response-Factory ist der Aktivierungsschalter für den cURL-fest verdrahteten Transport. Stellen Sie sie bereit, verwendet die Bridge den Pinning-Transport, sobald es etwas zu pinnen gibt (aufgelöste Adressen oder konfigurierte SPKI-Pins). Lassen Sie sie weg, wird immer der injizierte PSR-18-Client verwendet. Der vollständige Argumentvertrag steht unter /integrations/gotenberg/configuration/.

Boot-Sequenz

Es gibt keinen Registrierungsschritt. Der Lebenszyklus ist:

1. Der Host löst einen PSR-18-Client und PSR-17-Factories auf. Das erledigt der Host-Container; nicht das Paket.
2. Die Anwendung erstellt aus ihrer Konfigurationsquelle ein GotenbergConfig. GotenbergConfig::fromArray() akzeptiert ein snake_case-Array und toleriert fehlerhafte Werte, indem es Standardwerte einsetzt. Validieren Sie die Quelle in Ihrem Boot-Pfad, damit eine fehlende URL beim Booten fehlschlägt, nicht pro Konvertierung.
3. Die Anwendung konstruiert GotenbergBridge mit der Config und den Kollaborateuren.
4. Der erste Konvertierungsaufruf führt die URL-Validierung, die SSRF- und Dateinamenprüfung sowie die Anfrage aus. Zur Konstruktionszeit geschieht keine Arbeit; die Bridge bleibt inaktiv, bis Sie sie aufrufen.

Container-Bindings

Dieses Paket liefert keine Container-Bindings mit. Um die Bridge injizierbar zu machen, registrieren Sie sie wie folgt im Container Ihrer Host-Anwendung:

• Binden Sie GotenbergConfig aus Ihrer Konfigurationsquelle.
• Binden Sie den PSR-18-Client und die PSR-17-Factories an Ihre gewählten Implementierungen.
• Binden Sie GotenbergBridge als Service, der die genannten Abhängigkeiten erhält.

Framework-natives Auto-Wiring, das Veröffentlichen der Konfiguration und die Registrierung von Service Provider oder Bundle sind Teil der dedizierten Framework-Integrationspakete, nicht dieses Pakets. Dieses Paket bleibt absichtlich Framework-unabhängig. Es hängt nur von PSR-Schnittstellen ab und funktioniert daher mit jedem Container.

Reihenfolge der Konfigurationsauflösung

Das Paket liest von sich aus keine Konfiguration. Die Auflösungsreihenfolge ist die Reihenfolge, die Ihre Anwendung implementiert, bevor sie GotenbergConfig::fromArray() oder den Konstruktor aufruft. Eine gängige Reihenfolge lautet: Umgebungsvariablen, danach eine veröffentlichte Config-Datei, danach Code-Standards. Diese Reihenfolge ist der Vertrag Ihrer Anwendung, nicht der dieses Pakets. Das Paket definiert jedoch den Standardwert für jedes Feld, das das an fromArray() übergebene Array auslässt: leere API-URL, 30-Sekunden-Timeout, 50-MiB-Größenobergrenze, leerer API-Schlüssel, leere Pin-Listen.

Diagnose

Zwei eingebaute Signale bestätigen die Verdrahtung:

• isAvailable() validiert die URL ohne Netzwerkverkehr, sendet dann eine HEAD-Anfrage an <apiUrl>/health und meldet „verfügbar“, wenn der Status unter 500 liegt. Bei jedem Fehler gibt es false zurück, anstatt eine Ausnahme zu werfen. Rufen Sie es aus einer Readiness-Prüfung auf.
• Eine Smoke-Konvertierung eines bekanntermaßen funktionierenden kleinen Dokuments bestätigt den vollständigen Ende-zu-Ende-Pfad. Dazu gehören die Multipart-Anfrage an <apiUrl>/forms/libreoffice/convert und die Validierung der Response.

Siehe auch

• /integrations/gotenberg/integration/ — Ansteuerung einer NextPDF-Pipeline über den Service.
• /integrations/gotenberg/install/ — Installation des Pakets und des Service.
• /integrations/gotenberg/configuration/ — der vollständige Konstruktor- und Config-Vertrag.
• /integrations/gotenberg/overview/ — Konvertierungsablauf und Abhängigkeitsmodell.