Write Cloud Run functions

This page describes how to write HTTP and event-driven Cloud Run functions with the Functions Framework.

Functions Framework overview

When writing functions source code, you must use the Functions Framework, an open source library for writing Cloud Run functions. With the Functions Framework, you can write lightweight functions that run in Cloud Run and in other environments, including your local development machine and Knative-based environments.

The Functions Framework lets you:

  • Invoke a Cloud Run function in response to a request.
  • Automatically unmarshal events conforming to the CloudEvents specification, an industry-standard specification for describing event data in a common way.
  • Start a local development server for testing.

The Functions Framework provides an interface for building modular services. To use the Functions Framework in your source code, specify the following:

Function entry point

Your source code must define a function entry point, which is the code that runs when Cloud Run invokes your function. You specify this entry point when you deploy your function.

How you define the entry point depends on the language runtime you use. Some languages use a function as their entry point, while others use a class.

Signature Type

When you write the source code of a function with the Functions Framework, you must specify one of the two signature types:

  • HTTP functions: Registers an HTTP handler function. Use an HTTP function when your function needs a URL endpoint and must respond to HTTP requests, such as for webhooks.
  • Event-driven functions, also known as CloudEvents functions: Registers a CloudEvents handler function. Use an event-driven function when your function is triggered directly in response to events within your Google Cloud project, such as messages on a Pub/Sub topic or changes in a Cloud Storage bucket.

Source directory structure

The Functions Framework is supported in a number of programming languages. The language runtime you choose and the type of function you want to write determines how to structure your code and implement your function.

For Cloud Run to locate your function definition, each language runtime has requirements for structuring your source code.

Node.js

The basic directory structure for Node.js functions is as follows:

.
├── index.js
└── package.json

By default, Cloud Run attempts to load source code from a file named index.js at the root of your function directory. To specify a different main source file, use the main field in your package.json file.

Your package.json file must also include the Functions Framework for Node.js as a dependency:

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "type": "module"
}

The code in your main file must define your function entry point and can import other code and Node.js modules. The main file can also define multiple function entry points that can be deployed separately.

See the Node.js runtime overview and the Functions Framework for Node.js for more details.

Python

The basic directory structure for Python functions is as follows:

.
├── main.py
└── requirements.txt

Cloud Run loads source code from a file named main.py at the root of your function directory. You must name your main file main.py.

Your requirements.txt file must include the Functions Framework for Python as a dependency:

functions-framework==3.*

The code in your main.py file must define your function entry point and can import other code and external dependencies as normal. The main.py file can also define multiple function entry points that can be deployed separately.

See the Python runtime overview and the Functions Framework for Python for more details.

Go

The basic directory structure for Go functions is as follows:

.
├── myfunction.go
└── go.mod

Your function must be in a Go package at the root of your project. The package and its source files can have any name, except your function cannot be in package main. If you need a main package, for example for local testing, you can create one in a subdirectory:

.
├── myfunction.go
├── go.mod
└── cmd/
  └── main.go

Your go.mod file must include the Functions Framework for Go as a dependency:

module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)

The code in your root package must define your function entry point and can import other code from subpackages and dependencies as normal. Your package can also define multiple function entry points that can be deployed separately.

See the Go runtime overview and the Functions Framework for Go for more details.

Java

The basic directory structure for Java functions is as follows:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── MyFunction.java

Your Java source files must be under the src/main/java/ directory and can have any name. If your source files declare a package, add an extra directory under src/main/java with the name of the package:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── mypackage/
              └── MyFunction.java

We recommend putting associated tests under a src/test/java/ subdirectory.

Your pom.xml file must include the Functions Framework for Java as a dependency:

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

The code in your source files must define your function entry point and can import other code and external dependencies as normal. Your source files can also define multiple function entry points that can be deployed separately.

See the Java runtime overview and the Functions Framework for Java for more details.

.NET

The basic directory structure for .NET functions is as follows:

.
├── MyFunction.cs
└── MyProject.csproj

You can structure your projects as you would any other .NET source code. Your source files can have any name.

Your project file must include the Functions Framework for .NET as a dependency:

...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...

The code in your source files must define your function entry point and can import other code and external dependencies as normal. Your source files can also define multiple function entry points that can be deployed separately.

See the .NET runtime overview and the Functions Framework for .NET for more details.

Ruby

The basic directory structure for Ruby functions is as follows:

.
├── app.rb
├── Gemfile
└── Gemfile.lock

Cloud Run loads source code from a file named app.rb at the root of your function directory. Your main file must be named app.rb.

Your Gemfile file must include the Functions Framework for Ruby as a dependency:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

