feat: add models, endpoints and tests for system tables

Author: jaredhendrickson13

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

@@ -0,0 +1,28 @@
+<?php
+
+namespace RESTAPI\Endpoints;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Endpoint;
+
+/**
+ * Defines an Endpoint for interacting with singular Table Model objects at /api/v2/diagnostics/table.
+ */
+class DiagnosticsTableEndpoint extends Endpoint {
+    public function __construct() {
+        # Set Endpoint attributes
+        $this->url = '/api/v2/diagnostics/table';
+        $this->model_name = 'Table';
+        $this->request_method_options = ['GET', 'DELETE'];
+
+        # Set help texts
+        $this->get_help_text = 'Retrieves the entries in a specified table.';
+        $this->delete_help_text =
+            'Flushes all entries in a specified table. Please note this does not ' .
+            'delete the table itself, only its entries.';
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}

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

@@ -0,0 +1,28 @@
+<?php
+
+namespace RESTAPI\Endpoints;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Endpoint;
+
+/**
+ * Defines an Endpoint for interacting with multiple Table Model objects at /api/v2/diagnostics/tables.
+ */
+class DiagnosticsTablesEndpoint extends Endpoint {
+    public function __construct() {
+        # Set Endpoint attributes
+        $this->url = '/api/v2/diagnostics/tables';
+        $this->model_name = 'Table';
+        $this->request_method_options = ['GET'];
+        $this->many = true;
+
+        # Set help texts
+        $this->get_help_text =
+            'Retrieves the entries from all tables. For systems with a large number of tables or ' .
+            'entries, it is recommended to use pagination and/or querying to limit the amount of data returned.';
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}

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

@@ -0,0 +1,69 @@
+<?php
+
+namespace RESTAPI\Models;
+
+use RESTAPI\Core\Command;
+use RESTAPI\Core\Model;
+use RESTAPI\Fields\StringField;
+use RESTAPI\Responses\ServerError;
+
+/**
+ * Defines a Model for interacting with pfSense tables.
+ */
+class Table extends Model {
+    public StringField $entries;
+
+    public function __construct(mixed $id = null, mixed $parent_id = null, mixed $data = [], ...$options) {
+        # Set model attributes
+        $this->internal_callable = 'get_tables';
+        $this->id_type = 'string';
+        $this->many = true;
+
+        $this->entries = new StringField(many: true, delimiter: ' ', help_text: 'The entries currently in the table.');
+
+        parent::__construct($id, $parent_id, $data, ...$options);
+    }
+
+    /**
+     * Retrieves the list of available tables from the pfctl command.
+     * @return array The list of available table names.
+     */
+    public function get_available_table_names(): array {
+        $table_names_ouptput = new Command('/sbin/pfctl -sT');
+        return explode("\n", $table_names_ouptput->output);
+    }
+
+    /**
+     * Obtains the auth log as an array. This method is the internal callable for this Model.
+     * @return array The auth log as an array of objects.
+     */
+    protected function get_tables(): array {
+        $tables = [];
+
+        # Loop through each table and expand its entries
+        foreach ($this->get_available_table_names() as $table_name) {
+            # Get the entries for the table
+            $table_entries_output = new Command(
+                '/sbin/pfctl -t ' . escapeshellarg($table_name) . ' -T show',
+                trim_whitespace: true,
+            );
+            $tables[$table_name] = ['entries' => trim($table_entries_output->output)];
+        }
+
+        return $tables;
+    }
+
+    /**
+     * Overrides the default _delete method to flush the table entries instead.
+     */
+    protected function _delete(): void {
+        # Flush the table entries using pfctl
+        $flush_command = new Command('/sbin/pfctl -t ' . escapeshellarg($this->id) . ' -T flush');
+        if ($flush_command->result_code !== 0) {
+            throw new ServerError(
+                message: 'Failed to flush table entries for ' . $this->id . ': ' . $flush_command->output,
+                response_id: 'TABLE_FLUSH_FAILED',
+            );
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+<?php
+
+namespace RESTAPI\Tests;
+
+use RESTAPI\Core\Command;
+use RESTAPI\Core\TestCase;
+use RESTAPI\Models\CARP;
+use RESTAPI\Models\Table;
+use RESTAPI\Models\VirtualIP;
+
+class APIModelsTableTestCase extends TestCase {
+    /**
+     * Checks that we can successful retrieve the list of available table names.
+     */
+    public function test_get_available_table_names(): void {
+        # Create a new pf table to test with
+        new Command('/sbin/pfctl -t pfrest_test_table -T add 1.2.3.4');
+
+        # Ensure get_available_table_names returns the test table
+        $table = new Table();
+        $this->assert_is_true(
+            in_array('pfrest_test_table', $table->get_available_table_names()),
+            message: 'The test table should be in the list of available tables.',
+        );
+
+        # Delete the test table after the test
+        new Command('/sbin/pfctl -t pfrest_test_table -T kill');
+
+        # Ensure the test table is no longer available
+        $this->assert_is_false(
+            in_array('pfrest_test_table', $table->get_available_table_names()),
+            message: 'The test table should no longer be in the list of available tables.',
+        );
+    }
+
+    /**
+     * Checks that we can successfully read entries from a table
+     */
+    public function test_read(): void {
+        # Create a new pf table to test with
+        new Command('/sbin/pfctl -t pfrest_test_table -T add 1.2.3.4 4.3.2.1');
+
+        # Load the Table model
+        $table = new Table(id: 'pfrest_test_table');
+
+        # Ensure the table has the expected entries
+        $this->assert_equals($table->entries->value, ['1.2.3.4', '4.3.2.1']);
+
+        # Delete the test table after the test
+        new Command('/sbin/pfctl -t pfrest_test_table -T kill');
+    }
+
+    /**
+     * Checks that we can successfully delete (flush) entrries from a table
+     */
+    public function test_delete(): void {
+        # Create a new pf table to test with
+        new Command('/sbin/pfctl -t pfrest_test_table -T add 1.2.3.4 4.3.2.1');
+
+        # Load the Table model
+        $table = new Table(id: 'pfrest_test_table');
+
+        # Ensure the table entries are present (so we know delete actually flushes them)
+        $this->assert_equals($table->entries->value, ['1.2.3.4', '4.3.2.1']);
+
+        # Delete (flush) the test table and ensure the entries are actually flushed
+        $table->delete();
+        $table_show = new Command('/sbin/pfctl -t pfrest_test_table -T show');
+        $this->assert_str_does_not_contain($table_show->output, '1.2.3.4');
+        $this->assert_str_does_not_contain($table_show->output, '4.3.2.1');
+
+        # Delete the test table after the test
+        new Command('/sbin/pfctl -t pfrest_test_table -T kill');
+    }
+}