Enforce visibility struct tags

[mbarnes]

What this PR does

This enforces property visibility when creating or updating ARO-HCP resource types to comply with the OpenAPI spec. The implementation encodes property visibility as struct tags.

The autorest-generated API models have the useful characteristic of all struct fields being pointers. This allows us to identify which properties were explicitly provided in a create or update request.

However the generated models do not have property metadata encoded into struct tags, and we can't (or shouldn't) modify the generated models to add such information.

To get around this limitation, struct tags for property visibiility are encoded into the internal API models, which are not generated. The internal API models are of different Go types than the generated API models and are therefore not compatible, however the field names in each set of models are identical where property visibility is explicit (as opposed to implicitly inherited from parent types).

We can therefore build a lookup table of visibility struct tags by field name to use when evaluating create and update requests using the generated API models. We call this table a StructTagMap:

type StructTagMap map[string]reflect.StructTag

where the map keys are dotted struct field names (e.g. "A.B.C.D").

Then, while recursing over a generated API model type, we keep track of struct field names in order to build lookup keys for the table. This effectively allows struct tags from one Go type to be grafted on to another similar but incompatible Go type.

Jira: ARO-6347 : Validate metadata from api structs
Link to demo recording:

Special notes for your reviewer

Supporting documentation:

• TypeSpec Azure - Property Visibility and Other Constraints
• Microsoft Azure REST API Guidelines - Resource Schema & Field Mutability

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Deployment: The deployment process was considered and addressed if required
• Testing: New code requires new unit tests.
• Documentation: Is the documentation updated? Either in the doc located in focus area, in the README or in the code itself.
• Customers: Is this change affecting customers? Is the release plan considered?

[mbarnes]

@bennerv asked me (on Slack) about how we'd handle a potential field visibility change in future APIs out of concern that the metadata is on the internal structs. I wanted to address that here.

It's worth noting this type of change has never occurred on ARO Classic, so it's likely to be rare here too. But we can't discount it.

Suppose API versions v1-v4 (simplifying the version IDs for the sake of discussion) all had some field "foo" that was tagged @visibility("read", "create") in the OpenAPI spec.

Then v5 comes along and changes field "foo" to be @visibility("read", "create", "update").

Here's how I would handle that:

• Update the struct tag for field "foo" in the internal API to be visibility:"read create update". Visibility is now correct for v5 and subsequent versions.

• Each of the API packages for v1-v4 will have their own StructTagMap instances.

package v1 (or v2 or v3 or v4)

var clusterStructTagMap = api.NewStructTagMap[api.HCPOpenShiftCluster]()

• We would need to override the clusterStructTagMap for field "foo" in each of these older API packages to restore the original visibility for field "foo".

func init() {
        ...

        // This field was changed in v5 to be "read create update".
        clusterStructTagMap["Properties.Spec.Foo"] = reflect.StructTag("visibility:\"read create\"")
}

[mjlshen]

The proposed mitigation for api visibility changes makes sense to me as well.