fix: improve error handling during package updates #633 (#643)

* style: run prettier on changed files

* docs: add info about unavailability during updates #633

* fix: give friendlier error messages during updates #633

Before, access REST API resources resulted in a PHP error traceback which could cause unnecessary concern. This change will allow both endpoints and forms to give a friendlier, more informative notice.

* fix: correctly set http response code for 503s during updates

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Endpoint.inc

@@ -1199,9 +1199,20 @@ class Endpoint {
         $nq_class_name = $this->get_class_shortname();
 
         # Specify the PHP code to write to the Endpoints index.php file
+        $unavailable_error = new ServiceUnavailableError(
+            message: 'This resource is either not installed or is currently updating. Please try again later.',
+            response_id: 'ENDPOINT_UNAVAILABLE',
+        );
+        $unavailable_error_json = json_encode($unavailable_error->to_representation());
         $code =
             "<?php\n" .
-            "require_once('RESTAPI/Endpoints/$nq_class_name.inc');\n" .
+            "\$include = include('RESTAPI/Endpoints/$nq_class_name.inc');\n" .
+            "if (!\$include) {\n" .
+            "    header('Content-Type: application/json');\n" .
+            "    http_response_code(503);\n" .
+            "    echo '$unavailable_error_json';\n" .
+            "    exit(503);\n" .
+            "}\n" .
             "echo (new $fq_class_name())->process_request();\n" .
             "header('Referer: no-referrer');\n" .
             "session_destroy();\n" .

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Form.inc

@@ -529,14 +529,16 @@ class Form {
 
         # Specify the PHP code to write to the Endpoints index.php file
         $code =
-            "<?php
-            require_once('RESTAPI/Forms/" .
-            $nq_class_name .
-            ".inc');
-            require_once('guiconfig.inc');
-            (new " .
-            $fq_class_name .
-            '())->print_form();';
+            "<?php\n" .
+            "require_once('guiconfig.inc');\n" .
+            "\$include = include('RESTAPI/Forms/$nq_class_name.inc');\n" .
+            "if (!\$include) {\n" .
+            "    http_response_code(503);\n" .
+            "    echo '<h1>Service Unavailable</h1>';\n" .
+            "    echo 'This resource is either not installed or is currently updating. Please try again later.';\n" .
+            "    exit();\n" .
+            "}\n" .
+            "(new $fq_class_name())->print_form();\n";
 
         # Assign the absolute path to the file. Assume index.php filename if not specified.
         $filename = "/usr/local/www/$this->url";
@@ -548,7 +550,6 @@ class Form {
         if (is_file($filename)) {
             return true;
         }
-
         return false;
     }
 }

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Forms/SystemRESTAPIUpdatesForm.inc

@@ -31,8 +31,10 @@ class SystemRESTAPIUpdatesForm extends Form {
 
     public function on_save(string $success_banner_msg = ''): void {
         parent::on_save(
-            success_banner_msg: 'The requested version is being installed in the background. Check this page again ' .
-                'later to see the status.',
+            success_banner_msg: 'The requested version is being installed in the background. During the update, the ' .
+                "REST API may be intermittently unavailable. Attempts to access the REST API's endpoints and web " .
+                'pages during the update may result in errors until it completes. Check this page again later to see ' .
+                'the status.',
         );
     }
 }