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

osn_selenium/dev_tools/manager/logging.py

@@ -0,0 +1,153 @@
+import trio
+from osn_selenium.dev_tools.manager.base import BaseMixin
+from osn_selenium.exceptions.devtools import CDPEndExceptions
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from osn_selenium.dev_tools.logger.models import (
+	CDPLogLevelStats,
+	CDPMainLogEntry,
+	CDPTargetLogEntry,
+	FingerprintAPIStats,
+	FingerprintLogLevelStats,
+	FingerprintMainLogEntry,
+	FingerprintTargetLogEntry
+)
+
+
+__all__ = ["LoggingMixin"]
+
+
+class LoggingMixin(BaseMixin):
+	"""
+	Mixin for aggregating logs from all targets in the DevTools manager.
+	"""
+	
+	async def _add_main_cdp_log(self):
+		"""
+		Sends updated overall logging statistics to the main logger.
+
+		This method constructs a `MainLogEntry` with current statistics and
+		sends it to the `_main_logger_send_channel`. If the channel buffer is full,
+		the log is dropped silently.
+
+		Raises:
+			CDPEndExceptions: If a CDP connection error occurs.
+			BaseException: If any other error occurs during logging.
+		"""
+		
+		try:
+			if self._main_logger_cdp_send_channel is not None and self._main_logger is not None:
+				log_entry = CDPMainLogEntry(
+						num_channels=len(self._handling_targets),
+						targets_types_stats=self._cdp_targets_types_stats,
+						num_logs=self._num_cdp_logs,
+						log_level_stats=self._cdp_log_level_stats,
+						channels_stats=[
+							target.cdp_log_stats
+							for target in self._handling_targets.values()
+							if target.target_type_log_accepted
+						],
+				)
+		
+				self._main_logger_cdp_send_channel.send_nowait(log_entry)
+		except (trio.WouldBlock, trio.BrokenResourceError):
+			pass
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			log_exception(error)
+			raise error
+	
+	async def _add_cdp_log(self, log_entry: CDPTargetLogEntry):
+		"""
+		Updates internal logging statistics based on a new log entry.
+
+		This method increments total log counts and updates per-channel and per-level statistics.
+		It also triggers an update to the main logger.
+
+		Args:
+			log_entry (CDPTargetLogEntry): The log entry to use for updating statistics.
+
+		Raises:
+			BaseException: Catches and logs any unexpected errors during the log aggregation process.
+		"""
+		
+		try:
+			self._num_cdp_logs += 1
+		
+			if log_entry.level not in self._cdp_log_level_stats:
+				self._cdp_log_level_stats[log_entry.level] = CDPLogLevelStats(num_logs=1, last_log_time=log_entry.datetime)
+			else:
+				self._cdp_log_level_stats[log_entry.level].num_logs += 1
+				self._cdp_log_level_stats[log_entry.level].last_log_time = log_entry.datetime
+		
+			await self._add_main_cdp_log()
+		except CDPEndExceptions:
+			pass
+		except BaseException as error:
+			log_exception(error)
+			raise error
+	
+	async def _add_main_fingerprint_log(self):
+		"""
+		Sends updated overall fingerprint logging statistics to the main logger.
+
+		Raises:
+			CDPEndExceptions: If a CDP connection error occurs.
+			BaseException: If any other error occurs during logging.
+		"""
+		
+		try:
+			if self._main_logger_fingerprint_send_channel is not None and self._main_logger is not None:
+				log_entry = FingerprintMainLogEntry(
+						num_channels=len(self._handling_targets),
+						apis_stats=self._fingerprint_categories_stats,
+						num_logs=self._num_fingerprint_logs,
+						log_level_stats=self._fingerprint_log_level_stats,
+						channels_stats=[
+							target.fingerprint_log_stats
+							for target in self._handling_targets.values()
+							if target.target_type_log_accepted
+						],
+				)
+		
+				self._main_logger_fingerprint_send_channel.send_nowait(log_entry)
+		except (trio.WouldBlock, trio.BrokenResourceError):
+			pass
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			log_exception(error)
+			raise error
+	
+	async def _add_fingerprint_log(self, log_entry: FingerprintTargetLogEntry):
+		"""
+		Updates internal fingerprint logging statistics based on a new log entry.
+
+		Args:
+			log_entry (FingerprintTargetLogEntry): The log entry to use for updating statistics.
+
+		Raises:
+			BaseException: Catches and logs any unexpected errors during the log aggregation process.
+		"""
+		
+		try:
+			self._num_fingerprint_logs += 1
+		
+			if log_entry.level not in self._fingerprint_log_level_stats:
+				self._fingerprint_log_level_stats[log_entry.level] = FingerprintLogLevelStats(num_logs=1, last_log_time=log_entry.datetime)
+			else:
+				self._fingerprint_log_level_stats[log_entry.level].num_logs += 1
+				self._fingerprint_log_level_stats[log_entry.level].last_log_time = log_entry.datetime
+		
+			if log_entry.api not in self._fingerprint_categories_stats:
+				self._fingerprint_categories_stats[log_entry.api] = FingerprintAPIStats(num_logs=1, methods_stats={log_entry.used_method: 1})
+			else:
+				self._fingerprint_categories_stats[log_entry.api].num_logs += 1
+				self._fingerprint_categories_stats[log_entry.api].methods_stats[log_entry.used_method] = self._fingerprint_categories_stats[log_entry.api].methods_stats.get(log_entry.used_method, 0) + 1
+		
+			await self._add_main_fingerprint_log()
+		except CDPEndExceptions:
+			pass
+		except BaseException as error:
+			log_exception(error)
+			raise error

