mantil

README

mantil.go

mantil.go integrates Lambda function with API's in a Mantil project.

It is similar to the default AWS Go Lambda function handler. The main difference is that mantil.go handler mantil.LmabdaHandler accepts struct instance and exposes each exported method of that struct. Where the default implementation has a single function as an entrypoint.

Package is intended for usage inside Mantil project.

Package also provides simple key value store interface backed by a DynamoDB table. It manages that table as part of the Mantil project. It is created on demand and destroyed with the project.

Documentation

Overview

Package mantil integrates Lambda function with API's in a Mantil project.

It is similar to the default AWS Go [Lambda function handler](https://docs.aws.amazon.com/lambda/latest/dg/golang-handler.html). The main difference is that mantil.go handler mantil.LmabdaHandler accepts struct instance and exposes each exported method of that struct. Where the default implementation has a single function as an entrypoint.

Package is intended for usage inside Mantil project.

Package also provides simple key value store interface backed by a DynamoDB table. It manages that table as part of the Mantil project. It is created on demand and destroyed with the project.

Index

• Constants
• func DynamodbTable(name, primaryKey, sortKey string) (*dynamodb.Client, error)
• func LambdaHandler(api interface{})
• func Publish(subject string, payload interface{}) error
• func S3Bucket(name string) (*s3svc.Client, error)
• func SetLogger(l *log.Logger)
• type ErrItemNotFound
  • func (e ErrItemNotFound) Error() string
• type FindIterator
  • func (i FindIterator) Count() int
  • func (i *FindIterator) HasMore() bool
  • func (i *FindIterator) Next(items interface{}) error
• type FindOperator
• type KV
  • func NewKV(partition string) (*KV, error)
  • func (k *KV) Delete(key ...string) error
  • func (k *KV) DeleteAll() error
  • func (k *KV) Find(items interface{}, op FindOperator, args ...string) (*FindIterator, error)
  • func (k *KV) FindAll(items interface{}) (*FindIterator, error)
  • func (k *KV) Get(key string, value interface{}) error
  • func (k *KV) Put(key string, value interface{}) error
• type LambdaInvoker
  • func NewLambdaInvoker(function, role string) (*LambdaInvoker, error)
  • func (l *LambdaInvoker) Call(payload []byte) ([]byte, error)
  • func (l *LambdaInvoker) CallAsync(payload []byte) error
  • func (l *LambdaInvoker) Cast(payload []byte) error
  • func (l *LambdaInvoker) Timeout() time.Duration
• type Request
  • func (r *Request) RemoteIP() string
• type RequestContext
  • func FromContext(ctx context.Context) (*RequestContext, bool)
  • func (r *RequestContext) Authorizer() map[string]interface{}
  • func (r *RequestContext) WSConnectionID() string
• type RequestType
• type ResourceInfo
  • func Resource(name string) ResourceInfo

Constants

const (
	// ApiErrorHeader is the response header key for lambda errors
	ApiErrorHeader = "x-api-error"
	// ApiErrorCodeHeader is the response header key for lambda error codes
	ApiErrorCodeHeader = "x-api-error-code"
)

const (
	EnvConfig      = "MANTIL_GO_CONFIG"
	EnvKVTableName = "MANTIL_KV_TABLE"
)

Configuration environment variables:

const (
	PK = "PK"
	SK = "SK"
)

KV primary and sort key names in DynamoDB table:

const (
	RequestTypeUnknown = iota
	APIGateway
	WSConnect
	WSMessage
	WSDisconnect
	Streaming
)

RequestType enum possible values:

Functions

func DynamodbTable

func DynamodbTable(name, primaryKey, sortKey string) (*dynamodb.Client, error)

DynamodbTable creates a new dynamodb table (if it doesn't already exist) for use within a Mantil project. The final name of the table follows the same naming convention as other Mantil resources and can be found by calling the Resource function.

The table will be deleted when the project stage is destroyed.

To perform operations on this table, use the returned dynamodb client. Please refer to the AWS SDK documentation for more information on how to use the client: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client

func LambdaHandler

func LambdaHandler(api interface{})

LambdaHandler is entrypoint for Mantil Lambda functions. Use it in your Lambda functions:

mantil.LambdaHandler(api)

where api is Go struct. All exported methods of the api struct will be exposed as API Gateway HTTP methods. Exported methods must follow this rules:

• may take between 0 and two arguments.
• if there are two arguments, the first argument must satisfy the "context.Context" interface.
• may return between 0 and two arguments.
• if there are two return values, the second argument must be an error.
• if there is one return value it must be an error.

valid signatures are:

func ()
func () error
func (TIn) error
func () (TOut, error)
func (context.Context) error
func (context.Context, TIn) error
func (context.Context) (TOut, error)
func (context.Context, TIn) (TOut, error)

For example of Lambda function see this example: https://github.com/mantil-io/template-excuses/blob/master/functions/excuses/main.go

That defines Lambda handler around this Go struct: https://github.com/mantil-io/template-excuses/blob/master/api/excuses/excuses.go

When used with API Gateway in Mantil application exported methods are exposed at URLs:

Default - [root]/excuses
Count   - [root]/excuses/count
Random  - [root]/excuses/random

... and so on, where excuses is the name of this api.

This is similar to the default Go Lambda integration: https://docs.aws.amazon.com/lambda/latest/dg/golang-handler.html With added feature that all struct exported methods all exposed.

Context provided to the methods is RequestContext which is wrapper around default lambdacontext with few added attributes.

If you are using AWS Console and test calling Lambda functions use this test data:

{
  "uri": "count",
  "payload": ...
}

to call count method for example.

func Publish

func Publish(subject string, payload interface{}) error

Publish publishes a payload to a given subject. Clients can subscribe using the JS SDK: https://github.com/mantil-io/mantil.js

func S3Bucket

func S3Bucket(name string) (*s3svc.Client, error)

S3Bucket creates a new S3 bucket (if it doesn't already exist) for use within a Mantil project. The final name of the bucket follows the same naming convention as other Mantil resources and can be found by calling the Resource function.

The bucket will be deleted when the project stage is destroyed.

To perform operations on this bucket, use the returned s3 client. Please refer to the AWS SDK documentation for more information on how to use the S3 client: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client

func SetLogger

func SetLogger(l *log.Logger)

SetLogger changes library logger. By default it will log to stdout. Use `SetLogger(nil)` to discard logs.

Types

type ErrItemNotFound

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

ErrItemNotFound is returned when item with that key is not found in key value store.

func (ErrItemNotFound) Error

func (e ErrItemNotFound) Error() string

type FindIterator

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

FindIterator is used to iterate over a collection of items returned by the Find and FindAll methods

func (FindIterator) Count

func (i FindIterator) Count() int

Count number of items in iterator.

func (*FindIterator) HasMore

func (i *FindIterator) HasMore() bool

HasMore returns true if there are more items in iterator after those returned by first find or last Next.

func (*FindIterator) Next

func (i *FindIterator) Next(items interface{}) error

Next returns fills next chunk of itmes.

type FindOperator

type FindOperator int

FindOperator is a type representing search criteria for Find operations

const (
	// FindBeginsWith searches for items with keys beginning with a given prefix
	FindBeginsWith FindOperator = iota
	// FindGreaterThan searches for items with keys greater than the given key
	FindGreaterThan
	// FindLessThan searches for items with keys less than the given key
	FindLessThan
	// FindGreaterThanOrEqual searches for items with keys greater than or equal the given key
	FindGreaterThanOrEqual
	// FindLessThanOrEqual searches for items with keys less than or equal the given key
	FindLessThanOrEqual
	// FindBetween searches for items with keys between the given keys
	FindBetween
	// FindAll returns all items
	FindAll
)

type KV

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

KV is key value store backed DynamoDB. When used it becomes part of the Mantil project. DynamoDB table is created on demand, uses same naming convention as all other Mantil project resources. And it is removed when Mantil project stage is destroyed.

func NewKV

func NewKV(partition string) (*KV, error)

NewKV Creates new KV store. All KV stores uses same DynamoDB table. Partition splits that table into independent parts. Each partition has own set of keys.

func (*KV) Delete

func (k *KV) Delete(key ...string) error

Delete key or list of keys from KV.

func (*KV) DeleteAll

func (k *KV) DeleteAll() error

DeleteAll removes all keys from KV.

func (*KV) Find

func (k *KV) Find(items interface{}, op FindOperator, args ...string) (*FindIterator, error)

Find searches KV and returns iterator reading multiple items which satisfies search criteria. Example:

todos = make([]Todo, 0)
iter, err := kv.Find(&todos, FindBetween, "2", "6")
... consume todos
if iter.HasMore() {
   iter.Next(&todos)
   ... consume next chunk

func (*KV) FindAll

func (k *KV) FindAll(items interface{}) (*FindIterator, error)

FindAll return iterator over oll items in KV store.

func (*KV) Get

func (k *KV) Get(key string, value interface{}) error

Get value for the key. Value provided must be a non-nil pointer type.

func (*KV) Put

func (k *KV) Put(key string, value interface{}) error

Put value in to kv store by key.

type LambdaInvoker

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

LambdaInvoker represents a helper for invoking lambda functions with cross-account support.

func NewLambdaInvoker

func NewLambdaInvoker(function, role string) (*LambdaInvoker, error)

NewLambdaInvoker builds helper for invoking lambda functions.

function can be name of the function or full arn name - my-function (name-only), my-function:v1 (with alias). arn:aws:lambda:us-west-2:123456789012:function:my-function.

role is iam role to assume empty string if not needed; if the function is in the same aws account and caller has iam rights to invoke otherwise provide arn of the role

Example of full format: NewLambdaInvoker(

"arn:aws:lambda:eu-central-1:123456789012:function:dummy",
"arn:aws:iam::123456789012:role/cross-account-execute-lambda",

)

func (*LambdaInvoker) Call

func (l *LambdaInvoker) Call(payload []byte) ([]byte, error)

Call executes sync Lambda invoke. Expects payload to send in the Lambda function call.

func (*LambdaInvoker) CallAsync

func (l *LambdaInvoker) CallAsync(payload []byte) error

CallAsync invokes the Lambda function asynchronously

func (*LambdaInvoker) Cast

func (l *LambdaInvoker) Cast(payload []byte) error

Cast makes async Lambda invoke

func (*LambdaInvoker) Timeout

func (l *LambdaInvoker) Timeout() time.Duration

Timeout returns the lambda's timeout duration setting

type Request

type Request struct {
	Type    RequestType
	Methods []string
	Params  map[string]string
	Body    []byte
	Raw     []byte
	Headers map[string]string
	HTTP    httpData
	// contains filtered or unexported fields
}

Request contains Lambda function request attributes. It can be many sources of calling Lambda function:

• API Gateway
• AWS Console - detected at Type Unknown
• SDK - detected as Type Unknown
• Websocket API Gateway methods

Request contains most useful attributes regarding of calling method.

func (*Request) RemoteIP

func (r *Request) RemoteIP() string

RemoteIP returns remote IP (client IP) for request received through API Gateway

type RequestContext

type RequestContext struct {
	// Number of same worker Lambda function invocations
	// 1 - cold start
	RequestNo int
	// Lambda Request attributes
	Request Request
	// Ref: https://pkg.go.dev/github.com/aws/aws-lambda-go@v1.27.0/lambdacontext#LambdaContext
	Lambda *lambdacontext.LambdaContext
}

RequestContext is provided as first context attribute to all api methods handled by mantil.go You can get it by mantil.FromContext(). It is wrapper around github.com/aws/aws-lambda-go/lambdacontext

func FromContext

func FromContext(ctx context.Context) (*RequestContext, bool)

FromContext returns the LambdaContext value stored in ctx, if any.

func (*RequestContext) Authorizer

func (r *RequestContext) Authorizer() map[string]interface{}

Authorizer attributes. This is place where awuthorizer on API Gateway stores his metadata.

func (*RequestContext) WSConnectionID

func (r *RequestContext) WSConnectionID() string

WSConnectionID if the request is received through Websocket API Gateway this will return ID.

type RequestType

type RequestType int

RequestType represents the type of the incoming Lambda request

type ResourceInfo

type ResourceInfo struct {
	// Full name of the AWS resource
	Name string
	// Tags that are automatically added to the resource on creation
	Tags map[string]string
}

ResourceInfo contains information about resources created through Mantil

func Resource

func Resource(name string) ResourceInfo

Resource takes a user-defined resource name and returns a ResourceInfo struct containing the actual name and tags that are used to create the resource.