Merge pull request #377 from JLG-WOCFR-DEV/codex/continue-developpement-prioritaire-3x42eu

JLG-WOCFR-DEV · web-flow · commit e30ee96cec49 · 2025-10-11T12:03:23.000+02:00
Add remote request telemetry instrumentation
diff --git a/docs/ameliorations-et-tests.md b/docs/ameliorations-et-tests.md
@@ -7,7 +7,7 @@
 - **`blc_update_image_scan_status`** – La structure de statut n'expose ni `job_id` ni journal des transitions et ne notifie aucun hook dédié lors d'un changement d'état, ce qui complique l'audit et l'alignement avec les processus ITIL utilisés par les suites professionnelles. Harmoniser cette fonction avec `blc_update_link_scan_status()` (machine à états, journalisation) permettrait de tracer finement les scans d'images. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L867-L934】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L557-L666】
 - **`blc_update_image_scan_status`** – La structure de statut n'expose ni `job_id` ni journal des transitions et ne notifie aucun hook dédié lors d'un changement d'état, ce qui complique l'audit et l'alignement avec les processus ITIL utilisés par les suites professionnelles. Harmoniser cette fonction avec `blc_update_link_scan_status()` (machine à états, journalisation) permettrait de tracer finement les scans d'images. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L867-L934】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L557-L666】
 - **`blc_schedule_manual_image_scan`** – Contrairement au parcours des liens, la planification d'images ne retournait aucun identifiant de job ni tentative associée, empêchant de tracer les relances et de synchroniser l'interface avec le scan lancé. Une instrumentation équivalente est attendue côté solutions pro. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L1280-L1358】
-- **`JLG\BrokenLinks\Scanner\RemoteRequestClient`** – Le client gère désormais la rotation des User-Agent, le backoff exponentiel et le respect de `Retry-After`, mais reste mono-endpoint : aucun support de pool de proxys, de répartition géographique ou de métriques exportables n'est prévu. Les solutions pro offrent souvent une abstraction réseau capable de basculer entre plusieurs sorties et de publier des temps de réponse détaillés. 【F:liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php†L17-L168】
+- **`JLG\BrokenLinks\Scanner\RemoteRequestClient`** – Le client gère désormais la rotation des User-Agent, le backoff exponentiel et le respect de `Retry-After`, mais reste mono-endpoint : aucun support de pool de proxys, de répartition géographique ou de métriques exportables n'est prévu. Les solutions pro offrent souvent une abstraction réseau capable de basculer entre plusieurs sorties et de publier des temps de réponse détaillés. 【F:liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php†L17-L168】 ✅ Les tentatives sont maintenant journalisées via des métriques structurées (`blc_remote_request_metrics`) persistées dans l'historique. 【F:liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php†L17-L356】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L720-L768】
 - **`blc_schedule_automated_report_generation`** – La vérification d'un événement déjà planifié repose sur `wp_next_scheduled()` avec le contexte complet, mais `blc_normalize_report_context()` y injecte un `completed_at` recalculé à chaque appel. Les arguments diffèrent donc entre deux déclenchements successifs et la déduplication échoue, ce qui multiplie les jobs concurrents et peut saturer le stockage des exports. Stabiliser les métadonnées utilisées pour la comparaison (ou introduire un identifiant persistant) est nécessaire pour garantir l'idempotence. ✅ La normalisation accepte désormais un drapeau `stabilize_completed_at` qui réutilise `ended_at` ou `0` pour éviter les doublons lors de la planification. 【F:liens-morts-detector-jlg/includes/blc-reporting.php†L88-L166】
 ## Tests de débogage ajoutés
 
@@ -26,6 +26,7 @@
 > ✅ `blc_update_image_scan_status` conserve maintenant un journal d'audit (transitions valides/invalides), persiste l'historique des jobs et propage `job_id`, `attempt` et `scheduled_at` pour l'observabilité, offrant un suivi équivalent à celui des scans de liens. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L1109-L1285】【F:tests/LinkScanStatusTest.php†L294-L372】
 > ✅ `blc_schedule_manual_image_scan` génère un identifiant de job déterministe, retente la planification en cas d'échec, journalise le contexte et renvoie les métadonnées nécessaires à l'interface et aux appels AJAX. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L1280-L1366】【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L3698-L3771】
 > ✅ `blc_perform_image_check` journalise désormais la durée, l'état et la progression du lot traité, enregistre un historique `blc_image_scan_metrics_history` persistant et expose le hook `blc_image_scan_metrics` pour la télémétrie externe. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L742-L779】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L4668-L4744】
