Add ability to generate asynchronously using webhooks

config/builder_pdf.php

@@ -25,6 +25,7 @@
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
 
@@ -38,6 +39,7 @@
             service('router')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->call('setRequestContext', [service('.sensiolabs_gotenberg.request_context')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
@@ -50,6 +52,7 @@
             service('request_stack'),
             service('twig')->nullOnInvalid(),
         ])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
@@ -61,6 +64,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
 
@@ -71,6 +75,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
 
@@ -81,6 +86,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
 };

config/builder_screenshot.php

@@ -22,6 +22,7 @@
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.screenshot_builder')
     ;
 
@@ -35,6 +36,7 @@
             service('router')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->call('setRequestContext', [service('.sensiolabs_gotenberg.request_context')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.screenshot_builder')
     ;
@@ -48,6 +50,7 @@
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->call('setWebhookConfigurationRegistry', [service('.sensiolabs_gotenberg.webhook_configuration_registry')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.screenshot_builder')
     ;
 };

config/services.php

@@ -2,6 +2,8 @@
 
 use Sensiolabs\GotenbergBundle\Client\GotenbergClient;
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistry;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistryInterface;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 use Sensiolabs\GotenbergBundle\Gotenberg;
 use Sensiolabs\GotenbergBundle\GotenbergInterface;
@@ -63,4 +65,13 @@
         ])
         ->alias(GotenbergInterface::class, 'sensiolabs_gotenberg')
     ;
+
+    $services->set('.sensiolabs_gotenberg.webhook_configuration_registry', WebhookConfigurationRegistry::class)
+        ->args([
+            service('router'),
+            service('.sensiolabs_gotenberg.request_context')->nullOnInvalid(),
+        ])
+        ->tag('sensiolabs_gotenberg.webhook_configuration_registry')
+        ->alias(WebhookConfigurationRegistryInterface::class, '.sensiolabs_gotenberg.webhook_configuration_registry')
+    ;
 };

src/Builder/AsyncBuilderInterface.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Sensiolabs\GotenbergBundle\Builder;
+
+interface AsyncBuilderInterface
+{
+    /**
+     * Generates a file asynchronously.
+     */
+    public function generateAsync(): string;
+}

src/Builder/AsyncBuilderTrait.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Sensiolabs\GotenbergBundle\Builder;
+
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistry;
+use Sensiolabs\GotenbergBundle\Exception\WebhookConfigurationException;
+
+trait AsyncBuilderTrait
+{
+    use DefaultBuilderTrait;
+    private string $webhookUrl;
+    private string $errorWebhookUrl;
+    /**
+     * @var array<string, mixed>
+     */
+    private array $webhookExtraHeaders = [];
+    private \Closure $operationIdGenerator;
+    private WebhookConfigurationRegistry|null $webhookConfigurationRegistry = null;
+
+    public function generateAsync(): string
+    {
+        $operationId = ($this->operationIdGenerator ?? self::defaultOperationIdGenerator(...))();
+        $this->logger?->debug('Generating a file asynchronously with operation id {sensiolabs_gotenberg.operation_id} using {sensiolabs_gotenberg.builder} builder.', [
+            'sensiolabs_gotenberg.operation_id' => $operationId,
+            'sensiolabs_gotenberg.builder' => $this::class,
+        ]);
+
+        $this->webhookExtraHeaders['X-Gotenberg-Operation-Id'] = $operationId;
+        $headers = [
+            'Gotenberg-Webhook-Url' => $this->webhookUrl,
+            'Gotenberg-Webhook-Error-Url' => $this->errorWebhookUrl,
+            'Gotenberg-Webhook-Extra-Http-Headers' => json_encode($this->webhookExtraHeaders, \JSON_THROW_ON_ERROR),
+        ];
+        if (null !== $this->fileName) {
+            $headers['Gotenberg-Output-Filename'] = basename($this->fileName, '.pdf');
+        }
+        $this->client->call($this->getEndpoint(), $this->getMultipartFormData(), $headers);
+
+        return $operationId;
+    }
+
+    public function setWebhookConfigurationRegistry(WebhookConfigurationRegistry $registry): static
+    {
+        $this->webhookConfigurationRegistry = $registry;
+
+        return $this;
+    }
+
+    public function webhookConfiguration(string $webhook): static
+    {
+        if (null === $this->webhookConfigurationRegistry) {
+            throw new WebhookConfigurationException('The WebhookConfigurationRegistry is not available.');
+        }
+        $webhookConfiguration = $this->webhookConfigurationRegistry->get($webhook);
+
+        return $this->webhookUrls($webhookConfiguration['success'], $webhookConfiguration['error']);
+    }
+
+    public function webhookUrls(string $successWebhook, string|null $errorWebhook = null): static
+    {
+        $this->webhookUrl = $successWebhook;
+        $this->errorWebhookUrl = $errorWebhook ?? $successWebhook;
+
+        return $this;
+    }
+
+    /**
+     * @param array<string, mixed> $extraHeaders
+     */
+    public function webhookExtraHeaders(array $extraHeaders): static
+    {
+        $this->webhookExtraHeaders = array_merge($this->webhookExtraHeaders, $extraHeaders);
+
+        return $this;
+    }
+
+    public function operationIdGenerator(\Closure $operationIdGenerator): static
+    {
+        $this->operationIdGenerator = $operationIdGenerator;
+
+        return $this;
+    }
+
+    protected static function defaultOperationIdGenerator(): string
+    {
+        return 'gotenberg_'.bin2hex(random_bytes(16)).microtime(true);
+    }
+}

