xspeed / includes / modules / Health / HealthModule.php

HealthModule.php in xSpeed Cache: AI-Powered Performance Hub with MCP, Caching & CDN 1.3.6, at includes/modules/Health/HealthModule.php

375 lines 17.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Health module — read-only diagnostic surface for the dashboard.
4	*
5	* No settings_schema (this is a status panel, not a configuration
6	* surface). The React side renders a custom panel (HealthCard, declared
7	* via `ui_metadata.custom_panel`) instead of going through ModulePanel's
8	* schema-driven path.
9	*
10	* Data sources are all existing services:
11	* - Health::checks() — diagnostic rows
12	* - Cache::get_stats() — cached_pages / size / last_purge /
13	* hits_24h / misses_24h / hit_ratio
14	* - Hit_Counter::buckets() — 24 hourly buckets for the sparkline
15	* - Activity_Log::entries() — newest-first event log
16	*
17	* Tier: Free (per FEATURES.md "Cache Insights" — Cache Performance +
18	* Last 24h chart are Free; Recommendations + Frequently-missed-URLs
19	* stay Pro).
20	*
21	* @package XSpeed
22	*/
23
24	declare(strict_types=1);
25
26	namespace XSpeed\Modules\Health;
27
28	defined( 'ABSPATH' ) \|\| exit;
29
30	use XSpeed\Activity_Log;
31	use XSpeed\Cache;
32	use XSpeed\Health;
33	use XSpeed\Hit_Counter;
34	use XSpeed\Module;
35
36	final class HealthModule extends Module {
37
38	public const SLUG = 'health';
39	public const TIER = self::TIER_FREE;
40	public const VERSION = '1.0.0';
41
42	/**
43	* Surface the most important diagnostics in WordPress's built-in
44	* Site Health screen (Tools → Site Health → Status). Admins who
45	* never open the xSpeed dashboard still get a heads-up when
46	* static-rewrite is missing on Apache/LiteSpeed or when the nginx
47	* snippet hasn't been pasted yet — both lead to a 5-10× slowdown
48	* vs the optimal cache hit path.
49	*/
50	public function boot(): void {
51	add_filter( 'site_status_tests', array( $this, 'register_site_status_tests' ) );
52
53	// Out-of-band refresh of the Set-Cookie probe. Health::checks()
54	// only ever reads the cached verdict, so the HTTP round-trip
55	// happens here instead of inside a request the user waits on.
56	add_action( \XSpeed\Cookie_Inspector::CRON_HOOK, array( $this, 'refresh_cookie_probe' ) );
57	}
58
59	/** Cron callback: perform the real (blocking) probe off-request. */
60	public function refresh_cookie_probe(): void {
61	\XSpeed\Cookie_Inspector::probe( true );
62	}
63
64	public function register_site_status_tests( array $tests ): array {
65	$tests['direct']['xspeed_static_rewrite'] = array(
66	'label' => __( 'xSpeed static-rewrite cache', 'xspeed' ),
67	'test' => array( $this, 'site_status_static_rewrite' ),
68	);
69	return $tests;
70	}
71
72	/**
73	* Site Health test row. Reports green when the .htaccess block is
74	* present (Apache/LiteSpeed) or yellow with the nginx snippet
75	* embedded when nginx is detected. Skipped entirely when cache is
76	* disabled — no point telling the user to install a rewrite they
77	* haven't opted into.
78	*/
79	/**
80	* Decide what the nginx static rewrite is actually doing.
81	*
82	* Extracted so the ordering is testable without a WordPress bootstrap,
83	* and so Site Health and the dashboard Health panel cannot drift apart
84	* again — the whole point of #480.
85	*
86	* Returns one of: 'active', 'mobile_separate', 'skipped_nonce',
87	* 'unverified', 'required'.
88	*
89	* @param array<string, mixed> $probe probe_static_rewrite() result.
90	* @param string $block_reason A known refusal, or ''.
91	*/
92	public static function nginx_rewrite_verdict( array $probe, string $block_reason ): string {
93	$is_active = (bool) ( $probe['active'] ?? false );
94	$inconclusive = (bool) ( $probe['inconclusive'] ?? false );
95
96	// A known refusal OUTRANKS the probe. probe_static_rewrite() writes
97	// its own file under the static-cache dir and fetches that, which
98	// succeeds whenever the server can serve a static file at all — even
99	// when no real page is on the static path. It also outranks
100	// "inconclusive", so a blocked rewrite whose probe merely failed to
101	// complete is reported as the refusal it is. (FBS-83145)
102	if ( '' !== $block_reason ) {
103	if ( 'mobile_separate' === $block_reason ) {
104	return 'mobile_separate';
105	}
106	if ( 'skipped_nonce' === $block_reason ) {
107	return 'skipped_nonce';
108	}
109	return 'required';
110	}
111
112	if ( $is_active ) {
113	return 'active';
114	}
115
116	// The probe never reached a verdict (blocked loopback, self-signed
117	// cert, timeout, a CDN/WAF answering instead of the origin). That is
118	// not evidence the config is wrong, and must not produce a
119	// "paste this snippet" banner. (FBS-84012, #480)
120	return $inconclusive ? 'unverified' : 'required';
121	}
122
123	public function site_status_static_rewrite(): array {
124	$result = array(
125	'label' => __( 'xSpeed static-rewrite cache is active', 'xspeed' ),
126	'status' => 'good',
127	'badge' => array(
128	'label' => __( 'Performance', 'xspeed' ),
129	'color' => 'blue',
130	),
131	'description' => '<p>' . esc_html__( 'Cache hits bypass PHP for ~5-15ms TTFB.', 'xspeed' ) . '</p>',
132	'test' => 'xspeed_static_rewrite',
133	);
134
135	$cache_enabled = (bool) ( \XSpeed\Settings::get()['cache_enabled'] ?? false );
136	if ( ! $cache_enabled ) {
137	$result['label'] = __( 'xSpeed cache is disabled', 'xspeed' );
138	$result['status'] = 'recommended';
139	$result['description'] = '<p>' . esc_html__( 'Enable the page cache in the xSpeed dashboard to start serving cached HTML for non-logged-in visitors.', 'xspeed' ) . '</p>';
140	return $result;
141	}
142
143	$server_type = \XSpeed\Server::type();
144	if ( \XSpeed\Server::APACHE === $server_type \|\| \XSpeed\Server::LITESPEED === $server_type ) {
145	// Only call the block "missing" when it is genuinely absent by
146	// accident. When static_rewrite_allowed() deliberately refused it,
147	// "toggle Enable Cache off and on" cannot reinstall anything —
148	// the same condition suppresses the write and auto_heal() strips
149	// the block again on the next admin load. Explain the real cause.
150	$block_reason = \XSpeed\Cache::static_rewrite_block_reason();
151	if ( 'litespeed_dropin' === $block_reason ) {
152	// The intended LiteSpeed default (#509) — 'good', not a nag:
153	// hits are visible and counted, and the faster path is a
154	// deliberate opt-in, not a missing config.
155	$result['label'] = __( 'xSpeed is serving cache hits through PHP (LiteSpeed)', 'xspeed' );
156	$result['status'] = 'good';
157	$result['description'] = '<p>' . esc_html__( 'Caching is working — hits are served by the xSpeed drop-in and tagged X-XSpeed-Cache: HIT (php), so every hit is visible and counted. LiteSpeed\'s .htaccess engine cannot tag or log statically served files, so this is the default. To serve hits straight from the web server with no PHP (at the cost of that tagging and counting), turn on LiteSpeed Static Fast Path in xSpeed\'s Cache settings.', 'xspeed' ) . '</p>';
158	} elseif ( 'no_mod_headers' === $block_reason ) {
159	$result['label'] = __( 'xSpeed is serving cache hits through PHP', 'xspeed' );
160	$result['status'] = 'recommended';
161	$result['description'] = '<p>' . esc_html__( 'Caching is working — hits are served by the xSpeed drop-in and tagged X-XSpeed-Cache: HIT (php). The faster .htaccess fast path is off because Apache\'s mod_headers module is not loaded, without which a static hit could not be tagged or counted. Enable mod_headers (a2enmod headers on Debian/Ubuntu, then restart Apache) to shave roughly 20-30ms off each cache hit.', 'xspeed' ) . '</p>';
162	} elseif ( 'mobile_separate' === $block_reason ) {
163	$result['label'] = __( 'xSpeed static rewrite is off (Separate Mobile Cache)', 'xspeed' );
164	$result['status'] = 'recommended';
165	$result['description'] = '<p>' . esc_html__( 'Separate Mobile Cache is on, so cache hits are served by the PHP drop-in to keep per-device HTML correct. Turn Separate Mobile Cache off if your site serves the same HTML to every device to regain the faster static path.', 'xspeed' ) . '</p>';
166	} elseif ( '' === $block_reason && ! \XSpeed\Cache::rewrite_installed() ) {
167	// Apache, or LiteSpeed with the Static Fast Path opt-in on
168	// (#509) — either way the block SHOULD be there and is not.
169	$result['label'] = __( 'xSpeed .htaccess rewrite block is missing', 'xspeed' );
170	$result['status'] = 'recommended';
171	$result['description'] = '<p>' . esc_html__( 'Without the static-rewrite block, cache hits go through the PHP drop-in (~85ms TTFB) instead of the web server (~5-15ms). Toggle Enable Cache off and on in xSpeed to reinstall the block.', 'xspeed' ) . '</p>';
172	}
173	return $result;
174	}
175
176	if ( \XSpeed\Server::NGINX === $server_type ) {
177	// Ask the same question the dashboard Health panel asks, the same
178	// way. This test used to return "config required" unconditionally,
179	// so every correctly-configured nginx site — every xCloud site,
180	// where the panel installs the block for you — was told to paste a
181	// snippet it already had, and re-running the check never cleared
182	// it. Worse, the dashboard said the opposite at the same moment.
183	// Reuse probe_static_rewrite() + the refusal reasons so the two
184	// surfaces cannot disagree. (#480)
185	$probe = \XSpeed\Cache::probe_static_rewrite( true );
186	$probe_reason = (string) ( $probe['reason'] ?? '' );
187
188	$block_reason = \XSpeed\Cache::static_rewrite_block_reason();
189	$skip = \XSpeed\Cache::last_static_skip();
190	if ( '' === $block_reason && ! empty( $skip['reason'] ) ) {
191	$block_reason = 'skipped_' . (string) $skip['reason'];
192	}
193
194	switch ( self::nginx_rewrite_verdict( $probe, $block_reason ) ) {
195	case 'active':
196	$result['label'] = __( 'xSpeed nginx static rewrite is active', 'xspeed' );
197	$result['status'] = 'good';
198	$result['description'] = '<p>' . esc_html__( 'nginx is serving cache hits directly — PHP is bypassed (~5-15ms TTFB). No action needed.', 'xspeed' ) . '</p>';
199	return $result;
200
201	case 'mobile_separate':
202	$result['label'] = __( 'xSpeed static rewrite is off (Separate Mobile Cache)', 'xspeed' );
203	$result['status'] = 'recommended';
204	$result['description'] = '<p>' . esc_html__( 'Separate Mobile Cache is on, so cache hits are served by the PHP drop-in to keep per-device HTML correct. Turn Separate Mobile Cache off if your site serves the same HTML to every device to regain the faster static path.', 'xspeed' ) . '</p>';
205	return $result;
206
207	case 'skipped_nonce':
208	$result['label'] = __( 'xSpeed is serving cache hits through PHP (pages contain nonces)', 'xspeed' );
209	$result['status'] = 'recommended';
210	$result['description'] = '<p>' . esc_html__( 'Your nginx config is correct, but pages are not reaching the static cache, so hits are served by PHP. They contain nonces, and a static file is served with no PHP — nothing could ever refresh them, so every anonymous form on the page would break once they expire. Keeping these pages on PHP is deliberate.', 'xspeed' ) . '</p>';
211	return $result;
212
213	case 'unverified':
214	// The probe never reached a verdict (blocked loopback,
215	// self-signed cert, timeout, a CDN/WAF answering instead of
216	// the origin). Not evidence the config is wrong, so don't
217	// say "required" and don't dump a snippet the user has
218	// probably already pasted. (FBS-84012, and why #480 was filed.)
219	$result['label'] = __( 'xSpeed could not verify the nginx static rewrite', 'xspeed' );
220	$result['status'] = 'recommended';
221	$result['description'] = '<p>' . esc_html(
222	sprintf(
223	/* translators: %s: the reason the probe could not complete. */
224	__( 'The check itself did not complete, so this is not evidence that your config is wrong — if you have already pasted the snippet it may well be working. Reason: %s', 'xspeed' ),
225	$probe_reason
226	)
227	) . '</p>';
228	return $result;
229	}
230
231	$snippet = \XSpeed\Cache::nginx_snippet();
232	$result['label'] = __( 'xSpeed nginx server config required', 'xspeed' );
233	$result['status'] = 'recommended';
234	$result['description'] = '<p>' . esc_html__( 'xSpeed can\'t write nginx config from PHP. Paste this snippet into your site\'s server { } block, then reload nginx so cache hits serve without booting PHP:', 'xspeed' ) . '</p>'
235	. '<pre style="white-space:pre;overflow-x:auto;background:#f6f7f7;border:1px solid #c3c4c7;border-radius:4px;padding:12px;font-size:12px;line-height:1.4;">'
236	. esc_html( (string) $snippet )
237	. '</pre>';
238	return $result;
239	}
240
241	// Unknown / IIS — no server-level rewrite path available; PHP
242	// drop-in is the best we can offer. Don't flag as broken.
243	$result['label'] = __( 'xSpeed PHP drop-in cache active', 'xspeed' );
244	$result['status'] = 'recommended';
245	$result['description'] = '<p>' . esc_html__( 'Static-rewrite caching needs Apache, LiteSpeed, or nginx. The PHP drop-in is still serving cache hits at ~85ms TTFB on this server.', 'xspeed' ) . '</p>';
246	return $result;
247	}
248
249	public function ui_metadata(): array {
250	return array(
251	'label' => __( 'Health', 'xspeed' ),
252	'icon' => 'HeartPulse',
253	'description' => __( 'Diagnostics, hit ratio, and recent cache activity.', 'xspeed' ),
254	// Health is the single host page for all Insights (FBS-83633):
255	// a Recommendations action card + Cache / Visitors / PageSpeed
256	// tabs. HealthPanel renders the Free cache diagnostics (the old
257	// HealthCard) as the Cache tab and hosts the Pro insight panels
258	// as the other tabs via ProSlot.
259	'custom_panel' => 'HealthPanel',
260	);
261	}
262
263	// No settings — explicit empty so Module::rest_routes() doesn't
264	// auto-wire the schema-driven GET+POST.
265	public function settings_schema(): array {
266	return array();
267	}
268
269	public function rest_routes(): array {
270	return array(
271	array(
272	'path' => '/',
273	'methods' => 'GET',
274	'callback' => array( $this, 'rest_get_payload' ),
275	),
276	);
277	}
278
279	public function cli_commands(): array {
280	return array(
281	array(
282	'name' => 'xspeed health',
283	'callback' => array( $this, 'cli_handler' ),
284	'shortdesc' => 'Print diagnostic checks + cache stats + recent activity.',
285	'ai_hint' => 'Full diagnostic sweep: what is misconfigured or degraded on this site right now, plus cache stats and recent activity. The best FIRST call for open-ended "why is my site slow" or "is anything wrong" questions.',
286	'synopsis' => array(),
287	),
288	array(
289	'name' => 'xspeed recommend',
290	'callback' => array( $this, 'cli_recommend' ),
291	'shortdesc' => 'List ranked next-best-action recommendations, or apply one by id.',
292	'ai_hint' => 'The ranked list of what to do next to make this site faster, and the way to apply one. Use when asked "what should I improve" or "what\'s the biggest win" — each item is actionable and ordered by impact.',
293	'synopsis' => array(
294	array(
295	'type' => 'positional',
296	'name' => 'action',
297	'options' => array( 'list', 'apply' ),
298	'optional' => true,
299	),
300	array(
301	'type' => 'positional',
302	'name' => 'id',
303	'optional' => true,
304	),
305	),
306	),
307	);
308	}
309
310	/** CLI: `wp xspeed recommend [list\|apply <id>]` — MCP-reachable via run_command. */
311	public function cli_recommend( array $args, array $assoc ): void {
312	$action = isset( $args[0] ) ? (string) $args[0] : 'list';
313
314	if ( 'apply' === $action ) {
315	$id = isset( $args[1] ) ? (string) $args[1] : '';
316	if ( '' === $id ) {
317	\WP_CLI::error( 'Usage: wp xspeed recommend apply <id>' );
318	return;
319	}
320	$result = \XSpeed\Recommendations::apply( $id );
321	if ( is_wp_error( $result ) ) {
322	\WP_CLI::error( $result->get_error_message() );
323	return;
324	}
325	\WP_CLI::success( sprintf( 'Applied "%s". %d recommendation(s) remain.', $id, count( $result['recommendations'] ) ) );
326	return;
327	}
328
329	$recs = \XSpeed\Recommendations::all();
330	if ( empty( $recs ) ) {
331	\WP_CLI::success( 'No recommendations — configuration looks healthy.' );
332	return;
333	}
334	foreach ( $recs as $i => $rec ) {
335	$fixable = 'apply' === ( $rec['action']['type'] ?? '' ) ? ' (one-click: wp xspeed recommend apply ' . $rec['id'] . ')' : '';
336	\WP_CLI::log( sprintf( '%d. [%s] %s — %s%s', $i + 1, $rec['id'], $rec['title'], $rec['detail'], $fixable ) );
337	}
338	}
339
340	/**
341	* Single endpoint that backs the dashboard panel. Refreshed lazily by
342	* the React side; cheap enough that aggregating into one response is
343	* the right call (the buckets array is at most 24 entries; activity
344	* is capped at 50).
345	*/
346	public function rest_get_payload( \WP_REST_Request $request ) {
347	return rest_ensure_response( $this->payload() );
348	}
349
350	public function payload(): array {
351	return array(
352	'checks' => Health::checks(),
353	'stats' => Cache::get_stats(),
354	'buckets' => Hit_Counter::buckets(),
355	'activity' => Activity_Log::entries(),
356	);
357	}
358
359	public function cli_handler( array $args, array $assoc ): void {
360	$payload = $this->payload();
361	\WP_CLI::log( '== Checks ==' );
362	foreach ( $payload['checks'] as $c ) {
363	\WP_CLI::log( sprintf( '[%s] %s — %s', strtoupper( $c['tone'] ), $c['label'], $c['detail'] ) );
364	}
365	\WP_CLI::log( '' );
366	\WP_CLI::log( '== Stats (24h) ==' );
367	\WP_CLI::log( sprintf( 'Hits %d · Misses %d · Hit ratio %.2f%%', $payload['stats']['hits_24h'], $payload['stats']['misses_24h'], $payload['stats']['hit_ratio'] * 100 ) );
368	\WP_CLI::log( '' );
369	\WP_CLI::log( '== Recent activity ==' );
370	foreach ( array_slice( $payload['activity'], 0, 10 ) as $e ) {
371	\WP_CLI::log( sprintf( '%s [%s] %s', gmdate( 'Y-m-d H:i:s', $e['ts'] ), $e['severity'], $e['message'] ) );
372	}
373	}
374	}
375