feat: add model, endpoint and tests for /api/v2/system/update

Author: jaredhendrickson13

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Dispatchers/SystemUpdateDispatcher.inc

@@ -0,0 +1,43 @@
+<?php
+
+namespace RESTAPI\Dispatchers;
+
+use RESTAPI\Core\Command;
+use RESTAPI\Core\Dispatcher;
+
+/**
+ * Defines a Dispatcher for running pfSense package updates.
+ */
+class SystemUpdateDispatcher extends Dispatcher {
+    # Only allow one upgrade process at a time
+    public int $max_queue = 1;
+
+    /**
+     * Updates package metadata and runs the pfSense upgrade process.
+     */
+    protected function _process(mixed ...$arguments): void {
+        # Accept either named or positional dry_run argument.
+        $dry_run = false;
+        if (array_key_exists('dry_run', $arguments)) {
+            $dry_run = (bool) $arguments['dry_run'];
+        } elseif (array_key_exists(0, $arguments)) {
+            $dry_run = (bool) $arguments[0];
+        }
+
+        $this->run_command('/usr/local/sbin/pkg-static update');
+
+        $upgrade_command = '/usr/local/sbin/pfSense-upgrade -y';
+        if ($dry_run) {
+            $upgrade_command .= ' -n';
+        }
+
+        $this->run_command($upgrade_command);
+    }
+
+    /**
+     * Executes a shell command for this dispatcher process.
+     */
+    protected function run_command(string $command): void {
+        new Command($command);
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Endpoints/SystemUpdateEndpoint.inc

@@ -0,0 +1,23 @@
+<?php
+
+namespace RESTAPI\Endpoints;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Endpoint;
+
+/**
+ * Defines an Endpoint for interacting with singular SystemUpdate Model objects at /api/v2/system/update.
+ */
+class SystemUpdateEndpoint extends Endpoint {
+    public function __construct() {
+        # Set Endpoint attributes
+        $this->url = '/api/v2/system/update';
+        $this->model_name = 'SystemUpdate';
+        $this->request_method_options = ['POST'];
+        $this->post_help_text = 'Initiates a pfSense update process.';
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Models/SystemUpdate.inc

@@ -0,0 +1,46 @@
+<?php
+
+namespace RESTAPI\Models;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Model;
+use RESTAPI\Dispatchers\SystemUpdateDispatcher;
+use RESTAPI\Fields\BooleanField;
+
+/**
+ * Defines a Model that performs a pfSense update operation.
+ */
+class SystemUpdate extends Model {
+    public BooleanField $dry_run;
+
+    public function __construct(mixed $id = null, mixed $parent_id = null, mixed $data = [], ...$options) {
+        # Set model attributes
+        $this->many = false;
+        $this->always_apply = true;
+
+        # Set model fields
+        $this->dry_run = new BooleanField(
+            default: false,
+            write_only: true,
+            verbose_name: 'Dry Run',
+            help_text: 'Run the pfSense update process in dry-run mode (-n) without applying changes.',
+        );
+
+        parent::__construct($id, $parent_id, $data, ...$options);
+    }
+
+    /**
+     * This model only triggers apply behavior, so this method intentionally does nothing.
+     */
+    public function _create(): void {
+        # Intentionally empty.
+    }
+
+    /**
+     * Spawns a dispatcher process that performs package update + pfSense upgrade.
+     */
+    public function apply(): void {
+        (new SystemUpdateDispatcher(async: $this->async))->spawn_process(dry_run: $this->dry_run->value);
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Tests/APIDispatchersSystemUpdateDispatcherTestCase.inc

@@ -0,0 +1,63 @@
+<?php
+
+namespace RESTAPI\Tests;
+
+use RESTAPI\Core\TestCase;
+use RESTAPI\Dispatchers\SystemUpdateDispatcher;
+
+class TestSystemUpdateDispatcher extends SystemUpdateDispatcher {
+    public array $commands = [];
+
+    protected function run_command(string $command): void {
+        $this->commands[] = $command;
+    }
+}
+
+class APIDispatchersSystemUpdateDispatcherTestCase extends TestCase {
+    /**
+     * Ensure the dispatcher enforces max_queue of one process.
+     */
+    public function test_max_queue_is_one(): void {
+        $dispatcher = new SystemUpdateDispatcher();
+        $this->assert_equals($dispatcher->max_queue, 1);
+    }
+
+    /**
+     * Ensure the dispatcher calls pkg-static update and standard upgrade by default.
+     */
+    public function test_process_without_dry_run_uses_standard_upgrade_command(): void {
+        $dispatcher = new TestSystemUpdateDispatcher();
+        $dispatcher->process();
+
+        $this->assert_equals($dispatcher->commands, [
+            '/usr/local/sbin/pkg-static update',
+            '/usr/local/sbin/pfSense-upgrade -y',
+        ]);
+    }
+
+    /**
+     * Ensure named dry_run appends -n to pfSense-upgrade.
+     */
+    public function test_process_with_named_dry_run_uses_noop_upgrade_command(): void {
+        $dispatcher = new TestSystemUpdateDispatcher();
+        $dispatcher->process(dry_run: true);
+
+        $this->assert_equals($dispatcher->commands, [
+            '/usr/local/sbin/pkg-static update',
+            '/usr/local/sbin/pfSense-upgrade -y -n',
+        ]);
+    }
+
+    /**
+     * Ensure positional dry_run argument also appends -n to pfSense-upgrade.
+     */
+    public function test_process_with_positional_dry_run_uses_noop_upgrade_command(): void {
+        $dispatcher = new TestSystemUpdateDispatcher();
+        $dispatcher->process(true);
+
+        $this->assert_equals($dispatcher->commands, [
+            '/usr/local/sbin/pkg-static update',
+            '/usr/local/sbin/pfSense-upgrade -y -n',
+        ]);
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Tests/APIModelsSystemUpdateTestCase.inc

@@ -0,0 +1,21 @@
+<?php
+
+namespace RESTAPI\Tests;
+
+use RESTAPI\Core\TestCase;
+use RESTAPI\Models\SystemUpdate;
+
+class APIModelsSystemUpdateTestCase extends TestCase {
+    /**
+     * Check that the SystemUpdate model accepts and validates dry_run inputs.
+     */
+    public function test_validate_dry_run_field(): void {
+        $this->assert_does_not_throw(
+            callable: function () {
+                $update = new SystemUpdate(data: ['dry_run' => true]);
+                $update->validate();
+                $this->assert_is_true($update->dry_run->value);
+            },
+        );
+    }
+}