src/Builder/Pdf/AbstractChromiumPdfBuilder.php

@@ -4,6 +4,7 @@
 
 use Sensiolabs\GotenbergBundle\Builder\CookieAwareTrait;
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistry;
 use Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType;
 use Sensiolabs\GotenbergBundle\Enumeration\PaperSizeInterface;
 use Sensiolabs\GotenbergBundle\Enumeration\Part;
@@ -28,8 +29,9 @@ public function __construct(
         AssetBaseDirFormatter $asset,
         private readonly RequestStack $requestStack,
         private readonly Environment|null $twig = null,
+        WebhookConfigurationRegistry|null $webhookConfigurationRegistry = null,
     ) {
-        parent::__construct($gotenbergClient, $asset);
+        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry);
 
         $normalizers = [
             'extraHttpHeaders' => function (mixed $value): array {
@@ -586,6 +588,7 @@ protected function addConfiguration(string $configurationName, mixed $value): vo
             'fail_on_console_exceptions' => $this->failOnConsoleExceptions($value),
             'skip_network_idle_event' => $this->skipNetworkIdleEvent($value),
             'metadata' => $this->metadata($value),
+            'webhook' => null,
             default => throw new InvalidBuilderConfiguration(sprintf('Invalid option "%s": no method does not exist in class "%s" to configured it.', $configurationName, static::class)),
         };
     }

src/Builder/Pdf/AbstractPdfBuilder.php

@@ -2,12 +2,15 @@
 
 namespace Sensiolabs\GotenbergBundle\Builder\Pdf;
 
