support validating requests, responses against callbacks and webhooks - split up find_path usecases

[karenetheridge]

Most of the request and response validation can be applied equally well to descriptions in callbacks and webhooks -- just the initial bit where we take the request and call find_path on it to match the request URI against entries in /paths/{path description} doesn't apply here.

So, pull out the meat of the validation into separate subs which are called by multiple entry points - some of which would not require a path template for matching (instead, the inner sub takes the path-item location, which could be calculated by find_path or could be supplied directly, e.g. by an earlier call of validate_request that is processing a callback section.

[karenetheridge]

This will make it possible to call validate_response with just an operation_id, or path_item_path + http method. We don't care about the path template or path captures variables as they are not used for responses.

[karenetheridge]

In version 0.068, it is now possible to call validate_response purely by operation_id, without providing a request or providing a path_template value. This can be used to validate responses associated with a callback or webhook.

However, callback requests and webhook requests are not yet recognized by validate_request, as the request is still matched against path templates in /paths/*.

• add boolean webhook and callback parameters to the options hash, to allow the caller of validate_request, validate_response or find_path to indicate that the entity being validated does not correspond to an API under /paths/* but rather an out-of-band webhook. This would require the use of operation_id to actually find the operation in question in order to validate against it.

• for callbacks, things get more interesting, as we also would like to validate the individual parameters used in the callback definition... in this case, we need to have the original request that was used to initiate the callback, as that's what the templated parameters are expanded against... This should be pulled off into its own task (along with some helpers that can evaluate these templates, e.g. for request composition).

[karenetheridge]

Currently (version 0.074), we can handle validating responses for webhooks and callbacks by specifying the operationId. However, if we want to validate a request, we always attempt to match the request URI against all /paths/* entries, and this match will fail (or match the wrong thing). We need to skip the uri matching in this case, or use a different matching algorithm (in the case of callbacks we will be using other template variables).

We can handle validating requests if:

• we add a boolean to the global operationId registry, indicating if the operation is a webhook or callback; when set, we can skip the /paths/* matching against the request uri (and optionally add other matching instead)
• there are no path parameters defined for the path-item (because we have no path_template to use to extract $options->{path_captures}) OR the caller explicitly provides path_captures.

For webhooks specifically, if the openapi specification was modified such that /webhooks/$foo defined $foo as a path_template (just as for /paths/*), we could perform URI matching and path_captures extraction here as well. TODO: pursue this for moonwalk. Then, we could have a new interface validate_webhook_request which explicitly scans /webhooks/* instead of /paths/*, and does not require an operationId to be passed in (which would let us proactively identify that we're dealing with a webhook request and not a /paths api request).

For callbacks, it's more complicated as there is still an associated /paths api request/response associated, and we could be deep in the callback chain. Defer until later!