Skip to content

Commit 24123e0

Browse files
lbarbeevargaslbarbeevargas
authored
Merge pull request #32551 from abrennan89/nodejs
[srvls][SRVOCF-278] Adding Nodejs functions docs
2 parents b44c87f + 38c132c commit 24123e0

10 files changed

+373
-7
lines changed

‎_topic_map.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2679,7 +2679,7 @@ Topics:
26792679
- Name: Scheduling virtual machines
26802680
File: virt-schedule-vms
26812681
- Name: Configuring PCI passthrough
2682-
File: virt-configuring-pci-passthrough
2682+
File: virt-configuring-pci-passthrough
26832683
# Importing virtual machines
26842684
- Name: Importing virtual machines
26852685
Dir: importing_vms
@@ -2967,10 +2967,14 @@ Topics:
29672967
# File: serverless-functions-getting-started
29682968
# - Name: Setting up OpenShift Serverless Functions
29692969
# File: serverless-functions-setup
2970+
# - Name: Developing Node.js functions
2971+
# File: serverless-developing-nodejs-functions
29702972
# - Name: Developing Golang functions
29712973
# File: serverless-developing-go-functions
29722974
# - Name: Developing Python functions
29732975
# File: serverless-developing-python-functions
2976+
# - Name: Functions development reference guide
2977+
# File: serverless-functions-reference-guide
29742978
# Networking
29752979
- Name: Networking
29762980
Dir: networking

‎modules/serverless-nodejs-context-object-reference.adoc

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Module included in the following assemblies
2+
//
3+
// * /serverless/functions/serverless-functions-reference-guide.adoc
4+
5+
[id="serverless-nodejs-context-object-reference_{context}"]
6+
= Node.js context object reference
7+
8+
The `context` object has several properties that can be accessed by the function developer.
9+
10+
[id="serverless-nodejs-context-object-reference-log_{context}"]
11+
== log
12+
13+
Provides a logging object that can be used to write output to the cluster logs. The log adheres to the link:https://getpino.io/#/docs/api[Pino logging API].
14+
15+
.Example log
16+
[source,javascript]
17+
----
18+
function handle(context) {
19+
context.log.info(“Processing customer”);
20+
}
21+
----
22+
23+
You can access the function by using the `curl` command to invoke it:
24+
25+
.Example command
26+
[source,terminal]
27+
----
28+
$ curl http://example.com
29+
----
30+
31+
.Example output
32+
[source,terminal]
33+
----
34+
{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"Processing customer"}
35+
----
36+
37+
[id="serverless-nodejs-context-object-reference-query_{context}"]
38+
== query
39+
40+
Returns the query string for the request, if any, as key-value pairs. These attributes are also found on the context object itself.
41+
42+
.Example query
43+
[source,javascript]
44+
----
45+
function handle(context) {
46+
// Log the 'name' query parameter
47+
context.log.info(context.query.name);
48+
// Query parameters are also attached to the context
49+
context.log.info(context.name);
50+
}
51+
----
52+
53+
You can access the function by using the `curl` command to invoke it:
54+
55+
.Example command
56+
[source,terminal]
57+
----
58+
$ curl http://example.com?name=tiger
59+
----
60+
61+
.Example output
62+
[source,terminal]
63+
----
64+
{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"tiger"}
65+
----
66+
67+
[id="serverless-nodejs-context-object-reference-body_{context}"]
68+
== body
69+
70+
Returns the request body if any. If the request body contains JSON code, this will be parsed so that the attributes are directly available.
71+
72+
.Example body
73+
[source,javascript]
74+
----
75+
function handle(context) {
76+
// log the incoming request body's 'hello' parameter
77+
context.log.info(context.body.hello);
78+
}
79+
----
80+
81+
You can access the function by using the `curl` command to invoke it:
82+
83+
.Example command
84+
[source,terminal]
85+
----
86+
$ curl -X POST -d '{"hello": "world"}' -H 'Content-type: application/json' http://example.com
87+
----
88+
89+
.Example output
90+
[source,terminal]
91+
----
92+
{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"world"}
93+
----
94+
95+
[id="serverless-nodejs-context-object-reference-headers_{context}"]
96+
== headers
97+
98+
Returns the HTTP request headers as an object.
99+
100+
.Example header
101+
[source,javascript]
102+
----
103+
function handle(context) {
104+
context.log.info(context.headers["custom-header"]);
105+
}
106+
----
107+
108+
You can access the function by using the `curl` command to invoke it:
109+
110+
.Example command
111+
[source,terminal]
112+
----
113+
$ curl -H 'x-custom-header: some-value’' http://example.com
114+
----
115+
116+
.Example output
117+
[source,terminal]
118+
----
119+
{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"some-value"}
120+
----
121+
122+
[id="serverless-nodejs-context-object-reference-http-requests_{context}"]
123+
== HTTP requests
124+
125+
method:: Returns the HTTP request method as a string.
126+
httpVersion:: Returns the HTTP version as a string.
127+
httpVersionMajor:: Returns the HTTP major version number as a string.
128+
httpVersionMinor:: Returns the HTTP minor version number as a string.

