Add a Site Health connection test and debug information section (#192)

Author: pfefferle

.github/changelog/add-site-health-check

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Site Health now shows your Bluesky connection status, explains why a reconnect is needed and how to prevent it, and adds an ATmosphere section to the debug information for easier troubleshooting.

includes/class-api.php

@@ -14,7 +14,6 @@
 
 use Atmosphere\OAuth\Client;
 use Atmosphere\OAuth\DPoP;
-use Atmosphere\OAuth\Encryption;
 
 /**
  * PDS API client.
@@ -60,9 +59,9 @@ public static function request( string $method, string $endpoint, array $args =
 		 */
 		$access_token_snapshot = (string) ( $conn['access_token'] ?? '' );
 
-		$dpop_jwk_json = Encryption::decrypt( $conn['dpop_jwk'] ?? '' );
-		if ( false === $dpop_jwk_json ) {
-			return Client::flag_decrypt_failure( $conn, 'dpop_jwk' );
+		$dpop_jwk_json = Client::decrypt_field( $conn, 'dpop_jwk' );
+		if ( \is_wp_error( $dpop_jwk_json ) ) {
+			return $dpop_jwk_json;
 		}
 
 		$dpop_jwk = \json_decode( $dpop_jwk_json, true );

includes/class-atmosphere.php

@@ -25,6 +25,7 @@
 use Atmosphere\Rest\Client_Metadata_Controller;
 use Atmosphere\Rest\Reactions_Controller;
 use Atmosphere\WP_Admin\Admin;
+use Atmosphere\WP_Admin\Health_Check;
 use Atmosphere\WP_Admin\Settings_Fields;
 
 /**
@@ -163,6 +164,17 @@ public function init(): void {
 		\add_action( 'init', array( Options::class, 'init' ), 5 );
 		\add_action( 'init', array( Settings_Fields::class, 'init' ), 5 );
 
+		/*
+		 * Site Health status test + debug information. Registered
+		 * directly on the pull filters (no context gate, no `init`
+		 * indirection): they only fire on Site Health surfaces — the
+		 * screen, the weekly scheduled check, WP-CLI — so the class is
+		 * autoloaded only there and every other request just stores two
+		 * callables.
+		 */
+		\add_filter( 'site_status_tests', array( Health_Check::class, 'add_tests' ) );
+		\add_filter( 'debug_information', array( Health_Check::class, 'debug_information' ) );
+
 		/*
 		 * Display-side @handle.tld mention auto-linking. Self-registers on
 		 * init so the_content (priority 100) is wired for both front-end
@@ -1482,7 +1494,7 @@ public function register_share_status_field(): void {
 							return null;
 						}
 
-						$reconnect_class = \in_array( (string) $error['code'], self::RECONNECT_ERROR_CODES, true );
+						$reconnect_class = Client::is_reconnect_error( (string) $error['code'] );
 						$needs_reconnect = $reconnect_class && ! is_connected();
 
 						/*
@@ -2112,28 +2124,6 @@ private static function record_publish_error( int $post_id, \WP_Error $error, bo
 		);
 	}
 
-	/**
-	 * Failure codes resolvable only by reconnecting the Bluesky account.
-	 *
-	 * Consumed by the `atmosphere_publish_error` REST field as the
-	 * `needs_reconnect` flag (combined with the live connection state,
-	 * so the flag drops once the operator reconnects) — the editor
-	 * panel never keeps its own copy of this judgment. Folded into the
-	 * permanent codes of
-	 * {@see self::is_transient_publish_error()}, so each reconnect-class
-	 * code is declared exactly once. Deliberately without
-	 * `atmosphere_did_mismatch`, which reconnecting to the current
-	 * account does not fix.
-	 *
-	 * @var string[]
-	 */
-	private const RECONNECT_ERROR_CODES = array(
-		'atmosphere_key_changed',
-		'atmosphere_decrypt',
-		'atmosphere_needs_reauth',
-		'atmosphere_not_connected',
-	);
-
 	/**
 	 * Whether a publish failure is worth retrying.
 	 *
@@ -2148,27 +2138,32 @@ private static function record_publish_error( int $post_id, \WP_Error $error, bo
 	 * @return bool True when a retry has a chance of succeeding.
 	 */
 	private static function is_transient_publish_error( \WP_Error $error ): bool {
-		$permanent_codes = \array_merge(
-			// Reconnect-class failures are permanent by definition.
-			self::RECONNECT_ERROR_CODES,
-			array(
-				'atmosphere_post_not_publishable',
-				'atmosphere_missing_tid',
-				'atmosphere_invalid_pre_apply_writes_return',
-				'atmosphere_invalid_pre_apply_writes_response',
-				'atmosphere_invalid_pre_upload_blob_return',
-				'atmosphere_did_mismatch',
+		/*
+		 * Reconnect-class failures are permanent by definition; the code
+		 * list lives in {@see Client::is_reconnect_error()}, next to the
+		 * paths that mint those codes, so each code is declared once.
+		 */
+		if ( Client::is_reconnect_error( (string) $error->get_error_code() ) ) {
+			return false;
+		}
 
-				/*
-				 * Never retry a failed thread rollback: the orphan manifest
-				 * records live partial records on the PDS, and a retried
-				 * publish would mint fresh TIDs next to them — a duplicate,
-				 * user-visible copy of the post. This state needs operator
-				 * attention (see Post::META_ORPHAN_RECORDS), not another
-				 * attempt.
-				 */
-				'atmosphere_thread_rollback_failed',
-			)
+		$permanent_codes = array(
+			'atmosphere_post_not_publishable',
+			'atmosphere_missing_tid',
+			'atmosphere_invalid_pre_apply_writes_return',
+			'atmosphere_invalid_pre_apply_writes_response',
+			'atmosphere_invalid_pre_upload_blob_return',
+			'atmosphere_did_mismatch',
+
+			/*
+			 * Never retry a failed thread rollback: the orphan manifest
+			 * records live partial records on the PDS, and a retried
+			 * publish would mint fresh TIDs next to them — a duplicate,
+			 * user-visible copy of the post. This state needs operator
+			 * attention (see Post::META_ORPHAN_RECORDS), not another
+			 * attempt.
+			 */
+			'atmosphere_thread_rollback_failed',
 		);
 
 		if ( \in_array( $error->get_error_code(), $permanent_codes, true ) ) {

includes/functions.php

@@ -504,6 +504,30 @@ function get_reauth_reason(): string {
 	return (string) ( get_connection()['reauth_reason'] ?? '' );
 }
 
+/**
+ * Lead sentence explaining why the connection needs a reconnect.
+ *
+ * Single source for the cause copy so every surface that reads the
+ * `reauth_reason` marker — the admin reconnect notice and the Site
+ * Health test — explains the same failure with the same words. Each
+ * caller appends its own consequence/action tail; copy edits and
+ * translations happen once, here.
+ *
+ * @since unreleased
+ *
+ * @return string Translated, unescaped sentence.
+ */
+function reauth_reason_lead(): string {
+	switch ( get_reauth_reason() ) {
+		case Client::REAUTH_REASON_KEY_CHANGED:
+			return \__( 'Your site’s security keys have changed — this can happen after a migration, or when a security plugin rotates them on a schedule — so ATmosphere can no longer read its saved Bluesky login.', 'atmosphere' );
+		case Client::REAUTH_REASON_DECRYPT_FAILED:
+			return \__( 'ATmosphere can no longer read its saved Bluesky login.', 'atmosphere' );
+		default:
+			return \__( 'Your Bluesky session has expired.', 'atmosphere' );
+	}
+}
+
 /**
  * URL of the ATmosphere settings page.
  *

includes/oauth/class-client.php

@@ -140,9 +140,9 @@ class Client {
 	 * the stored tokens (salt rotation, regenerated wp-config.php).
 	 *
 	 * Written by {@see self::flag_decrypt_failure()}; read by the admin
-	 * reauth notice, whose copy explains the cause. A mistyped
-	 * comparison fails soft (falls through to generic expiry copy), so
-	 * consumers MUST use these constants.
+	 * reauth notice and Site Health, whose copy explains the cause. A
+	 * mistyped comparison fails soft (falls through to generic expiry
+	 * copy), so consumers MUST use these constants.
 	 *
 	 * @since unreleased
 	 *
@@ -794,14 +794,14 @@ public static function refresh(): true|\WP_Error {
 	 * @return true|\WP_Error
 	 */
 	private static function refresh_locked( array $conn ): true|\WP_Error {
-		$refresh_token = Encryption::decrypt( $conn['refresh_token'] );
-		if ( false === $refresh_token ) {
-			return self::flag_decrypt_failure( $conn, 'refresh_token' );
+		$refresh_token = self::decrypt_field( $conn, 'refresh_token' );
+		if ( \is_wp_error( $refresh_token ) ) {
+			return $refresh_token;
 		}
 
-		$dpop_jwk_json = Encryption::decrypt( $conn['dpop_jwk'] );
-		if ( false === $dpop_jwk_json ) {
-			return self::flag_decrypt_failure( $conn, 'dpop_jwk' );
+		$dpop_jwk_json = self::decrypt_field( $conn, 'dpop_jwk' );
+		if ( \is_wp_error( $dpop_jwk_json ) ) {
+			return $dpop_jwk_json;
 		}
 
 		$dpop_jwk       = \json_decode( $dpop_jwk_json, true );
@@ -973,6 +973,66 @@ private static function refresh_locked( array $conn ): true|\WP_Error {
 		return true;
 	}
 
+	/**
+	 * Decrypt a stored connection credential, flagging the row for
+	 * reauth on failure.
+	 *
+	 * The single chokepoint for reading connection ciphertext, so the
+	 * invariant "a failed credential decrypt always flags the row" is
+	 * enforced by the mechanism instead of repeated at every call site
+	 * (see {@see self::flag_decrypt_failure()} for why the failure is
+	 * permanent).
+	 *
+	 * @since unreleased
+	 *
+	 * @param array  $conn  Connection row the credential was read from.
+	 * @param string $field Connection field to decrypt (`access_token`,
+	 *                      `refresh_token`, `dpop_jwk`).
+	 * @return string|\WP_Error The plaintext, or the reauth error.
+	 */
+	public static function decrypt_field( array $conn, string $field ): string|\WP_Error {
+		$plaintext = Encryption::decrypt( (string) ( $conn[ $field ] ?? '' ) );
+
+		if ( false === $plaintext ) {
+			return self::flag_decrypt_failure( $conn, $field );
+		}
+
+		return $plaintext;
+	}
+
+	/**
+	 * Failure codes resolvable only by reconnecting the Bluesky account.
+	 *
+	 * Consumed by the `atmosphere_publish_error` REST field as the
+	 * `needs_reconnect` flag so the editor panel never keeps its own
+	 * copy of this judgment. Lives here, next to the code paths that
+	 * mint these codes, so a future reconnect-class error is added in
+	 * one place. A curated subset of the permanent codes in
+	 * {@see \Atmosphere\Atmosphere::is_transient_publish_error()} —
+	 * deliberately without `atmosphere_did_mismatch`, which reconnecting
+	 * to the current account does not fix.
+	 *
+	 * @var string[]
+	 */
+	private const RECONNECT_ERROR_CODES = array(
+		'atmosphere_key_changed',
+		'atmosphere_decrypt',
+		'atmosphere_needs_reauth',
+		'atmosphere_not_connected',
+	);
+
+	/**
+	 * Whether a failure code can only be resolved by reconnecting.
+	 *
+	 * @since unreleased
+	 *
+	 * @param string $code Machine-readable failure code.
+	 * @return bool
+	 */
+	public static function is_reconnect_error( string $code ): bool {
+		return \in_array( $code, self::RECONNECT_ERROR_CODES, true );
+	}
+
 	/**
 	 * Build the error for an undecryptable connection credential and
 	 * flag the connection for reauth.
@@ -1345,12 +1405,7 @@ public static function access_token(): string|\WP_Error {
 			$conn = \get_option( 'atmosphere_connection', array() );
 		}
 
-		$token = Encryption::decrypt( $conn['access_token'] );
-		if ( false === $token ) {
-			return self::flag_decrypt_failure( $conn, 'access_token' );
-		}
-
-		return $token;
+		return self::decrypt_field( $conn, 'access_token' );
 	}
 
 	/**

includes/oauth/class-encryption.php

@@ -70,7 +70,9 @@ private static function key(): string {
 	/**
 	 * Whether a dedicated `ATMOSPHERE_ENCRYPTION_KEY` is in effect.
 	 *
-	 * Single owner of the defined-non-empty-string semantics used by
+	 * Single owner of the defined-non-empty-string semantics, so the
+	 * admin surfaces reporting the key source (the Site Health test)
+	 * cannot drift from the actual derivation in
 	 * {@see self::key_material()}. A constant misdefined as a non-string
 	 * (e.g. `false` or an array) is treated as unset rather than being
 	 * silently coerced into weak key material.
@@ -79,7 +81,7 @@ private static function key(): string {
 	 *
 	 * @return bool
 	 */
-	private static function has_dedicated_key(): bool {
+	public static function has_dedicated_key(): bool {
 		return \defined( 'ATMOSPHERE_ENCRYPTION_KEY' )
 			&& \is_string( ATMOSPHERE_ENCRYPTION_KEY )
 			&& '' !== ATMOSPHERE_ENCRYPTION_KEY;

includes/wp-admin/class-admin.php

@@ -13,8 +13,8 @@
 use Atmosphere\Handle;
 use Atmosphere\OAuth\Client;
 use Atmosphere\Publisher;
-use function Atmosphere\get_reauth_reason;
 use function Atmosphere\is_operator_disconnected;
+use function Atmosphere\reauth_reason_lead;
 use function Atmosphere\settings_url;
 use function Atmosphere\get_supported_post_types;
 use function Atmosphere\has_identity;
@@ -238,23 +238,18 @@ public static function maybe_render_reauth_notice(): void {
 		}
 
 		$heading = \__( 'ATmosphere: reconnection required', 'atmosphere' );
-		$reason  = get_reauth_reason();
 
 		/*
-		 * Each branch supplies only its lead sentence; the shared tail
-		 * (what stops working + the reconnect link) is composed below so
-		 * copy edits and translations happen once. The disconnect gate's
+		 * The cause lead comes from `reauth_reason_lead()` (shared with
+		 * the Site Health test); only the shared tail (what stops working
+		 * + the reconnect link) is composed here. The disconnect gate's
 		 * stale-marker rationale lives in `is_operator_disconnected()`.
 		 */
 		if ( is_operator_disconnected() ) {
 			$heading = \__( 'ATmosphere: disconnected', 'atmosphere' );
 			$lead    = \__( 'ATmosphere is disconnected from Bluesky.', 'atmosphere' );
-		} elseif ( Client::REAUTH_REASON_KEY_CHANGED === $reason ) {
-			$lead = \__( 'Your site’s security keys have changed — this can happen after a migration, or when a security plugin rotates them on a schedule — so ATmosphere can no longer read its saved Bluesky login.', 'atmosphere' );
-		} elseif ( Client::REAUTH_REASON_DECRYPT_FAILED === $reason ) {
-			$lead = \__( 'ATmosphere can no longer read its saved Bluesky login.', 'atmosphere' );
 		} else {
-			$lead = \__( 'Your Bluesky session has expired.', 'atmosphere' );
+			$lead = reauth_reason_lead();
 		}
 
 		/* translators: %s: URL to the ATmosphere settings page. */