Enhancing API Logic Handling, Bug Fixes and Error handling improvements

Added optional reference property to security rules so the extension can track Cloudflare’s ref reliably across deploys.

Adjusted security-rule lookup to match on ref and expression first, reducing accidental hits from reused descriptions.

Set a custom User-Agent and added retry/backoff for 429/5xx responses to make API calls more resilient.

Wrapped JSON deserialization with contextual error messages so malformed API responses are easier to diagnose.

Verified DNS deployments now ensure the supplied zoneName now actually matches the resolved zone ID before upsert

Author: riosengineer

README.md

@@ -74,6 +74,7 @@ resource blockCountryTraffic 'SecurityRule' = {
   expression: '(ip.src.country eq "CN")'
   action: 'block'
   enabled: true
+  reference: 'block-country-cn' // Unique ref 
 }
 
 output recordName string = txtRecord.name
@@ -83,6 +84,7 @@ output securityRuleId string = blockCountryTraffic.ruleId
 
 > [!NOTE]
 > The `SecurityRule` resource maps to the Cloudflare [Security Rules](https://developers.cloudflare.com/security/rules/) API and supports the free plan feature set.
+> Specify the optional `reference` property when you need a custom Cloudflare identifier; the extension otherwise defaults it to the resource name on first deploy.
 
 For comprehensive usage examples, please refer to the [`Sample/`](Sample/) directory in this repository.
 

docs/idempotency.md

@@ -9,8 +9,8 @@ The extension keeps repeated `bicep local-deploy` executions safe by reusing exi
 
 ## Security Rules
 
-- On the first deploy a rule is created with a stable `ref` value matching the resource name, so future runs can find it.
-- Each update first attempts a lookup by rule name/description; if that fails, it falls back to downloading a paged rule list for the zone.
+- On the first deploy the rule receives a stable `ref` value (by default the resource name, or the optional `reference` property if supplied).
+- Each update tries to line up with existing rules by matching `ref` and expression before falling back to names/descriptions; if nothing matches, it downloads a paged rule list for the zone.
 - When a matching rule is found, the existing `ruleId` (and filter) are reused and a `PUT` updates the rule. New rules are created with `POST` calls.
 
 Whilst this has a performance hit, it stops subsequent template deployments failing entirely which is a better compromise at this stage.

docs/securityrule.md

@@ -6,7 +6,7 @@ Manages a Cloudflare Security Rule
 
 ### Block traffic from Country
 
-Creates a security rule that blocks requests originating from example Country using the free plan API.
+Creates a security rule that blocks requests originating from China using the free plan API.
 
 ```bicep
 resource blockCountryTraffic 'SecurityRule' = {
@@ -29,5 +29,6 @@ The following arguments are available:
 - `zoneId` - (Required) The zone ID this rule applies to
 - `description` - (Optional) Human friendly description shown in the Cloudflare dashboard
 - `enabled` - (Optional) Whether the rule is enabled (set to false to pause the rule)
+- `reference` - (Optional) Reference identifier persisted with the rule; defaults to the resource name on first deploy and cannot be changed by the Cloudflare API afterwards
 - `filterId` - (Optional) Cloudflare filter ID associated with this security rule (output only)
 - `ruleId` - (Optional) Cloudflare security rule ID (output only)

src/Handlers/CloudFlareDnsRecordHandler.cs

@@ -37,6 +37,16 @@ protected override async Task<ResourceResponse> CreateOrUpdate(ResourceRequest r
                 }
             }
 
+            var normalizedInputZone = request.Properties.ZoneName?.Trim().TrimEnd('.') ?? string.Empty;
+            if (!string.IsNullOrWhiteSpace(request.Properties.ZoneId))
+            {
+                var zone = await apiService.GetZoneAsync(normalizedInputZone, cancellationToken);
+                if (zone is not null && !string.Equals(zone.Name, normalizedInputZone, StringComparison.OrdinalIgnoreCase))
+                {
+                    throw new InvalidOperationException($"Zone name '{request.Properties.ZoneName}' does not match the CloudFlare zone '{zone.Name}' (ID {request.Properties.ZoneId}).");
+                }
+            }
+
             var createdRecord = await apiService.UpsertDnsRecordAsync(request.Properties, cancellationToken);
 
             // Update properties with the created record data

src/Handlers/CloudFlareSecurityRuleHandler.cs

@@ -23,6 +23,15 @@ protected override async Task<ResourceResponse> CreateOrUpdate(ResourceRequest r
                 request.Properties.Description = request.Properties.Name;
             }
 
+            if (string.IsNullOrWhiteSpace(request.Properties.Reference))
+            {
+                request.Properties.Reference = request.Properties.Name.Trim();
+            }
+            else
+            {
+                request.Properties.Reference = request.Properties.Reference.Trim();
+            }
+
             var config = Configuration.GetConfiguration();
             using var apiService = new CloudFlareApiService(config);
 
@@ -36,6 +45,10 @@ protected override async Task<ResourceResponse> CreateOrUpdate(ResourceRequest r
                     {
                         request.Properties.FilterId = existingRule.Filter.Id;
                     }
+                    if (!string.IsNullOrWhiteSpace(existingRule.Ref))
+                    {
+                        request.Properties.Reference = existingRule.Ref;
+                    }
                 }
             }
 
@@ -55,6 +68,7 @@ protected override async Task<ResourceResponse> CreateOrUpdate(ResourceRequest r
             request.Properties.Action = updatedRule.Action;
             request.Properties.Enabled = updatedRule.Enabled;
             request.Properties.Description = updatedRule.Description;
+            request.Properties.Reference = updatedRule.Reference;
 
             return GetResponse(request);
         }

src/Models/CloudFlareModels.cs

@@ -200,4 +200,7 @@ public class CloudFlareSecurityRule : CloudFlareSecurityRuleIdentifiers
 
     [TypeProperty("Cloudflare filter ID associated with this security rule (output only)")]
     public string? FilterId { get; set; }
+
+    [TypeProperty("Optional reference identifier persisted with the rule; defaults to the resource name on create")]
+    public string? Reference { get; set; }
 }