Add a function type for functions that receive CloudEvents. #51
Conversation
This is not yet connected to anything.
| /** | ||
| * Called to service an incoming event. This interface is implemented by user code to | ||
| * provide the action for a given background function. If this method throws any exception | ||
| * (including any {@link Error}) then the HTTP response will have a 500 status code. |
There was a problem hiding this comment.
As an FYI, I've been thinking about whether it would be worth having a specific exception meaning "the function failed, but please use status code X".
See GoogleCloudPlatform/functions-framework-dotnet#61
Thoughts welcome. (We'd want to do this across languages, I suspect.)
There was a problem hiding this comment.
Instead of always throwing 500s, I would assume we could throw a 400 bad request for a malformed CE and other 4XX errors implying a user error.
https://github.com/GoogleCloudPlatform/functions-framework#http-status-codes
There was a problem hiding this comment.
It depends on what detects that the CloudEvent is "malformed" - if it's "malformed" in that the user code can't deserialize the data, for example, then we need a way of communicating that.
If it's malformed in terms of (say) not having an event ID, then I'd expect that to mean the user's code is never run, in which case this paragraph is irrelevant (as it only talks about what happens when the user code throws an exception).
There was a problem hiding this comment.
I do like this idea, but I don't know how well it will map to all of our languages.
| * @param event the event. | ||
| * @throws Exception to produce a 500 status code in the HTTP response. | ||
| */ | ||
| void accept(CloudEvent event) throws Exception; |
There was a problem hiding this comment.
So this is what I refer to as an "untyped" CloudEvent function in C#.
Is there an expectation that you'd provide a "typed" CloudEvent function as well, where the author specifies the expected data type and you do the unmarshalling for them, or is the expectation that it's sufficiently easy to unmarshal the data, so leave it to the user?
There was a problem hiding this comment.
I've gone back and forth a bit on this. For legacy events, we already have RawBackgroundFunction and BackgroundFunction, which are respectively untyped and typed. We could do the same for CloudEvents. As you know, there's also discussion in the Java SDK about whether it should provide support for this kind of automatic unmarshalling, which in fact the v1 SDK did. I think it's probably not the SDK's place to do that.
Assuming the byte[] getData() of the payload is a JSON string, users can do this themselves with something like this...
PubSub message = new Gson().fromJson(new String(event.getData(), UTF_8), PubSub.class);
...which is maybe just annoying enough for us to provide a way to have it done for them. The disadvantage of that is that we have to choose a particular JSON framework, which might not be the same as the one they're using.
Since the API here is necessarily unstable (because the SDK is), we could in fact postpone making this particular decision until finalizing it. We can still go ahead with implementing and testing CloudEvents support, which is the bulk of the work.
| /** | ||
| * Called to service an incoming event. This interface is implemented by user code to | ||
| * provide the action for a given background function. If this method throws any exception | ||
| * (including any {@link Error}) then the HTTP response will have a 500 status code. |
There was a problem hiding this comment.
Instead of always throwing 500s, I would assume we could throw a 400 bad request for a malformed CE and other 4XX errors implying a user error.
https://github.com/GoogleCloudPlatform/functions-framework#http-status-codes
| * provide the action for a given background function. If this method throws any exception | ||
| * (including any {@link Error}) then the HTTP response will have a 500 status code. | ||
| * | ||
| * @param event the event. |
There was a problem hiding this comment.
Differentiate events and CloudEvents to discern the two signature types.
There was a problem hiding this comment.
I'm not sure what you mean?
There was a problem hiding this comment.
We say event here but we really mean a CloudEvent (rather than a legacy event or event seen with the events signature type)
There was a problem hiding this comment.
Well OK, but the parameter type is clearly CloudEvent. We could say CloudEvent here too, though, true.
This is not yet connected to anything.