tftypes: Introduce unknown value refinement support for Value

[austinvalle]

Ref: hashicorp/terraform#30937
Ref: hashicorp/terraform-plugin-framework#869

---

This PR introduces value refinement support to the tftypes package. This allows Terraform providers to communicate unknown value refinements to/from Terraform core (Terraform 1.6+).

Value refinements are additional constraints that can be applied to unknown values in Terraform that can be used to produce known results from unknown values. For example, with value refinements, providers can now indicate specific attributes will "definitely not be null" during PlanResourceChange, which would allow Terraform core to successfully evaluate expressions like count during plan, rather than returning an error like:

│ Error: Invalid count argument
│
│ ...
│
│ The "count" value depends on resource attributes that cannot be
│ determined until apply, so Terraform cannot predict how many
│ instances will be created. To work around this, use the -target
│ argument to first apply only the resources that the count depends
│ on.

---

No changes to existing provider code will be necessary as partially unknown values will still evaluate the same as a wholly unknown value today.

TODOs left on this PR

• Design is still under review
• Changelogs

[austinvalle]

We can bikeshed the display of these attributes since there is no established pattern ATM (core displays the cty methods when showing data consistency errors, but doesn't have a "user friendly" version of the data defined). Other thoughts:

tftypes.String<unknown, refinements = [not null, prefix = "str://"]>

tftypes.String<unknown, will not be null, will have prefix "str://">

[apparentlymart]

There is a potential subtle hazard here that you can read more about in the code that deals with the hazard over in the cty implementation:

https://github.com/zclconf/go-cty/blob/main/cty/ctystrings/prefix.go#L29

To reframe that in more practical terms, the hazard is that if the promised string prefix is "hi" and then the final string is "hí" (that is: h, i, followed by U+0301 combining acute accent) then cty's model of strings as a sequence of grapheme clusters (as opposed to unicode scalar values) will mean that the final value isn't considered to conform to the refinement, which will probably cause Terraform to complain that the refinements were inconsistent.

I don't recall whether Terraform actually checks this as part of its plan/apply consistency checks, but even if Terraform doesn't immediately catch and reject it the broken promise could still cause problems downstream with anything that was relying on the initial refinement.

In cty I implemented a rather heavy rule that discards any trailing character that could potentially turn out to be the start of a multi-scalar-value sequence. I think that's probably overkill for the Terraform plugin libraries because these prefixes are presumably going to be chosen directly by the provider developer rather than the end-user anyway, and so it'd probably be sufficient to just warn about this in the documentation here.

To again make that more practical/concrete: it's fine and good to say NewStringPrefix("ami-") because - is not the start of any valid combining sequence. It's also fine to announce NewStringPrefix("ami") if the provider dev knows that the final string is definitely not going to have a combining diacritic after it, which would be true for an AWS AMI ID. Where things get messy is if the character immediately after the prefix is end-user-controlled and could potentially begin with a combining character.

[austinvalle]

Thanks for sharing that @apparentlymart! I've put this work down ATM, but I'll make a note for later to come back and decide what we want to do here. Like you said, at the very least documentation should be added.

I did run a quick test and Terraform does check the refinements during it's plan/apply data consistency check, so that's good!

--- FAIL: TestSchemaResource_basic (0.89s)
    /Users/austin.valle/code/terraform-provider-corner/internal/framework6provider/schema_resource_test.go:19: Step 1/1 error: Error running apply: exit status 1
        
        Error: Provider produced inconsistent result after apply
        
        When applying changes to framework_schema.test, provider
        "provider[\"registry.terraform.io/hashicorp/framework\"]" produced an
        unexpected new value: .prefix_test: final value cty.StringVal("hí") does not
        conform to planning placeholder
        cty.UnknownVal(cty.String).Refine().NotNull().StringPrefixFull("hi").NewValue().
        
        This is a bug in the provider, which should be reported in the provider's own
        issue tracker.