osn_selenium/dev_tools/manager/settings.py

@@ -0,0 +1,89 @@
+from typing import Sequence, Union
+from osn_selenium.dev_tools.manager.base import BaseMixin
+from osn_selenium.dev_tools._decorators import warn_if_active
+from osn_selenium.exceptions.configuration import NotExpectedTypeError
+from osn_selenium.dev_tools.domains import (
+	DomainsSettings,
+	domains_classes_type,
+	domains_type
+)
+
+
+__all__ = ["SettingsMixin"]
+
+
+class SettingsMixin(BaseMixin):
+	"""
+	Mixin for managing DevTools domain settings (handlers and configurations).
+	"""
+	
+	@warn_if_active
+	def _remove_handler_settings(self, domain: domains_type):
+		"""
+		Removes the settings for a specific domain.
+
+		This is an internal method intended to be used only when the DevTools context is not active.
+		It uses the `@warn_if_active` decorator to log a warning if called incorrectly.
+
+		Args:
+			domain (domains_type): The name of the domain to remove settings for.
+		"""
+		
+		if self._domains_settings is not None:
+			self._domains_settings.pop(domain, None)
+	
+	def remove_domains_handlers(self, domains: Union[domains_type, Sequence[domains_type]]):
+		"""
+		Removes handler settings for one or more DevTools domains.
+
+		This method can be called with a single domain name or a sequence of domain names.
+		It should only be called when the DevTools context is not active.
+
+		Args:
+			domains (Union[domains_type, Sequence[domains_type]]): A single domain name as a string,
+				or a sequence of domain names to be removed.
+
+		Raises:
+			TypeError: If the `domains` argument is not a string or a sequence of strings.
+		"""
+		
+		if isinstance(domains, str):
+			self._remove_handler_settings(domains)
+		elif isinstance(domains, Sequence) and all(isinstance(domain, str) for domain in domains):
+			for domain in domains:
+				self._remove_handler_settings(domain)
+		else:
+			raise NotExpectedTypeError(
+					value_name="domains",
+					value=domains,
+					valid_types=("str", "Sequence[str]")
+			)
+	
+	@warn_if_active
+	def _set_handler_settings(self, domain: domains_type, settings: domains_classes_type):
+		"""
+		Sets the handler settings for a specific domain.
+
+		This is an internal method intended to be used only when the DevTools context is not active.
+		It uses the `@warn_if_active` decorator to log a warning if called incorrectly.
+
+		Args:
+			domain (domains_type): The name of the domain to configure.
+			settings (domains_classes_type): The configuration settings for the domain.
+		"""
+		
+		setattr(self._domains_settings, domain, settings)
+	
+	def set_domains_handlers(self, settings: DomainsSettings):
+		"""
+		Sets handler settings for multiple domains from a DomainsSettings object.
+
+		This method iterates through the provided settings and applies them to the corresponding domains.
+		It should only be called when the DevTools context is not active.
+
+		Args:
+			settings (DomainsSettings): An object containing the configuration for one or more domains.
+		"""
+		
+		for domain_name, domain_settings in settings.model_dump(exclude_none=True).items():
+			self._set_handler_settings(domain_name, domain_settings)

