sparta.go

package sparta

import (
	"context"
	"crypto/sha1"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"math/rand"
	"os"
	"reflect"
	"regexp"
	"runtime"
	"strings"
	"sync"
	"time"

	gof "github.com/awslabs/goformation/v5/cloudformation"
	gofcustom "github.com/awslabs/goformation/v5/cloudformation/cloudformation"
	gofiam "github.com/awslabs/goformation/v5/cloudformation/iam"
	goflambda "github.com/awslabs/goformation/v5/cloudformation/lambda"
	goftags "github.com/awslabs/goformation/v5/cloudformation/tags"
	spartaCF "github.com/mweagle/Sparta/v3/aws/cloudformation"
	cwCustomProvider "github.com/mweagle/Sparta/v3/aws/cloudformation/provider"
	spartaIAM "github.com/mweagle/Sparta/v3/aws/iam"
	gocc "github.com/mweagle/go-cloudcondenser"
	"github.com/pkg/errors"
	"github.com/rs/zerolog"
)

type cloudFormationLambdaCustomResource struct {
	gofcustom.CustomResource
	ServiceToken   string
	UserProperties map[string]interface{} `json:",omitempty"`
}

func customResourceProvider(resourceType string) gof.Resource {
	switch resourceType {
	case cloudFormationLambda:
		{
			return &cloudFormationLambdaCustomResource{}
		}
	default:
		return nil
	}
}

func init() {
	cwCustomProvider.RegisterCustomResourceProvider(customResourceProvider)
	rand.Seed(time.Now().Unix())
}

func noopMessage(operationName string) string {
	return fmt.Sprintf("Skipping %s due to -n/-noop flag",
		operationName)
}

/******************************************************************************/
// Global options
type optionsGlobalStruct struct {
	ServiceName        string          `validate:"required"`
	ServiceDescription string          `validate:"-"`
	Noop               bool            `validate:"-"`
	LogLevel           string          `validate:"eq=panic|eq=fatal|eq=error|eq=warn|eq=info|eq=debug"`
	LogFormat          string          `validate:"eq=txt|eq=text|eq=json"`
	TimeStamps         bool            `validate:"-"`
	Logger             *zerolog.Logger `validate:"-"`
	Command            string          `validate:"-"`
	BuildTags          string          `validate:"-"`
	LinkerFlags        string          `validate:"-"` // no requirements
	DisableColors      bool            `validate:"-"`
	startTime          time.Time
}

// OptionsGlobal stores the global command line options
var OptionsGlobal optionsGlobalStruct

////////////////////////////////////////////////////////////////////////////////
// Variables
////////////////////////////////////////////////////////////////////////////////

// Represents the CloudFormation Arn of this stack, referenced
// in CommonIAMStatements
var cloudFormationThisStackArn = gof.Join("", []string{
	"arn:aws:cloudformation:",
	gof.Ref("AWS::Region"),
	":",
	gof.Ref("AWS::AccountId"),
	":stack/",
	gof.Ref("AWS::StackName"),
	"/*"})

// CommonIAMStatements defines common IAM::Role Policy Statement values for different AWS
// service types.  See http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#genref-aws-service-namespaces
// for names.
// http://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions.html
// for more information.
var CommonIAMStatements = struct {
	Core           []spartaIAM.PolicyStatement
	VPC            []spartaIAM.PolicyStatement
	DynamoDB       []spartaIAM.PolicyStatement
	Kinesis        []spartaIAM.PolicyStatement
	SQS            []spartaIAM.PolicyStatement
	MSKCluster     []spartaIAM.PolicyStatement
	AmazonMQBroker []spartaIAM.PolicyStatement
}{
	Core: []spartaIAM.PolicyStatement{
		{
			Action: []string{"logs:CreateLogGroup",
				"logs:CreateLogStream",
				"logs:PutLogEvents"},
			Effect: "Allow",
			Resource: gof.Join("", []string{"arn:aws:logs:",
				gof.Ref("AWS::Region"),
				":",
				gof.Ref("AWS::AccountId"),
				":*"}),
		},
		{
			Effect: "Allow",
			Action: []string{"cloudformation:DescribeStacks",
				"cloudformation:DescribeStackResource"},
			Resource: cloudFormationThisStackArn,
		},
		// http://docs.aws.amazon.com/lambda/latest/dg/lambda-x-ray.html#enabling-x-ray
		{
			Effect: "Allow",
			Action: []string{"xray:PutTraceSegments",
				"xray:PutTelemetryRecords",
				"cloudwatch:PutMetricData"},
			Resource: "*",
		},
	},
	VPC: []spartaIAM.PolicyStatement{
		{
			Action: []string{"ec2:CreateNetworkInterface",
				"ec2:DescribeNetworkInterfaces",
				"ec2:DeleteNetworkInterface"},
			Effect:   "Allow",
			Resource: wildcardArn,
		},
	},
	DynamoDB: []spartaIAM.PolicyStatement{
		{
			Effect: "Allow",
			Action: []string{"dynamodb:DescribeStream",
				"dynamodb:GetRecords",
				"dynamodb:GetShardIterator",
				"dynamodb:ListStreams",
			},
		},
	},
	Kinesis: []spartaIAM.PolicyStatement{
		{
			Effect: "Allow",
			Action: []string{"kinesis:GetRecords",
				"kinesis:GetShardIterator",
				"kinesis:DescribeStream",
				"kinesis:ListStreams",
			},
		},
	},
	// https://docs.aws.amazon.com/lambda/latest/dg/with-sqs-create-execution-role.html
	SQS: []spartaIAM.PolicyStatement{
		{
			Effect: "Allow",
			Action: []string{"SQS:GetQueueAttributes",
				"SQS:ChangeMessageVisibility",
				"SQS:DeleteMessage",
				"SQS:ReceiveMessage",
			},
		},
	},
	MSKCluster: []spartaIAM.PolicyStatement{
		{
			Effect: "Allow",
			Action: []string{
				"kafka:DescribeCluster",
				"kafka:GetBootstrapBrokers",
				"ec2:CreateNetworkInterface",
				"ec2:DescribeNetworkInterfaces",
				"ec2:DescribeVpcs",
				"ec2:DeleteNetworkInterface",
				"ec2:DescribeSubnets",
				"ec2:DescribeSecurityGroups",
			},
		},
	},
	AmazonMQBroker: []spartaIAM.PolicyStatement{
		{
			Effect: "Allow",
			Action: []string{"mq:DescribeBroker",
				"secretsmanager:GetSecretValue",
				"ec2:CreateNetworkInterface",
				"ec2:DeleteNetworkInterface",
				"ec2:DescribeNetworkInterfaces",
				"ec2:DescribeSecurityGroups",
				"ec2:DescribeSubnets",
				"ec2:DescribeVpcs",
			},
		},
	},
}

