Added DNS firewall configuration

src/Extensions/Cloudflare.Dns/DnsFirewallExtensions.cs

@@ -0,0 +1,154 @@
+using System.Threading;
+using System.Threading.Tasks;
+using AMWD.Net.Api.Cloudflare.Dns.Internals;
+
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Extensions for the <see href="https://developers.cloudflare.com/api/resources/dns_firewall/">DNS Firewall</see>.
+	/// </summary>
+	public static class DnsFirewallExtensions
+	{
+		/// <summary>
+		/// List DNS Firewall clusters for an account.
+		/// </summary>
+		/// <param name="client">The <see cref="ICloudflareClient"/> instance.</param>
+		/// <param name="accountId">The account identifier.</param>
+		/// <param name="options">Filter options (optional).</param>
+		/// <param name="cancellationToken">A cancellation token used to propagate notification that this operation should be canceled.</param>
+		public static Task<CloudflareResponse<IReadOnlyCollection<DnsFirewallCluster>>> ListDNSFirewallClusters(this ICloudflareClient client, string accountId, ListDNSFirewallClustersFilter? options = null, CancellationToken cancellationToken = default)
+		{
+			accountId.ValidateCloudflareId();
+
+			return client.GetAsync<IReadOnlyCollection<DnsFirewallCluster>>($"/accounts/{accountId}/dns_firewall", options, cancellationToken);
+		}
+
+		/// <summary>
+		/// Show a single DNS Firewall cluster for an account.
+		/// </summary>
+		/// <param name="client">The <see cref="ICloudflareClient"/> instance.</param>
+		/// <param name="accountId">The account identifier.</param>
+		/// <param name="dnsFirewallId">The DNS firewall identifier.</param>
+		/// <param name="cancellationToken">A cancellation token used to propagate notification that this operation should be canceled.</param>
+		public static Task<CloudflareResponse<DnsFirewallCluster>> DNSFirewallClusterDetails(this ICloudflareClient client, string accountId, string dnsFirewallId, CancellationToken cancellationToken = default)
+		{
+			accountId.ValidateCloudflareId();
+			dnsFirewallId.ValidateCloudflareId();
+
+			return client.GetAsync<DnsFirewallCluster>($"/accounts/{accountId}/dns_firewall/{dnsFirewallId}", null, cancellationToken);
+		}
+
+		/// <summary>
+		/// Create a DNS Firewall cluster.
+		/// </summary>
+		/// <param name="client">The <see cref="ICloudflareClient"/> instance.</param>
+		/// <param name="request">The request.</param>
+		/// <param name="cancellationToken">A cancellation token used to propagate notification that this operation should be canceled.</param>
+		public static Task<CloudflareResponse<DnsFirewallCluster>> CreateDNSFirewallCluster(this ICloudflareClient client, CreateDNSFirewallClusterRequest request, CancellationToken cancellationToken = default)
+		{
+			request.AccountId.ValidateCloudflareId();
+
+			if (string.IsNullOrWhiteSpace(request.Name))
+				throw new ArgumentException("DNS Firewall cluster name must be provided.", nameof(request.Name));
+
+			request.Name = request.Name.Trim();
+
+			if (request.Name.Length > 160)
+				throw new ArgumentException("DNS Firewall cluster name must not exceed 160 characters.", nameof(request.Name));
+
+			if (request.MaximumCacheTtl.HasValue && (request.MaximumCacheTtl < 30 || 36000 < request.MaximumCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.MaximumCacheTtl), "Maximum cache TTL must be between 30 and 36000.");
+
+			if (request.MinimumCacheTtl.HasValue && (request.MinimumCacheTtl < 30 || 36000 < request.MinimumCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.MinimumCacheTtl), "Minimum cache TTL must be between 30 and 36000.");
+
+			if (request.NegativeCacheTtl.HasValue && (request.NegativeCacheTtl < 30 || 36000 < request.NegativeCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.NegativeCacheTtl), "Negative cache TTL must be between 30 and 36000.");
+
+			if (request.RateLimit.HasValue && (request.RateLimit < 100 || 1_000_000_000 < request.RateLimit))
+				throw new ArgumentOutOfRangeException(nameof(request.RateLimit), "Ratelimit must be between 100 and 1,000,000,000 seconds.");
+
+			if (request.Retries.HasValue && (request.Retries < 0 || 2 < request.Retries))
+				throw new ArgumentOutOfRangeException(nameof(request.Retries), "Retries must be between 0 and 2.");
+
+			var req = new InternalDNSFirewallClusterRequest
+			{
+				Name = request.Name,
+				UpstreamIps = request.UpstreamIps,
+				AttackMitigation = request.AttackMitigation,
+				DeprecateAnyRequests = request.DeprecateAnyRequests,
+				EcsFallback = request.EcsFallback,
+				MaximumCacheTtl = request.MaximumCacheTtl,
+				MinimumCacheTtl = request.MinimumCacheTtl,
+				NegativeCacheTtl = request.NegativeCacheTtl,
+				RateLimit = request.RateLimit,
+				Retries = request.Retries
+			};
+
+			return client.PostAsync<DnsFirewallCluster, InternalDNSFirewallClusterRequest>($"/accounts/{request.AccountId}/dns_firewall", req, null, cancellationToken);
+		}
+
+		/// <summary>
+		/// Modify the configuration of a DNS Firewall cluster.
+		/// </summary>
+		/// <param name="client">The <see cref="ICloudflareClient"/> instance.</param>
+		/// <param name="request">The request.</param>
+		/// <param name="cancellationToken">A cancellation token used to propagate notification that this operation should be canceled.</param>
+		public static Task<CloudflareResponse<DnsFirewallCluster>> UpdateDNSFirewallCluster(this ICloudflareClient client, UpdateDNSFirewallClusterRequest request, CancellationToken cancellationToken = default)
+		{
+			request.AccountId.ValidateCloudflareId();
+			request.DnsFirewallId.ValidateCloudflareId();
+
+			request.Name = request.Name?.Trim();
+
+			if (request.Name?.Length > 160)
+				throw new ArgumentException("DNS Firewall cluster name must not exceed 160 characters.", nameof(request.Name));
+
+			if (request.MaximumCacheTtl.HasValue && (request.MaximumCacheTtl < 30 || 36000 < request.MaximumCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.MaximumCacheTtl), "Maximum cache TTL must be between 30 and 36000.");
+
+			if (request.MinimumCacheTtl.HasValue && (request.MinimumCacheTtl < 30 || 36000 < request.MinimumCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.MinimumCacheTtl), "Minimum cache TTL must be between 30 and 36000.");
+
+			if (request.NegativeCacheTtl.HasValue && (request.NegativeCacheTtl < 30 || 36000 < request.NegativeCacheTtl))
+				throw new ArgumentOutOfRangeException(nameof(request.NegativeCacheTtl), "Negative cache TTL must be between 30 and 36000.");
+
+			if (request.RateLimit.HasValue && (request.RateLimit < 100 || 1_000_000_000 < request.RateLimit))
+				throw new ArgumentOutOfRangeException(nameof(request.RateLimit), "Ratelimit must be between 100 and 1,000,000,000 seconds.");
+
+			if (request.Retries.HasValue && (request.Retries < 0 || 2 < request.Retries))
+				throw new ArgumentOutOfRangeException(nameof(request.Retries), "Retries must be between 0 and 2.");
+
+			var req = new InternalDNSFirewallClusterRequest
+			{
+				Name = request.Name,
+				UpstreamIps = request.UpstreamIps,
+				AttackMitigation = request.AttackMitigation,
+				DeprecateAnyRequests = request.DeprecateAnyRequests,
+				EcsFallback = request.EcsFallback,
+				MaximumCacheTtl = request.MaximumCacheTtl,
+				MinimumCacheTtl = request.MinimumCacheTtl,
+				NegativeCacheTtl = request.NegativeCacheTtl,
+				RateLimit = request.RateLimit,
+				Retries = request.Retries
+			};
+
+			return client.PatchAsync<DnsFirewallCluster, InternalDNSFirewallClusterRequest>($"/accounts/{request.AccountId}/dns_firewall", req, cancellationToken);
+		}
+
+		/// <summary>
+		/// Delete a DNS Firewall cluster.
+		/// </summary>
+		/// <param name="client">The <see cref="ICloudflareClient"/> instance.</param>
+		/// <param name="accountId">The account identifier.</param>
+		/// <param name="dnsFirewallId">The DNS firewall identifier.</param>
+		/// <param name="cancellationToken">A cancellation token used to propagate notification that this operation should be canceled.</param>
+		public static Task<CloudflareResponse<Identifier>> DeleteDNSFirewallCluster(this ICloudflareClient client, string accountId, string dnsFirewallId, CancellationToken cancellationToken = default)
+		{
+			accountId.ValidateCloudflareId();
+			dnsFirewallId.ValidateCloudflareId();
+
+			return client.DeleteAsync<Identifier>($"/accounts/{accountId}/dns_firewall/{dnsFirewallId}", null, cancellationToken);
+		}
+	}
+}