osn_selenium/dev_tools/manager/targets.py

@@ -0,0 +1,175 @@
+from typing import Any, List, Optional
+from osn_selenium.dev_tools.models import TargetData
+from osn_selenium.dev_tools.target import DevToolsTarget
+from osn_selenium.dev_tools.manager.logging import LoggingMixin
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from osn_selenium.dev_tools.logger.models import CDPTargetTypeStats
+from osn_selenium.exceptions.devtools import (
+	BidiConnectionNotEstablishedError,
+	CDPEndExceptions
+)
+
+
+__all__ = ["TargetsMixin"]
+
+
+class TargetsMixin(LoggingMixin):
+	"""
+	Mixin for adding, removing, and retrieving DevTools targets.
+	"""
+	
+	async def _remove_target(self, target: DevToolsTarget) -> Optional[bool]:
+		"""
+		Removes a target ID from the List of currently handled targets.
+
+		This method also triggers the removal of the target's specific logger channel
+		and updates overall logging statistics.
+
+		Args:
+			target (DevToolsTarget): The target instance to remove.
+
+		Returns:
+			Optional[bool]: True if the target ID was successfully removed, False if it was not found.
+							Returns None if an exception occurs.
+		"""
+		
+		try:
+			async with self.targets_lock:
+				if target.target_id in self._handling_targets:
+					self._cdp_targets_types_stats[target.type_].num_targets -= 1
+		
+					target = self._handling_targets.pop(target.target_id)
+					await target.log_cdp_step(message=f"Target '{target.target_id}' removed.")
+					await target.stop()
+		
+					await self._add_main_cdp_log()
+		
+					return True
+				else:
+					return False
+		except CDPEndExceptions:
+			pass
+		except BaseException as error:
+			log_exception(error)
+	
+	async def _add_target(self, target_event: Any, is_main_target: bool = False) -> Optional[bool]:
+		"""
+		Adds a new browser target to the manager based on a target event.
+
+		This method processes events like `TargetCreated` or `AttachedToTarget`
+		to initialize and manage new `DevToolsTarget` instances. It ensures
+		that targets are not added if the manager is closing or if they already exist.
+
+		Args:
+			target_event (Any): The event object containing target information.
+								 Expected to have a `target_info` attribute or be the target info itself.
+
+		Returns:
+			Optional[bool]: True if a new target was successfully added and started,
+							False if the target already existed or was filtered,
+							or None if an error occurred.
+
+		Raises:
+			BaseException: Catches and logs any unexpected errors during target addition.
+		"""
+		
+		try:
+			if hasattr(target_event, "target_info"):
+				target_info = target_event.target_info
+			else:
+				target_info = target_event
+		
+			async with self.targets_lock:
+				target_id = target_info.target_id
+		
+				if self._is_closing:
+					return False
+		
+				if target_id not in self._handling_targets:
+					self._handling_targets[target_id] = DevToolsTarget(
+							target_data=TargetData(
+									target_id=target_id,
+									type_=target_info.type_,
+									title=target_info.title,
+									url=target_info.url,
+									attached=target_info.attached,
+									can_access_opener=target_info.can_access_opener,
+									opener_id=target_info.opener_id,
+									opener_frame_id=target_info.opener_frame_id,
+									browser_context_id=target_info.browser_context_id,
+									subtype=target_info.subtype,
+							),
+							is_main_target=is_main_target,
+							logger_settings=self._logger_settings,
+							domains_settings=self._domains_settings,
+							devtools_package=self._devtools_package,
+							websocket_url=self._websocket_url,
+							new_targets_filter_list=self._new_targets_filter,
+							new_targets_buffer_size=self._new_targets_buffer_size,
+							nursery=self._nursery_object,
+							exit_event=self.exit_event,
+							fingerprint_injection_script=self._fingerprint_injection_script,
+							target_background_task=self._target_background_task,
+							add_target_func=self._add_target,
+							remove_target_func=self._remove_target,
+							add_cdp_log_func=self._add_cdp_log,
+							add_fingerprint_log_func=self._add_fingerprint_log,
+					)
+		
+					if target_info.type_ not in self._cdp_targets_types_stats:
+						self._cdp_targets_types_stats[target_info.type_] = CDPTargetTypeStats(num_targets=1)
+					else:
+						self._cdp_targets_types_stats[target_info.type_].num_targets += 1
+		
+					await self._add_main_cdp_log()
+		
+					self._nursery_object.start_soon(self._handling_targets[target_id].run)
+		
+					return True
+				else:
+					self._handling_targets[target_id].type_ = target_info.type_
+					self._handling_targets[target_id].title = target_info.title
+					self._handling_targets[target_id].url = target_info.url
+					self._handling_targets[target_id].attached = target_info.attached
+					self._handling_targets[target_id].can_access_opener = target_info.can_access_opener
+					self._handling_targets[target_id].opener_id = target_info.opener_id
+					self._handling_targets[target_id].opener_frame_id = target_info.opener_frame_id
+					self._handling_targets[target_id].browser_context_id = target_info.browser_context_id
+					self._handling_targets[target_id].subtype = target_info.subtype
+		
+					return False
+		except* CDPEndExceptions:
+			pass
+		except* BaseException as error:
+			log_exception(error)
+			raise error
+	
+	async def _get_all_targets(self) -> List[Any]:
+		"""
+		Retrieves a List of all currently active browser targets.
+
+		Returns:
+			List[Any]: A List of target objects, each containing information like target ID, type, and URL.
+
+		Raises:
+			BidiConnectionNotEstablishedError: If the BiDi connection is not active.
+		"""
+		
+		try:
+			if self._bidi_connection_object is not None:
+				targets_filter = self._devtools_package.get("target.TargetFilter")(
+						[
+							{"exclude": False, "type": "page"},
+							{"exclude": False, "type": "tab"},
+							{"exclude": True}
+						]
+				)
+		
+				return await self._bidi_connection_object.session.execute(self._devtools_package.get("target.get_targets")(targets_filter))
+		
+			raise BidiConnectionNotEstablishedError()
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			log_exception(error)
+			raise error

