notify-tls-client 0.1.9__py3-none-any.whl → 2.0.1__py3-none-any.whl

notify_tls_client/config/__init__.py

@@ -0,0 +1,18 @@
+"""
+Módulo de configuração para NotifyTLSClient.
+
+Fornece classes de configuração especializadas para organizar
+os parâmetros do cliente TLS de forma mais limpa e reutilizável.
+"""
+
+from .rotation_config import RotationConfig
+from .recovery_config import RecoveryConfig
+from .client_config import ClientConfig
+from .client_configuration import ClientConfiguration
+
+__all__ = [
+    'RotationConfig',
+    'RecoveryConfig',
+    'ClientConfig',
+    'ClientConfiguration',
+]

notify_tls_client/config/client_config.py

@@ -0,0 +1,76 @@
+"""
+Configurações do cliente TLS (identifiers, headers, protocolos).
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from notify_tls_client.tls_client.settings import ClientIdentifiers
+
+
+@dataclass
+class ClientConfig:
+    """
+    Configurações relacionadas ao cliente TLS e fingerprinting.
+
+    Attributes:
+        client_identifiers: Lista de client identifiers para rotação.
+            Identifiers disponíveis incluem chrome_133, firefox_120, safari_17_0, etc.
+            Se apenas um identifier for fornecido, não haverá rotação.
+            Default: ["chrome_133"]
+
+        default_headers: Headers padrão a serem enviados em todas as requisições.
+            Pode ser sobrescrito por requisição individual.
+            Default: None (usa headers padrão do tls-client)
+
+        disable_http3: Se True, força o uso de HTTP/2 ou HTTP/1.1, desabilitando HTTP/3.
+            Útil para ambientes que não suportam QUIC.
+            Default: False
+
+        debug_mode: Se True, habilita logs de debug detalhados.
+            IMPORTANTE: Pode vazar informações sensíveis nos logs.
+            Default: False
+
+    Examples:
+        >>> # Configuração padrão
+        >>> config = ClientConfig()
+
+        >>> # Múltiplos identifiers para stealth
+        >>> config = ClientConfig(
+        ...     client_identifiers=["chrome_133", "firefox_120", "safari_17_0"]
+        ... )
+
+        >>> # Headers customizados
+        >>> config = ClientConfig(
+        ...     default_headers={
+        ...         "User-Agent": "Mozilla/5.0...",
+        ...         "Accept-Language": "pt-BR,pt;q=0.9"
+        ...     }
+        ... )
+
+        >>> # Forçar HTTP/2
+        >>> config = ClientConfig(disable_http3=True)
+    """
+
+    client_identifiers: list[ClientIdentifiers] = field(default_factory=lambda: ["chrome_133"])
+    default_headers: Optional[dict] = None
+    disable_http3: bool = False
+    debug_mode: bool = False
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        if not self.client_identifiers:
+            raise ValueError("client_identifiers não pode ser vazio")
+
+        if len(self.client_identifiers) != len(set(self.client_identifiers)):
+            raise ValueError("client_identifiers contém duplicatas")
+
+        # Valida default_headers se fornecido
+        if self.default_headers is not None:
+            if not isinstance(self.default_headers, dict):
+                raise ValueError("default_headers deve ser um dicionário")
+
+            # Valida que keys são strings
+            for key in self.default_headers.keys():
+                if not isinstance(key, str):
+                    raise ValueError(f"Header key inválido: {key}. Deve ser string")

notify_tls_client/config/client_configuration.py

@@ -0,0 +1,237 @@
+"""
+Configuração completa do NotifyTLSClient com factory methods para casos de uso comuns.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from notify_tls_client.core.proxiesmanager import ProxiesManager
+from .rotation_config import RotationConfig
+from .recovery_config import RecoveryConfig
+from .client_config import ClientConfig
+
+
+@dataclass
+class ClientConfiguration:
+    """
+    Configuração completa para NotifyTLSClient.
+
+    Agrupa todas as configurações específicas em um único objeto para
+    simplificar a criação e reutilização de configurações.
+
+    Attributes:
+        proxies_manager: Gerenciador de proxies para rotação automática.
+            Default: None (sem proxies)
+
+        rotation: Configurações de rotação de proxies e client identifiers.
+            Default: RotationConfig com valores padrão
+
+        recovery: Configurações de recuperação automática.
+            Default: RecoveryConfig com valores padrão
+
+        client: Configurações do cliente TLS.
+            Default: ClientConfig com valores padrão
+
+    Examples:
+        >>> # Configuração padrão
+        >>> config = ClientConfiguration()
+
+        >>> # Configuração customizada
+        >>> config = ClientConfiguration(
+        ...     proxies_manager=ProxiesManager([...]),
+        ...     rotation=RotationConfig(requests_limit_same_proxy=10),
+        ...     recovery=RecoveryConfig(
+        ...         instantiate_new_client_on_forbidden_response=True,
+        ...         status_codes_to_forbidden_response_handle=[403, 429]
+        ...     ),
+        ...     client=ClientConfig(
+        ...         client_identifiers=["chrome_133", "firefox_120"]
+        ...     )
+        ... )
+
+        >>> # Usando factory method
+        >>> config = ClientConfiguration.aggressive(proxies_manager)
+    """
+
+    proxies_manager: Optional[ProxiesManager] = None
+    rotation: RotationConfig = field(default_factory=RotationConfig)
+    recovery: RecoveryConfig = field(default_factory=RecoveryConfig)
+    client: ClientConfig = field(default_factory=ClientConfig)
+
+    @classmethod
+    def aggressive(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração agressiva: rotação rápida e recuperação automática completa.
+
+        Ideal para cenários de scraping intensivo onde detectar e contornar
+        bloqueios rapidamente é crítico.
+
+        Características:
+        - Troca proxy a cada 10 requisições
+        - Troca client identifier a cada 50 requisições
+        - Recuperação automática em erros e respostas proibidas
+        - Troca client identifier em respostas proibidas
+        - Monitora status codes 403, 429 e 503
+
+        Args:
+            proxies_manager: Gerenciador de proxies (obrigatório para rotação)
+
+        Returns:
+            ClientConfiguration configurado para modo agressivo
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.aggressive(proxies))
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=10,
+                requests_limit_same_client_identifier=50,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=True,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=True,
+                status_codes_to_forbidden_response_handle=[403, 429, 503]
+            ),
+            client=ClientConfig(
+                client_identifiers=["chrome_133", "firefox_120", "safari_17_0"]
+            )
+        )
+
+    @classmethod
+    def stealth(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração stealth: foco em evitar detecção através de diversidade.
+
+        Ideal para cenários onde ser discreto é mais importante que velocidade,
+        utilizando múltiplos client identifiers e randomização.
+
+        Características:
+        - Múltiplos client identifiers (Chrome, Firefox, Safari, Edge)
+        - Ordem de extensões TLS randomizada
+        - Rotação moderada de proxies (100 requisições)
+        - Rotação de client identifier a cada 30 requisições
+        - Recuperação básica apenas para erros críticos
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional mas recomendado)
+
+        Returns:
+            ClientConfiguration configurado para modo stealth
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.stealth(proxies))
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=100,
+                requests_limit_same_client_identifier=30,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=False,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403]
+            ),
+            client=ClientConfig(
+                client_identifiers=[
+                    "chrome_133",
+                    "firefox_120",
+                    "safari_17_0",
+                    "safari_ios_16_0"
+                ]
+            )
+        )
+
+    @classmethod
+    def simple(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração simples: apenas rotação básica de proxies.
+
+        Ideal para uso geral onde não há necessidade de evasão agressiva,
+        mantendo a simplicidade e confiabilidade.
+
+        Características:
+        - Client identifier único (Chrome 133)
+        - Rotação de proxy padrão (1000 requisições)
+        - Sem rotação de client identifier
+        - Sem recuperação automática
+        - Monitora apenas status 403
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional)
+
+        Returns:
+            ClientConfiguration configurado para modo simples
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.simple())
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=1000,
+                requests_limit_same_client_identifier=-1,
+                random_tls_extension_order=False
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=False,
+                instantiate_new_client_on_exception=False,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403]
+            ),
+            client=ClientConfig(
+                client_identifiers=["chrome_133"]
+            )
+        )
+
+    @classmethod
+    def mobile(cls, proxies_manager: Optional[ProxiesManager] = None, platform: str = "android") -> 'ClientConfiguration':
+        """
+        Configuração mobile: simula dispositivos móveis.
+
+        Ideal para APIs ou sites que têm comportamento diferente para mobile.
+
+        Características:
+        - Client identifiers mobile (Android ou iOS)
+        - Rotação moderada
+        - Recuperação automática em erros
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional)
+            platform: "android" ou "ios"
+
+        Returns:
+            ClientConfiguration configurado para modo mobile
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.mobile(platform="ios"))
+        """
+        if platform.lower() == "android":
+            identifiers = ["okhttp4_android_13", "okhttp4_android_12"]
+        elif platform.lower() == "ios":
+            identifiers = ["safari_ios_16_0", "safari_ios_15_6"]
+        else:
+            raise ValueError(f"Platform inválida: {platform}. Use 'android' ou 'ios'")
+
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=50,
+                requests_limit_same_client_identifier=100,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=True,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403, 429]
+            ),
+            client=ClientConfig(
+                client_identifiers=identifiers
+            )
+        )