‎modules/serverless-nodejs-function-return-values.adoc

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// Module included in the following assemblies
2+
//
3+
// * /serverless/functions/serverless-developing-nodejs-functions.adoc
4+
5+
[id="serverless-nodejs-function-return-values_{context}"]
6+
= Node.js function return values
7+
8+
Functions can return any valid JavaScript type or can have no return value. When a function has no return value specified, and no failure is indicated, the caller receives a `204 No Content` response.
9+
10+
Functions can also return a CloudEvent or a `Message` object in order to push events into the Knative Eventing system. In this case, the developer is not required to understand or implement the CloudEvent messaging specification. Headers and other relevant information from the returned values are extracted and sent with the response.
11+
12+
.Example
13+
[source,javascript]
14+
----
15+
function handle(context, customer) {
16+
// process customer and return a new CloudEvent
17+
return new CloudEvent({
18+
source: 'customer.processor',
19+
type: 'customer.processed'
20+
})
21+
}
22+
----
23+
24+
[id="serverless-nodejs-function-return-values-headers_{context}"]
25+
== Returning headers
26+
27+
You can set a response header by adding a `headers` property to the `return` object. These headers are extracted and sent with the response to the caller.
28+
29+
.Example response header
30+
[source,javascript]
31+
----
32+
function handle(context, customer) {
33+
// process customer and return custom headers
34+
// the response will be '204 No content'
35+
return { headers: { customerid: customer.id } };
36+
}
37+
----
38+
39+
[id="serverless-nodejs-function-return-values-status-codes_{context}"]
40+
== Returning status codes
41+
42+
You can set a status code that is returned to the caller by adding a `statusCode` property to the `return` object:
43+
44+
.Example status code
45+
[source,javascript]
46+
----
47+
function handle(context, customer) {
48+
// process customer
49+
if (customer.restricted) {
50+
return { statusCode: 451 }
51+
}
52+
}
53+
----
54+
55+
Status codes can also be set for errors that are created and thrown by the function:
56+
57+
.Example error status code
58+
[source,javascript]
59+
----
60+
function handle(context, customer) {
61+
// process customer
62+
if (customer.restricted) {
63+
const err = new Error(‘Unavailable for legal reasons’);
64+
err.statusCode = 451;
65+
throw err;
66+
}
67+
}
68+
----

‎modules/serverless-nodejs-functions-context-objects.adoc

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Module included in the following assemblies
2+
//
3+
// * /serverless/functions/serverless-developing-nodejs-functions.adoc
4+
5+
[id="serverless-nodejs-functions-context-objects_{context}"]
6+
= Node.js context objects
7+
8+
Functions are invoked by providing a `context` object as the first parameter.
9+
10+
.Example context object
11+
[source,javascript]
12+
----
13+
function handle(context, data)
14+
----
15+
16+
This object provides access to the incoming HTTP request information, including the HTTP request method, any query strings or headers sent with the request, the HTTP version, and the request body. Incoming requests that contain a CloudEvent attach the incoming instance of the CloudEvent to the context object so that it can be accessed by using `context.cloudevent`.
17+
18+
[id="serverless-nodejs-functions-context-objects-methods_{context}"]
19+
== Context object methods
20+
21+
The `context` object has a single method, `cloudEventResponse()`, that accepts a data value and returns a CloudEvent.
22+
23+
In a Knative system, if a function deployed as a service is invoked by an event broker sending a CloudEvent, the broker examines the response. If the response is a CloudEvent, this event is handled by the broker.
24+
25+
.Example context object method
26+
[source,javascript]
27+
----
28+
// Expects to receive a CloudEvent with customer data
29+
function handle(context, customer) {
30+
// process the customer
31+
const processed = handle(customer);
32+
return context.cloudEventResponse(customer)
33+
.source('/handle')
34+
.type('fn.process.customer')
35+
.response();
36+
}
37+
----
38+
39+
[id="serverless-nodejs-functions-context-objects-cloudevent-data_{context}"]
40+
== CloudEvent data
41+
42+
If the incoming request is a CloudEvent, any data associated with the CloudEvent is extracted from the event and provided as a second parameter. For example, if a CloudEvent is received that contains a JSON string in its data property that is similar to the following:
43+
44+
[source,json]
45+
----
46+
{
47+
"customerId": "0123456",
48+
"productId": "6543210"
49+
}
50+
----
51+
52+
When invoked, the second parameter to the function, after the `context` object, will be a JavaScript object that has `customerId` and `productId` properties.
53+
54+
.Example signature
55+
[source,javascript]
56+
----
57+
function handle(context, data)
58+
----
59+
60+
The `data` parameter in this example is a JavaScript object that contains the `customerId` and `productId` properties.