// RE for sanitizing names
var reSanitize = regexp.MustCompile(`\W+`)

// Wildcard ARN for any AWS resource
var wildcardArn = "*"

// AssumePolicyDocument defines common a IAM::Role PolicyDocument
// used as part of IAM::Role resource definitions
var AssumePolicyDocument = ArbitraryJSONObject{
	"Version": "2012-10-17",
	"Statement": []ArbitraryJSONObject{
		{
			"Effect": "Allow",
			"Principal": ArbitraryJSONObject{
				"Service": []string{LambdaPrincipal,
					EC2Principal,
					APIGatewayPrincipal},
			},
			"Action": []string{"sts:AssumeRole"},
		},
	},
}

////////////////////////////////////////////////////////////////////////////////
// Types
////////////////////////////////////////////////////////////////////////////////

// ArbitraryJSONObject represents an untyped key-value object. CloudFormation resource representations
// are aggregated as []ArbitraryJSONObject before being marsharled to JSON
// for API operations.
type ArbitraryJSONObject map[string]interface{}

// LambdaContext defines the AWS Lambda Context object provided by the AWS Lambda runtime.
// See http://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html
// for more information on field values.  Note that the golang version doesn't functions
// defined on the Context object.
type LambdaContext struct {
	FunctionName       string `json:"functionName"`
	FunctionVersion    string `json:"functionVersion"`
	InvokedFunctionARN string `json:"invokedFunctionArn"`
	MemoryLimitInMB    string `json:"memoryLimitInMB"`
	AWSRequestID       string `json:"awsRequestId"`
	LogGroupName       string `json:"logGroupName"`
	LogStreamName      string `json:"logStreamName"`
}

// LambdaFunctionOptions defines additional AWS Lambda execution params.  See the
// AWS Lambda FunctionConfiguration (http://docs.aws.amazon.com/lambda/latest/dg/API_FunctionConfiguration.html)
// docs for more information. Note that the "Runtime" field will be automatically set
// to "nodejs4.3" (at least until golang is officially supported). See
// http://docs.aws.amazon.com/lambda/latest/dg/programming-model.html
type LambdaFunctionOptions struct {
	// Additional function description
	Description string
	// Memory limit
	MemorySize int
	// Timeout (seconds)
	Timeout int
	// VPC Settings
	VpcConfig *goflambda.Function_VpcConfig
	// Environment Variables
	Environment map[string]string
	// KMS Key Arn used to encrypt environment variables
	KmsKeyArn string
	// The maximum of concurrent executions you want reserved for the function
	ReservedConcurrentExecutions int
	// DeadLetterConfigArn is how Lambda handles events that it can't process.If
	// you don't specify a Dead Letter Queue (DLQ) configuration, Lambda
	// discards events after the maximum number of retries. For more information,
	// see Dead Letter Queues in the AWS Lambda Developer Guide.
	DeadLetterConfigArn string
	// Tags to associate with the Lambda function
	Tags map[string]string
	// Tracing options for XRay
	TracingConfig *goflambda.Function_TracingConfig
	// Additional params
	ExtendedOptions *ExtendedOptions
}

func defaultLambdaFunctionOptions() *LambdaFunctionOptions {
	return &LambdaFunctionOptions{Description: "",
		MemorySize:                   128,
		Timeout:                      3,
		VpcConfig:                    nil,
		Environment:                  make(map[string]string),
		KmsKeyArn:                    "",
		ReservedConcurrentExecutions: 0,
		ExtendedOptions:              nil,
	}
}

// ExtendedOptions allow the passing in of additional options during the creation of a Lambda Function
type ExtendedOptions struct {
	// User supplied function name to use for
	// http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-functionname
	// value. If this is not supplied, a reflection-based
	// name will be automatically used.
	Name string
}

// WorkflowHooks is a structure that allows callers to customize the Sparta provisioning
// pipeline to add contents the Lambda archive or perform other workflow operations.
type WorkflowHooks struct {
	// Initial hook context. May be empty
	Context context.Context
	// PreBuilds are called before the current Sparta-binary is compiled
	PreBuilds []WorkflowHookHandler
	// PostBuilds are called after the current Sparta-binary is compiled
	PostBuilds []WorkflowHookHandler
	// ArchiveHook is called after Sparta has populated the ZIP archive containing the
	// AWS Lambda code package and before the ZIP writer is closed.  Define this hook
	// to add additional resource files to your Lambda package
	Archives []ArchiveHookHandler
	// PreMarshall is called before Sparta marshalls the application contents to a CloudFormation template
	PreMarshall WorkflowHook
	// PreMarshalls are called before Sparta marshalls the application contents into a CloudFormation
	// template
	PreMarshalls []WorkflowHookHandler
	// ServiceDecorators are called before Sparta marshalls the CloudFormation template
	ServiceDecorators []ServiceDecoratorHookHandler

	// PostMarshalls are called after Sparta marshalls the application contents to a CloudFormation
	// template
	PostMarshalls []WorkflowHookHandler

	// Validators are hooks that are called when all marshalling
	// is complete. Each hook receives a complete read-only
	// copy of the materialized template.
	Validators []ServiceValidationHookHandler

	// Rollbacks are called if there is an error performing the requested operation
	Rollbacks []RollbackHookHandler
}

