Chapter 12. Functions development reference guide

When you create a Go function by using the Knative (kn) CLI, the project directory looks like a typical Go project. The only exception is the additional func.yaml configuration file, which is used for specifying the image.

Go functions have few restrictions. The only requirements are that your project must be defined in a function module, and must export the function Handle().

Both http and event trigger functions have the same template structure:

fn
├── README.md
├── func.yaml
├── go.mod
├── go.sum
├── handle.go
└── handle_test.go

$ go get gopkg.in/yaml.v2@v2.4.0

When you use the Knative (kn) CLI to create a function project, you can generate a project that responds to CloudEvents or simple HTTP requests. Different methods call Go functions, depending on whether an HTTP request or a CloudEvent triggers them.

func Handle(ctx context.Context, res http.ResponseWriter, req *http.Request) {
  // Read body
  body, err := ioutil.ReadAll(req.Body)
  defer req.Body.Close()
  if err != nil {
	http.Error(res, err.Error(), 500)
	return
  }
  // Process body and function logic
  // ...
}

Handle()
Handle() error
Handle(context.Context)
Handle(context.Context) error
Handle(cloudevents.Event)
Handle(cloudevents.Event) error
Handle(context.Context, cloudevents.Event)
Handle(context.Context, cloudevents.Event) error
Handle(cloudevents.Event) *cloudevents.Event
Handle(cloudevents.Event) (*cloudevents.Event, error)
Handle(context.Context, cloudevents.Event) *cloudevents.Event
Handle(context.Context, cloudevents.Event) (*cloudevents.Event, error)

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

type Purchase struct {
  CustomerId string `json:"customerId"`
  ProductId  string `json:"productId"`
}
func Handle(ctx context.Context, event cloudevents.Event) (err error) {

  purchase := &Purchase{}
  if err = event.DataAs(purchase); err != nil {
	fmt.Fprintf(os.Stderr, "failed to parse incoming CloudEvent %s\n", err)
	return
  }
  // ...
}

func Handle(ctx context.Context, event cloudevents.Event) {
  bytes, err := json.Marshal(event)
  // ...
}

Functions triggered by HTTP requests can set the response directly. You can configure the function to do this by using the Go http.ResponseWriter parameter.

The following example displays HTTP response:

func Handle(ctx context.Context, res http.ResponseWriter, req *http.Request) {
  // Set response
  res.Header().Add("Content-Type", "text/plain")
  res.Header().Add("Content-Length", "3")
  res.WriteHeader(200)
  _, err := fmt.Fprintf(res, "OK\n")
  if err != nil {
	fmt.Fprintf(os.Stderr, "error or response write: %v", err)
  }
}

Functions triggered by a cloud event might return nothing, error, or CloudEvent to push events into the Knative Eventing system. In this case, you must set a unique ID, proper Source, and a Type for the cloud event. The data can be populated from a defined structure, or from a map.

The following example displays CloudEvent response:

func Handle(ctx context.Context, event cloudevents.Event) (resp *cloudevents.Event, err error) {
  // ...
  response := cloudevents.NewEvent()
  response.SetID("example-uuid-32943bac6fea")
  response.SetSource("purchase/getter")
  response.SetType("purchase")
  // Set the data from Purchase type
  response.SetData(cloudevents.ApplicationJSON, Purchase{
	CustomerId: custId,
	ProductId:  prodId,
  })
  // OR set the data directly from map
  response.SetData(cloudevents.ApplicationJSON, map[string]string{"customerId": custId, "productId": prodId})
  // Validate the response
  resp = &response
  if err = resp.Validate(); err != nil {
	fmt.Printf("invalid event created. %v", err)
  }
  return
}

Go functions can be tested locally on your computer. In the default project that is created when you create a function by using kn func create, there is a handle_test.go file, which has some basic tests. These tests can be extended as needed.

When you create a Quarkus function by using the Knative (kn) CLI, the project directory looks similar to a typical Maven project. Additionally, the project has the func.yaml file, which is used for configuring the function.

Both http and event trigger functions have the same template structure:

.
├── func.yaml 

├── mvnw
├── mvnw.cmd
├── pom.xml 