+> ✅ `JLG\BrokenLinks\Scanner\RemoteRequestClient` publie des métriques de requêtes HTTP (durée, code de réponse, retries) via `blc_remote_request_metrics` et conserve les 100 derniers échantillons pour l'observabilité. 【F:liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php†L216-L356】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L720-L768】
 
 ## Tests manuels recommandés
 
diff --git a/liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php b/liens-morts-detector-jlg/includes/Scanner/RemoteRequestClient.php
@@ -94,14 +94,30 @@ protected function requestWithRetries($method, $url, array $args)
             $this->enforceRateLimit();
 
             $requestArgs = $this->prepareRequestArguments($args, $attempt);
+            $requestStartedAt = microtime(true);
             $lastResponse = $this->dispatchRequest($method, $url, $requestArgs);
+            $durationMs = (int) round((microtime(true) - $requestStartedAt) * 1000);
 
-            if (!$this->shouldRetry($lastResponse, $attempt, $attempts)) {
+            $retryAfter = $this->getRetryAfterDelay($lastResponse);
+            $willRetry = $this->shouldRetry($lastResponse, $attempt, $attempts);
+
+            $this->recordRequestMetrics(
+                $method,
+                $url,
+                $requestArgs,
+                $attempt,
+                $attempts,
+                $durationMs,
+                $lastResponse,
+                $willRetry,
+                $retryAfter
+            );
+
+            if (!$willRetry) {
                 return $lastResponse;
             }
 
             $delay = min($maxDelayMs, $delayMs * (2 ** ($attempt - 1)));
-            $retryAfter = $this->getRetryAfterDelay($lastResponse);
             if ($retryAfter !== null) {
                 $delay = max($delay, $retryAfter);
             }
@@ -279,7 +295,7 @@ private function getRetryAfterDelay($response)
         }
 
         $header = \wp_remote_retrieve_header($response, 'retry-after');
-        if ($header === '') {
+        if (!is_string($header) || $header === '') {
             return null;
         }
 
@@ -315,6 +331,147 @@ private function pickUserAgent($attempt)
         return $this->userAgents[$index];
     }
 
