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"))

  // 3. assembles RESTful api service from gateway and lambda functions
  gateway.AddResource("hello", 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 RESTful API with Domain Name

Supply custom domain name and ARN of Certificate

scud.NewGateway(stack, jsii.String("Gateway")).
  ConfigRoute53("test.example.com", "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

scud.NewGateway(stack, jsii.String("Gateway")).
  ConfigAuthorizer("arn:aws:cognito-idp:...").
	AddResource("hello", myfun, "my/scope")

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

Documentation

Index

• func AssetCodeGo(sourceCodePackage, sourceCodeLambda string) awslambda.Code
• func NewFunctionGo(scope constructs.Construct, id *string, spec *FunctionGoProps) awslambda.Function
• type FunctionGoProps
• type Gateway
  • func NewGateway(scope constructs.Construct, id *string, props *awsapigateway.RestApiProps) Gateway

Functions

func AssetCodeGo

func AssetCodeGo(sourceCodePackage, sourceCodeLambda string) 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 FunctionGoProps

type FunctionGoProps struct {
	*awslambda.FunctionProps
	SourceCodePackage string
	SourceCodeLambda  string
}

FunctionGoProps is properties of the function

type Gateway

type Gateway interface {
	ConfigRoute53(host string, tlsArn string) Gateway
	ConfigAuthorizer(cognitoUserPools ...string) Gateway
	AddResource(resourceRootPath string, resourceHandler awslambda.Function, requiredAccessScope ...string) Gateway
}

Gateway is RESTful API Gateway Construct pattern

func NewGateway

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

NewGateway creates new instance of Gateway