fdk

README

Foundry Function as a Service Go SDK

foundry-fn-go is a community-driven, open source project designed to enable the authoring of functions. While not a formal CrowdStrike product, foundry-fn-go is maintained by CrowdStrike and supported in partnership with the open source developer community.

Installation ⚙️

Via go get

The SDK can be installed or updated via go get:

go get github.com/CrowdStrike/foundry-fn-go

From source

The SDK can be built from source via standard build:

go mod tidy
go build .

Quickstart 💫

Code

Add the SDK to your project by following the installation instructions above, then create your main.go:

package main

import (
	"context"
	"encoding/json"
	"errors"
	"net/http"

	fdk "github.com/CrowdStrike/foundry-fn-go"
)

func main() {
	fdk.Run(context.Background(), newHandler)
}

// newHandler here is showing how a config is integrated. It is using generics,
// so we can unmarshal the config into a concrete type and then validate it. The
// OK method is run to validate the contents of the config.
func newHandler(_ context.Context, cfg config) fdk.Handler {
	mux := fdk.NewMux()
	mux.Post("/echo", fdk.HandlerFn(func(ctx context.Context, r fdk.Request) fdk.Response {
		return fdk.Response{
			Body:   r.Body,
			Code:   201,
			Header: http.Header{"X-Cs-Method": []string{r.Method}},
		}
	}))
	return mux
}

type config struct {
	Int int    `json:"integer"`
	Str string `json:"string"`
}

func (c config) OK() error {
	var errs []error
	if c.Int < 1 {
		errs = append(errs, errors.New("integer must be greater than 0"))
	}
	if c.Str == "" {
		errs = append(errs, errors.New("non empty string must be provided"))
	}
	return errors.Join(errs...)
}

1. config: A type the raw json config is unmarshalled into.
2. Request: Request payload and metadata. At the time of this writing, the Request struct consists of:
   1. Body: The raw request payload as given in the Function Gateway body payload field.
   2. Params: Contains request headers and query parameters.
   3. URL: The request path relative to the function as a string.
   4. Method: The request HTTP method or verb.
   5. Context: Caller-supplied raw context.
   6. AccessToken: Caller-supplied access token.
3. Response
   1. The Response contains fields Body (the payload of the response), Code (an HTTP status code), Errors (a slice of APIErrors), and Headers (a map of any special HTTP headers which should be present on the response).
4. main(): Initialization and bootstrap logic all contained with fdk.Run and handler constructor.

more examples can be found at:

• fn with config
• fn without config
• more complex/complete example

Testing locally

The SDK provides an out-of-the-box runtime for executing the function. A basic HTTP server will be listening on port 8081.

# build the project which uses the sdk
cd my-project && go mod tidy && go build -o run_me .

# run the executable. config should be in json format here.
CS_FN_CONFIG_PATH=$PATH_TO_CONFIG_JSON ./run_me

Requests can now be made against the executable.

curl -X POST http://localhost:8081/ \
  -H "Content-Type: application/json" \
  --data '{
    "body": {
        "foo": "bar"
    },
    "method": "POST",
    "url": "/greetings"
}'

Convenience Functionality 🧰

gofalcon

Foundry Function integrates with gofalcon in a few simple lines.

package main

import (
	"context"

    fdk "github.com/CrowdStrike/foundry-fn-go"
	"github.com/CrowdStrike/gofalcon/falcon"
	"github.com/CrowdStrike/gofalcon/falcon/client"
)

func newHandler(_ context.Context, cfg config) fdk.Handler {
	mux := fdk.NewMux()
	mux.Post("/echo", fdk.HandlerFn(func(ctx context.Context, r fdk.Request) fdk.Response {
		client, err := newFalconClient(ctx, r.AccessToken)
		if err != nil {
			if err == falcon.ErrFalconNoToken {
				// not a processable request
				return fdk.Response{ /* snip */ }
			}
			// some other error - see gofalcon documentation
		}

		// trim rest
	}))
	return mux
}

func newFalconClient(ctx context.Context, token string) (*client.CrowdStrikeAPISpecification, error) {
	opts := fdk.FalconClientOpts()
	return falcon.NewClient(&falcon.ApiConfig{
		AccessToken:       token,
		Cloud:             falcon.Cloud(opts.Cloud),
		Context:           ctx,
		UserAgentOverride: out.UserAgent,
	})
}