src/Extensions/Cloudflare.Dns/Filters/ListDNSFirewallClustersFilter.cs

@@ -0,0 +1,32 @@
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Represents a filter for querying DNS firewall clusters with optional pagination parameters.
+	/// </summary>
+	public class ListDNSFirewallClustersFilter : IQueryParameterFilter
+	{
+		/// <summary>
+		/// Page number of paginated results.
+		/// </summary>
+		public int? Page { get; set; }
+
+		/// <summary>
+		/// Number of clusters per page.
+		/// </summary>
+		public int? PerPage { get; set; }
+
+		/// <inheritdoc/>
+		public IReadOnlyDictionary<string, string> GetQueryParameters()
+		{
+			var dict = new Dictionary<string, string>();
+
+			if (Page.HasValue && 1 <= Page.Value)
+				dict.Add("page", Page.Value.ToString());
+
+			if (PerPage.HasValue && 1 <= PerPage.Value && PerPage.Value <= 100)
+				dict.Add("per_page", PerPage.Value.ToString());
+
+			return dict;
+		}
+	}
+}

src/Extensions/Cloudflare.Dns/Internals/InternalDNSFirewallClusterRequest.cs

@@ -0,0 +1,35 @@
+namespace AMWD.Net.Api.Cloudflare.Dns.Internals
+{
+	internal class InternalDNSFirewallClusterRequest
+	{
+		[JsonProperty("name")]
+		public string? Name { get; set; }
+
+		[JsonProperty("upstream_ips")]
+		public IReadOnlyCollection<string>? UpstreamIps { get; set; }
+
+		[JsonProperty("attack_mitigation")]
+		public AttackMitigation? AttackMitigation { get; set; }
+
+		[JsonProperty("deprecate_any_requests")]
+		public bool? DeprecateAnyRequests { get; set; }
+
+		[JsonProperty("ecs_fallback")]
+		public bool? EcsFallback { get; set; }
+
+		[JsonProperty("maximum_cache_ttl")]
+		public int? MaximumCacheTtl { get; set; }
+
+		[JsonProperty("minimum_cache_ttl")]
+		public int? MinimumCacheTtl { get; set; }
+
+		[JsonProperty("negative_cache_ttl")]
+		public int? NegativeCacheTtl { get; set; }
+
+		[JsonProperty("ratelimit")]
+		public int? RateLimit { get; set; }
+
+		[JsonProperty("retries")]
+		public int? Retries { get; set; }
+	}
+}

