api-foundry-query-engine 0.8.39__py3-none-any.whl

api_foundry_query_engine/utils/gateway_operation.py

@@ -0,0 +1,279 @@
+"""
+Gateway Operation Decorator for Lambda Functions
+
+This decorator handles the marshalling and unmarshalling of API Gateway events
+into Operation objects, similar to what GatewayAdapter does but as a decorator.
+It extracts the operation details and adds them to the event for downstream processing.
+"""
+
+import functools
+import json
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Callable
+
+from api_foundry_query_engine.operation import Operation
+from api_foundry_query_engine.utils.app_exception import ApplicationException
+
+log = logging.getLogger(__name__)
+
+
+def gateway_operation(validate_scopes: bool = True, auto_marshal_response: bool = True):
+    """
+    Decorator to handle API Gateway event marshalling and unmarshalling.
+
+    This decorator:
+    1. Unmarshals API Gateway events into Operation objects
+    2. Adds the Operation to the event for downstream processing
+    3. Validates OAuth scopes based on the operation
+    4. Marshals response data back to API Gateway format
+
+    Args:
+        validate_scopes: Whether to validate OAuth scopes (default: True)
+        auto_marshal_response: Whether to automatically format response (default: True)
+
+    Returns:
+        Decorated function that processes API Gateway events
+
+    Example:
+        @token_decoder()
+        @claims_check()
+        @gateway_operation()
+        def handler(event, context):
+            # event now contains 'operation' key with Operation object
+            operation = event['operation']
+            return {"data": [{"id": 1, "name": "Test"}]}
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(event: Dict[str, Any], context: Any) -> Dict[str, Any]:
+            try:
+                log.debug("Gateway operation decorator starting")
+
+                # Unmarshal API Gateway event into Operation
+                operation = _unmarshal_gateway_event(event, validate_scopes)
+
+                # Add operation to event for downstream processing
+                event["operation"] = operation
+
+                log.debug(
+                    "Created operation: entity=%s, action=%s",
+                    operation.entity,
+                    operation.action,
+                )
+
+                # Execute the original function
+                result = func(event, context)
+
+                # Auto-marshal response if requested
+                if auto_marshal_response and isinstance(result, (list, dict)):
+                    return _marshal_response(result)
+                else:
+                    return result
+
+            except ApplicationException:
+                raise
+            except Exception as e:
+                log.error("Gateway operation error: %s", str(e))
+                raise ApplicationException(
+                    status_code=500,
+                    message="Internal server error during operation processing",
+                )
+
+        return wrapper
+
+    return decorator
+
+
+def _unmarshal_gateway_event(event: Dict[str, Any], validate_scopes: bool) -> Operation:
+    """
+    Unmarshal API Gateway event into Operation object.
+
+    This replicates the logic from GatewayAdapter.unmarshal() method.
+    """
+    # Extract entity from resource path
+    resource = event.get("resource")
+    if resource is not None and "/" in resource:
+        parts = resource.split("/")
+        entity = parts[1] if len(parts) > 1 else None
+    else:
+        entity = None
+
+    # Map HTTP method to action
+    method = str(event.get("httpMethod", "")).upper()
+    actions_map = {
+        "GET": "read",
+        "POST": "create",
+        "PUT": "update",
+        "DELETE": "delete",
+    }
+    action = actions_map.get(method, "read")
+
+    # Collect parameters from path and query string
+    event_params = {}
+
+    path_parameters = _convert_parameters(event.get("pathParameters"))
+    if path_parameters is not None:
+        event_params.update(path_parameters)
+
+    query_string_parameters = _convert_parameters(event.get("queryStringParameters"))
+    if query_string_parameters is not None:
+        event_params.update(query_string_parameters)
+
+    query_params, metadata_params = _split_params(event_params)
+
+    # Extract store params from request body
+    store_params = {}
+    body = event.get("body")
+    if body is not None and len(body) > 0:
+        store_params = json.loads(body)
+
+    # Extract claims from authorizer context
+    authorizer_info = event.get("requestContext", {}).get("authorizer", {})
+    claims = authorizer_info.get("claims", {})
+    scope_str = claims.get("scope", "")
+
+    # Validate OAuth scopes if requested
+    if validate_scopes and entity and scope_str:
+        _validate_oauth_scopes(method, entity, scope_str)
+
+    return Operation(
+        entity=entity,
+        action=action,
+        store_params=store_params,
+        query_params=query_params,
+        metadata_params=metadata_params,
+        claims=claims,
+    )
+
+
+def _decode_json_array(raw_value: Any) -> List[Any]:
+    """Decode JSON-encoded arrays from OAuth context."""
+    if isinstance(raw_value, str):
+        try:
+            return json.loads(raw_value)
+        except (json.JSONDecodeError, TypeError):
+            return []
+    else:
+        return raw_value if isinstance(raw_value, list) else []
+
+
+def _validate_oauth_scopes(method: str, entity: str, scope_str: str) -> None:
+    """
+    Validate OAuth scopes based on the operation.
+
+    Enforces scope pattern: read|write|delete:<entity>
+    """
+    required_action = {
+        "GET": "read",
+        "POST": "write",
+        "PUT": "write",
+        "PATCH": "write",
+        "DELETE": "delete",
+    }.get(method, "read")
+
+    required_scope = f"{required_action}:{entity}"
+    token_scopes = set(str(scope_str).split())
+
+    def _has_scope(required: str) -> bool:
+        return (
+            required in token_scopes
+            or f"{required_action}:*" in token_scopes
+            or "*" in token_scopes
+            or "*:*" in token_scopes
+        )
+
+    if not _has_scope(required_scope):
+        raise ApplicationException(
+            401, f"insufficient_scope: required_scope={required_scope}"
+        )
+
+
+def _convert_parameters(
+    parameters: Optional[Dict[str, Any]]
+) -> Optional[Dict[str, Any]]:
+    """
+    Convert parameters to appropriate types.
+
+    Tries to convert strings to int, then float, falls back to string.
+    """
+    if parameters is None:
+        return None
+
+    result = {}
+    for parameter, value in parameters.items():
+        try:
+            result[parameter] = int(value)
+        except ValueError:
+            try:
+                result[parameter] = float(value)
+            except ValueError:
+                result[parameter] = value
+    return result
+
+
+def _split_params(parameters: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """
+    Split parameters into query_params and metadata_params.
+
+    Metadata parameters start with '__'.
+    """
+    query_params = {}
+    metadata_params = {}
+
+    for key, value in parameters.items():
+        if key.startswith("__"):
+            metadata_params[key] = value
+        else:
+            query_params[key] = value
+
+    return query_params, metadata_params
+
+
+def _marshal_response(result: Any) -> Dict[str, Any]:
+    """
+    Marshal response data into API Gateway format.
+
+    Args:
+        result: The response data (list or dict)
+
+    Returns:
+        API Gateway compatible response
+    """
+    try:
+        return {
+            "isBase64Encoded": False,
+            "statusCode": 200,
+            "headers": {"Content-Type": "application/json"},
+            "body": json.dumps(result) if result is not None else json.dumps([]),
+        }
+    except (TypeError, ValueError) as e:
+        log.error("Failed to marshal response: %s", e)
+        raise ApplicationException(
+            status_code=500, message="Failed to serialize response data"
+        )
+
+
+# Convenience decorators for specific use cases
+def gateway_read_operation(validate_scopes: bool = True):
+    """Convenience decorator for read operations."""
+    return gateway_operation(
+        validate_scopes=validate_scopes, auto_marshal_response=True
+    )
+
+
+def gateway_write_operation(validate_scopes: bool = True):
+    """Convenience decorator for write operations."""
+    return gateway_operation(
+        validate_scopes=validate_scopes, auto_marshal_response=True
+    )
+
+
+def gateway_operation_no_validation():
+    """Decorator that skips scope validation."""
+    return gateway_operation(validate_scopes=False, auto_marshal_response=True)
+
+
+def gateway_operation_raw_response():
+    """Decorator that doesn't auto-marshal the response."""
+    return gateway_operation(validate_scopes=True, auto_marshal_response=False)