├── README.md
└── src
    ├── main
    │   ├── java
    │   │   └── functions
    │   │       ├── Function.java 

    │   │       ├── Input.java
    │   │       └── Output.java
    │   └── resources
    │       └── application.properties
    └── test
        └── java
            └── functions 

                ├── FunctionTest.java
                └── NativeFunctionIT.java

You get an output similar to the following example:

...
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.13</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.assertj</groupId>
      <artifactId>assertj-core</artifactId>
      <version>3.8.0</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
...

Dependencies are downloaded during the first compilation.

You can create a Quarkus project that responds to cloud events, or one that responds to simple HTTP requests. Cloud events in Knative are transported over HTTP as a POST request, so either function type can listen and respond to incoming HTTP requests.

When an incoming request is received, Quarkus functions are invoked with an instance of a permitted type.

The following table displays function invocation options:

The following example shows a function that receives and processes the customerId and productId buy data that is listed in the earlier table:

You get an output similar to the following example:

public class Functions {
    @Funq
    public void processPurchase(Purchase purchase) {
        // process the purchase
    }
}

The corresponding Purchase JavaBean class that has the purchase data looks as follows:

You get an output similar to the following example:

public class Purchase {
    private long customerId;
    private long productId;
    // getters and setters
}

import io.quarkus.funqy.Funq;
import io.quarkus.funqy.knative.events.CloudEvent;

public class Input {
    private String message;

    // getters and setters
}

public class Output {
    private String message;

    // getters and setters
}

public class Functions {
    @Funq
    public Output withBeans(Input in) {
        // function body
    }

    @Funq
    public CloudEvent<Output> withCloudEvent(CloudEvent<Input> in) {
        // function body
    }

    @Funq
    public void withBinary(byte[] in) {
        // function body
    }
}

If you need to read or write the attributes of a CloudEvent, such as type or subject, you can use the CloudEvent<T> generic interface and the CloudEventBuilder builder. The <T> type parameter must be one of the permitted types.

In the following example, CloudEventBuilder is used to return success or failure of processing the purchase:

public class Functions {

    private boolean _processPurchase(Purchase purchase) {
        // do stuff
    }

    public CloudEvent<Void> processPurchase(CloudEvent<Purchase> purchaseEvent) {
        System.out.println("subject is: " + purchaseEvent.subject());

        if (!_processPurchase(purchaseEvent.data())) {
            return CloudEventBuilder.create()
                    .type("purchase.error")
                    .build();
        }
        return CloudEventBuilder.create()
                .type("purchase.success")
                .build();
    }
}

Functions can return an instance of any type from the list of permitted types. Or, they can return the Uni<T> type, where the <T> type parameter can be of any type from the permitted types.

The Uni<T> type is useful if a function calls asynchronous APIs, because the returned object is serialized in the same format as the received object. For example:

The following example shows a function that fetches a list of purchases:

public class Functions {
    @Funq
    public List<Purchase> getPurchasesByName(String name) {
      // logic to retrieve purchases
    }
}

public class Functions {
    public List<Integer> getIds();
    public Purchase[] getPurchasesByName(String name);
    public String getNameById(int id);
    public Map<String,Integer> getNameIdMapping();
    public void processImage(byte[] img);
}

You can test Quarkus functions locally on your computer. The default project that kn func create creates has a src/test/ directory with basic Maven tests. You can extend these tests as needed.

You can override liveness and readiness probe values for your Quarkus functions. Configure these probes to define how the platform performs health checks on the function.

When you create a Node.js function by using the Knative (kn) CLI, the project directory looks like a typical Node.js project. The only exception is the additional func.yaml file, which is used to configure the function.

Both http and event trigger functions have the same template structure:

.
├── func.yaml 

├── index.js 

├── package.json 

├── README.md
└── test 

    ├── integration.js
    └── unit.js

You get an output similar to the following example:

npm install --save opossum

When the project is built for deployment, these dependencies are included in the created runtime container image.

