Create Functions Framework Spec

[benjaminhuo]

OpenFunction already have implemented the functions-framework-go and functions-framework-nodejs, the functions-framework-python, functions-framework-dotnet and functions-framework-java is also under developing.

We need a spec to guide the development of each language's functions framework.

Here is a draft of such a Spec https://hackmd.io/@xcEqMy2IQx-DQu_nUuPNXw/HkXqDW6P5
We need to create an English version of this and add more content to it based on each language's functions framework's experiences.

The author of each language's functions framework should contribute to this doc

@tpiperatgod @webup @wanjunlei @kehuili @geffzhang

[lizzzcai]

When I play around with the ff-go, I come up with the following enhancements (apply to all ff), which I think will be good to improve the functionality and user experience.

1. Support advanced http router
   1. some of the ff like ff-python is using flask which has powerful features. However, some like ff-go is using the built-in HTTP package which has limited functions and usually not production-ready (can be replaced by mux for example)
   2. advanced HTTP router can support like define variable in the route path like '/user/<username>' and get it by vars := mux.Vars(r), or define the allowing HTTP methods when registering the function like r.Methods("GET", "POST")
2. support metadata field in send function which is widely used in pubsub and binding (for example s3 binding)
3. allow users to get DaprClient and use it in the function.
   1. currently ofn only supports pubsub and bindings by send function, however, dapr has many other building blocks which are yet to support.
   2. Exploring the use cases and defining the API spec takes time. Opening up the DaprClient for exploration will be a better option now for users who have the experience to explore their use cases.
4. support plugin selection at the function level
   1. as we are able to support multiple functions. However, the plugin is defined at the framework level and applies to all the functions.
   2. provide options like WithPrePlugins([]string{”plugin-1”, “plugin-2”}) when registering the function.
5. It makes more sense to have a pathPrefix rather than pattern field in the runtime here as we define the path at the function level now.
6. support get the raw event data in ofn function type (fn(ctx ofctx.Context, in []byte)) when the incoming request is a cloudevent. (please find this comment)
   1. current in the ofn function type, ofn helps to decode the cloudevent internally and pass the data field ([]byte) to the user function. However, in the cloudevent spec, there are fields like type, source, id, time and other custom attributes, which user may use them in the user function.
   2. Possible solution is that the user can get the raw cloudevent data from the ctx.

Feel free to provide your feedback.

[tpiperatgod]

2. support metadata field in send function which is widely used in pubsub and binding (for example s3 binding)

In this PR I tried to introduce some options for the Send() and we can also pass some metadatas in this way. We can discuss how to pass metadata in the PR.

4. support plugin selection at the function level

   1. as we are able to support multiple functions. However, the plugin is defined at the framework level and applies to all the functions.
   2. provide options like WithPrePlugins([]string{”plugin-1”, “plugin-2”}) when registering the function.

function-level plugin configuration is now supported, pls see this. Does this meet with your needs?

6. support get the raw event data in ofn function type (fn(ctx ofctx.Context, in []byte)) when the incoming request is a cloudevent.

   1. current in the ofn function type, ofn helps to decode the cloudevent internally and pass the data field ([]byte) to the user function. However, in the cloudevent spec, there are fields like type, source, id, time and other custom attributes, which user may use them in the user function.
   2. Possible solution is that the user can get the raw cloudevent data from the ctx.

Currently supports getting the raw event from the Context, pls see this. And it can be used like this.

[lizzzcai]

2. support metadata field in send function which is widely used in pubsub and binding (for example s3 binding)

In this PR I tried to introduce some options for the Send() and we can also pass some metadatas in this way. We can discuss how to pass metadata in the PR.

4. support plugin selection at the function level

   1. as we are able to support multiple functions. However, the plugin is defined at the framework level and applies to all the functions.
   2. provide options like WithPrePlugins([]string{”plugin-1”, “plugin-2”}) when registering the function.

function-level plugin configuration is now supported, pls see this. Does this meet with your needs?

6. support get the raw event data in ofn function type (fn(ctx ofctx.Context, in []byte)) when the incoming request is a cloudevent.

   1. current in the ofn function type, ofn helps to decode the cloudevent internally and pass the data field ([]byte) to the user function. However, in the cloudevent spec, there are fields like type, source, id, time and other custom attributes, which user may use them in the user function.
   2. Possible solution is that the user can get the raw cloudevent data from the ctx.

Currently supports getting the raw event from the Context, pls see this. And it can be used like this.

cool, I have removed it from the list.

[tpiperatgod]

cool, I have removed it from the list.

It reflects that we lack a feature document or feature summary...🥲

[benjaminhuo]

Need to add the following method to context:

• get/save/delete/query for state management
• publish for pubsub
• output for output binding

Currently, we use send for both pubsub and binding, which is not accurate

[wrongerror]

Adjustments that need to be made:

1. To support dapr-proxy mode, functions-framework need to get DAPR_HOST from env vars, init daprClient based on DAPR_HOST and DAPR_HTTP_PORT/DAPR_GRPC_PORT.
2. Do not generate/init daprClient when the sync function uses the OpenFunction signature but does not define inputs and outputs.