+    /**
+     * Build and dispatch request metrics for observability.
+     *
+     * @param string               $method
+     * @param string               $url
+     * @param array<string, mixed> $args
+     * @param int                  $attempt
+     * @param int                  $maxAttempts
+     * @param int                  $durationMs
+     * @param array|WP_Error       $response
+     * @param bool                 $willRetry
+     * @param int|null             $retryAfterMs
+     *
+     * @return void
+     */
+    private function recordRequestMetrics(
+        $method,
+        $url,
+        array $args,
+        $attempt,
+        $maxAttempts,
+        $durationMs,
+        $response,
+        $willRetry,
+        $retryAfterMs
+    ) {
+        $metrics = $this->createRequestMetricsPayload(
+            $method,
+            $url,
+            $args,
+            $attempt,
+            $maxAttempts,
+            $durationMs,
+            $response,
+            $willRetry,
+            $retryAfterMs
+        );
+
+        if (function_exists('\\blc_record_remote_request_metrics')) {
+            \blc_record_remote_request_metrics($metrics);
+        }
+
+        if (function_exists('\\do_action')) {
+            \do_action('blc_remote_request_metrics', $metrics, $response, $args);
+        }
+    }
+
+    /**
+     * Assemble the metrics payload describing the request attempt.
+     *
+     * @param string               $method
+     * @param string               $url
+     * @param array<string, mixed> $args
+     * @param int                  $attempt
+     * @param int                  $maxAttempts
+     * @param int                  $durationMs
+     * @param array|WP_Error       $response
+     * @param bool                 $willRetry
+     * @param int|null             $retryAfterMs
+     *
+     * @return array<string, mixed>
+     */
+    private function createRequestMetricsPayload(
+        $method,
+        $url,
+        array $args,
+        $attempt,
+        $maxAttempts,
+        $durationMs,
+        $response,
+        $willRetry,
+        $retryAfterMs
+    ) {
+        $parsedUrl = function_exists('wp_parse_url') ? \wp_parse_url($url) : parse_url($url);
+
+        $host = '';
+        if (is_array($parsedUrl) && isset($parsedUrl['host'])) {
+            $host = (string) $parsedUrl['host'];
+            if (function_exists('blc_normalize_remote_host')) {
+                $normalizedHost = \blc_normalize_remote_host($host);
+                if ($normalizedHost !== '') {
+                    $host = $normalizedHost;
+                }
+            } else {
+                $host = strtolower($host);
+            }
+        }
+
+        $path = '/';
+        if (is_array($parsedUrl) && isset($parsedUrl['path'])) {
+            $candidatePath = (string) $parsedUrl['path'];
+            if ($candidatePath !== '') {
+                $path = $candidatePath;
+            }
+        }
+
+        $methodLabel = strtoupper((string) $method);
+        $timestamp = time();
+        $responseCode = 0;
+        $success = false;
+
+        $errorCode = '';
+        $errorMessage = '';
+
+        if ($response instanceof WP_Error) {
+            $errorCode = (string) $response->get_error_code();
+            $errorMessage = $response->get_error_message();
+        } else {
+            $responseCode = (int) \wp_remote_retrieve_response_code($response);
+            if (!$willRetry && $responseCode >= 200 && $responseCode < 400) {
+                $success = true;
+            }
+        }
+
+        $metrics = [
+            'method'         => $methodLabel,
+            'url'            => (string) $url,
+            'host'           => $host,
+            'path'           => $path,
+            'attempt'        => (int) $attempt,
+            'max_attempts'   => (int) $maxAttempts,
+            'duration_ms'    => max(0, (int) $durationMs),
+            'timestamp'      => (int) $timestamp,
+            'response_code'  => $responseCode,
+            'success'        => $success,
+            'will_retry'     => (bool) $willRetry,
+            'retry_after_ms' => ($retryAfterMs !== null) ? max(0, (int) $retryAfterMs) : null,
+        ];
+
+        if ($errorCode !== '' || $errorMessage !== '') {
+            $metrics['error_code'] = $errorCode;
+            $metrics['error_message'] = $errorMessage;
+        }
+
+        if (isset($args['user-agent']) && is_string($args['user-agent'])) {
+            $metrics['user_agent'] = trim($args['user-agent']);
+        }
+
+        return $metrics;
+    }
+
     /**
      * Provide a default pool of user agent strings inspired by common browsers.
      *
diff --git a/liens-morts-detector-jlg/includes/blc-scanner.php b/liens-morts-detector-jlg/includes/blc-scanner.php
@@ -766,6 +766,39 @@ function blc_record_image_scan_metrics(array $metrics) {
     }
 }
 
+if (!function_exists('blc_get_remote_request_metrics_history')) {
+    /**
+     * Retrieve the history of remote request metrics collected during scans.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    function blc_get_remote_request_metrics_history() {
+        $history = get_option('blc_remote_request_metrics_history', []);
+
+        return is_array($history) ? $history : [];
+    }
+}
+
+if (!function_exists('blc_record_remote_request_metrics')) {
+    /**
+     * Persist telemetry about a remote HTTP request performed during scanning.
+     *
+     * @param array<string, mixed> $metrics
+     *
+     * @return void
+     */
+    function blc_record_remote_request_metrics(array $metrics) {
+        $history = blc_get_remote_request_metrics_history();
+
+        array_unshift($history, $metrics);
+        if (count($history) > 100) {
+            $history = array_slice($history, 0, 100);
+        }
+
+        update_option('blc_remote_request_metrics_history', $history, false);
+    }
+}
+
 if (!function_exists('blc_get_image_scan_metrics_history')) {
     /**
      * Retrieve the persisted metrics history for image scans.
diff --git a/patchwork.json b/patchwork.json
@@ -5,6 +5,8 @@
         "dns_get_record",
         "gethostbynamel",
         "error_log",
-        "file_exists"
+        "file_exists",
+        "microtime",
+        "usleep"
     ]
 }
diff --git a/tests/Scanner/RemoteRequestClientTest.php b/tests/Scanner/RemoteRequestClientTest.php
@@ -102,4 +102,105 @@ public function test_request_replaces_empty_user_agent_with_pool_value(): void
         $this->assertSame('Pool-Agent/2.0', $capturedArgs['headers']['USER-AGENT']);
         $this->assertSame('Pool-Agent/2.0', $capturedArgs['user-agent']);
     }
+
+    public function test_request_records_metrics_and_triggers_hook(): void
+    {
+        $metricsLog = [];
+        $hookLog    = [];
+
+        Functions\when('blc_record_remote_request_metrics')->alias(function ($metrics) use (&$metricsLog) {
+            $metricsLog[] = $metrics;
+        });
+
+        Functions\when('do_action')->alias(function ($hook, ...$args) use (&$hookLog) {
+            if ($hook === 'blc_remote_request_metrics') {
+                $hookLog[] = $args;
+            }
+        });
+
+        Functions\when('time')->justReturn(1700000000);
+
+        $microtimeSequence = [1000.0, 1000.05, 1000.1, 1000.15, 1000.2, 1000.25, 1000.3, 1000.35];
+        Functions\when('microtime')->alias(function ($as_float = false) use (&$microtimeSequence) {
+            $value = array_shift($microtimeSequence);
+            if ($value === null) {
+                $value = 1000.4;
+            }
+
+            if ($as_float) {
+                return $value;
+            }
+
+            $integer = (int) $value;
+            $fraction = $value - $integer;
+
+            return sprintf('%0.8f %d', $fraction, $integer);
+        });
+
+        Functions\when('usleep')->alias(static function ($milliseconds) {
+            return true;
+        });
+
+        $responses = [
+            ['response' => ['code' => 429], 'headers' => ['retry-after' => '3']],
+            ['response' => ['code' => 200], 'headers' => []],
+        ];
+
+        Functions\when('wp_safe_remote_get')->alias(static function ($url, $args) use (&$responses) {
+            return array_shift($responses);
+        });
+
+        Functions\when('wp_remote_retrieve_response_code')->alias(static function ($response) {
+            return isset($response['response']['code']) ? (int) $response['response']['code'] : 0;
+        });
+
+        Functions\when('wp_remote_retrieve_header')->alias(static function ($response, $header) {
+            $header = strtolower((string) $header);
+            if (isset($response['headers'][$header])) {
+                return $response['headers'][$header];
+            }
+
+            return '';
+        });
+
+        $client = new RemoteRequestClient([], [
+            'max_attempts'     => 2,
+            'initial_delay_ms' => 10,
+            'max_delay_ms'     => 20,
+        ], []);
+
+        $result = $client->get('https://example.com/resource', []);
+
+        $this->assertSame(['response' => ['code' => 200], 'headers' => []], $result);
+        $this->assertCount(2, $metricsLog);
+        $this->assertCount(2, $hookLog);
+
+        $first = $metricsLog[0];
+        $this->assertSame('GET', $first['method']);
+        $this->assertSame('https://example.com/resource', $first['url']);
+        $this->assertSame('example.com', $first['host']);
+        $this->assertSame('/resource', $first['path']);
+        $this->assertSame(1, $first['attempt']);
+        $this->assertSame(2, $first['max_attempts']);
+        $this->assertSame(429, $first['response_code']);
+        $this->assertFalse($first['success']);
+        $this->assertTrue($first['will_retry']);
+        $this->assertSame(3000, $first['retry_after_ms']);
+        $this->assertSame(1700000000, $first['timestamp']);
+        $this->assertSame(
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0 Safari/537.36',
+            $first['user_agent']
+        );
+
+        $second = $metricsLog[1];
+        $this->assertSame(2, $second['attempt']);
+        $this->assertSame(2, $second['max_attempts']);
+        $this->assertSame(200, $second['response_code']);
+        $this->assertTrue($second['success']);
+        $this->assertFalse($second['will_retry']);
+        $this->assertNull($second['retry_after_ms']);
+
+        $this->assertSame($metricsLog[0], $hookLog[0][0]);
+        $this->assertSame($metricsLog[1], $hookLog[1][0]);
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,8 @@`
`5`	`5`	`"dns_get_record",`
`6`	`6`	`"gethostbynamel",`
`7`	`7`	`"error_log",`
`8`		`- "file_exists"`
	`8`	`+ "file_exists",`
	`9`	`+ "microtime",`
	`10`	`+ "usleep"`
`9`	`11`	`]`
`10`	`12`	`}`