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

osn_selenium/dev_tools/logger/target.py

@@ -0,0 +1,278 @@
+import trio
+import pathlib
+from typing import (
+	Callable,
+	Optional,
+	Tuple
+)
+from osn_selenium.dev_tools.models import TargetData
+from osn_selenium.dev_tools.settings import LoggerSettings
+from osn_selenium.exceptions.devtools import TrioEndExceptions
+from osn_selenium.dev_tools._validators import validate_log_filter
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from osn_selenium.dev_tools.logger.models import (
+	CDPTargetLogEntry,
+	FingerprintTargetLogEntry
+)
+
+
+__all__ = ["TargetLogger", "build_target_logger"]
+
+
+class TargetLogger:
+	"""
+	Manages logging for a specific browser target (e.g., a tab or iframe).
+
+	Each `TargetLogger` instance is responsible for writing log entries
+	related to its associated `TargetData` to a dedicated file.
+	"""
+	
+	def __init__(
+			self,
+			logger_settings: LoggerSettings,
+			nursery_object: trio.Nursery,
+			target_data: TargetData,
+			cdp_receive_channel: Optional[trio.MemoryReceiveChannel[CDPTargetLogEntry]],
+			fingerprint_receive_channel: Optional[trio.MemoryReceiveChannel[FingerprintTargetLogEntry]],
+	):
+		"""
+		Initializes the TargetLogger.
+
+		Args:
+			logger_settings (LoggerSettings): Configuration for logging.
+			nursery_object (trio.Nursery): The Trio nursery to spawn background tasks.
+			target_data (TargetData): The data of the browser target this logger will log for.
+			cdp_receive_channel (Optional[trio.MemoryReceiveChannel[CDPTargetLogEntry]]):
+				Channel to receive CDP logs.
+			fingerprint_receive_channel (Optional[trio.MemoryReceiveChannel[FingerprintTargetLogEntry]]):
+				Channel to receive fingerprint logs.
+
+		Raises:
+			ValueError: If settings require logging but `dir_path` is not set.
+		"""
+		
+		self._target_data = target_data
+		self._nursery_object = nursery_object
+		self._cdp_receive_channel = cdp_receive_channel
+		self._fingerprint_receive_channel = fingerprint_receive_channel
+		self._cdp_file_path: Optional[pathlib.Path] = None
+		self._cdp_log_level_filter: Optional[Callable[[str], bool]] = None
+		self._cdp_target_type_filter: Optional[Callable[[str], bool]] = None
+		self._fingerprint_file_path: Optional[pathlib.Path] = None
+		self._fingerprint_log_level_filter: Optional[Callable[[str], bool]] = None
+		self._fingerprint_target_type_filter: Optional[Callable[[str], bool]] = None
+		
+		if logger_settings.dir_path is None:
+			if logger_settings.cdp_settings:
+				raise ValueError("Can't log CDP without LoggerSettings.dir_path!")
+			
+			if logger_settings.fingerprint_settings:
+				raise ValueError("Can't log Fingerprint without LoggerSettings.log_dir_path!")
+		else:
+			logdir_path = logger_settings.dir_path.joinpath(target_data.target_id)
+			logdir_path.mkdir(exist_ok=True)
+			
+			if logger_settings.cdp_settings:
+				self._cdp_file_path = logdir_path.joinpath(f"cdp_log.txt")
+				
+				self._cdp_log_level_filter = validate_log_filter(
+						logger_settings.cdp_settings.log_level_filter_mode,
+						logger_settings.cdp_settings.log_level_filter
+				)
+				
+				self._cdp_target_type_filter = validate_log_filter(
+						logger_settings.cdp_settings.target_type_filter_mode,
+						logger_settings.cdp_settings.target_type_filter
+				)
+			
+			if logger_settings.fingerprint_settings:
+				self._fingerprint_file_path = logdir_path.joinpath(f"fingerprint_log.txt")
+				
+				self._fingerprint_log_level_filter = validate_log_filter(
+						logger_settings.fingerprint_settings.log_level_filter_mode,
+						logger_settings.fingerprint_settings.log_level_filter
+				)
+				
+				self._fingerprint_category_filter = validate_log_filter(
+						logger_settings.fingerprint_settings.category_filter_mode,
+						logger_settings.fingerprint_settings.category_filter
+				)
+		
+		self._cdp_file_writing_stopped: Optional[trio.Event] = None
+		self._fingerprint_file_writing_stopped: Optional[trio.Event] = None
+		self._is_active = False
+	
+	def filter_cdp_log(self, log_entry: CDPTargetLogEntry) -> bool:
+		"""
+		Applies configured filters to a CDP log entry.
+
+		Args:
+			log_entry (CDPTargetLogEntry): The log entry to check.
+
+		Returns:
+			bool: True if the log entry passes filters, False otherwise.
+		"""
+		
+		return self._cdp_log_level_filter(log_entry.level) and self._cdp_target_type_filter(log_entry.target_data.type_)
+	
+	def filter_fingerprint_log(self, log_entry: FingerprintTargetLogEntry) -> bool:
+		"""
+		Applies configured filters to a fingerprint log entry.
+
+		Args:
+			log_entry (FingerprintTargetLogEntry): The log entry to check.
+
+		Returns:
+			bool: True if the log entry passes filters, False otherwise.
+		"""
+		
+		return self._fingerprint_log_level_filter(log_entry.level) and self._fingerprint_category_filter(log_entry.api)
+	
+	@property
+	def is_active(self) -> bool:
+		"""
+		Checks if the target logger is currently active.
+
+		Returns:
+			bool: True if the logger is active and running, False otherwise.
+		"""
+		
+		return self._is_active
+	
+	async def close(self):
+		"""
+		Closes the target logger, including its receive channels and stops writing tasks.
+		"""
+		
+		if self._cdp_receive_channel is not None:
+			await self._cdp_receive_channel.aclose()
+			self._cdp_receive_channel = None
+		
+		if self._cdp_file_writing_stopped is not None:
+			await self._cdp_file_writing_stopped.wait()
+			self._cdp_file_writing_stopped = None
+		
+		if self._fingerprint_receive_channel is not None:
+			await self._fingerprint_receive_channel.aclose()
+			self._fingerprint_receive_channel = None
+		
+		if self._fingerprint_file_writing_stopped is not None:
+			await self._fingerprint_file_writing_stopped.wait()
+			self._fingerprint_file_writing_stopped = None
+		
+		self._is_active = False
+	
+	async def _write_fingerprint_file(self):
+		"""
+		Asynchronously writes fingerprint log entries to the target-specific file.
+
+		This method continuously receives `FingerprintTargetLogEntry` objects,
+		filters them, and appends them to the log file.
+		"""
+		
+		try:
+			end_of_entry = "\n\n" + "=" * 100 + "\n\n"
+		
+			async with await trio.open_file(self._fingerprint_file_path, "a+", encoding="utf-8") as file:
+				async for log_entry in self._fingerprint_receive_channel:
+					await file.write(log_entry.model_dump_json(indent=4) + end_of_entry)
+					await file.flush()
+		except* TrioEndExceptions:
+			pass
+		except* BaseException as error:
+			log_exception(error)
+		finally:
+			if self._fingerprint_file_writing_stopped is not None:
+				self._fingerprint_file_writing_stopped.set()
+	
+	async def _write_cdp_file(self):
+		"""
+		Asynchronously writes CDP log entries to the target-specific file.
+
+		This method continuously receives `CDPTargetLogEntry` objects from its channel
+		and appends their string representation to the configured file,
+		applying log level and target type filters.
+		It runs as a background task.
+		"""
+		
+		try:
+			end_of_entry = "\n\n" + "=" * 100 + "\n\n"
+		
+			async with await trio.open_file(self._cdp_file_path, "a+", encoding="utf-8") as file:
+				async for log_entry in self._cdp_receive_channel:
+					await file.write(log_entry.model_dump_json(indent=4) + end_of_entry)
+					await file.flush()
+		except* TrioEndExceptions:
+			pass
+		except* BaseException as error:
+			log_exception(error)
+		finally:
+			if self._cdp_file_writing_stopped is not None:
+				self._cdp_file_writing_stopped.set()
+	
+	async def run(self):
+		"""
+		Starts the target logger, setting up its receive channel and file writing task.
+		"""
+		
+		try:
+			if not self._is_active:
+				self._cdp_file_writing_stopped = trio.Event()
+		
+				if self._cdp_file_path is not None:
+					self._nursery_object.start_soon(self._write_cdp_file)
+		
+				self._fingerprint_file_writing_stopped = trio.Event()
+		
+				if self._fingerprint_file_path is not None:
+					self._nursery_object.start_soon(self._write_fingerprint_file)
+		
+				self._is_active = True
+		except* TrioEndExceptions:
+			await self.close()
+		except* BaseException as error:
+			log_exception(error)
+			await self.close()
+
+
+def build_target_logger(
+		target_data: TargetData,
+		nursery_object: trio.Nursery,
+		logger_settings: LoggerSettings
+) -> Tuple[
+	Optional[trio.MemorySendChannel[CDPTargetLogEntry]],
+	Optional[trio.MemorySendChannel[FingerprintTargetLogEntry]],
+	TargetLogger
+]:
+	"""
+	Builds and initializes a `TargetLogger` instance.
+
+	Args:
+		target_data (TargetData): Data associated with the target.
+		nursery_object (trio.Nursery): Trio nursery for background tasks.
+		logger_settings (LoggerSettings): Logger configuration.
+
+	Returns:
+		Tuple[Optional[trio.MemorySendChannel[CDPTargetLogEntry]], Optional[trio.MemorySendChannel[FingerprintTargetLogEntry]], TargetLogger]:
+			Tuple containing send channels for logs and the initialized logger instance.
+	"""
+	
+	if logger_settings.cdp_settings is not None:
+		cdp_send, cdp_recv = trio.open_memory_channel(logger_settings.cdp_settings.buffer_size)
+	else:
+		cdp_send, cdp_recv = None, None
+	
+	if logger_settings.fingerprint_settings is not None:
+		fp_send, fp_recv = trio.open_memory_channel(logger_settings.fingerprint_settings.buffer_size)
+	else:
+		fp_send, fp_recv = None, None
+	
+	target_logger = TargetLogger(
+			logger_settings=logger_settings,
+			nursery_object=nursery_object,
+			target_data=target_data,
+			cdp_receive_channel=cdp_recv,
+			fingerprint_receive_channel=fp_recv,
+	)
+	
+	return cdp_send, fp_send, target_logger