When using the Knative (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.

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.

// 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 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.

Functions can also return a CloudEvent or a Message object 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.

You get an output similar to the following example:

function handle(context, customer) {
  // process customer and return a new CloudEvent
  return new CloudEvent({
    source: 'customer.processor',
    type: 'customer.processed'
  })
}

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

$ curl https://myfunction.example.com

This function Works!

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

$ curl https://myfunction.example.com

100

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

$ curl https://myfunction.example.com

false

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

$ http :8080

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

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

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

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

Node.js functions can be tested locally on your computer. In the default project that is created when you create a function by using kn func create, there is a test folder that has some simple unit and integration tests.

You can override liveness and readiness probe values for your Node.js functions. You can configure health checks performed on the function.

export interface Function {
  init?: () => any;

  shutdown?: () => any;

  liveness?: HealthCheck;

  readiness?: HealthCheck;

  logLevel?: LogLevel;

  handle: CloudEventFunction | HTTPFunction;
}

For example, add the following code to the index.js file:

const Function = {

  handle: (context, body) => {
    // The function logic goes here
    return 'function called'
  },

  liveness: () => {
    process.stdout.write('In liveness\n');
    return 'ok, alive';
  },

  readiness: () => {
    process.stdout.write('In readiness\n');
    return 'ok, ready';
  }
};

Function.liveness.path = '/alive';
Function.readiness.path = '/ready';

module.exports = Function;

As an alternative to Function.liveness.path and Function.readiness.path, you can specify custom endpoints by using the LIVENESS_URL and READINESS_URL environment variables:

run:
  envs:
  - name: LIVENESS_URL
    value: /alive
  - name: READINESS_URL
    value: /ready

deploy:
  healthEndpoints:
    liveness: /alive
    readiness: /ready

The context object has several properties that can be accessed by the function developer. Accessing these properties can give information about HTTP requests and write output to the cluster logs.

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

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

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

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);
}

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

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

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

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

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

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

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

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

When you create a TypeScript function by using the Knative (kn) CLI, the project directory looks like a typical TypeScript project. The only exception is the additional func.yaml file, which is used for configuring the function.

Both http and event trigger functions have the same template structure:

.
├── func.yaml
├── package.json
├── package-lock.json
├── README.md
├── src
│   └── index.ts
├── test
│   ├── integration.ts
│   └── unit.ts
└── tsconfig.json

The following displays how to add npm dependencies:

npm install --save opossum

When the project is built for deployment, these dependencies are included in the created runtime container image.

When you use the Knative (kn) CLI to create a function project, you can generate a project that responds to CloudEvents or simple HTTP requests. Knative sends CloudEvents over HTTP as POST requests, so both function types listen for and respond to incoming HTTP events.

You can call TypeScript functions with a simple HTTP request. When a function receives a request, the runtime calls it with a context object as the first parameter.

function handle(context:Context): string

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

// Invokable is the expeted Function signature for user functions
export interface Invokable {
    (context: Context, cloudevent?: CloudEvent): any
}

// Logger can be used for structural logging to the console
export interface Logger {
  debug: (msg: any) => void,
  info:  (msg: any) => void,
  warn:  (msg: any) => void,
  error: (msg: any) => void,
  fatal: (msg: any) => void,
  trace: (msg: any) => void,
}

// Context represents the function invocation context, and provides
// access to the event itself as well as raw HTTP objects.
export interface Context {
    log: Logger;
    req: IncomingMessage;
    query?: Record<string, any>;
    body?: Record<string, any>|string;
    method: string;
    headers: IncomingHttpHeaders;
    httpVersion: string;
    httpVersionMajor: number;
    httpVersionMinor: number;
    cloudevent: CloudEvent;
    cloudEventResponse(data: string|object): CloudEventResponse;
}

// CloudEventResponse is a convenience class used to create
// CloudEvents on function returns
export interface CloudEventResponse {
    id(id: string): CloudEventResponse;
    source(source: string): CloudEventResponse;
    type(type: string): CloudEventResponse;
    version(version: string): CloudEventResponse;
    response(): CloudEvent;
}

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

function handle(context: Context, cloudevent?: CloudEvent): CloudEvent

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.

Functions can also return a CloudEvent or a Message object 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.

You get an output similar to the following example:

