snapshot

package
v0.18.0 Latest Latest
Warning

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

Go to latest
Published: Jul 22, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	MergeStrategyAccountRegion = "account-region-merge"
	MergeStrategyOverwrite     = "overwrite"
	MergeStrategyService       = "service-merge"
)

Variables

View Source
var (
	// ErrRemoteNotSupported is returned for remote schemes that are not yet
	// implemented (e.g. oras://). S3 (s3://) is supported.
	ErrRemoteNotSupported = errors.New("remote destinations are not yet supported — coming soon")
	// ErrUnknownScheme is returned for unrecognized URL schemes.
	ErrUnknownScheme = errors.New("unrecognized destination scheme")
	// ErrCredentialsInS3URL is returned when an s3:// ref embeds credential query
	// params. Credentials must come from the environment or --profile, never the URL.
	ErrCredentialsInS3URL = errors.New("do not put credentials in the s3:// URL; use AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or --profile")
)
View Source
var ErrHomeNotSet = errors.New("home directory is not set")

ErrHomeNotSet is returned when a path needs "~" expansion but no home directory was provided.

View Source
var ErrIncompatibleSnapshot = errors.New("snapshot is incompatible with the running LocalStack version")
View Source
var ErrInvalidSnapshotFile = errors.New("not a valid snapshot file")

ErrInvalidSnapshotFile indicates the source could not be read as a snapshot (e.g. a non-snapshot file was passed). It deliberately hides the underlying archive format from the user-facing message.

View Source
var ErrPodNotFound = errors.New("cloud pod not found")

ErrPodNotFound is returned when the cloud pod does not exist on the platform.

Functions

func DefaultRemotePodName added in v0.15.0

func DefaultRemotePodName(now time.Time) string

DefaultRemotePodName generates a timestamped pod name used when saving to a remote without an explicit name, mirroring local snapshot auto-naming.

func IsS3Ref added in v0.15.0

func IsS3Ref(ref string) bool

IsS3Ref reports whether ref is an s3:// reference. Used at the command boundary to classify positional args into a pod name and an S3 location.

func List added in v0.12.0

func List(ctx context.Context, lister CloudPodLister, authToken, creator string, sink output.Sink) error

func ListRemoteS3 added in v0.15.0

func ListRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, client RemoteClient, host, s3URL string, creds S3Credentials, authToken string, sink output.Sink) error

ListRemoteS3 lists the snapshots stored in the S3 bucket identified by s3URL. Unlike List (which queries the platform API), this requires a running emulator because the emulator performs the S3 listing.

func LoadLocal added in v0.10.0

func LoadLocal(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, client LocalLoadClient, host, src, strategy string, starter Starter, sink output.Sink) error

func LoadPod added in v0.10.0

func LoadPod(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, loader PodLoader, host, podName, authToken, strategy string, starter Starter, sink output.Sink) error

func LoadRemoteS3 added in v0.15.0

func LoadRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, client RemoteClient, host, podName, s3URL string, creds S3Credentials, authToken, strategy string, starter Starter, sink output.Sink) error

LoadRemoteS3 loads podName from the S3 bucket identified by s3URL into the running emulator, starting it first if needed.

func Remove added in v0.12.0

func Remove(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, podName, authToken string, remover PodRemover, host string, force bool, sink output.Sink) error

Remove deletes a remote pod snapshot, prompting for confirmation unless force is true.

func SaveLocal added in v0.9.0

func SaveLocal(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, exporter StateExporter, host, dest string, sink output.Sink) error

func SavePod added in v0.9.0

func SavePod(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, saver PodSaver, host, podName, authToken string, sink output.Sink) error

func SaveRemoteS3 added in v0.15.0

func SaveRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, client RemoteClient, host, podName, s3URL string, creds S3Credentials, authToken string, sink output.Sink) error

SaveRemoteS3 saves the running emulator's state to podName in the S3 bucket identified by s3URL, using the given credentials. An auth token is optional for S3 remotes (the S3 credentials are the auth); it is forwarded when present.

func Show added in v0.13.0

func Show(ctx context.Context, inspector CloudPodInspector, authToken, podName string, sink output.Sink) error

Show fetches a single cloud snapshot's metadata from the platform and emits it as a SnapshotShownEvent. It is cloud-only and requires authentication.

func ValidateMergeStrategy added in v0.10.0

func ValidateMergeStrategy(strategy string) error

func ValidatePodName added in v0.15.0

func ValidatePodName(name string) error

ValidatePodName validates a user-supplied pod name (the identity of a snapshot on a remote), using the same rules as pod: refs.

Types

type CloudPodInspector added in v0.13.0

type CloudPodInspector interface {
	GetCloudPod(ctx context.Context, authToken, podName string) (*api.CloudPodDetails, error)
}

type CloudPodLister added in v0.12.0

type CloudPodLister interface {
	ListCloudPods(ctx context.Context, authToken, creator string) ([]api.CloudPod, error)
}

type Destination added in v0.9.0

type Destination struct {
	Kind  DestinationKind
	Value string
}

Destination is the parsed result of a user-supplied snapshot destination. For KindLocal, Value is an absolute local file path with a .snapshot extension. For KindPod, Value is the validated pod name (without the "pod:" prefix). For KindS3, Value is the validated s3:// URL (bucket + optional key prefix), with no credential query params — credentials are supplied separately at runtime.

