From 309f541ae21e4bd7e94c1d63778548c6c8a7e27d Mon Sep 17 00:00:00 2001 From: Jared Hendrickson Date: Sat, 8 Oct 2022 10:45:16 -0600 Subject: [PATCH 1/4] feat: added /api/v1/system/version/upgrade this endpoint allows clients to check for available pfsense upgrades but does not apply them. --- .../api/endpoints/APISystemVersionUpgrade.inc | 26 +++++++++++ .../etc/inc/api/framework/APIResponse.inc | 2 +- .../inc/api/models/APISystemVersionRead.inc | 5 ++- .../models/APISystemVersionUpgradeRead.inc | 45 +++++++++++++++++++ .../local/www/api/documentation/openapi.yml | 23 ++++++++++ tests/test_api_v1_system_version_upgrade.py | 11 +++++ 6 files changed, 109 insertions(+), 3 deletions(-) create mode 100644 pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc create mode 100644 pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionUpgradeRead.inc create mode 100644 tests/test_api_v1_system_version_upgrade.py diff --git a/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc b/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc new file mode 100644 index 000000000..eec631fab --- /dev/null +++ b/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc @@ -0,0 +1,26 @@ +url = "/api/v1/system/version/upgrade"; + } + + protected function get() { + return (new APISystemVersionUpgradeRead())->call(); + } +} diff --git a/pfSense-pkg-API/files/etc/inc/api/framework/APIResponse.inc b/pfSense-pkg-API/files/etc/inc/api/framework/APIResponse.inc index 91b349ffe..918cad757 100644 --- a/pfSense-pkg-API/files/etc/inc/api/framework/APIResponse.inc +++ b/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", diff --git a/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionRead.inc b/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionRead.inc index 906731c39..02fc3e19f 100644 --- a/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionRead.inc +++ b/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()); diff --git a/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionUpgradeRead.inc b/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionUpgradeRead.inc new file mode 100644 index 000000000..c8f916e60 --- /dev/null +++ b/pfSense-pkg-API/files/etc/inc/api/models/APISystemVersionUpgradeRead.inc @@ -0,0 +1,45 @@ +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; + } + } +} diff --git a/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml b/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml index 5d4e23d54..90fa67423 100644 --- a/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml +++ b/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml @@ -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.

+ + _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 diff --git a/tests/test_api_v1_system_version_upgrade.py b/tests/test_api_v1_system_version_upgrade.py new file mode 100644 index 000000000..92b724237 --- /dev/null +++ b/tests/test_api_v1_system_version_upgrade.py @@ -0,0 +1,11 @@ +"""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"}] + + +APIE2ETestSystemVersion() From 22c8ff3e8b23f1d529c9925db63703bc876cc1fe Mon Sep 17 00:00:00 2001 From: Jared Hendrickson Date: Sat, 8 Oct 2022 10:54:17 -0600 Subject: [PATCH 2/4] fix: add use_cache to query excludes --- .../files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc b/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc index eec631fab..dfa28ad5a 100644 --- a/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc +++ b/pfSense-pkg-API/files/etc/inc/api/endpoints/APISystemVersionUpgrade.inc @@ -18,6 +18,7 @@ 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() { From 1848b877c804b6dd30aa58712a82159a1de6f774 Mon Sep 17 00:00:00 2001 From: Jared Hendrickson Date: Sat, 8 Oct 2022 11:05:20 -0600 Subject: [PATCH 3/4] tests: test version upgrade resp times --- tests/test_api_v1_system_version_upgrade.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/tests/test_api_v1_system_version_upgrade.py b/tests/test_api_v1_system_version_upgrade.py index 92b724237..ee79595ad 100644 --- a/tests/test_api_v1_system_version_upgrade.py +++ b/tests/test_api_v1_system_version_upgrade.py @@ -5,7 +5,20 @@ 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"}] + 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() From 2258c59db8e4f0c6e1d3c3b82fb5933e246aef81 Mon Sep 17 00:00:00 2001 From: Jared Hendrickson Date: Sat, 8 Oct 2022 11:08:46 -0600 Subject: [PATCH 4/4] docs: add new priv to system version adds priv page-system-update-settings to allow /api/v1/system/version calls --- .../files/usr/local/www/api/documentation/openapi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml b/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml index 90fa67423..547fab105 100644 --- a/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml +++ b/pfSense-pkg-API/files/usr/local/www/api/documentation/openapi.yml @@ -13223,7 +13223,7 @@ paths: version, buildtime, and last commit.

_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'