// omitting rest of implementation

Integration with Falcon Fusion workflows

When integrating with a Falcon Fusion workflow, the Request.Context can be decoded into WorkflowCtx type. You may json unmarshal into that type. The type provides some additional context from the workflow. This context is from the execution of the workflow, and may be dynamic in some usecases. To simplify things further for authors, we have introduced two handler functions to remove the boilerplate of dealing with a workflow.

package somefn

import (
	"context"

	fdk "github.com/CrowdStrike/foundry-fn-go"
)

type reqBody struct {
	Foo string `json:"foo"`
}

func New(ctx context.Context, _ fdk.SkipCfg) fdk.Handler {
	m := fdk.NewMux()

	// for get/delete reqs use HandleWorkflow. The path is just an examples, any payh can be used.
	m.Get("/workflow", fdk.HandleWorkflow(func(ctx context.Context, r fdk.Request, workflowCtx fdk.WorkflowCtx) fdk.Response {
		// ... trim impl
	}))

	// for handlers that expect a request body (i.e. PATCH/POST/PUT)
	m.Post("/workflow", fdk.HandleWorkflowOf(func(ctx context.Context, r fdk.RequestOf[reqBody], workflowCtx fdk.WorkflowCtx) fdk.Response {
		// .. trim imple
	}))

	return m
}

Working with Request and Response Schemas

Within the fdktest pkg, we maintain test funcs for validating a schema and its integration with a handler. Example:

package somefn_test

import (
	"context"
	"net/http"
	"testing"

	fdk "github.com/CrowdStrike/foundry-fn-go"
	"github.com/CrowdStrike/foundry-fn-go/fdktest"
)

func TestHandlerIntegration(t *testing.T) {
	reqSchema := `{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "postalCode": {
      "type": "string",
      "description": "The person's first name.",
      "pattern": "\\d{5}"
    },
    "optional": {
      "type": "string",
      "description": "The person's last name."
    }
  },
  "required": [
    "postalCode"
  ]
}`

	respSchema := `{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string",
      "description": "The person's first name.",
      "enum": ["bar"]
    }
  },
  "required": [
    "foo"
  ]
}`
	handler := fdk.HandlerFn(func(ctx context.Context, r fdk.Request) fdk.Response {
		return fdk.Response{Body: fdk.JSON(map[string]string{"foo": "bar"})}
	})

	req := fdk.Request{
		URL:    "/",
		Method: http.MethodPost,
		Body:   json.RawMessage(`{"postalCode": "55755"}`),
	}

	err := fdktest.HandlerSchemaOK(handler, req, reqSchema, respSchema)
	if err != nil {
		t.Fatal("unexpected err: ", err)
	}
}

A note on os.Exit

Please refrain from using os.Exit. When an error is encountered, we want to return a message to the caller. Otherwise, it'll os.Exit and all stakeholders will have no idea what to make of it. Instead, use something like the following in fdk.Run:

// sdk.go

package fdk

import (
	"context"
)

// Run is the meat and potatoes. This is the entrypoint for everything.
func Run[T Cfg](ctx context.Context, newHandlerFn func(_ context.Context, cfg T) Handler) {
	// ... trim

	cfg, loadErr := readCfg[T](ctx)
	if loadErr != nil {
		if loadErr.err != nil {
			// these being specific to the author's eyes only
			logger.Error("failed to load config", "err", loadErr.err)
		}
		// here we return a useful error to the caller of the function
		run(ctx, logger, ErrHandler(loadErr.apiErr))
		return
	}

	h := newHandlerFn(ctx, cfg)

	run(ctx, logger, h)

	return
}

---

WE STOP BREACHES

Documentation

Index

• Variables
• func FalconClientOpts() (out struct{ ... })
• func JSON(v any) json.Marshaler
• func RegisterConfigLoader(loaderType string, cr ConfigLoader)
• func RegisterRunner(runnerType string, r Runner)
• func Run[T Cfg](ctx context.Context, newHandlerFn func(_ context.Context, cfg T) Handler)
• type APIError
  • func (a APIError) Error() string
• type Cfg
• type ConfigLoader
• type File
  • func CompressGzip(file File) File
  • func NormalizeFile(f File) File
  • func (f File) MarshalJSON() ([]byte, error)
