scud

README

scud

scud is a Simple Cloud Usable Daemon for serverless RESTful API development. This library is AWS CDK pattern that takes care about infrastructure boilerplate so that you focuses on development of application logic.

Inspiration

AWS API Gateway and AWS Lambda is a perfect approach for quick prototyping or production development of microservice on Amazon Web Services. Unfortunately, it requires a boilerplate AWS CDK code to bootstrap the development. This library implements a high-order components on top of AWS CDK that hardens the api pattern

The library helps with building of lambda functions by

• integrating "compilation" fo Golang serverless functions within cdk workflows.
• integrates validation of OAuth2 Bearer token for each API endpoint

Getting started

The latest version of the library is available at its main branch. All development, including new features and bug fixes, take place on the main branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.

1. Use go get to retrieve the library and add it as dependency to your application.

go get -u github.com/fogfish/scud

1. Import it in your code

import "github.com/fogfish/scud"

Example RESTful API

import (
  "github.com/aws/aws-cdk-go/awscdk/v2"
  "github.com/aws/constructs-go/constructs/v10"
  "github.com/aws/jsii-runtime-go"
  "github.com/fogfish/scud"
)

func NewService(scope constructs.Construct) {
  // 1. declare lambda function
  myfun := scud.NewFunctionGo(scope, jsii.String("test"),
    &scud.FunctionGoProps{
      SourceCodePackage: "github.com/mygithub/myservice",
      SourceCodeLambda:  "aws/lambda/example",
      /* FunctionProps: optionally other awslambda.FunctionProps */
    },
  )

  // 2. declare api gateway
  gateway := scud.NewGateway(stack, jsii.String("Gateway"),
    &scud.GatewayProps{}
  )

  // 3. assembles RESTful api service from gateway and lambda functions
  gateway.AddResource("/hello", myfun)
  gateway.AddResource("/world/europe", myfun)
  gateway.AddResource("/world/asia", myfun)
}

// 4. injects the service to stack
stack := awscdk.NewStack(/* ... */)
NewService(stack)

Please see the RESTful API templates, clone them to draft a new microservice in matter of minutes:

• blueprint-serverless-golang

Example ARM64 functions

myfun := scud.NewFunctionGo(scope, jsii.String("test"),
    &scud.FunctionGoProps{
      SourceCodePackage: "github.com/mygithub/myservice",
      SourceCodeLambda:  "aws/lambda/example",
      GoEnv: map[string]string{"GOARCH": "arm64"},
    },
  )

Example RESTful API with Domain Name

Supply custom domain name and ARN of Certificate

scud.NewGateway(stack, jsii.String("Gateway"),
  &scud.GatewayProps{
    Host: jsii.String("test.example.com"),
    TlsArn: jsii.String("arn:aws:acm:eu-west-1:000000000000:certificate/00000000-0000-0000-0000-000000000000"),
  },
)

Example protect RESTful API with OAuth2

The construct supports integration with AWS Cognito, the integration of AWS API Gateway and AWS Cognito is well depicted by official documentation. The pattern enables deployment of this configuration, just supply ARN of user pool and supply scopes to protect endpoints

gw := scud.NewGateway(stack, jsii.String("Gateway"),
  &scud.GatewayProps{},
)

// Using AWS Cognito
gw.WithAuthorizerCognito("arn:aws:cognito-idp:...").
gw.AddResource("/hello", myfun, "my/scope")

// Using AWS IAM
gw.WithAuthorizerIAM().
gw.AddResource("/hello", myfun)

You can still access API with curl even if IAM authorizer is used

curl https://example.com/petshop/pets \
  -XGET \
  -H "Accept: application/json" \
  --aws-sigv4 "aws:amz:eu-west-1:execute-api" \
  --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY"

HowTo Contribute

The project is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it and clone
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

git clone https://github.com/fogfish/scud
cd scud

go build
go test

License

References

1. Migrating AWS Lambda functions from the Go1.x runtime to the custom runtime on Amazon Linux 2

Documentation

Index

• func AssetCodeGo(compiler Compiler) awslambda.Code
• func NewFunctionGo(scope constructs.Construct, id *string, spec *FunctionGoProps) awslambda.Function
• type Compiler
• type FunctionGoProps
• type Gateway
  • func NewGateway(scope constructs.Construct, id *string, props *GatewayProps) Gateway
• type GatewayProps
• type GoCompiler
  • func NewGoCompiler(sourceCodePackage string, sourceCodeLambda string, env map[string]string) *GoCompiler
  • func (g *GoCompiler) SourceCodeLambda() string
  • func (g *GoCompiler) SourceCodePackage() string
  • func (g *GoCompiler) TryBundle(outputDir *string, options *awscdk.BundlingOptions) *bool

Functions

func AssetCodeGo

func AssetCodeGo(compiler Compiler) awslambda.Code

AssetCodeGo bundles lambda function from source code

func NewFunctionGo

func NewFunctionGo(scope constructs.Construct, id *string, spec *FunctionGoProps) awslambda.Function

NewFunctionGo creates Golang Lambda Function from "inline" code

Types

type Compiler

type Compiler interface {
	awscdk.ILocalBundling
	SourceCodePackage() string
	SourceCodeLambda() string
}

type FunctionGoProps

type FunctionGoProps struct {
	*awslambda.FunctionProps
	SourceCodePackage string
	SourceCodeLambda  string
	GoEnv             map[string]string
}

FunctionGoProps is properties of the function

type Gateway

type Gateway interface {
	constructs.Construct
	RestApi() apigw2.HttpApi
	WithAuthorizerIAM()
	WithAuthorizerCognito(cognitoArn string)
	AddResource(resourceRootPath string, resourceHandler awslambda.Function, requiredAccessScope ...string)
}

Gateway is RESTful API Gateway Construct pattern

func NewGateway

func NewGateway(scope constructs.Construct, id *string, props *GatewayProps) Gateway

NewGateway creates new instance of Gateway

type GatewayProps

type GatewayProps struct {
	*apigw2.HttpApiProps
	Host   *string
	TlsArn *string
}

type GoCompiler

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

func NewGoCompiler

func NewGoCompiler(
	sourceCodePackage string,
	sourceCodeLambda string,
	env map[string]string,
) *GoCompiler

func (*GoCompiler) SourceCodeLambda

func (g *GoCompiler) SourceCodeLambda() string

func (*GoCompiler) SourceCodePackage

func (g *GoCompiler) SourceCodePackage() string

func (*GoCompiler) TryBundle

func (g *GoCompiler) TryBundle(outputDir *string, options *awscdk.BundlingOptions) *bool