localstack

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package localstack manages LocalStack container lifecycle via testcontainers-go.

The package wraps the testcontainers-go LocalStack module with libtftest-specific defaults:

  • The default image depends on authentication. LocalStack's unified single image (calendar-versioned YYYY.MM.patch, e.g. localstack/localstack:2026.07.4) requires an auth token even for free-tier use, so with LOCALSTACK_AUTH_TOKEN set the package uses it — Pro features unlock at runtime via the same token, and there is no separate localstack-pro image. Without a token it falls back to the last token-free community image, localstack/localstack:4.14. LIBTFTEST_LOCALSTACK_IMAGE or Options.Image override the pin for custom or mirrored images
  • Ports are bound via PortEndpoint with the explicit edge port rather than Endpoint(http) — the latter picks the lowest port, which is wrong for multi-port containers
  • The AllServicesReady wait strategy uses the io.Reader signature introduced in testcontainers-go v0.30
  • LIBTFTEST_CONTAINER_URL bypasses container startup entirely so a single external container can serve a whole test suite

See INV-0002 for the Pro vs. OSS image-version landscape and DESIGN-0001 for the container-lifecycle modes the package supports (per-test, per-package via harness, per-suite via LIBTFTEST_CONTAINER_URL).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllServicesReady

func AllServicesReady(body io.Reader) bool

AllServicesReady returns true if no service is in state "initializing" or "error". The signature matches testcontainers' wait.HTTPStrategy ResponseMatcher: func(body io.Reader) bool.

func WriteInitHooks

func WriteInitHooks(hooks []InitHook) (string, error)

WriteInitHooks writes all hooks to a temp directory and returns its path. The directory is suitable for bind-mounting at /etc/localstack/init/ready.d/.

Types

type Config

type Config struct {
	Edition   Edition
	Image     string
	Services  []string
	AuthToken string
	InitHooks []InitHook
}

Config configures a LocalStack container.

func (*Config) Env

func (c *Config) Env() map[string]string

Env builds the environment variable map for the container.

func (*Config) ResolveImage

func (c *Config) ResolveImage() string

ResolveImage returns the container image to use, checking (in order): Config.Image, the LIBTFTEST_LOCALSTACK_IMAGE env var, then an authentication-dependent default. LocalStack's unified single image requires an auth token even for free-tier use, so when no token is configured ResolveImage falls back to the last token-free community image (defaultCommunityImage); with a token it uses the single image (defaultImage), which also unlocks Pro features.

type Container

type Container struct {
	ID       string
	EdgeURL  string
	Edition  Edition
	Services map[string]string
	// contains filtered or unexported fields
}

Container holds a running LocalStack container and its metadata.

func Start

func Start(ctx context.Context, cfg *Config) (*Container, error)

Start creates and starts a LocalStack container. It pre-checks that Docker is available, then uses testcontainers.Run with functional options. The container is considered ready only when AllServicesReady returns true on the /_localstack/health endpoint.

func (*Container) Endpoint

func (c *Container) Endpoint() string

Endpoint returns the HTTP edge URL for the running container.

func (*Container) Stop

func (c *Container) Stop(_ context.Context) error

Stop terminates the container.

type Edition

type Edition int

Edition represents a LocalStack product edition.

const (
	// EditionAuto detects the edition from the LOCALSTACK_AUTH_TOKEN env var.
	// If the token is set, assumes Pro; otherwise Community.
	EditionAuto Edition = iota
	// EditionCommunity is the free, open-source LocalStack edition.
	EditionCommunity
	// EditionPro is the commercial LocalStack edition with additional services.
	EditionPro
)

func DetectEdition

func DetectEdition(e Edition) Edition

DetectEdition resolves EditionAuto to a concrete edition based on the LOCALSTACK_AUTH_TOKEN environment variable.

func DetectEditionFromHealth

func DetectEditionFromHealth(body []byte) Edition

DetectEditionFromHealth returns the Edition based on the health response's edition field.

func (Edition) String

func (e Edition) String() string

String returns the human-readable edition name.

type HealthResponse

type HealthResponse struct {
	Edition  string            `json:"edition"`
	Version  string            `json:"version"`
	Services map[string]string `json:"services"`
}

HealthResponse represents the JSON response from /_localstack/health.

func ParseHealth

func ParseHealth(body []byte) (*HealthResponse, error)

ParseHealth parses a raw health response body into a HealthResponse.

type InitHook

type InitHook struct {
	Name   string // Becomes the filename in /etc/localstack/init/ready.d/.
	Script string // Bash script content.
}

InitHook defines a script to run inside the LocalStack container during its ready.d init phase.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL