testbench-defect-service 0.1.0__py3-none-any.whl

testbench_defect_service/__init__.py

@@ -0,0 +1,8 @@
+"""
+# TestBench Defect Service
+
+Service to serve defects for TestBench DefectServiceWrapper interface.
+"""
+
+__title__ = "TestBenchDefectService"
+__version__ = "0.1.0"

testbench_defect_service/__main__.py

@@ -0,0 +1,8 @@
+import multiprocessing
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+
+    from testbench_defect_service.cli import cli
+
+    cli()

testbench_defect_service/app.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+
+from pydantic import ValidationError
+from sanic import Sanic
+
+from testbench_defect_service.config import AppConfig
+from testbench_defect_service.exceptions import (
+    AppErrorHandler,
+    handle_jira_error,
+    handle_validation_error,
+)
+from testbench_defect_service.log import get_logging_dict
+from testbench_defect_service.middleware import check_request_auth, log_request, log_response
+from testbench_defect_service.routes import router
+from testbench_defect_service.utils.dependencies import (
+    check_excel_dependencies,
+    check_jira_dependencies,
+)
+
+
+def register_middlewares(app: Sanic) -> None:
+    """Register application middlewares."""
+    app.register_middleware(log_request, "request")
+    app.register_middleware(check_request_auth, "request")
+    app.register_middleware(log_response, "response")  # type: ignore
+
+
+def register_exception_handlers(app: Sanic) -> None:
+    """Register application exception handlers."""
+    app.exception(ValidationError)(handle_validation_error)
+    try:
+        from jira import JIRAError  # noqa: PLC0415
+
+        app.exception(JIRAError)(handle_jira_error)
+    except ImportError:
+        pass
+
+
+def check_dependencies(app: Sanic) -> None:
+    """Check and validate optional dependencies based on client type."""
+    if "ExcelDefectClient" in app.config.CLIENT_CLASS:
+        check_excel_dependencies(raise_on_missing=True)
+
+    if "JiraDefectClient" in app.config.CLIENT_CLASS:
+        check_jira_dependencies(raise_on_missing=True)
+
+
+def create_app(name: str, config: AppConfig | None = None) -> Sanic:
+    """Create and configure the Sanic application."""
+    if not config:
+        config = AppConfig()
+
+    log_config = get_logging_dict(config.LOG_CONFIG, debug=config.DEBUG)
+
+    # Create Sanic app
+    app = Sanic(name, log_config=log_config, error_handler=AppErrorHandler())
+
+    # Apply configuration after Sanic initialization
+    app.update_config(config)
+
+    # Validate dependencies
+    check_dependencies(app)
+
+    # Setup application
+    register_middlewares(app)
+    register_exception_handlers(app)
+    app.blueprint(router)
+
+    # Serve static assets
+    static_path = (Path(__file__).parent / "static/swagger-ui").resolve().as_posix()
+    app.static("/static/swagger-ui", static_path)
+
+    return app

testbench_defect_service/cli.py

