pal-found-cli 0.1.2__py3-none-any.whl

pal_found_cli/common/error_serializer.py

@@ -0,0 +1,412 @@
+#!/usr/bin/env python3
+"""ErrorSerializer mapping SDK exceptions to exit codes (ADR-001).
+
+Maps SDK and runtime exceptions to the structured exit code taxonomy
+defined in ADR-001. Produces a JSON error envelope on stdout with
+structured metadata.
+
+Exit Code Taxonomy (ADR-001)
+----------------------------
+0  : Success
+1  : UserInputError (invalid CLI args, validation failure, missing param)
+2  : AuthenticationError (missing/invalid token, SDK auth failure)
+3  : PermissionDeniedError (API 403)
+4  : NotFoundError (API 404, resource does not exist)
+5  : TimeoutError (asyncio.wait_for timeout, SIGINT/SIGTERM)
+6  : ServerError (API 5xx excluding 503)
+7  : RateLimitExhausted (HTTP 429 + retries exhausted)
+8  : AccessControlError (CLI access control policy)
+9  : ConfigurationError (missing env var, malformed config)
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import traceback
+import uuid
+from typing import Any
+
+from pal_found_cli.common.sdk_error_utils import (
+    sdk_exception_exit_code,
+    sdk_exception_exit_map,
+    sdk_http_status,
+)
+
+logger = logging.getLogger(__name__)
+
+# Environment variable controlling traceback inclusion in error envelopes.
+# When set to a falsy value ("0", "false", "no", "off"), tracebacks are
+# suppressed to avoid leaking file paths / internal structure (OWASP A02).
+ENV_INCLUDE_TRACEBACK = "FOUNDRY_INCLUDE_TRACEBACK"
+DEFAULT_INCLUDE_TRACEBACK = True
+
+
+# ADR-001 Exit code taxonomy
+EXIT_SUCCESS = 0
+EXIT_USER_INPUT = 1
+EXIT_AUTH = 2
+EXIT_PERMISSION_DENIED = 3
+EXIT_NOT_FOUND = 4
+EXIT_TIMEOUT = 5
+EXIT_SERVER_ERROR = 6
+EXIT_RATE_LIMIT = 7
+EXIT_ACCESS_CONTROL = 8
+EXIT_CONFIGURATION = 9
+
+EXIT_CODE_NAMES = {
+    EXIT_SUCCESS: "Success",
+    EXIT_USER_INPUT: "UserInputError",
+    EXIT_AUTH: "AuthenticationError",
+    EXIT_PERMISSION_DENIED: "PermissionDeniedError",
+    EXIT_NOT_FOUND: "NotFoundError",
+    EXIT_TIMEOUT: "TimeoutError",
+    EXIT_SERVER_ERROR: "ServerError",
+    EXIT_RATE_LIMIT: "RateLimitExhausted",
+    EXIT_ACCESS_CONTROL: "AccessControlError",
+    EXIT_CONFIGURATION: "ConfigurationError",
+}
+
+
+class _SDKAuthError(Exception):
+    """Legacy internal placeholder for SDK authentication failure.
+
+    .. deprecated::
+        Retained only for backwards compatibility in unit tests. Real SDK
+        exception types are mapped dynamically via ``_register_sdk_exceptions``
+        when ``foundry_platform_python`` is importable.
+    """
+
+
+class _SDKValidationError(Exception):
+    """Legacy internal placeholder for SDK validation failure (deprecated)."""
+
+
+class _SDKNotFoundError(Exception):
+    """Legacy internal placeholder for SDK resource not found (deprecated)."""
+
+
+class _SDKRateLimitError(Exception):
+    """Legacy internal placeholder for SDK rate limit exceeded (deprecated)."""
+
+
+class _SDKConflictError(Exception):
+    """Legacy internal placeholder for SDK conflict error (deprecated)."""
+
+
+class _SDKNetworkError(Exception):
+    """Legacy internal placeholder for SDK network error (deprecated)."""
+
+
+def _register_sdk_exceptions() -> dict[type[BaseException], int]:
+    """Build an exit-code map that includes real SDK exceptions if available.
+
+    The Foundry SDK exposes ``PalantirRPCException`` subclasses through its
+    error module. When the SDK is importable, those
+    real exception types are mapped to ADR-001 exit codes so that
+    ``isinstance`` matching in :meth:`ErrorSerializer.serialize` actually fires.
+    When the SDK is not installed (e.g. unit tests, lightweight environments),
+    only the standard library fallbacks are used and HTTP status code
+    classification (see :meth:`ErrorSerializer._classify_http_exception`) acts
+    as the primary mapping path.
+
+    Returns
+    -------
+    Dict[Type[BaseException], int]
+        Mapping of exception classes to ADR-001 exit codes.
+    """
+    mapping: dict[type[BaseException], int] = {
+        # Auth errors -> code 2
+        _SDKAuthError: EXIT_AUTH,
+        # Validation -> code 1 (UserInputError in ADR-001)
+        _SDKValidationError: EXIT_USER_INPUT,
+        ValueError: EXIT_USER_INPUT,
+        TypeError: EXIT_USER_INPUT,
+        # Permission denied -> code 3
+        PermissionError: EXIT_PERMISSION_DENIED,
+        # Not found -> code 4
+        _SDKNotFoundError: EXIT_NOT_FOUND,
+        FileNotFoundError: EXIT_NOT_FOUND,
+        # Timeout -> code 5
+        TimeoutError: EXIT_TIMEOUT,
+        asyncio.TimeoutError: EXIT_TIMEOUT,
+        # Rate limit -> code 7
+        _SDKRateLimitError: EXIT_RATE_LIMIT,
+        # Config errors -> code 9
+        ImportError: EXIT_CONFIGURATION,
+        ModuleNotFoundError: EXIT_CONFIGURATION,
+        EnvironmentError: EXIT_CONFIGURATION,
+        OSError: EXIT_CONFIGURATION,
+    }
+
+    # Register the CLI's own AccessControlError -> exit code 8 (ADR-001).
+    # BUG-SUB-004: without this entry, serialize() falls through to the
+    # EXIT_USER_INPUT default because AccessControlError carries no HTTP
+    # status, so HTTP classification cannot rescue it. The import is lazy to
+    # avoid a circular dependency: access_control_guard imports
+    # EXIT_ACCESS_CONTROL from this module at its import time, which is safe
+    # because this function runs only after EXIT_ACCESS_CONTROL is defined.
+    try:
+        from pal_found_cli.common.access_control_guard import (
+            AccessControlError,  # type: ignore[import-not-found]
+        )
+    except ImportError:
+        AccessControlError = None  # type: ignore[assignment, misc]
+
+    if AccessControlError is not None:
+        mapping[AccessControlError] = EXIT_ACCESS_CONTROL
+
+    mapping.update(sdk_exception_exit_map())
+    return mapping
+
+
+# Map exception classes to ADR-001 exit codes (computed at import time).
+_EXCEPTION_TO_EXIT_CODE: dict[type[BaseException], int] = _register_sdk_exceptions()
+
+
+class ErrorSerializer:
+    """Serializes exceptions to ADR-001 exit codes and JSON error envelopes.
+
+    Maps exceptions to the structured exit code taxonomy and produces
+    a JSON error envelope on stdout.
+
+    Error Envelope Schema
+    ---------------------
+    {
+        "error": true,
+        "exit_code": int,
+        "exit_code_name": str,
+        "message": str,
+        "exception_type": str,
+        "traceback": str,
+        "call_id": str,
+    }
+
+    Examples
+    --------
+    >>> serializer = ErrorSerializer()
+    >>> try:
+    ...     await call_api()
+    ... except Exception as e:
+    ...     exit_code = serializer.serialize(e)
+    ...     sys.exit(exit_code)
+    """
+
+    def __init__(self, call_id: str | None = None) -> None:
+        """Initialize ErrorSerializer.
+
+        Parameters
+        ----------
+        call_id : str, optional
+            Unique identifier for this CLI invocation. Auto-generated if not set.
+        """
+        self.call_id = call_id or str(uuid.uuid4())
+
+    def _get_http_status_from_exception(self, exception: BaseException) -> int | None:
+        """Extract HTTP status code from an exception if available.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception to inspect.
+
+        Returns
+        -------
+        int or None
+            HTTP status code if available, None otherwise.
+        """
+        return sdk_http_status(exception)
+
+    def _classify_http_exception(self, exception: BaseException) -> int | None:
+        """Classify HTTP exceptions based on status code.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception to classify.
+
+        Returns
+        -------
+        int or None
+            Exit code if classifiable, None otherwise.
+        """
+        status = self._get_http_status_from_exception(exception)
+        if status is None:
+            return None
+
+        if status == 401:
+            return EXIT_AUTH
+        if status == 403:
+            return EXIT_PERMISSION_DENIED
+        if status == 404:
+            return EXIT_NOT_FOUND
+        if status == 409:
+            return EXIT_USER_INPUT  # Conflict treated as user input
+        if status == 429:
+            return EXIT_RATE_LIMIT
+        if status == 503:
+            return EXIT_SERVER_ERROR
+        if status and status >= 500 and status != 503:
+            return EXIT_SERVER_ERROR
+        return None
+
+    def serialize(
+        self,
+        exception: BaseException,
+        print_to_stdout: bool = True,
+    ) -> int:
+        """Serialize an exception to an ADR-001 exit code.
+
+        Maps the exception to an exit code and optionally prints a
+        structured JSON error envelope to stdout.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception to serialize.
+        print_to_stdout : bool, optional
+            Whether to print the JSON error envelope to stdout.
+            Default: True.
+
+        Returns
+        -------
+        int
+            The exit code (0-9) per ADR-001 taxonomy.
+        """
+        exit_code = EXIT_USER_INPUT  # Default: UserInputError
+
+        # First try HTTP status classification
+        http_exit = self._classify_http_exception(exception)
+        if http_exit is not None:
+            exit_code = http_exit
+        else:
+            declared_exit_code = getattr(exception, "exit_code", None)
+            if (
+                isinstance(declared_exit_code, int)
+                and declared_exit_code in EXIT_CODE_NAMES
+            ):
+                exit_code = declared_exit_code
+            elif (sdk_exit_code := sdk_exception_exit_code(exception)) is not None:
+                exit_code = sdk_exit_code
+            # Walk MRO for exception type matching
+            else:
+                for klass in type(exception).__mro__:
+                    if klass in _EXCEPTION_TO_EXIT_CODE:
+                        exit_code = _EXCEPTION_TO_EXIT_CODE[klass]
+                        break
+
+        exit_code_name = EXIT_CODE_NAMES.get(exit_code, "UnknownError")
+
+        # Traceback inclusion is configurable to mitigate sensitive data
+        # exposure (OWASP A02). Defaults to on for diagnostics; production
+        # deployments can set FOUNDRY_INCLUDE_TRACEBACK=false.
+        include_tb = os.environ.get(ENV_INCLUDE_TRACEBACK, "")
+        if include_tb == "":
+            include_tb_val = DEFAULT_INCLUDE_TRACEBACK
+        else:
+            include_tb_val = include_tb.lower() in ("true", "1", "yes", "on")
+
+        if include_tb_val:
+            tb_lines = traceback.format_exception(
+                type(exception), exception, exception.__traceback__
+            )
+            traceback_str = "".join(tb_lines).rstrip()
+        else:
+            traceback_str = ""
+
+        error_envelope: dict[str, Any] = {
+            "error": True,
+            "exit_code": exit_code,
+            "exit_code_name": exit_code_name,
+            "message": str(exception),
+            "exception_type": type(exception).__name__,
+            "traceback": traceback_str,
+            "call_id": self.call_id,
+        }
+
+        # Add HTTP status if available
+        http_status = self._get_http_status_from_exception(exception)
+        if http_status is not None:
+            error_envelope["http_status"] = http_status
+
+        diagnostic_metadata = getattr(exception, "diagnostic_metadata", None)
+        if isinstance(diagnostic_metadata, dict):
+            safe_keys = {"session_id", "source_size", "source_size_at_least"}
+            safe_metadata = {
+                key: value
+                for key, value in diagnostic_metadata.items()
+                if key in safe_keys
+                and isinstance(value, (str, int, float, bool, type(None)))
+            }
+            if safe_metadata:
+                error_envelope["details"] = safe_metadata
+
+        if print_to_stdout:
+            json_str = json.dumps(error_envelope, default=str)
+            sys.stdout.write(json_str + "\n")
+            sys.stdout.flush()
+
+        logger.error(
+            f"Serialized {type(exception).__name__} to exit code {exit_code} "
+            f"({exit_code_name}): {exception}",
+            extra={
+                "http_status": http_status,
+                "call_id": self.call_id,
+            },
+        )
+
+        return exit_code
+
+    @staticmethod
+    def get_exit_code_name(exit_code: int) -> str:
+        """Get the human-readable name for an exit code.
+
+        Parameters
+        ----------
+        exit_code : int
+            The exit code to look up.
+
+        Returns
+        -------
+        str
+            The name of the exit code, or 'UnknownError' if not found.
+        """
+        return EXIT_CODE_NAMES.get(exit_code, "UnknownError")
+
+    @staticmethod
+    def create_error_envelope(
+        exit_code: int,
+        message: str,
+        exception_type: str = "UnknownError",
+        call_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a JSON error envelope without an exception object.
+
+        Parameters
+        ----------
+        exit_code : int
+            Exit code per ADR-001.
+        message : str
+            Human-readable error message.
+        exception_type : str, optional
+            Name of the exception type.
+        call_id : str, optional
+            Unique invocation identifier.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Error envelope dictionary.
+        """
+        exit_code_name = EXIT_CODE_NAMES.get(exit_code, "UnknownError")
+
+        return {
+            "error": True,
+            "exit_code": exit_code,
+            "exit_code_name": exit_code_name,
+            "message": message,
+            "exception_type": exception_type,
+            "traceback": "",
+            "call_id": call_id or str(uuid.uuid4()),
+        }