func ParseDestination

func ParseDestination(dest, home string, now time.Time) (Destination, error)

ParseDestination resolves a user-supplied destination to a local path (KindLocal) or validated pod name (KindPod). home is used to expand a leading "~" or "~/"; pass "" to disable tilde expansion.

func ParseRemovable added in v0.12.0

func ParseRemovable(ref, cwd, home string) (Destination, error)

ParseRemovable parses a ref for snapshot remove. Only cloud (pod:) refs are accepted; local file paths are rejected because the CLI cannot delete local files. cwd and home are used to produce a human-readable path in error messages.

func ParseShowable added in v0.13.0

func ParseShowable(ref, cwd, home string) (Destination, error)

ParseShowable parses a ref for snapshot show. Only cloud (pod:) refs are accepted; local file paths are rejected because show only inspects cloud snapshots. cwd and home are used to produce a human-readable path in error messages.

func ParseSource added in v0.10.0

func ParseSource(ref, home string) (Destination, error)

ParseSource resolves a user-supplied source REF for loading a snapshot. Unlike ParseDestination it never auto-generates a name: REF is required. For local paths, the file must exist; if no matching file is found, .snapshot and then .zip (legacy) are tried as fallbacks. home is used to expand a leading "~" or "~/"; pass "" to disable tilde expansion.

type DestinationKind added in v0.9.0

type DestinationKind int

DestinationKind distinguishes local file paths from remote pod destinations.

const (
	KindLocal DestinationKind = iota
	KindPod
	KindS3
)

type LocalLoadClient added in v0.10.0

type LocalLoadClient interface {
	// ImportState posts a zip to /_localstack/pods[?merge=strategy] and streams
	// the NDJSON response. strategy is passed as-is; empty means server default.
	ImportState(ctx context.Context, host string, src io.Reader, strategy string) error
	// ResetState wipes all running state via POST /_localstack/state/reset.
	// Used to implement overwrite client-side before importing.
	ResetState(ctx context.Context, host string) error
}

LocalLoadClient is satisfied by aws.Client.

type PodLoader added in v0.10.0

type PodLoader interface {
	// LoadPodSnapshot issues PUT /_localstack/pods/{name}?merge=strategy and
	// streams the NDJSON response.
	LoadPodSnapshot(ctx context.Context, host, podName, authToken, strategy string) ([]string, error)
}

PodLoader is satisfied by aws.Client.

type PodRemover added in v0.12.0

type PodRemover interface {
	RemovePodSnapshot(ctx context.Context, host, podName, authToken string) error
}

PodRemover deletes a remote pod snapshot on the LocalStack platform.

type PodSaveResult added in v0.9.0

type PodSaveResult struct {
	Version  int
	Services []string
	Size     int64
}

PodSaveResult holds the metadata returned by the platform after a successful pod save.

type PodSaver added in v0.9.0

type PodSaver interface {
	SavePodSnapshot(ctx context.Context, host, podName, authToken string) (PodSaveResult, error)
}

PodSaver triggers a remote pod snapshot save on the running LocalStack instance.

type RemoteClient added in v0.15.0

type RemoteClient interface {
	// S3BucketExists reports whether the named S3 bucket exists. Used to reject a
	// missing bucket before an operation, rather than letting the emulator
	// auto-create it.
	S3BucketExists(ctx context.Context, bucket string) (bool, error)
	// RegisterRemote upserts a named remote on the running emulator
	// (POST /_localstack/pods/remotes/<name>). remoteURL may contain {placeholder}
	// tokens that the emulator renders with the per-request params.
	RegisterRemote(ctx context.Context, host, name, remoteURL string) error
	// SavePodRemote saves the running state to podName on the named remote.
	SavePodRemote(ctx context.Context, host, podName, remoteName string, params map[string]string, authToken string) (PodSaveResult, error)
	// LoadPodRemote loads podName from the named remote with the given merge strategy.
	LoadPodRemote(ctx context.Context, host, podName, remoteName string, params map[string]string, authToken, strategy string) ([]string, error)
	// ListPodsRemote lists the snapshots stored on the named remote.
	ListPodsRemote(ctx context.Context, host, remoteName string, params map[string]string, authToken, creator string) ([]RemotePod, error)
}

RemoteClient is satisfied by aws.Client. It manages remote registration and the pod operations that target a named remote.

type RemotePod added in v0.15.0

type RemotePod struct {
	Name       string
	MaxVersion int
}

RemotePod is a snapshot listed on a remote storage backend.

type S3Credentials added in v0.15.0

type S3Credentials struct {
	AccessKeyID     string
	SecretAccessKey string
	SessionToken    string
}

S3Credentials are the AWS credentials sent to the emulator for an S3 remote. They are passed as ephemeral per-request parameters and never persisted.

type Starter added in v0.10.0

type Starter func(ctx context.Context, sink output.Sink) error

Starter is called to auto-start the emulator when none is running.

type StateExporter

type StateExporter interface {
	ExportState(ctx context.Context, host string, dst io.Writer) error
}

StateExporter retrieves state from the running LocalStack instance.

Jump to

Keyboard shortcuts

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