feature symfony#49815 [HttpClient][Messenger] add PingWebhookMessage and PingWebhookMessageHandler (kbond)

This PR was squashed before being merged into the 6.4 branch.

Discussion
----------

[HttpClient][Messenger] add `PingWebhookMessage` and `PingWebhookMessageHandler`

| Q             | A
| ------------- | ---
| Branch?       | 6.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | n/a
| License       | MIT
| Doc PR        | todo

With symfony/scheduler, it could be useful to ping some kind of uptime monitoring service like [ohdearapp](https://ohdear.app/).

## Usage

```php
use Symfony\Component\HttpClient\Messenger\PingWebhookMessage;

$bus->dispatch(new PingWebhookMessage('GET', 'https://example.com')); // simple ping, throws HttpExceptionInterface on 3xx/4xx/5xx

$bus->dispatch(new PingWebhookMessage('GET', 'https://example.com', throw: false)); // ping, but does not throw HttpExceptionInterface on 3xx/4xx/5xx

$bus->dispatch(new PingWebhookMessage('GET', 'https://example.com', [
    'headers' => ['X-FOO => 'bar'], // any HttpClientInterface options
]));
```

TODO:
- [x] wire up
- [x] tests

Commits
-------

f0644d9 [HttpClient][Messenger] add `PingWebhookMessage` and `PingWebhookMessageHandler`

Author: fabpot

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -83,6 +83,7 @@
 use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerInterface;
+use Symfony\Component\HttpClient\Messenger\PingWebhookMessageHandler;
 use Symfony\Component\HttpClient\MockHttpClient;
 use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
 use Symfony\Component\HttpClient\RetryableHttpClient;
@@ -2462,6 +2463,10 @@ private function registerHttpClientConfiguration(array $config, ContainerBuilder
         unset($options['vars']);
         $container->getDefinition('http_client.transport')->setArguments([$options, $config['max_host_connections'] ?? 6]);
 
+        if (!class_exists(PingWebhookMessageHandler::class)) {
+            $container->removeDefinition('http_client.messenger.ping_webhook_handler');
+        }
+
         if (!$hasPsr18 = ContainerBuilder::willBeAvailable('psr/http-client', ClientInterface::class, ['symfony/framework-bundle', 'symfony/http-client'])) {
             $container->removeDefinition('psr18.http_client');
             $container->removeAlias(ClientInterface::class);

src/Symfony/Bundle/FrameworkBundle/Resources/config/http_client.php

@@ -17,6 +17,7 @@
 use Psr\Http\Message\StreamFactoryInterface;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Component\HttpClient\HttplugClient;
+use Symfony\Component\HttpClient\Messenger\PingWebhookMessageHandler;
 use Symfony\Component\HttpClient\Psr18Client;
 use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
 use Symfony\Component\HttpClient\UriTemplateHttpClient;
@@ -90,5 +91,11 @@
             ->args([
                 [inline_service(\Rize\UriTemplate::class), 'expand'],
             ])
+
+        ->set('http_client.messenger.ping_webhook_handler', PingWebhookMessageHandler::class)
+            ->args([
+                service('http_client'),
+            ])
+            ->tag('messenger.message_handler')
     ;
 };

src/Symfony/Component/HttpClient/CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * Add `HarFileResponseFactory` testing utility, allow to replay responses from `.har` files
  * Add `max_retries` option to `RetryableHttpClient` to adjust the retry logic on a per request level
+ * Add `PingWehookMessage` and `PingWebhookMessageHandler`
 
 6.3
 ---

src/Symfony/Component/HttpClient/Messenger/PingWebhookMessage.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpClient\Messenger;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+final class PingWebhookMessage implements \Stringable
+{
+    public function __construct(
+        public readonly string $method,
+        public readonly string $url,
+        public readonly array $options = [],
+        public readonly bool $throw = true,
+    ) {
+    }
+
+    public function __toString(): string
+    {
+        return "[{$this->method}] {$this->url}";
+    }
+}

src/Symfony/Component/HttpClient/Messenger/PingWebhookMessageHandler.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpClient\Messenger;
+
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+class PingWebhookMessageHandler
+{
+    public function __construct(
+        private readonly HttpClientInterface $httpClient,
+    ) {
+    }
+
+    public function __invoke(PingWebhookMessage $message): ResponseInterface
+    {
+        $response = $this->httpClient->request($message->method, $message->url, $message->options);
+        $response->getHeaders($message->throw);
+
+        return $response;
+    }
+}

src/Symfony/Component/HttpClient/Tests/Messenger/PingWebhookMessageHandlerTest.php

@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpClient\Tests\Messenger;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpClient\Exception\ClientException;
+use Symfony\Component\HttpClient\Messenger\PingWebhookMessage;
+use Symfony\Component\HttpClient\Messenger\PingWebhookMessageHandler;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\MockResponse;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+final class PingWebhookMessageHandlerTest extends TestCase
+{
+    public function testSuccessfulPing()
+    {
+        $client = new MockHttpClient([
+            function ($method, $url) {
+                $this->assertSame('POST', $method);
+                $this->assertSame('https://endpoint.com/key', $url);
+
+                return new MockResponse('a response');
+            },
+        ]);
+        $handler = new PingWebhookMessageHandler($client);
+        $response = $handler(new PingWebhookMessage('POST', 'https://endpoint.com/key'));
+
+        $this->assertSame(200, $response->getStatusCode());
+        $this->assertSame('a response', $response->getContent());
+        $this->assertSame('https://endpoint.com/key', $response->getInfo('url'));
+    }
+
+    public function testPingErrorThrowsException()
+    {
+        $client = new MockHttpClient([
+            function ($method, $url) {
+                $this->assertSame('POST', $method);
+                $this->assertSame('https://endpoint.com/key', $url);
+
+                return new MockResponse('a response', ['http_code' => 404]);
+            },
+        ]);
+
+        $handler = new PingWebhookMessageHandler($client);
+
+        $this->expectException(ClientException::class);
+
+        $handler(new PingWebhookMessage('POST', 'https://endpoint.com/key'));
+    }
+
+    public function testPingErrorDoesNotThrowException()
+    {
+        $client = new MockHttpClient([
+            function ($method, $url) {
+                $this->assertSame('POST', $method);
+                $this->assertSame('https://endpoint.com/key', $url);
+
+                return new MockResponse('a response', ['http_code' => 404]);
+            },
+        ]);
+
+        $handler = new PingWebhookMessageHandler($client);
+        $response = $handler(new PingWebhookMessage('POST', 'https://endpoint.com/key', throw: false));
+
+        $this->assertSame(404, $response->getStatusCode());
+        $this->assertSame('a response', $response->getContent(false));
+        $this->assertSame('https://endpoint.com/key', $response->getInfo('url'));
+    }
+}

src/Symfony/Component/HttpClient/composer.json

@@ -39,6 +39,7 @@
         "psr/http-client": "^1.0",
         "symfony/dependency-injection": "^5.4|^6.0|^7.0",
         "symfony/http-kernel": "^5.4|^6.0|^7.0",
+        "symfony/messenger": "^5.4|^6.0|^7.0",
         "symfony/process": "^5.4|^6.0|^7.0",
         "symfony/stopwatch": "^5.4|^6.0|^7.0"
     },