github.com/zclconf/go-cty

• cty: IndexStep.Apply will no longer panic if given a marked collection to traverse through. (#160).

• function: If a function parameter that doesn't declare AllowDynamicType: true recieves a cty.DynamicVal, the function system would previously just skip calling the function's Type callback and treat the result type as unknown. However, the Call method was then still calling a function's Impl callback anyway, which violated the usual contract that Type acts as a guard for Impl so Impl doesn't have to repeat type-checking already done in Type: it's only valid to call Impl if Type was previosly called and it succeeded.

  The function system will now skip calling Impl if it skips calling Type, immediately returning cty.DynamicVal in that case. Individual functions can opt out of this behavior by marking one or more of their parameters as AllowDynamicType: true and then handling that situation manually inside the Type and Impl callbacks.

  As a result of this problem, some of the function/stdlib functions were not correctly handling cty.DynamicVal arguments after being extended to support refinements in the v1.13.0 release, causing unexpected errors or panics when calling them. Those functions are fixed indirectly by this change, since their callbacks will no longer run at all in those cases, as was true before they were extended to support refinements.

Upgrade Notes

This release introduces a new concept called Refinements, which allow cty to constrain the range of an unknown value beyond just a type constraint and then make deductions about validity or result range based on those refinements.

These changes are consistent with the backward-compatibility policy but you may see some changed results in your unit tests of operations involving unknown values. If the new results don't seem like valid refinements of what was previously being returned in the v1.12 series, please open an issue to discuss that.

If the new results have a range that is a valid subset of the old results then that is expected behavior and you should update your tests as part of upgrading.

Other changes in this release

• Refinements: cty will can track a refined range for some unknown values and will take those into account when evaluating certain operations, thereby allowing a "more known" result than before. (#153)

• function/stdlib: The FormatDate and TimeAdd functions in previous releases were accidentally more liberal than intended in their interpretation of timestamp strings documented as requiring RFC3339. (#152)

  Those functions are now corrected to use a stricter RFC3339 parser, meaning that they will now reject some inputs that were previously accepted but were not valid per the RFC3339 syntax rules. The documentation for these functions already specified that RFC3339 syntax was required and so this is a fix to a defect rather than a breaking change, but calling applications which embed these functions may wish to pass on an upgrade note about this behavior difference in their own releaase notes after upgrading.

• convert: Will now produce correct type constraints when the input value is an empty collection and the target element type has optional attributes. In this case the conversion process must remove the optional attribute annotations because those are only for type conversion purposes and have no meaning when used in the type constraint for an empty collection. (#143)
• convert: Will now prefer to retain a concrete type in the input value when the input is either null or unknown and the target type is cty.DynamicPseudoType, which represents "any type". (#144)

• function: Each function can now have an English-language description summarizing its behavior. This is intended as a default string to use when an application wants to provide code hover tips or similar development aids. However, these descriptions are basic and only available in English, so applications may still prefer to provide their own descriptions and ignore those encoded in this module. (#137)

• convert: When running in "unsafe mode" (which allows additional conversions that can potentially fail with certain input values), we'll now allow converting from a map type to an object type with optional attributes as long as all of the present map elements are compatible with their corresponding optional attributes.

  It's still a dynamic error to convert a map whose element type is incompatible with any of the attributes that do have corresponding keys in the given map. (#139)

• convert: Will now produce correct type constraints when the input value is null and the target type has optional attributes. In this case the conversion process must remove the optional attribute annotations because those are only for type conversion purposes and have no meaning when used in the type constraint for a null or unknown value. (#140, #141)

• convert: Fix for error when converting empty sets and lists with nested optional attributes by explicitly removing optional attribute information from collections.

Upgrade Notes

This release contains some changes to some aspects of the API that are either legacy or de-facto internal (from before the Go toolchain had an explicit idea of that). Any external module using these will experience these as breaking changes, but we know of no such caller and so are admitting these without a major release in the interests of not creating churn for users of the main API.

• encoding/gob support utilities removed: we added these as a concession to HashiCorp who wanted to try to send cty values over some legacy protocols/formats used by legacy versions of HashiCorp Terraform. In the end those efforts were not successful for other reasons and so no Terraform release ever relied on this functionality.

  encoding/gob support has been burdensome due to how its unmarshaler interface is defined and so cty values and types are no longer automatically compatible with encoding/gob. Callers should instead use explicitly-implemented encodings, such as the built-in JSON and msgpack encodings or external libraries which use the public cty API to encode and decode.

• cty now requires Go 1.18: although the main API is not yet making any use of type parameters, we've begun to adopt it in the hope of improving the maintainability of some internal details, starting with the backing implementation of set types.

  Since type parameters are not supported by earlier versions of the Go compiler, callers must upgrade to Go 1.18 before using cty v1.11.0 or later.

Other changes in this release

• cty: Improved performance when comparing nonzero numbers to zero, by performing a relatively-cheap sign check on both numbers before falling back on the more expensive general equality implementation. (#125)
• cty: It's now possible to use capsule types in the elements of sets. Previously cty would panic if asked to construct a value of a set type whose element type either is or contains a capsule type, but there is now explicit support for storing encapsulated values in sets and optional (but recommended) support for a custom hashing function per type in order to improve performance for sets with a large number of elements.
• convert: Unify will no longer panic when asked to find a common base type for a tuple type and a list of unknown element type, and will instead just signal that such a unification is not possible. (#126)
• stdlib: FlattenFunc will no longer panic if it encounters a null value of a type that would normally be subject to flattening. Instead, it will treat it in the same way as a null value of any non-flattenable type. (#129)