+use Sensiolabs\GotenbergBundle\Builder\AsyncBuilderInterface;
+use Sensiolabs\GotenbergBundle\Builder\AsyncBuilderTrait;
 use Sensiolabs\GotenbergBundle\Builder\DefaultBuilderTrait;
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 
-abstract class AbstractPdfBuilder implements PdfBuilderInterface
+abstract class AbstractPdfBuilder implements PdfBuilderInterface, AsyncBuilderInterface
 {
+    use AsyncBuilderTrait;
     use DefaultBuilderTrait;
 
     public function __construct(

src/Builder/Pdf/UrlPdfBuilder.php

@@ -3,6 +3,7 @@
 namespace Sensiolabs\GotenbergBundle\Builder\Pdf;
 
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistry;
 use Sensiolabs\GotenbergBundle\Exception\MissingRequiredFieldException;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 use Symfony\Component\HttpFoundation\RequestStack;
@@ -22,8 +23,9 @@ public function __construct(
         RequestStack $requestStack,
         Environment|null $twig = null,
         private readonly UrlGeneratorInterface|null $urlGenerator = null,
+        WebhookConfigurationRegistry|null $webhookConfigurationRegistry = null,
     ) {
-        parent::__construct($gotenbergClient, $asset, $requestStack, $twig);
+        parent::__construct($gotenbergClient, $asset, $requestStack, $twig, $webhookConfigurationRegistry);
 
         $this->addNormalizer('route', $this->generateUrlFromRoute(...));
     }

src/Builder/Screenshot/AbstractChromiumScreenshotBuilder.php

@@ -4,6 +4,7 @@
 
 use Sensiolabs\GotenbergBundle\Builder\CookieAwareTrait;
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistryInterface;
 use Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType;
 use Sensiolabs\GotenbergBundle\Enumeration\Part;
 use Sensiolabs\GotenbergBundle\Enumeration\ScreenshotFormat;
@@ -26,8 +27,9 @@ public function __construct(
         AssetBaseDirFormatter $asset,
         private readonly RequestStack $requestStack,
         private readonly Environment|null $twig = null,
+        WebhookConfigurationRegistryInterface|null $webhookConfigurationRegistry = null,
     ) {
-        parent::__construct($gotenbergClient, $asset);
+        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry);
 
         $normalizers = [
             'extraHttpHeaders' => function (mixed $value): array {

src/Builder/Screenshot/AbstractScreenshotBuilder.php

@@ -2,14 +2,17 @@
 
 namespace Sensiolabs\GotenbergBundle\Builder\Screenshot;
 
+use Sensiolabs\GotenbergBundle\Builder\AsyncBuilderInterface;
+use Sensiolabs\GotenbergBundle\Builder\AsyncBuilderTrait;
 use Sensiolabs\GotenbergBundle\Builder\DefaultBuilderTrait;
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
 use Sensiolabs\GotenbergBundle\Enumeration\Part;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 use Symfony\Component\Mime\Part\DataPart;
 
-abstract class AbstractScreenshotBuilder implements ScreenshotBuilderInterface
+abstract class AbstractScreenshotBuilder implements ScreenshotBuilderInterface, AsyncBuilderInterface
 {
+    use AsyncBuilderTrait;
     use DefaultBuilderTrait;
 
     public function __construct(

src/Builder/Screenshot/UrlScreenshotBuilder.php

@@ -3,6 +3,7 @@
 namespace Sensiolabs\GotenbergBundle\Builder\Screenshot;
 
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
+use Sensiolabs\GotenbergBundle\DependencyInjection\WebhookConfiguration\WebhookConfigurationRegistryInterface;
 use Sensiolabs\GotenbergBundle\Exception\MissingRequiredFieldException;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 use Symfony\Component\HttpFoundation\RequestStack;
@@ -22,8 +23,9 @@ public function __construct(
         RequestStack $requestStack,
         Environment|null $twig = null,
         private readonly UrlGeneratorInterface|null $urlGenerator = null,
+        WebhookConfigurationRegistryInterface|null $webhookConfigurationRegistry = null,
     ) {
-        parent::__construct($gotenbergClient, $asset, $requestStack, $twig);
+        parent::__construct($gotenbergClient, $asset, $requestStack, $twig, $webhookConfigurationRegistry);
 
         $this->addNormalizer('route', $this->generateUrlFromRoute(...));
     }

src/Client/GotenbergClient.php

@@ -28,7 +28,7 @@ public function call(string $endpoint, array $multipartFormData, array $headers
             ],
         );
 
-        if (200 !== $response->getStatusCode()) {
+        if (!\in_array($response->getStatusCode(), [200, 204], true)) {
             throw new ClientException($response->getContent(false), $response->getStatusCode());
         }
 

src/Debug/Builder/TraceablePdfBuilder.php

@@ -2,6 +2,7 @@
 
 namespace Sensiolabs\GotenbergBundle\Debug\Builder;
 
+use Sensiolabs\GotenbergBundle\Builder\AsyncBuilderInterface;
 use Sensiolabs\GotenbergBundle\Builder\GotenbergFileResult;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\PdfBuilderInterface;
 use Symfony\Component\Stopwatch\Stopwatch;
@@ -50,6 +51,22 @@ public function generate(): GotenbergFileResult
         return $response;
     }
 
+    public function generateAsync(): string
+    {
+        if (!$this->inner instanceof AsyncBuilderInterface) {
+            throw new \LogicException(sprintf('The inner builder of %s must implement %s.', self::class, AsyncBuilderInterface::class));
+        }
+
+        $name = self::$count.'.'.$this->inner::class.'::'.__FUNCTION__;
+        ++self::$count;
+
+        $swEvent = $this->stopwatch->start($name, 'gotenberg.generate_pdf');
+        $gotenbergTrace = $this->inner->generateAsync();
+        $swEvent->stop();
+
+        return $gotenbergTrace;
+    }
+
     /**
      * @param array<mixed> $arguments
      */