OpenFaaS Golang HTTP templates

This repository contains two Golang templates for OpenFaaS which give additional control over the HTTP request and response. They will both handle higher throughput than the classic watchdog due to the process being kept warm.

Using the templates:

faas-cli template store pull golang-http
faas-cli template store pull golang-middleware

Or:

$ faas template pull https://github.com/openfaas-incubator/golang-http-template
$ faas new --list

Languages available as templates:
- golang-http
- golang-middleware

The two templates are equivalent with golang-http using a structured request/response object and the alternative implementing a Golang http.HandleFunc from the Golang stdlib. golang-http is more "conventional" for a Golang serverless template but this is a question of style/taste.

Dependencies

You can manage dependencies in one of the following ways:

To use Go modules without vendoring, add --build-arg GO111MODULE=on to faas-cli up, you can also use --build-arg GOPROXY=https:// if you want to use your own mirror for the modules
You can also Go modules with vendoring, run go mod vendor in your function folder and add --build-arg GO111MODULE=on to faas-cli up
For traditional vendoring with dep give no argument, or add --build-arg GO111MODULE=off to faas-cli up

1.0 golang-http

This template provides additional context and control over the HTTP response from your function.

Status of the template

This template is the most performant and recent Golang template for OpenFaaS which also provides a function-style request and response for the user.

Get the template

$ faas template store pull golang-http

# Or
$ faas template pull https://github.com/openfaas-incubator/golang-http-template
$ faas new --lang golang-http <fn-name>

Example usage

Example writing a successful message:

package function

import (
	"fmt"
	"net/http"

	"github.com/openfaas-incubator/go-function-sdk"
)

// Handle a function invocation
func Handle(req handler.Request) (handler.Response, error) {
	var err error

	message := fmt.Sprintf("Hello world, input was: %s", string(req.Body))

	return handler.Response{
		Body:       []byte(message),
    }, err
}

Example writing a custom status code

package function

import (
	"fmt"
	"net/http"

	"github.com/openfaas-incubator/go-function-sdk"
)

// Handle a function invocation
func Handle(req handler.Request) (handler.Response, error) {
	var err error

	return handler.Response{
		Body:       []byte("Your workload was accepted"),
		StatusCode: http.StatusAccepted,
	}, err
}

Example writing an error / failure.

package function

import (
	"fmt"
	"net/http"

	"github.com/openfaas-incubator/go-function-sdk"
)

// Handle a function invocation
func Handle(req handler.Request) (handler.Response, error) {
	var err error

	return handler.Response{
        Body: []byte("the input was invalid")
	}, fmt.Errorf("invalid input")
}

The error will be logged to stderr and the body will be written to the client along with a HTTP 500 status code.

Example reading a header.

package function

import (
	"log"

	"github.com/openfaas-incubator/go-function-sdk"
)

// Handle a function invocation
func Handle(req handler.Request) (handler.Response, error) {
	var err error

	log.Println(req.Header) // Check function logs for the request headers

	return handler.Response{
		Body: []byte("This is the response"),
		Header: map[string][]string{
			"X-Served-By": []string{"My Awesome Function"},
		},
	}, err
}

Example responding to an aborted request.

The Request object provides access to the request context. This allows you to check if the request has been cancelled by using the context's done channel req.Context().Done() or the context's error req.Context().Err()

package function

import (
	"fmt"
	"net/http"

	handler "github.com/openfaas-incubator/go-function-sdk"
)

// Handle a function invocation
func Handle(req handler.Request) (handler.Response, error) {
	var err error

	for i := 0; i < 10000; i++ {
		if req.Context().Err() != nil  {
			return handler.Response{}, fmt.Errorf("request cancelled")
		}
		fmt.Printf("count %d\n", i)
	}

	message := fmt.Sprintf("Hello world, input was: %s", string(req.Body))
	return handler.Response{
		Body:       []byte(message),
		StatusCode: http.StatusOK,
	}, err
}

This context can also be passed to other methods so that they can respond to the cancellation as well, for example db.ExecContext(req.Context())

2.0 golang-middleware

This template uses the http.HandlerFunc as entry point.

Status of the template

Like the golang-http template, this is one of the fastest templates available, but takes a more service-orientated approach to its signature. Instead of looking like a traditional function, the user has complete control over the HTTP request and response.

Get the template

$ faas template store pull golang-middleware

