Define Go runtime handlers for events and HTTP triggers - Function Compute

Define a handler function in Go, compile it into an executable binary, and set the Handler parameter in the Function Compute console to the name of that binary. Function Compute runs this handler each time your function is invoked.

Note

If you want to use HTTP triggers or custom domain names to access functions, obtain request struct before you define HTTP responses. For more information, see Use an HTTP trigger to invoke a function.

Quick start

Import the SDK package github.com/aliyun/fc-runtime-go-sdk/fc, implement a handler function, and pass it to fc.Start in main().

package main

import (
    "fmt"
    "context"

    "github.com/aliyun/fc-runtime-go-sdk/fc"
)

type StructEvent struct {
    Key string `json:"key"`
}

func HandleRequest(ctx context.Context, event StructEvent) (string, error) {
    return fmt.Sprintf("hello, %s!", event.Key), nil
}

func main() {
    fc.Start(HandleRequest)
}

This handler accepts a JSON event with a key field and returns a greeting string:

{
  "key": "value"
}

Code walkthrough

Element	Purpose
`package main`	Required entry package for any Go executable
`github.com/aliyun/fc-runtime-go-sdk/fc`	Function Compute Go SDK
`context`	Provides runtime context for the function invocation
`HandleRequest(ctx context.Context, event StructEvent) (string, error)`	Handler function: receives a context and a typed event, returns a string and an error
`fc.Start(HandleRequest)`	Registers the handler with Function Compute and starts the runtime loop

For more information about the context object, see Context. For error handling, see Error handling.

Build and deploy

Initialize a Go module and install the Function Compute SDK:

go mod init my-fc-function
go get github.com/aliyun/fc-runtime-go-sdk

Compile your handler into a Linux binary (Function Compute runs on Linux):

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o main main.go

Set the Handler parameter in the Function Compute console to main (the name of the compiled binary). For instructions on creating a function, see Create an event function.

Handler signatures

A handler must follow these rules:

It must be a function.
It accepts 0 to 2 input parameters. If two parameters are used, the first must be context.Context.
It returns 0 to 2 values. A single return value must be of type error. Two return values must have error as the second.

All valid signatures:

func ()
func () error
func (InputType) error
func () (OutputType, error)
func (InputType) (OutputType, error)
func (context.Context) error
func (context.Context, InputType) error
func (context.Context) (OutputType, error)
func (context.Context, InputType) (OutputType, error)

InputType and OutputType must be compatible with the encoding/json standard library. Function Compute deserializes the input with json.Unmarshal and serializes the output with json.Marshal. For details, see JSON Unmarshal.

Input event types

The event parameter supports multiple Go types. Choose the type that fits your use case:

Event type	Use case	Example
Struct	Strongly typed events with known fields	event-struct.go
`string`	Raw string input	event-string.go
`map[string]interface{}`	Dynamic or loosely typed events	event-map.go

For more examples, see fc-runtime-go-sdk/examples.

HTTP trigger handlers

To handle HTTP requests through an HTTP trigger or a custom domain name, use the HTTPTriggerEvent and HTTPTriggerResponse structs from the SDK events package.

Handle HTTP trigger events

package main

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/aliyun/fc-runtime-go-sdk/events"
	"github.com/aliyun/fc-runtime-go-sdk/fc"
)

type HTTPTriggerEvent events.HTTPTriggerEvent
type HTTPTriggerResponse events.HTTPTriggerResponse

func (h HTTPTriggerEvent) String() string {
	jsonBytes, err := json.MarshalIndent(h, "", "  ")
	if err != nil {
		return ""
	}
	return string(jsonBytes)
}

func NewHTTPTriggerResponse(statusCode int) *HTTPTriggerResponse {
	return &HTTPTriggerResponse{StatusCode: statusCode}
}

func (h *HTTPTriggerResponse) String() string {
	jsonBytes, err := json.MarshalIndent(h, "", "  ")
	if err != nil {
		return ""
	}
	return string(jsonBytes)
}

func (h *HTTPTriggerResponse) WithStatusCode(statusCode int) *HTTPTriggerResponse {
	h.StatusCode = statusCode
	return h
}

func (h *HTTPTriggerResponse) WithHeaders(headers map[string]string) *HTTPTriggerResponse {
	h.Headers = headers
	return h
}

func (h *HTTPTriggerResponse) WithIsBase64Encoded(isBase64Encoded bool) *HTTPTriggerResponse {
	h.IsBase64Encoded = isBase64Encoded
	return h
}

func (h *HTTPTriggerResponse) WithBody(body string) *HTTPTriggerResponse {
	h.Body = body
	return h
}

func HandleRequest(event HTTPTriggerEvent) (*HTTPTriggerResponse, error) {
	fmt.Printf("event: %v\n", event)
	if event.Body == nil {
		return NewHTTPTriggerResponse(http.StatusBadRequest).
			WithBody(fmt.Sprintf("the request did not come from an HTTP Trigger, event: %v", event)), nil
	}

	reqBody := *event.Body
	if event.IsBase64Encoded != nil && *event.IsBase64Encoded {
		decodedByte, err := base64.StdEncoding.DecodeString(*event.Body)
		if err != nil {
			return NewHTTPTriggerResponse(http.StatusBadRequest).
				WithBody(fmt.Sprintf("HTTP Trigger body is not base64 encoded, err: %v", err)), nil
		}
		reqBody = string(decodedByte)
	}
	return NewHTTPTriggerResponse(http.StatusOK).WithBody(reqBody), nil
}

func main() {
	fc.Start(HandleRequest)
}

This handler reads the HTTP request body from HTTPTriggerEvent, decodes it if Base64-encoded, and returns it in the response. The request and response structs come from github.com/aliyun/fc-runtime-go-sdk/events. For payload format details, see Use an HTTP trigger to invoke a function.

Invoke the function

Prerequisites

Before you begin, make sure that you have:

A function created in a Go runtime with the preceding handler code
An HTTP trigger configured for the function

For setup instructions, see Create an event function and Configure an HTTP trigger.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Functions.
In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.
Click the Triggers tab. Copy the public endpoint of the HTTP trigger.

Send a request to the endpoint:

   curl -i "https://http-trigger-demo.cn-shanghai.fcapp.run" -d "Hello FC!"

Important

If the Authentication Method of the HTTP trigger is set to No Authentication, invoke the function directly with curl or Postman.
If set to Signature Authentication or JWT Authentication, include the required credentials. For details, see Authentication.

Troubleshoot Test Function errors

This handler expects input from an HTTP trigger or a custom domain name. Invoking it through the Test Function button in the console sends a standard event payload, not an HTTP trigger payload. This results in a 400 error:

{
    "statusCode": 400,
    "body": "the request did not come from an HTTP Trigger, event: {\n  \"version\": null,\n  \"rawPath\": null,\n  \"headers\": null,\n  \"queryParameters\": null,\n  \"body\": null,\n  \"isBase64Encoded\": null,\n  \"requestContext\": null\n}"
}

To inspect the raw event payload regardless of the source, use a []byte handler:

// GetRawRequestEvent returns the raw event as the response body
func GetRawRequestEvent(event []byte) (*HTTPTriggerResponse, error) {
	fmt.Printf("raw event: %s\n", string(event))
	return NewHTTPTriggerResponse(http.StatusOK).WithBody(string(event)), nil
}

func main() {
	fc.Start(GetRawRequestEvent)
}

Function Compute:Go runtime handlers