////////////////////////////////////////////////////////////////////////////////
// START - IAMRolePrivilege
//

// IAMRolePrivilege struct stores data necessary to create an IAM Policy Document
// as part of the inline IAM::Role resource definition.  See
// http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html
// for more information
// Deprecated: Prefer github.com/aws/iam/PolicyStatement instead.
type IAMRolePrivilege struct {
	// What actions you will allow.
	// Each AWS service has its own set of actions.
	// For example, you might allow a user to use the Amazon S3 ListBucket action,
	// which returns information about the items in a bucket.
	// Any actions that you don't explicitly allow are denied.
	Actions []string
	// Which resources you allow the action on. For example, what specific Amazon
	// S3 buckets will you allow the user to perform the ListBucket action on?
	// Users cannot access any resources that you have not explicitly granted
	// permissions to.
	Resource interface{} `json:",omitempty"`
	// Service that requires the action
	Principal interface{} `json:",omitempty"`
	// Optional condition for the privilege
	Condition interface{} `json:",omitempty"`
}

func (rolePrivilege *IAMRolePrivilege) resourceExpr() string {
	switch typedPrivilege := rolePrivilege.Resource.(type) {
	case string:
		return typedPrivilege
	default:
		return typedPrivilege.(string)
	}
}

// IAMRoleDefinition stores a slice of IAMRolePrivilege values
// to "Allow" for the given IAM::Role.
// Note that the CommonIAMStatements will be automatically included and do
// not need to be multiply specified.
type IAMRoleDefinition struct {
	// Slice of IAMRolePrivilege entries
	Privileges []IAMRolePrivilege
	// Cached logical resource name
	cachedLogicalName string
}

func (roleDefinition *IAMRoleDefinition) toResource(eventSourceMappings []*EventSourceMapping,
	options *LambdaFunctionOptions,
	logger *zerolog.Logger) *gofiam.Role {

	statements := CommonIAMStatements.Core
	for _, eachPrivilege := range roleDefinition.Privileges {
		policyStatement := spartaIAM.PolicyStatement{
			Effect:   "Allow",
			Action:   eachPrivilege.Actions,
			Resource: eachPrivilege.resourceExpr(),
		}
		statements = append(statements, policyStatement)
	}

	// Add VPC permissions iff needed
	if options != nil && options.VpcConfig != nil {
		statements = append(statements, CommonIAMStatements.VPC...)
	}
	// In the past Sparta used to attach EventSourceMapping policies here.
	// However, moving everything to dynamic references means that we can't
	// fully populate the PolicyDocument statement slice until all of
	// the dynamically provisioned resources are defined. So that logic has
	// been moved to annotateMaterializedTemplate and annotateEventSourceMappings
	// which is run as the final step right before the template is marshaled
	// for creation.

	// http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
	iamPolicies := []gofiam.Role_Policy{}
	iamPolicies = append(iamPolicies, gofiam.Role_Policy{
		PolicyDocument: ArbitraryJSONObject{
			"Version":   "2012-10-17",
			"Statement": statements,
		},
		PolicyName: "LambdaPolicy",
	})
	return &gofiam.Role{
		AssumeRolePolicyDocument: AssumePolicyDocument,
		Policies:                 iamPolicies,
	}
}

// Returns the stable logical name for this IAMRoleDefinition, which depends on the serviceName
// and owning targetLambdaFnName.  This potentially creates semantically equivalent IAM::Role entries
// from the same struct pointer, so:
// TODO: Create a canonical IAMRoleDefinition serialization that can be used as the digest source
func (roleDefinition *IAMRoleDefinition) logicalName(serviceName string, targetLambdaFnName string) string {
	if roleDefinition.cachedLogicalName == "" {
		roleDefinition.cachedLogicalName = CloudFormationResourceName("IAMRole", serviceName, targetLambdaFnName)
	}
	return roleDefinition.cachedLogicalName
}

//
// END - IAMRolePrivilege
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// START - EventSourceMapping

// EventSourceMapping specifies data necessary for pull-based configuration. The fields
// directly correspond to the golang AWS SDK's CreateEventSourceMappingInput
// (http://docs.aws.amazon.com/sdk-for-go/api/service/lambda.html#type-CreateEventSourceMappingInput)
type EventSourceMapping struct {
	BatchSize                      int
	StartingPosition               string
	EventSourceArn                 string
	Disabled                       bool
	BisectBatchOnFunctionError     bool
	DestinationConfig              *goflambda.EventSourceMapping_DestinationConfig
	MaximumBatchingWindowInSeconds int
	MaximumRecordAgeInSeconds      int
	MaximumRetryAttempts           int
	ParallelizationFactor          int
	PartialBatchResponse           bool
	Queues                         []string
	Topics                         []string
}

func (mapping *EventSourceMapping) export(serviceName string,
	targetLambdaName string,
	targetLambdaArn string,
	lambdaFunctionCode *goflambda.Function_Code,
	template *gof.Template,
	logger *zerolog.Logger) error {

	eventSourceMappingResource := &goflambda.EventSourceMapping{
		StartingPosition:               mapping.StartingPosition,
		EventSourceArn:                 mapping.EventSourceArn,
		FunctionName:                   targetLambdaArn,
		BatchSize:                      mapping.BatchSize,
		Enabled:                        !mapping.Disabled,
		BisectBatchOnFunctionError:     mapping.BisectBatchOnFunctionError,
		DestinationConfig:              mapping.DestinationConfig,
		MaximumBatchingWindowInSeconds: mapping.MaximumBatchingWindowInSeconds,
		MaximumRecordAgeInSeconds:      mapping.MaximumRecordAgeInSeconds,
		MaximumRetryAttempts:           mapping.MaximumRetryAttempts,
		ParallelizationFactor:          mapping.ParallelizationFactor,
		Queues:                         mapping.Queues,
		Topics:                         mapping.Topics,
	}

	// Unique components for the hash for the EventSource mapping
	// resource name
	hashParts := []string{
		targetLambdaName,
		mapping.EventSourceArn,
		targetLambdaArn,
		fmt.Sprintf("%d", mapping.BatchSize),
		mapping.StartingPosition,
	}
	hash := sha1.New()
	for _, eachHashPart := range hashParts {
		_, writeErr := hash.Write([]byte(eachHashPart))
		if writeErr != nil {
			return errors.Wrapf(writeErr,
				"Failed to update EventSourceMapping name: %s", eachHashPart)
		}
	}
	resourceName := fmt.Sprintf("LambdaES%s", hex.EncodeToString(hash.Sum(nil)))
	template.Resources[resourceName] = eventSourceMappingResource
	return nil
}