notify_tls_client/config/recovery_config.py

@@ -0,0 +1,71 @@
+"""
+Configurações de recuperação automática em caso de erros e respostas proibidas.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RecoveryConfig:
+    """
+    Configurações para controlar o comportamento de recuperação automática.
+
+    Attributes:
+        instantiate_new_client_on_forbidden_response: Se True, cria uma nova sessão TLS
+            quando receber um status code configurado como "proibido".
+            Default: False
+
+        instantiate_new_client_on_exception: Se True, cria uma nova sessão TLS
+            quando ocorrer uma exceção durante a requisição.
+            Default: False
+
+        change_client_identifier_on_forbidden_response: Se True, além de criar uma nova
+            sessão, também troca o client identifier quando receber resposta proibida.
+            Requer instantiate_new_client_on_forbidden_response=True para ter efeito.
+            Default: False
+
+        status_codes_to_forbidden_response_handle: Lista de status codes HTTP que devem
+            acionar os mecanismos de recuperação automática.
+            Default: [403]
+
+    Examples:
+        >>> # Recuperação agressiva
+        >>> config = RecoveryConfig(
+        ...     instantiate_new_client_on_forbidden_response=True,
+        ...     instantiate_new_client_on_exception=True,
+        ...     change_client_identifier_on_forbidden_response=True,
+        ...     status_codes_to_forbidden_response_handle=[403, 429, 503]
+        ... )
+
+        >>> # Sem recuperação automática
+        >>> config = RecoveryConfig()
+    """
+
+    instantiate_new_client_on_forbidden_response: bool = False
+    instantiate_new_client_on_exception: bool = False
+    change_client_identifier_on_forbidden_response: bool = False
+    status_codes_to_forbidden_response_handle: tuple[int, ...] = field(default_factory=lambda: (403,))
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        # Converter lista para tuple se necessário (compatibilidade)
+        if isinstance(self.status_codes_to_forbidden_response_handle, list):
+            object.__setattr__(self, 'status_codes_to_forbidden_response_handle',
+                             tuple(self.status_codes_to_forbidden_response_handle))
+
+        if not self.status_codes_to_forbidden_response_handle:
+            raise ValueError("status_codes_to_forbidden_response_handle não pode ser vazio")
+
+        for code in self.status_codes_to_forbidden_response_handle:
+            if not isinstance(code, int) or code < 100 or code > 599:
+                raise ValueError(f"Status code inválido: {code}. Deve estar entre 100 e 599")
+
+        # Aviso sobre configuração inconsistente
+        if self.change_client_identifier_on_forbidden_response and not self.instantiate_new_client_on_forbidden_response:
+            import warnings
+            warnings.warn(
+                "change_client_identifier_on_forbidden_response=True não terá efeito "
+                "porque instantiate_new_client_on_forbidden_response=False. "
+                "Considere habilitar ambos.",
+                UserWarning
+            )

notify_tls_client/config/rotation_config.py

@@ -0,0 +1,56 @@
+"""
+Configurações de rotação de proxies e client identifiers.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RotationConfig:
+    """
+    Configurações para controlar a rotação automática de proxies e client identifiers.
+
+    Attributes:
+        requests_limit_same_proxy: Número máximo de requisições com o mesmo proxy.
+            Use -1 para desabilitar rotação automática por limite.
+            Default: 1000
+
+        requests_limit_same_client_identifier: Número máximo de requisições com o mesmo
+            client identifier. Use -1 para desabilitar rotação automática por limite.
+            Default: -1 (desabilitado)
+
+        random_tls_extension_order: Se True, randomiza a ordem das extensões TLS
+            para dificultar fingerprinting.
+            Default: True
+
+    Examples:
+        >>> # Rotação agressiva
+        >>> config = RotationConfig(
+        ...     requests_limit_same_proxy=10,
+        ...     requests_limit_same_client_identifier=50
+        ... )
+
+        >>> # Sem rotação automática
+        >>> config = RotationConfig(
+        ...     requests_limit_same_proxy=-1,
+        ...     requests_limit_same_client_identifier=-1
+        ... )
+    """
+
+    requests_limit_same_proxy: int = 1000
+    requests_limit_same_client_identifier: int = -1
+    random_tls_extension_order: bool = True
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        if self.requests_limit_same_proxy < -1:
+            raise ValueError("requests_limit_same_proxy deve ser >= -1")
+
+        if self.requests_limit_same_client_identifier < -1:
+            raise ValueError("requests_limit_same_client_identifier deve ser >= -1")
+
+        if self.requests_limit_same_proxy == 0:
+            raise ValueError("requests_limit_same_proxy não pode ser 0 (use -1 para desabilitar)")
+
+        if self.requests_limit_same_client_identifier == 0:
+            raise ValueError("requests_limit_same_client_identifier não pode ser 0 (use -1 para desabilitar)")