pal_found_cli/common/log_setup.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Structured NDJSON logging setup for Foundry CLI (ADR-005).
+
+Configures Python `logging` with a custom JSON formatter directed to stderr.
+Implements newline-delimited JSON (NDJSON) format for machine-parseable logs.
+
+Environment Variables
+---------------------
+FOUNDRY_AGENTIC_CLI_LOG_LEVEL : str
+    Log level control. Supported: DEBUG, INFO, WARNING, ERROR.
+    Default: WARNING
+
+Log Record Schema
+-----------------
+Required fields: ts, level, logger, msg
+Optional context fields: op, call_id, attempt, delay_ms, access_decision, http_status
+
+Metadata Separator
+------------------
+'# ---metadata-start---' precedes metadata JSON on stderr.
+"""
+
+import json
+import logging
+import os
+import sys
+import threading
+from datetime import UTC, datetime
+from typing import Any
+
+# Metadata separator as defined in ADR-005
+METADATA_SEPARATOR = "# ---metadata-start---"
+
+# Default log level
+DEFAULT_LOG_LEVEL = "WARNING"
+
+# Environment variable for log level
+ENV_LOG_LEVEL = "FOUNDRY_AGENTIC_CLI_LOG_LEVEL"
+
+# Supported log levels
+SUPPORTED_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+
+
+class _NdJsonFormatter(logging.Formatter):
+    """Newline-delimited JSON formatter for structured logging (ADR-005).
+
+    Each log record is emitted as a single JSON line to stderr.
+    Required fields: ts, level, logger, msg
+    Optional context fields are merged from extra={} passed to logging calls.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record as NDJSON.
+
+        Parameters
+        ----------
+        record : logging.LogRecord
+            The log record to format.
+
+        Returns
+        -------
+        str
+            A single JSON line representing the log record.
+        """
+        ts = datetime.fromtimestamp(record.created, tz=UTC).isoformat()
+
+        log_entry: dict[str, Any] = {
+            "ts": ts,
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+
+        # Merge optional context fields from extra data
+        # These are attached as attributes on the LogRecord by the caller
+        optional_fields = [
+            "op",
+            "call_id",
+            "attempt",
+            "delay_ms",
+            "access_decision",
+            "http_status",
+            "session_alias",
+            "active_session_count",
+            "file_size",
+            "max_download_bytes",
+            "truncated",
+            "source_size",
+            "source_size_at_least",
+            "trace_id",
+            "span_id",
+        ]
+        for field in optional_fields:
+            value = getattr(record, field, None)
+            if value is not None:
+                log_entry[field] = value
+
+        # Include exception info if present
+        if record.exc_info and record.exc_info[0] is not None:
+            log_entry["exc"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_entry, default=str)
+
+
+class LogSetup:
+    """Configures Python logging with NDJSON formatter directed to stderr (ADR-005).
+
+    Usage
+    -----
+    >>> LogSetup.configure(log_level="WARNING")
+    >>> logger = logging.getLogger("pal_found_cli.common.retry")
+    >>> logger.warning("Retrying after 429", extra={"op": "datasets.list", "attempt": 2})
+    """
+
+    _configured: bool = False
+    _lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def configure(
+        cls,
+        log_level: str | None = None,
+    ) -> logging.Logger:
+        """Configure the root logger with NDJSON formatter to stderr.
+
+        Thread-safe: serialises concurrent first-configurations through a
+        class-level lock so that two threads racing to configure logging do
+        not register duplicate handlers.
+
+        Parameters
+        ----------
+        log_level : str, optional
+            Log level (DEBUG, INFO, WARNING, ERROR). Defaults to env var
+            `FOUNDRY_AGENTIC_CLI_LOG_LEVEL`, then to `WARNING`.
+
+        Returns
+        -------
+        logging.Logger
+            The configured root logger.
+
+        Raises
+        ------
+        ValueError
+            If log_level is not one of the supported levels.
+        """
+        # Fast path: already configured (no lock needed for the read).
+        if cls._configured:
+            return logging.getLogger()
+
+        with cls._lock:
+            # Re-check inside the lock to avoid duplicate configuration.
+            if cls._configured:
+                return logging.getLogger()
+
+            # Resolve log level: explicit arg > env var > default
+            effective_level = log_level or os.environ.get(ENV_LOG_LEVEL)
+            if not effective_level:
+                effective_level = DEFAULT_LOG_LEVEL
+            effective_level = effective_level.upper()
+
+            if effective_level not in SUPPORTED_LEVELS:
+                raise ValueError(
+                    f"Unsupported log level '{effective_level}'. "
+                    f"Must be one of: {', '.join(sorted(SUPPORTED_LEVELS))}"
+                )
+
+            root_logger = logging.getLogger()
+            root_logger.setLevel(getattr(logging, effective_level))
+
+            # Remove any existing handlers to prevent duplicates
+            root_logger.handlers.clear()
+
+            # Create stderr handler with NDJSON formatter
+            stderr_handler = logging.StreamHandler(sys.stderr)
+            stderr_handler.setFormatter(_NdJsonFormatter())
+            root_logger.addHandler(stderr_handler)
+
+            cls._configured = True
+            return root_logger
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset logging configuration (for testing purposes).
+
+        Clears all handlers and resets the configured flag.
+        """
+        with cls._lock:
+            root_logger = logging.getLogger()
+            root_logger.handlers.clear()
+            cls._configured = False
+
+    @staticmethod
+    def emit_metadata_separator() -> None:
+        """Emit the metadata separator line to stderr (ADR-005).
+
+        Writes `# ---metadata-start---` to stderr to indicate
+        the start of metadata JSON output.
+        """
+        sys.stderr.write(METADATA_SEPARATOR + "\n")
+        sys.stderr.flush()
+
+    @staticmethod
+    def emit_metadata(metadata: dict[str, Any]) -> None:
+        """Emit metadata JSON to stderr after the separator.
+
+        Parameters
+        ----------
+        metadata : Dict[str, Any]
+            Metadata dictionary to serialize as JSON on stderr.
+        """
+        LogSetup.emit_metadata_separator()
+        sys.stderr.write(json.dumps(metadata, default=str) + "\n")
+        sys.stderr.flush()
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a named logger for a Foundry CLI module.
+
+    The logger is automatically configured with NDJSON format to stderr.
+    Use `extra={}` on log calls to include optional context fields.
+
+    Parameters
+    ----------
+    name : str
+        Logger name, typically the module path (e.g., 'pal_found_cli.common.retry').
+
+    Returns
+    -------
+    logging.Logger
+        A configured logger instance.
+
+    Examples
+    --------
+    >>> logger = get_logger("pal_found_cli.common.retry")
+    >>> logger.warning(
+    ...     "Retrying after 429: attempt 2/4, delay 1000ms",
+    ...     extra={"op": "datasets.dataset.read_table", "attempt": 2, "delay_ms": 1000},
+    ... )
+    """
+    # Ensure logging is configured
+    LogSetup.configure()
+    return logging.getLogger(name)