//
// END - EventSourceMapping
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// START - customResourceInfo

// customResourceInfo wraps up information about any userDefined CloudFormation
// user-defined Resources
type customResourceInfo struct {
	roleDefinition   *IAMRoleDefinition
	roleName         string
	handlerSymbol    interface{}
	userFunctionName string
	options          *LambdaFunctionOptions
	properties       map[string]interface{}
}

// Returns the stable CloudFormation resource logical name for this resource.  For
// a CustomResource, this name corresponds to the AWS::CloudFormation::CustomResource
// invocation of the Lambda function, not the lambda function itself
func (resourceInfo *customResourceInfo) logicalName() string {
	hash := sha1.New()
	// The name has to be stable so that the ServiceToken value which is
	// part the CustomResource invocation doesn't change during stack updates. CF
	// will throw an error if the ServiceToken changes across updates.
	source := fmt.Sprintf("%#v", resourceInfo.userFunctionName)
	_, writeErr := hash.Write([]byte(source))
	if writeErr != nil {
		fmt.Printf("TODO: failed to update hash. Error: %s", writeErr)
		panic("See previous error")
	}
	return CloudFormationResourceName(resourceInfo.userFunctionName,
		hex.EncodeToString(hash.Sum(nil)))
}

func (resourceInfo *customResourceInfo) export(serviceName string,
	targetLambda string,
	lambdaFunctionCode *goflambda.Function_Code,
	roleNameMap map[string]string,
	template *gof.Template,
	logger *zerolog.Logger) error {

	// Is this valid
	invalidErr := ensureValidSignature(resourceInfo.userFunctionName,
		resourceInfo.handlerSymbol)
	if invalidErr != nil {
		return invalidErr
	}

	// Figure out the role name
	iamRoleArnName := resourceInfo.roleName

	// If there is no user supplied role, that means that the associated
	// IAMRoleDefinition name has been created and this resource needs to
	// depend on that being created.
	if iamRoleArnName == "" && resourceInfo.roleDefinition != nil {
		iamRoleArnName = resourceInfo.roleDefinition.logicalName(serviceName,
			resourceInfo.userFunctionName)
	}
	lambdaDescription := resourceInfo.options.Description
	if lambdaDescription == "" {
		lambdaDescription = fmt.Sprintf("%s CustomResource: %s",
			serviceName,
			resourceInfo.userFunctionName)
	}

	// Create the Lambda Function
	lambdaFunctionName := awsLambdaFunctionName(resourceInfo.userFunctionName)

	lambdaEnv, lambdaEnvErr := lambdaFunctionEnvironment(nil,
		resourceInfo.userFunctionName,
		nil,
		logger)
	if lambdaEnvErr != nil {
		return errors.Wrapf(lambdaEnvErr, "Failed to create environment resource for custom info")
	}

	lambdaResource := &goflambda.Function{
		Code:         lambdaFunctionCode,
		FunctionName: lambdaFunctionName,
		Description:  lambdaDescription,
		Handler:      SpartaBinaryName,
		MemorySize:   resourceInfo.options.MemorySize,
		Role:         roleNameMap[iamRoleArnName],
		Runtime:      string(Go1LambdaRuntime),
		Timeout:      resourceInfo.options.Timeout,
		VpcConfig:    resourceInfo.options.VpcConfig,
		// DISPATCH INFORMATION
		Environment: lambdaEnv,
	}

	lambdaFunctionCFName := CloudFormationResourceName("CustomResourceLambda",
		resourceInfo.userFunctionName,
		resourceInfo.logicalName())
	lambdaResource.AWSCloudFormationMetadata = map[string]interface{}{
		fmt.Sprintf("%sFunc", string(Go1LambdaRuntime)): resourceInfo.userFunctionName,
	}
	template.Resources[lambdaFunctionCFName] = lambdaResource

	// And create the CustomResource that actually invokes it...
	newResource, newResourceError := newCloudFormationResource(cloudFormationLambda, logger)
	if nil != newResourceError {
		return newResourceError
	}
	customResource := newResource.(*cloudFormationLambdaCustomResource)
	customResource.ServiceToken = gof.GetAtt(lambdaFunctionCFName, "Arn")
	customResource.UserProperties = resourceInfo.properties
	template.Resources[resourceInfo.logicalName()] = customResource
	return nil
}

// END - customResourceInfo
////////////////////////////////////////////////////////////////////////////////

// Interceptor is the type of an event interceptor that taps the event lifecycle
type Interceptor func(ctx context.Context, msg json.RawMessage) context.Context

// NamedInterceptor represents a named interceptor that's invoked in the event path
type NamedInterceptor struct {
	Name        string
	Interceptor Interceptor
}

// InterceptorList is a list of NamedInterceptors
type InterceptorList []*NamedInterceptor

////////////////////////////////////////////////////////////////////////////////
// START - LambdaEventInterceptors

// LambdaEventInterceptors is the struct that stores event handlers that tap into
// the normal event dispatching workflow
type LambdaEventInterceptors struct {
	Begin          InterceptorList
	BeforeSetup    InterceptorList
	AfterSetup     InterceptorList
	BeforeDispatch InterceptorList
	AfterDispatch  InterceptorList
	Complete       InterceptorList
}

