Add write-only headers and request bodies (Closes #115, #116)

Introduce headers_wo and request_body_wo on terracurl_request with version
attributes, private-state snapshots for read/destroy, and Terraform 1.11+ support.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: devops-rob

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.8.0
+
+ENHANCEMENTS:
+
+- Add write-only headers and request bodies on `terracurl_request` resources with `_wo_version` companions and private-state snapshots for read/destroy. Requires Terraform 1.11+. Closes #115, #116.
+
 ## 2.7.0
 
 ENHANCEMENTS:

docs/guides/default_headers.md

@@ -80,7 +80,7 @@ Provider headers win on key collision. This ensures a fresh provider token repla
 ## Limitations
 
 - Tokens set only in resource `headers` or `destroy_headers` are still persisted in state. For destroy-only refresh, move auth to `default_headers` or run `terraform apply` before destroy to update state.
-- Write-only resource headers (see issue #115) are a separate follow-up to avoid persisting secrets in state entirely.
+- Write-only resource headers (see the [Write-Only Headers and Request Bodies guide](write_only)) avoid persisting secrets in state entirely.
 - `default_headers` is marked sensitive in the provider schema and will not appear in plan output.
 
 ## Workaround without default_headers

docs/guides/digest_auth.md

@@ -87,7 +87,7 @@ If credentials are set only in `destroy_digest_auth`, those values are persisted
 
 - HTTP Basic authentication is not built in; set a static `Authorization: Basic ...` header manually or use provider `default_headers`.
 - NTLM, Kerberos, and other enterprise proxy authentication mechanisms remain unsupported. See the [HTTP Proxy Support guide](proxy).
-- Digest credentials configured on resources are stored in Terraform state (marked sensitive). Write-only credentials are tracked separately in issue #115.
+- Digest credentials configured on resources are stored in Terraform state (marked sensitive). For credentials that must not appear in state, use write-only headers or provider `default_headers` where applicable. See the [Write-Only Headers and Request Bodies guide](write_only).
 - Custom `realm` or algorithm tuning is not exposed unless a real API requires it.
 
 ## Digest vs default_headers

docs/guides/write_only.md

@@ -0,0 +1,82 @@
+---
+page_title: "Write-Only Headers and Request Bodies"
+subcategory: "Guides"
+description: |-
+  Use write-only headers and request bodies on terracurl_request resources to send secrets without persisting them in Terraform state.
+---
+
+# Write-Only Headers and Request Bodies
+
+Terraform 1.11+ supports **write-only arguments**: values supplied in configuration that are used during apply but are **not stored in plan or state JSON**. TerraCurl exposes this for `terracurl_request` resource headers and request bodies on create, read, and destroy operations.
+
+Use write-only attributes when secrets must not appear in `terraform show`, remote state, or version control–backed state files — even when marked `sensitive`.
+
+## Requirements
+
+- Terraform **1.11 or later**
+- `terracurl_request` **resource only** (write-only is not available on data sources, actions, or ephemeral resources)
+
+## Create example
+
+```terraform
+resource "terracurl_request" "example" {
+  name   = "example"
+  url    = "https://api.example.com/resource"
+  method = "PUT"
+
+  headers_wo = {
+    X-Vault-Token = var.vault_token
+  }
+  headers_wo_version = 1
+
+  request_body_wo = jsonencode({
+    password = var.password
+  })
+  request_body_wo_version = 1
+
+  response_codes = [200]
+  skip_read      = true
+}
+```
+
+Do **not** set both `headers` and `headers_wo` (or `request_body` and `request_body_wo`) on the same operation. TerraCurl rejects conflicting pairs at plan time.
+
+## Per-operation attributes
+
+| Operation | Headers | Body | Version attributes |
+|-----------|---------|------|--------------------|
+| Create | `headers_wo` | `request_body_wo` | `headers_wo_version`, `request_body_wo_version` |
+| Read | `read_headers_wo` | `read_request_body_wo` | `read_headers_wo_version`, `read_request_body_wo_version` |
+| Destroy | `destroy_headers_wo` | `destroy_request_body_wo` | `destroy_headers_wo_version`, `destroy_request_body_wo_version` |
+
+Version attributes are stored in state (not write-only). Increment a `_wo_version` when you change the corresponding write-only value so TerraCurl refreshes the snapshotted credentials on update.
+
+## Read and destroy without config access
+
+Terraform does not pass resource configuration to Read or Delete RPCs. TerraCurl **snapshots** read/destroy write-only values into provider private state during Create (and refreshes the snapshot on Update when a `_wo_version` changes). Private state is not shown in plan output, but it is persisted with the resource.
+
+For rotating destroy credentials without storing them in resource state, consider [provider `default_headers`](default_headers) instead.
+
+## Updating write-only values
+
+TerraCurl does not re-issue the create HTTP call on in-place update. To change a write-only body or header after initial apply:
+
+1. Update the write-only value in configuration
+2. Increment the matching `_wo_version` attribute
+3. Run `terraform apply`
+
+If the API must be called again with the new payload, trigger replacement through other attribute changes or taint the resource.
+
+## Comparison with other options
+
+| Approach | In state? | In plan? | Destroy refresh |
+|----------|-----------|----------|-----------------|
+| `headers` / `request_body` | Yes (sensitive still stored) | Hidden if sensitive | From state (can go stale) |
+| `headers_wo` / `request_body_wo` | No | No | From private snapshot |
+| Provider `default_headers` | No (provider config) | No | Re-evaluated every run |
+
+## Limitations
+
+- Resource-only; use `default_headers` or sensitive attributes on data sources, actions, and ephemeral resources
+- Private state snapshot is not zero-persistence storage
+- Digest credentials remain stateful today; write-only digest auth is future work

docs/index.md

@@ -163,4 +163,45 @@ resource "terracurl_request" "example" {
 }
 ```
 
+## Write-Only Headers and Request Bodies
+
+TerraCurl supports write-only `headers_wo` and `request_body_wo` attributes on `terracurl_request` resources (Terraform 1.11+). Values are sent on HTTP calls but are not stored in Terraform state.
+
+See the [Write-Only Headers and Request Bodies guide](guides/write_only) for version attributes, read/destroy private-state behavior, and comparison with `default_headers`.
+
+```terraform
+# Write-only headers and bodies require Terraform 1.11+.
+#
+# Values are used for HTTP calls but not stored in Terraform state.
+# Increment *_wo_version when changing a write-only value.
+
+resource "terracurl_request" "example" {
+  name   = "example"
+  url    = "https://httpbin.org/put"
+  method = "PUT"
+
+  headers_wo = {
+    Authorization = "Bearer ${var.api_token}"
+  }
+  headers_wo_version = 1
+
+  request_body_wo = jsonencode({
+    password = var.password
+  })
+  request_body_wo_version = 1
+
+  response_codes = [200]
+  skip_read      = true
+
+  destroy_url            = "https://httpbin.org/delete"
+  destroy_method         = "DELETE"
+  destroy_response_codes = [200]
+
+  destroy_headers_wo = {
+    Authorization = "Bearer ${var.api_token}"
+  }
+  destroy_headers_wo_version = 1
+}
+```
+
 ## Limitations

docs/resources/request.md

@@ -25,6 +25,8 @@ When `skip_read` is `false` and `read_url`, `read_method`, and `read_response_co
 
 ### Optional
 
+> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.
+
 - `ca_cert_directory` (String) Path to a directory on local disk that contains one or more certificate files that will be used to validate the certificate presented by the server
 - `ca_cert_file` (String) Path to a file on local disk that will be used to validate the certificate presented by the server
 - `cert_file` (String) Path to a file on local disk that contains the PEM-encoded certificate to present to the server
@@ -33,10 +35,14 @@ When `skip_read` is `false` and `read_url`, `read_method`, and `read_response_co
 - `destroy_cert_file` (String) Path to a file on local disk that contains the PEM-encoded certificate to present to the server for the destroy call
 - `destroy_digest_auth` (Attributes, Sensitive) HTTP Digest authentication credentials for the destroy request. Overrides provider `default_digest_auth` when configured. (see [below for nested schema](#nestedatt--destroy_digest_auth))
 - `destroy_headers` (Map of String) Map of headers to attach to the destroy API call. Host (case-insensitive) overrides the HTTP Host header sent on the wire, independent of the URL hostname.
+- `destroy_headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only headers for the destroy call. Snapshotted in provider private state for use during destroy.
+- `destroy_headers_wo_version` (Number) Increment to trigger refreshing snapshotted `destroy_headers_wo` values.
 - `destroy_key_file` (String) Path to a file on local disk that contains the PEM-encoded private key for which the authentication certificate was issued for the destroy call
 - `destroy_max_retry` (Number) Maximum number of tries until it is marked as failed for the destroy call
 - `destroy_method` (String) Destroy HTTP method to use in the API call
 - `destroy_request_body` (String) A request body to attach to the destroy API call
+- `destroy_request_body_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only request body for the destroy call. Not stored in Terraform state.
+- `destroy_request_body_wo_version` (Number) Increment to trigger applying an updated `destroy_request_body_wo` value.
 - `destroy_request_parameters` (Map of String) Map of parameters to attach to the destroy API call
 - `destroy_response_codes` (List of String) A list of expected response codes for the destroy call
 - `destroy_retry_interval` (Number) Interval between each attempt for the destroy call
@@ -45,6 +51,8 @@ When `skip_read` is `false` and `read_url`, `read_method`, and `read_response_co
 - `destroy_url` (String) Destroy API endpoint to call
 - `digest_auth` (Attributes, Sensitive) HTTP Digest authentication credentials for the create request. Overrides provider `default_digest_auth` when configured. (see [below for nested schema](#nestedatt--digest_auth))
 - `headers` (Map of String) Map of headers to attach to the API call. Host (case-insensitive) overrides the HTTP Host header sent on the wire, independent of the URL hostname.
+- `headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only headers for the create call. Not stored in Terraform state. Requires Terraform 1.11 or later.
+- `headers_wo_version` (Number) Increment to trigger applying updated `headers_wo` values.
 - `ignore_response_fields` (List of String) List of JSON fields to ignore during drift detection.
 - `key_file` (String) Path to a file on local disk that contains the PEM-encoded private key for which the authentication certificate was issued
 - `max_retry` (Number) Maximum number of tries until it is marked as failed
@@ -53,14 +61,20 @@ When `skip_read` is `false` and `read_url`, `read_method`, and `read_response_co
 - `read_cert_file` (String) Path to a PEM-encoded certificate for the read request (TLS).
 - `read_digest_auth` (Attributes, Sensitive) HTTP Digest authentication credentials for the read request. Overrides provider `default_digest_auth` when configured. (see [below for nested schema](#nestedatt--read_digest_auth))
 - `read_headers` (Map of String) Map of headers for the read request. Host (case-insensitive) overrides the HTTP Host header sent on the wire, independent of the URL hostname.
+- `read_headers_wo` (Map of String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only headers for the read call. Snapshotted in provider private state for drift detection.
+- `read_headers_wo_version` (Number) Increment to trigger refreshing snapshotted `read_headers_wo` values.
 - `read_key_file` (String) Path to a PEM-encoded private key for the read request (TLS).
 - `read_method` (String) HTTP method for reading resource state. Required if `skip_read` is false.
 - `read_parameters` (Map of String) Optional request parameters to add to the URL
 - `read_request_body` (String) Optional request body to use for the read request.
+- `read_request_body_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only request body for the read call. Snapshotted in provider private state for drift detection.
+- `read_request_body_wo_version` (Number) Increment to trigger refreshing snapshotted `read_request_body_wo` values.
 - `read_response_codes` (List of String) Expected response codes for the read request. Required if `skip_read` is false.
 - `read_skip_tls_verify` (Boolean) Skip TLS verification for the read request.
 - `read_url` (String) API endpoint for reading resource state. Required if `skip_read` is false.
 - `request_body` (String) A request body to attach to the API call
+- `request_body_wo` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Write-only request body for the create call. Not stored in Terraform state. Requires Terraform 1.11 or later.
+- `request_body_wo_version` (Number) Increment to trigger applying an updated `request_body_wo` value.
 - `request_parameters` (Map of String) Map of parameters to attach to the API call
 - `response_sensitive` (Boolean) Set to `true` to treat the response as sensitive. When enabled, the response body is written to `sensitive_response` (a sensitive attribute) and `response` is left empty so that secret values are not displayed in plan output. Defaults to `false` to preserve existing behavior.
 - `retry_interval` (Number) Interval between each attempt

examples/provider/write_only_example.tf

@@ -0,0 +1,32 @@
+# Write-only headers and bodies require Terraform 1.11+.
+#
+# Values are used for HTTP calls but not stored in Terraform state.
+# Increment *_wo_version when changing a write-only value.
+
+resource "terracurl_request" "example" {
+  name   = "example"
+  url    = "https://httpbin.org/put"
+  method = "PUT"
+
+  headers_wo = {
+    Authorization = "Bearer ${var.api_token}"
+  }
+  headers_wo_version = 1
+
+  request_body_wo = jsonencode({
+    password = var.password
+  })
+  request_body_wo_version = 1
+
+  response_codes = [200]
+  skip_read      = true
+
+  destroy_url            = "https://httpbin.org/delete"
+  destroy_method         = "DELETE"
+  destroy_response_codes = [200]
+
+  destroy_headers_wo = {
+    Authorization = "Bearer ${var.api_token}"
+  }
+  destroy_headers_wo_version = 1
+}