# Or

$ faas template pull https://github.com/openfaas-incubator/golang-http-template
$ faas new --lang golang-middleware <fn-name>

Example usage

Example writing a JSON response:

package function

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"os"
)

func Handle(w http.ResponseWriter, r *http.Request) {
	var input []byte

	if r.Body != nil {
		defer r.Body.Close()

		// read request payload
		reqBody, err := ioutil.ReadAll(r.Body)

		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return

		input = reqBody
		}
	}

	// log to stdout
	fmt.Printf("request body: %s", string(input))

	response := struct {
		Payload     string              `json:"payload"`
		Headers     map[string][]string `json:"headers"`
		Environment []string            `json:"environment"`
	}{
		Payload:     string(input),
		Headers:     r.Header,
		Environment: os.Environ(),
	}

	resBody, err := json.Marshal(response)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

    // write result
	w.WriteHeader(http.StatusOK)
	w.Write(resBody)
}

Example persistent database connection pool between function calls:

package function

import (
	"database/sql"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
	_ "github.com/go-sql-driver/mysql"
)

// db pool shared between function calls
var db *sql.DB

func init() {
	var err error
	db, err = sql.Open("mysql", "user:password@/dbname")
	if err != nil {
		panic(err.Error())
	}

	err = db.Ping()
	if err != nil {
		panic(err.Error())
	}
}

func Handle(w http.ResponseWriter, r *http.Request) {
	var query string
	ctx := r.Context()

	if r.Body != nil {
		defer r.Body.Close()

		// read request payload
		body, err := ioutil.ReadAll(r.Body)

		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}

		query = string(body)
	}

	// log to stdout
	fmt.Printf("Executing query: %s", query)

	rows, err := db.QueryContext(ctx, query)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
	defer rows.Close()

	ids := make([]string, 0)
	for rows.Next() {
		if e := ctx.Err(); e != nil {
			http.Error(w, e, http.StatusBadRequest)
			return
		}
		var id int
		if err := rows.Scan(&id); err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		ids = append(ids, string(id))
	}
	if err := rows.Err(); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	result := fmt.Sprintf("ids %s", strings.Join(ids, ", "))

	// write result
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(result))
}

Example retrieving request query strings

package function
import (
	"fmt"
	"net/http"
)
func Handle(w http.ResponseWriter, r *http.Request) {
	// Parses RawQuery and returns the corresponding
	// values as a map[string][]string
	// for more info https://golang.org/pkg/net/url/#URL.Query
	query := r.URL.Query()
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(fmt.Sprintf("id: %s", query.Get("id"))))
}

Advanced usage

Sub-packages

It is often natural to organize your code into sub-packages, for example you may have a function with the following structure

./echo
├── go.mod
├── go.sum
├── handler.go
└── pkg
    └── version
        └── version.go

First update your go.mod file to replace handler/function with your local folder

go mod edit -replace=handler/function=./

Now if you want to reference theversion sub-package, import it as

import "handler/function/pkg/version"

This replacement is handled gracefully by the template at build time and your local development environment will now recognize the sub-package.

Go sub-modules

For this example you will need to be using Go 1.13 or newer and Go modules, enable this via faas-cli build --build-arg GO111MODULE=on.

Imagine you have a package which you want to store outside of the handler.go file, it's another middleware which can perform an echo of the user's input.

package handlers

import (
	"io/ioutil"
	"net/http"
)

func Echo(w http.ResponseWriter, r *http.Request) {
	if r.Body != nil {
		defer r.Body.Close()
		b, _ := ioutil.ReadAll(r.Body)
		w.Write(b)
	}
}

To include a relative module such as this new handlers package, you should update your go.mod file as follows:

go mod edit -replace=github.com/alexellis/vault/purchase/handlers=./handlers

At build time, this relative path will be handled correctly inside the template.

Now if you want to reference the handlers package from within your handler.go write the following:

package function

import (
	"net/http"

	"github.com/alexellis/vault/purchase/handlers"
)

func Handle(w http.ResponseWriter, r *http.Request) {

	handlers.Echo(w, r)
}

red-gold/go-fiber-template

OpenFaaS Golang HTTP templates

Dependencies

1.0 golang-http

Status of the template

Get the template

Example usage

2.0 golang-middleware

Status of the template

Get the template

Example usage

Advanced usage

Sub-packages

Go sub-modules