gitwebhooks 2.0.0__py3-none-any.whl

gitwebhooks/handlers/gitee.py

@@ -0,0 +1,113 @@
+"""Gitee webhook handler
+
+Handles webhook requests from Gitee.
+
+Gitee supports two authentication modes:
+1. Signature mode: X-Gitee-Timestamp + X-Gitee-Token (HMAC-SHA256)
+2. Password mode: X-Gitee-Token only (plaintext)
+
+According to Gitee documentation:
+https://help.gitee.com/webhook/how-to-verify-webhook-keys
+
+Even when verify=False, if a password is provided (no timestamp),
+it should still be validated for security.
+"""
+
+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
+from gitwebhooks.utils.exceptions import SignatureValidationError, UnsupportedEventError
+
+
+class GiteeHandler(WebhookHandler):
+    """Gitee webhook handler"""
+
+    def __init__(self):
+        self._verifier = VerifierFactory.create_gitee_verifier()
+
+    def get_provider(self) -> Provider:
+        """Return Provider.GITEE"""
+        return Provider.GITEE
+
+    def verify_signature(self, request: WebhookRequest,
+                        config: ProviderConfig) -> SignatureVerificationResult:
+        """Verify Gitee signature or password
+
+        Gitee has two modes:
+        1. Signature mode: Has X-Gitee-Timestamp header
+        2. Password mode: Only X-Gitee-Token header
+
+        Args:
+            request: Webhook request
+            config: Provider configuration
+
+        Returns:
+            SignatureVerificationResult instance
+        """
+        signature = request.headers.get('X-Gitee-Token')
+        timestamp = request.headers.get('X-Gitee-Timestamp')
+
+        # Always validate if signature/token is provided
+        if signature is None:
+            return SignatureVerificationResult.failure('Missing signature or password')
+
+        return self._verifier.verify(
+            request.payload,
+            signature,
+            config.secret,
+            timestamp=timestamp
+        )
+
+    def handle_request(self, request: WebhookRequest,
+                      config: ProviderConfig) -> Optional[str]:
+        """Handle complete webhook request
+
+        Override base implementation to handle Gitee's special case:
+        Even when verify=False, password validation is performed if provided.
+
+        Args:
+            request: Webhook request data
+            config: Provider configuration
+
+        Returns:
+            Repository identifier, None if processing failed
+
+        Raises:
+            SignatureValidationError: Signature/password 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 or password
+        # For Gitee, we always validate if token is provided
+        signature = request.headers.get('X-Gitee-Token')
+        if signature is not None:
+            result = self.verify_signature(request, config)
+            if not result.is_valid:
+                raise SignatureValidationError(result.error_message or 'Verification failed')
+        elif config.verify:
+            # verify=True but no signature provided
+            raise SignatureValidationError('Missing signature')
+
+        # Step 3: Extract repository identifier
+        return self.extract_repository(request, config)
+
+    def extract_repository(self, request: WebhookRequest,
+                          config: ProviderConfig) -> Optional[str]:
+        """Extract Gitee repository full name from request"""
+        if request.post_data is None:
+            return None
+        repo = request.post_data.get('repository', {})
+        return repo.get('full_name') if isinstance(repo, dict) else None
+
+    def is_event_allowed(self, event: Optional[str],
+                        config: ProviderConfig) -> bool:
+        """Check if event is in config.handle_events list"""
+        return config.allows_event(event)

gitwebhooks/handlers/github.py

@@ -0,0 +1,43 @@
+"""GitHub webhook handler
+
+Handles webhook requests from GitHub.
+"""
+
+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 GithubHandler(WebhookHandler):
+    """GitHub webhook handler"""
+
+    def __init__(self):
+        self._verifier = VerifierFactory.create_github_verifier()
+
+    def get_provider(self) -> Provider:
+        """Return Provider.GITHUB"""
+        return Provider.GITHUB
+
+    def verify_signature(self, request: WebhookRequest,
+                        config: ProviderConfig) -> SignatureVerificationResult:
+        """Verify GitHub HMAC-SHA1 signature"""
+        signature = request.headers.get('X-Hub-Signature')
+        return self._verifier.verify(request.payload, signature, config.secret)
+
+    def extract_repository(self, request: WebhookRequest,
+                          config: ProviderConfig) -> Optional[str]:
+        """Extract GitHub repository full name from request"""
+        if request.post_data is None:
+            return None
+        repo = request.post_data.get('repository', {})
+        return repo.get('full_name') if isinstance(repo, dict) else None
+
+    def is_event_allowed(self, event: Optional[str],
+                        config: ProviderConfig) -> bool:
+        """Check if event is in config.handle_events list"""
+        return config.allows_event(event)

gitwebhooks/handlers/gitlab.py

@@ -0,0 +1,43 @@
+"""GitLab webhook handler
+
+Handles webhook requests from GitLab.
+"""
+
+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 GitlabHandler(WebhookHandler):
+    """GitLab webhook handler"""
+
+    def __init__(self):
+        self._verifier = VerifierFactory.create_gitlab_verifier()
+
+    def get_provider(self) -> Provider:
+        """Return Provider.GITLAB"""
+        return Provider.GITLAB
+
+    def verify_signature(self, request: WebhookRequest,
+                        config: ProviderConfig) -> SignatureVerificationResult:
+        """Verify GitLab token"""
+        signature = request.headers.get('X-Gitlab-Token')
+        return self._verifier.verify(request.payload, signature, config.secret)
+
+    def extract_repository(self, request: WebhookRequest,
+                          config: ProviderConfig) -> Optional[str]:
+        """Extract GitLab project path from request"""
+        if request.post_data is None:
+            return None
+        project = request.post_data.get('project', {})
+        return project.get('path_with_namespace') if isinstance(project, dict) else None
+
+    def is_event_allowed(self, event: Optional[str],
+                        config: ProviderConfig) -> bool:
+        """Check if event is in config.handle_events list"""
+        return config.allows_event(event)

gitwebhooks/handlers/request.py

@@ -0,0 +1,248 @@
+"""HTTP request handler
+
+Handles webhook endpoint for HTTP POST requests.
+"""
+
+import json
+import logging
+from http.server import BaseHTTPRequestHandler
+from typing import Dict, Optional
+from urllib.parse import parse_qs
+
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.models.request import WebhookRequest
+from gitwebhooks.config.models import ProviderConfig, RepositoryConfig
+from gitwebhooks.handlers.factory import HandlerFactory
+from gitwebhooks.utils.constants import *
+from gitwebhooks.utils.exceptions import *
+from gitwebhooks.utils.executor import execute_deployment
+
+
+class WebhookRequestHandler(BaseHTTPRequestHandler):
+    """Webhook request handler
+
+    Handles HTTP POST requests, verifies signatures, triggers deployment commands.
+    """
+
+    # Class variables: configuration injection
+    _provider_configs: Dict[Provider, ProviderConfig] = {}
+    _repository_configs: Dict[str, RepositoryConfig] = {}
+
+    @classmethod
+    def configure(cls, provider_configs: Dict[Provider, ProviderConfig],
+                 repository_configs: Dict[str, RepositoryConfig]) -> None:
+        """Configure handler class (dependency injection)
+
+        Args:
+            provider_configs: Provider configuration dictionary
+            repository_configs: Repository configuration dictionary
+        """
+        cls._provider_configs = provider_configs
+        cls._repository_configs = repository_configs
+
+    def __init__(self, request, client_address, server):
+        """Initialize request handler
+
+        Args:
+            request: HTTP request
+            client_address: Client address
+            server: Server instance
+        """
+        # Copy class-level config to instance (avoid shared state)
+        self._provider_configs = self.__class__._provider_configs.copy()
+        self._repository_configs = self.__class__._repository_configs.copy()
+        super().__init__(request, client_address, server)
+
+    def do_GET(self) -> None:
+        """Handle GET request
+
+        All GET requests return 403 Forbidden
+        """
+        self.send_error(HTTP_FORBIDDEN, MESSAGE_FORBIDDEN)
+
+    def do_POST(self) -> None:
+        """Handle POST request (webhook endpoint)
+
+        Implementation flow:
+        1. Parse request body
+        2. Identify provider and event
+        3. Create corresponding handler
+        4. Verify signature
+        5. Extract repository identifier
+        6. Execute deployment command
+        7. Send response
+
+        All errors are caught and appropriate HTTP status codes are returned
+        """
+        try:
+            # Step 1: Parse request body
+            try:
+                request = self._parse_request()
+            except RequestParseError as e:
+                logging.warning('Request parse failed: %s', e)
+                self._send_error(HTTP_BAD_REQUEST, MESSAGE_BAD_REQUEST)
+                return
+
+            if request.post_data is None:
+                logging.warning('Unsupported request format')
+                self._send_error(HTTP_BAD_REQUEST, MESSAGE_BAD_REQUEST)
+                return
+
+            # Step 2: Identify provider
+            provider = self._identify_provider(request)
+            if provider is None:
+                logging.warning('Unknown provider')
+                self._send_error(HTTP_PRECONDITION_FAILED, MESSAGE_PRECONDITION_FAILED)
+                return
+
+            # Step 3: Create handler
+            handler = HandlerFactory.from_handler_type(provider)
+
+            # Steps 4-6: Process request
+            try:
+                provider_config = self._provider_configs.get(provider)
+                if not provider_config:
+                    raise UnsupportedProviderError(f'{provider} configuration not found')
+
+                repo_name = handler.handle_request(request, provider_config)
+
+            except (SignatureValidationError, UnsupportedEventError,
+                   UnsupportedProviderError) as e:
+                logging.warning('Webhook processing error: %s', e)
+                if isinstance(e, SignatureValidationError):
+                    self._send_error(HTTP_UNAUTHORIZED, MESSAGE_UNAUTHORIZED)
+                elif isinstance(e, UnsupportedEventError):
+                    self._send_error(HTTP_NOT_ACCEPTABLE, MESSAGE_NOT_ACCEPTABLE)
+                else:
+                    self._send_error(HTTP_PRECONDITION_FAILED, MESSAGE_PRECONDITION_FAILED)
+                return
+
+            # Step 7: Execute deployment command
+            if repo_name:
+                repo_config = self._repository_configs.get(repo_name)
+                if not repo_config:
+                    logging.warning('No repository configuration: %s', repo_name)
+                    self._send_error(HTTP_NOT_FOUND, MESSAGE_NOT_FOUND)
+                    return
+
+                execute_deployment(repo_name, repo_config.cwd, repo_config.cmd)
+                self._send_response(HTTP_OK)
+            else:
+                logging.warning('Repository information missing from payload')
+                self._send_error(HTTP_NOT_FOUND, MESSAGE_NOT_FOUND)
+
+        except Exception as e:
+            logging.error('Unexpected error processing webhook: %s', e)
+            self._send_error(HTTP_INTERNAL_SERVER_ERROR, MESSAGE_INTERNAL_SERVER_ERROR)
+
+    def _parse_request(self) -> WebhookRequest:
+        """Parse HTTP request
+
+        Returns:
+            WebhookRequest instance
+
+        Raises:
+            RequestParseError: Parsing failed
+        """
+        # Get Content-Type and Content-Length
+        content_type = self.headers.get(HEADER_CONTENT_TYPE, '')
+        content_length = int(self.headers.get(HEADER_CONTENT_LENGTH, 0))
+
+        # Read request body
+        if content_length == 0:
+            raise RequestParseError('Empty request body')
+
+        payload = self.rfile.read(content_length)
+
+        # Parse POST data
+        post_data = None
+        if CONTENT_TYPE_JSON in content_type:
+            try:
+                post_data = json.loads(payload.decode('utf-8'))
+            except (json.JSONDecodeError, UnicodeDecodeError) as e:
+                raise RequestParseError(f'Invalid JSON: {e}')
+        elif CONTENT_TYPE_FORM_URLENCODED in content_type:
+            try:
+                post_data = {k: v[0] if v else None for k, v in parse_qs(payload.decode('utf-8')).items()}
+            except UnicodeDecodeError as e:
+                raise RequestParseError(f'Invalid form data: {e}')
+
+        # Identify provider and event
+        provider, event = self._parse_provider_and_event()
+
+        return WebhookRequest(
+            provider=provider,
+            event=event,
+            payload=payload,
+            headers=dict(self.headers),
+            post_data=post_data,
+            content_type=content_type,
+            content_length=content_length
+        )
+
+    def _parse_provider_and_event(self) -> tuple:
+        """Parse provider and event from request headers
+
+        Returns:
+            Tuple of (provider, event)
+        """
+        headers_dict = dict(self.headers)
+
+        # GitHub
+        if HEADER_GITHUB_EVENT in headers_dict:
+            return Provider.GITHUB, headers_dict.get(HEADER_GITHUB_EVENT)
+
+        # Gitee
+        if HEADER_GITEE_EVENT in headers_dict:
+            return Provider.GITEE, headers_dict.get(HEADER_GITEE_EVENT)
+
+        # GitLab
+        if HEADER_GITLAB_EVENT in headers_dict:
+            return Provider.GITLAB, headers_dict.get(HEADER_GITLAB_EVENT)
+
+        # Custom
+        custom_config = self._provider_configs.get(Provider.CUSTOM)
+        if custom_config and custom_config.header_name:
+            header_value = headers_dict.get(custom_config.header_name, '')
+            if header_value.startswith(custom_config.header_value):
+                event = headers_dict.get(custom_config.header_event) if custom_config.header_event else None
+                return Provider.CUSTOM, event
+
+        # Unable to identify
+        return None, None
+
+    def _identify_provider(self, request: WebhookRequest) -> Optional[Provider]:
+        """Identify provider from request
+
+        Args:
+            request: Webhook request
+
+        Returns:
+            Provider enum value, None if unable to identify
+        """
+        return request.provider
+
+    def _send_response(self, status_code: int, message: bytes = MESSAGE_OK) -> None:
+        """Send HTTP response
+
+        Args:
+            status_code: HTTP status code
+            message: Response body
+        """
+        self.send_response(status_code)
+        self.send_header('Content-Type', 'text/plain')
+        self.end_headers()
+        self.wfile.write(message)
+
+    def _send_error(self, status_code: int, message: str = '') -> None:
+        """Send HTTP error response
+
+        Args:
+            status_code: HTTP status code
+            message: Error message
+        """
+        self.send_error(status_code, message)
+
+    def log_message(self, format: str, *args) -> None:
+        """Override to prevent duplicate logging"""
+        pass

gitwebhooks/logging/__init__.py

@@ -0,0 +1,10 @@
+"""Logging configuration module
+
+Configures application logging system.
+"""
+
+from .setup import setup_logging
+
+__all__ = [
+    'setup_logging',
+]

gitwebhooks/logging/setup.py

@@ -0,0 +1,57 @@
+"""日志配置
+
+配置应用程序日志系统。
+"""
+
+import logging
+import sys
+
+
+def setup_logging(log_file: str = None):
+    """配置日志系统
+
+    Args:
+        log_file: 日志文件路径（空字符串表示不记录到文件）
+
+    根据配置设置日志记录：
+    - 如果 log_file 为空，只输出到 stdout
+    - 如果 log_file 非空，同时输出到文件和 stdout
+
+    Note:
+        Python 3.8+ 使用 force 参数确保重新配置，
+        早期版本手动清除现有 handlers。
+    """
+    handlers = []
+
+    # 文件处理器
+    if log_file:
+        file_handler = logging.FileHandler(log_file, encoding='utf-8')
+        file_handler.setFormatter(logging.Formatter(
+            '%(asctime)s %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        ))
+        handlers.append(file_handler)
+
+    # 控制台处理器
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(logging.Formatter(
+        '%(asctime)s %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    ))
+    handlers.append(console_handler)
+
+    # 配置根日志记录器
+    # Python 3.8+ 支持 force 参数
+    basic_config_kwargs = {
+        'level': logging.DEBUG,
+        'handlers': handlers,
+    }
+    if sys.version_info >= (3, 8):
+        basic_config_kwargs['force'] = True
+    else:
+        # 早期版本：手动清除现有 handlers
+        root_logger = logging.getLogger()
+        for handler in root_logger.handlers[:]:
+            root_logger.removeHandler(handler)
+
+    logging.basicConfig(**basic_config_kwargs)

gitwebhooks/models/__init__.py

@@ -0,0 +1,14 @@
+"""Data models module
+
+Defines core data types and enumerations.
+"""
+
+from .provider import Provider
+from .request import WebhookRequest
+from .result import SignatureVerificationResult
+
+__all__ = [
+    'Provider',
+    'WebhookRequest',
+    'SignatureVerificationResult',
+]

gitwebhooks/models/provider.py

@@ -0,0 +1,22 @@
+"""Git platform provider enumeration
+
+Defines supported Git hosting platform types.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class Provider(Enum):
+    """Git platform provider type
+
+    Supported Git hosting platforms:
+    - GITHUB: GitHub platform
+    - GITEE: Gitee platform (China)
+    - GITLAB: GitLab platform
+    - CUSTOM: Custom webhook platform
+    """
+    GITHUB = 'github'
+    GITEE = 'gitee'
+    GITLAB = 'gitlab'
+    CUSTOM = 'custom'

