Merge pull request #161 from hookdeck/2025-07-01

feat: change connection rules schema from set to list & bump hookdeck api version to 2025-07-01

Author: leggetter

docs/data-sources/connection.md

@@ -33,7 +33,7 @@ data "hookdeck_connection" "example" {
 - `disabled_at` (String) Date the connection was disabled
 - `name` (String) A unique, human-friendly name for the connection
 - `paused_at` (String) Date the connection was paused
-- `rules` (Attributes Set) (see [below for nested schema](#nestedatt--rules))
+- `rules` (Attributes List) (see [below for nested schema](#nestedatt--rules))
 - `source_id` (String) ID of a source to bind to the connection
 - `team_id` (String) ID of the workspace
 - `updated_at` (String) Date the connection was last updated

docs/guides/rules.md

@@ -6,7 +6,37 @@ description: "Connection Rules"
 # Hookdeck Rules
 
 A rule is a piece of instructional logic that dictates the behavior of events
-routed through a connection. There are 4 types of rules in Hookdeck:
+routed through a connection.
+
+### Rule Execution Order
+
+The order of rules in the `rules` list matters. `filter_rule` and `transform_rule` blocks are executed sequentially in the order they are defined. This allows you to create powerful workflows, such as filtering a request *before* transforming it to avoid unnecessary processing.
+
+Other rule types, like `retry_rule` and `delay_rule`, are not affected by ordering, as their execution is not sequential.
+
+For example, you can define a `filter_rule` to run before a `transform_rule`:
+
+```hcl
+resource "hookdeck_connection" "my_connection" {
+  # ...
+  rules = [
+    {
+      filter_rule = {
+        body = {
+          json = jsonencode({ "status" = "active" })
+        }
+      }
+    },
+    {
+      transform_rule = {
+        transformation_id = hookdeck_transformation.my_transformation.id
+      }
+    }
+  ]
+}
+```
+
+There are 4 types of rules in Hookdeck:
 
 ## Retry rule
 

docs/guides/v1-to-v2-migration.md

@@ -0,0 +1,111 @@
+---
+page_title: "Migrating from v1.x to v2.x"
+description: "How to migrate from v1.x to v2.x of the Hookdeck Terraform Provider"
+---
+
+The Hookdeck API version `2025-07-01` introduces a [breaking change](https://hookdeck.com/docs/api#2025-07-01), [Transform](https://hookdeck.com/docs/transformations) and [Filter](https://hookdeck.com/docs/filters) rules in a connection are now **executed in the order defined**. Previously, the execution order was fixed: **Transform rules always ran before Filter rules**.
+
+Hookdeck has automatically migrated all existing rules to match the previous behavior (Transform before Filter). However, your **Terraform configuration may now show diffs** if it defines rules in a different order than what is stored remotely.
+
+This guide walks through how to adjust your configuration to match the new behavior.
+
+## Summary of Change
+
+- **What changed**: The `rules` list in a `hookdeck_connection` is now **ordered**. `transform_rule` and `filter_rule` blocks are executed in the order they appear.
+- **Which rules are affected**: Only `transform_rule` and `filter_rule` blocks respect the order. Other rule blocks (e.g., `retry_rule`, `delay_rule`) are not affected as their execution order is not important.
+- **Default behavior**: Existing Hookdeck connections have been migrated so that `transform_rule` blocks appear before `filter_rule` blocks in the `rules` list—preserving legacy behavior.
+- **Terraform implications**: If your configuration has a `filter_rule` before a `transform_rule`, Terraform will detect this as a change.
+
+## What You Should Do
+
+Update your Terraform `rules` definition to ensure `transform_rule` blocks come **before** `filter_rule` blocks, unless you intentionally want the new ordering behavior.
+
+### Example
+
+The `v1.x` provider introduced the `rules` attribute with the modern syntax for `filter_rule` and `transform_rule`. The breaking change in `v2.x` is that the *order* of these rules now matters.
+
+For example, if your configuration defined a `filter_rule` before a `transform_rule`:
+
+```hcl
+resource "hookdeck_transformation" "my_transformation" {
+  name = "my-transformation"
+  code = file("${path.module}/transformation.js")
+}
+
+resource "hookdeck_connection" "my_connection" {
+  # ... other attributes like source_id and destination_id
+
+  rules = [
+    {
+      // This filter rule runs first in the list...
+      filter_rule = {
+        body = {
+          // Using jsonencode is recommended for readability
+          json = jsonencode({
+            status = "active"
+          })
+        }
+      }
+    },
+    {
+      // ...followed by this transform rule.
+      transform_rule = {
+        transformation_id = hookdeck_transformation.my_transformation.id
+      }
+    }
+  ]
+}
+```
+
+Because Hookdeck automatically migrated existing connections to have `transform` rules run before `filter` rules, the above configuration will produce a `terraform plan` diff.
+
+To align your configuration with the migrated state and avoid the diff, you must reorder the rules in your file:
+
+```hcl
+resource "hookdeck_transformation" "my_transformation" {
+  name = "my-transformation"
+  code = file("${path.module}/transformation.js")
+}
+
+resource "hookdeck_connection" "my_connection" {
+  # ... other attributes like source_id and destination_id
+
+  rules = [
+    {
+      // The transform rule is now first, matching the legacy behavior.
+      transform_rule = {
+        transformation_id = hookdeck_transformation.my_transformation.id
+      }
+    },
+    {
+      // The filter rule is now second.
+      filter_rule = {
+        body = {
+          json = jsonencode({
+            status = "active"
+          })
+        }
+      }
+    }
+  ]
+}
+```
+
+This will preserve the same behavior as before the API update and resolve any `terraform plan` diffs.
+
+## Optional: Leverage the New Behavior
+
+This update also unlocks new use cases:
+
+- Run a **filter before a transformation** to skip unnecessary processing.
+- Use a transformation **after** a filter to clean up headers or payloads before delivery.
+
+If you're intentionally using the new ordering capability, no migration is needed—just ensure your rule order in Terraform matches your intended logic.
+
+## Final Notes
+
+- The Hookdeck provider does **not** modify rule order—your configuration must match your intended logic.
+- If you see diffs after upgrading, they are likely due to mismatched rule order and can be resolved by reordering locally.
+- The provider will output a warning message if it detects that your existing rule definitions have a filter rule before a transformation rule.
+
+For questions or help migrating, please [raise an issue on the Hookdeck Terraform Provider GitHub repo](https://github.com/hookdeck/terraform-provider-hookdeck/issues).

docs/resources/connection.md

@@ -71,7 +71,7 @@ resource "hookdeck_connection" "connection_example" {
 - `description` (String) Description for the connection
 - `disabled_at` (String) Date the connection was disabled
 - `name` (String) A unique, human-friendly name for the connection
-- `rules` (Attributes Set) (see [below for nested schema](#nestedatt--rules))
+- `rules` (Attributes List) (see [below for nested schema](#nestedatt--rules))
 
 ### Read-Only
 

examples/full/main.tf

@@ -115,10 +115,25 @@ resource "hookdeck_destination" "aws_destination" {
   })
 }
 
+resource "hookdeck_transformation" "example_transformation" {
+  name = "example_transformation"
+  code = <<EOT
+addHandler("transform", (request, context) => {
+  request.headers["example-header"] = "Hello World";
+  return request;
+});
+EOT
+}
+
 resource "hookdeck_connection" "first_connection" {
   source_id      = hookdeck_source.first_source.id
   destination_id = hookdeck_destination.first_destination.id
   rules = [
+    {
+      transform_rule = {
+        transformation_id = hookdeck_transformation.example_transformation.id
+      }
+    },
     {
       filter_rule = {
         headers = {
@@ -127,7 +142,7 @@ resource "hookdeck_connection" "first_connection" {
           })
         }
       }
-    }
+    },
   ]
 }
 

internal/provider/connection/resource.go

@@ -35,6 +35,7 @@ func (r *connectionResource) Metadata(_ context.Context, req resource.MetadataRe
 // Schema returns the resource schema.
 func (r *connectionResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Version:             1,
 		MarkdownDescription: "Connection Resource",
 		Attributes:          schemaAttributes(),
 	}

internal/provider/connection/schema.go

@@ -1,176 +1,9 @@
 package connection
 
 import (
-	"terraform-provider-hookdeck/internal/validators"
-
-	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
-	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
-	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
-	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
 )
 
 func schemaAttributes() map[string]schema.Attribute {
-	filterRulePropertySchema := schema.SingleNestedAttribute{
-		Optional: true,
-		Attributes: map[string]schema.Attribute{
-			"boolean": schema.BoolAttribute{
-				Optional: true,
-			},
-			"json": schema.StringAttribute{
-				Optional:    true,
-				Description: `Stringied JSON using our filter syntax to filter on request headers`,
-			},
-			"number": schema.NumberAttribute{
-				Optional: true,
-			},
-			"string": schema.StringAttribute{
-				Optional: true,
-			},
-		},
-		Validators: []validator.Object{
-			validators.ExactlyOneChild(),
-		},
-	}
-
-	return map[string]schema.Attribute{
-		"created_at": schema.StringAttribute{
-			Computed: true,
-			Validators: []validator.String{
-				validators.IsRFC3339(),
-			},
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.UseStateForUnknown(),
-			},
-			Description: "Date the connection was created",
-		},
-		"description": schema.StringAttribute{
-			Optional: true,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.UseStateForUnknown(),
-			},
-			Description: "Description for the connection",
-		},
-		"destination_id": schema.StringAttribute{
-			Required: true,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.RequiresReplace(),
-			},
-			Description: "ID of a destination to bind to the connection",
-		},
-		"disabled_at": schema.StringAttribute{
-			Computed: true,
-			Optional: true,
-			Validators: []validator.String{
-				validators.IsRFC3339(),
-			},
-			Description: "Date the connection was disabled",
-		},
-		"id": schema.StringAttribute{
-			Computed:    true,
-			Description: `ID of the connection`,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.UseStateForUnknown(),
-			},
-		},
-		"name": schema.StringAttribute{
-			Optional: true,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.UseStateForUnknown(),
-			},
-			Description: `A unique, human-friendly name for the connection`,
-		},
-		"paused_at": schema.StringAttribute{
-			Computed: true,
-			Validators: []validator.String{
-				validators.IsRFC3339(),
-			},
-			Description: "Date the connection was paused",
-		},
-		"rules": schema.SetNestedAttribute{
-			Optional: true,
-			NestedObject: schema.NestedAttributeObject{
-				Attributes: map[string]schema.Attribute{
-					"delay_rule": schema.SingleNestedAttribute{
-						Optional: true,
-						Attributes: map[string]schema.Attribute{
-							"delay": schema.Int64Attribute{
-								Required:    true,
-								Description: `Delay to introduce in MS`,
-							},
-						},
-					},
-					"filter_rule": schema.SingleNestedAttribute{
-						Optional: true,
-						Attributes: map[string]schema.Attribute{
-							"body":    filterRulePropertySchema,
-							"headers": filterRulePropertySchema,
-							"path":    filterRulePropertySchema,
-							"query":   filterRulePropertySchema,
-						},
-						Validators: []validator.Object{
-							validators.AtLeastOneChild(),
-						},
-					},
-					"retry_rule": schema.SingleNestedAttribute{
-						Optional: true,
-						Attributes: map[string]schema.Attribute{
-							"count": schema.Int64Attribute{
-								Optional:    true,
-								Description: `Maximum number of retries to attempt`,
-							},
-							"interval": schema.Int64Attribute{
-								Optional:    true,
-								Description: `Time in MS between each retry`,
-							},
-							"strategy": schema.StringAttribute{
-								Required: true,
-								Validators: []validator.String{
-									stringvalidator.OneOf(
-										"linear",
-										"exponential",
-									),
-								},
-								MarkdownDescription: `must be one of ["linear", "exponential"]` + "\n" +
-									`Algorithm to use when calculating delay between retries`,
-							},
-						},
-					},
-					"transform_rule": schema.SingleNestedAttribute{
-						Optional: true,
-						Attributes: map[string]schema.Attribute{
-							"transformation_id": schema.StringAttribute{
-								Required:    true,
-								Description: `ID of the attached transformation object.`,
-							},
-						},
-					},
-				},
-				Validators: []validator.Object{
-					validators.ExactlyOneChild(),
-				},
-			},
-		},
-		"source_id": schema.StringAttribute{
-			Required: true,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.RequiresReplace(),
-			},
-			Description: `ID of a source to bind to the connection`,
-		},
-		"team_id": schema.StringAttribute{
-			Computed: true,
-			PlanModifiers: []planmodifier.String{
-				stringplanmodifier.UseStateForUnknown(),
-			},
-			Description: `ID of the workspace`,
-		},
-		"updated_at": schema.StringAttribute{
-			Computed: true,
-			Validators: []validator.String{
-				validators.IsRFC3339(),
-			},
-			Description: `Date the connection was last updated`,
-		},
-	}
+	return schemaAttributesV1()
 }