Cloud region affinity (earthlens.base.region)

region_affinity(bucket_region) answers one question: is this process running in the same cloud region as the target bucket? A backend uses the answer to choose between a cheap in-region streaming read and a slow, billed cross-region egress download.

It returns one of three verdicts:

Verdict	Meaning
"in-region"	the caller region equals bucket_region — stream directly
"egress"	caller and bucket are in different (known) regions — expect billed, slower transfer
"unknown"	the caller region could not be determined — fall back to the safe (HTTPS) path

How the caller region is resolved

Resolution is env-first, then an optional metadata probe:

1. an explicit caller_region= argument, then
2. AWS_REGION / AWS_DEFAULT_REGION, then
3. (only when probe=True) an instance-metadata probe — AWS IMDSv2, GCP metadata.google.internal, or Azure IMDS — each behind a hard 1 s timeout and cached per process.

Detection never raises and never blocks: any failure yields "unknown". Pass probe=False to skip all network access entirely (tests, air-gapped runs). The earthdata backend deliberately uses probe=False so its in-region decision never risks hanging an off-cloud caller.

Warning before large egress

warn_if_egress(bucket_region, *, size_bytes, threshold_bytes=1<<30) emits a single loguru warning when the hint is "egress" and the transfer exceeds the threshold (default 1 GiB), and returns the hint. The s3 backend calls it before a bulk pull (using the object sizes the listing already reported), so a cross-region transfer is never a silent cost surprise.

from earthlens.base.region import region_affinity, warn_if_egress

if region_affinity("us-west-2") == "in-region":
    ...  # stream from S3 in-region
else:
    warn_if_egress("us-west-2", size_bytes=total_bytes)  # advise, then HTTPS download

API

earthlens.base.region.region_affinity(bucket_region, *, caller_region=None, probe=True)

Classify the caller's region relative to a target bucket.

Resolves the caller region in order — explicit caller_region, then AWS_REGION / AWS_DEFAULT_REGION, then (when probe) an instance-metadata probe — and compares it to bucket_region. The result guides a backend's choice between an in-region streaming read and a cross-region egress download.

Parameters:

Name	Type	Description	Default
bucket_region	str | None	The region the target bucket lives in (e.g. "us-west-2"). None or empty yields "unknown".	required
caller_region	str | None	An explicit override for the caller's region. When given, the environment and probe are not consulted.	None
probe	bool	Whether to fall back to the instance-metadata probe when the environment carries no region. False skips all network access (tests, air-gapped runs, and the earthdata re-point).	True

Returns:

Type	Description
str	"in-region" when the caller region equals bucket_region,
str	"egress" when both are known and differ, or "unknown" when
str	the caller region cannot be determined (or bucket_region is
str	empty).

Examples:

• An explicit caller region drives the verdict without touching the environment:

  >>> from earthlens.base.region import region_affinity
  >>> region_affinity("us-west-2", caller_region="us-west-2")
  'in-region'
  >>> region_affinity("us-west-2", caller_region="eu-central-1")
  'egress'
  >>> region_affinity("", caller_region="us-west-2")
  'unknown'
  

Source code in src/earthlens/base/region.py

def region_affinity(
    bucket_region: str | None,
    *,
    caller_region: str | None = None,
    probe: bool = True,
) -> str:
    """Classify the caller's region relative to a target bucket.

    Resolves the caller region in order — explicit `caller_region`, then
    `AWS_REGION` / `AWS_DEFAULT_REGION`, then (when `probe`) an
    instance-metadata probe — and compares it to `bucket_region`. The
    result guides a backend's choice between an in-region streaming read
    and a cross-region egress download.

    Args:
        bucket_region: The region the target bucket lives in (e.g.
            `"us-west-2"`). `None` or empty yields `"unknown"`.
        caller_region: An explicit override for the caller's region. When
            given, the environment and probe are not consulted.
        probe: Whether to fall back to the instance-metadata probe when
            the environment carries no region. `False` skips all network
            access (tests, air-gapped runs, and the earthdata re-point).

    Returns:
        `"in-region"` when the caller region equals `bucket_region`,
        `"egress"` when both are known and differ, or `"unknown"` when
        the caller region cannot be determined (or `bucket_region` is
        empty).

    Examples:
        - An explicit caller region drives the verdict without touching
          the environment:
            ```python
            >>> from earthlens.base.region import region_affinity
            >>> region_affinity("us-west-2", caller_region="us-west-2")
            'in-region'
            >>> region_affinity("us-west-2", caller_region="eu-central-1")
            'egress'
            >>> region_affinity("", caller_region="us-west-2")
            'unknown'

            ```
    """
    if not bucket_region:
        return UNKNOWN
    caller = caller_region or _caller_region_from_env()
    if caller is None and probe:
        caller = _detect_caller_region()
    if caller is None:
        return UNKNOWN
    return IN_REGION if caller == bucket_region else EGRESS

earthlens.base.region.warn_if_egress(bucket_region, *, size_bytes, threshold_bytes=DEFAULT_EGRESS_THRESHOLD_BYTES, caller_region=None, probe=True)

Warn once before a large cross-region pull, returning the hint.

Computes the region affinity and, when the caller is in a different region than the bucket ("egress") and the transfer exceeds threshold_bytes, emits a single loguru warning so the user learns about the cross-region cost and latency up front. The hint is returned so a caller can branch on it too.

Parameters:

Name	Type	Description	Default
bucket_region	str | None	The region the target bucket lives in.	required
size_bytes	int	The size of the pending transfer in bytes.	required
threshold_bytes	int	The size above which the warning fires (default 1 GiB). A parameter, never hard-coded at the call site.	DEFAULT_EGRESS_THRESHOLD_BYTES
caller_region	str | None	An explicit override for the caller's region.	None
probe	bool	Whether to allow the instance-metadata probe (see :func:region_affinity).	True

Returns:

Type	Description
str	The affinity hint — "in-region", "egress", or "unknown".

Source code in src/earthlens/base/region.py

def warn_if_egress(
    bucket_region: str | None,
    *,
    size_bytes: int,
    threshold_bytes: int = DEFAULT_EGRESS_THRESHOLD_BYTES,
    caller_region: str | None = None,
    probe: bool = True,
) -> str:
    """Warn once before a large cross-region pull, returning the hint.

    Computes the region affinity and, when the caller is in a different
    region than the bucket (`"egress"`) and the transfer exceeds
    `threshold_bytes`, emits a single `loguru` warning so the user learns
    about the cross-region cost and latency up front. The hint is
    returned so a caller can branch on it too.

    Args:
        bucket_region: The region the target bucket lives in.
        size_bytes: The size of the pending transfer in bytes.
        threshold_bytes: The size above which the warning fires (default
            1 GiB). A parameter, never hard-coded at the call site.
        caller_region: An explicit override for the caller's region.
        probe: Whether to allow the instance-metadata probe (see
            :func:`region_affinity`).

    Returns:
        The affinity hint — `"in-region"`, `"egress"`, or `"unknown"`.
    """
    hint = region_affinity(bucket_region, caller_region=caller_region, probe=probe)
    if hint == EGRESS and size_bytes > threshold_bytes:
        logger.warning(
            f"Cross-region egress: pulling {size_bytes / (1 << 30):.2f} GiB "
            f"from {bucket_region!r} while running elsewhere — expect slower, "
            f"billed transfer. Run in {bucket_region!r} to stream in-region."
        )
    return hint