export const handle: Invokable = function (
  context: Context,
  cloudevent?: CloudEvent
): Message {
  // process customer and return a new CloudEvent
  const customer = cloudevent.data;
  return HTTP.binary(
    new CloudEvent({
      source: 'customer.processor',
      type: 'customer.processed'
    })
  );
};

export function handle(context: Context, cloudevent?: CloudEvent): Record<string, any> {
  // process customer and return custom headers
  const customer = cloudevent.data as Record<string, any>;
  return { headers: { 'customer-id': customer.id } };
}

export function handle(context: Context, cloudevent?: CloudEvent): Record<string, any> {
  // process customer
  const customer = cloudevent.data as Record<string, any>;
  if (customer.restricted) {
    return {
      statusCode: 451
    }
  }
  // business logic, then
  return {
    statusCode: 240
  }
}

export function handle(context: Context, cloudevent?: CloudEvent): Record<string, string> {
  // process customer
  const customer = cloudevent.data as Record<string, any>;
  if (customer.restricted) {
    const err = new Error(‘Unavailable for legal reasons’);
    err.statusCode = 451;
    throw err;
  }
}

TypeScript functions can be tested locally on your computer. In the default project that is created when you create a function by using kn func create, there is a test folder that has some simple unit and integration tests.

You can override liveness and readiness probe values for your TypeScript functions. Use these probes to configure how the platform performs health checks on the function.

The context object has several properties that can be accessed by the function developer. Accessing these properties can give information about incoming HTTP requests and write output to the cluster logs.

export function handle(context: Context): string {
    // log the incoming request body's 'hello' parameter
    if (context.body) {
      context.log.info((context.body as Record<string, string>).hello);
    } else {
      context.log.info('No data received');
    }
    return 'OK';
}

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

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

export function handle(context: Context): string {
      // log the 'name' query parameter
    if (context.query) {
      context.log.info((context.query as Record<string, string>).name);
    } else {
      context.log.info('No data received');
    }
    return 'OK';
}

$ kn func invoke --target 'http://example.function.com' --data '{"name": "tiger"}'

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

export function handle(context: Context): string {
    // log the incoming request body's 'hello' parameter
    if (context.body) {
      context.log.info((context.body as Record<string, string>).hello);
    } else {
      context.log.info('No data received');
    }
    return 'OK';
}

$ kn func invoke --target 'http://example.function.com' --data '{"hello": "world"}'

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

export function handle(context: Context): string {
    // log the incoming request body's 'hello' parameter
    if (context.body) {
      context.log.info((context.headers as Record<string, string>)['custom-header']);
    } else {
      context.log.info('No data received');
    }
    return 'OK';
}

$ curl -H'x-custom-header: some-value’' http://example.function.com

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

When you create a Python function by using the Knative (kn) CLI, the project directory looks similar to a typical Python project. Python functions have very few restrictions. The only requirements are that your project contains a func.py file that contains a main() function, and a func.yaml configuration file.

Developers are not restricted to the dependencies provided in the template requirements.txt file. Additional dependencies can be added as they would be in any other Python project. When the project is built for deployment, these dependencies will be included in the created runtime container image.

Both http and event trigger functions have the same template structure:

fn
├── func.py 

├── func.yaml 

├── requirements.txt 

└── test_func.py 

You can call Python functions with a simple HTTP request. When a function receives a request, the runtime calls it with a context object as the first parameter.

The context object is a Python class with two attributes:

Developers can access any CloudEvent data from the context object.

You get an output similar to the following example:

def main(context: Context):
    """
    The context parameter contains the Flask request object and any
    CloudEvent received with the request.
    """
    print(f"Method: {context.request.method}")
    print(f"Event data {context.cloud_event.data}")
    # ... business logic here

Functions can return any value supported by Flask. This is because the invocation framework proxies these values directly to the Flask server.

You get an output similar to the following example:

def main(context: Context):
    body = { "message": "Howdy!" }
    headers = { "content-type": "application/json" }
    return body, 200, headers

Functions can set both headers and response codes as secondary and tertiary response values from function invocation.

@event("event_source"="/my/function", "event_type"="my.type")
def main(context):
    # business logic here
    data = do_something()
    # more data processing
    return data

You can test Python functions locally on your computer. The default project has a test_func.py file, which provides a simple unit test for functions.