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

osn_selenium/dev_tools/target/events.py

@@ -0,0 +1,120 @@
+import trio
+from typing import List, TYPE_CHECKING
+from osn_selenium.exceptions.devtools import CDPEndExceptions
+from osn_selenium.dev_tools.target.logging import LoggingMixin
+
+
+__all__ = ["EventHandlersMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.domains.abstract import (AbstractDomainSettings, AbstractEventSettings)
+
+
+class EventHandlersMixin(LoggingMixin):
+	"""
+	Mixin for handling generic DevTools domain events.
+	"""
+	
+	async def _run_event_handler(
+			self,
+			domain_handler_ready_event: trio.Event,
+			event_config: "AbstractEventSettings"
+	):
+		"""
+		Runs a specific event handler listener loop.
+
+		Listens for events of the type specified in `event_config` and invokes the configured `handle_function`.
+
+		Args:
+			domain_handler_ready_event (trio.Event): Event to signal that this specific handler is ready.
+			event_config (AbstractEventSettings): Configuration for the specific event.
+
+		Raises:
+			CDPEndExceptions: If connection issues occur.
+			BaseException: If initialization fails.
+		"""
+		
+		await self.log_cdp_step(message=f"Event handler '{event_config.class_to_use_path}' starting.")
+		
+		try:
+			receiver_channel: trio.MemoryReceiveChannel = self.cdp_session.listen(
+					self.devtools_package.get(event_config.class_to_use_path),
+					buffer_size=event_config.listen_buffer_size
+			)
+			channel_stopped_event = trio.Event()
+		
+			self._events_receive_channels[event_config.class_to_use_path] = (receiver_channel, channel_stopped_event)
+		
+			domain_handler_ready_event.set()
+			handler = event_config.handle_function
+		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=f"Event handler '{event_config.class_to_use_path}' started.")
+		
+		keep_alive = True
+		while keep_alive:
+			try:
+				event = await receiver_channel.receive()
+				self._nursery_object.start_soon(handler, self, event_config, event)
+			except* CDPEndExceptions:
+				keep_alive = False
+			except* BaseException as error:
+				await self.log_cdp_error(error=error)
+				keep_alive = False
+		
+		channel_stopped_event.set()
+	
+	async def _run_events_handlers(
+			self,
+			events_ready_event: trio.Event,
+			domain_config: "AbstractDomainSettings"
+	):
+		"""
+		Sets up and runs event handlers for a specific domain.
+
+		Iterates through the domain configuration and starts a separate task for each configured event handler.
+
+		Args:
+			events_ready_event (trio.Event): Event to signal when all handlers for the domain are ready.
+			domain_config (AbstractDomainSettings): Configuration for the domain events.
+
+		Raises:
+			CDPEndExceptions: If connection issues occur.
+			BaseException: If other errors occur during setup.
+		"""
+		
+		await self.log_cdp_step(
+				message=f"Domain '{domain_config.name}' events handlers setup started."
+		)
+		
+		try:
+			events_handlers_ready_events: List[trio.Event] = []
+		
+			for event_name, event_config in domain_config.handlers.model_dump(exclude_none=True).items():
+				if event_config is not None:
+					event_handler_ready_event = trio.Event()
+					events_handlers_ready_events.append(event_handler_ready_event)
+		
+					self._nursery_object.start_soon(
+							self._run_event_handler,
+							event_handler_ready_event,
+							getattr(domain_config.handlers, event_name)
+					)
+		
+			for event_handler_ready_event in events_handlers_ready_events:
+				await event_handler_ready_event.wait()
+		
+			events_ready_event.set()
+		
+			await self.log_cdp_step(
+					message=f"Domain '{domain_config.name}' events handlers setup complete."
+			)
+		except* CDPEndExceptions as error:
+			raise error
+		except* BaseException as error:
+			await self.log_cdp_error(error=error)
+			raise error

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,179 @@
+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 channel in self._events_receive_channels.values():
+			await channel[0].aclose()
+			await channel[1].wait()
+		
+		self._events_receive_channels = {}
+		
+		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,155 @@
+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:
+				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:
+				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)}.")