@@ -0,0 +1,282 @@
+import sys
+from functools import partial
+from pathlib import Path
+from ssl import SSLContext
+
+import click
+from dotenv import load_dotenv
+from sanic import Sanic
+from sanic.worker.loader import AppLoader
+
+from testbench_defect_service import __title__, __version__
+from testbench_defect_service.app import AppConfig, create_app
+from testbench_defect_service.log import logger
+from testbench_defect_service.utils.config_wizard import (
+    configure_client_only,
+    configure_credentials_only,
+    configure_service_only,
+    run_full_wizard,
+    show_main_menu,
+    view_current_config,
+)
+
+
+def print_service_banner():
+    click.echo(rf"""  ______          __  ____                  __       ____  __  ___   _____                 _         
+ /_  __/__  _____/ /_/ __ )___  ____  _____/ /_     / __ \/  |/  /  / ___/___  ______   __(_)_______ 
+  / / / _ \/ ___/ __/ __  / _ \/ __ \/ ___/ __ \   / / / / /|_/ /   \__ \/ _ \/ ___/ | / / / ___/ _ \
+ / / /  __(__  ) /_/ /_/ /  __/ / / / /__/ / / /  / /_/ / /  / /   ___/ /  __/ /   | |/ / / /__/  __/   version:
+/_/  \___/____/\__/_____/\___/_/ /_/\___/_/ /_/  /_____/_/  /_/   /____/\___/_/    |___/_/\___/\___/    {__version__} 
+                                                                                                     """)  # noqa: W291, E501
+
+
+def print_wizard_banner():
+    click.echo("╔════════════════════════════════════════════════════════╗")
+    click.echo("║  TestBench Defect Service - Configuration Wizard       ║")
+    click.echo("╚════════════════════════════════════════════════════════╝\n")
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name=__title__, message="%(prog)s %(version)s")
+@click.pass_context
+def cli(ctx):
+    ctx.max_content_width = 120
+    load_dotenv()
+
+
+@click.command()
+@click.option(
+    "--path",
+    "config_path",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    metavar="PATH",
+    default="config.toml",
+    help="Path to the configuration file.",
+)
+def init(config_path: Path):
+    """Initialize service configuration interactively."""
+    print_wizard_banner()
+    run_full_wizard(config_path)
+
+
+@click.command()
+@click.option(
+    "--path",
+    "config_path",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default="config.toml",
+    help="Path to the app configuration file",
+)
+@click.option("--full", is_flag=True, help="Run full configuration wizard (skip menu)")
+@click.option("--service-only", is_flag=True, help="Configure service settings only")
+@click.option("--credentials-only", is_flag=True, help="Configure service credentials only")
+@click.option("--client-only", is_flag=True, help="Configure client settings only")
+@click.option("--view", is_flag=True, help="View current configuration")
+def configure(  # noqa: PLR0911, PLR0913, C901
+    config_path: Path,
+    full: bool,
+    service_only: bool,
+    credentials_only: bool,
+    client_only: bool,
+    view: bool,
+):
+    """Create or update configuration files interactively."""
+    print_wizard_banner()
+
+    # Handle command flags (direct modes)
+    if service_only:
+        configure_service_only(config_path)
+        return
+
+    if credentials_only:
+        configure_credentials_only(config_path)
+        return
+
+    if client_only:
+        configure_client_only(config_path)
+        return
+
+    if view:
+        view_current_config(config_path)
+        return
+
+    # Show menu if no flags specified
+    if not full:
+        mode = show_main_menu(config_path)
+        if mode is None or mode == "quit":
+            click.echo("\nConfiguration cancelled.")
+            return
+
+        if mode == "service":
+            configure_service_only(config_path)
+            return
+        if mode == "credentials":
+            configure_credentials_only(config_path)
+            return
+        if mode == "client":
+            configure_client_only(config_path)
+            return
+        if mode == "view":
+            view_current_config(config_path)
+            return
+
+    run_full_wizard(config_path)
+
+
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help=("Path to the app config file  [default: config.toml]"),
+)
+@click.option(
+    "--client-class",
+    type=str,
+    metavar="PATH",
+    help="""Path or module string to the client class  \b
+    [default: testbench_defect_service.clients.JsonlDefectClient]""",
+)
+@click.option(
+    "--client-config",
+    type=click.Path(dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help="Path to the client config file  [default: client_config.toml]",
+)
+@click.option(
+    "--host", type=str, metavar="HOST", help="Host to run the service on  [default: 127.0.0.1]"
+)
+@click.option(
+    "--port", type=int, metavar="PORT", help="Port to run the service on  [default: 8000]"
+)
+@click.option(
+    "--dev",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="Run the service in dev mode (debug + auto reload)",
+)
+@click.option(
+    "--ssl-cert",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help="Path to SSL certificate file for HTTPS",
+)
+@click.option(
+    "--ssl-key",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help="Path to SSL private key file for HTTPS",
+)
+@click.option(
+    "--ssl-ca-cert",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help="Path to CA certificate file for client verification (optional)",
+)
+def start(  # noqa: PLR0913
+    config_path: Path | None = None,
+    client_class: str | None = None,
+    client_config: Path | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    dev: bool = False,
+    ssl_cert: Path | None = None,
+    ssl_key: Path | None = None,
+    ssl_ca_cert: Path | None = None,
+):
+    """Start the TestBench Defect Service."""
+    app_name = __title__
+    app_config = AppConfig(
+        config_path=config_path,
+        client_class=client_class,
+        client_config_path=client_config,
+        host=host,
+        port=port,
+        debug=dev,
+        ssl_cert=ssl_cert,
+        ssl_key=ssl_key,
+        ssl_ca_cert=ssl_ca_cert,
+    )
+
+    print_service_banner()
+
+    factory = partial(create_app, app_name, app_config)
+    loader = AppLoader(factory=factory)
+    try:
+        app = loader.load()
+    except ImportError as e:
+        raise click.ClickException(str(e)) from e
+
+    logger.info("Starting %s v%s", app_name, __version__)
+
+    if not host:
+        host = getattr(app.config, "HOST", None)
+    if not port:
+        port = getattr(app.config, "PORT", None)
+
+    server_config = app_config.SERVER_CONFIG
+    ssl_context = app_config.get_ssl_context()
+
+    use_single_process = server_config.single_process
+    if dev and use_single_process:
+        logger.info(
+            "Dev mode enabled: switching to multi-process mode to support auto-reload. "
+            "Set 'server.single_process = false' explicitly to suppress this message."
+        )
+        use_single_process = False
+    if getattr(sys, "frozen", False) and not use_single_process:
+        logger.warning(
+            "Auto-reload is not supported in the executable. Falling back to single-process mode."
+        )
+        use_single_process = True
+    if isinstance(ssl_context, SSLContext) and not use_single_process:
+        logger.warning(
+            "mTLS (ssl_ca_cert) requires single-process mode. "
+            "Ignoring 'single_process = false' and running in single-process mode."
+        )
+        use_single_process = True
+
+    common_kwargs: dict = {
+        "host": host,
+        "port": port,
+        "debug": app_config.DEBUG,
+        "access_log": True,
+        "ssl": ssl_context,
+        **server_config.run_kwargs,
+    }
+
+    try:
+        if use_single_process:
+            app.run(**common_kwargs, single_process=True)
+        else:
+            app.prepare(**common_kwargs, dev=dev)
+            Sanic.serve(primary=app, app_loader=loader)
+    except Exception as e:
+        raise click.ClickException(f"Server could not start: {e}") from e
+
+
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    metavar="PATH",
+    default="config.toml",
+    help="Path to the app config file",
+)
+@click.option("--username", type=str, help="Username (prompts if not provided)")
+@click.option("--password", type=str, help="Password (prompts if not provided)")
+def set_credentials(config_path, username, password):
+    """Set credentials for the TestBench Defect Service."""
+    configure_credentials_only(config_path, username=username, password=password)
+
+
+cli.add_command(init)
+cli.add_command(configure)
+cli.add_command(set_credentials)
+cli.add_command(start)
+
+if __name__ == "__main__":
+    cli()

