capo-lambda 0.5.0__py3-none-any.whl

capo_lambda/_rule_engine/_endpoint_rule_set.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._aws_partition import aws_partition
+from ._endpoint_runtime import (
+    Endpoint,
+    EndpointError,
+    get_attr,
+    interpolate,
+)
+
+
+class EndpointParams:
+    def __init__(
+        self,
+        *,
+        UseDualStack: bool | None = None,
+        UseFIPS: bool | None = None,
+        Region: str | None = None,
+        Endpoint: str | None = None,
+    ):
+        self.UseDualStack = UseDualStack if UseDualStack is not None else False
+        self.UseFIPS = UseFIPS if UseFIPS is not None else False
+        self.Region = Region if Region is not None else None
+        self.Endpoint = Endpoint if Endpoint is not None else None
+
+
+def resolve(p: EndpointParams) -> Endpoint:  # type: ignore
+    """Resolve endpoint from parameters using generated ruleset."""
+    _locals: dict[str, Any] = {}
+    if p.Endpoint is not None:
+        if p.UseFIPS is True:
+            raise EndpointError(
+                interpolate(
+                    "Invalid Configuration: FIPS and custom endpoint are not supported",
+                    p,
+                    _locals,
+                )
+            )
+        if p.UseDualStack is True:
+            raise EndpointError(
+                interpolate(
+                    "Invalid Configuration: Dualstack and custom endpoint are not supported",
+                    p,
+                    _locals,
+                )
+            )
+        return Endpoint(url=p.Endpoint, properties={}, headers={})
+    _locals: dict[str, Any] = {}
+    if p.Region is not None:
+        _locals["PartitionResult"] = aws_partition(p.Region)
+        if _locals["PartitionResult"] is not None:
+            if p.UseFIPS is True:
+                if p.UseDualStack is True:
+                    if True is get_attr(
+                        _locals["PartitionResult"],
+                        interpolate("supportsFIPS", p, _locals),
+                    ):
+                        if True is get_attr(
+                            _locals["PartitionResult"],
+                            interpolate("supportsDualStack", p, _locals),
+                        ):
+                            return Endpoint(
+                                url=interpolate(
+                                    "https://lambda-fips.{Region}.{PartitionResult#dualStackDnsSuffix}",
+                                    p,
+                                    _locals,
+                                ),
+                                properties={},
+                                headers={},
+                            )
+                    raise EndpointError(
+                        interpolate(
+                            "FIPS and DualStack are enabled, but this partition does not support one or both",
+                            p,
+                            _locals,
+                        )
+                    )
+            if p.UseFIPS is True:
+                if (
+                    get_attr(
+                        _locals["PartitionResult"],
+                        interpolate("supportsFIPS", p, _locals),
+                    )
+                    is True
+                ):
+                    return Endpoint(
+                        url=interpolate(
+                            "https://lambda-fips.{Region}.{PartitionResult#dnsSuffix}",
+                            p,
+                            _locals,
+                        ),
+                        properties={},
+                        headers={},
+                    )
+                raise EndpointError(
+                    interpolate(
+                        "FIPS is enabled but this partition does not support FIPS",
+                        p,
+                        _locals,
+                    )
+                )
+            if p.UseDualStack is True:
+                if True is get_attr(
+                    _locals["PartitionResult"],
+                    interpolate("supportsDualStack", p, _locals),
+                ):
+                    return Endpoint(
+                        url=interpolate(
+                            "https://lambda.{Region}.{PartitionResult#dualStackDnsSuffix}",
+                            p,
+                            _locals,
+                        ),
+                        properties={},
+                        headers={},
+                    )
+                raise EndpointError(
+                    interpolate(
+                        "DualStack is enabled but this partition does not support DualStack",
+                        p,
+                        _locals,
+                    )
+                )
+            return Endpoint(
+                url=interpolate(
+                    "https://lambda.{Region}.{PartitionResult#dnsSuffix}", p, _locals
+                ),
+                properties={},
+                headers={},
+            )
+    _locals: dict[str, Any] = {}
+    raise EndpointError(
+        interpolate("Invalid Configuration: Missing Region", p, _locals)
+    )
+    raise EndpointError("No endpoint rules matched")

capo_lambda/_rule_engine/_endpoint_runtime.py