gitwebhooks/models/request.py

@@ -0,0 +1,61 @@
+"""Webhook request data wrapper
+
+Represents a parsed HTTP webhook request.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from gitwebhooks.models.provider import Provider
+
+
+@dataclass
+class WebhookRequest:
+    """Webhook request data wrapper
+
+    Attributes:
+        provider: Git platform provider
+        event: Event type (e.g., 'push', 'merge_request')
+        payload: Raw request body bytes
+        headers: HTTP request headers
+        post_data: Parsed JSON/form data
+        content_type: Content-Type header value
+        content_length: Content-Length header value
+    """
+    provider: Provider
+    event: Optional[str]
+    payload: bytes
+    headers: Dict[str, str]
+    post_data: Optional[Dict[str, Any]]
+    content_type: str
+    content_length: int
+
+    @property
+    def repo_identifier(self) -> Optional[str]:
+        """Extract repository identifier from post_data
+
+        Returns:
+            Repository identifier (e.g., 'owner/repo'), None if not found
+
+        Extraction rules:
+        - GitHub: repository.full_name
+        - Gitee: repository.full_name
+        - GitLab: project.path_with_namespace
+        - Custom: Uses ProviderConfig.identifier_path
+        """
+        if self.post_data is None:
+            return None
+
+        extractors = {
+            Provider.GITHUB: lambda d: d.get('repository', {}).get('full_name'),
+            Provider.GITEE: lambda d: d.get('repository', {}).get('full_name'),
+            Provider.GITLAB: lambda d: d.get('project', {}).get('path_with_namespace'),
+        }
+
+        extractor = extractors.get(self.provider)
+        if extractor:
+            result = extractor(self.post_data)
+            return result if isinstance(result, str) else None
+
+        # Custom provider uses identifier_path (handled in handler)
+        return None

gitwebhooks/models/result.py

@@ -0,0 +1,40 @@
+"""Signature verification result dataclass
+
+Represents the result status of signature verification.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class SignatureVerificationResult:
+    """Signature verification result
+
+    Attributes:
+        is_valid: Whether verification passed
+        error_message: Error description when verification fails
+    """
+    is_valid: bool
+    error_message: Optional[str] = None
+
+    @classmethod
+    def success(cls) -> 'SignatureVerificationResult':
+        """Create a successful verification result
+
+        Returns:
+            Result object with is_valid=True
+        """
+        return cls(is_valid=True)
+
+    @classmethod
+    def failure(cls, message: str) -> 'SignatureVerificationResult':
+        """Create a failed verification result
+
+        Args:
+            message: Error description
+
+        Returns:
+            Result object with is_valid=False and error message
+        """
+        return cls(is_valid=False, error_message=message)