osn-selenium 0.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

osn_selenium/dev_tools/target/fingerprint.py

@@ -0,0 +1,126 @@
+import trio
+from osn_selenium.dev_tools.models import FingerprintData
+from osn_selenium.exceptions.devtools import CDPEndExceptions
+from osn_selenium.dev_tools.target.logging import LoggingMixin
+from osn_selenium.dev_tools._functions import execute_cdp_command
+
+
+__all__ = ["FingerprintMixin"]
+
+
+class FingerprintMixin(LoggingMixin):
+	"""
+	Mixin for detecting and logging fingerprinting attempts in the browser.
+	"""
+	
+	async def _run_fingerprint_detect_listener(self, ready_event: trio.Event):
+		"""
+		Runs the listener for fingerprint detection events from the browser.
+
+		Args:
+			ready_event (trio.Event): Event to signal when the listener is set up and ready.
+
+		Raises:
+			CDPEndExceptions: If a CDP connection error occurs.
+			BaseException: If any other error occurs.
+		"""
+		
+		await self.log_cdp_step(message="Fingerprint detection listener starting.")
+		
+		try:
+			BindingCalled = self.devtools_package.get("runtime.BindingCalled")
+		
+			self._fingerprint_receive_channel = self.cdp_session.listen(BindingCalled, buffer_size=100)
+		
+			ready_event.set()
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			await self.log_cdp_error(error=error)
+			raise error
+		
+		await self.log_cdp_step(message="Fingerprint detection listener started.")
+		
+		keep_alive = True
+		while keep_alive:
+			try:
+				event = await self._fingerprint_receive_channel.receive()
+		
+				if event.name == "__osn_fingerprint_report__":
+					fingerprint_data = FingerprintData.model_validate_json(event.payload)
+		
+					await self.log_fingerprint(level="Detect", data=fingerprint_data)
+			except* CDPEndExceptions:
+				keep_alive = False
+			except* BaseException as error:
+				await self.log_cdp_error(error=error)
+	
+	async def _setup_fingerprint_injection(self, ready_event: trio.Event):
+		"""
+		Injects the fingerprint detection scripts into the browser page.
+
+		Enables necessary domains (Page, Runtime), adds the reporting binding,
+		and evaluates the fingerprint injection script on new document creation.
+
+		Args:
+			ready_event (trio.Event): Event to signal when injection setup is complete.
+
+		Raises:
+			CDPEndExceptions: If a CDP connection error occurs.
+			BaseException: If any other error occurs.
+		"""
+		
+		if self._fingerprint_injection_script:
+			try:
+				await execute_cdp_command(
+						self=self,
+						cdp_error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						function=self.devtools_package.get("page.enable"),
+				)
+				await execute_cdp_command(
+						self=self,
+						cdp_error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						function=self.devtools_package.get("runtime.enable"),
+				)
+		
+				await execute_cdp_command(
+						self=self,
+						cdp_error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						error_mode="pass"
+						if not self._is_main_target
+						else "log",
+						function=self.devtools_package.get("runtime.add_binding"),
+						name="__osn_fingerprint_report__",
+				)
+		
+				await execute_cdp_command(
+						self=self,
+						cdp_error_mode="pass"
+						if not self._is_main_target
+						else "log_without_args",
+						error_mode="pass"
+						if not self._is_main_target
+						else "log_without_args",
+						function=self.devtools_package.get("page.add_script_to_evaluate_on_new_document"),
+						source=self._fingerprint_injection_script,
+						run_immediately=True,
+				)
+		
+				self._nursery_object.start_soon(self._run_fingerprint_detect_listener, ready_event)
+			except* CDPEndExceptions as error:
+				raise error
+			except* BaseException as error:
+				await self.log_cdp_error(error=error)
+				raise error

osn_selenium/dev_tools/target/lifecycle.py

