Open grayside opened 3 years ago
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.
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: https://github.com/GoogleCloudPlatform/functions-framework-python/pull/114 Ref: b/162521109
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.
Assigning to @anniefu per request.
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.
There are some enforced principles for the case when the user function itself errors that are important to maintain for privacy and security reasons:
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.
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.
https://github.com/GoogleCloudPlatform/functions-framework-php/issues/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:
X-Google-Status
custom HTTP headerExpected
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.