Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
50.00%
35 / 70
40.00%
2 / 5
 CRAP
0.00%
0 / 1
External_Storage
49.28%
34 / 69
40.00%
2 / 5
 205.15
0.00%
0 / 1
 register_provider
100.00%
2 / 2
100.00%
1 / 1
 1
 get_value
62.50%
10 / 16
0.00%
0 / 1
 13.27
 log_event
0.00%
0 / 28
0.00%
0 / 1
 240
 should_report_empty_state
100.00%
14 / 14
100.00%
1 / 1
 8
 should_log_event
88.89%
8 / 9
0.00%
0 / 1
 3.01
1<?php
2/**
3 * External Storage utilities for Jetpack Connection.
4 *
5 * Provides centralized logic for external storage implementations
6 * across different environments (WoA, VIP, other).
7 *
8 * Usage Example:
9 *
10 *     // 1. Create a storage provider class implementing the interface:
11 *     class My_Storage_Provider implements Storage_Provider_Interface {
12 *         public function is_available() { return true; }
13 *         public function should_handle( $option_name ) {
14 *             return in_array( $option_name, array( 'blog_token', 'id' ), true );
15 *         }
16 *         public function get( $option_name ) {
17 *             // Return value from your external storage or null
18 *         }
19 *         public function get_environment_id() { return 'my_env'; }
20 *     }
21 *
22 *     // 2. Register the provider:
23 *     if ( class_exists( 'Automattic\Jetpack\Connection\External_Storage' ) ) {
24 *         \Automattic\Jetpack\Connection\External_Storage::register_provider( new My_Storage_Provider() );
25 *     }
26 *
27 *     // 3. External storage is now automatically used by Jetpack_Options::get_option()
28 *
29 * @package automattic/jetpack-connection
30 */
31
32namespace Automattic\Jetpack\Connection;
33
34require_once __DIR__ . '/interface-storage-provider.php';
35
36/**
37 * External Storage utilities class.
38 *
39 * @since 6.18.0
40 */
41class External_Storage {
42
43    /**
44     * Registered storage provider.
45     *
46     * @since 6.18.0
47     *
48     * @var Storage_Provider_Interface|null
49     */
50    private static $provider = null;
51
52    /**
53     * Static cache to prevent logging same event multiple times in single request.
54     *
55     * @since 7.0.0
56     *
57     * @var array
58     */
59    private static $logged_events = array();
60
61    /**
62     * Maximum delay threshold for empty state reporting (in seconds).
63     * This also determines the transient expiry for tracking first empty state.
64     * Provider custom thresholds must not exceed this value.
65     *
66     * @since 7.0.0
67     */
68    private const EMPTY_STATE_TRANSIENT_EXPIRY = 15 * MINUTE_IN_SECONDS;
69
70    /**
71     * Register a storage provider for external storage.
72     *
73     * @since 6.18.0
74     *
75     * @param Storage_Provider_Interface $provider Storage provider implementing the interface.
76     * @return bool True if provider was registered successfully, false otherwise.
77     */
78    public static function register_provider( Storage_Provider_Interface $provider ) {
79        self::$provider = $provider;
80        return true;
81    }
82
83    /**
84     * Get value from external storage provider.
85     *
86     * Returns null if no provider is registered or if the provider can't provide the value (triggers database fallback).
87     *
88     * @since 6.18.0
89     *
90     * @param string $key The key to retrieve.
91     * @return mixed The value from external storage, or null for database fallback.
92     */
93    public static function get_value( $key ) {
94        $provider = self::$provider;
95
96        // Check if we have a registered provider
97        if ( null === $provider ) {
98            return null; // No provider registered, use database
99        }
100
101        $environment = $provider->get_environment_id();
102
103        // Check if provider is available in current environment
104        if ( ! $provider->is_available() ) {
105            self::log_event( 'unavailable', $key, 'External storage not available', $environment );
106            return null;
107        }
108
109        // Check if provider should handle this option
110        if ( ! $provider->should_handle( $key ) ) {
111            return null;
112        }
113
114        // Try to get value from the provider
115        try {
116            $value = $provider->get( $key );
117
118            // Check if we got a valid value
119            if ( null !== $value && false !== $value && '' !== $value && 0 !== $value ) {
120                return $value;
121            }
122
123            // Empty value - log it
124            self::log_event( 'empty', $key, '', $environment );
125
126        } catch ( \Exception $e ) {
127            // Provider threw an exception
128            self::log_event( 'error', $key, $e->getMessage(), $environment );
129        }
130
131        // Provider couldn't provide value, return null for database fallback
132        return null;
133    }
134
135    /**
136     * Log events if WP_DEBUG is enabled and delegate to provider for error reporting.
137     * Includes rate limiting to prevent log spam from noisy events.
138     *
139     * Storage providers can optionally implement handle_error_event() method to receive
140     * notifications about storage errors and empty states for their own error reporting.
141     *
142     * @since 6.18.0
143     *
144     * @param string $event_type  The event type (error, empty, unavailable).
145     * @param string $key         The key that triggered the event.
146     * @param string $details     Additional details about the event.
147     * @param string $environment The environment identifier (atomic, vip, etc.).
148     */
149    public static function log_event( $event_type, $key, $details = '', $environment = 'unknown' ) {
150        // Only process 'error' and 'empty' events for provider error reporting
151        if ( 'error' !== $event_type && 'empty' !== $event_type ) {
152            // For non-reportable events, just do debug logging with rate limiting
153            if ( self::should_log_event( $key, $event_type ) && defined( 'WP_DEBUG' ) && WP_DEBUG ) {
154                error_log( // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
155                    sprintf(
156                        'Jetpack External Storage %s: %s in %s%s',
157                        $event_type,
158                        $key,
159                        $environment,
160                        $details ? ' - ' . $details : ''
161                    )
162                );
163            }
164            return;
165        }
166
167        // For 'empty' events, check delay mechanism first to avoid false positives
168        // during sync between external storage and the database.
169        // This is checked BEFORE rate limiting so we don't block legitimate reports.
170        if ( 'empty' === $event_type && ! self::should_report_empty_state( $key ) ) {
171            return;
172        }
173
174        // Apply rate limiting only for events that will trigger provider notification
175        if ( ! self::should_log_event( $key, $event_type ) ) {
176            return;
177        }
178
179        // Local debug logging (only when WP_DEBUG is enabled)
180        if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
181            error_log( // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
182                sprintf(
183                    'Jetpack External Storage %s: %s in %s%s',
184                    $event_type,
185                    $key,
186                    $environment,
187                    $details ? ' - ' . $details : ''
188                )
189            );
190        }
191
192        // Delegate to provider if it implements error handling
193        if ( null !== self::$provider && method_exists( self::$provider, 'handle_error_event' ) ) {
194            // @phan-suppress-next-line PhanUndeclaredMethod -- Optional method, checked via method_exists()
195            self::$provider->handle_error_event( $event_type, $key, $details, $environment );
196        }
197    }
198
199    /**
200     * Determine if we should report an empty state based on delay mechanism.
201     *
202     * This prevents false positives during storage sync delays. On first encounter
203     * of empty state, sets a transient. On subsequent encounters after the delay
204     * threshold, allows reporting (indicating likely disconnection, not sync delay).
205     *
206     * Providers can customize the delay threshold by implementing get_empty_state_delay_threshold().
207     *
208     * @since 6.18.0
209     *
210     * @param string $key The key that was empty.
211     * @return bool True if we should report this empty state, false otherwise.
212     */
213    private static function should_report_empty_state( $key ) {
214        $delay_key        = 'jetpack_external_storage_empty_delay_' . $key;
215        $first_empty_time = get_transient( $delay_key );
216
217        if ( false === $first_empty_time ) {
218            // First time encountering empty state - set delay transient and don't report yet
219            set_transient( $delay_key, time(), self::EMPTY_STATE_TRANSIENT_EXPIRY );
220            return false;
221        }
222
223        // Default delay threshold (5 minutes)
224        $delay_threshold = 5 * MINUTE_IN_SECONDS;
225
226        // Allow provider to customize delay threshold
227        // A threshold of 0 is valid for providers where external storage is written first
228        if ( null !== self::$provider && method_exists( self::$provider, 'get_empty_state_delay_threshold' ) ) {
229            // @phan-suppress-next-line PhanUndeclaredMethod -- Optional method, checked via method_exists()
230            $custom_threshold = self::$provider->get_empty_state_delay_threshold();
231            if ( is_int( $custom_threshold ) && $custom_threshold >= 0 && $custom_threshold <= self::EMPTY_STATE_TRANSIENT_EXPIRY ) {
232                $delay_threshold = $custom_threshold;
233            }
234        }
235
236        if ( ( time() - $first_empty_time ) >= $delay_threshold ) {
237            // Delay threshold passed - likely disconnection, report it
238            delete_transient( $delay_key );
239            return true;
240        }
241
242        return false;
243    }
244
245    /**
246     * Determine if an event should be logged based on rate limiting rules.
247     *
248     * This prevents log spam from noisy events by applying a simple one-hour
249     * rate limit per key and event type combination. Also uses a static cache
250     * to prevent duplicate logs within the same request.
251     *
252     * @since 6.18.0
253     *
254     * @param string $key        The key that triggered the event.
255     * @param string $event_type The event type (error, empty, unavailable).
256     * @return bool True if the event should be logged, false if rate limited.
257     */
258    private static function should_log_event( $key, $event_type = '' ) {
259        // Combine event type and key for unique tracking
260        $event_cache_key = $event_type . '_' . $key;
261
262        // Check static cache first (prevents multiple logs in same request)
263        if ( isset( self::$logged_events[ $event_cache_key ] ) ) {
264            return false;
265        }
266
267        $rate_limit_key = 'jetpack_ext_storage_rate_limit_' . $event_cache_key;
268
269        // Check if we're still within the rate limit period
270        if ( get_transient( $rate_limit_key ) ) {
271            return false;
272        }
273
274        // Mark as logged in both caches
275        self::$logged_events[ $event_cache_key ] = true;
276        set_transient( $rate_limit_key, true, HOUR_IN_SECONDS );
277
278        return true;
279    }
280}