Support annotated-exception

[parsonsmatt]

Fixes #1761

Before submitting your PR, check that you've:

• Bumped the version number
• Documented new APIs with Haddock markup
• Added @since declarations to the Haddocks for new, public APIs

After submitting your PR:

• Update the Changelog.md file with a link to your PR
• Check that CI passes (or if it fails, for reasons unrelated to your change, like CI timeouts)

[parsonsmatt]

I've made a PR to add annotated-exception to STackage which is probably a prerequisite: commercialhaskell/stackage#6540

[parsonsmatt]

This deserves a bit of commentary.

The instance Exception e => Exception (AnnotatedException e) has a slightly magical terrible horrifying unusual implementation of fromException.

The tests for this demonstrate the pattern, but tl;dr, the Exception instance here on AnnotatedException will work to catch both an AnnotatedException HandlerContents and a HandlerContents, which is then promoted to AnnotatedException mempty (hc :: HandlerContents).

[schoettl]

Hi Matt,
Maybe it makes sense to clarify first, if this library can make it into Yesod as a dependency at the moment. Before you put too much work in this PR.
Don't get me wrong but I'm not sure about that. Because your library is pretty new, has no ratings yet and very few downloads on hackage. And maintainers are usually reluctant to add dependencies that are not (yet) popular, at least not if they are not adding a great value for many users, I think.

[parsonsmatt]

I'm happy to let this sit until folks feel good integrating it. At the very least, the issue and PR presence is useful for folks that inevitably run into trouble when using annotated-exception with Yesod.

[snoyberg]

I’m OK with the change if you find this useful. But there are merge conflicts now, sorry for the delayed review

[lorenzo]

@parsonsmatt do you need help finishing this? I'm interested

[parsonsmatt]

I need to verify that the HCError <$> toHandlerError e does the right thing here - I suspect it may not have the right behavior

[parsonsmatt]

We have a Yesod middleware at work that handles this unwrapping, and as long as it's the last middleware, everything works fine.

I want to write some tests and verify that this is properly integrated before recommending merging.

[parsonsmatt]

OK, digging into this some more:

-- | Convert a synchronous exception into an ErrorResponse
toErrorHandler :: SomeException -> IO ErrorResponse
toErrorHandler e0 = handleAny errFromShow $
    case fromException e0 of
        Just (HCError x) -> evaluate $!! x
        _ -> errFromShow e0

So I think this function needs to also check for AnnotatedException - since the fromException e0 :: Maybe HCContents won't work if the underlying application code is calling throwWithCallStack.

-- | Generate an @ErrorResponse@ based on the shown version of the exception
errFromShow :: SomeException -> IO ErrorResponse
errFromShow x = do
  text <- evaluate (T.pack $ show x) `catchAny` \_ ->
          return (T.pack "Yesod.Core.Internal.Run.errFromShow: show of an exception threw an exception")
  return $ InternalError text

Fortunately this should work fine - perhaps we want to unwrap the AnnotatedException before showing it?