The code in your app.rb file must define your function entry point and can import other code and external dependencies as normal. The app.rb file can also define multiple function entry points that can be deployed separately.

See the Ruby runtime overview and the Functions Framework for Ruby for more details.

PHP

The basic directory structure for PHP functions is as follows:

.
├── index.php
└── composer.json

Cloud Run loads source code from a file named index.php at the root of your function directory. You must name your main file index.php.

Your composer.json file must include the Functions Framework for PHP as a dependency:

{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}

The code in your index.php file must define your function entry point and can import other code and external dependencies as normal. The index.php file can also define multiple function entry points that can be deployed separately.

See the PHP runtime overview and the Functions Framework for PHP for more details.

If you group multiple functions into a single project, be aware that every function might end up sharing the same set of dependencies. However, some of the functions might not need all of the dependencies.

Where possible, we recommend splitting up large multi-function codebases and putting each function in its own top-level directory as shown in the preceding examples, with its own source and project configuration files. This approach minimizes the number of dependencies required for a particular function, which in turn reduces the amount of memory your function needs.

Write HTTP functions

Write an HTTP function when you want to invoke a function through an HTTP(S) request. To allow for HTTP semantics, you use the Function Framework and specify the HTTP Function signature to accept HTTP-specific arguments.

The following example shows a basic HTTP function source file for each runtime. For a complete working example, see Deploy a Cloud Run function using the Google Cloud CLI. For For more information about where to locate your source code, see Source directory structure.

Node.js

ES module 

import { http } from '@google-cloud/functions-framework';
// Register an HTTP function with the Functions Framework that executes
// when you make an HTTP request to the deployed function's endpoint.
http('helloGET', (req, res) => {
  res.send('Hello World!');
});

Add the following dependencies in your package.json file:

{
  "name": "nodejs-docs-samples-functions-hello-world-get",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google Inc.",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=6000 --exit"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.1.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "gaxios": "^6.0.0",
    "mocha": "^10.0.0",
    "wait-port": "^1.0.4"
  }
}

CommonJS module 

  const functions = require('@google-cloud/functions-framework');

  // Register an HTTP function with the Functions Framework
  functions.http('helloGET', (req, res) => {
    // Your code here

    // Send an HTTP response
    res.send('OK');
  });

Add the following dependencies in your package.json file:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    }
  }

In Node.js, you register an HTTP handler function with the Functions Framework for Node.js. Your HTTP handler function must be an Express middleware function that accepts the request and response arguments and sends an HTTP response.

Cloud Run automatically parses the request body for you based on the request's Content-Type header using body-parser, so you can access the req.body and req.rawBody objects in your HTTP handler.

The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is helloGET.

Python

import functions_framework

# Register an HTTP function with the Functions Framework
@functions_framework.http
def my_http_function(request):
  # Your code here

  # Return an HTTP response
  return 'OK'

In Python, you register an HTTP handler function with the Functions Framework for Python. Your HTTP handler function must accept a Flask request object as an argument and return a value that Flask can convert into an HTTP response object.

The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is my_http_function.

Go

package myhttpfunction

import (
    "fmt"
    "net/http"

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

func init() {
    // Register an HTTP function with the Functions Framework
    functions.HTTP("MyHTTPFunction", myHTTPFunction)
}

// Function myHTTPFunction is an HTTP handler
func myHTTPFunction(w http.ResponseWriter, r *http.Request) {
    // Your code here

    // Send an HTTP response
    fmt.Fprintln(w, "OK")
}

In Go, you register an HTTP handler function with the Functions Framework for Go in your init() function. Your HTTP handler function must use the standard http.HandlerFunc interface to send an HTTP response.

The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is MyHTTPFunction.

Your HTTP handler function must implement the standard http.HandlerFunc interface. It accepts an http.ResponseWriter interface that your function uses to create a reply to the request, and a pointer to an http.Request struct containing the details of the inbound HTTP request.

Java

package myhttpfunction;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;

// Define a class that implements the HttpFunction interface
public class MyHttpFunction implements HttpFunction {
  // Implement the service() method to handle HTTP requests
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    // Your code here

    // Send an HTTP response
    response.getWriter().write("OK");
  }
}

In Java, you use the Functions Framework Java API to implement an HTTP handler class with the HttpFunction interface. The service() method must send an HTTP response.

The function entry point is the fully-qualified name of the HTTP handler class, including the package name. In this example, the entry point is myhttpfunction.MyHttpFunction.

Your service method receives an HttpRequest object describing the inbound HTTP request, and an HttpResponse object that your function populates with a response message.

