gitwebhooks 2.0.0__py3-none-any.whl

gitwebhooks/config/models.py

@@ -0,0 +1,145 @@
+"""Configuration data models
+
+Defines configuration-related dataclasses.
+"""
+
+import configparser
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.utils.exceptions import ConfigurationError
+
+
+@dataclass
+class ProviderConfig:
+    """Git platform provider configuration
+
+    Attributes:
+        provider: Provider type
+        verify: Whether to verify signature/token
+        secret: Secret key for verification
+        handle_events: List of events to handle (empty list = handle all events)
+        header_name: Custom identification header (CUSTOM only)
+        header_value: Custom identification value (CUSTOM only)
+        header_event: Custom event header (CUSTOM only)
+        header_token: Custom token header (CUSTOM only)
+        identifier_path: Repository identifier JSON path (CUSTOM only)
+    """
+    provider: Provider
+    verify: bool
+    secret: str
+    handle_events: List[str]
+
+    # Custom provider only
+    header_name: str = ''
+    header_value: str = ''
+    header_event: str = ''
+    header_token: str = ''
+    identifier_path: str = ''
+
+    @classmethod
+    def from_config_parser(cls, parser: configparser.ConfigParser,
+                          provider: Provider) -> 'ProviderConfig':
+        """Load provider configuration from ConfigParser
+
+        Args:
+            parser: ConfigParser instance
+            provider: Provider type
+
+        Returns:
+            ProviderConfig instance
+
+        Raises:
+            configparser.NoSectionError: Configuration section does not exist
+        """
+        section = provider.value
+        handle_events_str = parser.get(section, 'handle_events',
+                                       fallback='').strip()
+        handle_events = [e.strip() for e in handle_events_str.split(',')
+                        if e.strip()] if handle_events_str else []
+
+        config = cls(
+            provider=provider,
+            verify=parser.getboolean(section, 'verify', fallback=False),
+            secret=parser.get(section, 'secret', fallback=''),
+            handle_events=handle_events
+        )
+
+        # Custom provider additional fields
+        if provider == Provider.CUSTOM:
+            config.header_name = parser.get(section, 'header_name',
+                                           fallback='X-Custom-Webhook')
+            config.header_value = parser.get(section, 'header_value',
+                                            fallback='custom')
+            config.header_event = parser.get(section, 'header_event',
+                                            fallback='X-Custom-Event')
+            config.header_token = parser.get(section, 'header_token',
+                                            fallback='X-Custom-Token')
+            config.identifier_path = parser.get(section, 'identifier_path',
+                                               fallback='')
+
+        return config
+
+    def allows_event(self, event: str) -> bool:
+        """Check if an event is allowed to be handled
+
+        Args:
+            event: Event type (None means all events)
+
+        Returns:
+            True if event is allowed, False otherwise
+        """
+        if not self.handle_events:
+            return True  # Empty list = handle all events
+        return event in self.handle_events
+
+
+@dataclass
+class RepositoryConfig:
+    """Repository deployment configuration
+
+    Attributes:
+        name: Repository name (format: 'owner/repo' or 'group/project/repo')
+        cwd: Working directory for deployment command execution
+        cmd: Deployment command (shell string)
+    """
+    name: str
+    cwd: str
+    cmd: str
+
+    @classmethod
+    def from_config_parser(cls, parser: configparser.ConfigParser,
+                          name: str):
+        """Load repository configuration from ConfigParser
+
+        Args:
+            parser: ConfigParser instance
+            name: Configuration section name (repository name)
+
+        Returns:
+            RepositoryConfig instance, or None if section does not exist
+
+        Raises:
+            configparser.NoOptionError: Section exists but missing required options
+        """
+        if not parser.has_section(name):
+            return None
+
+        return cls(
+            name=name,
+            cwd=parser.get(name, 'cwd'),
+            cmd=parser.get(name, 'cmd')
+        )
+
+    def validate(self) -> None:
+        """Validate configuration
+
+        Raises:
+            ConfigurationError: Configuration is invalid
+        """
+        if not self.cwd:
+            raise ConfigurationError(f'Repository {self.name}: cwd is required')
+        if not self.cmd:
+            raise ConfigurationError(f'Repository {self.name}: cmd is required')

gitwebhooks/config/registry.py

