endpoint

Documentation

Index

• Constants
• func ResolveHost(ctx context.Context, port, override string) (host string, dnsOK bool)
• func ResolvedSource(cmd *cobra.Command) (source, value string, ok bool)
• func S3Addressing(endpointURL string) (pathStyle bool, s3Endpoint string)
• type IndeterminateTypeError
  • func (e *IndeterminateTypeError) Error() string
• type SchemeMismatchError
  • func (e *SchemeMismatchError) Error() string
  • func (e *SchemeMismatchError) Unwrap() error
• type Target
  • func Resolve(ctx context.Context, cmd *cobra.Command) (*Target, error)
  • func (t *Target) HostPort() string
• type UnreachableError
  • func (e *UnreachableError) Error() string
  • func (e *UnreachableError) Unwrap() error

Constants

const DNSRebindNote = "Could not resolve localhost.localstack.cloud, falling back to 127.0.0.1."

const EnvVar = "LSTK_ENDPOINT_URL"

EnvVar is the emulator-neutral environment variable that provides an endpoint URL when --endpoint-url is not passed.

const FlagName = "endpoint-url"

FlagName is the name of the global --endpoint-url persistent flag.

const Hostname = "localhost.localstack.cloud"

Functions

func ResolveHost

func ResolveHost(ctx context.Context, port, override string) (host string, dnsOK bool)

ResolveHost returns the best host:port for reaching LocalStack on the given port. If override is non-empty it is returned as-is. Otherwise a DNS check is performed; if Hostname does not resolve to 127.0.0.1 (e.g. DNS rebind protection is active), it falls back to 127.0.0.1 directly.

func ResolvedSource

func ResolvedSource(cmd *cobra.Command) (source, value string, ok bool)

ResolvedSource reports which endpoint URL source (if any) is present for this invocation — the flag itself if passed, else "LSTK_ENDPOINT_URL" or "AWS_ENDPOINT_URL" if set in the environment, in the same precedence order as Resolve — without validating or probing it.

func S3Addressing

func S3Addressing(endpointURL string) (pathStyle bool, s3Endpoint string)

S3Addressing decides S3 path-style and the S3 endpoint for the given base endpoint. Virtual-host-style addressing (used by *.localstack.cloud hosts) places the bucket as a subdomain of the S3 endpoint host, so the S3 endpoint host carries an `s3.` prefix and path style is off. Non-domain hosts (127.0.0.1/localhost) require path style and use the bare endpoint.

It is used both by the Terraform proxy (to set `s3_use_path_style` and the `s3` endpoint key in the generated override) and by the CDK proxy (to set `AWS_ENDPOINT_URL_S3`). CDK has no env-only lever for path style, so a pathStyle==true result there is informational only — see the cdk-proxy design.

Types

type IndeterminateTypeError

type IndeterminateTypeError struct {
	URL string
}

IndeterminateTypeError reports that a resolved endpoint responded, but its health/info payload could not be classified as aws, azure, or snowflake. There is no override flag or config setting for the type — detection is the only mechanism, so this is a hard failure rather than a fallback.

func (*IndeterminateTypeError) Error

func (e *IndeterminateTypeError) Error() string

type SchemeMismatchError

type SchemeMismatchError struct {
	// AltURL is the same endpoint under the other scheme, which did respond.
	AltURL string
	// Unreachable is the failure for the URL the user actually gave.
	Unreachable *UnreachableError
}

SchemeMismatchError reports that a resolved endpoint URL did not respond, but the very same host and port answered as a LocalStack emulator under the other scheme. The common shape is pointing at a cloud-hosted (TLS-terminated) instance with `http://`, where the raw transport error is a bare "no route to host" against port 80 that gives no hint the scheme is what's wrong.

It unwraps to the *UnreachableError it replaces, so callers matching on that type still match.

func (*SchemeMismatchError) Error

func (e *SchemeMismatchError) Error() string

func (*SchemeMismatchError) Unwrap

func (e *SchemeMismatchError) Unwrap() error

type Target

type Target struct {
	// URL is the normalized endpoint, e.g. "http://localhost:4566" (no
	// trailing slash).
	URL string
	// Type is the emulator type determined by probing the endpoint.
	Type config.EmulatorType
}

Target describes an externally-managed emulator resolved from --endpoint-url, LSTK_ENDPOINT_URL, or AWS_ENDPOINT_URL, rather than one discovered via local Docker inspection.

func Resolve

func Resolve(ctx context.Context, cmd *cobra.Command) (*Target, error)

Resolve determines whether the user gave an endpoint URL for this invocation, via (in precedence order) the --endpoint-url flag, LSTK_ENDPOINT_URL, or AWS_ENDPOINT_URL. If none are set, it returns (nil, nil) so the caller falls back to existing Docker-based discovery. If one is set, it validates the URL and probes it for reachability and emulator type, returning a *Target or a descriptive error.

cmd may be nil (some call sites don't have a *cobra.Command handy), in which case only the two environment variables are consulted.

func (*Target) HostPort

func (t *Target) HostPort() string

HostPort returns the bare host:port of the target, discarding the scheme. Every other consumer of a resolved Target now uses the full URL (see Target.URL) to preserve the caller's scheme end-to-end; the sole remaining use is cmd/az.go's azPreflight, which feeds this into azureconfig.BuildEndpoint — that helper always constructs its own "https://<subdomain>.<host>" Azure gateway address regardless of the original scheme, so discarding it there is correct, not a scheme leak.

type UnreachableError

type UnreachableError struct {
	URL   string
	Cause error
}

UnreachableError reports that a resolved endpoint URL did not respond, or did not respond with a recognizable LocalStack health payload. Its message deliberately never mentions Docker or suggests `lstk start` — the target is an emulator lstk did not start.

func (*UnreachableError) Error

func (e *UnreachableError) Error() string

func (*UnreachableError) Unwrap

func (e *UnreachableError) Unwrap() error