localstack

README

go-localstack

Go Wrapper for using localstack in go testing

Installation

Please make sure that you have Docker installed.

go get github.com/khulnasoft-labs/go-localstack

Usage

With SDK V2

func ExampleLocalstackWithContextSdkV2() {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()
    
    l, err := localstack.NewInstance()
    if err != nil {
        log.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.StartWithContext(ctx); err != nil {
        log.Fatalf("Could not start localstack %v", err)
    }
    
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithEndpointResolverWithOptions(aws.EndpointResolverWithOptionsFunc(func(_, _ string, _ ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{
			    PartitionID:       "aws", 
			    URL:               l.EndpointV2(localstack.SQS), 
			    SigningRegion:     "us-east-1", 
			    HostnameImmutable: true,
		    }, nil
        })),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("dummy", "dummy", "dummy")),
    )
    if err != nil {
        log.Fatalf("Could not get config %v", err)
    }
    
    myTestWithV2(cfg)
}

With SDK V1

func TestWithLocalStack(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    l, err := localstack.NewInstance()
    if err != nil {
        log.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.StartWithContext(ctx); err != nil {
        log.Fatalf("Could not start localstack %v", err)
    }

    myTestWith(&aws.Config{
        Credentials: credentials.NewStaticCredentials("not", "empty", ""),
        DisableSSL:  aws.Bool(true),
        Region:      aws.String(endpoints.UsWest1RegionID),
        Endpoint:    aws.String(l.Endpoint(localstack.SQS)),
    })
}

Documentation

Index

• Variables
• type Instance
  • func NewInstance(opts ...InstanceOption) (*Instance, error)
  • func (i *Instance) Endpoint(service Service) string
  • func (i *Instance) EndpointV2(service Service) string
  • func (i *Instance) Start() error
  • func (i *Instance) StartWithContext(ctx context.Context, services ...Service) error
  • func (i *Instance) Stop() error
• type InstanceOption
  • func WithClientFromEnv() (InstanceOption, error)
  • func WithInitScriptMount(initScriptDirPath string, completeLogLine string) (InstanceOption, error)
  • func WithLabels(labels map[string]string) InstanceOption
  • func WithLogger(logger *logrus.Logger) InstanceOption
  • func WithTimeout(timeout time.Duration) InstanceOption
  • func WithVersion(version string) InstanceOption
  • func WithVolumeMount(mountPath, hostPath string) (InstanceOption, error)
• type Service

Variables

var (
	FixedPort = Service{Name: "all", Port: "4566/tcp"}

	CloudFormation   = Service{Name: "cloudformation", Port: "4581/tcp"}
	CloudWatch       = Service{Name: "cloudwatch", Port: "4582/tcp"}
	CloudWatchLogs   = Service{Name: "cloudwatchlogs", Port: "4586/tcp"}
	CloudWatchEvents = Service{Name: "cloudwatchevents", Port: "4587/tcp"}
	DynamoDB         = Service{Name: "dynamoDB", Port: "4569/tcp"}
	DynamoDBStreams  = Service{Name: "dynamoDBStreams", Port: "4570/tcp"}
	EC2              = Service{Name: "ec2", Port: "4597/tcp"}
	ES               = Service{Name: "es", Port: "4578/tcp"}
	Firehose         = Service{Name: "firehose", Port: "4573/tcp"}
	IAM              = Service{Name: "iam", Port: "4593/tcp"}
	Kinesis          = Service{Name: "kinesis", Port: "4568/tcp"}
	Lambda           = Service{Name: "lambda", Port: "4574/tcp"}
	Redshift         = Service{Name: "redshift", Port: "4577/tcp"}
	Route53          = Service{Name: "route53", Port: "4580/tcp"}
	S3               = Service{Name: "s3", Port: "4572/tcp"}
	SecretsManager   = Service{Name: "secretsmanager", Port: "4584/tcp"}
	SES              = Service{Name: "ses", Port: "4579/tcp"}
	SNS              = Service{Name: "sns", Port: "4575/tcp"}
	SQS              = Service{Name: "sqs", Port: "4576/tcp"}
	SSM              = Service{Name: "ssm", Port: "4583/tcp"}
	STS              = Service{Name: "sts", Port: "4592/tcp"}
	StepFunctions    = Service{Name: "stepfunctions", Port: "4585/tcp"}
)

Supported AWS/localstack services

var AvailableServices = map[Service]struct{}{
	FixedPort:        {},
	CloudFormation:   {},
	CloudWatch:       {},
	CloudWatchLogs:   {},
	CloudWatchEvents: {},
	DynamoDB:         {},
	DynamoDBStreams:  {},
	EC2:              {},
	ES:               {},
	Firehose:         {},
	IAM:              {},
	Kinesis:          {},
	Lambda:           {},
	Redshift:         {},
	Route53:          {},
	S3:               {},
	SecretsManager:   {},
	SES:              {},
	SNS:              {},
	SQS:              {},
	SSM:              {},
	STS:              {},
	StepFunctions:    {},
}

AvailableServices provides a map of all services for faster searches

Types

type Instance

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

Instance manages the localstack

func NewInstance

func NewInstance(opts ...InstanceOption) (*Instance, error)

NewInstance creates a new Instance Fails when Docker is not reachable

func (*Instance) Endpoint

func (i *Instance) Endpoint(service Service) string

Endpoint returns the endpoint for the given service Endpoints are allocated dynamically (to avoid blocked ports), but are fix after starting the instance

func (*Instance) EndpointV2

func (i *Instance) EndpointV2(service Service) string

EndpointV2 returns the endpoint for the given service when used by aws-sdk-v2 Endpoints are allocated dynamically (to avoid blocked ports), but are fix after starting the instance

func (*Instance) Start

func (i *Instance) Start() error

Start starts the localstack Deprecated: Use StartWithContext instead.

func (*Instance) StartWithContext

func (i *Instance) StartWithContext(ctx context.Context, services ...Service) error

StartWithContext starts the localstack and ends it when the context is done. Use it to also start individual services, by default all are started.

func (*Instance) Stop

func (i *Instance) Stop() error

Stop stops the localstack Deprecated: Use StartWithContext instead.

type InstanceOption

type InstanceOption func(i *Instance)

InstanceOption is an option that controls the behaviour of localstack.

func WithClientFromEnv

func WithClientFromEnv() (InstanceOption, error)

WithClientFromEnv configures the instance to use a client that respects environment variables.

func WithInitScriptMount

func WithInitScriptMount(initScriptDirPath string, completeLogLine string) (InstanceOption, error)

WithInitScriptMount configures the instance with init scripts and waits for a specific line from the script to show as ready to continue

func WithLabels

func WithLabels(labels map[string]string) InstanceOption

WithLabels configures the labels that will be applied on the instance.

func WithLogger

func WithLogger(logger *logrus.Logger) InstanceOption

WithLogger configures the instance to use the specified logger.

func WithTimeout

func WithTimeout(timeout time.Duration) InstanceOption

WithTimeout configures the timeout for terminating the localstack instance. This was invented to prevent orphaned containers after panics. The default timeout is set to 5 minutes.

func WithVersion

func WithVersion(version string) InstanceOption

WithVersion configures the instance to use a specific version of localstack. Must be a valid version string or "latest".

func WithVolumeMount

func WithVolumeMount(mountPath, hostPath string) (InstanceOption, error)

WithVolumeMount configures the instance to use the specified volume mounts.

type Service

type Service struct {
	Name string
	Port string
}

Service represents an AWS service