Refactor firewall backends into dedicated resources

Author: damacus

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ name: ci
 
 jobs:
   lint-unit:
-    uses: sous-chefs/.github/.github/workflows/lint-unit.yml@6.0.0
+    uses: sous-chefs/.github/.github/workflows/lint-unit.yml@8.0.0
     permissions:
       checks: write
       pull-requests: write
@@ -192,7 +192,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
       - name: Install Cinc Workstation
-        uses: sous-chefs/.github/.github/actions/install-workstation@6.0.0
+        uses: sous-chefs/.github/.github/actions/install-workstation@8.0.0
       - name: Dokken
         uses: actionshub/test-kitchen@3.0.0
         env:

.github/workflows/conventional-commits.yml

@@ -11,6 +11,6 @@ name: conventional-commits
 
 jobs:
   conventional-commits:
-    uses: sous-chefs/.github/.github/workflows/conventional-commits.yml@6.0.0
+    uses: sous-chefs/.github/.github/workflows/conventional-commits.yml@8.0.0
     permissions:
       pull-requests: read

.github/workflows/prevent-file-change.yml

@@ -11,7 +11,7 @@ name: prevent-file-change
 
 jobs:
   prevent-file-change:
-    uses: sous-chefs/.github/.github/workflows/prevent-file-change.yml@6.0.0
+    uses: sous-chefs/.github/.github/workflows/prevent-file-change.yml@8.0.0
     permissions:
       pull-requests: write
     secrets:

.github/workflows/release.yml

@@ -16,7 +16,7 @@ permissions:
 
 jobs:
   release:
-    uses: sous-chefs/.github/.github/workflows/release-cookbook.yml@6.0.0
+    uses: sous-chefs/.github/.github/workflows/release-cookbook.yml@8.0.0
     secrets:
       token: ${{ secrets.PORTER_GITHUB_TOKEN }}
       supermarket_user: ${{ secrets.CHEF_SUPERMARKET_USER }}

README.md

@@ -101,11 +101,12 @@ The most basic use involves two resources, `firewall` and `firewall_rule`. The
 typical usage scenario is as follows:
 
 * declare the `firewall` resource named `'default'`, which installs appropriate packages and configures services to start on boot and starts them.
-* run the `:create` action on every `firewall_rule` resource, which routes to the selected backend resource. How the rules are implemented depends on the firewall backend:
-  * **firewalld**: `firewall_rule` creates firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html) in the system's default zone.
+* run the `:create` action on every `firewall_rule` resource, which routes to the selected backend rule resource. How the rules are implemented depends on the firewall backend:
+  * **firewalld**: `firewall_rule` routes to `firewalld_rule`, which creates firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html) in the system's default zone.
   * **nftables**: `firewall_rule` routes to `nftables_rule`.
-  * **iptables, ufw, windows**: `firewall_rule` routes to the matching backend rule resource, which automatically sends a delayed notification to the `firewall['default']` resource to run the `:restart` action.
-    * when the delayed `:restart` notification on the `firewall` resource fires, if any rules are different than the last run, the provider will update the current state of the firewall rules to match the expected rules.
+  * **iptables, ufw, windows**: `firewall_rule` routes to the matching backend rule resource.
+* backend rule resources notify their matching backend resource, such as `iptables['default']`, `ufw['default']`, `nftables['default']`, or `windows_firewall['default']`, to rebuild delayed.
+  * when the delayed backend rebuild fires, if any rules are different than the last run, the backend resource updates the current firewall rules to match the expected rules.
 
 There is a fundamental mismatch between the idea of a Chef action and the action that should be taken on a firewall
 rule. For this reason, the Chef action for a `firewall_rule` may be `:create` (the rule should be present in the
@@ -159,9 +160,10 @@ Please read the documentation for the
 ## firewalld
 
 For most rules it's sufficient to simply use the `firewall_rule` resource which is a platform-agnostic way to add
-firewall rules. On firewalld systems it adds rules to the default zone as firewalld [rich
-rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html). See the
-[`firewall_rule`](#firewall_rule) section for examples.
+firewall rules. On firewalld systems it routes to `firewalld_rule`, which adds rules to the default zone as firewalld
+[rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html). Use `firewalld_rule`
+directly when you want the portable firewalld rule interface, and use `firewalld_rich_rule` when you want to pass
+native rich-rule properties.
 
 See the [`firewalld` resources](documentation/README.md) documentation for advanced firewalld configuration.
 
@@ -178,7 +180,7 @@ recipe and attribute API.
 Declare this resource before adding your desired `firewall_rule` resources. See
 the [`firewall_rule`](#firewall_rule) section for examples.
 
-***NB***: The name 'default' of this resource is important as it is used for firewall_rule providers to locate the firewall resource. If you change it, you must also supply the same value to any firewall_rule resources using the `firewall_name` parameter.
+***NB***: The name 'default' of this resource is important as it is used for `firewall_rule` to locate the matching backend resource. If you change it, you must also supply the same value to any `firewall_rule` resources using the `firewall_name` parameter.
 
 #### Actions
 
@@ -220,7 +222,7 @@ end
 
 #### Actions
 
-* `:create`: Create the firewall rule and notify the firewall to reload after the rule has been saved. On firewalld systems, the rules are added to the default zone as firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html).
+* `:create`: Create the firewall rule through the selected backend rule resource. On firewalld systems, rules are routed through `firewalld_rule` and added to the default zone as firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html).
 
 #### Properties
 
@@ -247,15 +249,15 @@ firewall_rule 'name' do
   stateful        Symbol, Array     # Firewall: iptables, nftables, ufw
   raw             String            # Firewall: iptables, nftables, ufw
   direction       Symbol            # Firewall: iptables, nftables, ufw, windows. Default: :in
-  notify_firewall true, false       # Firewall: iptables, nftables, ufw, windows. Default: true
+  notify_firewall true, false       # Notify selected backend to apply rules. Default: true
   program         String            # Firewall: windows
   service         String            # Firewall: windows
 end
 ```
 
 Firewall-agnostic properties that can be used with `firewall_rule` on any firewall system:
 
-* `firewall_name`: the matching firewall resource that this rule applies to. Default value: `default`
+* `firewall_name`: the matching `firewall` facade and backend resource name that this rule applies to. Default value: `default`
 * `description` (*default: same as rule name*): Used to provide a comment that will be included when adding the firewall rule.
 * `command`: What action to take on a particular packet
    * `:allow` (*default action*): the rule should allow matching packets
@@ -287,8 +289,8 @@ Additional properties for advanced firewall rules that are tied to specific fire
 * `raw` (*iptables, nftables, ufw*): Used to pass an entire rule as a string, omitting all other parameters. This line will be directly loaded by `iptables-restore`, included in the nftables ruleset, or fed directly into `ufw` on the command line.
 * `direction` (*iptables, nftables, ufw, windows*): Direction of the rule. Valid values are: `:in` (*default*), `:out`, `:pre`,
 `:post`.
-* `notify_firewall` (*iptables, nftables, ufw, windows*): Notify the firewall to recalculate (and potentially reapply) the
-  `firewall_rule`(s) it finds. Default: `true`
+* `notify_firewall` (*iptables, nftables, ufw, windows*): Notify the selected backend resource to recalculate (and
+  potentially reapply) the `firewall_rule`(s) it finds. Default: `true`
 
 #### Examples
 

documentation/README.md

@@ -10,6 +10,7 @@
 * [firewalld_icmptype](resources/firewalld_icmptype.md)
 * [firewalld_ipset](resources/firewalld_ipset.md)
 * [firewalld_policy](resources/firewalld_policy.md)
+* [firewalld_rule](resources/firewalld_rule.md)
 * [firewalld_rich_rule](resources/firewalld_rich_rule.md)
 * [firewalld_service](resources/firewalld_service.md)
 * [firewalld_zone](resources/firewalld_zone.md)

documentation/firewall_firewall.md

@@ -1,14 +1,14 @@
 # firewall
 
-The `firewall` resource installs, enables, disables, and rebuilds a platform
-firewall backend.
+The `firewall` resource is a compatibility facade that delegates install,
+reload, disable, flush, and rebuild actions to the selected backend resource.
 
 ## Actions
 
 | Action     | Description                                                       |
 | ---------- | ----------------------------------------------------------------- |
 | `:install` | Install and enable the selected firewall backend.                 |
-| `:restart` | Rebuild and apply rules collected from `firewall_rule` resources. |
+| `:restart` | Rebuild and apply rules through the selected backend resource.     |
 | `:reload`  | Reload firewalld, or rebuild non-firewalld backends.              |
 | `:disable` | Disable the selected firewall backend.                            |
 | `:flush`   | Flush runtime rules where the selected backend supports it.       |

documentation/firewall_firewall_rule.md

@@ -1,7 +1,8 @@
 # firewall_rule
 
 The `firewall_rule` resource creates backend-agnostic firewall rules and
-notifies the named `firewall` resource to apply them.
+routes them to the backend rule resource selected by the named `firewall`
+resource.
 
 ## Actions
 
@@ -13,7 +14,7 @@ notifies the named `firewall` resource to apply them.
 
 | Property          | Type                  | Default       | Description                                                                 |
 | ----------------- | --------------------- | ------------- | --------------------------------------------------------------------------- |
-| `firewall_name`   | String                | `default`     | Name of the `firewall` resource to notify.                                  |
+| `firewall_name`   | String                | `default`     | Name shared by the `firewall` facade and selected backend resource.          |
 | `command`         | Symbol                | `:allow`      | One of `:reject`, `:allow`, `:deny`, `:masquerade`, `:redirect`, or `:log`. |
 | `protocol`        | Integer, Symbol       | `:tcp`        | Protocol for the rule.                                                      |
 | `source`          | String                |               | Source address.                                                             |
@@ -34,7 +35,7 @@ notifies the named `firewall` resource to apply them.
 | `program`         | String                |               | Windows program match.                                                      |
 | `service`         | String                |               | Windows service match.                                                      |
 | `raw`             | String                |               | Raw backend rule.                                                           |
-| `notify_firewall` | true, false           | `true`        | Notify the firewall resource to apply rules.                                |
+| `notify_firewall` | true, false           | `true`        | Notify the backend resource to apply rules.                                 |
 
 ## Examples
 

documentation/resources/firewalld_rule.md

@@ -0,0 +1,32 @@
+# firewalld_rule
+
+The `firewalld_rule` resource is the firewalld backend implementation for the
+portable `firewall_rule` API. It translates common firewall rule properties into
+`firewalld_rich_rule` declarations.
+
+Use `firewalld_rule` directly when you want the portable rule shape on a
+firewalld-only cookbook. Use `firewalld_rich_rule` when you want to model native
+firewalld rich-rule properties directly.
+
+## Actions
+
+| Action    | Description                          |
+| --------- | ------------------------------------ |
+| `:create` | Create the matching firewalld rule. |
+
+## Examples
+
+```ruby
+firewalld_rule 'ssh' do
+  port 22
+  command :allow
+end
+```
+
+```ruby
+firewalld_rule 'redirect ssh' do
+  command :redirect
+  source_port 2222
+  redirect_port 22
+end
+```