@@ -0,0 +1,184 @@
+import trio
+from typing import List
+from osn_selenium.dev_tools.target.detach import DetachMixin
+from osn_selenium.exceptions.devtools import CDPEndExceptions
+from osn_selenium.dev_tools.target.discovery import DiscoveryMixin
+from osn_selenium.dev_tools.target.events import EventHandlersMixin
+from osn_selenium.dev_tools.logger.target import build_target_logger
+from osn_selenium.dev_tools.target.fingerprint import FingerprintMixin
+from selenium.webdriver.common.bidi.cdp import (
+	BrowserError,
+	open_cdp
+)
+from osn_selenium.dev_tools._decorators import (
+	background_task_decorator
+)
+from osn_selenium.dev_tools._functions import (
+	execute_cdp_command,
+	wait_one
+)
+
+
+__all__ = ["LifecycleMixin"]
+
+
+class LifecycleMixin(DiscoveryMixin, EventHandlersMixin, DetachMixin, FingerprintMixin):
+	"""
+	Mixin managing the main lifecycle of the DevTools target (setup, run, close).
+	"""
+	
+	async def _close_instances(self):
+		"""
+		Closes all active resources, channels, and loggers associated with the target.
+		"""
+		
+		if self._new_target_receive_channel is not None:
+			await self._new_target_receive_channel[0].aclose()
+			await self._new_target_receive_channel[1].wait()
+			self._new_target_receive_channel = None
+		
+		if self._detached_receive_channel is not None:
+			await self._detached_receive_channel.aclose()
+			self._detached_receive_channel = None
+		
+		if self._logger_cdp_send_channel is not None:
+			await self._logger_cdp_send_channel.aclose()
+			self._logger_cdp_send_channel = None
+		
+		if self._logger_fingerprint_send_channel is not None:
+			await self._logger_fingerprint_send_channel.aclose()
+			self._logger_fingerprint_send_channel = None
+		
+		if self._logger is not None:
+			await self._logger.close()
+			self._logger = None
+		
+		for event_name, channel in self._events_receive_channels.items():
+			await channel[0].aclose()
+			await channel[1].wait()
+		
+		self._events_receive_channels = {}
+		
+		for scope_name, scope in self._cancel_scopes.items():
+			scope.cancel()
+		
+		self._cancel_scopes = {}
+		
+		if self.background_task_ended is not None:
+			await self.background_task_ended.wait()
+			self.background_task_ended = None
+	
+	async def _setup_target(self):
+		"""
+		Configures the target session by enabling domains and starting listeners.
+
+		Enables configured CDP domains, starts event listeners for them,
+		and initializes target discovery and detach monitoring.
+
+		Raises:
+			CDPEndExceptions: If connection issues occur.
+			BaseException: If setup fails.
+		"""
+		
+		try:
+			await self.log_cdp_step(message="Target setup started.")
+		
+			await self._setup_new_targets_attaching()
+		
+			target_ready_events: List[trio.Event] = []
+		
+			new_targets_listener_ready_event = trio.Event()
+			target_ready_events.append(new_targets_listener_ready_event)
+		
+			fingerprint_detecting_ready_event = trio.Event()
+			target_ready_events.append(fingerprint_detecting_ready_event)
+		
+			self._nursery_object.start_soon(self._run_new_targets_listener, new_targets_listener_ready_event)
+			self._nursery_object.start_soon(self._setup_fingerprint_injection, fingerprint_detecting_ready_event)
+			self._nursery_object.start_soon(self._run_detach_checking)
+		
+			if self._domains_settings:
+				for domain_name, domain_config in self._domains_settings.model_dump(exclude_none=True).items():
+					if domain_config.get("enable_func_path", None) is not None:
+						enable_func_kwargs = domain_config.get("enable_func_kwargs", {})
+		
+						if (
+								domain_config["include_target_types"]
+								and self.type_ in domain_config["include_target_types"]
+								or domain_config["exclude_target_types"]
+								and self.type_ not in domain_config["exclude_target_types"]
+						):
+							await execute_cdp_command(
+									self=self,
+									error_mode="log",
+									function=self.devtools_package.get(domain_config["enable_func_path"]),
+									**enable_func_kwargs
+							)
+		
+					domain_handlers_ready_event = trio.Event()
+					target_ready_events.append(domain_handlers_ready_event)
+					self._nursery_object.start_soon(
+							self._run_events_handlers,
+							domain_handlers_ready_event,
+							getattr(self._domains_settings, domain_name)
+					)
+		
+			for domain_handlers_ready_event in target_ready_events:
+				await domain_handlers_ready_event.wait()
+		
+			await execute_cdp_command(
+					self=self,
+					error_mode="log",
+					function=self.devtools_package.get("runtime.run_if_waiting_for_debugger"),
+			)
+		
+			await self.log_cdp_step(message="Target setup complete.")
+		except* CDPEndExceptions as error:
+			raise error
+		except* BaseException as error:
+			await self.log_cdp_error(error=error)
+			raise error
+	
+	async def run(self):
+		"""
+		Starts the main lifecycle loop of the target.
+
+		Initializes logging, establishes the CDP session, sets up event handling,
+		runs background tasks, and waits for exit signals.
+
+		Raises:
+			BaseException: Handles and logs various exceptions during the lifecycle.
+		"""
+		
+		try:
+			self._logger_cdp_send_channel, self._logger_fingerprint_send_channel, self._logger = build_target_logger(self.target_data, self._nursery_object, self._logger_settings)
+		
+			if self._cdp_target_type_log_accepted:
+				await self._logger.run()
+		
+			await self.log_cdp_step(message=f"Target '{self.target_id}' added.")
+		
+			async with open_cdp(self.websocket_url) as new_connection:
+				target_id_instance = self.devtools_package.get("target.TargetID").from_json(self.target_id)
+		
+				async with new_connection.open_session(target_id_instance) as new_session:
+					self._cdp_session = new_session
+		
+					await self._setup_target()
+		
+					if self._target_background_task is not None:
+						self._nursery_object.start_soon(background_task_decorator(self._target_background_task), self)
+		
+					await wait_one(self.exit_event, self.about_to_stop_event)
+		except* (BrowserError, RuntimeError):
+			self.about_to_stop_event.set()
+		except* CDPEndExceptions:
+			self.about_to_stop_event.set()
+		except* BaseException as error:
+			self.about_to_stop_event.set()
+			await self.log_cdp_error(error=error)
+		finally:
+			await self._close_instances()
+			await self._remove_target_func(self)
+		
+			self.stopped_event.set()