• type Handler
  • func ErrHandler(errs ...APIError) Handler
  • func HandleFnOf[T any](fn func(context.Context, RequestOf[T]) Response) Handler
  • func HandleWorkflow(fn func(context.Context, Request, WorkflowCtx) Response) Handler
  • func HandleWorkflowOf[T any](fn func(context.Context, RequestOf[T], WorkflowCtx) Response) Handler
• type HandlerFn
  • func (h HandlerFn) Handle(ctx context.Context, r Request) Response
• type Mux
  • func NewMux() *Mux
  • func (m *Mux) Delete(route string, h Handler)
  • func (m *Mux) Get(route string, h Handler)
  • func (m *Mux) Handle(ctx context.Context, r Request) Response
  • func (m *Mux) Post(route string, h Handler)
  • func (m *Mux) Put(route string, h Handler)
• type Request
• type RequestOf
• type Response
  • func ErrResp(errs ...APIError) Response
  • func (r Response) StatusCode() int
• type Runner
• type SkipCfg
  • func (n SkipCfg) OK() error
• type WorkflowCtx

Variables

var (
	// ErrCfgNotFound defines the inability to find a config at the expected location.
	ErrCfgNotFound = errors.New("no config provided")
)

Functions

func FalconClientOpts

func FalconClientOpts() (out struct {
	Cloud     string
	UserAgent string
})

FalconClientOpts provides the cloud for use with the falcon client. To setup the falcon Client you can follow the following example.

func newFalconClient(ctx context.Context, token string) (*client.CrowdStrikeAPISpecification, error) {
	opts := fdk.FalconClientOpts()
	return falcon.NewClient(&falcon.ApiConfig{
		AccessToken:       token,
		Cloud:             falcon.Cloud(opts.Cloud),
		Context:           ctx,
		UserAgentOverride: out.UserAgent,
	})
}

func JSON

func JSON(v any) json.Marshaler

JSON jsonifies the input to valid json upon request marshaling.

func RegisterConfigLoader

func RegisterConfigLoader(loaderType string, cr ConfigLoader)

RegisterConfigLoader will register a config loader at the specified type. Similar to registering a database with the database/sql, you're able to provide a config for use at runtime. During Run, the config loader defined by the env var, CS_CONFIG_LOADER_TYPE, is used. If one is not provided, then the fs config loader will be used.

func RegisterRunner

func RegisterRunner(runnerType string, r Runner)

RegisterRunner registers a runner.

func Run

func Run[T Cfg](ctx context.Context, newHandlerFn func(_ context.Context, cfg T) Handler)

Run is the meat and potatoes. This is the entrypoint for everything.

Types

type APIError

type APIError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

APIError defines a error that is shared back to the caller.

func (APIError) Error

func (a APIError) Error() string

Error provides a human readable error message.

type Cfg

type Cfg interface {
	OK() error
}

Cfg marks the configuration type parameter. Any config type must have a validation method, OK, defined on it.

type ConfigLoader

type ConfigLoader interface {
	LoadConfig(ctx context.Context) ([]byte, error)
}

ConfigLoader defines the behavior for loading config.

type File

type File struct {
	ContentType string        `json:"content_type"`
	Encoding    string        `json:"encoding"`
	Filename    string        `json:"filename"`
	Contents    io.ReadCloser `json:"-"`
}

File represents a response that is a response body. The runner is in charge of getting the contents to the destination. The metadata will be received. One note, we call NormalizeFile on the File's in the Runner's that execute the handler. Testing through the Run function will illustrate this.

func CompressGzip

func CompressGzip(file File) File

CompressGzip compresses a files contents with gzip compression.

func NormalizeFile

func NormalizeFile(f File) File

NormalizeFile normalizes a file so that all fields are set with sane defaults.

func (File) MarshalJSON

func (f File) MarshalJSON() ([]byte, error)

MarshalJSON marshals the file metadata.

type Handler

type Handler interface {
	Handle(ctx context.Context, r Request) Response
}

Handler provides a handler for our incoming request.

func ErrHandler

func ErrHandler(errs ...APIError) Handler

ErrHandler creates a new handler to respond with only errors.

func HandleFnOf

func HandleFnOf[T any](fn func(context.Context, RequestOf[T]) Response) Handler

