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

osn_selenium/dev_tools/target/base.py

@@ -0,0 +1,427 @@
+import trio
+from osn_selenium.dev_tools.models import TargetData
+from selenium.webdriver.common.bidi.cdp import CdpSession
+from osn_selenium.dev_tools._wrappers import DevToolsPackage
+from osn_selenium.dev_tools.logger.target import TargetLogger
+from typing import (
+	Any,
+	Callable,
+	Coroutine,
+	Dict,
+	Optional,
+	Sequence,
+	TYPE_CHECKING,
+	Tuple
+)
+from osn_selenium.dev_tools._validators import (
+	validate_target_event_filter,
+	validate_type_filter
+)
+from osn_selenium.dev_tools.logger.models import (
+	CDPLoggerChannelStats,
+	CDPTargetLogEntry,
+	FingerprintLoggerChannelStats,
+	FingerprintTargetLogEntry
+)
+
+
+__all__ = ["BaseMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.target import DevToolsTarget
+	from osn_selenium.dev_tools.domains import DomainsSettings
+	from osn_selenium.dev_tools.settings import LoggerSettings
+	from osn_selenium.dev_tools._typehints import DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT
+
+
+class BaseMixin:
+	"""
+	Base mixin for DevToolsTarget providing initialization, properties, and logging functionality.
+
+	This class handles the core state of a DevTools target, including its data, logging channels,
+	filter configurations, and synchronization primitives.
+
+	Attributes:
+		target_data (TargetData): The essential data identifying the target (id, type, url, etc.).
+		devtools_package (DevToolsPackage): The wrapper for the DevTools protocol module.
+		websocket_url (Optional[str]): The WebSocket URL used to connect to this target.
+		exit_event (trio.Event): Event to signal global exit.
+		started_event (trio.Event): Event set when the target handling has started.
+		about_to_stop_event (trio.Event): Event set when the target is about to stop.
+		stopped_event (trio.Event): Event set when the target handling has fully stopped.
+		background_task_ended (Optional[trio.Event]): Event set when the background task completes.
+	"""
+	
+	def __init__(
+			self,
+			target_data: TargetData,
+			is_main_target: bool,
+			logger_settings: "LoggerSettings",
+			domains_settings: Optional["DomainsSettings"],
+			devtools_package: DevToolsPackage,
+			websocket_url: Optional[str],
+			new_targets_filter_list: Sequence[Dict[str, Any]],
+			new_targets_buffer_size: int,
+			nursery: trio.Nursery,
+			exit_event: trio.Event,
+			fingerprint_injection_script: Optional[str],
+			target_background_task: Optional["DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT"],
+			add_target_func: Callable[[Any], Coroutine[Any, Any, bool]],
+			remove_target_func: Callable[["DevToolsTarget"], Coroutine[Any, Any, Optional[bool]]],
+			add_cdp_log_func: Callable[[CDPTargetLogEntry], Coroutine[Any, Any, None]],
+			add_fingerprint_log_func: Callable[[FingerprintTargetLogEntry], Coroutine[Any, Any, None]],
+	):
+		"""
+		Initializes the BaseMixin.
+
+		Args:
+			target_data (TargetData): Information about the target.
+			is_main_target (bool): Whether this is the primary target.
+			logger_settings ("LoggerSettings"): Configuration for logging.
+			domains_settings (Optional["DomainsSettings"]): Configuration for enabled domains and handlers.
+			devtools_package (DevToolsPackage): Access to CDP commands and events.
+			websocket_url (Optional[str]): The debugger URL.
+			new_targets_filter_list (Sequence[Mapping[str, Any]]): Filters for discovering new targets.
+			new_targets_buffer_size (int): Buffer size for new target events.
+			nursery (trio.Nursery): Trio nursery for background tasks.
+			exit_event (trio.Event): Signal to stop all operations.
+			fingerprint_injection_script (Optional[str]): JS script to inject into the target.
+			target_background_task (Optional[devtools_background_func_type]): Optional background task to run.
+			add_target_func (Callable[[Any], Coroutine[Any, Any, bool]]): Callback to add a new target.
+			remove_target_func (Callable[[DevToolsTarget], Coroutine[Any, Any, Optional[bool]]]): Callback to remove this target.
+			add_cdp_log_func (Callable[[CDPTargetLogEntry], Coroutine[Any, Any, None]]): Callback to record a CDP log entry.
+			add_fingerprint_log_func (Callable[[FingerprintTargetLogEntry], Coroutine[Any, Any, None]]): Callback to record a fingerprint log entry.
+		"""
+		
+		self.target_data = target_data
+		self._is_main_target = is_main_target
+		self._logger_settings = logger_settings
+		self._domains_settings = domains_settings
+		self.devtools_package = devtools_package
+		self.websocket_url = websocket_url
+		self._new_targets_filter_list = new_targets_filter_list
+		self._new_targets_buffer_size = new_targets_buffer_size
+		self._nursery_object = nursery
+		self.exit_event = exit_event
+		self._target_background_task = target_background_task
+		self._add_target_func = add_target_func
+		self._remove_target_func = remove_target_func
+		self._add_cdp_log_func = add_cdp_log_func
+		self._add_fingerprint_log_func = add_fingerprint_log_func
+		self._fingerprint_injection_script = fingerprint_injection_script
+		
+		self._new_targets_events_filters = validate_target_event_filter(filter_=new_targets_filter_list)
+		
+		self._cdp_target_type_log_accepted = validate_type_filter(
+				type_=self.type_,
+				filter_mode=self._logger_settings.cdp_settings.target_type_filter_mode,
+				filter_instances=self._logger_settings.cdp_settings.target_type_filter
+		)
+		
+		self._cdp_log_stats = CDPLoggerChannelStats(
+				target_id=target_data.target_id,
+				title=target_data.title,
+				url=target_data.url,
+		)
+		
+		self._fingerprint_log_stats = FingerprintLoggerChannelStats(
+				target_id=target_data.target_id,
+				title=target_data.title,
+				url=target_data.url,
+		)
+		
+		self.started_event = trio.Event()
+		self.about_to_stop_event = trio.Event()
+		self.background_task_ended: Optional[trio.Event] = None
+		self.stopped_event = trio.Event()
+		self._logger_cdp_send_channel: Optional[trio.MemorySendChannel[CDPTargetLogEntry]] = None
+		self._logger_fingerprint_send_channel: Optional[trio.MemorySendChannel[FingerprintTargetLogEntry]] = None
+		self._logger: Optional[TargetLogger] = None
+		self._cdp_session: Optional[CdpSession] = None
+		self._new_target_receive_channel: Optional[Tuple[trio.MemoryReceiveChannel, trio.Event]] = None
+		self._detached_receive_channel: Optional[trio.MemoryReceiveChannel] = None
+		self._events_receive_channels: Dict[str, Tuple[trio.MemoryReceiveChannel, trio.Event]] = {}
+		self._cancel_scopes: Dict[str, trio.CancelScope] = {}
+	
+	@property
+	def type_(self) -> Optional[str]:
+		"""
+		Gets the type of the target (e.g., 'page', 'iframe').
+
+		Returns:
+			Optional[str]: The target type.
+		"""
+		
+		return self.target_data.type_
+	
+	@type_.setter
+	def type_(self, value: Optional[str]) -> None:
+		"""
+		Sets the target type and re-evaluates log filtering.
+
+		Args:
+			value (Optional[str]): The new target type.
+		"""
+		
+		self._cdp_target_type_log_accepted = validate_type_filter(
+				type_=value,
+				filter_mode=self._logger_settings.cdp_settings.target_type_filter_mode,
+				filter_instances=self._logger_settings.cdp_settings.target_type_filter
+		)
+		self.target_data.type_ = value
+	
+	@property
+	def attached(self) -> Optional[bool]:
+		"""
+		Checks if the target is currently attached.
+
+		Returns:
+			Optional[bool]: True if attached, False otherwise.
+		"""
+		
+		return self.target_data.attached
+	
+	@attached.setter
+	def attached(self, value: Optional[bool]) -> None:
+		"""
+		Sets the attached status.
+
+		Args:
+			value (Optional[bool]): The new attached status.
+		"""
+		
+		self.target_data.attached = value
+	
+	@property
+	def browser_context_id(self) -> Optional[str]:
+		"""
+		Gets the browser context ID.
+
+		Returns:
+			Optional[str]: The browser context ID.
+		"""
+		
+		return self.target_data.browser_context_id
+	
+	@browser_context_id.setter
+	def browser_context_id(self, value: Optional[str]) -> None:
+		"""
+		Sets the browser context ID.
+
+		Args:
+			value (Optional[str]): The new browser context ID.
+		"""
+		
+		self.target_data.browser_context_id = value
+	
+	@property
+	def can_access_opener(self) -> Optional[bool]:
+		"""
+		Checks if the target can access its opener.
+
+		Returns:
+			Optional[bool]: True if accessible, False otherwise.
+		"""
+		
+		return self.target_data.can_access_opener
+	
+	@can_access_opener.setter
+	def can_access_opener(self, value: Optional[bool]) -> None:
+		"""
+		Sets whether the target can access its opener.
+
+		Args:
+			value (Optional[bool]): Access status.
+		"""
+		
+		self.target_data.can_access_opener = value
+	
+	@property
+	def cancel_scopes(self) -> Dict[str, trio.CancelScope]:
+		"""
+		Provides access to the dictionary of cancellation scopes.
+
+		Returns:
+			Dict[str, trio.CancelScope]: The cancel scopes dictionary.
+		"""
+		
+		return self._cancel_scopes
+	
+	@property
+	def cdp_log_stats(self) -> CDPLoggerChannelStats:
+		"""
+		Gets the CDP logging statistics for this target channel.
+
+		Returns:
+			CDPLoggerChannelStats: The statistics object.
+		"""
+		
+		return self._cdp_log_stats
+	
+	@property
+	def cdp_session(self) -> CdpSession:
+		"""
+		Gets the active CDP session for this target.
+
+		Returns:
+			CdpSession: The CDP session object.
+		"""
+		
+		return self._cdp_session
+	
+	@property
+	def fingerprint_log_stats(self) -> FingerprintLoggerChannelStats:
+		"""
+		Gets the fingerprint logging statistics for this target channel.
+
+		Returns:
+			FingerprintLoggerChannelStats: The statistics object.
+		"""
+		
+		return self._fingerprint_log_stats
+	
+	@property
+	def opener_frame_id(self) -> Optional[str]:
+		"""
+		Gets the ID of the opener frame.
+
+		Returns:
+			Optional[str]: The opener frame ID.
+		"""
+		
+		return self.target_data.opener_frame_id
+	
+	@opener_frame_id.setter
+	def opener_frame_id(self, value: Optional[str]) -> None:
+		"""
+		Sets the ID of the opener frame.
+
+		Args:
+			value (Optional[str]): The new opener frame ID.
+		"""
+		
+		self.target_data.opener_frame_id = value
+	
+	@property
+	def opener_id(self) -> Optional[str]:
+		"""
+		Gets the ID of the opener target.
+
+		Returns:
+			Optional[str]: The opener ID.
+		"""
+		
+		return self.target_data.opener_id
+	
+	@opener_id.setter
+	def opener_id(self, value: Optional[str]) -> None:
+		"""
+		Sets the ID of the opener target.
+
+		Args:
+			value (Optional[str]): The new opener ID.
+		"""
+		
+		self.target_data.opener_id = value
+	
+	@property
+	def subtype(self) -> Optional[str]:
+		"""
+		Gets the subtype of the target.
+
+		Returns:
+			Optional[str]: The subtype.
+		"""
+		
+		return self.target_data.subtype
+	
+	@subtype.setter
+	def subtype(self, value: Optional[str]) -> None:
+		"""
+		Sets the subtype of the target.
+
+		Args:
+			value (Optional[str]): The new subtype.
+		"""
+		
+		self.target_data.subtype = value
+	
+	@property
+	def target_id(self) -> Optional[str]:
+		"""
+		Gets the unique target ID.
+
+		Returns:
+			Optional[str]: The target ID.
+		"""
+		
+		return self.target_data.target_id
+	
+	@target_id.setter
+	def target_id(self, value: Optional[str]) -> None:
+		"""
+		Sets the target ID and updates log stats.
+
+		Args:
+			value (Optional[str]): The new target ID.
+		"""
+		
+		self._cdp_log_stats.target_id = value
+		self.target_data.target_id = value
+	
+	@property
+	def target_type_log_accepted(self) -> bool:
+		"""
+		Checks if logging is accepted for this target type.
+
+		Returns:
+			bool: True if logging is allowed, False otherwise.
+		"""
+		
+		return self._cdp_target_type_log_accepted
+	
+	@property
+	def title(self) -> Optional[str]:
+		"""
+		Gets the title of the target.
+
+		Returns:
+			Optional[str]: The title.
+		"""
+		
+		return self.target_data.title
+	
+	@title.setter
+	def title(self, value: Optional[str]) -> None:
+		"""
+		Sets the title of the target and updates log stats.
+
+		Args:
+			value (Optional[str]): The new title.
+		"""
+		
+		self._cdp_log_stats.title = value
+		self.target_data.title = value
+	
+	@property
+	def url(self) -> Optional[str]:
+		"""
+		Gets the URL of the target.
+
+		Returns:
+			Optional[str]: The URL.
+		"""
+		
+		return self.target_data.url
+	
+	@url.setter
+	def url(self, value: Optional[str]) -> None:
+		"""
+		Sets the URL of the target and updates log stats.
+
+		Args:
+			value (Optional[str]): The new URL.
+		"""
+		
+		self._cdp_log_stats.url = value
+		self.target_data.url = value

osn_selenium/dev_tools/target/detach.py

@@ -0,0 +1,54 @@
+import trio
+from osn_selenium.exceptions.devtools import CDPEndExceptions
+from osn_selenium.dev_tools.target.logging import LoggingMixin
+
+
+__all__ = ["DetachMixin"]
+
+
+class DetachMixin(LoggingMixin):
+	"""
+	Mixin for monitoring target detach, crash, or destruction events.
+	"""
+	
+	async def stop(self):
+		"""
+		Signals the target to begin its shutdown process.
+
+		Sets the `about_to_stop_event` which allows the main loop to exit.
+		"""
+		
+		self.about_to_stop_event.set()
+	
+	async def _run_detach_checking(self):
+		"""
+		Continuously listens for CDP events indicating the target is no longer available.
+
+		Monitors `TargetCrashed`, `TargetDestroyed`, and `DetachedFromTarget` events.
+		If the target associated with this instance is affected, it triggers the stop sequence.
+		"""
+		
+		TargetCrashed = self.devtools_package.get("target.TargetCrashed")
+		TargetDestroyed = self.devtools_package.get("target.TargetDestroyed")
+		DetachedFromTarget = self.devtools_package.get("target.DetachedFromTarget")
+		
+		self._detached_receive_channel: trio.MemoryReceiveChannel = self.cdp_session.listen(TargetCrashed, TargetDestroyed, DetachedFromTarget, buffer_size=10)
+		
+		should_stop = False
+		break_ = False
+		
+		while not should_stop and not break_:
+			try:
+				event = await self._detached_receive_channel.receive()
+		
+				if isinstance(event, (TargetCrashed, TargetDestroyed, DetachedFromTarget,)):
+					if event.target_id == self.target_id:
+						should_stop = True
+			except* CDPEndExceptions:
+				break_ = True
+			except* BaseException as error:
+				await self.log_cdp_error(error=error)
+				break_ = True
+		
+		if should_stop:
+			await self.stop()

osn_selenium/dev_tools/target/discovery.py

@@ -0,0 +1,112 @@
+import trio
+from typing import Tuple
+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
+from osn_selenium.dev_tools._validators import (
+	validate_target_event
+)
+
+
+__all__ = ["DiscoveryMixin"]
+
+
+class DiscoveryMixin(LoggingMixin):
+	"""
+	Mixin for discovering and attaching to new DevTools targets.
+	"""
+	
+	async def _run_new_targets_listener(self, new_targets_listener_ready_event: trio.Event):
+		"""
+		Listens for `TargetCreated` and `TargetInfoChanged` events to manage new targets.
+
+		Attaches to valid new targets and adds them to the management system.
+
+		Args:
+			new_targets_listener_ready_event (trio.Event): Event to signal that the listener is successfully started.
+
+		Raises:
+			CDPEndExceptions: If connection issues occur during initialization.
+			BaseException: If other errors occur during initialization.
+		"""
+		
+		await self.log_cdp_step(message="New Targets listener starting.")
+		
+		try:
+			self._new_target_receive_channel: Tuple[trio.MemoryReceiveChannel, trio.Event] = (
+					self.cdp_session.listen(
+							self.devtools_package.get("target.TargetCreated"),
+							# self.devtools_package.get("target.AttachedToTarget"),
+							self.devtools_package.get("target.TargetInfoChanged"),
+							buffer_size=self._new_targets_buffer_size
+					),
+					trio.Event()
+			)
+			new_targets_listener_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="New Targets listener started.")
+		
+		keep_alive = True
+		while keep_alive:
+			try:
+				event = await self._new_target_receive_channel[0].receive()
+		
+				if validate_target_event(event=event, filter_=self._new_targets_events_filters):
+					await execute_cdp_command(
+							self=self,
+							error_mode="log",
+							function=self.devtools_package.get("target.attach_to_target"),
+							target_id=event.target_info.target_id,
+							flatten=True
+					)
+		
+					self._nursery_object.start_soon(self._add_target_func, event)
+			except* CDPEndExceptions:
+				keep_alive = False
+			except* BaseException as error:
+				await self.log_cdp_error(error=error)
+				keep_alive = False
+		
+		self._new_target_receive_channel[1].set()
+	
+	async def _setup_new_targets_attaching(self):
+		"""
+		Configures the target to discover and auto-attach to new targets.
+
+		Executes CDP commands to set discovery mode and auto-attach behavior
+		based on the configured filters.
+
+		Raises:
+			CDPEndExceptions: If the connection closes during setup.
+			BaseException: If other errors occur.
+		"""
+		
+		try:
+			target_filter = self.devtools_package.get("target.TargetFilter")(self._new_targets_filter_list) if self._new_targets_filter_list is not None else None
+		
+			await execute_cdp_command(
+					self=self,
+					error_mode="log",
+					function=self.devtools_package.get("target.set_discover_targets"),
+					discover=True,
+					filter_=target_filter,
+			)
+			await execute_cdp_command(
+					self=self,
+					error_mode="log",
+					function=self.devtools_package.get("target.set_auto_attach"),
+					auto_attach=True,
+					wait_for_debugger_on_start=True,
+					flatten=True,
+					filter_=target_filter,
+			)
+		except CDPEndExceptions as error:
+			raise error
+		except BaseException as error:
+			await self.log_cdp_error(error=error)
+			raise error

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