Skip to content
FaaS (Function as a service) framework for writing portable Go functions
Go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
framework Fix lint warnings (#15) Nov 14, 2019
funcframework
.travis.yml Fix travis file (#17) Nov 18, 2019
CONTRIBUTING.md Initial commit Oct 14, 2019
LICENSE
README.md
go.mod Bump dependency versions (#19) Nov 19, 2019
go.sum

README.md

Functions Framework for Go Build Status GoDoc Go version

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:

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.

You can’t perform that action at this time.