localstack

Documentation

Overview

This package was written to help writing tests with Localstack. (https://github.com/localstack/localstack) It uses libraries that help create and manage a Localstack docker container for your go tests.

Requirements

Go v1.11.0 or higher
Docker (Tested on version 19.03.0-rc Community Edition)

Example (S3)

In this example we initialize Localstack with the S3 service enabled, create a bucket, upload a file to that bucket, then download that file from s3 and output it's content.

For complete testing examples, see the examples in the github.com repository. https://github.com/mitchelldavis/go_localstack/tree/master/examples

// LOCALSTACK: A reference to the Localstack object
var LOCALSTACK *Localstack

// Create the S3 Service definition
s3Service, _ := NewLocalstackService("s3")

// Gather up all service definitions in a single collection.
// (Only one in this case.)
LOCALSTACK_SERVICES := &LocalstackServiceCollection{
	*s3Service,
}

// Initialize Localstack.  Here Localstack is created and
// is ready to go.
var err error
LOCALSTACK, err = NewLocalstack(LOCALSTACK_SERVICES)
if err != nil {
	log.Fatal(fmt.Sprintf("Unable to create the instance: %s", err))
}
if LOCALSTACK == nil {
	log.Fatal("LOCALSTACK was nil.")
}

// Make sure we Destroy Localstack.  This method handles
// stopping and removing the docker container.
defer LOCALSTACK.Destroy()

// Here we start the code to interact with S3
svc := s3.New(LOCALSTACK.CreateAWSSession())

// Create Bucket
input := &s3.CreateBucketInput{
	Bucket: aws.String("examplebucket"),
	CreateBucketConfiguration: &s3.CreateBucketConfiguration{
		LocationConstraint: aws.String("us-east-1"),
	},
}

_, err = svc.CreateBucket(input)
if err != nil {
	log.Fatal(err)
}

//Upload File
uploader := s3manager.NewUploader(LOCALSTACK.CreateAWSSession())
_, err = uploader.Upload(&s3manager.UploadInput{
	Bucket: aws.String("examplebucket"),
	Key:    aws.String("examplefile"),
	Body:   strings.NewReader("Hello World"),
})
if err != nil {
	log.Fatal(err)
}

// Download the file
getObjectInput := &s3.GetObjectInput{
	Bucket: aws.String("examplebucket"),
	Key:    aws.String("examplefile"),
}

result, err := svc.GetObject(getObjectInput)
if err != nil {
	log.Fatal(err)
}

// Read the contents of the file.
text, err := ioutil.ReadAll(result.Body)

if err != nil {
	log.Fatal(err)
}

// Print the contents of the file out.
fmt.Println(string(text))

Output:

Hello World

Index

• Constants
• type DockerWrapper
• type Localstack
  • func NewLocalstack(services *LocalstackServiceCollection) (*Localstack, error)
  • func NewSpecificLocalstack(services *LocalstackServiceCollection, name, repository, tag string) (*Localstack, error)
  • func (l *Localstack) CreateAWSSession() *session.Session
  • func (ls *Localstack) Destroy() error
  • func (l Localstack) EndpointFor(service, region string, optFns ...func(*endpoints.Options)) (endpoints.ResolvedEndpoint, error)
• type LocalstackService
  • func NewLocalstackService(name string) (*LocalstackService, error)
  • func (service *LocalstackService) Equals(rhs *LocalstackService) bool
  • func (service *LocalstackService) GetNamePort() string
  • func (service *LocalstackService) GetPortProtocol() string
• type LocalstackServiceCollection
  • func (a *LocalstackServiceCollection) Contains(name string) bool
  • func (collection *LocalstackServiceCollection) GetServiceMap() string
  • func (a LocalstackServiceCollection) Len() int
  • func (a LocalstackServiceCollection) Less(i, j int) bool
  • func (a *LocalstackServiceCollection) Sort() *LocalstackServiceCollection
  • func (a LocalstackServiceCollection) Swap(i, j int)

Examples

• Package (S3)

Constants

const Localstack_Repository string = "localstack/localstack"

Localstack_Repository is the Localstack Docker repository

const Localstack_Tag string = "0.9.1"

Localstack_Tag is the last tested version of the Localstack Docker repository

Types

type DockerWrapper

type DockerWrapper interface {
	// See https://godoc.org/github.com/ory/dockertest/docker#Client.InspectContainer
	InspectContainer(string) (*docker.Container, error)
	// See https://godoc.org/github.com/ory/dockertest/docker#Client.ListContainers
	ListContainers(docker.ListContainersOptions) ([]docker.APIContainers, error)
	// See https://godoc.org/github.com/ory/dockertest/docker#Client.RunWithOptions
	RunWithOptions(*dockertest.RunOptions, ...func(*docker.HostConfig)) (*dockertest.Resource, error)
	// See https://godoc.org/github.com/ory/dockertest/docker#Client.Retry
	Retry(func() error) error
}

DockerWrapper is used to abstract docker to make testing easier. Each method of this interface simply wraps functionality that already exists in the Client object of the github.com/ory/dockertest/docker library.

type Localstack

type Localstack struct {
	// Resource is a pointer to the dockertest.Resource
	// object that is the localstack docker container.
	// (https://godoc.org/github.com/ory/dockertest#Resource)
	Resource *dockertest.Resource
	// Services is a pointer to a collection of service definitions
	// that are being requested from this particular instance of Localstack.
	Services *LocalstackServiceCollection
}

Localstack is a structure used to control the lifecycle of the Localstack Docker container.

func NewLocalstack

func NewLocalstack(services *LocalstackServiceCollection) (*Localstack, error)

NewLocalstack creates a new Localstack docker container based on the latest version.

func NewSpecificLocalstack

func NewSpecificLocalstack(services *LocalstackServiceCollection, name, repository, tag string) (*Localstack, error)

NewSpecificLocalstack creates a new Localstack docker container based on the given name, repository, and tag given. NOTE: The Docker image used should be a Localstack image. The behavior is unknown otherwise. This method is provided to allow special situations like using a tag other than latest or when referencing an internal Localstack image.

func (*Localstack) CreateAWSSession

func (l *Localstack) CreateAWSSession() *session.Session

CreateAWSSession should be used to make sure that your AWS SDK traffic is routing to Localstack correctly.

func (*Localstack) Destroy

func (ls *Localstack) Destroy() error

Destroy simply shuts down and cleans up the Localstack container out of docker.

func (Localstack) EndpointFor

func (l Localstack) EndpointFor(service, region string, optFns ...func(*endpoints.Options)) (endpoints.ResolvedEndpoint, error)

EndpointResolver is necessary to route traffic to AWS services in your code to the Localstack endpoints.

type LocalstackService

type LocalstackService struct {
	// The name of the AWS Service. (I.E. "s3" or "apigateway")
	Name string
	// Protocol is the network protocol used for communication.
	Protocol string
	// Port is the port used when communicating with the service in the
	// Localstack instance.
	Port int
}

LocalstackService defines a particular AWS service requested for a Localstack instances. Note: You shold not create an instance of LocastackService directly. See: NewLocalstackService

func NewLocalstackService

func NewLocalstackService(name string) (*LocalstackService, error)

NewLocalstackService returns a new pointer to an instance of LocalstackService given the name of the service provided. Note: The name must match an aws service from this list (https://docs.aws.amazon.com/cli/latest/reference/#available-services) and be a supported service by Localstack.

func (*LocalstackService) Equals

func (service *LocalstackService) Equals(rhs *LocalstackService) bool

Equals returns wether two pointers to a LocalstackService are equal.

func (*LocalstackService) GetNamePort

func (service *LocalstackService) GetNamePort() string

GetNameProtocol returns the protocol string (eg. s3:1234) used by Docker.

func (*LocalstackService) GetPortProtocol

func (service *LocalstackService) GetPortProtocol() string

GetPortProtocol returns the protocol string (eg. 1234/tcp) used by Docker.

type LocalstackServiceCollection

type LocalstackServiceCollection []LocalstackService

LocalstackServiceCollection represents a collection of LocalstackService objects.

func (*LocalstackServiceCollection) Contains

func (a *LocalstackServiceCollection) Contains(name string) bool

func (*LocalstackServiceCollection) GetServiceMap

func (collection *LocalstackServiceCollection) GetServiceMap() string

GetServiceMap returns a comma delimited string of all the AWS service names in the collection.

func (LocalstackServiceCollection) Len

func (a LocalstackServiceCollection) Len() int

Len returns the number of items in the collection.

func (LocalstackServiceCollection) Less

func (a LocalstackServiceCollection) Less(i, j int) bool

Less compares two items in the collection. This returns true if the instance at i is less than the instance at j. Otherwise it will return false.

func (*LocalstackServiceCollection) Sort

func (a *LocalstackServiceCollection) Sort() *LocalstackServiceCollection

Sort simply sorts the collection based on the names of the defined services. The collection returned is a pointer to the calling collection.

func (LocalstackServiceCollection) Swap

func (a LocalstackServiceCollection) Swap(i, j int)

Swap will swap two items in the collection.