Skip to content

Commit b2373e0

Browse files
webupwebup
committed
📝 docs(README): refine some feature descriptions
1 parent e5be7b8 commit b2373e0

File tree

1 file changed

+44
-71
lines changed

1 file changed

+44
-71
lines changed

‎README.md

Lines changed: 44 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,19 @@
77
> This is OpenFunction's nodejs functions-framework forked from [GCP functions-framework-nodejs](https://github.com/GoogleCloudPlatform/functions-framework-nodejs)
88
99
An open source FaaS (Function as a Service) framework based on [Express](https://expressjs.com/)
10-
for writing portable Node.js functions
10+
and [Restana](https://github.com/BackendStack21/restana) for writing portable sync and async Node.js functions.
1111

1212
The Functions Framework lets you write lightweight functions that run in many
1313
different environments, including:
1414

15-
* [Google Cloud Functions](https://cloud.google.com/functions/)
16-
* Your local development machine
17-
* [Cloud Run](https://cloud.google.com/run/) and [Cloud Run for Anthos](https://cloud.google.com/anthos/run)
15+
* [OpenFunction](https://github.com/OpenFunction/OpenFunction)
1816
* [Knative](https://github.com/knative/)-based environments
1917
* [Dapr](https://dapr.io/)-based environments
20-
* [OpenFunction](https://github.com/OpenFunction/OpenFunction)
18+
* [Google Cloud Functions](https://cloud.google.com/functions/)
19+
* [Cloud Run](https://cloud.google.com/run/) and [Cloud Run for Anthos](https://cloud.google.com/anthos/run)
20+
* Your local development machine
2121

22-
The framework allows you to go from:
22+
Generally speaking, the framework allows you to go from:
2323

2424
```js
2525
/**
@@ -39,17 +39,16 @@ curl http://my-url
3939
# Output: Hello, World!
4040
```
4141

42-
All without needing to worry about writing an HTTP server or complicated request
43-
handling logic.
42+
All without needing to worry about writing an HTTP server or complicated request handling logic.
4443

4544
> Watch [this video](https://youtu.be/yMEcyAkTliU?t=912) to learn more about the Node Functions Framework.
4645
4746
## Features
4847

4948
* Spin up a local development server for quick testing
5049
* Invoke a function in response to a request
51-
* Automatically unmarshal events conforming to the
52-
[CloudEvents](https://cloudevents.io/) spec
50+
* Listen and respond to the events bridged from Dapr system
51+
* Automatically unmarshal events conforming to the [CloudEvents](https://cloudevents.io/) spec
5352
* Portable between serverless platforms
5453

5554
## Installation
@@ -62,7 +61,7 @@ npm install @openfunction/functions-framework
6261

6362
## Quickstarts
6463

65-
### Quickstart: Hello, World on your local machine
64+
### Quickstart: "Hello, World" on your local machine
6665

6766
1. Create an `index.js` file with the following contents:
6867

@@ -118,6 +117,7 @@ command-line arguments:
118117
...
119118
Serving function...
120119
Function: helloWorld
120+
Signature type: http
121121
URL: http://localhost:8080/
122122
```
123123

@@ -130,9 +130,9 @@ command-line arguments:
130130

131131
### Quickstart: Build a Deployable Container
132132

133-
1. Install [Docker](https://store.docker.com/search?type=edition&offering=community) and the [`pack` tool](https://buildpacks.io/docs/install-pack/).
133+
1. Install [Docker](https://store.docker.com/search?type=edition&offering=community) and the [pack](https://buildpacks.io/docs/install-pack/) tool.
134134

135-
1. Build a container from your function using the Functions [buildpacks](https://github.com/GoogleCloudPlatform/buildpacks):
135+
2. Build a container from your function using the [Cloud Native Buildpacks](https://buildpacks.io/):
136136

137137
```sh
138138
pack build \
@@ -142,44 +142,22 @@ command-line arguments:
142142
my-first-function
143143
```
144144

145-
1. Start the built container:
145+
3. Start the built function container:
146146

147147
```sh
148-
docker run --rm -p 8080:8080 my-first-function
148+
docker run --rm -p 8080:8080 -e NODE_ENV=dev my-first-function
149149
# Output: Serving function...
150150
```
151151

152-
1. Send requests to this function using `curl` from another terminal window:
152+
> NOTICE: `-e NODE_ENV=dev` is required to display "Serving function...", and you can also append `-e DEBUG=*` to display Express internal debug messages.
153+
154+
4. Send requests to this function using `curl` from another terminal window:
153155

154156
```sh
155157
curl localhost:8080
156158
# Output: Hello, World!
157159
```
158160

159-
## Run your function on serverless platforms
160-
161-
### Google Cloud Functions
162-
163-
The
164-
[Node.js 10 runtime on Google Cloud Functions](https://cloud.google.com/functions/docs/concepts/nodejs-10-runtime)
165-
is based on the Functions Framework. On Cloud Functions, the Functions Framework
166-
is completely optional: if you don't add it to your `package.json`, it will be
167-
installed automatically.
168-
169-
After you've written your function, you can simply deploy it from your local
170-
machine using the `gcloud` command-line tool.
171-
[Check out the Cloud Functions quickstart](https://cloud.google.com/functions/docs/quickstart).
172-
173-
### Cloud Run / Cloud Run for Anthos
174-
175-
After you've written your function, added the Functions Framework and updated your `start` script in `package.json`, deploy it to Cloud Run with `gcloud run deploy`. Check out the [Cloud Run quickstart for Node.js](https://cloud.google.com/run/docs/quickstarts/build-and-deploy/nodejs).
176-
177-
If you want even more control over the environment, you can [deploy to Cloud Run for Anthos](https://cloud.google.com/anthos/run/docs/quickstarts/prebuilt-deploy-gke). With Cloud Run for Anthos, you can run your function on a GKE cluster, which gives you additional control over the environment (including use of GPU-based instances, longer timeouts and more).
178-
179-
### Container environments based on Knative
180-
181-
Cloud Run and Cloud Run for Anthos both implement the [Knative Serving API](https://www.knative.dev/docs/). The Functions Framework is designed to be compatible with Knative environments. Just build and deploy your container to a Knative environment.
182-
183161
## Configure the Functions Framework
184162

185163
You can configure the Functions Framework using command-line flags or
@@ -202,34 +180,39 @@ For example:
202180
}
203181
```
204182
205-
## Enable Google Cloud Functions Events
183+
## Run your function on Serverless platforms
206184
207-
The Functions Framework can unmarshall incoming
208-
Google Cloud Functions [event](https://cloud.google.com/functions/docs/concepts/events-triggers#events) payloads to `data` and `context` objects.
209-
These will be passed as arguments to your function when it receives a request.
210-
Note that your function must use the `event`-style function signature:
185+
### Container environments based on Knative
211186
212-
```js
213-
exports.helloEvents = (data, context) => {
214-
console.log(data);
215-
console.log(context);
216-
};
217-
```
187+
The Functions Framework is designed to be compatible with Knative environments. Build and deploy your container to a Knative environment.
188+
189+
### OpenFunction
218190
219-
To enable automatic unmarshalling, set the function signature type to `event`
220-
using a command-line flag or an environment variable. By default, the HTTP
221-
signature will be used and automatic event unmarshalling will be disabled.
191+
![OpenFunction Platform Overview](https://openfunction.dev/openfunction-0.5-architecture.png)
192+
193+
Besides Knative function support, one notable feature of OpenFunction is embracing Dapr system, so far Dapr pub/sub and bindings have been support.
194+
195+
Dapr bindings allows you to trigger your applications or services with events coming in from external systems, or interface with external systems. OpenFunction [0.6.0 release](https://openfunction.dev/blog/2022/03/25/announcing-openfunction-0.6.0-faas-observability-http-trigger-and-more/) adds Dapr output bindings to its synchronous functions which enables HTTP triggers for asynchronous functions. For example, synchronous functions backed by the Knative runtime can now interact with middlewares defined by Dapr output binding or pub/sub, and an asynchronous function will be triggered by the events sent from the synchronous function.
196+
197+
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.
198+
199+
More details would be brought up to you in some quickstart samples, stay tuned.
200+
201+
### Google Cloud Functions
222202
223-
For more details on this signature type, check out the Google Cloud Functions
224-
documentation on
225-
[background functions](https://cloud.google.com/functions/docs/writing/background#cloud_pubsub_example).
203+
The [Node.js 10 runtime on Google Cloud Functions](https://cloud.google.com/functions/docs/concepts/nodejs-10-runtime) is based on the Functions Framework. On Cloud Functions, the Functions Framework is completely optional: if you don't add it to your `package.json`, it will be installed automatically.
204+
205+
After you've written your function, you can deploy it from your local machine using the `gcloud` command-line tool. [Check out the Cloud Functions quickstart](https://cloud.google.com/functions/docs/quickstart).
206+
207+
### Cloud Run / Cloud Run for Anthos
208+
209+
After you've written your function, added the Functions Framework and updated your `start` script in `package.json`, deploy it to Cloud Run with `gcloud run deploy`. Check out the [Cloud Run quickstart for Node.js](https://cloud.google.com/run/docs/quickstarts/build-and-deploy/nodejs).
210+
211+
If you want even more control over the environment, you can [deploy to Cloud Run for Anthos](https://cloud.google.com/anthos/run/docs/quickstarts/prebuilt-deploy-gke). With Cloud Run for Anthos, you can run your function on a GKE cluster, which gives you additional control over the environment (including use of GPU-based instances, longer timeouts and more).
226212
227213
## Enable CloudEvents
228214
229-
The Functions Framework can unmarshall incoming
230-
[CloudEvents](http://cloudevents.io) payloads to a `cloudevent` object.
231-
It will be passed as an argument to your function when it receives a request.
232-
Note that your function must use the `cloudevent`-style function signature:
215+
The Functions Framework can unmarshall incoming [CloudEvents](http://cloudevents.io) payloads to a `cloudevent` object. It will be passed as an argument to your function when it receives a request. Note that your function must use the `cloudevent`-style function signature:
233216
234217
```js
235218
const functions = require('@openfunction/functions-framework');
@@ -245,16 +228,6 @@ functions.cloudEvent('helloCloudEvents', (cloudevent) => {
245228
});
246229
```
247230
248-
To enable the CloudEvent functions, you must list the Functions Framework as a dependency in your `package.json`:
249-
250-
```json
251-
{
252-
"dependencies": {
253-
"@openfunction/functions-framework": "~0.4.0"
254-
}
255-
}
256-
```
257-
258231
Learn how to use CloudEvents in this [guide](docs/cloudevents.md).
259232
260233
## Advanced Docs

0 commit comments

Comments
 (0)