@@ -0,0 +1,104 @@
+"""Configuration registry
+
+Holds all configuration and provides access interface.
+"""
+
+from typing import Dict
+
+from gitwebhooks.config.loader import ConfigLoader
+from gitwebhooks.config.models import ProviderConfig, RepositoryConfig
+from gitwebhooks.config.server import ServerConfig
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.utils.exceptions import ConfigurationError
+
+
+class ConfigurationRegistry:
+    """Configuration registry
+
+    Holds all configuration and provides access interface
+    """
+
+    def __init__(self, loader: ConfigLoader):
+        """Initialize configuration registry
+
+        Args:
+            loader: Configuration loader instance
+        """
+        self.loader = loader
+        self._server_config = None
+        self._provider_configs = None
+        self._repository_configs = None
+        self._load_all_configs()
+
+    def _load_all_configs(self) -> None:
+        """Load all configurations
+
+        Raises:
+            ConfigurationError: Configuration loading or validation failed
+        """
+        self._server_config = ServerConfig.from_loader(self.loader)
+        self._server_config.validate()
+
+        self._provider_configs = self.loader.load_all_provider_configs()
+        self._repository_configs = self.loader.load_all_repository_configs()
+
+        self.loader.validate_repository_configs()
+
+    @property
+    def server_config(self) -> ServerConfig:
+        """Get server configuration"""
+        if self._server_config is None:
+            raise ConfigurationError('Server config not loaded')
+        return self._server_config
+
+    @property
+    def provider_configs(self) -> Dict[Provider, ProviderConfig]:
+        """Get provider configuration dictionary"""
+        if self._provider_configs is None:
+            raise ConfigurationError('Provider configs not loaded')
+        return self._provider_configs
+
+    @property
+    def repository_configs(self) -> Dict[str, RepositoryConfig]:
+        """Get repository configuration dictionary"""
+        if self._repository_configs is None:
+            raise ConfigurationError('Repository configs not loaded')
+        return self._repository_configs
+
+    def get_provider_config(self, provider: Provider) -> ProviderConfig:
+        """Get configuration for specified provider
+
+        Args:
+            provider: Provider type
+
+        Returns:
+            ProviderConfig instance
+        """
+        return self.provider_configs.get(provider, ProviderConfig(
+            provider=provider,
+            verify=False,
+            secret='',
+            handle_events=[]
+        ))
+
+    def get_repository_config(self, name: str) -> RepositoryConfig:
+        """Get configuration for specified repository
+
+        Args:
+            name: Repository name
+
+        Returns:
+            RepositoryConfig instance, or None if not found
+        """
+        return self.repository_configs.get(name)
+
+    def has_repository(self, name: str) -> bool:
+        """Check if repository exists
+
+        Args:
+            name: Repository name
+
+        Returns:
+            True if exists, False otherwise
+        """
+        return name in self.repository_configs

gitwebhooks/config/server.py