notify_tls_client/core/client/decorators.py

@@ -3,6 +3,8 @@ from datetime import datetime
 from typing import Optional
 from urllib.parse import urlparse
 
+from orjson import orjson
+
 from notify_tls_client.tls_client.response import Response
 
 logger = logging.getLogger(__name__)
@@ -38,8 +40,8 @@ def request_guard_decorator(callback):
                 request_headers = value
 
         try:
-            self.requests_amount += 1
             res = callback(*args, **kwargs)
+            self.requests_amount += 1
             _log_request_info(self, res, request_url, request_headers)
             _requests_handler(self, res)
             return res
@@ -63,10 +65,14 @@ def request_guard_decorator(callback):
 def _recover_on_exception(self):
     if self.instantiate_new_client_on_exception:
         logging.info("Instantiating new TLS client due to exception...")
-        self.get_tls().close()
-        self._create_new_client()
-
-    if self.proxies_manager:
+        current_identifier = self.client_identifiers_manager.get_current_item()
+        next_proxy = self.proxies_manager.get_next() if self.proxies_manager else None
+        self._create_new_client(
+            client_identifier=current_identifier or 'chrome_133',
+            random_tls_extension_order=self.random_tls_extension_order,
+            proxy=next_proxy
+        )
+    elif self.proxies_manager:
         logging.info("Changing proxy due to exception...")
         self.change_proxy()
 
