microburst 0.1.0__py3-none-any.whl

microburst/__init__.py

@@ -0,0 +1,3 @@
+"""microburst — AWS failure injection proxy."""
+
+__version__ = "0.1.0"

microburst/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from microburst.cli import main
+
+sys.exit(main())

microburst/cli.py

@@ -0,0 +1,87 @@
+"""microburst CLI."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from aiohttp import web
+
+from microburst.proxy import Microburst, load_config, make_app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="microburst",
+        description="AWS failure injection proxy — inject realistic AWS "
+        "errors, latency, and connection faults between your app and any "
+        "AWS endpoint (MiniStack, moto, LocalStack, or real AWS).",
+    )
+    parser.add_argument(
+        "--upstream", "-u", default=None,
+        help="upstream AWS endpoint (default: config file or http://localhost:4566)",
+    )
+    parser.add_argument(
+        "--port", "-p", type=int, default=None,
+        help="listen port (default: 9999)",
+    )
+    parser.add_argument(
+        "--host", default=None, help="listen host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--config", "-c", default=None,
+        help="YAML config file (upstream, port, rules)",
+    )
+    parser.add_argument(
+        "--resign", action="store_true", default=None,
+        help="re-sign requests with AWS_* env credentials (auto for "
+        "amazonaws.com upstreams)",
+    )
+    parser.add_argument(
+        "--no-resign", action="store_true",
+        help="never re-sign, even for amazonaws.com upstreams",
+    )
+    parser.add_argument(
+        "--verbose", "-v", action="store_true", help="debug logging",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+    config = {}
+    if args.config:
+        config = load_config(args.config)
+
+    upstream = args.upstream or config.get("upstream") or "http://localhost:4566"
+    port = args.port or config.get("port") or 9999
+    host = args.host or config.get("host") or "127.0.0.1"
+    rules = config.get("rules") or []
+
+    if args.no_resign:
+        resign = False
+    elif args.resign:
+        resign = True
+    else:
+        resign = None  # auto
+
+    microburst = Microburst(upstream, rules=rules, resign=resign)
+    app = make_app(microburst)
+
+    print(f"microburst listening on http://{host}:{port} → {upstream}", flush=True)
+    print(f"control API: http://{host}:{port}/_microburst/health", flush=True)
+    print(f"point your app: AWS_ENDPOINT_URL=http://{host}:{port}", flush=True)
+
+    web.run_app(app, host=host, port=port, print=None)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

microburst/detect.py

@@ -0,0 +1,208 @@
+"""Request detection: resolve (service, operation, region, resource) from an
+incoming AWS API request.
+
+Mirrors how AWS itself — and MiniStack's router — identify a request:
+SigV4 credential scope names the service and region; ``X-Amz-Target`` or the
+query-protocol ``Action`` parameter names the operation; REST services are
+matched on method + requestUri patterns from the botocore service model.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from urllib.parse import parse_qsl
+
+from microburst.models import get_protocol, get_service_model, service_for_scope
+
+_CRED_RE = re.compile(
+    r"Credential=(?P<key>[^/,]+)/(?P<date>\d{8})/(?P<region>[^/]+)/"
+    r"(?P<service>[^/]+)/aws4_request"
+)
+
+# Operations that carry large payloads in either direction. For these the body
+# is streamed through untouched — detection never needs them.
+_STREAMING_OPS = {
+    ("s3", "PutObject"),
+    ("s3", "GetObject"),
+    ("s3", "UploadPart"),
+    ("lambda", "Invoke"),  # response payloads can be large; body still small
+}
+
+
+@dataclass
+class RequestInfo:
+    service: str | None
+    operation: str | None
+    region: str | None
+    resource: str | None
+    access_key: str | None = None
+
+
+def _parse_credential_scope(headers) -> tuple[str | None, str | None, str | None]:
+    auth = headers.get("Authorization", "")
+    match = _CRED_RE.search(auth)
+    if not match:
+        return None, None, None
+    return (
+        service_for_scope(match.group("service")),
+        match.group("region"),
+        match.group("key"),
+    )
+
+
+_REST_OP_CACHE: dict[str, list[dict]] = {}
+
+
+def _uri_to_regex(uri: str) -> re.Pattern:
+    """Convert a Smithy requestUri (``/x/{Label}/{Greedy+}``) to a regex."""
+    out = ""
+    i = 0
+    for match in re.finditer(r"\{[A-Za-z0-9_]+\+?\}", uri):
+        out += re.escape(uri[i:match.start()])
+        out += ".*" if match.group().endswith("+}") else "[^/]+"
+        i = match.end()
+    out += re.escape(uri[i:])
+    return re.compile(f"^{out}$")
+
+
+def _rest_operations(service: str) -> list[dict]:
+    """Compile candidate operations for a REST-protocol service.
+
+    Several operations share the same method+path (S3 ``PutObject`` vs
+    ``CopyObject``); disambiguation happens at match time via query-string
+    markers and headers declared in the service model.
+    """
+    if service in _REST_OP_CACHE:
+        return _REST_OP_CACHE[service]
+    entries: list[dict] = []
+    model = get_service_model(service)
+    if model is not None:
+        for op_name in model.operation_names:
+            op = model.operation_model(op_name)
+            http = op.http
+            uri = http.get("requestUri", "/")
+            path_uri, _, literal_query = uri.partition("?")
+            query_markers = {
+                part.split("=", 1)[0] for part in literal_query.split("&") if part
+            }
+            required_headers = set()
+            input_shape = getattr(op, "input_shape", None)
+            if input_shape is not None:
+                for name, member in input_shape.members.items():
+                    if (
+                        member.serialization.get("location") == "header"
+                        and name in input_shape.required_members
+                    ):
+                        required_headers.add(
+                            member.serialization.get("locationName", name).lower()
+                        )
+            entries.append(
+                {
+                    "method": http.get("method", "GET"),
+                    "regex": _uri_to_regex(path_uri),
+                    "op": op_name,
+                    "query_markers": query_markers,
+                    "required_headers": required_headers,
+                }
+            )
+    _REST_OP_CACHE[service] = entries
+    return entries
+
+
+def _match_rest_operation(service: str, method: str, path: str, query,
+                          headers) -> str | None:
+    candidates = []
+    for entry in _rest_operations(service):
+        if entry["method"] != method or not entry["regex"].match(path):
+            continue
+        score = 0
+        if entry["query_markers"]:
+            if entry["query_markers"] <= set(query):
+                score += 2 * len(entry["query_markers"])
+            else:
+                score -= 10
+        lower_headers = {k.lower() for k in headers}
+        for h in entry["required_headers"]:
+            score += 2 if h in lower_headers else -10
+        candidates.append((score, entry["op"]))
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: item[0], reverse=True)
+    return candidates[0][1]
+
+
+def _operation_for(service: str | None, headers, method: str, path: str,
+                   query: dict, body: bytes | None) -> str | None:
+    if service is None:
+        return None
+
+    target = headers.get("X-Amz-Target", "")
+    if "." in target:
+        return target.rsplit(".", 1)[-1]
+
+    # Query-protocol style `Action` — some services migrated models to `json`
+    # but clients may still speak query; check both query string and body.
+    action = query.get("Action")
+    if action:
+        return action
+    if body and b"Action=" in body:
+        params = dict(parse_qsl(body.decode("utf-8", "replace")))
+        action = params.get("Action")
+        if action:
+            return action
+
+    protocol = get_protocol(service)
+    if protocol in ("rest-xml", "rest-json"):
+        return _match_rest_operation(service, method, path, query, headers)
+
+    return None
+
+
+def _resource_hint(service: str | None, operation: str | None, path: str,
+                   body: bytes | None) -> str | None:
+    if service is None:
+        return None
+    if service == "s3":
+        segments = [s for s in path.split("/") if s]
+        return segments[0] if segments else None
+    if body:
+        if service == "sqs":
+            segments = [s for s in path.split("/") if s]
+            return segments[-1] if segments else None
+        try:
+            payload = json.loads(body)
+        except (ValueError, UnicodeDecodeError):
+            return None
+        if service == "dynamodb":
+            return payload.get("TableName")
+        for key in ("TopicArn", "TargetArn", "QueueUrl", "FunctionName",
+                    "Name", "StackName", "Bucket"):
+            if isinstance(payload.get(key), str):
+                return payload[key].rsplit(":", 1)[-1].rsplit("/", 1)[-1]
+    return None
+
+
+def should_buffer(service: str | None, operation: str | None,
+                  content_length: int | None) -> bool:
+    """Whether the body is needed for detection/rule matching."""
+    if (service, operation) in _STREAMING_OPS:
+        return False
+    if content_length is None:
+        return True
+    return content_length <= 4 * 1024 * 1024
+
+
+def detect(headers, method: str, path: str, query: dict,
+           body: bytes | None) -> RequestInfo:
+    service, region, access_key = _parse_credential_scope(headers)
+    operation = _operation_for(service, headers, method, path, query, body)
+    resource = _resource_hint(service, operation, path, body)
+    return RequestInfo(
+        service=service,
+        operation=operation,
+        region=region,
+        resource=resource,
+        access_key=access_key,
+    )

microburst/errors.py

@@ -0,0 +1,102 @@
+"""Error serialization per AWS wire protocol.
+
+The SDKs classify failures by the *error code parsed from the body* (plus
+status code), not the status alone. To make injected faults exercise the real
+retry machinery — throttling backoff, adaptive rate limiting, modeled
+retryable exceptions — the body must be shaped the way the service actually
+shapes it.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from xml.sax.saxutils import escape
+
+from microburst.models import error_http_status, get_protocol
+
+
+def _request_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _json_body(code: str, message: str) -> bytes:
+    return json.dumps({"__type": code, "message": message}).encode()
+
+
+def render_error(
+    service: str | None,
+    code: str,
+    message: str = "",
+    status: int | None = None,
+) -> tuple[int, dict[str, str], bytes]:
+    """Serialize an AWS-looking error. Returns (status, headers, body)."""
+    protocol = get_protocol(service) if service else None
+    if status is None:
+        if service is None:
+            status = 503
+        else:
+            # json/query services conventionally serve client faults at 400;
+            # rest protocols lean on 5xx for transient errors.
+            default = 400 if protocol in ("json", "query", "ec2") else 503
+            status = error_http_status(service, code, default=default)
+    if not message:
+        message = code
+
+    rid = _request_id()
+
+    if protocol == "json":
+        headers = {
+            "Content-Type": "application/x-amz-json-1.0",
+            "x-amzn-RequestId": rid,
+            "x-amzn-ErrorType": code,
+        }
+        return status, headers, _json_body(code, message)
+
+    if protocol in ("query", "ec2"):
+        headers = {
+            "Content-Type": "text/xml",
+            "x-amzn-RequestId": rid,
+        }
+        body = (
+            "<ErrorResponse>"
+            "<Error>"
+            f"<Code>{escape(code)}</Code>"
+            f"<Message>{escape(message)}</Message>"
+            "<Type>Sender</Type>"
+            "</Error>"
+            f"<RequestId>{rid}</RequestId>"
+            "</ErrorResponse>"
+        )
+        return status, headers, body.encode()
+
+    if protocol == "rest-xml":
+        headers = {
+            "Content-Type": "application/xml",
+            "x-amz-request-id": rid,
+            "x-amz-id-2": uuid.uuid4().hex * 2,
+        }
+        body = (
+            "<Error>"
+            f"<Code>{escape(code)}</Code>"
+            f"<Message>{escape(message)}</Message>"
+            f"<RequestId>{rid}</RequestId>"
+            "</Error>"
+        )
+        return status, headers, body.encode()
+
+    if protocol == "rest-json":
+        headers = {
+            "Content-Type": "application/json",
+            "x-amzn-RequestId": rid,
+            "x-amzn-errortype": code,
+        }
+        return status, headers, json.dumps({"message": message}).encode()
+
+    # Unknown service/protocol: closest AWS-looking generic envelope.
+    headers = {
+        "Content-Type": "application/x-amz-json-1.0",
+        "x-amzn-RequestId": rid,
+        "x-amzn-ErrorType": code,
+    }
+    return status, headers, _json_body(code, message)

microburst/models.py

@@ -0,0 +1,174 @@
+"""Service model access via botocore.
+
+Wraps botocore's loader to resolve AWS service models (protocol, operations,
+error shapes) by the names requests actually carry: SigV4 credential scope and
+endpoint prefixes. Everything is lazy and cached.
+"""
+
+from __future__ import annotations
+
+import botocore.session
+
+# SigV4 credential scopes that differ from the botocore service name.
+_SCOPE_ALIASES = {
+    "monitoring": "cloudwatch",
+    "email": "ses",
+    "iotdata": "iot-data",
+    "iot-jobs-data": "iot-jobs-data",
+    "iotwireless": "iotwireless",
+    "elasticfilesystem": "elasticfilesystem",
+    "api.ecr": "ecr",
+    "aoss": "opensearchserverless",
+    "cloudfront-keyvaluestore": "cloudfront-keyvaluestore",
+    "cognito-idp": "cognito-idp",
+    "cognito-identity": "cognito-identity",
+}
+
+_session = botocore.session.get_session()
+_model_cache: dict[str, object] = {}
+
+
+def service_for_scope(scope: str) -> str:
+    """Map a SigV4 credential scope to a botocore service name."""
+    return _SCOPE_ALIASES.get(scope, scope)
+
+
+def get_service_model(service: str):
+    """Return the botocore ServiceModel for a service name, or None."""
+    if service in _model_cache:
+        return _model_cache[service]
+    try:
+        model = _session.get_service_model(service)
+    except Exception:  # noqa: BLE001 — unknown service names / broken data loaders
+        model = None
+    _model_cache[service] = model
+    return model
+
+
+def get_protocol(service: str) -> str | None:
+    model = get_service_model(service)
+    if model is None:
+        return None
+    return model.protocol
+
+
+def error_shape(service: str, code: str):
+    """Find the shape for an error code/name in a service model, or None.
+
+    Accepts the bare shape name or a Smithy-style ``prefix#Name``.
+    """
+    model = get_service_model(service)
+    if model is None:
+        return None
+    name = code.rsplit("#", 1)[-1]
+    shape = _shape_or_none(model, name)
+    if shape is not None:
+        return shape
+    for candidate in model.shape_names:
+        if candidate == name or candidate.rsplit("#", 1)[-1] == name:
+            return _shape_or_none(model, candidate)
+    return None
+
+
+def _shape_or_none(model, name: str):
+    try:
+        return model.shape_for(name)
+    except Exception:  # noqa: BLE001 — unmodeled codes raise assorted errors
+        return None
+
+
+# AWS's real status for common codes when the service model doesn't carry an
+# ``httpStatusCode`` trait (most don't). Verified behavior that matters: the
+# SDK's retry decision depends on the status — S3 SlowDown at 400 is treated
+# as a terminal client error, at 503 it retries.
+_KNOWN_STATUS = {
+    # throttling family (botocore's retryable throttled codes)
+    "Throttling": 400,
+    "ThrottlingException": 400,
+    "ThrottledException": 400,
+    "RequestThrottledException": 400,
+    "RequestThrottled": 400,
+    "EC2ThrottledException": 400,
+    "TooManyRequestsException": 429,
+    "ProvisionedThroughputExceededException": 400,
+    "TransactionInProgressException": 400,
+    "RequestLimitExceeded": 503,
+    "BandwidthLimitExceeded": 400,
+    "LimitExceededException": 400,
+    "PriorRequestNotComplete": 400,
+    "SlowDown": 503,
+    # transient server-side
+    "InternalError": 500,
+    "InternalServerError": 500,
+    "InternalFailure": 500,
+    "InternalServiceError": 500,
+    "ServiceUnavailable": 503,
+    "ServiceUnavailableException": 503,
+    "ServiceUnavailableError": 503,
+    "RequestTimeout": 408,
+    "RequestTimeoutException": 408,
+    # common terminal errors — keep these non-retryable
+    "AccessDeniedException": 403,
+    "AccessDenied": 403,
+    "InvalidAccessKeyId": 403,
+    "SignatureDoesNotMatch": 403,
+    "ExpiredTokenException": 400,
+    "UnauthorizedException": 401,
+    "NotAuthorizedException": 400,
+    "ValidationException": 400,
+    "ValidationError": 400,
+    "InvalidParameterValue": 400,
+    "InvalidParameterException": 400,
+    "InvalidParameterValueException": 400,
+    "MissingParameter": 400,
+    "NoSuchBucket": 404,
+    "NoSuchKey": 404,
+    "NotFound": 404,
+    "NotFoundException": 404,
+    "ResourceNotFoundException": 404,
+    "ResourceNotFound": 404,
+    "ResourceInUseException": 400,
+    "ResourceAlreadyExistsException": 400,
+    "ConditionalCheckFailedException": 400,
+    "InvalidClientTokenId": 403,
+}
+
+
+def _modeled_status(service: str, name: str) -> int | None:
+    """httpStatusCode from the raw service model, when modeled."""
+    try:
+        loader = _session.get_component("data_loader")
+        model = loader.load_service_model(service, "service-2")
+        shape = model.get("shapes", {}).get(name)
+        if shape:
+            status = shape.get("error", {}).get("httpStatusCode")
+            return status if isinstance(status, int) else None
+    except Exception:  # noqa: BLE001 — service model may be absent/partial
+        return None
+    return None
+
+
+def error_http_status(service: str, code: str, default: int = 503) -> int:
+    """HTTP status for an error code.
+
+    Order: modeled ``httpStatusCode`` (rare but authoritative when present) →
+    curated AWS-observed map → ``default`` (callers pick per protocol; AWS
+    json/query services conventionally serve client errors at 400).
+    """
+    name = code.rsplit("#", 1)[-1]
+    status = _modeled_status(service, name)
+    if status is not None:
+        return status
+    return _KNOWN_STATUS.get(name, default)
+
+
+def operation_error_names(service: str, operation: str) -> list[str]:
+    """Error shape names modeled for an operation (for plausible sampling)."""
+    model = get_service_model(service)
+    if model is None:
+        return []
+    try:
+        op = model.operation_model(operation)
+    except Exception:  # noqa: BLE001 — OperationNotFoundError and friends
+        return []
+    return [shape.name for shape in op.error_shapes]