miso-client 0.1.0__py3-none-any.whl → 3.7.2__py3-none-any.whl

miso_client/utils/logger_helpers.py

@@ -0,0 +1,206 @@
+"""
+Logger helper functions for building log entries.
+
+Extracted from logger.py to reduce file size and improve maintainability.
+"""
+
+import os
+import sys
+from datetime import datetime
+from typing import Any, Dict, Literal, Optional, Union
+
+from ..models.config import ClientLoggingOptions, ForeignKeyReference, LogEntry
+from ..utils.data_masker import DataMasker
+from ..utils.jwt_tools import decode_token
+
+
+def extract_jwt_context(token: Optional[str]) -> Dict[str, Any]:
+    """
+    Extract JWT token information.
+
+    Args:
+        token: JWT token string
+
+    Returns:
+        Dictionary with userId, applicationId, sessionId, roles, permissions
+    """
+    if not token:
+        return {}
+
+    try:
+        decoded = decode_token(token)
+        if not decoded:
+            return {}
+
+        # Extract roles - handle different formats
+        roles = []
+        if "roles" in decoded:
+            roles = decoded["roles"] if isinstance(decoded["roles"], list) else []
+        elif "realm_access" in decoded and isinstance(decoded["realm_access"], dict):
+            roles = decoded["realm_access"].get("roles", [])
+
+        # Extract permissions - handle different formats
+        permissions = []
+        if "permissions" in decoded:
+            permissions = decoded["permissions"] if isinstance(decoded["permissions"], list) else []
+        elif "scope" in decoded and isinstance(decoded["scope"], str):
+            permissions = decoded["scope"].split()
+
+        return {
+            "userId": decoded.get("sub") or decoded.get("userId") or decoded.get("user_id"),
+            "applicationId": decoded.get("applicationId") or decoded.get("app_id"),
+            "sessionId": decoded.get("sessionId") or decoded.get("sid"),
+            "roles": roles,
+            "permissions": permissions,
+        }
+    except Exception:
+        # JWT parsing failed, return empty context
+        return {}
+
+
+def extract_metadata() -> Dict[str, Any]:
+    """
+    Extract metadata from environment (browser or Node.js).
+
+    Returns:
+        Dictionary with hostname, userAgent, etc.
+    """
+    metadata: Dict[str, Any] = {}
+
+    # Try to extract Node.js/Python metadata
+    if hasattr(os, "environ"):
+        metadata["hostname"] = os.environ.get("HOSTNAME", "unknown")
+
+    # In Python, we don't have browser metadata like in TypeScript
+    # But we can capture some environment info
+    metadata["platform"] = sys.platform
+    metadata["python_version"] = sys.version
+
+    return metadata
+
+
+def _convert_to_foreign_key_reference(
+    value: Optional[Union[str, ForeignKeyReference]], entity_type: str
+) -> Optional[ForeignKeyReference]:
+    """
+    Convert string ID or ForeignKeyReference to ForeignKeyReference object.
+
+    Args:
+        value: String ID or ForeignKeyReference object
+        entity_type: Entity type (e.g., 'User', 'Application')
+
+    Returns:
+        ForeignKeyReference object or None
+    """
+    if value is None:
+        return None
+
+    # If already a ForeignKeyReference, return as-is
+    if isinstance(value, ForeignKeyReference):
+        return value
+
+    # If string, create minimal ForeignKeyReference
+    # Note: This is a minimal conversion - full ForeignKeyReference should come from API responses
+    if isinstance(value, str):
+        return ForeignKeyReference(
+            id=value,
+            key=value,  # Use id as key when key is not available
+            name=value,  # Use id as name when name is not available
+            type=entity_type,
+        )
+
+    return None
+
+
+def build_log_entry(
+    level: Literal["error", "audit", "info", "debug"],
+    message: str,
+    context: Optional[Dict[str, Any]],
+    config_client_id: str,
+    correlation_id: Optional[str] = None,
+    jwt_token: Optional[str] = None,
+    stack_trace: Optional[str] = None,
+    options: Optional[ClientLoggingOptions] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    mask_sensitive: bool = True,
+) -> LogEntry:
+    """
+    Build LogEntry object from parameters.
+
+    Args:
+        level: Log level
+        message: Log message
+        context: Additional context data
+        config_client_id: Client ID from config
+        correlation_id: Optional correlation ID
+        jwt_token: Optional JWT token for context extraction
+        stack_trace: Stack trace for errors
+        options: Logging options
+        metadata: Environment metadata
+        mask_sensitive: Whether to mask sensitive data
+
+    Returns:
+        LogEntry object
+    """
+    # Extract JWT context if token provided
+    jwt_context = extract_jwt_context(jwt_token or (options.token if options else None))
+
+    # Extract environment metadata
+    env_metadata = metadata or extract_metadata()
+
+    # Generate correlation ID if not provided
+    final_correlation_id = correlation_id or (options.correlationId if options else None)
+
+    # Mask sensitive data in context if enabled
+    should_mask = (options.maskSensitiveData if options else None) is not False and mask_sensitive
+    masked_context = DataMasker.mask_sensitive_data(context) if should_mask and context else context
+
+    # Convert applicationId and userId to ForeignKeyReference if needed
+    application_id_value = options.applicationId if options else None
+    user_id_value = (options.userId if options else None) or jwt_context.get("userId")
+
+    application_id_ref = _convert_to_foreign_key_reference(application_id_value, "Application")
+    user_id_ref = _convert_to_foreign_key_reference(user_id_value, "User")
+
+    log_entry_data = {
+        "timestamp": datetime.utcnow().isoformat(),
+        "level": level,
+        "environment": "unknown",  # Backend extracts from client credentials
+        "application": config_client_id,  # Use clientId as application identifier
+        "applicationId": application_id_ref,
+        "message": message,
+        "context": masked_context,
+        "stackTrace": stack_trace,
+        "correlationId": final_correlation_id,
+        "userId": user_id_ref,
+        "sessionId": (options.sessionId if options else None) or jwt_context.get("sessionId"),
+        "requestId": options.requestId if options else None,
+        "ipAddress": options.ipAddress if options else None,
+        "userAgent": options.userAgent if options else None,
+        **env_metadata,
+        # Indexed context fields from options
+        "sourceKey": options.sourceKey if options else None,
+        "sourceDisplayName": options.sourceDisplayName if options else None,
+        "externalSystemKey": options.externalSystemKey if options else None,
+        "externalSystemDisplayName": options.externalSystemDisplayName if options else None,
+        "recordKey": options.recordKey if options else None,
+        "recordDisplayName": options.recordDisplayName if options else None,
+        # Credential context
+        "credentialId": options.credentialId if options else None,
+        "credentialType": options.credentialType if options else None,
+        # Request metrics
+        "requestSize": options.requestSize if options else None,
+        "responseSize": options.responseSize if options else None,
+        "durationMs": options.durationMs if options else None,
+        "durationSeconds": options.durationSeconds if options else None,
+        "timeout": options.timeout if options else None,
+        "retryCount": options.retryCount if options else None,
+        # Error classification
+        "errorCategory": options.errorCategory if options else None,
+        "httpStatusCategory": options.httpStatusCategory if options else None,
+    }
+
+    # Remove None values
+    log_entry_data = {k: v for k, v in log_entry_data.items() if v is not None}
+
+    return LogEntry(**log_entry_data)