testbench_defect_service/clients/__init__.py

@@ -0,0 +1,13 @@
+from testbench_defect_service.clients.abstract_client import AbstractDefectClient
+from testbench_defect_service.clients.jsonl.client import JsonlDefectClient
+
+try:  # noqa: SIM105
+    from testbench_defect_service.clients.jira.client import JiraDefectClient
+except ImportError:
+    pass
+
+__all__ = [
+    "AbstractDefectClient",
+    "JiraDefectClient",
+    "JsonlDefectClient",
+]

testbench_defect_service/clients/abstract_client.py

@@ -0,0 +1,244 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from testbench_defect_service.models.defects import (
+    Defect,
+    DefectID,
+    DefectWithAttributes,
+    Protocol,
+    ProtocolledDefectSet,
+    ProtocolledString,
+    Results,
+    Settings,
+    SyncContext,
+    UserDefinedAttribute,
+)
+
+
+class AbstractDefectClient(ABC):
+    """Base class for defect management system clients.
+
+    This abstract class defines the interface for integrating with various defect
+    management systems (e.g., Jira, JSONL). All implementations must conform to
+    the API3 Defect Management API specification.
+
+    Subclasses must:
+    - Set CONFIG_CLASS to their specific config model type (e.g., JiraDefectClientConfig)
+    - Implement all abstract methods
+    - Raise appropriate exceptions for error conditions (NotFound, ServerError, ValidationError)
+    - Handle authentication and authorization through the principal in Defect objects
+
+    Exception Guidelines:
+    - Raise sanic.NotFound for missing resources (projects, defects)
+    - Raise sanic.ServerError for client/server errors
+    - Raise pydantic.ValidationError for invalid data
+    """
+
+    # Subclasses must override this to specify their config model type
+    CONFIG_CLASS: ClassVar[type[BaseModel] | None] = None
+
+    @abstractmethod
+    def __init__(self, config: BaseModel):
+        """Initialize the defect client with validated configuration.
+
+        Args:
+            config: Validated configuration object (type specified by CONFIG_CLASS)
+        """
+
+    @abstractmethod
+    def check_login(self, project: str | None) -> bool:
+        """Check whether the current credentials are valid.
+
+        Args:
+            project (str | None): Optional project identifier to scope the credential check.
+                    If None, validates general system access.
+
+        Returns:
+            bool: True if credentials are valid, False otherwise.
+        """
+
+    @abstractmethod
+    def get_settings(self) -> Settings:
+        """Retrieve defect management system settings and metadata.
+
+        Returns:
+            Settings: object containing system name, description, and readonly status.
+        """
+
+    @abstractmethod
+    def get_projects(self) -> list[str]:
+        """Get list of all available project identifiers.
+
+        Returns:
+            list[str]: List of projects that the authenticated user can access.
+        """
+
+    @abstractmethod
+    def get_control_fields(self, project: str | None) -> dict[str, list[str]]:
+        """Return the allowed values for all defect control fields
+        (status, priority, classification).
+
+        Args:
+            project (str | None): Optional project identifier. If None, returns system-wide control fields.
+
+        Returns:
+            dict[str,list[str]]: Dictionary mapping each field name to its list of valid values.
+            Example: {"status": ["Open", "Closed"], "priority": ["High", "Low"]}
+        """  # noqa: E501
+
+    @abstractmethod
+    def get_defects(self, project: str, sync_context: SyncContext) -> ProtocolledDefectSet:
+        """Return all defects for a project together with a sync protocol.
+
+        Args:
+            project (str): Project identifier.
+            sync_context (SyncContext): Synchronization context containing sync options and filtering criteria.
+
+        Returns:
+            ProtocolledDefectSet: object containing defects and operation protocol messages.
+        """  # noqa: E501
+
+    @abstractmethod
+    def get_defects_batch(
+        self, project: str, defect_ids: list[DefectID], sync_context: SyncContext
+    ) -> ProtocolledDefectSet:
+        """Return a specific set of defects by their IDs.
+
+        Args:
+            project (str): Project identifier.
+            defect_ids (list[DefectID]): List of defect IDs to retrieve.
+            sync_context (SyncContext): Synchronization context for filtering and options.
+
+        Returns:
+            ProtocolledDefectSet: object containing the requested defects and protocol messages.
+        """
+
+    @abstractmethod
+    def create_defect(
+        self, project: str, defect: Defect, sync_context: SyncContext
+    ) -> ProtocolledString:
+        """Create a new defect in the specified project.
+
+        Args:
+            project (str): Project identifier where the defect will be created.
+            defect (Defect): Defect data including all required fields.
+            sync_context (SyncContext): Synchronization context for creation options.
+
+        Returns:
+            ProtocolledString: object containing the ID of the created defect and an operation protocol.
+        """  # noqa: E501
+
+    @abstractmethod
+    def update_defect(
+        self, project: str, defect_id: str, defect: Defect, sync_context: SyncContext
+    ) -> Protocol:
+        """Update an existing defect with new data.
+
+        Args:
+            project (str): Project identifier containing the defect.
+            defect_id (str): Unique identifier of the defect to update.
+            defect (Defect): Defect object carrying the updated field values.
+            sync_context (SyncContext): Synchronization context for update options.
+
+        Returns:
+            Protocol: object containing the operation result and any messages.
+        """
+
+    @abstractmethod
+    def delete_defect(
+        self, project: str, defect_id: str, defect: Defect, sync_context: SyncContext
+    ) -> Protocol:
+        """Delete an existing defect.
+
+        Args:
+            project (str): Project identifier containing the defect.
+            defect_id (str): Unique identifier of the defect to delete.
+            defect (Defect): Defect object carrying principal/authorization information.
+            sync_context (SyncContext): Synchronization context for deletion options.
+
+        Returns:
+            Protocol: object containing the operation result and any messages.
+        """
+
+    @abstractmethod
+    def get_defect_extended(
+        self, project: str, defect_id: str, sync_context: SyncContext
+    ) -> DefectWithAttributes:
+        """Return a defect together with its extended system-specific attributes.
+
+        Args:
+            project (str): Project identifier containing the defect.
+            defect_id (str): Unique identifier of the defect.
+            sync_context (SyncContext): Synchronization context used to determine which attributes to include.
+
+        Returns:
+            DefectWithAttributes: object containing the full defect data plus extended attributes.
+        """  # noqa: E501
+
+    @abstractmethod
+    def get_user_defined_attributes(self, project: str | None) -> list[UserDefinedAttribute]:
+        """Return the user-defined field definitions for a project.
+
+        Args:
+            project (str | None): Optional project identifier. If None, returns system-wide definitions.
+
+        Returns:
+            list[UserDefinedAttribute]: List of user-defined attribute definitions including their value types and constraints.
+        """  # noqa: E501
+
+    @abstractmethod
+    def before_sync(self, project: str, sync_type: str, sync_context: SyncContext) -> Protocol:
+        """Run pre-synchronization setup and validation hooks.
+
+        Called once before a sync operation begins. Implementations may use this
+        to acquire locks, validate state, or perform any required setup.
+
+        Args:
+            project (str): Project identifier to synchronize.
+            sync_type (str): Type of synchronization operation being started.
+            sync_context (SyncContext): Synchronization context and options.
+
+        Returns:
+            Protocol: object containing pre-sync validation results and messages.
+        """
+
+    @abstractmethod
+    def after_sync(self, project: str, sync_type: str, sync_context: SyncContext) -> Protocol:
+        """Run post-synchronization cleanup and finalization hooks.
+
+        Called once after a sync operation completes. Implementations may use this
+        to release locks, persist state, or perform any required cleanup.
+
+        Args:
+            project (str): Project identifier that was synchronized.
+            sync_type (str): Type of synchronization operation that completed.
+            sync_context (SyncContext): Synchronization context and options.
+
+        Returns:
+            Protocol: object containing post-sync results and messages.
+        """
+
+    @abstractmethod
+    def supports_changes_timestamps(self) -> bool:
+        """Return whether the defect management system supports change timestamps.
+
+        Returns:
+            bool: True if change tracking with timestamps is supported, False otherwise.
+        """
+
+    @abstractmethod
+    def correct_sync_results(self, project: str, body: Results) -> Results:
+        """Review and correct proposed synchronization changes before they are applied.
+
+        Allows the defect management system to filter, adjust, or reject individual
+        sync actions in the proposed change set.
+
+        Args:
+            project (str): Project identifier for the sync operation.
+            body (Results): Proposed sync actions for local and remote changes.
+
+        Returns:
+            Results: object with corrected/validated sync actions.
+        """