Clarify error handling expectations

[grayside]

In #15 a set of typical HTTP response codes was documented, however, in working on the PHP functions framework we have found there's a lot that remains undefined in how errors should be handled.

GoogleCloudPlatform/functions-framework-php#60 demonstrates the only definition is triangulating against the behaviors of other functions frameworks, which include some behaviors in the name of backwards compatibility that are not intended as part of the functions framework specification.

Actual

Each language makes independent decisions around error handling, including:

• Handling the X-Google-Status custom HTTP header
• What error message is returned in the body of the response
• Reliable use of error status codes in all edge cases
• Generation of a stack trace/integration with Error Reporting

Expected

Functions frameworks provide a consistent experience in surfacing errors such as HTTP Functions and CloudEvent Functions present a language agnostic programming paradigm for service-to-service communications.

[grant]

Thanks for filing the issue.

We might want to take these one by one. Some of the behavior may purposefully be undefined and custom per language and some might be legacy code form the internal invoker. Nonetheless, we should provide more guidance on each of these bullets around error handling.

[grant]

Handling X-Google-Status is more of an issue for the Runtimes team who should describe how this should behave across runtimes w.r.t. the supervisor.

In general, each language has a different server implementation that gives some variability. Nonetheless, given a more concrete list of possible errors, we could document the expected error message and status codes in this contract.

CC: @asriniva
Ref: GoogleCloudPlatform/functions-framework-python#114
Ref: b/162521109

[asriniva]

Specifically talking about the X-Google-Status header, this was added due to customer request for a similar user experience between GCF Python 3.7 and 3.8+. It's not officially stated in the functions framework contract, but a few of the runtimes provide this header (Node.js, Go, Python). There's no reason it can't be added to the other frameworks.

[grant]

Assigning to @anniefu per request.

[anniefu]

Unfortunately, the frameworks themselves are pretty scattered on HTTP code usage, and additionally underlying web frameworks in each language may be returning different codes for different cases. Due to that, it is difficult to establish any hard guidelines for errors at this point.

Function Errors

There are some enforced principles for the case when the user function itself errors that are important to maintain for privacy and security reasons:

• Do not return user-created exception messages in the response body, log it instead
• Do not return stack traces in the response body, log it instead
• Return HTTP status code 500 if the user function itself errors

System Errors

For "system" errors coming from the Functions Framework or underlying HTTP frameworks, there are no hard guidelines, but this would be my recommendation:

Handling the X-Google-Status custom HTTP header

Not required, but the framework must follow the above guidelines for handing user function errors

What error message is returned in the body of the response

May be highly dependent on the language. Prefer detailed error messages, especially if the error is a user error that can is fixable. Only include system error information, do not include error messages from user function (log those instead).

Reliable use of error status codes in all edge cases

Use exactly 400 when the end user/client is deemed to be the issue (invalid event payload, function stub can't be loaded). Use exactly 500 when the framework is the issue and it's unlikely the end user will be able to fix it.

Prefer using the error message to differentiate error cases instead of the HTTP code.

Generation of a stack trace/integration with Error Reporting

Stack traces are not required, but can be very helpful. They should be logged instead of included in response bodies.