New simplified API that supports converters

[ahx]

This is a follow-up of #207
This is another variant with new a API that could supports converters. I hope that this also simplifies the general API a bit as well.

I like this API overall, except of the "failure" case (see beneath). My question is:
Do we need an extra method that raises an error instead of returning a failure object? Using a bang method (like validate_request!) for that is not really idiomatic Ruby, but it's simple to use. Do you have any thoughts about this and the new interface?

definition = OpenapiFirst.load('./openapi/openapi.yaml')

# Validate a request

validated = definition.validate_request(rack_request) # Returns a validated request that can be either valid or invalid
validated.valid? # => true / false
# If converters are defined, these values are converted:
validated.params # => Hash of params or empty hash
validated.body # => Hash of body or empty hash
validated.query # => Hash of query params or empty hash
validated.headers # => Hash of headers or empty hash
validated.cookies # => Hash of cookies or empty hash
validated.path_params # => Hash of path params or empty hash

# Validate a response

validated = definition.validate_response(rack_request, rack_response)
validated.valid? # => true / false
# If converters are defined, these values are converted
validated.headers # => Hash of headers or empty hash
validated.body # => Hash of body or empty hash

I would like to support inspecting a failed validation as well as raising a meaningful exception. This could look like:

# Inspect failed validation
validated.failure # => Instance of Failure or nil. Call #raise to  raise an exception.
validated.failure&.raise # Raise an exception if invalid (for example RequestInvalidError or ResponseInvalidError) 🤔 

[supermomonga]

@ahx It looks nice!

Do we need an extra method that raises an error instead of returning a failure object? Using a bang method (like validate_request!) for that is not really idiomatic Ruby, but it's simple to use.

I like validated.failure than validate_request! method.

Do you have any thoughts about this and the new interface?

In this interface, If I only want to validate, should I reset all converters including default converters, manually?

or, can it have an option to opt-out converting, like this?

validated_and_converted =
  definition.validate_request(rack_request, apply_value_converter: true)
validated_and_not_converted =
  definition.validate_request(rack_request, apply_value_converter: false)

# default behavior. apply converters by default.
validated_and_converted = definition.validate_request(rack_request)

[ahx]

Can you share your use-case that requires opt-out of configured converters?
In general, I think having an option to opt-out looks good, but I would like to learn more about the use-case. My assumption was if I configure converters I always want them to run.
Thanks for the feedback, @supermomonga !

[supermomonga]

@ahx I had assumed that this gem would provide default custom converters such as DateTimeStringConverter so I thought some users prefer to use json_schemer's default behavior, but I realize that such design was not presented in your concept. Sorry, please forget about apply_value_converter option.

[MrBananaLord]

Do we need an extra method that raises an error instead of returning a failure object?

I just reviewed your last commits and it looks really good with the explicit raise_error

[ahx]

Thanks for looking into it @MrBananaLord . I would like to deprecate validate! in the long run.

But next up I would like to work on the converter feature, probably starting with finding an easy way to configure this.

[ahx]

This API has been released in 1.3.0. Converters are not implemented, yet.