osn_selenium/dev_tools/models.py

@@ -0,0 +1,49 @@
+from typing import Optional
+from osn_selenium._base_models import DictModel
+
+
+__all__ = ["FingerprintData", "TargetData"]
+
+
+class TargetData(DictModel):
+	"""
+	Dataclass to hold essential information about a browser target.
+
+	Attributes:
+		target_id (Optional[str]): The unique identifier for the target.
+		type_ (Optional[str]): The type of the target (e.g., "page", "iframe", "worker").
+		title (Optional[str]): The title of the target (e.g., the page title).
+		url (Optional[str]): The URL of the target.
+		attached (Optional[bool]): Indicates if the DevTools session is currently attached to this target.
+		can_access_opener (Optional[bool]): Whether the target can access its opener.
+		opener_id (Optional[str]): The ID of the opener target.
+		opener_frame_id (Optional[str]): The ID of the opener frame.
+		browser_context_id (Optional[str]): The browser context ID associated with the target.
+		subtype (Optional[str]): Subtype of the target.
+	"""
+	
+	target_id: Optional[str] = None
+	type_: Optional[str] = None
+	title: Optional[str] = None
+	url: Optional[str] = None
+	attached: Optional[bool] = None
+	can_access_opener: Optional[bool] = None
+	opener_id: Optional[str] = None
+	opener_frame_id: Optional[str] = None
+	browser_context_id: Optional[str] = None
+	subtype: Optional[str] = None
+
+
+class FingerprintData(DictModel):
+	"""
+	Dataclass representing detected fingerprinting activity.
+
+	Attributes:
+		api (str): The API that was accessed.
+		used_method (str): The method called.
+		stacktrace (Optional[str]): The stack trace where the access occurred.
+	"""
+	
+	api: str
+	used_method: str
+	stacktrace: Optional[str]

