feat: added SystemDNS endpoint and model

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

@@ -1,6 +1,6 @@
 <?php
 
-namespace API\Endpointss;
+namespace API\Endpoints;
 
 require_once("api/auto_loader.inc");
 

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

@@ -1,6 +1,6 @@
 <?php
 
-namespace API\Endpointss;
+namespace API\Endpoints;
 
 require_once("api/auto_loader.inc");
 

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

@@ -1,6 +1,6 @@
 <?php
 
-namespace API\Endpointss;
+namespace API\Endpoints;
 
 require_once("api/auto_loader.inc");
 

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

@@ -1,6 +1,6 @@
 <?php
 
-namespace API\Endpointss;
+namespace API\Endpoints;
 
 require_once("api/auto_loader.inc");
 

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

@@ -1,6 +1,6 @@
 <?php
 
-namespace API\Endpointss;
+namespace API\Endpoints;
 
 require_once("api/auto_loader.inc");
 

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

@@ -0,0 +1,28 @@
+<?php
+
+namespace API\Endpoints;
+
+require_once("api/auto_loader.inc");
+
+use API\Core\Endpoint;
+
+class SystemDNS extends Endpoint
+{
+    public function __construct() {
+        # Assign the URL for this endpoint along with the Model it corresponds to.
+        $this->url = "/api/v2/system/dns";
+        $this->model_name = "SystemDNS";
+
+        # Assign allowed request methods along with the privileges required for each
+        $this->request_method_options = ["GET", "PATCH"];
+        $this->get_privileges = ["page-all", "page-system-generalsetup"];
+        $this->patch_privileges = ["page-all", "page-system-generalsetup"];
+
+        # Assign documentation help text for each request method
+        $this->get_help_text = "Reads the current system DNS settings.";
+        $this->patch_help_text = "Updates the current system DNS settings.";
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}

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

@@ -0,0 +1,56 @@
+<?php
+
+namespace API\Models;
+
+use API\Core\Auth;
+use API\Core\Model;
+use API\Dispatchers\SystemHostnameApplyDispatcher;
+use API\Fields\BooleanField;
+use API\Fields\StringField;
+use API\Validators\IPAddressValidator;
+
+class SystemDNS extends Model
+{
+    public BooleanField $dnsallowoverride;
+    public StringField $dnslocalhost;
+    public StringField $dnsserver;
+
+    public function __construct(mixed $data = [], Auth $client = null, bool $async = true)
+    {
+        # Set model attributes
+        $this->config_path = "system";
+        $this->update_strategy = "merge";
+        $this->always_apply = true;
+
+        # Set model fields
+        $this->dnsallowoverride = new BooleanField(
+            default: false,
+            help_text: "Allow DNS servers to be overwritten by DHCP on WAN interfaces."
+        );
+        $this->dnslocalhost = new StringField(
+            default: null,
+            choices: ["local", "remote"],
+            allow_null: true,
+            help_text: "Use local DNS server (DNS Resover or DNS Forwarder) as the primary DNS, or use only remote ".
+                "DNS servers specified in `dnsserver`. Set to `null` to use local DNS server as the primary and ".
+                "remote DNS servers as backup."
+        );
+        $this->dnsserver = new StringField(
+            default: [],
+            allow_empty: true,
+            many: true,
+            delimiter: null,
+            validators: [new IPAddressValidator(allow_ipv4: true, allow_ipv6: true)],
+            help_text: "The remote DNS server IPv4 or IPv6 addresses."
+        );
+
+        parent::__construct(data: $data, client: $client, async: $async);
+    }
+
+    /**
+     * Apply these DNS server changes to the system and restart associated services.
+     */
+    public function apply() {
+        (new SystemHostnameApplyDispatcher(async: $this->async))->spawn_process();
+    }
+}

pfSense-pkg-API/files/etc/inc/api/tests/APIModelsSystemDNSTestCase.inc

@@ -0,0 +1,58 @@
+<?php
+
+namespace API\Tests;
+
+use API\Core\TestCase;
+use API\Models\SystemDNS;
+
+class APIModelsSystemDNSTestCase extends TestCase
+{
+    /**
+     * Checks that setting `dnslocalhost` to `local` only adds 127.0.0.1 as a DNS server in resolv.conf
+     */
+    public function test_dnslocalhost_local_resolvconf() {
+        # Create the system DNS model object to test with
+        $system_dns = new SystemDNS(async: false);
+
+        # Set dnslocalhost to local and ensure 127.0.0.1 is the only DNS server listed
+        $system_dns->dnslocalhost->value = "local";
+        $system_dns->update();
+        $resolvconf = file_get_contents("/etc/resolv.conf");
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 127.0.0.1"));
+    }
+
+    /**
+     * Checks that setting `dnslocalhost` to `remote` only adds specific DNS servers in resolv.conf
+     */
+    public function test_dnslocalhost_remote_resolvconf() {
+        # Create the system DNS model object to test with
+        $system_dns = new SystemDNS(async: false);
+
+        # Set dnslocalhost to remote and ensure the remote DNS servers are the only servers listed
+        $system_dns->dnslocalhost->value = "remote";
+        $system_dns->dnsserver->value = ["8.8.8.8", "8.8.4.4"];
+        $system_dns->update();
+        $resolvconf = file_get_contents("/etc/resolv.conf");
+        $this->assert_is_false(str_contains($resolvconf, "nameserver 127.0.0.1"));
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 8.8.8.8"));
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 8.8.4.4"));
+    }
+
+    /**
+     * Checks that setting `dnslocalhost` to `null` only adds the local and remote DNS servers in resolv.conf
+     */
+    public function test_dnslocalhost_null_resolvconf() {
+        # Create the system DNS model object to test with
+        $system_dns = new SystemDNS(async: false);
+
+        # Set dnslocalhost to null and ensure 127.0.0.1 and remote DNS servers are listed
+        $system_dns->dnslocalhost->value = null;
+        $system_dns->dnsserver->value = ["8.8.8.8", "8.8.4.4"];
+        $system_dns->update();
+        $resolvconf = file_get_contents("/etc/resolv.conf");
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 127.0.0.1"));
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 8.8.8.8"));
+        $this->assert_is_true(str_contains($resolvconf, "nameserver 8.8.4.4"));
+    }
+
+}

pfSense-pkg-API/files/etc/inc/api/tests/APIModelsSystemHostnameTestCase.inc

@@ -0,0 +1,36 @@
+<?php
+
+namespace API\Tests;
+
+use API\Core\Command;
+use API\Core\TestCase;
+use API\Models\SystemHostname;
+
+class APIModelsSystemHostnameTestCase extends TestCase
+{
+    /**
+     * Checks that the system hostname is configured after updating.
+     */
+    public function test_update() {
+        # Create the SystemHostname model object to test with
+        $hostname = new SystemHostname(async: false);
+
+        # Remember the original hostname and domain
+        $original_hostname = $hostname->hostname->value;
+        $original_domain = $hostname->domain->value;
+
+        # Update the system hostname to something different and ensure it is configured
+        $hostname->hostname->value = "test";
+        $hostname->domain->value = "example.com";
+        $hostname->update();
+        $hostname_cmd = new Command("hostname");
+        $this->assert_is_true(str_contains($hostname_cmd->output, "test.example.com"));
+
+        # Restore the original hostname and domain and ensure it is configured
+        $hostname->hostname->value = $original_hostname;
+        $hostname->domain->value = $original_domain;
+        $hostname->update();
+        $hostname_cmd = new Command("hostname");
+        $this->assert_is_true(str_contains($hostname_cmd->output, "$original_hostname.$original_domain"));
+    }
+}