// Register is a convenience function to register a struct that
// implements the LambdaInterceptorProvider interface
func (lei *LambdaEventInterceptors) Register(provider LambdaInterceptorProvider) *LambdaEventInterceptors {
	namedInterceptor := func(interceptor Interceptor) *NamedInterceptor {
		return &NamedInterceptor{
			Name:        fmt.Sprintf("%T", provider),
			Interceptor: interceptor,
		}
	}
	if lei.Begin == nil {
		lei.Begin = make(InterceptorList, 0)
	}
	lei.Begin = append(lei.Begin, namedInterceptor(provider.Begin))

	if lei.BeforeSetup == nil {
		lei.BeforeSetup = make(InterceptorList, 0)
	}
	lei.BeforeSetup = append(lei.BeforeSetup, namedInterceptor(provider.BeforeSetup))

	if lei.AfterSetup == nil {
		lei.AfterSetup = make(InterceptorList, 0)
	}
	lei.AfterSetup = append(lei.AfterSetup, namedInterceptor(provider.AfterSetup))

	if lei.BeforeDispatch == nil {
		lei.BeforeDispatch = make(InterceptorList, 0)
	}
	lei.BeforeDispatch = append(lei.BeforeDispatch, namedInterceptor(provider.BeforeDispatch))

	if lei.AfterDispatch == nil {
		lei.AfterDispatch = make(InterceptorList, 0)
	}
	lei.AfterDispatch = append(lei.AfterDispatch, namedInterceptor(provider.AfterDispatch))

	if lei.Complete == nil {
		lei.Complete = make(InterceptorList, 0)
	}
	lei.Complete = append(lei.Complete, namedInterceptor(provider.Complete))
	return lei
}

// LambdaInterceptorProvider is the interface that defines an event interceptor
// Interceptors are able to hook into the normal event processing pipeline
type LambdaInterceptorProvider interface {
	Begin(ctx context.Context, msg json.RawMessage) context.Context
	BeforeSetup(ctx context.Context, msg json.RawMessage) context.Context
	AfterSetup(ctx context.Context, msg json.RawMessage) context.Context
	BeforeDispatch(ctx context.Context, msg json.RawMessage) context.Context
	AfterDispatch(ctx context.Context, msg json.RawMessage) context.Context
	Complete(ctx context.Context, msg json.RawMessage) context.Context
}

////////////////////////////////////////////////////////////////////////////////
// START - LambdaAWSInfo

// LambdaAWSInfo stores all data necessary to provision a golang-based AWS Lambda function.
type LambdaAWSInfo struct {
	// AWS Go lambda compliant function
	handlerSymbol interface{}
	// pointer to lambda function
	//lambdaFn LambdaFunction
	// The user supplied internal name
	userSuppliedFunctionName string
	// Role name (NOT ARN) to use during AWS Lambda Execution.  See
	// the FunctionConfiguration (http://docs.aws.amazon.com/lambda/latest/dg/API_FunctionConfiguration.html)
	// docs for more info.
	// Note that either `RoleName` or `RoleDefinition` must be supplied
	RoleName string
	// IAM Role Definition if the stack should implicitly create an IAM role for
	// lambda execution. Note that either `RoleName` or `RoleDefinition` must be supplied
	RoleDefinition *IAMRoleDefinition
	// Additional exeuction options
	Options *LambdaFunctionOptions
	// Permissions to enable push-based Lambda execution.  See the
	// Permission Model docs (http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)
	// for more information.
	Permissions []LambdaPermissionExporter
	// EventSource mappings to enable for pull-based Lambda execution.  See the
	// Event Source docs (http://docs.aws.amazon.com/lambda/latest/dg/intro-core-components.html)
	// for more information
	EventSourceMappings []*EventSourceMapping
	// Template decorators. If non empty, the decorators will be called,
	// in order, to annotate the template
	Decorators []TemplateDecoratorHandler
	// Template decorator. If defined, the decorator will be called to insert additional
	// resources on behalf of this lambda function
	Decorator TemplateDecorator
	// Optional array of infrastructure resource logical names, typically
	// defined by a TemplateDecorator, that this lambda depends on
	DependsOn []string

	// Lambda Layers
	// Ref: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-layers
	Layers []string

	// Slice of customResourceInfo pointers for any associated CloudFormation
	// CustomResources associated with this lambda
	customResources []*customResourceInfo
	// Cached lambda name s.t. we only compute it once
	cachedLambdaFunctionName string

	// deprecation notices
	deprecationNotices []string

	// runtime name
	runtimeName AWSLambdaRuntimeName

	// interceptors
	Interceptors *LambdaEventInterceptors

	// Internal mutex to prevent race conditions when lazily updating lambda function name
	rwMutex sync.Mutex
}