miso_client/utils/logging_helpers.py

@@ -0,0 +1,70 @@
+"""Logging context helpers for extracting indexed fields."""
+
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HasKey(Protocol):
+    """Protocol for objects with key and displayName."""
+
+    key: str
+    displayName: Optional[str]
+
+
+@runtime_checkable
+class HasExternalSystem(Protocol):
+    """Protocol for objects with key, displayName, and optional externalSystem."""
+
+    key: str
+    displayName: Optional[str]
+    externalSystem: Optional[HasKey]
+
+
+def extract_logging_context(
+    source: Optional[HasExternalSystem] = None,
+    record: Optional[HasKey] = None,
+    external_system: Optional[HasKey] = None,
+) -> Dict[str, Any]:
+    """
+    Extract indexed fields for logging.
+
+    Indexed fields:
+    - sourceKey, sourceDisplayName
+    - externalSystemKey, externalSystemDisplayName
+    - recordKey, recordDisplayName
+
+    Args:
+        source: ExternalDataSource object (optional)
+        record: ExternalRecord object (optional)
+        external_system: ExternalSystem object (optional)
+
+    Returns:
+        Dictionary with indexed context fields (only non-None values)
+
+    Design principles:
+    - No DB access
+    - Explicit context passing
+    - Safe to use in hot paths
+    """
+    context: Dict[str, Any] = {}
+
+    if source:
+        context["sourceKey"] = source.key
+        if source.displayName:
+            context["sourceDisplayName"] = source.displayName
+        if source.externalSystem:
+            context["externalSystemKey"] = source.externalSystem.key
+            if source.externalSystem.displayName:
+                context["externalSystemDisplayName"] = source.externalSystem.displayName
+
+    if external_system:
+        context["externalSystemKey"] = external_system.key
+        if external_system.displayName:
+            context["externalSystemDisplayName"] = external_system.displayName
+
+    if record:
+        context["recordKey"] = record.key
+        if record.displayName:
+            context["recordDisplayName"] = record.displayName
+
+    return context

