Smarter auto fallback

[ahopkins]

This relates back to the error formatting from #1937.

It adds:

• error_format on @app.route and convenience methods
• smarter "auto" check

At startup, every route will now have an error_format assigned to it. This can be configured at the route level (perhaps we can think about adding it at Blueprint or BlueprintGroup).

@app.route(..., error_format="text")

If it is not set, then it will use the value of FALLBACK_ERROR_FORMAT, which can be set to "text", "json", "html", or "auto". It will now default to "auto".

---

What does auto do now? Previously it would try and look at the incoming headers and make a guess by looking at the request content-type and request body (for json).

Now, it at startup it will evaluate the returns of the route handlers and look for text(), json(), html(), etc. It is still not perfect obviously. And, I think we still might want to add a check incoming Accept headers to make sure the selection makes sense.

If auto does not come up with a guess it will fallback HTMLRenderer, which can be reconfigured if you use your own base Config (see #2119).

---

TODO:

• Make sure that FALLBACK_ERROR_FORMAT is a proper value
• Tests
• Check incoming headers (pushed to RFC: Accept header parsing #2171)

[Tronic]

What does auto do now? Previously it would try and look at the incoming headers and make a guess by looking at the request content-type and request body (for json).

Should be using the accept header instead:

• If it includes (starts with, even) text/html: HTML
• If it includes application/json: JSON
• Else (it is probably */* the default of curl, wget and fetch):
  • check content-type for application/json: JSON (Note 1!)
  • otherwise return TEXT.

Note 1: Request body and content-type detection has the drawback that requests with no body "randomly" return different format error responses, so I might even leave out this detection entirely but certainly wouldn't be looking at request.json. Tough luck for those JSON users who do not correctly specify accept.

[Tronic]

Other relevant cases for the above: img, script, video, audio etc. tags, where that logic would return a text response. What is returned doesn't matter much because browsers won't show the response even in developer tools; maybe an empty response would be more appropriate.

[ahopkins]

Other relevant cases for the above: img, script, video, audio etc. tags, where that logic would return a text response. What is returned doesn't matter much because browsers won't show the response even in developer tools; maybe an empty response would be more appropriate.

Not sure that I agree that it should be an empty response; you could be accessing the resource directly in a browser.

[Tronic]

Other relevant cases for the above: img, script, video, audio etc. tags, where that logic would return a text response. What is returned doesn't matter much because browsers won't show the response even in developer tools; maybe an empty response would be more appropriate.

Not sure that I agree that it should be an empty response; you could be accessing the resource directly in a browser.

I believe in that case the accept header lists text/html. It only shows image and other formats if the request is from an HTML element.

[ahopkins]

OK. I'll check that.

[ahopkins]

This is roughly the logic:

• Use explicit error_format, if available
• Use likely intended response type, if available (this will cover the MAJORITY of use cases)
• Use the fallback
• If the fallback is auto:
  • Look to see if text/html is first in Accept header, use HTMLRenderer
  • Look to see if application/json is anywhere in Accept or if incoming request has content-type: application/json, use JSONRenderer
  • Check if completely missing Accept header, use TextRenderer (Likely coming from a raw socket)
  • If still nothing matches...
    • Check if its a poorly formatted JSON request, and use JSONRenderer (covers backwards compat)
    • Fallback to TextRenderer if curl
• In all cases, if there is an Accept header, make sure it is allowed
• If not, loop thru the Accept and stop at the first match (we may need to add some more potential matches here, but that can be in another iteration)
• If still nothing, use base renderer (which is HTMLRenderer for compat. Change this to TextRenderer in v22.3)

[vltr]

it seems all good to me! 😎

[codeclimate]

Code Climate has analyzed commit 0e0b982 and detected 1 issue on this pull request.

Here's the issue category breakdown:

Category	Count
Complexity	1

The test coverage on the diff in this pull request is 97.9% (86% is the threshold).

This pull request will bring the total coverage in the repository to 87.1% (0.0% change).

View more on Code Climate.