// lambdaFunctionName returns the internal
// function name for lambda export binding
func (info *LambdaAWSInfo) lambdaFunctionName() string {
	info.rwMutex.Lock()
	defer info.rwMutex.Unlock()
	if info.cachedLambdaFunctionName != "" {
		return info.cachedLambdaFunctionName
	}
	var lambdaFuncName string

	if info.Options != nil &&
		info.Options.ExtendedOptions != nil &&
		info.Options.ExtendedOptions.Name != "" {
		lambdaFuncName = info.Options.ExtendedOptions.Name
	} else if info.userSuppliedFunctionName != "" {
		lambdaFuncName = info.userSuppliedFunctionName
	} else {
		// Using the default name, let's at least remove the
		// first prefix, since that's the SCM provider and
		// doesn't provide a lot of value...

		if info.handlerSymbol != nil {
			lambdaPtr := runtime.FuncForPC(reflect.ValueOf(info.handlerSymbol).Pointer())
			lambdaFuncName = lambdaPtr.Name()
		}

		// Split
		// cwd: /Users/mweagle/Documents/gopath/src/github.com/mweagle/SpartaHelloWorld
		// anonymous: github.com/mweagle/Sparta.(*StructHandler1).(github.com/mweagle/Sparta.handler)-fm
		//	RE==> var reSplit = regexp.MustCompile("[\\(\\)\\.\\*]+")
		// 	RESULT ==> Hello,[github com/mweagle/Sparta StructHandler1 github com/mweagle/Sparta handler -fm]
		// Same package: main.helloWorld
		// Other package, free function: github.com/mweagle/SpartaPython.HelloWorld

		// Grab the name of the function...
		structDefined := strings.Contains(lambdaFuncName, "(") || strings.Contains(lambdaFuncName, ")")
		otherPackage := strings.Contains(lambdaFuncName, "/")
		canonicalName := lambdaFuncName
		if structDefined {
			var reSplit = regexp.MustCompile(`[*\(\)\[\]]+`)
			// Function name:
			// github.com/mweagle/Sparta.(*StructHandler1).handler-fm
			parts := reSplit.Split(lambdaFuncName, -1)
			lastPart := parts[len(parts)-1]
			penultimatePart := lastPart
			if len(parts) > 1 {
				penultimatePart = parts[len(parts)-2]
			}
			intermediateName := fmt.Sprintf("%s-%s", penultimatePart, lastPart)
			reClean := regexp.MustCompile(`[\*\(\)]+`)
			canonicalName = reClean.ReplaceAllString(intermediateName, "")
		} else if otherPackage {
			parts := strings.Split(lambdaFuncName, "/")
			canonicalName = parts[len(parts)-1]
		}
		// Final sanitization
		// Issue: https://github.com/mweagle/Sparta/issues/63
		lambdaFuncName = sanitizedName(canonicalName)
	}
	// Cache it so we only do this once
	info.cachedLambdaFunctionName = lambdaFuncName
	return info.cachedLambdaFunctionName
}

// NewDescriptionTriplet returns a decription triplet where this lambda
// is either a sink or a source
func (info *LambdaAWSInfo) NewDescriptionTriplet(nodeName string, lambdaIsTarget bool) *DescriptionTriplet {

	if lambdaIsTarget {
		return &DescriptionTriplet{
			SourceNodeName: nodeName,
			TargetNodeName: info.lambdaFunctionName(),
		}
	}
	return &DescriptionTriplet{
		SourceNodeName: info.lambdaFunctionName(),
		TargetNodeName: nodeName,
	}
}

// Description satisfies the Describable interface
func (info *LambdaAWSInfo) Description(targetNodeName string) ([]*DescriptionTriplet, error) {

	descriptionNodes := make([]*DescriptionTriplet, 0)
	descriptionNodes = append(descriptionNodes, &DescriptionTriplet{
		SourceNodeName: info.lambdaFunctionName(),
		DisplayInfo: &DescriptionDisplayInfo{
			SourceIcon: &DescriptionIcon{
				Category: "Arch_Compute",
				Name:     "64/Arch_AWS-Lambda_64.png",
			},
		},
		TargetNodeName: targetNodeName,
	})
	// What about the permissions?
	for _, eachPermission := range info.Permissions {
		nodes, err := eachPermission.descriptionInfo()
		if nil != err {
			return nil, err
		}

		for _, eachNode := range nodes {
			name := strings.TrimSpace(eachNode.Name)
			arc := strings.TrimSpace(eachNode.Relation)
			descriptionNodes = append(descriptionNodes, &DescriptionTriplet{
				SourceNodeName: name,
				DisplayInfo: &DescriptionDisplayInfo{
					SourceNodeColor: nodeColorEventSource,
					SourceIcon:      iconForAWSResource(name),
				},
				ArcLabel:       arc,
				TargetNodeName: info.lambdaFunctionName(),
			})
		}
	}

	// Finally, event sources...
	for index, eachEventSourceMapping := range info.EventSourceMappings {
		jsonBytes, jsonBytesErr := json.Marshal(eachEventSourceMapping.EventSourceArn)
		if jsonBytesErr != nil {
			jsonBytes = []byte(fmt.Sprintf("%s-EventSourceMapping[%d]",
				info.lambdaFunctionName(),
				index))
		}
		nodeName := string(jsonBytes)
		descriptionNodes = append(descriptionNodes, &DescriptionTriplet{
			SourceNodeName: nodeName,
			DisplayInfo: &DescriptionDisplayInfo{
				SourceIcon: iconForAWSResource(eachEventSourceMapping.EventSourceArn),
			},
			TargetNodeName: info.lambdaFunctionName(),
		})
	}
	return descriptionNodes, nil
}

// RequireCustomResource adds a Lambda-backed CustomResource entry to the CloudFormation
// template. This function will be made a dependency of the owning Lambda function.
// The returned string is the custom resource's CloudFormation logical resource
// name that can be used for `Fn:GetAtt` calls for metadata lookups
func (info *LambdaAWSInfo) RequireCustomResource(roleNameOrIAMRoleDefinition interface{},
	handlerSymbol interface{},
	lambdaOptions *LambdaFunctionOptions,
	resourceProps map[string]interface{}) (string, error) {
	if nil == handlerSymbol {
		return "", fmt.Errorf("RequireCustomResource userFunc must not be nil")
	}
	// Is it valid?
	// Get the function pointer for this...
	handlerType := reflect.TypeOf(handlerSymbol)
	if handlerType.Kind() != reflect.Func {
		return "", fmt.Errorf("CustomResourceHandler kind %s is not %s",
			handlerType.Kind(),
			reflect.Func)
	}

	if nil == lambdaOptions {
		lambdaOptions = defaultLambdaFunctionOptions()
	}
	funcPtr := runtime.FuncForPC(reflect.ValueOf(handlerSymbol).Pointer())
	resourceInfo := &customResourceInfo{
		handlerSymbol:    handlerSymbol,
		userFunctionName: funcPtr.Name(),
		options:          lambdaOptions,
		properties:       resourceProps,
	}
	switch v := roleNameOrIAMRoleDefinition.(type) {
	case string:
		resourceInfo.roleName = roleNameOrIAMRoleDefinition.(string)
	case IAMRoleDefinition:
		definition := roleNameOrIAMRoleDefinition.(IAMRoleDefinition)
		resourceInfo.roleDefinition = &definition
	default:
		panic(fmt.Sprintf("Unsupported IAM Role type: %s", v))
	}
	resourceInfo.options.Environment = make(map[string]string)
	info.customResources = append(info.customResources, resourceInfo)
	info.DependsOn = append(info.DependsOn, resourceInfo.logicalName())
	return resourceInfo.logicalName(), nil
}