osn_selenium/dev_tools/settings.py

@@ -0,0 +1,139 @@
+from pathlib import Path
+from pydantic import Field
+from osn_selenium._base_models import DictModel
+from osn_selenium.dev_tools.filters import TargetFilter
+from osn_selenium.dev_tools.domains import DomainsSettings
+from typing import (
+	Literal,
+	Optional,
+	Sequence,
+	Union
+)
+from osn_selenium.javascript.fingerprint import FingerprintSettings
+from osn_selenium.dev_tools._typehints import (
+	CDP_LOG_LEVELS_TYPEHINT,
+	DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT,
+	FINGERPRINT_LOG_LEVELS_TYPEHINT
+)
+
+
+__all__ = [
+	"CDPLoggerSettings",
+	"DevToolsSettings",
+	"FingerprintLoggerSettings",
+	"LoggerSettings"
+]
+
+
+class FingerprintLoggerSettings(DictModel):
+	"""
+	Configuration settings for fingerprint logging.
+
+	Attributes:
+		buffer_size (int): The size of the log buffer. Defaults to 100.
+		log_level_filter_mode (Literal["exclude", "include"]): Mode for filtering log levels.
+			Defaults to "exclude".
+		log_level_filter (Optional[Union[FingerprintLogLevelsType, Sequence[FingerprintLogLevelsType]]]):
+			Specific log levels to filter based on the mode. Defaults to None.
+		category_filter_mode (Literal["exclude", "include"]): Mode for filtering categories.
+			Defaults to "exclude".
+		category_filter (Optional[Union[str, Sequence[str]]]): Specific categories to filter.
+			Defaults to None.
+		send_wait (bool): Whether to wait for the log to be sent. Defaults to False.
+	"""
+	
+	buffer_size: int = 100
+	log_level_filter_mode: Literal["exclude", "include"] = "exclude"
+	log_level_filter: Optional[
+		Union[
+			FINGERPRINT_LOG_LEVELS_TYPEHINT,
+			Sequence[FINGERPRINT_LOG_LEVELS_TYPEHINT]
+		]
+	] = None
+	category_filter_mode: Literal["exclude", "include"] = "exclude"
+	category_filter: Optional[Union[str, Sequence[str]]] = None
+	send_wait: bool = False
+
+
+class CDPLoggerSettings(DictModel):
+	"""
+	Configuration settings for Chrome DevTools Protocol (CDP) logging.
+
+	Attributes:
+		buffer_size (int): The size of the log buffer. Defaults to 100.
+		log_level_filter_mode (Literal["exclude", "include"]): The mode for filtering log levels.
+			"exclude" means log levels in `log_level_filter` will be excluded.
+			"include" means only log levels in `log_level_filter` will be included.
+			Defaults to "exclude".
+		log_level_filter (Optional[Union[CDPLogLevelsType, Sequence[CDPLogLevelsType]]]):
+			A single log level or a sequence of log levels to filter by.
+			Used in conjunction with `log_level_filter_mode`. Defaults to None.
+		target_type_filter_mode (Literal["exclude", "include"]): The mode for filtering target types.
+			"exclude" means target types in `target_type_filter` will be excluded.
+			"include" means only target types in `target_type_filter` will be included.
+			Defaults to "exclude".
+		target_type_filter (Optional[Union[str, Sequence[str]]]):
+			A single target type string or a sequence of target type strings to filter by.
+			Used in conjunction with `target_type_filter_mode`. Defaults to None.
+		send_wait (bool): Whether to wait for the log to be sent. Defaults to False.
+	"""
+	
+	buffer_size: int = 100
+	log_level_filter_mode: Literal["exclude", "include"] = "exclude"
+	log_level_filter: Optional[Union[CDP_LOG_LEVELS_TYPEHINT, Sequence[CDP_LOG_LEVELS_TYPEHINT]]] = None
+	target_type_filter_mode: Literal["exclude", "include"] = "exclude"
+	target_type_filter: Optional[Union[str, Sequence[str]]] = None
+	send_wait: bool = False
+
+
+class LoggerSettings(DictModel):
+	"""
+	Settings for configuring the LoggerManager.
+
+	Attributes:
+		dir_path (Optional[Path]): The base directory where log files will be stored.
+			If None, logging will only happen in memory and not be written to files.
+			Defaults to None.
+		renew_log (bool): Whether to clear/renew the log directory on startup. Defaults to True.
+		cdp_settings (Optional[CDPLoggerSettings]): Settings specific to CDP logging. Defaults to None.
+		fingerprint_settings (Optional[FingerprintLoggerSettings]): Settings specific to fingerprint logging.
+			Defaults to None.
+	"""
+	
+	dir_path: Optional[Path] = None
+	renew_log: bool = True
+	cdp_settings: Optional[CDPLoggerSettings] = None
+	fingerprint_settings: Optional[FingerprintLoggerSettings] = None
+
+
+class DevToolsSettings(DictModel):
+	"""
+	Settings for configuring the DevTools manager.
+
+	Attributes:
+		new_targets_filter (Optional[Sequence[TargetFilter]]): A sequence of `TargetFilter` objects
+			to control which new browser targets (e.g., tabs, iframes) DevTools should discover and attach to.
+			Defaults to None, meaning all targets are considered.
+		new_targets_buffer_size (int): The buffer size for the Trio memory channel
+			used to receive new target events. A larger buffer can prevent `trio.WouldBlock`
+			errors under high event load. Defaults to 100.
+		target_background_task (Optional[devtools_background_func_type]): An optional asynchronous function
+			that will be run as a background task for each attached DevTools target. This can be used
+			for custom per-target logic. Defaults to None.
+		logger_settings (Optional[LoggerSettings]): Configuration settings for the internal logging system.
+			If None, default logging settings will be used (no file logging by default).
+			Defaults to None.
+		fingerprint_settings (Optional[FingerprintSettings]): Configuration for fingerprint detection.
+		domains_settings (Optional[DomainsSettings]): Configuration settings for various DevTools domains.
+	"""
+	
+	new_targets_filter: Optional[Sequence[TargetFilter]] = None
+	new_targets_buffer_size: int = 100
+	target_background_task: Optional[DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT] = None
+	logger_settings: Optional[LoggerSettings] = Field(default_factory=LoggerSettings)
+	fingerprint_settings: Optional[FingerprintSettings] = None
+	domains_settings: Optional[DomainsSettings] = None
+
+
+LoggerSettings.model_rebuild()
+DevToolsSettings.model_rebuild()

osn_selenium/dev_tools/target/__init__.py

@@ -0,0 +1,16 @@
+from osn_selenium.dev_tools.target.lifecycle import LifecycleMixin
+
+
+__all__ = ["DevToolsTarget"]
+
+
+class DevToolsTarget(LifecycleMixin):
+	"""
+	Manages the DevTools Protocol session and event handling for a specific browser target.
+
+	Each `DevToolsTarget` instance represents a single CDP target (e.g., a browser tab,
+	an iframe, or a service worker) and handles its dedicated CDP session, event listeners,
+	and associated logging.
+	"""
+	
+	pass