@@ -0,0 +1,85 @@
+"""Server configuration
+
+Defines server-related configuration dataclasses.
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional
+
+from gitwebhooks.utils.exceptions import ConfigurationError
+
+
+@dataclass
+class ServerConfig:
+    """Server configuration
+
+    Attributes:
+        address: Listen address
+        port: Listen port
+        log_file: Log file path (empty string means no file logging)
+        ssl_enabled: Whether SSL is enabled
+        ssl_key_file: SSL key file path
+        ssl_cert_file: SSL certificate file path
+    """
+    address: str
+    port: int
+    log_file: str
+    ssl_enabled: bool = False
+    ssl_key_file: Optional[str] = None
+    ssl_cert_file: Optional[str] = None
+
+    @classmethod
+    def from_loader(cls, loader: 'ConfigLoader') -> 'ServerConfig':
+        """Create server configuration from ConfigLoader
+
+        Args:
+            loader: Configuration loader instance
+
+        Returns:
+            ServerConfig instance
+        """
+        server_cfg = loader.get_server_config()
+        ssl_cfg = loader.get_ssl_config()
+
+        return cls(
+            address=server_cfg['address'],
+            port=server_cfg['port'],
+            log_file=server_cfg['log_file'],
+            ssl_enabled=ssl_cfg is not None,
+            ssl_key_file=ssl_cfg['key_file'] if ssl_cfg else None,
+            ssl_cert_file=ssl_cfg['cert_file'] if ssl_cfg else None,
+        )
+
+    def validate(self) -> None:
+        """Validate server configuration
+
+        Raises:
+            ConfigurationError: Configuration is invalid
+        """
+        if self.ssl_enabled:
+            if not self.ssl_key_file:
+                raise ConfigurationError('SSL enabled but key_file not specified')
+            if not self.ssl_cert_file:
+                raise ConfigurationError('SSL enabled but cert_file not specified')
+
+            # Verify files exist
+            key_path = Path(self.ssl_key_file)
+            cert_path = Path(self.ssl_cert_file)
+
+            if not key_path.exists():
+                raise ConfigurationError(f'SSL key file not found: {self.ssl_key_file}')
+            if not cert_path.exists():
+                raise ConfigurationError(f'SSL cert file not found: {self.ssl_cert_file}')
+
+        # Validate port range
+        if not (1 <= self.port <= 65535):
+            raise ConfigurationError(f'Invalid port number: {self.port}')
+
+        # Validate log file writable (if specified)
+        if self.log_file:
+            log_path = Path(self.log_file)
+            parent_dir = log_path.parent
+            if parent_dir.exists() and not os.access(parent_dir, os.W_OK):
+                raise ConfigurationError(f'Log directory not writable: {parent_dir}')

gitwebhooks/handlers/__init__.py

@@ -0,0 +1,22 @@
+"""Webhook handlers module
+
+Handles webhook requests from different Git platforms.
+"""
+
+from .base import WebhookHandler
+from .github import GithubHandler
+from .gitee import GiteeHandler
+from .gitlab import GitlabHandler
+from .custom import CustomHandler
+from .factory import HandlerFactory
+from .request import WebhookRequestHandler
+
+__all__ = [
+    'WebhookHandler',
+    'GithubHandler',
+    'GiteeHandler',
+    'GitlabHandler',
+    'CustomHandler',
+    'HandlerFactory',
+    'WebhookRequestHandler',
+]

gitwebhooks/handlers/base.py

@@ -0,0 +1,107 @@
+"""Handler base class
+
+Defines the abstract interface for webhook handlers.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.models.request import WebhookRequest
+from gitwebhooks.models.result import SignatureVerificationResult
+from gitwebhooks.config.models import ProviderConfig
+from gitwebhooks.utils.exceptions import SignatureValidationError, UnsupportedEventError
+
+
+class WebhookHandler(ABC):
+    """Webhook handler base class
+
+    All platform-specific handlers must inherit from this class and implement all abstract methods.
+    """
+
+    @abstractmethod
+    def get_provider(self) -> Provider:
+        """Return the provider type supported by this handler
+
+        Returns:
+            Provider enum value
+        """
+        pass
+
+    @abstractmethod
+    def verify_signature(self, request: WebhookRequest,
+                        config: ProviderConfig) -> SignatureVerificationResult:
+        """Verify webhook signature
+
+        Args:
+            request: Webhook request data
+            config: Provider configuration (includes secret)
+
+        Returns:
+            Signature verification result
+
+        Raises:
+            SignatureValidationError: When verification fails
+        """
+        pass
+
+    @abstractmethod
+    def extract_repository(self, request: WebhookRequest,
+                          config: ProviderConfig) -> Optional[str]:
+        """Extract repository identifier from request
+
+        Args:
+            request: Webhook request data
+            config: Provider configuration (may include identifier_path)
+
+        Returns:
+            Repository identifier (e.g., 'owner/repo'), None if not found
+        """
+        pass
+
+    @abstractmethod
+    def is_event_allowed(self, event: Optional[str],
+                        config: ProviderConfig) -> bool:
+        """Check if event type is allowed to be handled
+
+        Args:
+            event: Event type (e.g., 'push', 'merge_request')
+            config: Provider configuration (includes handle_events list)
+
+        Returns:
+            True if event is allowed, False otherwise
+        """
+        pass
+
+    def handle_request(self, request: WebhookRequest,
+                      config: ProviderConfig) -> Optional[str]:
+        """Handle complete webhook request
+
+        This is a template method that defines the fixed flow of request processing:
+        1. Check if event is allowed
+        2. Verify signature
+        3. Extract repository identifier
+
+        Args:
+            request: Webhook request data
+            config: Provider configuration
+
+        Returns:
+            Repository identifier, None if processing failed
+
+        Raises:
+            SignatureValidationError: Signature verification failed
+            UnsupportedEventError: Event type not allowed
+        """
+        # Step 1: Check event
+        if not self.is_event_allowed(request.event, config):
+            raise UnsupportedEventError(f'Event not configured: {request.event}')
+
+        # Step 2: Verify signature (if required)
+        if config.verify:
+            result = self.verify_signature(request, config)
+            if not result.is_valid:
+                raise SignatureValidationError(result.error_message or 'Verification failed')
+
+        # Step 3: Extract repository identifier
+        return self.extract_repository(request, config)

gitwebhooks/handlers/custom.py