// LogicalResourceName returns the stable, content-addressable logical
// name for this LambdaAWSInfo value. This is the CloudFormation
// resource name
func (info *LambdaAWSInfo) LogicalResourceName() string {
	// Per http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html,
	// we can only use alphanumeric, so we'll take the sanitized name and
	// remove all underscores
	// Prefer the user-supplied stable name to the internal one.
	baseName := info.lambdaFunctionName()
	resourceName := strings.Replace(sanitizedName(baseName), "_", "", -1)
	prefix := fmt.Sprintf("%sLambda", resourceName)
	return CloudFormationResourceName(prefix, info.lambdaFunctionName())
}

func (info *LambdaAWSInfo) applyDecorators(ctx context.Context,
	template *gof.Template,
	lambdaResource *goflambda.Function,
	serviceName string,
	lambdaFunctionCode *goflambda.Function_Code,
	buildID string,
	logger *zerolog.Logger) (context.Context, error) {

	decorators := info.Decorators
	if info.Decorator != nil {
		logger.Debug().
			Msgf("Decorator found for Lambda: %s",
				info.lambdaFunctionName())
		decorators = append(decorators, TemplateDecoratorHookFunc(info.Decorator))
	}

	decoratorCtx := ctx
	for _, eachDecorator := range decorators {
		// Create an empty template so that we can track whether things
		// are overwritten
		metadataMap := make(map[string]interface{})
		decoratorProxyTemplate := gof.NewTemplate()
		responseCtx, decoratorErr := eachDecorator.DecorateTemplate(decoratorCtx,
			serviceName,
			info.LogicalResourceName(),
			lambdaResource,
			metadataMap,
			lambdaFunctionCode,
			buildID,
			decoratorProxyTemplate,
			logger)
		if decoratorErr != nil {
			// Can we get the name?
			decoratorName := fmt.Sprintf("%T", eachDecorator)
			errorValue := errors.Errorf("TemplateDecorator %s failed to apply. Error: %s",
				decoratorName,
				decoratorErr)
			return responseCtx, errorValue
		}
		decoratorCtx = responseCtx
		// This data is marshalled into a DiscoveryInfo struct s.t. it can be
		// unmarshalled via sparta.Discover.  We're going to just stuff it into
		// it's own same named property
		if len(metadataMap) != 0 {
			errInsert := safeMetadataInsert(lambdaResource, info.LogicalResourceName(), metadataMap)
			if errInsert != nil {
				return ctx, errInsert
			}
		}
		// Append the custom resources
		safeMergeErrs := gocc.SafeMerge(decoratorProxyTemplate,
			template)
		if len(safeMergeErrs) != 0 {
			return decoratorCtx, errors.Errorf("Lambda (%s) decorator created conflicting resources: %v",
				info.lambdaFunctionName(),
				safeMergeErrs)
		}
	}
	return decoratorCtx, nil
}

