return explanation error for a broken Json call

[arhimede]

Feature Request

Q	A
New Feature	yes
RFC	yes
BC Break	no

Summary

For instance, I am sending a bad json body to an endpoint

I am getting the below response
{"title":"Internal Server Error","type":"https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error","status":500,"detail":"An unknown error occurred."}

In logs at the server level, i have

"priority":3,"priorityName":"ERR","message":"Error when parsing JSON request body: Syntax error","extra":{"\u0000*\u0000message":"Error when parsing JSON request body: Syntax error",ETC

can we somehow return a more detailed error in this case to the client ?

[alexmerlin]

The response you get is what problem details should return when NOT in development mode.

Response when development mode is disabled:

{
    "title": "Internal Server Error",
    "type": "https://datatracker.ietf.org/doc/html/rfc9110#name-500-internal-server-error",
    "status": 500,
    "detail": "An unknown error occurred."
}

Response when development mode is enabled:

{
    "exception": {
        "class": "Mezzio\\Helper\\Exception\\MalformedRequestBodyException",
        "code": 400,
        "message": "Error when parsing JSON request body: Syntax error",
        "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio-helpers/src/BodyParams/JsonStrategy.php",
        "line": 45,
        "trace": [
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio-helpers/src/BodyParams/BodyParamsMiddleware.php",
                "line": 76,
                "function": "parse",
                "class": "Mezzio\\Helper\\BodyParams\\JsonStrategy",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio/src/Middleware/LazyLoadingMiddleware.php",
                "line": 27,
                "function": "process",
                "class": "Mezzio\\Helper\\BodyParams\\BodyParamsMiddleware",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/laminas/laminas-stratigility/src/Next.php",
                "line": 49,
                "function": "process",
                "class": "Mezzio\\Middleware\\LazyLoadingMiddleware",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio-problem-details/src/ProblemDetailsMiddleware.php",
                "line": 48,
                "function": "handle",
                "class": "Laminas\\Stratigility\\Next",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio/src/Middleware/LazyLoadingMiddleware.php",
                "line": 27,
                "function": "process",
                "class": "Mezzio\\ProblemDetails\\ProblemDetailsMiddleware",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/laminas/laminas-stratigility/src/Next.php",
                "line": 49,
                "function": "process",
                "class": "Mezzio\\Middleware\\LazyLoadingMiddleware",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/laminas/laminas-stratigility/src/MiddlewarePipe.php",
                "line": 81,
                "function": "handle",
                "class": "Laminas\\Stratigility\\Next",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/laminas/laminas-stratigility/src/MiddlewarePipe.php",
                "line": 70,
                "function": "process",
                "class": "Laminas\\Stratigility\\MiddlewarePipe",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/laminas/laminas-httphandlerrunner/src/RequestHandlerRunner.php",
                "line": 73,
                "function": "handle",
                "class": "Laminas\\Stratigility\\MiddlewarePipe",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/vendor/mezzio/mezzio/src/Application.php",
                "line": 56,
                "function": "run",
                "class": "Laminas\\HttpHandlerRunner\\RequestHandlerRunner",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/public/index.php",
                "line": 37,
                "function": "run",
                "class": "Mezzio\\Application",
                "type": "->"
            },
            {
                "file": "/var/www/api.dotkernel.localhost/html/public/index.php",
                "line": 38,
                "function": "{closure:/var/www/api.dotkernel.localhost/html/public/index.php:24}"
            }
        ]
    },
    "title": "Bad Request",
    "type": "https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request",
    "status": 400,
    "detail": "Error when parsing JSON request body: Syntax error"
}

Not sure though why wouldn't the error get logged in log/.
I tried using both development mode enabled/disabled and I saw the entire trace being logged in the daily log file.
Maybe if you provide a specific request body, I can dig deeper into this.

[arhimede]

The problem is that when in production, so development mode is disabled

An API client should get something like:

"message": "Error when parsing JSON request body: Syntax error",

instead of current "detail": "An unknown error occurred." which is not helpful at all.

We should look at the problem from Client perspective , which do not have access to APi logs

[alexmerlin]

Long story short

When development mode is disabled, the message is not returned in the response as long as the exception does not implement ProblemDetailsExceptionInterface.
Therefore, real error messages will only be logged but not returned in the response.

---

Short story long

Here's the request flow starting from the point when it fails:

We try to parse the request body, json_decode fails and an exception is thrown on line 45.
The exception runs through BodyParamsMiddleware.php which is registered in Dotkernel API pipeline.
ProblemDetailsMiddleware catches the exception in the process method.
Then, the exception is processed in ProblemDetailsResponseFactory.php - here comes the "fun" part:
The exception thrown being of type MalformedRequestBodyException which does not implement ProblemDetailsExceptionInterface the error message is being generated on line 289 which will not use the exception message when not in development mode.

---

Solution

Create a new middleware that catches MalformedRequestBodyExceptions and re-throws a different exception implements ProblemDetailsExceptionInterface.