@@ -0,0 +1,73 @@
+"""Custom webhook handler
+
+Handles webhook requests from custom webhook sources.
+"""
+
+from typing import Optional
+
+from gitwebhooks.handlers.base import WebhookHandler
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.models.request import WebhookRequest
+from gitwebhooks.models.result import SignatureVerificationResult
+from gitwebhooks.config.models import ProviderConfig
+from gitwebhooks.auth.factory import VerifierFactory
+
+
+class CustomHandler(WebhookHandler):
+    """Custom webhook handler"""
+
+    def __init__(self):
+        self._verifier = None  # Created dynamically based on configuration
+
+    def get_provider(self) -> Provider:
+        """Return Provider.CUSTOM"""
+        return Provider.CUSTOM
+
+    def verify_signature(self, request: WebhookRequest,
+                        config: ProviderConfig) -> SignatureVerificationResult:
+        """Verify custom token"""
+        # Create verifier (verification enabled depends on whether header_token is configured)
+        verify_enabled = bool(config.header_token)
+        if not self._verifier:
+            self._verifier = VerifierFactory.create_custom_verifier(verify_enabled)
+
+        signature = request.headers.get(config.header_token) if config.header_token else ''
+        return self._verifier.verify(request.payload, signature, config.secret)
+
+    def extract_repository(self, request: WebhookRequest,
+                          config: ProviderConfig) -> Optional[str]:
+        """Extract repository identifier using JSON path"""
+        if request.post_data is None or not config.identifier_path:
+            return None
+
+        # Split path by '.'
+        path_parts = config.identifier_path.split('.')
+        current = request.post_data
+
+        # Traverse level by level
+        for part in path_parts:
+            if isinstance(current, dict):
+                current = current.get(part)
+            else:
+                return None
+
+        # Return final value (must be string)
+        return current if isinstance(current, str) else None
+
+    def is_event_allowed(self, event: Optional[str],
+                        config: ProviderConfig) -> bool:
+        """Check if event is allowed
+
+        Args:
+            event: Event type (already parsed from headers by caller)
+            config: Provider configuration
+
+        Returns:
+            True if event is allowed, False otherwise
+        """
+        # If no event header configured, allow all events
+        if not config.header_event:
+            return config.allows_event(event)
+
+        # Use the passed event parameter (already parsed from headers by caller)
+        return config.allows_event(event)

gitwebhooks/handlers/factory.py

@@ -0,0 +1,83 @@
+"""Handler factory class
+
+Creates corresponding handler instances based on request headers.
+"""
+
+from typing import Dict
+
+from gitwebhooks.handlers.base import WebhookHandler
+from gitwebhooks.handlers.github import GithubHandler
+from gitwebhooks.handlers.gitee import GiteeHandler
+from gitwebhooks.handlers.gitlab import GitlabHandler
+from gitwebhooks.handlers.custom import CustomHandler
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.config.models import ProviderConfig
+from gitwebhooks.utils.exceptions import UnsupportedProviderError
+
+
+class HandlerFactory:
+    """Handler factory class
+
+    Creates corresponding handler instances based on request headers
+    """
+
+    @staticmethod
+    def from_headers(headers: Dict[str, str],
+                    configs: Dict[Provider, ProviderConfig]) -> WebhookHandler:
+        """Create handler based on request headers
+
+        Args:
+            headers: HTTP request header dictionary
+            configs: Provider configuration dictionary
+
+        Returns:
+            Corresponding WebhookHandler instance
+
+        Raises:
+            UnsupportedProviderError: Unrecognized platform
+        """
+        # Check X-GitHub-Event
+        if 'X-GitHub-Event' in headers:
+            return GithubHandler()
+
+        # Check X-Gitee-Event
+        if 'X-Gitee-Event' in headers:
+            return GiteeHandler()
+
+        # Check X-Gitlab-Event
+        if 'X-Gitlab-Event' in headers:
+            return GitlabHandler()
+
+        # Check custom header
+        custom_config = configs.get(Provider.CUSTOM)
+        if custom_config and custom_config.header_name:
+            if headers.get(custom_config.header_name) == custom_config.header_value:
+                return CustomHandler()
+
+        raise UnsupportedProviderError('Unable to identify provider from headers')
+
+    @staticmethod
+    def from_handler_type(provider: Provider) -> WebhookHandler:
+        """Create handler based on provider type
+
+        Args:
+            provider: Provider type
+
+        Returns:
+            Corresponding WebhookHandler instance
+
+        Raises:
+            UnsupportedProviderError: Unsupported provider
+        """
+        handlers = {
+            Provider.GITHUB: GithubHandler,
+            Provider.GITEE: GiteeHandler,
+            Provider.GITLAB: GitlabHandler,
+            Provider.CUSTOM: CustomHandler,
+        }
+
+        handler_class = handlers.get(provider)
+        if handler_class is None:
+            raise UnsupportedProviderError(f'No handler for provider: {provider}')
+
+        return handler_class()