Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultRemotePodName(now time.Time) string
- func IsS3Ref(ref string) bool
- func List(ctx context.Context, lister CloudPodLister, authToken, creator string, ...) error
- func ListRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func LoadLocal(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func LoadPod(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func LoadRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func Remove(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func SaveLocal(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func SavePod(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func SaveRemoteS3(ctx context.Context, rt runtime.Runtime, containers []config.ContainerConfig, ...) error
- func Show(ctx context.Context, inspector CloudPodInspector, authToken, podName string, ...) error
- func ValidateMergeStrategy(strategy string) error
- func ValidatePodName(name string) error
- type CloudPodInspector
- type CloudPodLister
- type Destination
- type DestinationKind
- type LocalLoadClient
- type PodLoader
- type PodRemover
- type PodSaveResult
- type PodSaver
- type RemoteClient
- type RemotePod
- type S3Credentials
- type Starter
- type StateExporter
Constants ¶
const ( MergeStrategyAccountRegion = "account-region-merge" MergeStrategyOverwrite = "overwrite" MergeStrategyService = "service-merge" )
Variables ¶
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") )
var ErrHomeNotSet = errors.New("home directory is not set")
ErrHomeNotSet is returned when a path needs "~" expansion but no home directory was provided.
var ErrIncompatibleSnapshot = errors.New("snapshot is incompatible with the running LocalStack version")
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.
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
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
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 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 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 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 ValidatePodName ¶ added in v0.15.0
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 CloudPodLister ¶ added in v0.12.0
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
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 S3Credentials ¶ added in v0.15.0
S3Credentials are the AWS credentials sent to the emulator for an S3 remote. They are passed as ephemeral per-request parameters and never persisted.