‎modules/serverless-nodejs-template.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Module included in the following assemblies
2+
//
3+
// * /serverless/functions/serverless-developing-nodejs-functions.adoc
4+
5+
[id="serverless-nodejs-template_{context}"]
6+
= Node.js function template structure
7+
8+
When you create a Node.js function using the `kn` CLI, the project directory looks like a typical Node.js project, with the exception of an additional `func.yaml` configuration file.
9+
10+
Both `http` and `event` trigger functions have the same template structure:
11+
12+
.Template structure
13+
[source,terminal]
14+
----
15+
.
16+
├── func.yaml <1>
17+
├── index.js <2>
18+
├── package.json <3>
19+
├── README.md
20+
└── test <4>
21+
├── integration.js
22+
└── unit.js
23+
----
24+
<1> The `func.yaml` configuration file is used to determine the image name and registry.
25+
<2> Your project must contain an `index.js` file which exports a single function.
26+
<3> You are not restricted to the dependencies provided in the template `package.json` file. You can add additional dependencies as you would in any other Node.js project.
27+
+
28+
.Example of adding npm dependencies
29+
[source,terminal]
30+
----
31+
npm install --save opossum
32+
----
33+
+
34+
When the project is built for deployment, these dependencies are included in the created runtime container image.
35+
<4> Integration and unit test scripts are provided as part of the function template.

‎modules/serverless-testing-nodejs-functions.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assemblies
2+
//
3+
// * /serverless/functions/serverless-developing-nodejs-functions.adoc
4+
5+
[id="serverless-testing-nodejs-functions_{context}"]
6+
= Testing Node.js functions
7+
8+
Node.js functions can be tested locally on your computer. In the default project that is created when you create a function using `kn func create`, there is a *test* folder that contains some simple unit and integration tests.
9+
10+
.Procedure
11+
12+
* Run the tests:
13+
+
14+
[source,terminal]
15+
----
16+
$ npm test
17+
----

‎serverless/functions/serverless-developing-nodejs-functions.adoc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
include::modules/serverless-document-attributes.adoc[]
2+
[id="serverless-developing-nodejs-functions"]
3+
= Developing Node.js functions
4+
:context: serverless-developing-nodejs-functions
5+
include::modules/common-attributes.adoc[]
6+
7+
toc::[]
8+
9+
:FeatureName: {FunctionsProductName}
10+
include::modules/technology-preview.adoc[leveloffset=+2]
11+
12+
After you have xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-create-func-kn_serverless-functions-getting-started[created a Node.js function project], you can modify the template files provided to add business logic to your function.
13+
14+
[id="prerequisites_serverless-developing-nodejs-functions"]
15+
== Prerequisites
16+
17+
* Before you can develop functions, you must complete the steps in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductName}].
18+
19+
include::modules/serverless-nodejs-template.adoc[leveloffset=+1]
20+
21+
[id="serverless-developing-nodejs-functions-about-invoking_{context}"]
22+
== About invoking Node.js functions
23+
24+
When using the `kn` CLI to create a function project, you can generate a project that responds to CloudEvents, or one that responds to simple HTTP requests. CloudEvents in Knative are transported over HTTP as a POST request, so both function types listen for and respond to incoming HTTP events.
25+
26+
Node.js functions can be invoked with a simple HTTP request. When an incoming request is received, functions are invoked with a `context` object as the first parameter.
27+
28+
include::modules/serverless-nodejs-functions-context-objects.adoc[leveloffset=+2]
29+
include::modules/serverless-nodejs-function-return-values.adoc[leveloffset=+1]
30+
include::modules/serverless-testing-nodejs-functions.adoc[leveloffset=+1]
31+
32+
[id="next-steps_serverless-developing-nodejs-functions"]
33+
== Next steps
34+
35+
* See the xref:../../serverless/functions/serverless-functions-reference-guide.adoc#serverless-nodejs-context-object-reference_serverless-functions-reference-guide[Node.js context object reference] documentation.
36+
* xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-build-func-kn_serverless-functions-getting-started[Build] and xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-deploy-func-kn_serverless-functions-getting-started[deploy] a function.

‎serverless/functions/serverless-functions-about.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsP
1919
{FunctionsProductName} provides templates that can be used to create basic functions for the following runtimes:
2020

2121
// add xref links to docs once added
22-
* Node.js
22+
* xref:../../serverless/functions/serverless-developing-nodejs-functions.adoc#serverless-developing-nodejs-functions[Node.js]
2323
* xref:../../serverless/functions/serverless-developing-python-functions.adoc#serverless-developing-python-functions[Python]
2424
* xref:../../serverless/functions/serverless-developing-go-functions.adoc#serverless-developing-go-functions[Golang]
2525
* Quarkus

‎serverless/functions/serverless-functions-getting-started.adoc

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,3 @@ Before you can complete the following procedures, you must ensure that you have
2020
include::modules/serverless-create-func-kn.adoc[leveloffset=+1]
2121
include::modules/serverless-build-func-kn.adoc[leveloffset=+1]
2222
include::modules/serverless-deploy-func-kn.adoc[leveloffset=+1]
23-
24-
[id="additional-resources_serverless-functions-getting-started"]
25-
== Additional resources
26-
27-
* See the reference documentation for xref:../../serverless/cli_reference/kn-func-ref.adoc#kn-func-ref[`kn func`].

0 commit comments

Comments
 (0)