functions-framework-go

module
Version: v1.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 24, 2021 License: Apache-2.0

README

Functions Framework for Go

GoDoc Go version

Go unit CI Go lint CI Go conformace CI

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

  • Build your Function in the same container environment used by Cloud Functions using buildpacks.
  • 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. Install Go 1.11+.

  2. Create a Go module:

    go mod init example.com/hello
    

    ``

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

  3. 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).

  4. To run locally, you'll need to create a main package to start your server (see instructions below for container builds to skip this step and match your local development environment to production):

    mkdir cmd
    
  5. Create a cmd/main.go file with the following contents:

    package main
    import (
    	"log"
    	"os"
    	"context"
    	"github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
    	"example.com/hello"
    )
    func main() {
    	ctx := context.Background()
    	if err := funcframework.RegisterHTTPFunctionContext(ctx, "/", hello.HelloWorld); err != nil {
            log.Fatalf("funcframework.RegisterHTTPFunctionContext: %v\n", err)
    	}
    	// 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)
    	}
    }
    

    ``

  6. Start the local development server:

    cd cmd
    go run main.go
    # Output: Serving function...
    

    ``

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

    curl localhost:8080
    # Output: Hello, World!
    

    ``

Go further: build a deployable container

  1. Install Docker and the pack tool.

  2. Build a container from your function using the Functions buildpacks:

    pack build \
    	--builder gcr.io/buildpacks/builder:v1 \
    	--env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \
    	--env GOOGLE_FUNCTION_TARGET=HelloWorld \
    	my-first-function
    

    ``

  3. Start the built container:

    docker run --rm -p 8080:8080 my-first-function
    # Output: Serving function...
    

    ``

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

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

Functions Framework Features

The Go Functions Framework conforms to the Functions Framework Contract, As such, it supports HTTP functions, background event functions, and CloudEvent functions (as of v1.1.0). The primary build mechanism is the GCP buildpacks stack, which takes a function of one of the accepted types, converts it to a full HTTP serving app, and creates a launchable container to run the server.

HTTP Functions

The Framework provides support for handling native Go HTTP-style functions:

func HTTPFunction(w http.ResponseWriter, r *http.Request) error {
	// Do something with r, and write response to w.
}

These functions are registered with the handler via funcframework.RegisterHTTPFunctionContext.

Background Event Functions

Background events are also supported. This type of function takes two parameters: a Go context and a user-defined data struct.

func BackgroundEventFunction(ctx context.Context, data userDefinedEventStruct) error {
	// Do something with ctx and data.
}

This type of event requires you to define a struct with the appropriate data fields (e.g. those for a PubSub message or GCS event) and pass that struct as the data parameter. See the samples for details.

The context parameter is a Go context.Context, and contains additional event metadata under a functions-specific key. This data is accesible via the cloud.google.com/go/functions/metadata package:

m := metadata.FromContext(ctx)

These functions are registered with the handler via funcframework.RegisterEventFunctionContext.

CloudEvent Functions

The Functions Framework provides support for unmarshalling an incoming CloudEvent payload into a cloudevents.Event object. These will be passed as arguments to your function when it receives a request.

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

These functions are registered with the handler via funcframework.RegisterCloudEventFunctionContext.

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

Declarative Functions

The Functions Framework also provides a way to declaratively define HTTP and CloudEvent functions:

package function

import (
	"net/http"

	funcframework "github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
)

func init() {
	funcframework.HTTP("hello", HelloWorld)
	funcframework.CloudEvent("ce", CloudEvent)
}

func HelloWorld(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello, World!"))
}

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

Upon starting, the framework will listen to HTTP requests at / and invoke your registered function specified by the FUNCTION_TARGET environment variable (i.e. FUNCTION_TARGET=hello).

Directories

Path Synopsis
Package funcframework is a Functions Framework implementation for Go.
Package funcframework is a Functions Framework implementation for Go.
internal
events/pubsub
Package pubsub contains utilities for handling Google Cloud Pub/Sub events.
Package pubsub contains utilities for handling Google Cloud Pub/Sub events.
fftypes
Package fftypes contains core types used throughout the functions framework (ff) implementation.
Package fftypes contains core types used throughout the functions framework (ff) implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL