Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
97.70%
298 / 305
70.00%
7 / 10
 CRAP
0.00%
0 / 1
Restore_Bridge
98.35%
298 / 303
70.00%
7 / 10
 73
0.00%
0 / 1
 register_routes
100.00%
68 / 68
100.00%
1 / 1
 1
 initiate_restore
96.77%
60 / 62
0.00%
0 / 1
 15
 threats_refusal
100.00%
11 / 11
100.00%
1 / 1
 4
 known_threats_available
100.00%
1 / 1
100.00%
1 / 1
 1
 threats_unavailable
100.00%
5 / 5
100.00%
1 / 1
 1
 get_backups_known_threats
97.78%
44 / 45
0.00%
0 / 1
 14
 backup_complete_rewind_id
100.00%
39 / 39
100.00%
1 / 1
 11
 get_known_threats
100.00%
31 / 31
100.00%
1 / 1
 7
 get_restore_status
92.59%
25 / 27
0.00%
0 / 1
 9.03
 project_status
100.00%
14 / 14
100.00%
1 / 1
 10
1<?php
2/**
3 * Restore REST bridge — proxies wpcom/v2 /sites/{site}/rewind/restores.
4 *
5 * @package automattic/jetpack-backup-plugin
6 */
7
8namespace Automattic\Jetpack\Backup\V0005\REST;
9
10use Automattic\Jetpack\Connection\Client;
11use Automattic\Jetpack\Status\Host;
12use WP_Error;
13use WP_REST_Request;
14use WP_REST_Server;
15
16if ( ! defined( 'ABSPATH' ) ) {
17    exit( 0 );
18}
19
20/**
21 * Restore endpoints powering the Restore screen:
22 *   - POST /jetpack/v4/rewind/to/{rewindId}                     → initiate restore
23 *   - GET  /jetpack/v4/rewind/restore/{restoreId}/status        → poll status
24 *   - GET  /jetpack/v4/rewind/backups/{rewindId}/threats        → known threats in a backup
25 */
26class Restore_Bridge {
27
28    /**
29     * Register routes.
30     *
31     * @return void
32     */
33    public static function register_routes() {
34        register_rest_route(
35            'jetpack/v4',
36            '/rewind/to/(?P<rewind_id>[A-Za-z0-9.\-]+)',
37            array(
38                'methods'             => WP_REST_Server::CREATABLE,
39                'callback'            => array( __CLASS__, 'initiate_restore' ),
40                'permission_callback' => array( Rest_Controller::class, 'permission_check' ),
41                'args'                => array(
42                    'rewind_id'           => array(
43                        'type'     => 'string',
44                        'required' => true,
45                    ),
46                    'types'               => array(
47                        'type'                 => 'object',
48                        // See the download bridge: `object` alone accepts a
49                        // JSON list, because WordPress validates it with
50                        // `is_array()`.
51                        'additionalProperties' => array( 'type' => 'boolean' ),
52                    ),
53                    'acknowledge_threats' => array(
54                        'type'    => 'boolean',
55                        'default' => false,
56                    ),
57                ),
58            )
59        );
60
61        register_rest_route(
62            'jetpack/v4',
63            '/rewind/backups/known-threats',
64            array(
65                'methods'             => WP_REST_Server::READABLE,
66                'callback'            => array( __CLASS__, 'get_backups_known_threats' ),
67                'permission_callback' => array( Rest_Controller::class, 'permission_check' ),
68                'args'                => array(
69                    'with_clean_rewind_id' => array(
70                        'type'    => 'boolean',
71                        'default' => false,
72                    ),
73                ),
74            )
75        );
76
77        register_rest_route(
78            'jetpack/v4',
79            '/rewind/backups/(?P<rewind_id>[0-9.]+)/threats',
80            array(
81                'methods'             => WP_REST_Server::READABLE,
82                'callback'            => array( __CLASS__, 'get_known_threats' ),
83                'permission_callback' => array( Rest_Controller::class, 'permission_check' ),
84                'args'                => array(
85                    'rewind_id' => array(
86                        'type'     => 'string',
87                        'required' => true,
88                    ),
89                ),
90            )
91        );
92
93        register_rest_route(
94            'jetpack/v4',
95            '/rewind/restore/(?P<restore_id>\d+)/status',
96            array(
97                'methods'             => WP_REST_Server::READABLE,
98                'callback'            => array( __CLASS__, 'get_restore_status' ),
99                'permission_callback' => array( Rest_Controller::class, 'permission_check' ),
100                'args'                => array(
101                    'restore_id' => array(
102                        'type'     => 'integer',
103                        'required' => true,
104                    ),
105                ),
106            )
107        );
108    }
109
110    /**
111     * Initiate a restore.
112     *
113     * Proxies POST wpcom/v2 /sites/{blog_id}/rewind/restores.
114     *
115     * This route exists because the v1 activity-log endpoint this used to
116     * call could never work from wp-admin: the v1 JSON API discards
117     * Jetpack user tokens by design, so `can_rewind()` evaluated an empty
118     * user and every request came back 401. The permission rule is the
119     * same on both — v1 simply had nobody logged in.
120     *
121     * Signed as the user, and that is not incidental: the guard upstream
122     * is `can_rewind()`, which needs `upload_files` and `delete_users`
123     * for a specific user id, so a bare blog token has no capabilities to
124     * evaluate and is rejected. It is also the right answer on its own
125     * terms — a restore is destructive and the activity log names the
126     * person who started it.
127     *
128     * @param WP_REST_Request $request The REST request.
129     * @return \WP_REST_Response|WP_Error
130     */
131    public static function initiate_restore( WP_REST_Request $request ) {
132        $blog_id = Rest_Controller::get_blog_id_or_error();
133        if ( is_wp_error( $blog_id ) ) {
134            return $blog_id;
135        }
136        $rewind_id = (string) $request->get_param( 'rewind_id' );
137        $types     = $request->get_param( 'types' );
138
139        // A supplied `types` that names nothing is refused rather than
140        // dropped, and this is the screen where that matters most: an
141        // absent `types` means every category upstream, so forwarding an
142        // empty selection as an omission would overwrite the live site
143        // with exactly the parts the caller excluded.
144        //
145        // The v2 route this now calls rejects it too, so there are two
146        // lines of defence — but this is the one that matters, since the
147        // other only fires after the request has left the site.
148        if ( Rest_Controller::request_names_no_types( $request ) ) {
149            return new WP_Error(
150                'no_types_selected',
151                __( 'Select at least one item to restore.', 'jetpack-backup-pkg' ),
152                array( 'status' => 400 )
153            );
154        }
155
156        // The rewind id travels in the body, in full. The decimal suffix is
157        // significant — it is passed straight to VaultPress as the backup's
158        // timestamp, and truncating it addresses a different backup than
159        // the reader picked. (`toIntRewindId` belongs to the file-browser
160        // URL family only, whose route regex really is `\d+`.)
161        $request_body = array(
162            'rewindId'     => $rewind_id,
163            // Optional upstream, and it now defaults to false — but both
164            // this dashboard and Calypso have always sent true, so omitting
165            // it would be a silent behaviour change for existing callers.
166            'force_rewind' => true,
167        );
168
169        // Absent when the caller named no categories at all, which is how
170        // a whole-site restore is spelled upstream. Rebuilt as a named map
171        // otherwise — the same contract the download bridge follows.
172        $named_types = Rest_Controller::named_types( $types );
173        if ( ! empty( $named_types ) ) {
174            $request_body['types'] = $named_types;
175        }
176
177        // WordPress.com skips the known-threats check for signed restores that omit the flag,
178        // so only sites that can show the warning send it.
179        if ( self::known_threats_available() ) {
180            $request_body['acknowledge_threats'] = true === rest_sanitize_boolean( $request->get_param( 'acknowledge_threats' ) );
181        }
182
183        $response = Client::wpcom_json_api_request_as_user(
184            sprintf( '/sites/%d/rewind/restores', $blog_id ),
185            'v2',
186            array( 'method' => 'POST' ),
187            $request_body,
188            'wpcom'
189        );
190
191        if ( is_wp_error( $response ) ) {
192            return Rest_Controller::transport_error( $response, 'restore_initiate_failed' );
193        }
194
195        // Cast because `wp_remote_retrieve_response_code()` hands back
196        // whatever the transport put there, and a numeric string fails the
197        // strict comparison below. On this route that is the worst place to
198        // get it wrong: a restore WordPress.com accepted would be reported
199        // as a failure, and the reader would start a second one. The long
200        // version is on `Rest_Controller::upstream_error()`.
201        $status_code = (int) wp_remote_retrieve_response_code( $response );
202        if ( 409 === $status_code ) {
203            $refusal = self::threats_refusal( $response );
204            if ( null !== $refusal ) {
205                return $refusal;
206            }
207        }
208        if ( 200 !== $status_code ) {
209            return Rest_Controller::upstream_error(
210                $response,
211                'restore_initiate_failed',
212                __( 'Could not start the backup restore.', 'jetpack-backup-pkg' )
213            );
214        }
215
216        $decoded = json_decode( wp_remote_retrieve_body( $response ), true );
217        if ( ! is_array( $decoded ) ) {
218            $decoded = array();
219        }
220
221        // `ok` is the success signal, not the presence of an id.
222        //
223        // VaultPress does not reliably echo a restore id back — the
224        // underlying call's documented response is only `{ ok, error }` —
225        // so `restore_id: null` means "queued, id not known yet", which is
226        // a perfectly good outcome. Reading the id as the signal reported
227        // a successfully queued restore as a 500, and could not have
228        // distinguished the two cases anyway: `(int) null` and `(int) 0`
229        // are both `0`.
230        if ( empty( $decoded['ok'] ) ) {
231            $data = array( 'status' => 500 );
232
233            // The `error` beside it is the whole of what went wrong —
234            // "There is already a restore in progress" and its like — and
235            // it was being dropped on the floor, leaving a reader who
236            // cannot start a second restore with no way to learn why.
237            //
238            // It arrives as prose with no machine code beside it, which is
239            // why `upstream_reason()` sorts on shape rather than on which
240            // key a value came from. The v2 route usually turns this
241            // answer into a 500 `rewind_error` before it ever reaches us,
242            // so what this branch catches is the shape upstream does not.
243            $reason = Rest_Controller::upstream_reason( $decoded );
244            if ( ! empty( $reason ) ) {
245                $data['wpcom'] = $reason;
246            }
247
248            return new WP_Error(
249                'restore_initiate_failed',
250                __( 'Could not start the backup restore.', 'jetpack-backup-pkg' ),
251                $data
252            );
253        }
254
255        $restore_id_in = isset( $decoded['restore_id'] ) && null !== $decoded['restore_id']
256            ? (int) $decoded['restore_id']
257            : null;
258
259        return rest_ensure_response(
260            array(
261                // Null is meaningful here and the client branches on it:
262                // the restore is running, and its id has to be recovered
263                // from the restores collection before progress can be
264                // polled.
265                'id'        => $restore_id_in,
266                'rewind_id' => isset( $decoded['rewind_id'] ) ? (string) $decoded['rewind_id'] : $rewind_id,
267            )
268        );
269    }
270
271    /**
272     * The refusal WordPress.com sends for a backup with unacknowledged known threats, or null for any other 409.
273     *
274     * @param array $response The wp_remote_* response.
275     * @return WP_Error|null
276     */
277    private static function threats_refusal( $response ) {
278        $body = json_decode( wp_remote_retrieve_body( $response ), true );
279        if ( ! is_array( $body ) || 'threats_not_acknowledged' !== ( $body['code'] ?? null ) ) {
280            return null;
281        }
282
283        $data = array( 'status' => 409 );
284        if ( isset( $body['data']['known_threats'] ) ) {
285            $data['known_threats'] = $body['data']['known_threats'];
286        }
287
288        return new WP_Error(
289            'threats_not_acknowledged',
290            __( 'This backup is known to contain security threats. Acknowledge them to restore it.', 'jetpack-backup-pkg' ),
291            $data
292        );
293    }
294
295    /**
296     * Whether this site checks backups for known threats. Only WoA sites do, for now.
297     *
298     * @return bool
299     */
300    public static function known_threats_available() {
301        return ( new Host() )->is_woa_site();
302    }
303
304    /**
305     * The answer for a site whose known threats can't be read, so the screen restores as before.
306     *
307     * @return WP_Error
308     */
309    private static function threats_unavailable() {
310        return new WP_Error(
311            'threats_unavailable',
312            __( 'Known threats are not available for this site.', 'jetpack-backup-pkg' ),
313            array( 'status' => 404 )
314        );
315    }
316
317    /**
318     * Known Scan threat counts for the newest 100 backups, by backup period, and the newest
319     * backup without known threats. Proxies GET wpcom/v3 /sites/{blog_id}/rewind/backups.
320     *
321     * Without Scan, or off WoA, the answer is `threats_unavailable` and the dashboard shows no badges.
322     *
323     * @param WP_REST_Request $request The REST request; `with_clean_rewind_id` also finds when the clean backup finished.
324     * @return \WP_REST_Response|WP_Error
325     */
326    public static function get_backups_known_threats( WP_REST_Request $request ) {
327        if ( ! self::known_threats_available() ) {
328            return self::threats_unavailable();
329        }
330
331        $blog_id = Rest_Controller::get_blog_id_or_error();
332        if ( is_wp_error( $blog_id ) ) {
333            return $blog_id;
334        }
335
336        $response = Client::wpcom_json_api_request_as_user(
337            sprintf( '/sites/%d/rewind/backups?number=100&page=1&known_threats_only=true', $blog_id ),
338            '3',
339            array(),
340            null,
341            'wpcom'
342        );
343
344        if ( is_wp_error( $response ) ) {
345            return Rest_Controller::transport_error( $response, 'known_threats_fetch_failed' );
346        }
347
348        $status_code = (int) wp_remote_retrieve_response_code( $response );
349        if ( 403 === $status_code ) {
350            return self::threats_unavailable();
351        }
352        $body = json_decode( wp_remote_retrieve_body( $response ), true );
353        if ( 200 !== $status_code || ! is_array( $body ) ) {
354            return Rest_Controller::upstream_error(
355                $response,
356                'known_threats_fetch_failed',
357                __( 'Could not fetch the known threats for this backup.', 'jetpack-backup-pkg' )
358            );
359        }
360
361        $backups = array();
362        foreach ( (array) ( $body['backups'] ?? array() ) as $backup ) {
363            if ( ! isset( $backup['object']['backup_period'] ) || ! is_numeric( $backup['object']['backup_period'] ) ) {
364                continue;
365            }
366            $known_threats = $backup['object']['known_threats'] ?? null;
367            $backups[]     = array(
368                'period'        => (int) $backup['object']['backup_period'],
369                'known_threats' => is_array( $known_threats ) ? $known_threats : null,
370            );
371        }
372
373        $latest_clean = $body['latest_without_known_threats'] ?? null;
374        $latest_clean = is_numeric( $latest_clean ) ? (int) $latest_clean : null;
375
376        $latest_clean_rewind_id = null;
377        if ( null !== $latest_clean && true === rest_sanitize_boolean( $request->get_param( 'with_clean_rewind_id' ) ) ) {
378            $latest_clean_rewind_id = self::backup_complete_rewind_id( $blog_id, $latest_clean, array_column( $backups, 'period' ) );
379        }
380
381        return rest_ensure_response(
382            array(
383                'backups'                                => $backups,
384                'latest_without_known_threats'           => $latest_clean,
385                'latest_without_known_threats_rewind_id' => $latest_clean_rewind_id,
386            )
387        );
388    }
389
390    /**
391     * The rewind id of a backup's "Backup complete" Activity Log entry: when it finished, the time
392     * the backup lists show. A backup's period is when it started.
393     *
394     * @param int   $blog_id The site's WordPress.com blog id.
395     * @param int   $period  The backup period.
396     * @param int[] $periods The other known backup periods; the next one bounds the search.
397     * @return string|null The rewind id, or null when it can't be found.
398     */
399    private static function backup_complete_rewind_id( $blog_id, $period, array $periods ) {
400        // A finished backup's entry never changes; "not found yet" is kept only briefly.
401        $cache_key = sprintf( 'jetpack_backup_complete_rewind_id_%d_%d', $blog_id, $period );
402        $cached    = get_transient( $cache_key );
403        if ( is_string( $cached ) ) {
404            return '' === $cached ? null : $cached;
405        }
406
407        $next = DAY_IN_SECONDS + $period;
408        foreach ( $periods as $candidate ) {
409            if ( $candidate > $period && $candidate < $next ) {
410                $next = $candidate;
411            }
412        }
413
414        $query = http_build_query(
415            array(
416                'name'       => array(
417                    'rewind__backup_complete_full',
418                    'rewind__backup_complete_initial',
419                    'rewind__backup_only_complete_full',
420                    'rewind__backup_only_complete_initial',
421                ),
422                'after'      => gmdate( 'c', $period ),
423                'before'     => gmdate( 'c', $next ),
424                'sort_order' => 'asc',
425                'number'     => 10,
426            )
427        );
428
429        $response = Client::wpcom_json_api_request_as_user(
430            sprintf( '/sites/%d/activity/rewindable?%s', $blog_id, $query ),
431            'v2',
432            array(),
433            null,
434            'wpcom'
435        );
436        if ( is_wp_error( $response ) || 200 !== (int) wp_remote_retrieve_response_code( $response ) ) {
437            return null;
438        }
439
440        $body = json_decode( wp_remote_retrieve_body( $response ), true );
441        foreach ( (array) ( $body['current']['orderedItems'] ?? array() ) as $item ) {
442            $rewind_id = $item['rewind_id'] ?? null;
443            if ( is_numeric( $rewind_id ) && (int) floor( (float) $rewind_id ) >= $period ) {
444                set_transient( $cache_key, (string) $rewind_id, MONTH_IN_SECONDS );
445                return (string) $rewind_id;
446            }
447        }
448        set_transient( $cache_key, '', 5 * MINUTE_IN_SECONDS );
449        return null;
450    }
451
452    /**
453     * Known Scan threats in a backup. Proxies GET wpcom/v2 /sites/{blog_id}/rewind/backups/{rewind_id}/threats.
454     *
455     * Without Scan (a 403 upstream), or off WoA, the answer is a 404 `threats_unavailable`.
456     *
457     * @param WP_REST_Request $request The REST request.
458     * @return \WP_REST_Response|WP_Error
459     */
460    public static function get_known_threats( WP_REST_Request $request ) {
461        if ( ! self::known_threats_available() ) {
462            return self::threats_unavailable();
463        }
464
465        $blog_id = Rest_Controller::get_blog_id_or_error();
466        if ( is_wp_error( $blog_id ) ) {
467            return $blog_id;
468        }
469
470        $response = Client::wpcom_json_api_request_as_user(
471            sprintf( '/sites/%d/rewind/backups/%s/threats', $blog_id, rawurlencode( (string) $request->get_param( 'rewind_id' ) ) ),
472            'v2',
473            array(),
474            null,
475            'wpcom'
476        );
477
478        if ( is_wp_error( $response ) ) {
479            return Rest_Controller::transport_error( $response, 'known_threats_fetch_failed' );
480        }
481
482        $status_code = (int) wp_remote_retrieve_response_code( $response );
483        if ( 403 === $status_code ) {
484            return self::threats_unavailable();
485        }
486        if ( 200 !== $status_code ) {
487            return Rest_Controller::upstream_error(
488                $response,
489                'known_threats_fetch_failed',
490                __( 'Could not fetch the known threats for this backup.', 'jetpack-backup-pkg' )
491            );
492        }
493
494        $body = json_decode( wp_remote_retrieve_body( $response ), true );
495        if ( ! is_array( $body ) ) {
496            return new WP_Error(
497                'known_threats_fetch_failed',
498                __( 'Could not fetch the known threats for this backup.', 'jetpack-backup-pkg' ),
499                array( 'status' => 502 )
500            );
501        }
502
503        return rest_ensure_response( $body );
504    }
505
506    /**
507     * WPCOM's restore statuses, mapped to the vocabulary the client uses.
508     *
509     * Two engines write this field and the v2 route serves whichever ran:
510     * a Rewind restore — which is every restore this package starts —
511     * reports `queued | running | finished | fail`, a legacy VaultPress one
512     * `success | success-with-errors | aborted`.
513     *
514     * The Rewind half comes from Calypso's typed contract for this same
515     * endpoint, not from the v1 endpoint's docblock: that list omits
516     * `finished`, so every successful restore once reported `unknown`.
517     *
518     * Mapped here rather than in the client for the same reason the
519     * download bridge derives its own status: the wire vocabulary is
520     * WPCOM's to change, and one place to change it is better than three
521     * string comparisons scattered through a state machine.
522     *
523     * `success-with-errors` is deliberately kept distinct instead of being
524     * folded into either neighbour. A restore that completed but not
525     * cleanly is neither a success the reader should walk away from nor a
526     * failure they should retry blindly.
527     *
528     * @var array<string, string>
529     */
530    private const STATUS_MAP = array(
531        'queued'              => 'queued',
532        'running'             => 'running',
533        'finished'            => 'finished',
534        'fail'                => 'failed',
535        'success'             => 'finished',
536        'success-with-errors' => 'finished-with-errors',
537        'aborted'             => 'aborted',
538    );
539
540    /**
541     * Poll restore status.
542     *
543     * Proxies GET wpcom/v2 /sites/{blog_id}/rewind/restores/{restore_id}.
544     *
545     * Signed `as_blog`, unlike its sibling. Starting a restore is
546     * user-attributed and needs a user token; *watching* one does not —
547     * this route falls through to `is_jetpack_authorized_for_site()`, the
548     * same check the already-registered `GET /jetpack/v4/restores` relies
549     * on. That is a real capability gain rather than a shortcut: progress
550     * now survives the initiating user's session and is visible to any
551     * admin, which is exactly the failure mode where someone closes the
552     * tab mid-restore and can never see the outcome again.
553     *
554     * @param WP_REST_Request $request The REST request.
555     * @return \WP_REST_Response|WP_Error
556     */
557    public static function get_restore_status( WP_REST_Request $request ) {
558        $blog_id = Rest_Controller::get_blog_id_or_error();
559        if ( is_wp_error( $blog_id ) ) {
560            return $blog_id;
561        }
562        $restore_id = (int) $request->get_param( 'restore_id' );
563
564        $response = Client::wpcom_json_api_request_as_blog(
565            sprintf( '/sites/%d/rewind/restores/%d', $blog_id, $restore_id ),
566            'v2',
567            array(),
568            null,
569            'wpcom'
570        );
571
572        if ( is_wp_error( $response ) ) {
573            return Rest_Controller::transport_error( $response, 'restore_status_fetch_failed' );
574        }
575
576        // Cast, as in `initiate_restore()`. Both branches below depend on
577        // it: an uncast `'404'` would miss the queued-restore carve-out as
578        // well as the success test, so the ordinary opening seconds of a
579        // restore would surface as an error.
580        $status_code = (int) wp_remote_retrieve_response_code( $response );
581
582        // A 404 is the normal first answer, not a failure. A restore that
583        // has just been queued is not visible to this route yet, and the
584        // id may not even exist on our side (see `initiate_restore`, where
585        // VaultPress can decline to echo one). Reporting it as an error
586        // would turn the ordinary opening seconds of every restore into a
587        // user-visible failure.
588        //
589        // Reported as `not-found` and never as `queued`, which upstream
590        // also returns: the client reads the two the same way on screen
591        // but must not treat "no record of it" as a sign of life.
592        //
593        // Safe to treat softly only because the upstream route now
594        // answers 502 for an unparseable VaultPress reply — before that, a
595        // 404 could quietly have meant "upstream is down".
596        if ( 404 === $status_code ) {
597            return rest_ensure_response( self::project_status( array(), $restore_id, 'not-found' ) );
598        }
599
600        if ( 200 !== $status_code ) {
601            return Rest_Controller::upstream_error(
602                $response,
603                'restore_status_fetch_failed',
604                __( 'Could not fetch restore progress.', 'jetpack-backup-pkg' )
605            );
606        }
607
608        $body = json_decode( wp_remote_retrieve_body( $response ), true );
609        // The v2 payload is flat. The old nested `restore_status` unwrap is
610        // kept because it is what makes the flat shape work too — the
611        // fallback branch is the live path now, not the defensive one.
612        $status = is_array( $body ) && isset( $body['restore_status'] ) && is_array( $body['restore_status'] )
613            ? $body['restore_status']
614            : ( is_array( $body ) ? $body : array() );
615
616        return rest_ensure_response( self::project_status( $status, $restore_id ) );
617    }
618
619    /**
620     * Shape a restore-status payload for the client.
621     *
622     * @param array       $status   Upstream status fields, possibly empty.
623     * @param int         $fallback Restore id to report when upstream names none.
624     * @param string|null $force    Status to report regardless of the payload.
625     * @return array
626     */
627    private static function project_status( array $status, $fallback, $force = null ) {
628        $raw = isset( $status['status'] ) ? (string) $status['status'] : '';
629
630        if ( null !== $force ) {
631            $mapped = $force;
632        } elseif ( '' === $raw ) {
633            // A record that arrived without a status is queued and has not
634            // started reporting. An empty payload is not a record, and
635            // calling it `queued` would claim upstream is holding a
636            // restore it never mentioned — enough to refuse the reader a
637            // new one. Tested on emptiness rather than on one key, so a
638            // record spelled with fields we do not read still counts.
639            $mapped = empty( $status ) ? 'not-found' : 'queued';
640        } else {
641            // Anything unrecognised is reported as such rather than
642            // guessed at. The client keeps polling through `unknown` under
643            // a bounded cap, so a status WPCOM adds later degrades into a
644            // slower answer instead of a frozen progress bar.
645            $mapped = self::STATUS_MAP[ $raw ] ?? 'unknown';
646        }
647
648        return array(
649            'id'         => isset( $status['restore_id'] ) ? (int) $status['restore_id'] : (int) $fallback,
650            'status'     => $mapped,
651            'progress'   => isset( $status['percent'] ) ? (float) $status['percent'] : 0,
652            'rewind_id'  => isset( $status['rewind_id'] ) ? (string) $status['rewind_id'] : '',
653            'error_code' => isset( $status['error_code'] ) ? (string) $status['error_code'] : '',
654            'message'    => isset( $status['message'] ) ? (string) $status['message'] : '',
655        );
656    }
657}