.NET

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the IHttpFunction interface
    public class MyHttpFunction : IHttpFunction
    {
        // Implement the HandleAsync() method to handle HTTP requests
        public async Task HandleAsync(HttpContext context)
        {
            // Your code here

            // Send an HTTP response
            await context.Response.WriteAsync("OK");
        }
    }
}

In .NET runtimes, you use the Functions Framework for .NET to implement an HTTP handler class with the IHttpFunction interface. The HandleAsync() method accepts a standard ASP.NET HttpContext object as an argument and must send an HTTP response.

The function entry point is the fully-qualified name of the HTTP handler class, including the namespace. In this example, the entry point is MyProject.MyHttpFunction.

Ruby

require "functions_framework"

# Register an HTTP function with the Functions Framework
FunctionsFramework.http "my_http_function" do |request|
  # Your code here

  # Return an HTTP response
  "OK"
end

In Ruby, you register an HTTP handler function with the Functions Framework for Ruby. Your HTTP handler function must accept a Rack request object as an argument and return a value that can be used as an HTTP response.

The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is my_http_function.

PHP

<?php

use Google\CloudFunctions\FunctionsFramework;
use Psr\Http\Message\ServerRequestInterface;

// Register an HTTP function with the Functions Framework
FunctionsFramework::http('myHttpFunction', 'myHttpHandler');

// Define your HTTP handler
function myHttpHandler(ServerRequestInterface $request): string
{
    // Your code here

    // Return an HTTP response
    return 'OK';
}

In PHP, you register an HTTP handler function with the Functions Framework for PHP. Your HTTP handler function must accept an argument that implements the PSR-7 ServerRequestInterface interface, and must return an HTTP response as either a string or an object that implements the PSR-7 ResponseInterface interface.

The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is myHttpFunction.

HTTP request and responses

When you register an HTTP handler function with the Functions Framework, your HTTP handler can inspect the request method and perform different actions based on the method.

When you configure an event provider to send HTTP requests to your Cloud Run function, your function sends an HTTP response. If the function creates background tasks (such as with threads, futures, JavaScript Promise objects, callbacks, or system processes), you must terminate or otherwise resolve these tasks before sending an HTTP response. Any tasks not terminated before the HTTP response is sent might not be completed, and might cause undefined behavior.

Handle CORS

Cross-Origin Resource Sharing (CORS) is a way to let applications running on one domain access resources from another domain. For example, you might need to let your domain make requests to the Cloud Run functions domain to access your function.

To allow cross-origin requests to your function, set the Access-Control-Allow-Origin header as appropriate on your HTTP response. For preflighted cross-origin requests, you must respond to the preflight OPTIONS request with a 204 response code and additional headers.

Node.js

const functions = require('@google-cloud/functions-framework');

/**
 * HTTP function that supports CORS requests.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('corsEnabledFunction', (req, res) => {
  // Set CORS headers for preflight requests
  // Allows GETs from any origin with the Content-Type header
  // and caches preflight response for 3600s

  res.set('Access-Control-Allow-Origin', '*');

  if (req.method === 'OPTIONS') {
    // Send response to OPTIONS requests
    res.set('Access-Control-Allow-Methods', 'GET');
    res.set('Access-Control-Allow-Headers', 'Content-Type');
    res.set('Access-Control-Max-Age', '3600');
    res.status(204).send('');
  } else {
    res.send('Hello World!');
  }
});

Python

import functions_framework

@functions_framework.http
def cors_enabled_function(request):
    # For more information about CORS and CORS preflight requests, see:
    # https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request

    # Set CORS headers for the preflight request
    if request.method == "OPTIONS":
        # Allows GET requests from any origin with the Content-Type
        # header and caches preflight response for an 3600s
        headers = {
            "Access-Control-Allow-Origin": "*",
            "Access-Control-Allow-Methods": "GET",
            "Access-Control-Allow-Headers": "Content-Type",
            "Access-Control-Max-Age": "3600",
        }

        return ("", 204, headers)

    # Set CORS headers for the main request
    headers = {"Access-Control-Allow-Origin": "*"}

    return ("Hello World!", 200, headers)

Go


// Package http provides a set of HTTP Cloud Functions samples.
package http

import (
	"fmt"
	"net/http"

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

// CORSEnabledFunction is an example of setting CORS headers.
// For more information about CORS and CORS preflight requests, see
// https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
func CORSEnabledFunction(w http.ResponseWriter, r *http.Request) {
	// Set CORS headers for the preflight request
	if r.Method == http.MethodOptions {
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Methods", "POST")
		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
		w.Header().Set("Access-Control-Max-Age", "3600")
		w.WriteHeader(http.StatusNoContent)
		return
	}
	// Set CORS headers for the main request.
	w.