api_foundry_query_engine/utils/logger.py

@@ -0,0 +1,60 @@
+import logging
+import os
+
+# Configuring the logging module with basic settings, including format and log level,
+# where the log level is obtained from the environment variable LOGGING_LEVEL
+# with a default of DEBUG, and force=True to ensure the configuration is applied immediately.
+logging.basicConfig(
+    format="%(name)s:%(lineno)s - %(levelname)s - %(message)s",
+    level=os.getenv("LOGGING_LEVEL", "DEBUG").upper(),
+    force=True,
+)
+
+WARN = logging.WARN
+INFO = logging.INFO
+DEBUG = logging.DEBUG
+
+
+def logger(name=None):
+    """
+    Function to create a logger with a specified name or default name.
+
+    Parameters:
+        name (str): Name of the logger. If not provided, the root logger is returned.
+
+    Returns:
+        logging.Logger: Logger object with the specified name or the root logger.
+
+    """
+    # Retrieving the logging level from the environment variable LOGGING_LEVEL
+    # with a default of DEBUG, and converting it to uppercase
+    loggingLevel = os.getenv("LOGGING_LEVEL", "DEBUG").upper()
+
+    # Setting the logging level for the root logger to the obtained logging level
+    logging.getLogger().setLevel(loggingLevel)
+
+    # Returning a logger object with the specified name or the root logger
+    return logging.getLogger(name)
+
+
+def write_logging_file(file_name, content):
+    """
+    Function to write a given string to a file in the temp/logging folder.
+
+    Parameters:
+        file_name (str): Name of the file to write the content to.
+        content (str): The string content to write to the file.
+
+    """
+    # Define the directory path
+    dir_path = os.path.join("temp", "logging")
+
+    # Ensure the directory exists
+    os.makedirs(dir_path, exist_ok=True)
+
+    # Define the file path
+    file_path = os.path.join(dir_path, file_name)
+
+    # Write the content to the file
+    with open(file_path, "w") as file:
+        file.write(content + "\n")