HandleFnOf provides a means to translate the incoming requests to the destination body type. This normalizes the sad path and provides the caller with a zero fuss request to work with. Reducing json boilerplate for what is essentially the same operation on different types.

func HandleWorkflow

func HandleWorkflow(fn func(context.Context, Request, WorkflowCtx) Response) Handler

HandleWorkflow provides a means to create a handler with workflow integration. This function does not have an opinion on the request body but does expect a workflow integration. Typically, this is useful for DELETE/GET handlers.

func HandleWorkflowOf

func HandleWorkflowOf[T any](fn func(context.Context, RequestOf[T], WorkflowCtx) Response) Handler

HandleWorkflowOf provides a means to create a handler with Workflow integration. This function is useful when you expect a request body and have workflow integrations. Typically, this is with PATCH/POST/PUT handlers.

type HandlerFn

type HandlerFn func(ctx context.Context, r Request) Response

HandlerFn wraps a function to return a handler. Similar to the http.HandlerFunc.

func (HandlerFn) Handle

func (h HandlerFn) Handle(ctx context.Context, r Request) Response

Handle is the request/response lifecycle handler.

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

Mux defines a handler that will dispatch to a matching route/method combination. Much like the std lib http.ServeMux, but with slightly more opinionated route setting. We only support the DELETE, GET, POST, and PUT.

func NewMux

func NewMux() *Mux

NewMux creates a new Mux that is ready for assignment.

func (*Mux) Delete

func (m *Mux) Delete(route string, h Handler)

Delete creates a DELETE route.

func (*Mux) Get

func (m *Mux) Get(route string, h Handler)

Get creates a GET route.

func (*Mux) Handle

func (m *Mux) Handle(ctx context.Context, r Request) Response

Handle enacts the handler to process the request/response lifecycle. The mux fulfills the Handler interface and can dispatch to any number of sub routes.

func (*Mux) Post

func (m *Mux) Post(route string, h Handler)

Post creates a POST route.

func (*Mux) Put

func (m *Mux) Put(route string, h Handler)

Put creates a PUT route.

type Request

type Request RequestOf[json.RawMessage]

Request defines a request structure that is given to the runner. The Body is set to json.RawMessage, to enable decoration/middleware.

type RequestOf

type RequestOf[T any] struct {
	FnID      string
	FnVersion int
	Body      T
	Context   json.RawMessage
	Params    struct {
		Header http.Header
		Query  url.Values
	}
	URL         string
	Method      string
	AccessToken string
	TraceID     string
}

RequestOf provides a generic body we can target our unmarshaling into.

type Response

type Response struct {
	Body   json.Marshaler
	Code   int
	Errors []APIError
	Header http.Header
}

Response is the domain type for the response.

func ErrResp

func ErrResp(errs ...APIError) Response

ErrResp creates a sad path errors only response.

Note: the highest status code from the errors will be used for the response status if no status code is set on the response.

func (Response) StatusCode

func (r Response) StatusCode() int

StatusCode returns the response status code. When a Response.Code is not set and errors exist, then the highest code on the errors is returned.

type Runner

type Runner interface {
	Run(ctx context.Context, logger *slog.Logger, h Handler)
}

Runner defines the runtime that executes the request/response handler lifecycle.

type SkipCfg

type SkipCfg struct{}

SkipCfg indicates the config is not needed and will skip the config loading procedure.

func (SkipCfg) OK

func (n SkipCfg) OK() error

OK is a noop validation.

type WorkflowCtx

type WorkflowCtx struct {
	ActivityExecID    string `json:"activity_execution_id"`
	AppID             string `json:"app_id"`
	CID               string `json:"cid"`
	OwnerCID          string `json:"owner_cid"`
	DefinitionID      string `json:"definition_id,omitempty"`
	DefinitionVersion int    `json:"definition_version,omitempty"`
	ExecutionID       string `json:"execution_id,omitempty"`
	Activity          struct {
		ID     string `json:"id"`
		Name   string `json:"name"`
		NodeID string `json:"node_id"`
	} `json:"activity"`
	Trigger struct {
		ID   string `json:"id,omitempty"`
		Name string `json:"name,omitempty"`
	} `json:"trigger"`
}

WorkflowCtx is the Request.Context field when integrating a function with Falcon Fusion workflow.