osn_selenium/dev_tools/manager/__init__.py

@@ -0,0 +1,16 @@
+from osn_selenium.dev_tools.manager.settings import SettingsMixin
+from osn_selenium.dev_tools.manager.lifecycle import LifecycleMixin
+
+
+__all__ = ["DevTools"]
+
+
+class DevTools(LifecycleMixin, SettingsMixin):
+	"""
+	Main entry point for managing Chrome DevTools Protocol (CDP) interactions.
+
+	This class combines lifecycle management, settings configuration, and target handling
+	to provide a comprehensive interface for controlling browser behavior via CDP.
+	"""
+	
+	pass

osn_selenium/dev_tools/manager/base.py

@@ -0,0 +1,124 @@
+import trio
+from contextlib import (
+	AbstractAsyncContextManager
+)
+from osn_selenium.dev_tools.target import DevToolsTarget
+from osn_selenium.dev_tools.logger.main import MainLogger
+from osn_selenium.dev_tools.domains import DomainsSettings
+from osn_selenium.dev_tools._wrappers import DevToolsPackage
+from osn_selenium.dev_tools.settings import DevToolsSettings
+from typing import (
+	Any,
+	Dict,
+	Optional,
+	TYPE_CHECKING
+)
+from osn_selenium.dev_tools._system_utils import prepare_log_dir
+from selenium.webdriver.remote.bidi_connection import BidiConnection
+from osn_selenium.dev_tools.logger.models import (
+	CDPLogLevelStats,
+	CDPMainLogEntry,
+	CDPTargetTypeStats,
+	FingerprintAPIStats,
+	FingerprintLogLevelStats,
+	FingerprintMainLogEntry
+)
+
+
+__all__ = ["BaseMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.webdrivers.trio_threads.core import CoreWebDriver
+
+
+class BaseMixin:
+	"""
+	Base class for handling DevTools functionalities in Selenium WebDriver.
+
+	Provides an interface to interact with Chrome DevTools Protocol (CDP)
+	for advanced browser control and monitoring. This class supports event handling
+	and allows for dynamic modifications of browser behavior, such as network request interception,
+	by using an asynchronous context manager.
+
+	Attributes:
+		targets_lock (trio.Lock): A lock used for synchronizing access to shared resources, like the List of handled targets.
+		exit_event (Optional[trio.Event]): Trio Event to signal exiting of DevTools event handling.
+	"""
+	
+	def __init__(
+			self,
+			parent_webdriver: "CoreWebDriver",
+			devtools_settings: Optional[DevToolsSettings] = None
+	):
+		"""
+		Initializes the DevTools manager.
+
+		Args:
+			parent_webdriver (CoreWebDriver): The WebDriver instance to which this DevTools manager is attached.
+			devtools_settings (Optional[DevToolsSettings]): Configuration settings for DevTools.
+				If None, default settings will be used.
+		"""
+		
+		if devtools_settings is None:
+			devtools_settings = DevToolsSettings()
+		
+		self._webdriver = parent_webdriver
+		self._logger_settings = devtools_settings.logger_settings
+		self._domains_settings = devtools_settings.domains_settings
+		self._fingerprint_settings = devtools_settings.fingerprint_settings
+		self._new_targets_buffer_size = devtools_settings.new_targets_buffer_size
+		self._target_background_task = devtools_settings.target_background_task
+		
+		self._new_targets_filter = [
+			filter_.model_dump(exclude_none=True, by_alias=True)
+			for filter_ in devtools_settings.new_targets_filter
+		] if devtools_settings.new_targets_filter is not None else None
+		
+		self._bidi_connection: Optional[AbstractAsyncContextManager[BidiConnection, Any]] = None
+		self._bidi_connection_object: Optional[BidiConnection] = None
+		self._devtools_package: Optional[DevToolsPackage] = None
+		self._websocket_url: Optional[str] = None
+		self._nursery: Optional[AbstractAsyncContextManager[trio.Nursery, Optional[bool]]] = None
+		self._nursery_object: Optional[trio.Nursery] = None
+		self._handling_targets: Dict[str, DevToolsTarget] = {}
+		self.targets_lock = trio.Lock()
+		self.exit_event: Optional[trio.Event] = None
+		self._is_active = False
+		self._is_closing = False
+		self._num_cdp_logs = 0
+		self._num_fingerprint_logs = 0
+		self._cdp_targets_types_stats: Dict[str, CDPTargetTypeStats] = {}
+		self._cdp_log_level_stats: Dict[str, CDPLogLevelStats] = {}
+		self._main_logger_cdp_send_channel: Optional[trio.MemorySendChannel[CDPMainLogEntry]] = None
+		self._fingerprint_categories_stats: Dict[str, FingerprintAPIStats] = {}
+		self._fingerprint_log_level_stats: Dict[str, FingerprintLogLevelStats] = {}
+		self._main_logger_fingerprint_send_channel: Optional[trio.MemorySendChannel[FingerprintMainLogEntry]] = None
+		self._main_logger: Optional[MainLogger] = None
+		self._fingerprint_injection_script: Optional[str] = None
+		
+		prepare_log_dir(logger_settings=devtools_settings.logger_settings)
+	
+	@property
+	def is_active(self) -> bool:
+		"""
+		Checks if DevTools is currently active.
+
+		Returns:
+			bool: True if DevTools event handler context manager is active, False otherwise.
+		"""
+		
+		return self._is_active
+	
+	@property
+	def websocket_url(self) -> Optional[str]:
+		"""
+		Gets the WebSocket URL for the DevTools session.
+
+		This URL is used to establish a direct Chrome DevTools Protocol (CDP) connection
+		to the browser, enabling low-level control and event listening.
+
+		Returns:
+			Optional[str]: The WebSocket URL, or None if it has not been retrieved yet.
+		"""
+		
+		return self._websocket_url

osn_selenium/dev_tools/manager/lifecycle.py

@@ -0,0 +1,236 @@
+import trio
+from types import TracebackType
+from typing import Optional, Type
+from osn_selenium.dev_tools._decorators import log_on_error
+from osn_selenium.dev_tools._wrappers import DevToolsPackage
+from osn_selenium.dev_tools.manager.targets import TargetsMixin
+from osn_selenium.dev_tools.logger.main import build_main_logger
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from osn_selenium.exceptions.devtools import (
+	BidiConnectionNotEstablishedError,
+	CDPEndExceptions,
+	CantEnterDevToolsContextError
+)
+
+
+__all__ = ["LifecycleMixin"]
+
+
+class LifecycleMixin(TargetsMixin):
+	"""
+	Mixin managing the lifecycle of the DevTools context, including connection setup and teardown.
+	"""
+	
+	def _get_websocket_url(self) -> None:
+		"""
+		Retrieves the WebSocket URL for DevTools from the WebDriver.
+
+		This method attempts to get the WebSocket URL from the WebDriver capabilities or by directly querying the CDP details.
+		The WebSocket URL is necessary to establish a connection to the browser's DevTools.
+
+		Returns:
+			None: The WebSocket URL for DevTools, or None if it cannot be retrieved.
+
+		Raises:
+			CDPEndExceptions: If a CDP-related connection error occurs.
+			BaseException: If another unexpected error occurs during URL retrieval.
+		"""
+		
+		try:
+			driver = self._webdriver.driver
+		
+			if driver is None:
+				self._websocket_url = None
+		
+			if driver.caps.get("se:cdp"):
+				self._websocket_url = driver.caps.get("se:cdp")
+		
+			self._websocket_url = driver._get_cdp_details()[1]
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			log_exception(error)
+			raise error
+	
+	def _get_devtools_package(self) -> None:
+		"""
+		Retrieves the DevTools protocol package from the active BiDi connection.
+
+		Returns:
+			DevToolsPackage: The DevTools protocol package object, providing access to CDP domains and commands.
+
+		Raises:
+			BidiConnectionNotEstablishedError: If the BiDi connection is not active.
+		"""
+		
+		try:
+			if self._bidi_connection_object is not None:
+				self._devtools_package = DevToolsPackage(package=self._bidi_connection_object.devtools)
+			else:
+				raise BidiConnectionNotEstablishedError()
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			log_exception(error)
+			raise error
+	
+	async def run(self) -> None:
+		"""
+		Initializes and runs the DevTools manager.
+
+		This method sets up the BiDi connection, starts the Trio nursery, retrieves
+		necessary CDP packages and URLs, initializes the main logger, and adds the
+		initial target to be monitored.
+
+		Raises:
+			CantEnterDevToolsContextError: If the WebDriver is not initialized.
+		"""
+		
+		if self._webdriver.driver is None:
+			raise CantEnterDevToolsContextError(reason="Driver is not initialized")
+		
+		self._bidi_connection = self._webdriver.bidi_connection()
+		self._bidi_connection_object = await self._bidi_connection.__aenter__()
+		
+		self._nursery = trio.open_nursery()
+		self._nursery_object = await self._nursery.__aenter__()
+		
+		self._get_devtools_package()
+		self._get_websocket_url()
+		
+		self._main_logger_cdp_send_channel, self._main_logger_fingerprint_send_channel, self._main_logger = build_main_logger(self._nursery_object, self._logger_settings)
+		await self._main_logger.run()
+		
+		self.exit_event = trio.Event()
+		
+		self._fingerprint_injection_script = await self._webdriver.sync_to_trio(sync_function=self._fingerprint_settings.generate_js)()
+		main_target = (await self._get_all_targets())[0]
+		
+		await self._add_target(target_event=main_target, is_main_target=True)
+		
+		self._is_active = True
+	
+	async def __aenter__(self):
+		"""
+		Enters the asynchronous context for DevTools event handling.
+
+		This method establishes the BiDi connection, initializes the Trio nursery,
+		sets up the main target, and starts listening for DevTools events.
+
+		Raises:
+			CantEnterDevToolsContextError: If the WebDriver is not initialized.
+			BaseException: If any other unexpected error occurs during context entry.
+		"""
+		
+		await self.run()
+	
+	async def stop(
+			self,
+			exc_type: Optional[Type[BaseException]],
+			exc_val: Optional[BaseException],
+			exc_tb: Optional[TracebackType],
+	) -> None:
+		"""
+		Stops the DevTools manager and cleans up resources.
+
+		This method signals all targets to stop, closes the main logger, cancels the nursery,
+		and closes the BiDi connection.
+
+		Args:
+			exc_type (Optional[Type[BaseException]]): The exception type if stopping due to an error.
+			exc_val (Optional[BaseException]): The exception value if stopping due to an error.
+			exc_tb (Optional[TracebackType]): The traceback if stopping due to an error.
+		"""
+		
+		@log_on_error
+		async def _stop_main_logger():
+			"""Stops the main logger and closes its channels."""
+			
+			if self._main_logger_cdp_send_channel is not None:
+				await self._main_logger_cdp_send_channel.aclose()
+				self._main_logger_cdp_send_channel = None
+			
+			if self._main_logger_fingerprint_send_channel is not None:
+				await self._main_logger_fingerprint_send_channel.aclose()
+				self._main_logger_fingerprint_send_channel = None
+			
+			if self._main_logger is not None:
+				await self._main_logger.close()
+				self._main_logger = None
+		
+		@log_on_error
+		async def _stop_all_targets():
+			"""Signals all active targets to stop and waits for their completion."""
+			
+			for target in self._handling_targets.copy().values():
+				try:
+					await target.stop()
+					await target.stopped_event.wait()
+				except (BaseException,):
+					pass
+			
+			self._handling_targets = {}
+		
+		@log_on_error
+		async def _close_nursery():
+			"""Asynchronously exits the Trio nursery context manager."""
+			
+			if self._nursery_object is not None:
+				self._nursery_object.cancel_scope.cancel()
+				self._nursery_object = None
+			
+			if self._nursery is not None:
+				await self._nursery.__aexit__(exc_type, exc_val, exc_tb)
+				self._nursery = None
+		
+		@log_on_error
+		async def _close_bidi_connection():
+			"""Asynchronously exits the BiDi connection context manager."""
+			
+			if self._bidi_connection is not None:
+				await self._bidi_connection.__aexit__(exc_type, exc_val, exc_tb)
+				self._bidi_connection = None
+				self._bidi_connection_object = None
+		
+		if self._is_active:
+			self._is_closing = True
+			self.exit_event.set()
+		
+			await _stop_all_targets()
+			await _stop_main_logger()
+			await _close_nursery()
+			await _close_bidi_connection()
+		
+			self.exit_event = None
+			self._devtools_package = None
+			self._websocket_url = None
+			self._num_cdp_logs = 0
+			self._num_fingerprint_logs = 0
+			self._cdp_targets_types_stats = {}
+			self._cdp_log_level_stats = {}
+			self._fingerprint_categories_stats = {}
+			self._fingerprint_log_level_stats = {}
+			self._is_active = False
+			self._is_closing = False
+	
+	async def __aexit__(
+			self,
+			exc_type: Optional[Type[BaseException]],
+			exc_val: Optional[BaseException],
+			exc_tb: Optional[TracebackType],
+	):
+		"""
+		Asynchronously exits the DevTools event handling context.
+
+		This method is called when exiting an `async with` block with a DevTools instance.
+		It ensures that all event listeners are cancelled, the Trio nursery is closed,
+		and the BiDi connection is properly shut down. Cleanup attempts are made even if
+		an exception occurred within the `async with` block.
+
+		Args:
+			exc_type (Optional[Type[BaseException]]): The exception type, if any, that caused the context to be exited.
+			exc_val (Optional[BaseException]): The exception value, if any.
+			exc_tb (Optional[TracebackType]): The exception traceback, if any.
+		"""
+		
+		await self.stop(exc_type=exc_type, exc_val=exc_val, exc_tb=exc_tb)