12.3. Developing Node.js functions

Functions are invoked by providing a context object as the first parameter. This object provides access to the incoming HTTP request information.

This information includes 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.

// Expects to receive a CloudEvent with customer data
function handle(context, customer) {
  // process the customer
  const processed = handle(customer);
  return context.cloudEventResponse(customer)
    .source('/handle')
    .type('fn.process.customer')
    .response();
}

{
  "customerId": "0123456",
  "productId": "6543210"
}

function handle(context, data)

{
  "id": "12345",
  "contact": {
    "title": "Mr.",
    "firstname": "John",
    "lastname": "Smith"
  }
}

function handle(context, customer) {
  return "Hello " + customer.contact.title + " " + customer.contact.lastname;
}

Hello Mr. Smith

function handle(context, data) {
  if (context.headers['content-type'] === 'application/json') {
    // handle JSON data
  } else if (context.headers['content-type'] === 'application/xml') {
    // handle XML data
  } else {
    // handle other data types
  }
}

Functions can return any valid JavaScript type, including primitives such as strings, numbers, and booleans:

function handle(context) {
  return "This function Works!"
}

Calling this function returns the following string:

$ curl https://myfunction.example.com

This function Works!

function handle(context) {
  let somenumber = 100
  return { body: somenumber }
}

Calling this function returns the following number:

$ curl https://myfunction.example.com

100

function handle(context) {
  let someboolean = false
  return { body: someboolean }
}

Calling this function returns the following boolean:

$ curl https://myfunction.example.com

false

Returning primitives directly without wrapping them in an object results in a 204 No Content status code with an empty body:

function handle(context) {
  let someboolean = false
  return someboolean
}

Calling this function returns the following:

$ http :8080

HTTP/1.1 204 No Content
Connection: keep-alive
...

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.

function handle(context, customer) {
  // process customer and return custom headers
  // the response will be '204 No content'
  return { headers: { customerid: customer.id } };
}

You can set a status code that is returned to the caller by adding a statusCode property to the return object:

function handle(context, customer) {
  // process customer
  if (customer.restricted) {
    return { statusCode: 451 }
  }
}

Status codes can also be set for errors that are created and thrown by the function:

function handle(context, customer) {
  // process customer
  if (customer.restricted) {
    const err = new Error(‘Unavailable for legal reasons’);
    err.statusCode = 451;
    throw err;
  }
}

Provides a logging object that can be used to write output to the cluster logs. The log adheres to the Pino logging API.

function handle(context) {
  context.log.info(“Processing customer”);
}

You can access the function by using the kn func invoke command:

$ kn func invoke --target 'http://example.function.com'

{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"Processing customer"}

You can change the log level to one of fatal, error, warn, info, debug, trace, or silent. To do that, change the value of logLevel by assigning one of these values to the environment variable FUNC_LOG_LEVEL using the config command.

Returns the query string for the request, if any, as key-value pairs. These attributes are also found on the context object itself.

function handle(context) {
  // Log the 'name' query parameter
  context.log.info(context.query.name);
  // Query parameters are also attached to the context
  context.log.info(context.name);
}

You can access the function by using the kn func invoke command:

$ kn func invoke --target 'http://example.com?name=tiger'

{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"tiger"}

Returns the request body if any. If the request body contains JSON code, this will be parsed so that the attributes are directly available.

function handle(context) {
  // log the incoming request body's 'hello' parameter
  context.log.info(context.body.hello);
}

You can access the function by using the curl command to invoke it:

$ kn func invoke -d '{"Hello": "world"}'

{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"world"}

Returns the HTTP request headers as an object.

function handle(context) {
  context.log.info(context.headers["custom-header"]);
}

You can access the function by using the kn func invoke command:

$ kn func invoke --target 'http://example.function.com'

{"level":30,"time":1604511655265,"pid":3430203,"hostname":"localhost.localdomain","reqId":1,"msg":"some-value"}