[http/openapi] Use enum-driven visibility analysis APIs

[witemple-msft]

This PR brings the core enum-driven visibility system to parity with the existing visibility concepts and uses its new analysis methods in the HTTP and OpenAPI libraries.

• Added lifecycle visibility modifiers for Delete and Query phases. Delete applies when a resource is passed as an argument to a DELETE operation. Query applies when a resource is passed as an argument to a GET or HEAD operation.
• Added lifecycle transform templates for Delete and Query.
• Made the logic of applying a visibility filter a little bit more robust. It will consider the any constraint of the filter to be satisfied if it is missing OR if some modifier in the constraint is present. If the any constraint is present, but empty, it will be unsatisfiable.
• Deprecated getParameterVisibility and getReturnTypeVisibility in favor of getParameterVisibilityFilter and getReturnTypeVisibilityFilter which return VisibilityFilter objects instead of string[]. Like the modifier analysis methods, the filter versions of these methods are infallible.
• getParameterVisibilityFilter and getReturnTypeVisibilityFilter accept a VisibilityProvider object that provides default visibility filters for parameters and return types if the parameter/returnType visibilities are not set explicitly. TypeSpec core exports an EmptyProvider that always return filters with no constraints, suitable as a default. HTTP exports HttpVisibilityProvider, which must be used when working in HTTP, as it provides the HTTP-specific default visibility logic that determines visibility by verb.
• HttpVisibilityProvider can be instantiated with either an HttpVerb directly, in which case that exact verb will be used; HttpOperationOptions, in which case the verbSelector will be used if present, otherwise the fallback logic will be used; or no argument in which case the fallback logic will always be used. This gives it parity with getHttpOperation.
• HTTP now marshals conversions between core visibility and HTTP Visibility through visibility filters instead of visibility string arrays. The HTTP Visibility concept is unchanged.
• Used new forms of visibility analysis APIs in openapi to detect read-only properties.
• Fixed a bug in http-server-csharp that was surfaced by these changes where a visibility constraint Visibility.Create & Visibility.Update was provided, resulting in Visibility.None and properties being made invisible, affecting effective type calculation for anonymous models. (invalidated by merge)
• Fixed a bug in which hasVisibility and getVisibilityForClass were improperly initializing the visibility state. This didn't affect the new APIs, but it would cause the state of the legacy APIs to be corrupted if visibility is queried from the new APIs before the legacy APIs.

Closes #5119
Closes #5120

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/http
• ✅ @typespec/openapi

Show changes

@typespec/http - internal ✏️

Updated the OpenAPI3 and HTTP libraries to use the new visibility analysis APIs.

@typespec/openapi - internal ✏️

Updated the OpenAPI3 and HTTP libraries to use the new visibility analysis APIs.

@typespec/compiler - feature ✏️

Added APIs for getting parameterVisibility and returnTypeVisibility as VisibilityFilter objects.

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs	🛝 VSCode Extension

[witemple-msft]

Validation PRs:

• Uptake enum-driven visibility for HTTP. Azure/typespec-azure#2057
• Validate uptake of http-enum-visibility Azure/azure-rest-api-specs#32043

[markcowl]

Also, one question: should we change the @parameterVisibility and @returnTypeVisibility decorators to accept enum visibility (or have I missed this being done previously?). Should we be clear that these are any filters?

Also, does @parameterVisibility() now effectively create an undefined any filter, meaning that all properties are allowed?

[markcowl]

The two deprecations on the operation visibility decorators will have to be approved by the breaking change review board. I will be surprised if anyone is using these filters, other than possibly the typespec-autorest emitter.

[witemple-msft]

There are no occurrences of getReturnTypeVisibility or getParameterVisibility within the packages folder of typespec-azure. I doubt anything other than typespec itself was using these APIs.

[markcowl]

same comment as above

[markcowl]

Do we want the default here to be to return a filter, so that this should be deprecated as well?

[witemple-msft]

Is this question about HttpVisibilityProvider or resolveRequestVisibility? If former, it will always return a filter. If latter, it would be severely breaking. I did consider it, but don't think we can really swallow deprecating the whole HTTP Visibility concept right now. I think instead of preemptively deprecating the HTTP-only Visibility, my hope is that if the core APIs are used in the next couple of months (i.e., people switch to using getReturnTypeVisibilityFilter(..., HttpVisibilityProvider) instead of resolveRequestVisibility or MetadataInfo, then HTTP's Visibility will become a vestigial feature that we can deprecate once some emitters have really proved that this analysis API works for their use case (I'm going to do this for the JS server emitter).

[witemple-msft]

@markcowl @returnTypeVisibility and @parameterVisibility were changed to accept EnumValue in the first patch. The core system does the same kind of normalization for them that it does for visibility modifiers on properties.

I can clarify that returnType/parameter visibility are specifying any constraints. The documentation for those decorators isn't clear about that right now. I considered adding an @returnTypeVisibilityFilter and @parameterVisibilityFilter decorator, but HTTP's visibility concept isn't expressive enough for that. Strictly speaking, the VisibilityProvider can return a visibility filter of any form, but HTTP only understands the any constraint (and only yields filters with the any constraint from its provider). If we decide to make HTTP work with other forms of visibility filters, or add the ability to put a generic filter on returnType/parameters in an operation, we will be compelled to rip Visibility out of the HTTP core or change it very significantly.

Good question on @parameterVisibility() with no arguments. It will effectively create a VisibilityFilter that has { any: new Set() }, which will actually allow nothing rather than everything (VisibilityFilter#any has the same semantics as Array.some, false for an empty array). I'll have to check what we did before, but I can easily make it so that if the list of modifiers was set to empty in the decorator it will return an empty filter rather than a filter with an empty any constraint. An empty filter with no constraints passes all properties, where a filter with an empty any constraint rejects all properties.