osn_selenium/dev_tools/target/logging.py

@@ -0,0 +1,163 @@
+import trio
+import inspect
+import warnings
+from datetime import datetime
+from osn_selenium.dev_tools.target.base import BaseMixin
+from osn_selenium.dev_tools.models import FingerprintData
+from typing import (
+	Any,
+	Dict,
+	Optional,
+	TYPE_CHECKING
+)
+from osn_selenium.dev_tools._exception_helpers import (
+	extract_exception_trace,
+	log_exception
+)
+from osn_selenium.dev_tools.logger.models import (
+	CDPTargetLogEntry,
+	FingerprintTargetLogEntry
+)
+
+
+__all__ = ["LoggingMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools._typehints import CDP_LOG_LEVELS_TYPEHINT, FINGERPRINT_LOG_LEVELS_TYPEHINT
+
+
+class LoggingMixin(BaseMixin):
+	"""
+	Mixin for handling logging operations within a DevTools target.
+	"""
+	
+	async def log_cdp(
+			self,
+			level: "CDP_LOG_LEVELS_TYPEHINT",
+			message: str,
+			extra_data: Optional[Dict[str, Any]] = None
+	):
+		"""
+		Records a CDP log entry.
+
+		If logging is accepted for this target type, the entry is sent to the target-specific
+		logger channel.
+
+		Args:
+			level (CDPLogLevelsType): The severity level (e.g., 'INFO', 'ERROR').
+			message (str): The log message.
+			extra_data (Optional[Dict[str, Any]]): Additional data to log.
+		"""
+		
+		log_entry = CDPTargetLogEntry(
+				target_data=self.target_data,
+				message=message,
+				level=level,
+				datetime=datetime.now(),
+				extra_data=extra_data
+		)
+		
+		await self._add_cdp_log_func(log_entry)
+		
+		if self.target_type_log_accepted and self._logger is not None and self._logger_cdp_send_channel is not None:
+			await self._cdp_log_stats.add_log(log_entry)
+			await self._logger.run()
+		
+			try:
+				if self._logger.filter_cdp_log(log_entry=log_entry):
+					if self._logger_settings.cdp_settings.send_wait:
+						await self._logger_cdp_send_channel.send(log_entry)
+					else:
+						self._logger_cdp_send_channel.send_nowait(log_entry)
+			except trio.WouldBlock:
+				warnings.warn(
+						f"WARNING: Log channel for session {self.target_id} is full. Log dropped:\n{log_entry.model_dump_json(indent=4)}"
+				)
+			except trio.BrokenResourceError:
+				warnings.warn(
+						f"WARNING: Log channel for session {self.target_id} is broken. Log dropped:\n{log_entry.model_dump_json(indent=4)}"
+				)
+	
+	async def log_cdp_error(self, error: BaseException, extra_data: Optional[Dict[str, Any]] = None):
+		"""
+		Logs an error with exception traceback and context.
+
+		Args:
+			error (BaseException): The exception to log.
+			extra_data (Optional[Dict[str, Any]]): Additional context data.
+		"""
+		
+		stack = inspect.stack()
+		extra_data_ = {
+			"frame": str(stack[1].frame),
+			"source_function": " <- ".join(stack_.function for stack_ in stack[1:]),
+			"target_data": self.target_data.model_dump(),
+		}
+		
+		if extra_data is not None:
+			extra_data_.update(extra_data)
+		
+		await self.log_cdp(
+				level="ERROR",
+				message=extract_exception_trace(error),
+				extra_data=extra_data_
+		)
+		log_exception(exception=error, extra_data=extra_data_)
+	
+	async def log_cdp_step(self, message: str, extra_data: Optional[Dict[str, Any]] = None):
+		"""
+		Logs a 'step' or informational message at INFO level.
+
+		Automatically includes the source function in the extra data.
+
+		Args:
+			message (str): The log message.
+			extra_data (Optional[Dict[str, Any]]): Additional context data.
+		"""
+		
+		stack = inspect.stack()
+		extra_data_ = {"source_function": " <- ".join(stack_.function for stack_ in stack[1:])}
+		
+		if extra_data is not None:
+			extra_data_.update(extra_data)
+		
+		await self.log_cdp(level="INFO", message=message, extra_data=extra_data_)
+	
+	async def log_fingerprint(self, level: "FINGERPRINT_LOG_LEVELS_TYPEHINT", data: FingerprintData):
+		"""
+		Records a fingerprint detection log entry.
+
+		Args:
+			level ("FingerprintLogLevelsType"): The log level (e.g., "Detect").
+			data (FingerprintData): The detected fingerprint data.
+		"""
+		
+		log_entry = FingerprintTargetLogEntry(
+				target_data=self.target_data,
+				level=level,
+				api=data.api,
+				used_method=data.used_method,
+				datetime=datetime.now(),
+				stacktrace=data.stacktrace,
+		)
+		
+		await self._add_fingerprint_log_func(log_entry)
+		
+		if self.target_type_log_accepted and self._logger is not None and self._logger_fingerprint_send_channel is not None:
+			await self._fingerprint_log_stats.add_log(log_entry)
+			await self._logger.run()
+		
+			try:
+				if self._logger.filter_fingerprint_log(log_entry=log_entry):
+					if self._logger_settings.fingerprint_settings.send_wait:
+						await self._logger_fingerprint_send_channel.send(log_entry)
+					else:
+						self._logger_fingerprint_send_channel.send_nowait(log_entry)
+			except trio.WouldBlock:
+				warnings.warn(
+						f"WARNING: Log channel for session {self.target_id} is full. Log dropped:\n{log_entry.model_dump_json(indent=4)}"
+				)
+			except trio.BrokenResourceError:
+				warnings.warn(
+						f"WARNING: Log channel for session {self.target_id} is broken. Log dropped:\n{log_entry.model_dump_json(indent=4)}"
+				)

osn_selenium/exceptions/__init__.py

@@ -0,0 +1 @@
+

osn_selenium/exceptions/base.py

@@ -0,0 +1,9 @@
+__all__ = ["OSNSeleniumError"]
+
+
+class OSNSeleniumError(Exception):
+	"""
+	Base exception class for all errors in the OSN Selenium library.
+	"""
+	
+	pass

osn_selenium/exceptions/configuration.py

@@ -0,0 +1,84 @@
+from typing import Any, Iterable, Union
+from osn_selenium._functions import flatten_types
+from osn_selenium.exceptions.base import OSNSeleniumError
+from osn_selenium._typehints import (
+	TYPES_FOR_FLATTENING_TYPEHINT
+)
+
+
+__all__ = [
+	"ConfigurationError",
+	"DuplicationError",
+	"NotExpectedTypeError",
+	"NotExpectedValueError"
+]
+
+
+class ConfigurationError(OSNSeleniumError):
+	"""
+	Base class for configuration-related errors.
+	"""
+	
+	pass
+
+
+class NotExpectedValueError(ConfigurationError):
+	"""
+	Error raised when a configuration value is not among the expected valid values.
+	"""
+	
+	def __init__(self, value_name: str, value: Any, valid_values: Iterable[Any]) -> None:
+		"""
+		Initializes NotExpectedValueError.
+
+		Args:
+			value_name (str): The name of the configuration parameter.
+			value (Any): The invalid value provided.
+			valid_values (Iterable[Any]): A collection of acceptable values.
+		"""
+		
+		super().__init__(
+				f"Invalid '{value_name}' value ({str(value)}. Valid values: {', '.join(str(valid_value) for valid_value in valid_values)}."
+		)
+
+
+class NotExpectedTypeError(ConfigurationError):
+	"""
+	Error raised when a configuration value has an invalid type.
+	"""
+	
+	def __init__(
+			self,
+			value_name: str,
+			value: Any,
+			valid_types: Union[TYPES_FOR_FLATTENING_TYPEHINT, Iterable[TYPES_FOR_FLATTENING_TYPEHINT]]
+	) -> None:
+		"""
+		Initializes NotExpectedTypeError.
+
+		Args:
+			value_name (str): The name of the configuration parameter.
+			value (Any): The value with the incorrect type.
+			valid_types (Union[TYPE_FOR_FLATTENING, Iterable[TYPE_FOR_FLATTENING]]): The expected type or types.
+		"""
+		
+		super().__init__(
+				f"Invalid '{value_name}' type ({str(value)}. Valid types: {', '.join(flatten_types(valid_types))}."
+		)
+
+
+class DuplicationError(ConfigurationError):
+	"""
+	Error raised when a configuration parameter contains duplicated values.
+	"""
+	
+	def __init__(self, value_name: str, duplicated_values: Union[str, Iterable[str]]) -> None:
+		"""
+		Initializes DuplicationError.
+
+		Args:
+			value_name (str): The name of the parameter.
+			duplicated_values (Union[str, Iterable[str]]): The value or values that were duplicated.
+		"""
+		
+		super().__init__(f"'{value_name}' has been duplicated: {', '.join(duplicated_values)}.")

osn_selenium/exceptions/dependencies.py

@@ -0,0 +1,60 @@
+from typing import Union
+from osn_selenium._cdp_import import (
+	check_cdp_version_exists_on_github
+)
+
+
+__all__ = ["CDPPackageError", "DependencyError"]
+
+_CDP_PACKAGE_EXISTS = """
+CDP package for {version} is not installed.
+Fix: Run the following command:
+\t`pip install git+https://github.com/oddshellnick/osn-selenium-cdp.git@{version}`
+""".strip("\n")
+
+_CDP_PACKAGE_NOT_EXISTS = """
+CDP package for version {version} was not found on GitHub or locally.
+Please check available versions at: https://github.com/oddshellnick/osn-selenium-cdp
+If you need this specific version, you can generate it using the https://github.com/oddshellnick/selenium-package-parser tool.
+""".strip("\n")
+
+
+class DependencyError(Exception):
+	"""
+	Base exception for dependency-related issues.
+	"""
+	
+	pass
+
+
+class CDPPackageError(DependencyError):
+	"""
+	Exception raised when a required CDP package is missing.
+	"""
+	
+	def __init__(self, version: Union[int, str]):
+		"""
+		Initializes the error with version details.
+
+		Args:
+			version (Union[int, str]): The missing CDP version.
+		"""
+		
+		self.version = version if isinstance(version, str) else f"v{version}"
+		
+		super().__init__(self._generate_report())
+	
+	def _generate_report(self) -> str:
+		"""
+		Generates a detailed error message checking remote availability.
+
+		Returns:
+			str: Formatted error message with instructions.
+		"""
+		
+		version_exists_on_github = check_cdp_version_exists_on_github(version=self.version)
+		
+		if version_exists_on_github:
+			return _CDP_PACKAGE_EXISTS.format(version=self.version)
+		
+		return _CDP_PACKAGE_NOT_EXISTS.format(version=self.version)