// Marshal this object into 1 or more CloudFormation resource definitions that are accumulated
// in the resources map
func (info *LambdaAWSInfo) export(ctx context.Context,
	serviceName string,
	lambdaFunctionCode *goflambda.Function_Code,
	buildID string,
	roleNameMap map[string]string,
	template *gof.Template,
	logger *zerolog.Logger) (context.Context, error) {

	// Let's make sure the handler has the proper signature...This is basically
	// copy-pasted from the SDK

	// If we have RoleName, then get the ARN, otherwise get the Ref
	var dependsOn []string
	if nil != info.DependsOn {
		dependsOn = append(dependsOn, info.DependsOn...)
	}

	iamRoleArnName := info.RoleName

	// If there is no user supplied role, that means that the associated
	// IAMRoleDefinition name has been created and this resource needs to
	// depend on that being created.
	if iamRoleArnName == "" && info.RoleDefinition != nil {
		iamRoleArnName = info.RoleDefinition.logicalName(serviceName, info.lambdaFunctionName())
		dependsOn = append(dependsOn, info.RoleDefinition.logicalName(serviceName, info.lambdaFunctionName()))
	}
	lambdaDescription := info.Options.Description
	if lambdaDescription == "" {
		lambdaDescription = fmt.Sprintf("%s: %s", serviceName, info.lambdaFunctionName())
	}

	handlerName := ""
	switch info.runtimeName {
	case Go1LambdaRuntime:
		handlerName = SpartaBinaryName
	}
	// Create the primary resource
	lambdaResource := &goflambda.Function{
		Code:        lambdaFunctionCode,
		Description: lambdaDescription,
		MemorySize:  info.Options.MemorySize,
		Role:        roleNameMap[iamRoleArnName],
		Timeout:     info.Options.Timeout,
		VpcConfig:   info.Options.VpcConfig,
	}

	// Pick the right kind of handler/runtime
	if lambdaFunctionCode.ImageUri != "" {
		lambdaResource.PackageType = "Image"
	} else {
		lambdaResource.Runtime = string(info.runtimeName)
		lambdaResource.Handler = handlerName
	}
	// Layers?
	if nil != info.Layers {
		lambdaResource.Layers = info.Layers
	}

	if info.Options.ReservedConcurrentExecutions != 0 {
		lambdaResource.ReservedConcurrentExecutions = info.Options.ReservedConcurrentExecutions
	}
	if info.Options.DeadLetterConfigArn != "" {
		lambdaResource.DeadLetterConfig = &goflambda.Function_DeadLetterConfig{
			TargetArn: info.Options.DeadLetterConfigArn,
		}
	}
	if nil != info.Options.TracingConfig {
		lambdaResource.TracingConfig = info.Options.TracingConfig
	}
	if info.Options.KmsKeyArn != "" {
		lambdaResource.KmsKeyArn = info.Options.KmsKeyArn
	}
	if nil != info.Options.Tags {
		tagList := []goftags.Tag{}
		for eachKey, eachValue := range info.Options.Tags {
			tagList = append(tagList, goftags.Tag{
				Key:   eachKey,
				Value: eachValue,
			})
		}
		lambdaResource.Tags = tagList
	}

	// DISPATCH INFORMATION
	// Make sure we set the environment variable that
	// tells us which function to actually execute in
	// execute_awsbinary.go
	if info.Options.Environment == nil {
		info.Options.Environment = make(map[string]string)
	}
	info.Options.Environment[envVarLogLevel] =
		logger.GetLevel().String()

	lambdaResource.Environment = &goflambda.Function_Environment{
		Variables: info.Options.Environment,
	}

	// This function name is set here to be the same
	// name that the dispatcher will look up in execute
	// using the same logic so that we can borrow the
	// `AWS_LAMBDA_FUNCTION_NAME` env var
	lambdaFunctionName := awsLambdaFunctionName(info.lambdaFunctionName())
	lambdaResource.FunctionName = lambdaFunctionName
	lambdaResource.AWSCloudFormationDependsOn = dependsOn
	lambdaResource.AWSCloudFormationMetadata = map[string]interface{}{
		string(info.runtimeName): info.lambdaFunctionName(),
	}
	template.Resources[info.LogicalResourceName()] = lambdaResource

	// Create the lambda Ref in case we need a permission or event mapping
	functionAttr := gof.GetAtt(info.LogicalResourceName(), "Arn")

	// Permissions
	for _, eachPermission := range info.Permissions {
		_, err := eachPermission.export(serviceName,
			info.lambdaFunctionName(),
			info.LogicalResourceName(),
			template,
			lambdaFunctionCode,
			logger)
		if nil != err {
			return ctx, errors.Wrapf(err, "Failed to export lambda permission")
		}
	}

	// Event Source Mappings
	for _, eachEventSourceMapping := range info.EventSourceMappings {
		mappingErr := eachEventSourceMapping.export(serviceName,
			info.lambdaFunctionName(),
			functionAttr,
			lambdaFunctionCode,
			template,
			logger)
		if nil != mappingErr {
			return ctx, mappingErr
		}
	}

	// CustomResource
	for _, eachCustomResource := range info.customResources {
		resourceErr := eachCustomResource.export(serviceName,
			functionAttr,
			lambdaFunctionCode,
			roleNameMap,
			template,
			logger)
		if nil != resourceErr {
			return ctx, resourceErr
		}
	}

	responseCtx, decoratorErr := info.applyDecorators(ctx,
		template,
		lambdaResource,
		serviceName,
		lambdaFunctionCode,
		buildID,
		logger)

	if decoratorErr != nil {
		return responseCtx, decoratorErr
	}

	// Log any deprecation notices
	for _, eachDeprecation := range info.deprecationNotices {
		logger.Warn().Msg(eachDeprecation)
	}
	return responseCtx, nil
}

//
// END - LambdaAWSInfo
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// Public
////////////////////////////////////////////////////////////////////////////////

// AWSLambdaProvider is an interface that represents a struct that
// encapsulates a Lambda function
type AWSLambdaProvider interface {
	Handler() interface{}
	Name() string
	Role() interface{}
}

// CloudFormationResourceName returns a name suitable as a logical
// CloudFormation resource value.  See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html
// for more information.  The `prefix` value should provide a hint as to the
// resource type (eg, `SNSConfigurator`, `ImageTranscoder`).  Note that the returned
// name is not content-addressable.
func CloudFormationResourceName(prefix string, parts ...string) string {
	return spartaCF.ResourceName(prefix, parts...)
}

// LambdaName returns the Go-reflection discovered name for a given
// function
func LambdaName(handlerSymbol interface{}) string {
	funcPtr := runtime.FuncForPC(reflect.ValueOf(handlerSymbol).Pointer())
	return funcPtr.Name()
}

// NewAWSLambdaFromProvider is a utility function to return
// an LambdaAWSInfo from an AWSLambdaProvider
func NewAWSLambdaFromProvider(provider AWSLambdaProvider) (*LambdaAWSInfo, error) {
	return NewAWSLambda(provider.Name(),
		provider.Handler(),
		provider.Role())
}

/*
Supported lambdaHandler signatures:

• 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)
*/

// NewAWSLambda is the creation function that replaces HandleAWSLambda. It returns
// a *LambdaAWSInfo pointer to the struct representing the AWS lambda target. It's a
// go-friendly signature for creating a lambda function
func NewAWSLambda(functionName string,
	lambdaHandler interface{},
	roleNameOrIAMRoleDefinition interface{}) (*LambdaAWSInfo, error) {

	if functionName == "" {
		return nil, errors.Errorf("AWS Lambda function name must not be empty")
	}
	if lambdaHandler == nil {
		return nil, errors.Errorf("AWS Lambda function handler must not be nil")
	}

	lambda := &LambdaAWSInfo{
		userSuppliedFunctionName: functionName,
		handlerSymbol:            lambdaHandler,
		Options:                  defaultLambdaFunctionOptions(),
		Permissions:              make([]LambdaPermissionExporter, 0),
		EventSourceMappings:      make([]*EventSourceMapping, 0),
		deprecationNotices:       make([]string, 0),
		runtimeName:              Go1LambdaRuntime,
	}

	switch v := roleNameOrIAMRoleDefinition.(type) {
	case string:
		lambda.RoleName = v
	case IAMRoleDefinition:
		definition := v
		lambda.RoleDefinition = &definition
	default:
		return nil, errors.Errorf("AWS Lambda function IAM role must not be empty")
	}
	return lambda, nil
}

// IsExecutingInLambda is a utility function to return a boolean
// indicating whether the application is running in AWS Lambda.
// See the list of environment variables defined at:
// https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html
// for more information.
func IsExecutingInLambda() bool {
	return os.Getenv("LAMBDA_TASK_ROOT") != "" ||
		os.Getenv("AWS_EXECUTION_ENV") != ""
}