miso_client/utils/origin_validator.py

@@ -0,0 +1,128 @@
+"""
+Origin validation utility for CORS security.
+
+This module provides utilities for validating request origins against
+a list of allowed origins, with support for wildcard port matching.
+"""
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+
+def validate_origin(headers: Any, allowed_origins: List[str]) -> Dict[str, Any]:
+    """
+    Validate request origin against allowed origins list.
+
+    Checks the 'origin' header first, then falls back to 'referer' header.
+    Supports wildcard ports (e.g., 'http://localhost:*' matches any port).
+
+    Args:
+        headers: Request headers dict or object with headers attribute
+        allowed_origins: List of allowed origin URLs (supports wildcard ports)
+
+    Returns:
+        Dictionary with:
+            - valid: bool - Whether origin is valid
+            - error: Optional[str] - Error message if invalid, None if valid
+
+    Example:
+        >>> headers = {"origin": "http://localhost:3000"}
+        >>> result = validate_origin(headers, ["http://localhost:*"])
+        >>> result["valid"]
+        True
+    """
+    if not allowed_origins:
+        # If no allowed origins configured, allow all (backward compatibility)
+        return {"valid": True, "error": None}
+
+    # Extract headers dict from various request object types
+    headers_dict: Optional[Dict[str, Any]] = None
+    if isinstance(headers, dict):
+        headers_dict = headers
+    elif hasattr(headers, "headers"):
+        # FastAPI, Flask style: request.headers
+        headers_obj = getattr(headers, "headers")
+        if isinstance(headers_obj, dict):
+            headers_dict = headers_obj
+        elif hasattr(headers_obj, "get"):
+            # Headers object with get method (like Starlette headers)
+            headers_dict = dict(headers_obj)
+    elif hasattr(headers, "get"):
+        # Already a dict-like object
+        headers_dict = dict(headers)
+
+    if headers_dict is None:
+        return {"valid": False, "error": "Unable to extract headers from request"}
+
+    # Extract origin from headers (case-insensitive)
+    origin = None
+    for key in ["origin", "Origin", "ORIGIN"]:
+        if key in headers_dict:
+            origin_value = headers_dict[key]
+            if isinstance(origin_value, str) and origin_value.strip():
+                origin = origin_value.strip()
+                break
+
+    # Fallback to referer header if origin not found
+    if not origin:
+        for key in ["referer", "Referer", "REFERER", "referrer", "Referrer", "REFERRER"]:
+            if key in headers_dict:
+                referer_value = headers_dict[key]
+                if isinstance(referer_value, str) and referer_value.strip():
+                    # Extract origin from referer URL
+                    try:
+                        parsed = urlparse(referer_value.strip())
+                        if parsed.scheme and parsed.netloc:
+                            origin = f"{parsed.scheme}://{parsed.netloc}"
+                            break
+                    except Exception:
+                        pass
+
+    if not origin:
+        return {"valid": False, "error": "No origin or referer header found"}
+
+    # Normalize origin (remove trailing slash, lowercase scheme/host)
+    try:
+        parsed_origin = urlparse(origin)
+        if not parsed_origin.scheme or not parsed_origin.netloc:
+            return {"valid": False, "error": f"Invalid origin format: {origin}"}
+        origin_scheme = parsed_origin.scheme.lower()
+        origin_netloc = parsed_origin.netloc.lower()
+        origin_normalized = f"{origin_scheme}://{origin_netloc}"
+    except Exception:
+        return {"valid": False, "error": f"Invalid origin format: {origin}"}
+
+    # Check against allowed origins
+    for allowed in allowed_origins:
+        if not allowed or not isinstance(allowed, str):
+            continue
+
+        try:
+            parsed_allowed = urlparse(allowed)
+            allowed_scheme = parsed_allowed.scheme.lower()
+            allowed_netloc = parsed_allowed.netloc.lower()
+            allowed_normalized = f"{allowed_scheme}://{allowed_netloc}"
+
+            # Check for exact match
+            if origin_normalized == allowed_normalized:
+                return {"valid": True, "error": None}
+
+            # Check for wildcard port match (e.g., localhost:* matches localhost:3000)
+            if "*" in allowed_netloc:
+                # Extract host from origin
+                origin_host = origin_netloc.split(":")[0]
+
+                # Extract host from allowed (may have wildcard port)
+                allowed_host = allowed_netloc.split(":")[0]
+                allowed_port = allowed_netloc.split(":")[1] if ":" in allowed_netloc else None
+
+                # Match if host matches and allowed has wildcard port
+                if origin_host == allowed_host and allowed_port == "*":
+                    if origin_scheme == allowed_scheme:
+                        return {"valid": True, "error": None}
+
+        except Exception:
+            # Skip invalid allowed origin format
+            continue
+
+    return {"valid": False, "error": f"Origin '{origin}' is not in allowed origins list"}

