functions-framework-go

Functions Framework for Go

An open source FaaS (Function as a Service) framework for writing portable Go functions, brought to you by the Google Cloud Functions team.

The Functions Framework lets you write lightweight functions that run in many different environments, including:

• Google Cloud Functions
• Your local development machine
• Knative-based environments
• Google App Engine
• Google Cloud Run

The framework allows you to go from:

func HelloWorld(w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Hello, World!")
}

To:

curl http://my-url
# Output: Hello, World!

All without needing to worry about writing an HTTP server or request handling logic.

Features

• Spin up a local development server for quick testing with little extra code
• Invoke a function in response to a request
• Automatically unmarshal events conforming to the CloudEvents spec
• Portable between serverless platforms

Quickstart: Hello, World on your local machine

1. Make sure you have Go 1.11+ installed with:

   go version
   

   The output should be Go 1.11 or higher.

2. Create the necessary directories.

   mkdir -p hello/cmd
   cd hello
   

3. Create a Go module:

   go mod init example.com/hello
   

   Note: You can use a different module name rather than example.com/hello.

4. Create a function.go file with the following contents:

   package hello
   
   import (
   	"net/http"
   	"fmt"
   )
   
   // HelloWorld writes "Hello, World!" to the HTTP response.
   func HelloWorld(w http.ResponseWriter, r *http.Request) {
   	fmt.Fprint(w, "Hello, World!\n")
   }
   

   Note that you can use any file name or package name (convention is to make package name same as directory name).

5. Now go to the cmd subdirectory.

   cd cmd
   

6. Create a main.go file with the following contents:

   package main
   
   import (
   	"log"
   	"os"
   
   	"github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
   	"example.com/hello"
   )
   
   func main() {
   	funcframework.RegisterHTTPFunction("/", hello.HelloWorld)
   	// Use PORT environment variable, or default to 8080.
   	port := "8080"
   	if envPort := os.Getenv("PORT"); envPort != "" {
   		port = envPort
   	}
   
   	if err := funcframework.Start(port); err != nil {
   		log.Fatalf("funcframework.Start: %v\n", err)
   	}
   }
   

7. Start the local development server:

   go build
   ./cmd
   Serving function...
   

8. Send requests to this function using curl from another terminal window:

   curl localhost:8080
   # Output: Hello, World!
   

Run your function on serverless platforms

Google Cloud Functions

You cannot deploy main packages to Google Cloud Functions. You need to go back to the parent directory in which your function code is.

cd ..

and you can deploy it from your local machine using the gcloud command-line tool. Check out the Cloud Functions quickstart.

Container environments based on Knative

The Functions Framework is designed to be compatible with Knative environments. Just build and deploy your container to a Knative environment. Note that your app needs to listen PORT environment variable per Knative runtime contract.

Configure the Functions Framework

If you're deploying to Google Cloud Functions, you don't need to worry about writing a package main. But if you want to run your function locally (e.g., for local development), you may want to configure the port, the function to be executed, and the function signature type (which specifies event unmarshalling logic). You can do this by modifying the main.go file described above:

To select a port, set the $PORT environment variable when running.

PORT=8000 ./cmd

To select a function, pass your function to funcframework.RegisterHTTPFunction in the second variable.

funcframework.RegisterHTTPFunction("/", myFunction);

If your function handles events, use funcframework.RegisterEventFunction instead of funcframework.RegisterHTTPFunction.

funcframework.RegisterEventFunction("/", eventFunction);

func eventFunction(ctx context.Context, e myEventType){
	// function logic
}

Note that the first parameter to a function that handles events has to be context.Context and the type of second parameter needs to be a type of an unmarshallable event.

Enable Cloud Events

The Functions Framework can unmarshal to custom structs, and provides support for unmarshalling an incoming CloudEvents payload to a cloudevents.Event object. These will be passed as arguments to your function when it receives a request. Note that your function must use the event-style function signature.

func CloudEventsFunction(ctx context.Context, e cloudevents.Event) {
	// Do something with event.Context and event.Data (via event.DataAs(foo)).
}

To learn more about CloudEvents, see the Go SDK for CloudEvents.