@@ -0,0 +1,389 @@
+"""Endpoint rule-set runtime — hand-written helpers shared by every generated
+``_endpoint_rule_set.py``.  Pure, no third-party deps.
+
+Functions mirror the Smithy rules-engine standard library:
+https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+from urllib.parse import quote, urlsplit
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """Resolved endpoint returned by ``resolve()``.
+
+    Mirrors the rules-engine *Endpoint object*: a ``url`` plus optional
+    ``properties`` (arbitrary document values) and ``headers`` (multi-value
+    map of header name to list of values).
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/specification.html#endpoint-object
+    """
+
+    url: str
+    properties: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, list[str]] = field(default_factory=dict)
+
+
+class EndpointError(Exception):
+    """Raised when no endpoint rule matches or an ``error`` rule fires.
+
+    Corresponds to the rules-engine *error rule*: terminates evaluation
+    with a diagnostic message produced by the rule set.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/specification.html#error-rule
+    """
+
+
+_PLACEHOLDER = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)(?:#([A-Za-z0-9_.\[\]]+))?\}")
+
+
+def interpolate(template: str, params: object, locals_: dict[str, Any]) -> str:
+    """Expand a rules-engine *template string*.
+
+    Substitutes ``{Name}`` and ``{Name#path.subpath}`` references inside
+    ``template``. Names resolve against ``locals_`` first (variables bound
+    by ``assign`` conditions), then against ``params`` attributes (any
+    object with attribute access — a dataclass, plain class, etc.; not a
+    dict).
+    ``#path`` segments walk the resolved value via :func:`get_attr`.
+
+    Raises :class:`EndpointError` if a referenced name resolves to ``None``.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/specification.html#template-strings
+    """
+
+    def replace(match: re.Match[str]) -> str:
+        name, path = match.group(1), match.group(2)
+
+        if name in locals_:
+            value = locals_[name]
+        elif hasattr(params, name):
+            value = getattr(params, name)
+        else:
+            raise EndpointError(f"interpolate: unknown reference '{name}'")
+
+        if value is None:
+            raise EndpointError(f"interpolate: '{name}' is None")
+
+        if path:
+            value = get_attr(value, path)
+
+        if value is None:
+            raise EndpointError(f"interpolate: '{name}#{path}' is None")
+
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        return str(value)
+
+    return _PLACEHOLDER.sub(replace, template)
+
+
+_SEGMENT_RE = re.compile(r"([A-Za-z_][A-Za-z0-9_]*|\[-?\d+\])")
+
+
+def get_attr(value: Mapping[str, object] | list[str], path: str) -> object:
+    """Rules-engine ``getAttr`` — index into a value by a dotted/bracketed path.
+
+    Walks segments like ``a.b[0].c`` against dicts (key lookup), objects
+    (attribute lookup), and indexable sequences (integer index). Any missing
+    key, missing attribute, out-of-range index, or non-indexable cursor
+    short-circuits to ``None``.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#getattr-function
+    """
+    cursor: object = value
+    for segment in _SEGMENT_RE.findall(path):
+        if cursor is None:
+            return None
+
+        if segment.startswith("["):
+            # Array index
+            idx = int(segment[1:-1])
+            try:
+                cursor = cursor[idx]  # type: ignore
+            except IndexError:
+                return None
+            except TypeError:
+                return None
+            except KeyError:
+                return None
+        else:
+            # Field access
+            if isinstance(cursor, dict):
+                cursor = cursor.get(segment)
+            else:
+                cursor = getattr(cursor, segment, None)
+
+    return cursor
+
+
+def string_equals(a: Any, b: Any) -> bool:
+    """Rules-engine ``stringEquals`` — strict string equality.
+
+    Both operands must be Python ``str``; any non-str comparand returns
+    ``False``.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#stringequals-function
+    """
+    return isinstance(a, str) and isinstance(b, str) and a == b
+
+
+_HOST_LABEL = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$")
+
+
+def substring(value: Any, start: int, stop: int, reverse: bool) -> str | None:
+    """Rules-engine ``substring`` — slice an ASCII string by ``[start, stop)``.
+
+    Returns ``None`` when ``value`` is not a string, contains non-ASCII
+    code points, or the ``start``/``stop`` indices are negative, equal,
+    inverted, or past the end. When ``reverse`` is true, indices count
+    from the end of the string toward the start.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#substring-function
+    """
+    if not isinstance(value, str):
+        return None
+    if not value.isascii():
+        return None
+    if start < 0 or stop < 0 or start >= stop:
+        return None
+    if stop > len(value):
+        return None
+    if reverse:
+        n = len(value)
+        return value[n - stop : n - start]
+    return value[start:stop]
+
+
+def is_valid_host_label(value: Any, allow_subdomains: bool) -> bool:
+    """Rules-engine ``isValidHostLabel`` — validate an RFC 1123 host label.
+
+    A label is 1–63 chars of ``[A-Za-z0-9-]`` that does not start or end
+    with a hyphen. When ``allow_subdomains`` is true, ``value`` may be a
+    dot-separated sequence of such labels (every label must be valid).
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#isvalidhostlabel-function
+    """
+    if not isinstance(value, str) or not value:
+        return False
+    if allow_subdomains:
+        labels = value.split(".")
+        return bool(labels) and all(_HOST_LABEL.match(label) for label in labels)
+    return _HOST_LABEL.match(value) is not None
+
+
+def uri_encode(value: str | None) -> str:
+    """Rules-engine ``uriEncode`` — percent-encode per RFC 3986 §2.3.
+
+    Every character outside the unreserved set ``A-Z a-z 0-9 - _ . ~`` is
+    percent-encoded, including ``/``. Non-string input yields ``""``.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#uriencode-function
+    """
+    if value is None:
+        return ""
+    return quote(value, safe="-_.~")
+
+
+class ParsedUrl(TypedDict):
+    scheme: str
+    authority: str
+    path: str
+    normalizedPath: str
+    isIp: bool
+
+
+def parse_url(value: str) -> ParsedUrl | None:
+    """Rules-engine ``parseUrl`` — split an HTTP(S) URL into components.
+
+    Returns a :class:`ParsedUrl` with ``scheme``, ``authority`` (host plus
+    optional ``:port``), ``path``, ``normalizedPath`` (``path`` guaranteed
+    to end in ``/``), and ``isIp`` (true for IPv4 dotted-quad or IPv6
+    hosts). Returns ``None`` when ``value`` is not a string, the scheme is
+    not ``http``/``https``, or a query/fragment is present.
+
+    Reference:
+        https://smithy.io/2.0/additional-specs/rules-engine/standard-library.html#parseurl-function
+    """
+
+    try:
+        parts = urlsplit(value)
+
+        if parts.scheme not in ("http", "https"):
+            return None
+
+        # Smithy parseUrl rejects query strings and fragments.
+        if parts.query or parts.fragment:
+            return None
+
+        # urlsplit preserves the raw/encoded path.
+        path = parts.path
+
+        normalized_path = path if path.endswith("/") else f"{path}/"
+
+        return {
+            "scheme": parts.scheme,
+            "authority": parts.netloc,
+            "path": path,
+            "normalizedPath": normalized_path,
+            "isIp": _looks_like_ip(parts.hostname or ""),
+        }
+
+    except Exception:
+        return None
+
+
+def _looks_like_ip(host: str) -> bool:
+    if not host:
+        return False
+    if ":" in host:  # IPv6 (urlsplit strips brackets from hostname)
+        return True
+    parts = host.split(".")
+    return len(parts) == 4 and all(p.isdigit() for p in parts)
+
+
+class ParsedArn(TypedDict):
+    partition: str
+    service: str
+    region: str
+    accountId: str
+    resourceId: list[str]
+
+
+def aws_parse_arn(arn: Any) -> ParsedArn | None:
+    """AWS rules-engine ``aws.parseArn`` — split an ARN into components.
+
+    An ARN has the shape ``arn:<partition>:<service>:<region>:<account>:<resource>``.
+    Returns a :class:`ParsedArn` with ``partition``, ``service``, ``region``,
+    ``accountId``, and ``resourceId`` (the trailing resource section split
+    on ``:`` and ``/``). Returns ``None`` when ``arn`` is not a string, has
+    fewer than six ``:``-separated parts, does not begin with ``arn``, or
+    has empty ``partition``/``service``/resource sections. ``region`` and
+    ``accountId`` may be empty (e.g. IAM ARNs have no region).
+
+    Reference:
+        https://smithy.io/2.0/aws/rules-engine/standard-library.html#aws-parsearn-function
+    """
+    if not isinstance(arn, str):
+        return None
+    parts = arn.split(":", 5)
+    if len(parts) != 6:
+        return None
+    prefix, partition, service, region, account_id, resource = parts
+    if prefix != "arn" or not partition or not service or not resource:
+        return None
+    return {
+        "partition": partition,
+        "service": service,
+        "region": region,
+        "accountId": account_id,
+        "resourceId": re.split(r"[:/]", resource),
+    }
+
+
+_S3_BUCKET_LABEL = re.compile(r"^[a-z0-9][a-z0-9\-]{1,61}[a-z0-9]$")
+_IPV4 = re.compile(r"^(\d{1,3}\.){3}\d{1,3}$")
+
+
+def aws_is_virtual_hostable_s3_bucket(value: Any, allow_subdomains: Any) -> bool:
+    """AWS rules-engine ``aws.isVirtualHostableS3Bucket`` — validate an S3
+    bucket name for virtual-hosted-style addressing.
+
+    Returns ``True`` when ``value`` is a DNS-compliant S3 bucket name
+    (3–63 chars, lowercase alphanumeric plus hyphens, no leading/trailing
+    hyphen, no IPv4-address shape). When ``allow_subdomains`` is true,
+    dotted bucket names are accepted and each dot-separated label must
+    independently satisfy the same rules.
+
+    Reference:
+        https://smithy.io/2.0/aws/rules-engine/standard-library.html#aws-isvirtualhostables3bucket-function
+    """
+    if not isinstance(value, str):
+        return False
+    if allow_subdomains:
+        labels = value.split(".")
+        return all(aws_is_virtual_hostable_s3_bucket(label, False) for label in labels)
+    if _IPV4.match(value):
+        return False
+    return _S3_BUCKET_LABEL.match(value) is not None
+
+
+def apply_label(url: str, placeholder: str, value: str) -> str:
+    """Substitute ``placeholder`` in ``url`` with ``value`` — except when the
+    rule engine has already embedded ``value`` as a whole host label or path
+    segment. In that case, strip the placeholder and collapse any resulting
+    ``//`` or trailing ``/`` in the path.
+
+    "Part" = host label (split on ``.``) or path segment (split on ``/``).
+    Match is case-sensitive, whole-part only. An empty ``value`` always
+    substitutes (never matches).
+    """
+    if placeholder not in url:
+        return url
+
+    if not value:
+        return url.replace(placeholder, "")
+
+    try:
+        parsed = urlsplit(url)
+        # urlsplit.hostname lowercases the value, which would break the
+        # case-sensitive membership test below.  Extract from netloc manually
+        # to preserve the original casing.
+        netloc = parsed.netloc or ""
+        host = (
+            netloc.rsplit(":", 1)[0]
+            if ":" in netloc and not netloc.startswith("[")
+            else netloc
+        )
+        path = parsed.path or ""
+    except Exception:
+        # Parse failure -> fall back to substitution (defensive).
+        return url.replace(placeholder, quote(value, safe=""))
+
+    host_labels = host.split(".") if host and not host.startswith("[") else []
+    path_segments = [seg for seg in path.split("/") if seg]
+
+    # Guard: only strip when the placeholder is in the path portion. If the
+    # placeholder appears only in a query string or fragment, a coincidental
+    # host/path match must not trigger the strip branch.
+    scheme_sep = url.find("://")
+    head_end = url.find("/", scheme_sep + 3) if scheme_sep != -1 else -1
+    path_portion = url[head_end:] if head_end != -1 else ""
+    # Strip query and fragment off the path portion for the placeholder check.
+    for sep in ("?", "#"):
+        idx = path_portion.find(sep)
+        if idx != -1:
+            path_portion = path_portion[:idx]
+    if placeholder not in path_portion:
+        return url.replace(placeholder, quote(value, safe=""))
+
+    if value in host_labels or value in path_segments:
+        # Splice the placeholder out, then collapse the one seam slash our
+        # removal may have created. Pre-existing slash duplicates in the
+        # URI template are not our concern — we only fix what we caused.
+        idx = url.find(placeholder)
+        stripped = url[:idx] + url[idx + len(placeholder) :]
+        before = stripped[idx - 1] if idx > 0 else ""
+        after = stripped[idx] if idx < len(stripped) else ""
+        if before == "/" and after == "/":
+            stripped = stripped[:idx] + stripped[idx + 1 :]
+        # Placeholder at the path's tail leaves a stray trailing ``/``.
+        if stripped.endswith("/"):
+            stripped = stripped[:-1]
+        return stripped
+
+    return url.replace(placeholder, quote(value, safe=""))

capo_lambda/_services/_aws_config.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import configparser
+import functools
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeVar
+
+from capo_lambda._services._pipeline import (
+    AsyncInterceptor,
+    AsyncNextFn,
+    AsyncOperationRequest,
+    AsyncOperationResponse,
+    Interceptor,
+    NextFn,
+    OperationRequest,
+    OperationResponse,
+)
+
+ENDPOINT_ENV_VAR = "AWS_ENDPOINT_URL_LAMBDA"
+SERVICE_ID = "lambda"
+TInput = TypeVar("TInput")
+TOutput = TypeVar("TOutput")
+
+
+@dataclass(frozen=True)
+class AwsSettings:
+    region: str | None
+    endpoint: str | None
+    use_fips: bool
+    use_dual_stack: bool
+    max_attempts: int
+
+
+def _env_bool(name: str) -> bool | None:
+    val = os.environ.get(name)
+    if val is None:
+        return None
+    return val.strip().lower() in ("true", "1")
+
+
+def _profile_bool(section: dict[str, str], key: str) -> bool | None:
+    val = section.get(key)
+    if val is None:
+        return None
+    return val.strip().lower() in ("true", "1")
+
+
+def _load_profile() -> tuple[dict[str, str], dict[str, dict[str, str]]]:
+    profile = (
+        os.environ.get("AWS_PROFILE")
+        or os.environ.get("AWS_DEFAULT_PROFILE")
+        or "default"
+    )
+    raw_cfg = os.environ.get("AWS_CONFIG_FILE")
+    cfg_file = (
+        Path(raw_cfg).expanduser() if raw_cfg else Path.home() / ".aws" / "config"
+    )
+    merged: dict[str, str] = {}
+    services: dict[str, dict[str, str]] = {}
+    if cfg_file.is_file():
+        cfg = configparser.ConfigParser(interpolation=None)
+        cfg.read(cfg_file)
+        key = "default" if profile == "default" else f"profile {profile}"
+        if cfg.has_section(key):
+            merged.update(dict(cfg.items(key)))
+        services_name = merged.get("services")
+        if services_name and cfg.has_section(f"services {services_name}"):
+            raw = dict(cfg.items(f"services {services_name}"))
+            for svc, block in raw.items():
+                parsed: dict[str, str] = {}
+                for line in block.splitlines():
+                    stripped = line.strip()
+                    if "=" in stripped:
+                        k, _, val = stripped.partition("=")
+                        parsed[k.strip()] = val.strip()
+                services[svc] = parsed
+    return merged, services
+
+
+@functools.cache
+def load_aws_settings() -> AwsSettings:
+    profile, services = _load_profile()
+    region = os.environ.get("AWS_REGION") or profile.get("region")
+    endpoint = (
+        os.environ.get(ENDPOINT_ENV_VAR)
+        or os.environ.get("AWS_ENDPOINT_URL")
+        or services.get(SERVICE_ID, {}).get("endpoint_url")
+        or profile.get("endpoint_url")
+    )
+    use_fips: bool | None = _env_bool("AWS_USE_FIPS_ENDPOINT")
+    if use_fips is None:
+        use_fips = _profile_bool(profile, "use_fips_endpoint")
+    if use_fips is None:
+        use_fips = False
+    use_dual_stack: bool | None = _env_bool("AWS_USE_DUALSTACK_ENDPOINT")
+    if use_dual_stack is None:
+        use_dual_stack = _profile_bool(profile, "use_dualstack_endpoint")
+    if use_dual_stack is None:
+        use_dual_stack = False
+    max_attempts_raw = os.environ.get("AWS_MAX_ATTEMPTS") or profile.get("max_attempts")
+    max_attempts = int(max_attempts_raw) if max_attempts_raw else 3
+    return AwsSettings(
+        region=region,
+        endpoint=endpoint,
+        use_fips=use_fips,
+        use_dual_stack=use_dual_stack,
+        max_attempts=max_attempts,
+    )
+
+
+def aws_config() -> Interceptor[TInput, TOutput]:
+    def interceptor(
+        request: OperationRequest[TInput], next: NextFn[TInput, TOutput]
+    ) -> OperationResponse[TOutput]:
+        settings = load_aws_settings()
+        options = request.options
+        if options.region is None:
+            options.region = settings.region
+        if options.endpoint is None:
+            options.endpoint = settings.endpoint
+        if options.use_fips is None:
+            options.use_fips = settings.use_fips
+        if options.use_dual_stack is None:
+            options.use_dual_stack = settings.use_dual_stack
+        if options.retry_max_attempts is None:
+            options.retry_max_attempts = settings.max_attempts
+        return next(request)
+
+    return interceptor
+
+
+def aaws_config() -> AsyncInterceptor[TInput, TOutput]:
+    async def interceptor(
+        request: AsyncOperationRequest[TInput], next: AsyncNextFn[TInput, TOutput]
+    ) -> AsyncOperationResponse[TOutput]:
+        settings = load_aws_settings()
+        options = request.options
+        if options.region is None:
+            options.region = settings.region
+        if options.endpoint is None:
+            options.endpoint = settings.endpoint
+        if options.use_fips is None:
+            options.use_fips = settings.use_fips
+        if options.use_dual_stack is None:
+            options.use_dual_stack = settings.use_dual_stack
+        if options.retry_max_attempts is None:
+            options.retry_max_attempts = settings.max_attempts
+        return await next(request)
+
+    return interceptor