src/Extensions/Cloudflare.Dns/Models/DnsFirewallCluster.cs

@@ -0,0 +1,140 @@
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Represents the response data for a DNS Firewall configuration on cloudflare.
+	/// </summary>
+	public class DnsFirewallCluster
+	{
+		/// <summary>
+		/// The identifier.
+		/// </summary>
+		[JsonProperty("id")]
+		public string? Id { get; set; }
+
+		/// <summary>
+		/// Whether to refuse to answer queries for the ANY type.
+		/// </summary>
+		[JsonProperty("deprecate_any_requests")]
+		public bool? DeprecateAnyRequests { get; set; }
+
+		/// <summary>
+		/// List of IPs used by DNS Firewall cluster.
+		/// </summary>
+		[JsonProperty("dns_firewall_ips")]
+		public IReadOnlyCollection<string>? DnsFirewallIps { get; set; }
+
+		/// <summary>
+		/// Whether to forward client IP (resolver) subnet if no EDNS Client Subnet is sent.
+		/// </summary>
+		[JsonProperty("ecs_fallback")]
+		public bool? EcsFallback { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// By default, Cloudflare attempts to cache responses for as long as indicated by
+		/// the TTL received from upstream nameservers.This setting sets an upper bound on
+		/// this duration.For caching purposes, higher TTLs will be decreased to the
+		/// maximum value defined by this setting.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare
+		/// returns to clients.Cloudflare will always forward the TTL value received from
+		/// upstream nameservers.
+		/// </para>
+		/// </summary>
+		[JsonProperty("maximum_cache_ttl")]
+		public int? MaximumCacheTtl { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// By default, Cloudflare attempts to cache responses for as long as indicated by
+		/// the TTL received from upstream nameservers.This setting sets a lower bound on
+		/// this duration.For caching purposes, lower TTLs will be increased to the minimum
+		/// value defined by this setting.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare
+		/// returns to clients.Cloudflare will always forward the TTL value received from
+		/// upstream nameservers.
+		/// </para>
+		/// </summary>
+		/// <remarks>
+		/// Note that, even with this setting, there is no guarantee that a response will be
+		/// cached for at least the specified duration.Cached responses may be removed
+		/// earlier for capacity or other operational reasons.
+		/// </remarks>
+		[JsonProperty("minimum_cache_ttl")]
+		public int? MinimumCacheTtl { get; set; }
+
+		/// <summary>
+		/// Last modification of DNS Firewall cluster
+		/// </summary>
+		[JsonProperty("modified_on")]
+		public DateTime? ModifiedOn { get; set; }
+
+		/// <summary>
+		/// DNS Firewall cluster name.
+		/// </summary>
+		[JsonProperty("name")]
+		public string? Name { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// This setting controls how long DNS Firewall should cache negative responses
+		/// (e.g., NXDOMAIN) from the upstream servers.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare
+		/// returns to clients.Cloudflare will always forward the TTL value received from
+		/// upstream nameservers.
+		/// </para>
+		/// </summary>
+		[JsonProperty("negative_cache_ttl")]
+		public int? NegativeCacheTtl { get; set; }
+
+		/// <summary>
+		/// Ratelimit in queries per second per datacenter
+		/// (applies to DNS queries sent to the upstream nameservers configured on the cluster).
+		/// </summary>
+		[JsonProperty("ratelimit")]
+		public int? RateLimit { get; set; }
+
+		/// <summary>
+		/// Number of retries for fetching DNS responses from upstream nameservers
+		/// (not counting the initial attempt).
+		/// </summary>
+		[JsonProperty("retries")]
+		public int? Retries { get; set; }
+
+		/// <summary>
+		/// Upstream DNS server IPs.
+		/// </summary>
+		[JsonProperty("upstream_ips")]
+		public IReadOnlyCollection<string>? UpstreamIps { get; set; }
+
+		/// <summary>
+		/// Attack mitigation settings.
+		/// </summary>
+		[JsonProperty("attack_mitigation")]
+		public AttackMitigation? AttackMitigation { get; set; }
+	}
+
+	/// <summary>
+	/// Attack mitigation settings.
+	/// <see href="https://github.com/cloudflare/cloudflare-typescript/blob/v4.4.1/src/resources/dns-firewall/dns-firewall.ts#L154">Source</see>
+	/// </summary>
+	public class AttackMitigation
+	{
+		/// <summary>
+		/// When enabled, automatically mitigate random-prefix attacks to protect upstream DNS servers.
+		/// </summary>
+		[JsonProperty("enabled")]
+		public bool? Enabled { get; set; }
+
+		/// <summary>
+		/// Only mitigate attacks when upstream servers seem unhealthy.
+		/// </summary>
+		[JsonProperty("only_when_upstream_unhealthy")]
+		public bool? OnlyWhenUpstreamUnhealthy { get; set; }
+	}
+}

src/Extensions/Cloudflare.Dns/README.md

@@ -113,6 +113,15 @@ This package contains the feature set of the _DNS_ section of the Cloudflare API
 - [Delete TSIG](https://developers.cloudflare.com/api/resources/dns/subresources/zone_transfers/subresources/tsigs/methods/delete/)
 
 
+### [DNS Firewall]
+
+- [List DNS Firewall Clusters](https://developers.cloudflare.com/api/resources/dns_firewall/methods/list/)
+- [DNS Firewall Cluster Details](https://developers.cloudflare.com/api/resources/dns_firewall/methods/get/)
+- [Create DNS Firewall Cluster](https://developers.cloudflare.com/api/resources/dns_firewall/methods/create/)
+- [Update DNS Firewall Cluster](https://developers.cloudflare.com/api/resources/dns_firewall/methods/update/)
+- [Delete DNS Firewall Cluster](https://developers.cloudflare.com/api/resources/dns_firewall/methods/delete/)
+
+
 ---
 
 Published under MIT License (see [choose a license])
@@ -136,3 +145,4 @@ Published under MIT License (see [choose a license])
 		[Outgoing]: https://developers.cloudflare.com/api/resources/dns/subresources/zone_transfers/subresources/outgoing/
 		[Peers]: https://developers.cloudflare.com/api/resources/dns/subresources/zone_transfers/subresources/peers/
 		[TSIGs]: https://developers.cloudflare.com/api/resources/dns/subresources/zone_transfers/subresources/tsigs/
+[DNS Firewall]: https://developers.cloudflare.com/api/resources/dns_firewall/

src/Extensions/Cloudflare.Dns/Requests/CreateDNSFirewallClusterRequest.cs

@@ -0,0 +1,24 @@
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Represents a request to create a DNS Firewall cluster with specific configuration settings.
+	/// </summary>
+	public class CreateDNSFirewallClusterRequest : DNSFirewallClusterRequestBase
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="CreateDNSFirewallClusterRequest"/> class.
+		/// </summary>
+		/// <param name="accountId">The account identifier.</param>
+		/// <param name="name">DNS Firewall cluster name.</param>
+		public CreateDNSFirewallClusterRequest(string accountId, string name)
+			: base(accountId)
+		{
+			Name = name;
+		}
+
+		/// <summary>
+		/// DNS Firewall cluster name.
+		/// </summary>
+		public string Name { get; set; }
+	}
+}

src/Extensions/Cloudflare.Dns/Requests/DNSFirewallClusterRequestBase.cs

@@ -0,0 +1,93 @@
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Represents a request to create a DNS Firewall cluster with specific configuration settings.
+	/// </summary>
+	public abstract class DNSFirewallClusterRequestBase
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="CreateDNSFirewallClusterRequest"/> class.
+		/// </summary>
+		/// <param name="accountId">The account identifier.</param>
+		public DNSFirewallClusterRequestBase(string accountId)
+		{
+			AccountId = accountId;
+		}
+
+		/// <summary>
+		/// The account identifier.
+		/// </summary>
+		public string AccountId { get; set; }
+
+		/// <summary>
+		/// Upstream DNS server IPs.
+		/// </summary>
+		public IReadOnlyCollection<string>? UpstreamIps { get; set; }
+
+		/// <summary>
+		/// Attack mitigation settings.
+		/// </summary>
+		public AttackMitigation? AttackMitigation { get; set; }
+
+		/// <summary>
+		/// Whether to refuse to answer queries for the ANY type.
+		/// </summary>
+		public bool? DeprecateAnyRequests { get; set; }
+
+		/// <summary>
+		/// Whether to forward client IP (resolver) subnet if no EDNS Client Subnet is sent.
+		/// </summary>
+		public bool? EcsFallback { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// By default, Cloudflare attempts to cache responses for as long as indicated by the TTL received from upstream nameservers.
+		/// This setting sets an upper bound on this duration.
+		/// For caching purposes, higher TTLs will be decreased to the maximum value defined by this setting.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare returns to clients.
+		/// Cloudflare will always forward the TTL value received from upstream nameservers.
+		/// </para>
+		/// </summary>
+		public int? MaximumCacheTtl { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// By default, Cloudflare attempts to cache responses for as long as indicated by the TTL received from upstream nameservers.
+		/// This setting sets a lower bound on this duration.
+		/// For caching purposes, lower TTLs will be increased to the minimum value defined by this setting.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare returns to clients.
+		/// Cloudflare will always forward the TTL value received from upstream nameservers.
+		/// </para>
+		/// </summary>
+		/// <remarks>
+		/// Note that, even with this setting, there is no guarantee that a response will be cached for at least the specified duration.
+		/// Cached responses may be removed earlier for capacity or other operational reasons.
+		/// </remarks>
+		public int? MinimumCacheTtl { get; set; }
+
+		/// <summary>
+		/// <para>
+		/// This setting controls how long DNS Firewall should cache negative responses (e.g., NXDOMAIN) from the upstream servers.
+		/// </para>
+		/// <para>
+		/// This setting does not affect the TTL value in the DNS response Cloudflare returns to clients.
+		/// Cloudflare will always forward the TTL value received from upstream nameservers.
+		/// </para>
+		/// </summary>
+		public int? NegativeCacheTtl { get; set; }
+
+		/// <summary>
+		/// Ratelimit in queries per second per datacenter (applies to DNS queries sent to the upstream nameservers configured on the cluster).
+		/// </summary>
+		public int? RateLimit { get; set; }
+
+		/// <summary>
+		/// Number of retries for fetching DNS responses from upstream nameservers (not counting the initial attempt).
+		/// </summary>
+		public int? Retries { get; set; }
+	}
+}

src/Extensions/Cloudflare.Dns/Requests/UpdateDNSFirewallClusterRequest.cs

@@ -0,0 +1,29 @@
+namespace AMWD.Net.Api.Cloudflare.Dns
+{
+	/// <summary>
+	/// Represents a request to create a DNS Firewall cluster with specific configuration settings.
+	/// </summary>
+	public class UpdateDNSFirewallClusterRequest : DNSFirewallClusterRequestBase
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="CreateDNSFirewallClusterRequest"/> class.
+		/// </summary>
+		/// <param name="accountId">The account identifier.</param>
+		/// <param name="dnsFirewallId">DNS Firewall cluster name.</param>
+		public UpdateDNSFirewallClusterRequest(string accountId, string dnsFirewallId)
+			: base(accountId)
+		{
+			DnsFirewallId = dnsFirewallId;
+		}
+
+		/// <summary>
+		/// The DNS firewall cluster identifier.
+		/// </summary>
+		public string DnsFirewallId { get; set; }
+
+		/// <summary>
+		/// DNS Firewall cluster name.
+		/// </summary>
+		public string? Name { get; set; }
+	}
+}