@@ -75,41 +81,65 @@ def _log_request_info(self,
                       response: Optional[Response],
                       request_url: Optional[str],
                       request_headers: dict):
+    if not logger.isEnabledFor(logging.DEBUG):
+        return
+
     if response:
-        logger.debug(f"""Request finished
-                                        client_identifier={self.get_current_client_identifier()}
-                                        request_url={request_url}
-                                        request_headers={request_headers}
-                                        response_url={response.url}
-                                        status_code={response.status_code}
-                                        response_time={response.elapsed}ms
-                                        response_headers={dict(response.headers)}
-                                        proxy={self.client.proxies['http'] if self.client.proxies else None}
-                             """,
+        proxy = self.client.proxies['http'] if self.client.proxies else None
+        client_id = self.get_current_client_identifier()
+        response_headers_dict = dict(response.headers)
+
+        # Serializar dados complexos com orjson (mais rápido)
+        try:
+            request_headers_json = orjson.dumps(request_headers).decode('utf-8')
+            response_headers_json = orjson.dumps(response_headers_dict).decode('utf-8')
+        except Exception:
+            request_headers_json = str(request_headers)
+            response_headers_json = str(response_headers_dict)
+
+        logger.debug("Request finished\n"
+                     "                                        client_identifier=%s\n"
+                     "                                        request_url=%s\n"
+                     "                                        request_headers=%s\n"
+                     "                                        response_url=%s\n"
+                     "                                        status_code=%s\n"
+                     "                                        response_time=%sms\n"
+                     "                                        response_headers=%s\n"
+                     "                                        proxy=%s",
+                     client_id, request_url, request_headers_json, response.url,
+                     response.status_code, response.elapsed, response_headers_json, proxy,
                      extra={
                          "date": datetime.now().strftime("%d-%m-%Y %H:%M:%S.%f")[:-3],
                          "request_url": request_url,
                          "request_headers": request_headers,
                          "response_url": response.url,
                          "status_code": response.status_code,
-                         "response_headers": dict(response.headers),
+                         "response_headers": response_headers_dict,
                          "response_elapsed_ms": response.elapsed,
-                         "proxy": self.client.proxies['http'] if self.client.proxies else None,
-                         "client_identifier": self.get_current_client_identifier()
-
+                         "proxy": proxy,
+                         "client_identifier": client_id
                      })
 
     if not response:
-        logger.debug(f"""Request failed before getting a response
-                                        client_identifier={self.get_current_client_identifier()}
-                                        request_url={request_url}
-                                        request_headers={request_headers}
-                                        response_url=None
-                                        status_code=None
-                                        response_headers=None
-                                        response_time=0
-                                        proxy={self.client.proxies['http'] if self.client.proxies else None}
-                             """,
+        proxy = self.client.proxies['http'] if self.client.proxies else None
+        client_id = self.get_current_client_identifier()
+
+        # Serializar request_headers com orjson
+        try:
+            request_headers_json = orjson.dumps(request_headers).decode('utf-8')
+        except Exception:
+            request_headers_json = str(request_headers)
+
+        logger.debug("Request failed before getting a response\n"
+                     "                                        client_identifier=%s\n"
+                     "                                        request_url=%s\n"
+                     "                                        request_headers=%s\n"
+                     "                                        response_url=None\n"
+                     "                                        status_code=None\n"
+                     "                                        response_headers=None\n"
+                     "                                        response_time=0\n"
+                     "                                        proxy=%s",
+                     client_id, request_url, request_headers_json, proxy,
                      extra={
                          "date": datetime.now().strftime("%d-%m-%Y %H:%M:%S.%f")[:-3],
                          "request_url": request_url,
@@ -118,9 +148,8 @@ def _log_request_info(self,
                          "status_code": None,
                          "response_headers": None,
                          "response_elapsed_ms": 0,
-                         "proxy": self.client.proxies['http'] if self.client.proxies else None,
-                         "client_identifier": self.get_current_client_identifier()
-
+                         "proxy": proxy,
+                         "client_identifier": client_id
                      })
 
 
@@ -194,46 +223,3 @@ def _requests_handler(self, response: Optional[Response]):
         if has_proxies_manager:
             logging.info("Changing proxy due to requests limit reached...")
             self.change_proxy()
-
-    # if client_identifier_changed_by_limit:
-    #     logging.info("Requests limit reached for current client identifier")
-    #     logging.info("Changing client identifier due to requests limit reached...")
-    #     # self._create_new_client(self.client_identifiers_manager.get_next(),
-    #     #                         proxy=self.proxies_manager.get_current_proxy() if self.proxies_manager else None)
-    #
-    #
-    #
-    #
-    # if self.requests_limit_with_same_proxy and self.requests_amount_with_current_proxy >= self.requests_limit_with_same_proxy:
-    #     logging.info("Requests limit reached for current proxy")
-    #     if self.proxies_manager:
-    #         proxy_changed_by_limit = True
-    #         logging.info("Changing proxy due to requests limit reached...")
-    #
-    #         if response.status_code in self.status_codes_to_forbidden_response_handle and self.instantiate_new_client_on_forbidden_response:
-    #             logging.info("Instantiating new TLS client due to forbidden response before changing proxy...")
-    #             self.get_tls().close()
-    #             if self.change_client_identifier_on_forbidden_response:
-    #                 self._create_new_client(self.client_identifiers_manager.get_next())
-    #             else:
-    #                 self._create_new_client(self.client_identifiers_manager.get_current())
-    #
-    #         self.change_proxy()
-    #
-    # # Metodo vai ter que ser usado para não trocar o proxy duas vezes, uma pelo status 403 e outra pelo limite de requests
-    # if not proxy_changed_by_limit:
-    #     return
-    #
-    # if response.status_code in self.status_codes_to_forbidden_response_handle:
-    #     if self.instantiate_new_client_on_forbidden_response:
-    #         logging.info("Instantiating new TLS client due to forbidden response...")
-    #         self.get_tls().close()
-    #
-    #         if self.change_client_identifier_on_forbidden_response:
-    #             self._create_new_client(self.client_identifiers_manager.get_next())
-    #         else:
-    #             self._create_new_client()
-    #
-    #     if self.proxies_manager:
-    #         logging.info("Changing proxy due to forbidden response...")
-    #         self.change_proxy()