https://github.com/fnproject/fdk-node
Experimental FDK for Node.js
https://github.com/fnproject/fdk-node
Last synced: about 1 year ago
JSON representation
Experimental FDK for Node.js
- Host: GitHub
- URL: https://github.com/fnproject/fdk-node
- Owner: fnproject
- License: apache-2.0
- Created: 2018-01-17T19:29:33.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-04-24T09:17:50.000Z (about 1 year ago)
- Last Synced: 2025-05-09T01:59:06.567Z (about 1 year ago)
- Language: JavaScript
- Size: 551 KB
- Stars: 23
- Watchers: 29
- Forks: 12
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Fn Function Developer Kit for Node.js
This Function Developer Kit makes it easy to deploy Node.js functions to Fn.
It currently supports default (cold) and hot functions using the JSON format.
## Creating a Node Function
Writing a Node.js function is simply a matter of writing a handler function
that you pass to the FDK to invoke each time your function is called.
Start by creating a node function with `fn init` and installing the FDK:
```sh
fn init --runtime node nodefunc
cd nodefunc
```
This creates a simple hello world function in `func.js`:
```javascript
const fdk=require('@fnproject/fdk');
fdk.handle(function(input){
let name = 'World';
if (input.name) {
name = input.name;
}
return {'message': 'Hello ' + name}
})
```
The handler function takes the string input that is sent to the function
and returns a response string. Using the FDK you don't have to worry about reading
input from standard input and writing to standard output to return your response.
The FDK let's you focus on your function logic and not the mechanics.
Now run it!
```sh
fn deploy --local --app fdkdemo
fn invoke fdkdemo nodefunc
```
Now you have a basic running Node function that you can modify and add what you want.
```sh
echo -n '{"name": "Tom"}' | fn invoke fdkdemo nodefunc
```
You should see the result
```sh
{"message": "Hello Tom"}
```
## Function Context
Function invocation context details are available through an optional function argument.
To receive a context object, simply add a second argument to your handler function.
in the following example the `callID` is obtained from the context and included in
the response message:
```javascript
const fdk=require('@fnproject/fdk');
fdk.handle(function(input, ctx){
let name = 'World';
if (input) {
name = input;
}
return 'Hello ' + name + ' from Node call ' + ctx.callID + '!';
})
```
The context contains other context information about the request such as:
* `ctx.config` : An Object containing function config variables (from the environment ) (read only)
* `ctx.headers` : an object containing input headers for the event as lists of strings (read only)
* `ctx.deadline` : a `Date` object indicating when the function call must be processed by
* `ctx.callID` : The call ID of the current call
* `ctx.fnID` : The Function ID of the current function
* `ctx.memory` : Amount of ram in MB allocated to this function
* `ctx.contentType` : The incoming request content type (if set, otherwise null)
* `ctx.setResponseHeader(key,values...)` : Sets a response header to one or more values
* `ctx.addResponseHeader(key,values...)` : Appends values to an existing response header
* `ctx.responseContentType` set/read the response content type of the function (read/write)
* `ctx.httpGateway` The HTTP Gateway context for this function (if set) see `HTTPGatewayContext` below
## Asynchronous function responses
You return an asynchronous response from a function by returning a Javascript `Promise` from the function body:
```javascript
const fdk=require('@fnproject/fdk');
fdk.handle(function(input, ctx){
return new Promise((resolve,reject)=>{
setTimeout(()=>resolve("Hello"),1000);
});
})
```
You can also use `async`/`await` calling conventions in functions.
## Handling non-json input and output
By default the FDK will try and convert input into a JSON object, or fall back to its string format otherwise.
Likewise by default the output of a function will be treated as a JSON object and converted using JSON.stringify.
To change the handling of the input you can add an additional `options` parameter to `fdk.handle` that specifies the input handling strategy:
```javascript
function myfunction(input,ctx){}
fdk.handle(myfunction, {inputMode: 'string'})
```
valid input modes are:
* `json` (the default) attempts to parse the input as json or falls back to raw (possibly binary) string value otherwise
* `string` always treats input as a string
* `buffer` reads input into a `Buffer` object and passes this to your function
To change the output handling of your function from the default you should wrap the result value using a response decorator:
```javascript
function myfunction(input,ctx){
return fdk.rawResult("Some string")
}
fdk.handle(myfunction)
```
the available decorators are:
* `rawResult({string|Buffer})` passes the result directly to the response - the value can be a string or a buffer - this will not encode quotes on string objects
* `streamResult({ReadableStream})` pipes the contents of a `ReadableStream` into the output - this allows processing of data from files or HTTP responses
## Using HTTP headers and setting HTTP status codes
You can read http headers passed into a function invocation using `ctx.protocol.header(key)`, this returns the first header value of the header matching `key` (after canonicalization) and `ctx.protocol.headers` which returns an object containing all headers.
```javascript
const fdk=require('@fnproject/fdk');
fdk.handle(function(input, ctx){
let hctx = ctx.httpGateway
console.log("Request URL" , hctx.requestURL)
console.log("Authorization header:" , hctx.getHeader("Authorization"))
console.log( hctx.headers) // prints e.g. { "Content-Type": ["application/json"],"Accept":["application/json","text/plain"] }
})
```
Outbound headers and the HTTP status code can be modified in a similar way:
```javascript
const fdk=require('@fnproject/fdk');
fdk.handle(function(input, ctx){
let hctx = ctx.httpGateway
hctx.setResponseHeader("Location","http://example.com")
hctx.statusCode = 302
})
```
The `HTTPGatewayContext` object has a similar interface to `Context` but accesses only the HTTP headers of the function:
* `hctx.requestURL` : Get the http request URL of the function as received by the gateway (null if not set)
* `hctx.method` : Get the HTTP request method used to invoke the gateway
* `hctx.headers` : Get the HTTP headers of the incoming request (read-only)
* `hctx.statusCode` : Set the the HTTP status code of the HTTP resposne
& `hctx.setResponseHeader(key,values..)`, `hctx.addResponseHeader(key,values)` Set/add response headers
## Fn and Node.js Dependencies
Fn handles Node.js dependencies in the following way:
* If a `package.json` is present without a `node_modules` directory, an Fn build runs an `npm install` within the build process and installs your dependencies.
* If the `node_modules` is present, Fn assumes you have provided the dependencies yourself and no installation is performed.