Enhancements for Custom Error Handling and Configuration in Marten Framework

[muhammadnawzad]

Overview

Hello there, I hope all is well. I'm developing an API using the Marten framework and have encountered several limitations regarding error handling and its configuration, particularly around custom error codes, JSON error responses, and behavior in debug mode. Below, I detail these interconnected issues and suggest potential improvements.

1. Custom Error Code Handling

Currently, Marten supports handling of a limited set of HTTP error codes (404, 500, 403, 400). I require the ability to define custom handlers for additional HTTP status codes, such as 409, 429, 503 and more to handle specific API error conditions.

Expected Behavior:

• Extend the error handling configuration to allow developers to specify custom handlers for any HTTP status code.

2. Global Error Handling with JSON Responses

Marten's error handling seems primarily designed for HTML responses. For API development, a mechanism to globally handle errors and return them in JSON format is essential.

Expected Behavior:

• Introduce a global error handling hook or middleware that enables developers to customize the format of error responses, ideally allowing for JSON-formatted errors.

3. Custom Handlers in Debug Mode

In debug mode, custom error handlers are bypassed in favor of default debug pages. For consistency in API error responses, it's crucial to allow custom handlers to function even in debug mode.

Expected Behavior:

• Provide a configuration option or guideline to enable custom error handlers during development, regardless of debug mode status.

Conclusion

Addressing these issues would significantly improve the flexibility and developer experience of using Marten for API development. I believe these enhancements could make Marten a more robust solution for building APIs, offering greater control over error handling and response formatting.

Thank you for considering these suggestions. I look forward to any feedback or discussion on these topics.

[notramo]

Currently, for API apps, I would recommend other Crystal frameworks, like Athena and Spider-Gazelle (which can automatically generate OpenAPI spec from classes, and has many API-related features). Marten seems to be more of a HTML-oriented framework in my opinion, although @ellmetha may have a different stance on this. Sure, it would be great to have the level of API support in Marten as Spider-Gazelle has, but if there aren't enough resources, I think it's better to do 1 thing well (HTML) than 2 things partially. There are many features regarding HTML that need to be improved in order to be a production-ready framework.

[ellmetha]

Currently, for API apps, I would recommend other Crystal frameworks, like Athena and Spider-Gazelle (which can automatically generate OpenAPI spec from classes, and has many API-related features). Marten seems to be more of a HTML-oriented framework in my opinion, although @ellmetha may have a different stance on this. Sure, it would be great to have the level of API support in Marten as Spider-Gazelle has, but if there aren't enough resources, I think it's better to do 1 thing well (HTML) than 2 things partially. There are many features regarding HTML that need to be improved in order to be a production-ready framework.

I am not sure I am aligned with this analysis. Marten is not and was never marketed as an HTML-oriented framework. If one wants to use Marten to build an API, I would be very inclined to learn about their use case and get their feedbacks regarding limiting aspects and things to possibly improve in the framework.

Indeed, some things may be easier to do than others with Marten, but this is mainly because the framework is (i) relatively young and (ii) opinionated regarding what it should do or not do:

• Marten hasn't been battle-tested for every possible use case and it hasn't built a big community around it yet (which means that not a lot of tooling is available outside of what is directly provided by the framework). For example, Marten is not less API-capable than frameworks like Django, but Django has lots of tools for building APIs on the side (eg. Django-Rest-Framework). Similar shards do not exist for Marten at the moment.
• Marten is a generic framework and choices have been made regarding what should go into the framework and what should not: generating OpenAPI documentation or things like that will never be part of Marten as those things map to specific API-building strategies and the framework shouldn't account for all of them. The idea is that complimentary shards with tooling helping in building REST APIs or GraphQL APIs should become available at one point.

It is perfectly possible to build APIs with Marten and I hope that the community comes up with dedicated tools to answer various API needs over time (eg. REST, GraphQL, etc) and ease this process. But I want to manage expectations here: those helpers should be provided separately as dedicated shards, not by the framework itself.

[ellmetha]

Hey! 👋 Welcome here!

Regarding (1) and (2) I am not sure Marten will be able to help much unfortunately. Marten is a generic framework with which APIs can be built, but it mainly focuses on relatively generic things (like the main error codes that you mentioned). There is no Marten shard available for helping with building REST APIs at the moment, but I hope that this is something that becomes a thing at one point (eg. something like Django-Rest-Framework for Marten would be awesome).

It is worth mentioning that the default error handlers can be overridden if necessary (they are all associated with dedicated settings: handler400, handler403, handler404, and handler500). It is perfectly possible to define new error handlers that return the expected JSON responses with your preferred format and use these settings to override the default error handlers.

Ultimately, I think Marten could return a JSON payload in these default error handlers in case the incoming HTTP request indicates that it accepts JSON (possibly an improvement that we can implement), but for full customization of the error format I would suggest overriding the error handlers directly as I was mentioning. As for handling very specific error codes (409, 429, etc), this is definitely something that should be implemented on an API-tooling shard or in projects directly (eg. custom middlewares) as these codes wouldn't match any existing exception in Marten anyway.

Regarding (3), indeed error pages are bypassed in debug mode in order to help with the debugging process. That said, we could probably make it easier to access the error pages in debug mode in another way (without having to add development-specific routes in each project). I will think a bit more about this one, but it seems like an improvement that we could make!

[muhammadnawzad]

Thank you so much for taking the time to respond and provide your insights. I really appreciate your thorough explanation and the clarity you've provided.

Your suggestion about overriding the default error handlers with custom settings is indeed helpful. I have already explored this option to meet my API's specific needs.

I agree that having a dedicated API-tooling shard or implementing custom middlewares for handling very specific error codes sounds like a sensible path forward.

Your consideration for improving accessibility to error pages in debug mode is also greatly appreciated. I'm excited about the possibilities Marten offers, and I'm looking forward to dive deeper into building tools around it.

Thanks again for your valuable input and for being so receptive to feedback.