api_foundry_query_engine/utils/reference_resolver.py

@@ -0,0 +1,222 @@
+"""
+Reference Resolver for Batch Operations
+
+Resolves $ref: placeholders in operation parameters with values from
+previously executed operations.
+"""
+
+import re
+from typing import Dict, Any, List
+from api_foundry_query_engine.utils.app_exception import ApplicationException
+from api_foundry_query_engine.utils.logger import logger
+
+log = logger(__name__)
+
+
+class ReferenceResolver:
+    """Resolves $ref: references to values from completed operations."""
+
+    REF_PATTERN = re.compile(r"\$ref:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_.]+)")
+
+    def __init__(self, results: Dict[str, Dict[str, Any]]):
+        """
+        Initialize the reference resolver.
+
+        Args:
+            results: Dictionary mapping operation IDs to their results
+        """
+        self.results = results
+
+    def resolve_parameters(
+        self, params: Dict[str, Any], operation_id: str = None
+    ) -> Dict[str, Any]:
+        """
+        Resolve all $ref: references in parameters.
+
+        Args:
+            params: Parameter dictionary potentially containing references
+            operation_id: ID of the operation being resolved (for logging)
+
+        Returns:
+            Parameters with all references replaced with actual values
+
+        Raises:
+            ApplicationException: If reference cannot be resolved
+        """
+        if not params:
+            return params
+
+        resolved = {}
+        for key, value in params.items():
+            resolved[key] = self._resolve_value(value, key, operation_id)
+
+        return resolved
+
+    def _resolve_value(
+        self, value: Any, param_name: str = None, operation_id: str = None
+    ) -> Any:
+        """
+        Recursively resolve a parameter value.
+
+        Args:
+            value: The value to resolve
+            param_name: Name of the parameter (for error messages)
+            operation_id: ID of the operation (for error messages)
+
+        Returns:
+            Resolved value
+        """
+        if isinstance(value, str):
+            return self._resolve_string_value(value, param_name, operation_id)
+        elif isinstance(value, dict):
+            return {
+                k: self._resolve_value(v, f"{param_name}.{k}", operation_id)
+                for k, v in value.items()
+            }
+        elif isinstance(value, list):
+            return [
+                self._resolve_value(item, f"{param_name}[{i}]", operation_id)
+                for i, item in enumerate(value)
+            ]
+        else:
+            return value
+
+    def _resolve_string_value(
+        self, value: str, param_name: str = None, operation_id: str = None
+    ) -> Any:
+        """
+        Resolve a string value that may contain $ref: references.
+
+        Supports:
+        - Full replacement: "$ref:op1.customer_id" → 42
+        - Partial replacement: "prefix_$ref:op1.id_suffix" → "prefix_42_suffix"
+
+        Args:
+            value: String value to resolve
+            param_name: Name of the parameter (for error messages)
+            operation_id: ID of the operation (for error messages)
+
+        Returns:
+            Resolved value (may not be string if full replacement)
+        """
+        if not isinstance(value, str) or "$ref:" not in value:
+            return value
+
+        matches = list(self.REF_PATTERN.finditer(value))
+
+        # If entire string is a single reference, return the actual type
+        if len(matches) == 1 and matches[0].group(0) == value:
+            return self._extract_reference(
+                matches[0].group(1), matches[0].group(2), param_name, operation_id
+            )
+
+        # Otherwise, perform string substitution
+        result = value
+        for match in matches:
+            ref_op_id = match.group(1)
+            ref_path = match.group(2)
+            ref_value = self._extract_reference(
+                ref_op_id, ref_path, param_name, operation_id
+            )
+            result = result.replace(match.group(0), str(ref_value))
+
+        return result
+
+    def _extract_reference(
+        self,
+        ref_op_id: str,
+        ref_path: str,
+        param_name: str = None,
+        operation_id: str = None,
+    ) -> Any:
+        """
+        Extract a value from results using operation ID and property path.
+
+        Args:
+            ref_op_id: Referenced operation ID
+            ref_path: Dot-notation path to property (e.g., "customer_id")
+            param_name: Name of the parameter (for error messages)
+            operation_id: ID of the operation (for error messages)
+
+        Returns:
+            The referenced value
+
+        Raises:
+            ApplicationException: If reference cannot be resolved
+        """
+        # Check if referenced operation exists
+        if ref_op_id not in self.results:
+            context = f" in operation '{operation_id}'" if operation_id else ""
+            raise ApplicationException(
+                400,
+                f"Reference to unknown operation '{ref_op_id}'{context}. "
+                f"Ensure operation is defined and appears before this one.",
+            )
+
+        # Check if operation completed successfully
+        op_result = self.results[ref_op_id]
+        if op_result.get("status") != "completed":
+            context = f" in operation '{operation_id}'" if operation_id else ""
+            raise ApplicationException(
+                400,
+                f"Cannot reference operation '{ref_op_id}'{context}: "
+                f"operation {op_result.get('status', 'failed')}",
+            )
+
+        # Navigate to the referenced property
+        data = op_result.get("data", {})
+        path_parts = ref_path.split(".")
+
+        try:
+            value = data
+            for part in path_parts:
+                if isinstance(value, dict):
+                    value = value[part]
+                elif isinstance(value, list):
+                    # Support array indexing: items.0.id
+                    value = value[int(part)]
+                else:
+                    raise KeyError(part)
+            return value
+
+        except (KeyError, IndexError, ValueError) as e:
+            context = f" in operation '{operation_id}'" if operation_id else ""
+            param_context = f" for parameter '{param_name}'" if param_name else ""
+            # Show available properties if data is a dict, otherwise show data type
+            available = (
+                f"Available properties: {list(data.keys())}"
+                if isinstance(data, dict)
+                else f"Data is {type(data).__name__}, not a dict"
+            )
+            raise ApplicationException(
+                400,
+                f"Cannot resolve reference '$ref:{ref_op_id}.{ref_path}'"
+                f"{context}{param_context}: property not found in result. "
+                f"{available}",
+            ) from e
+
+    def validate_references(self, params: Dict[str, Any]) -> List[str]:
+        """
+        Validate that all references in parameters can be resolved.
+
+        Args:
+            params: Parameters to validate
+
+        Returns:
+            List of referenced operation IDs
+        """
+        refs = []
+
+        def find_refs(value: Any):
+            if isinstance(value, str) and "$ref:" in value:
+                for match in self.REF_PATTERN.finditer(value):
+                    refs.append(match.group(1))
+            elif isinstance(value, dict):
+                for v in value.values():
+                    find_refs(v)
+            elif isinstance(value, list):
+                for item in value:
+                    find_refs(item)
+
+        find_refs(params)
+        return list(set(refs))