miso_client/utils/pagination.py

@@ -0,0 +1,275 @@
+"""
+Pagination utilities for MisoClient SDK.
+
+This module provides reusable pagination utilities for parsing pagination parameters,
+creating meta objects, and working with paginated responses.
+"""
+
+from typing import Dict, List, Tuple, TypeVar
+
+from ..models.pagination import Meta, PaginatedListResponse
+
+T = TypeVar("T")
+
+
+def parsePaginationParams(params: dict) -> Dict[str, int]:
+    """
+    Parse query parameters into pagination values.
+
+    Parses `page` and `page_size` query parameters into `currentPage` and `pageSize`.
+    Both are 1-based (page starts at 1).
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'page': '1', 'page_size': '25'})
+
+    Returns:
+        Dictionary with 'currentPage' and 'pageSize' keys (camelCase)
+
+    Examples:
+        >>> parsePaginationParams({'page': '1', 'page_size': '25'})
+        {'currentPage': 1, 'pageSize': 25}
+        >>> parsePaginationParams({'page': '2'})
+        {'currentPage': 2, 'pageSize': 20}  # Default pageSize is 20
+    """
+    # Default values (matching TypeScript default of 20)
+    default_page = 1
+    default_page_size = 20
+
+    # Parse page (must be >= 1)
+    page_str = params.get("page") or params.get("current_page")
+    if page_str is None:
+        current_page = default_page
+    else:
+        try:
+            current_page = int(page_str)
+            if current_page < 1:
+                current_page = default_page
+        except (ValueError, TypeError):
+            current_page = default_page
+
+    # Parse page_size (must be >= 1)
+    page_size_str = params.get("page_size") or params.get("pageSize")
+    if page_size_str is None:
+        page_size = default_page_size
+    else:
+        try:
+            page_size = int(page_size_str)
+            if page_size < 1:
+                page_size = default_page_size
+        except (ValueError, TypeError):
+            page_size = default_page_size
+
+    return {"currentPage": current_page, "pageSize": page_size}
+
+
+# Alias for backward compatibility
+def parse_pagination_params(params: dict) -> Tuple[int, int]:
+    """
+    Parse query parameters to pagination values (legacy function).
+
+    Parses `page` and `page_size` query parameters into `current_page` and `page_size`.
+    Both are 1-based (page starts at 1).
+
+    Args:
+        params: Dictionary with query parameters (e.g., {'page': '1', 'page_size': '25'})
+
+    Returns:
+        Tuple of (current_page, page_size) as integers
+
+    Examples:
+        >>> parse_pagination_params({'page': '1', 'page_size': '25'})
+        (1, 25)
+        >>> parse_pagination_params({'page': '2'})
+        (2, 20)  # Default page_size is 20
+    """
+    result = parsePaginationParams(params)
+    return (result["currentPage"], result["pageSize"])
+
+
+def createMetaObject(totalItems: int, currentPage: int, pageSize: int, type: str) -> Meta:
+    """
+    Construct meta object for API response.
+
+    Args:
+        totalItems: Total number of items available in full dataset
+        currentPage: Current page index (1-based)
+        pageSize: Number of items per page
+        type: Logical resource type (e.g., "application", "environment")
+
+    Returns:
+        Meta object
+
+    Examples:
+        >>> meta = createMetaObject(120, 1, 25, 'item')
+        >>> meta.totalItems
+        120
+        >>> meta.currentPage
+        1
+    """
+    return Meta(
+        totalItems=totalItems,
+        currentPage=currentPage,
+        pageSize=pageSize,
+        type=type,
+    )
+
+
+def create_meta_object(total_items: int, current_page: int, page_size: int, type: str) -> Meta:
+    """
+    Construct Meta object from pagination parameters.
+
+    Args:
+        total_items: Total number of items across all pages
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+        type: Resource type identifier (e.g., 'item', 'user', 'group')
+
+    Returns:
+        Meta object with pagination metadata
+
+    Examples:
+        >>> meta = create_meta_object(120, 1, 25, 'item')
+        >>> meta.totalItems
+        120
+        >>> meta.currentPage
+        1
+    """
+    return Meta(
+        totalItems=total_items,
+        currentPage=current_page,
+        pageSize=page_size,
+        type=type,
+    )
+
+
+def applyPaginationToArray(items: List[T], currentPage: int, pageSize: int) -> List[T]:
+    """
+    Apply pagination to an array (for mock/testing).
+
+    Args:
+        items: Array of items to paginate
+        currentPage: Current page index (1-based)
+        pageSize: Number of items per page
+
+    Returns:
+        Paginated slice of the array
+
+    Examples:
+        >>> items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        >>> applyPaginationToArray(items, 1, 3)
+        [1, 2, 3]
+        >>> applyPaginationToArray(items, 2, 3)
+        [4, 5, 6]
+    """
+    if not items:
+        return []
+
+    if currentPage < 1:
+        currentPage = 1
+    if pageSize < 1:
+        pageSize = 25
+
+    # Calculate start and end indices
+    start_index = (currentPage - 1) * pageSize
+    end_index = start_index + pageSize
+
+    # Return paginated subset
+    return items[start_index:end_index]
+
+
+def apply_pagination_to_array(items: List[T], current_page: int, page_size: int) -> List[T]:
+    """
+    Apply pagination to array (for testing/mocks).
+
+    Args:
+        items: Array of items to paginate
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+
+    Returns:
+        Paginated subset of items for the specified page
+
+    Examples:
+        >>> items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        >>> apply_pagination_to_array(items, 1, 3)
+        [1, 2, 3]
+        >>> apply_pagination_to_array(items, 2, 3)
+        [4, 5, 6]
+    """
+    if not items:
+        return []
+
+    if current_page < 1:
+        current_page = 1
+    if page_size < 1:
+        page_size = 25
+
+    # Calculate start and end indices
+    start_index = (current_page - 1) * page_size
+    end_index = start_index + page_size
+
+    # Return paginated subset
+    return items[start_index:end_index]
+
+
+def createPaginatedListResponse(
+    items: List[T],
+    totalItems: int,
+    currentPage: int,
+    pageSize: int,
+    type: str,
+) -> PaginatedListResponse[T]:
+    """
+    Wrap array + meta into a standard paginated response.
+
+    Args:
+        items: Array of items for the current page
+        totalItems: Total number of items available in full dataset
+        currentPage: Current page index (1-based)
+        pageSize: Number of items per page
+        type: Logical resource type (e.g., "application", "environment")
+
+    Returns:
+        PaginatedListResponse object
+
+    Examples:
+        >>> items = [{'id': 1}, {'id': 2}]
+        >>> response = createPaginatedListResponse(items, 10, 1, 2, 'item')
+        >>> response.meta.totalItems
+        10
+        >>> len(response.data)
+        2
+    """
+    meta = createMetaObject(totalItems, currentPage, pageSize, type)
+    return PaginatedListResponse(meta=meta, data=items)
+
+
+def create_paginated_list_response(
+    items: List[T],
+    total_items: int,
+    current_page: int,
+    page_size: int,
+    type: str,
+) -> PaginatedListResponse[T]:
+    """
+    Wrap array + meta into standard paginated response (legacy function).
+
+    Args:
+        items: Array of items for current page
+        total_items: Total number of items across all pages
+        current_page: Current page number (1-based)
+        page_size: Number of items per page
+        type: Resource type identifier (e.g., 'item', 'user', 'group')
+
+    Returns:
+        PaginatedListResponse with meta and data
+
+    Examples:
+        >>> items = [{'id': 1}, {'id': 2}]
+        >>> response = create_paginated_list_response(items, 10, 1, 2, 'item')
+        >>> response.meta.totalItems
+        10
+        >>> len(response.data)
+        2
+    """
+    return createPaginatedListResponse(items, total_items, current_page, page_size, type)