Merge pull request #10 from OpenFunction/feature/sync-trigger-async

feat: enable HTTP function trigger async functions

Author: webup

.github/mergable.yml renamed to .github/mergeable.yml

@@ -1,61 +1,44 @@
 # How to Contribute
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+We'd love to accept your patches and contributions to this project. There are a few small guidelines you need to follow.
 
 ## Contributor License Agreement
 
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+Contributions to this project must be accompanied by a  Developer Certificate of Origin (DCO). You (or your employer) retain the copyright to your contribution; this gives us permission to use and redistribute your contributions as part of the project. Head over to <https://developercertificate.org/> to see your current agreements on file or to sign a new one.
 
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+You only need to submit a DTO once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
 
 ## Code reviews
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.
 
 ## Testing
 
 ### Unit Tests
 
 All pull requests should have an associated test to ensure foward compatibility.
 
+> Make sure you have installed [Dapr](https://dapr.io/) before running unit tests, check out [Install Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) for more details
+
 To run an individual test, you can run a command such as the following:
 
-```
+```sh
 npm run test -- -g 'loading function'
 ```
 
-### Conformance Tests
-
-To run the conformance tests, first install Go 1.16+, then run the tests:
-
-```
-npm run conformance
-```
-
 ### Manual Testing
 
-When developing a feature locally, you can install a local version of the Functions Framework
-using `npm link`. First compile your local clone of the Functions Framework:
+When developing a feature locally, you can install a local version of the Functions Framework using `npm link`. First compile your local clone of the Functions Framework:
 
 > You'll need to install typescript first by: `npm install typescript --save-dev`
 
-```
+```sh
 npx tsc
 ```
 
 Then link the Functions Framework using `npm link`.
 
-```
+```sh
 npm link
 ```
 
@@ -65,14 +48,15 @@ You can then run the Functions Framework locally using `functions-framework`.
 
 This module is published using Release Please. When you merge a release PR, the npm package will be automatically published.
 
-```shell
+```sh
 # Login to npm registry, contact repo admin for https://www.npmjs.com/ user name and password
 npm login
 # First run a dry run to find out errors
 npm publish ./ --access public --dry-run
 # Then publish the package
 npm publish --access public
 ```
+
 ### Reverting a Publish
 
 If the release process fails, you can revert the publish by running the following (i.e. unpublishing `1.10.0`):
@@ -101,5 +85,4 @@ The docs will be generated in [`docs/generated/`](docs/generated/).
 
 ## Community Guidelines
 
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google.com/conduct/).
+This project follows [CNCF openness guidelines](https://www.cncf.io/blog/2019/06/11/cncf-openness-guidelines/).

CONTRIBUTING.md

@@ -168,7 +168,7 @@ ignored.
 | ------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--port`           | `PORT`                    | The port on which the Functions Framework listens for requests. Default: `8080`                                                                                                                                  |
 | `--target`         | `FUNCTION_TARGET`         | The name of the exported function to be invoked in response to requests. Default: `function`                                                                                                                     |
-| `--signature-type` | `FUNCTION_SIGNATURE_TYPE` | The signature used when writing your function. Controls unmarshalling rules and determines which arguments are used to invoke your function. Default: `http`; accepted values: `http` or `event` or `cloudevent` |
+| `--signature-type` | `FUNCTION_SIGNATURE_TYPE` | The signature used when writing your function. Controls unmarshalling rules and determines which arguments are used to invoke your function. Default: `http`; accepted values: `http` or `event` or `cloudevent` or `openfunction` |
 | `--source`         | `FUNCTION_SOURCE`         | The path to the directory of your function. Default: `cwd` (the current working directory)                                                                                                                       |
 
 You can set command-line flags in your `package.json` via the `start` script.
@@ -196,7 +196,52 @@ Dapr bindings allows you to trigger your applications or services with events co
 
 Asynchronous function introduces Dapr pub/sub to provide a platform-agnostic API to send and receive messages. A typical use case is that you can leverage synchronous functions to receive an event in plain JSON or Cloud Events format, and then send the received event to a Dapr output binding or pub/sub component, most likely a message queue (e.g. Kafka, NATS Streaming, GCP PubSub, MQTT). Finally, the asynchronous function could be triggered from the message queue.
 
-More details would be brought up to you in some quickstart samples, stay tuned.
+Async function use below function signature which is quite difference from that of Express style sync function:
+
+```js
+function (ctx, data) {}
+```
+
+* `ctx`: OpenFunction [context](https://github.com/OpenFunction/functions-framework-nodejs/blob/master/src/openfunction/function_context.ts) object
+  * `ctx.send(payload, output?)`: Send `payload` to all or one specific `output` of Dapr Output [Binding](https://docs.dapr.io/reference/components-reference/supported-bindings/) or Pub [Broker](https://docs.dapr.io/reference/components-reference/supported-pubsub/)
+  * Notice that `ctx.send` CAN be invoked where necessary, when you have certain outgoing data to send
+* `data`: Data recieved from Dapr Input Binding or Sub Broker
+
+For more details about async function and demo, please check out our [Node.js Async Function Quickstart](https://openfunction-talks.netlify.app/2022/202-node-async/).
+
+#### HTTP Trigger Async Function
+
+Sync functions is triggered by HTTP request, so Dapr is not used in sync function input. Whenever there are functions output requirements, sync functions can also send output to Dapr output binding or pubsub components.
+
+Here is another function sample:
+
+* Users send a HTTP request to a [Knative Sync function](https://github.com/OpenFunction/samples/tree/main/functions/knative/with-output-binding).
+* This sync function handles the request and then send its output to Kafka through a Dapr Kafka output binding or pubsub component.
+* An [async function](https://github.com/OpenFunction/samples/tree/main/functions/async/bindings/kafka-input) is then triggered by this output event in Kafka (through a Dapr Kafka input binding or pubsub component)
+
+![HTTP Trigger Async Function](https://raw.githubusercontent.com/OpenFunction/samples/main/images/knative-dapr.png)
+
+Node.js Functions Framework also supports such use case, you can switch Express function signature to typical async style as below example indicates:
+
+```js
+async function tryKnativeAsync(ctx, data) {
+  // Receive and handle data from HTTP request's body
+  console.log('Function should receive request: %o', data);
+
+  // Send output in async way via Dapr
+  await ctx.send(data);
+
+  // Use `ctx.res` object to deal with HTTP response
+  ctx.res.send(data);
+```
+
+Remember that you also need set command-line flags `--signature-type=openfunction`, for example in your `package.json` via the `start` script:
+
+```js
+  "scripts": {
+    "start": "functions-framework --signature-type=openfunction --target=tryKnativeAsync"
+  }
+```
 
 ### Google Cloud Functions
 
@@ -243,5 +288,3 @@ Contributions to this library are welcome and encouraged. See
 [ff_node_unit_link]:  https://github.com/openfunction/functions-framework-nodejs/actions?query=workflow%3A"Node.js+Unit+CI"
 [ff_node_lint_img]: https://github.com/openfunction/functions-framework-nodejs/workflows/Node.js%20Lint%20CI/badge.svg
 [ff_node_lint_link]:  https://github.com/openfunction/functions-framework-nodejs/actions?query=workflow%3A"Node.js+Lint+CI"
-[ff_node_conformance_img]: https://github.com/openfunction/functions-framework-nodejs/workflows/Node.js%20Conformance%20CI/badge.svg
-[ff_node_conformance_link]:  https://github.com/openfunction/functions-framework-nodejs/actions?query=workflow%3A"Node.js+Conformance+CI"