feat: read available pfsense upgrades

pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc

@@ -0,0 +1,27 @@
+<?php
+//   Copyright 2022 Jared Hendrickson
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//       http://www.apache.org/licenses/LICENSE-2.0
+//
+//   Unless required by applicable law or agreed to in writing, software
+//   distributed under the License is distributed on an "AS IS" BASIS,
+//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//   See the License for the specific language governing permissions and
+//   limitations under the License.
+
+require_once("api/framework/APIEndpoint.inc");
+
+class APISystemVersionUpgrade extends APIEndpoint {
+    public function __construct() {
+        $this->url = "/api/v1/system/version/upgrade";
+        $this->query_excludes = ["use_cache"];
+    }
+
+    protected function get() {
+        return (new APISystemVersionUpgradeRead())->call();
+    }
+}

pfSense-pkg-API/files/etc/inc/api/framework/APIResponse.inc

@@ -77,7 +77,7 @@ function get($id, $data=[], $all=false) {
             "status" => "forbidden",
             "code" => 403,
             "return" => $id,
-            "message" => "Authentication mode must be set to JWT to enable access token authentication",
+            "message" => "Authentication mode must be set to JWT ot API Token to enable access token authentication",
         ],
         10 => [
             "status" => "server error",

pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionRead.inc

@@ -21,8 +21,9 @@ class APISystemVersionRead extends APIModel {
     # Create our method constructor
     public function __construct() {
         parent::__construct();
-        $this->privileges = ["page-all", "page-dashboard-widgets", "page-diagnostics-command"];
-    }
+        $this->privileges = [
+            "page-all", "page-dashboard-widgets", "page-diagnostics-command", "page-system-update-settings"
+        ];    }
 
     public function action() {
         return APIResponse\get(0, APITools\get_pfsense_version());

pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionUpgradeRead.inc

@@ -0,0 +1,45 @@
+<?php
+//   Copyright 2022 Jared Hendrickson
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//       http://www.apache.org/licenses/LICENSE-2.0
+//
+//   Unless required by applicable law or agreed to in writing, software
+//   distributed under the License is distributed on an "AS IS" BASIS,
+//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//   See the License for the specific language governing permissions and
+//   limitations under the License.
+
+require_once("api/framework/APIModel.inc");
+require_once("api/framework/APIResponse.inc");
+
+
+class APISystemVersionUpgradeRead extends APIModel {
+    # Create our method constructor
+    public function __construct() {
+        parent::__construct();
+        $this->privileges = [
+            "page-all", "page-dashboard-widgets", "page-diagnostics-command", "page-system-update-settings"
+        ];
+    }
+
+    public function action() {
+        return APIResponse\get(0, get_system_pkg_version(false, $this->validated_data["use_cache"]));
+    }
+
+    public function validate_payload() {
+        $this->__validate_use_cache();
+    }
+
+    private function __validate_use_cache() {
+        # Check for the optional 'use_cache' field
+        if ($this->initial_data["use_cache"] === false) {
+            $this->validated_data["use_cache"] = false;
+        } else {
+            $this->validated_data["use_cache"] = true;
+        }
+    }
+}

pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml

@@ -13223,7 +13223,7 @@ paths:
         version, buildtime, and last commit.<br><br>
 
         _Requires at least one of the following privileges:_ [`page-all`, `page-dashboard-widgets`,
-        `page-diagnostics-command`]'
+        `page-diagnostics-command`, `page-system-update-settings`]'
       responses:
         "200":
           $ref: '#/components/responses/Success'
@@ -13232,6 +13232,29 @@ paths:
       summary: Read system version
       tags:
         - System > Version
+  /api/v1/system/version/upgrade:
+    get:
+      operationId: APISystemVersionUpgradeRead
+      description: 'Checks if there is a pfSense upgrade available but does not apply upgrades.<br><br>
+
+        _Requires at least one of the following privileges:_ [`page-all`, `page-dashboard-widgets`, 
+        `page-diagnostics-command`, `page-system-update-settings`]'
+      parameters:
+        - description: Use cached upgrade information. This will speed up the response but may reference slightly 
+            outdated data. pfSense updates this cache automatically at scheduled intervals.
+          in: query
+          name: use_cache
+          schema:
+            type: boolean
+            default: true
+      responses:
+        "200":
+          $ref: '#/components/responses/Success'
+        "401":
+          $ref: '#/components/responses/AuthenticationFailed'
+      summary: Check for system version upgrades
+      tags:
+        - System > Version
   /api/v1/user:
     delete:
       operationId: APIUserDelete

tests/test_api_v1_system_version_upgrade.py

@@ -0,0 +1,24 @@
+"""Script used to test the /api/v1/system/version/upgrade endpoint."""
+import e2e_test_framework
+
+
+class APIE2ETestSystemVersion(e2e_test_framework.APIE2ETest):
+    """Class used to test the /api/v1/system/version/upgrade endpoint."""
+    uri = "/api/v1/system/version/upgrade"
+    get_tests = [
+        {
+            "name": "Read available pfSense upgrades"
+        },
+        {
+            "name": "Read available pfSense upgrades using cache",
+            "payload": {"use_cache": True}
+        },
+        {
+            "name": "Read available pfSense upgrades without cache",
+            "payload": {"use_cache": False},
+            "resp_time": 20
+        }
+    ]
+
+
+APIE2ETestSystemVersion()