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

osn_selenium/dev_tools/domains_default/fetch.py

@@ -1,24 +1,31 @@
 import trio
-from osn_selenium.dev_tools.utils import (
-	TargetData,
-	log_exception
-)
+from datetime import datetime
+from osn_selenium._base_models import DictModel
+from osn_selenium.dev_tools._exception_helpers import log_exception
 from typing import (
 	Any,
+	Dict,
+	List,
 	Literal,
-	Sequence,
 	TYPE_CHECKING,
-	TypedDict,
 	Union
 )
 
 
+__all__ = [
+	"HeaderInstance",
+	"auth_required_choose_func",
+	"headers_handler",
+	"on_error_func",
+	"request_paused_choose_func"
+]
+
 if TYPE_CHECKING:
-	from osn_selenium.dev_tools.manager import DevToolsTarget
+	from osn_selenium.dev_tools.target import DevToolsTarget
 	from osn_selenium.dev_tools.domains.fetch import request_paused_actions_literal, auth_required_actions_literal
 
 
-def request_paused_choose_func(self: "DevToolsTarget", event: Any) -> Sequence["request_paused_actions_literal"]:
+def request_paused_choose_func(self: "DevToolsTarget", event: Any) -> List["request_paused_actions_literal"]:
 	"""
 	Default function to choose actions for a 'fetch.RequestPaused' event.
 
@@ -27,11 +34,11 @@ def request_paused_choose_func(self: "DevToolsTarget", event: Any) -> Sequence["
 	deciding which actions to take based on the event details.
 
 	Args:
-		self (DevToolsTarget): The DevToolsTarget instance.
+		self ("DevToolsTarget"): The DevToolsTarget instance.
 		event (Any): The 'RequestPaused' event object.
 
 	Returns:
-		Sequence[request_paused_actions_literal]: A sequence of action names to be executed.
+		List[request_paused_actions_literal]: A list of action names to be executed.
 	"""
 	
 	return ["continue_request"]
@@ -45,15 +52,22 @@ def on_error_func(self: "DevToolsTarget", event: Any, error: BaseException):
 	Users can provide their own function to implement custom error handling logic.
 
 	Args:
-		self (DevToolsTarget): The DevToolsTarget instance.
+		self ("DevToolsTarget"): The DevToolsTarget instance.
 		event (Any): The event object that was being processed when the error occurred.
 		error (BaseException): The exception that was raised.
 	"""
 	
-	log_exception(error)
+	log_exception(
+			exception=error,
+			extra_data={
+				"datetime": datetime.now(),
+				"target object data": self.target_data.model_dump(),
+				"event": event
+			}
+	)
 
 
-class HeaderInstance(TypedDict):
+class HeaderInstance(DictModel):
 	"""
 	Type definition for header modification instructions used by the `headers_handler`.
 
@@ -76,9 +90,9 @@ class HeaderInstance(TypedDict):
 async def headers_handler(
 		self: "DevToolsTarget",
 		ready_event: trio.Event,
-		headers_instances: dict[str, HeaderInstance],
+		headers_instances: Dict[str, HeaderInstance],
 		event: Any,
-		kwargs: dict[str, Any]
+		kwargs: Dict[str, Any]
 ):
 	"""
 	A parameter handler function to modify request headers.
@@ -89,24 +103,24 @@ async def headers_handler(
 	like `fetch.continueRequest`.
 
 	Args:
-		self (DevToolsTarget): The DevToolsTarget instance.
+		self ("DevToolsTarget"): The DevToolsTarget instance.
 		ready_event (trio.Event): A Trio event to signal when the handler has completed its work.
-		headers_instances (dict[str, HeaderInstance]): A dictionary where keys are header names
+		headers_instances (Dict[str, HeaderInstance]): A dictionary where keys are header names
 			and values are `HeaderInstance` objects defining the modification.
 		event (Any): The CDP event object (e.g., `RequestPaused`) containing the original request headers.
-		kwargs (dict[str, Any]): The dictionary of keyword arguments to which the modified headers will be added.
+		kwargs (Dict[str, Any]): The dictionary of keyword arguments to which the modified headers will be added.
 
 	Raises:
 		Exception: If an error occurs during header modification.
 	"""
 	
 	try:
-		header_entry_class = await self.get_devtools_object("fetch.HeaderEntry")
+		header_entry_class = self.devtools_package.get("fetch.HeaderEntry")
 		headers = {name: value for name, value in event.request.headers.items()}
 	
 		for name, instance in headers_instances.items():
-			value = instance["value"]
-			instruction = instance["instruction"]
+			value = instance.value
+			instruction = instance.instruction
 	
 			if instruction == "set":
 				headers[name] = value
@@ -119,8 +133,7 @@ async def headers_handler(
 				continue
 	
 			if instruction == "remove":
-				if name in headers:
-					headers.pop(name)
+				headers.pop(name, None)
 	
 				continue
 	
@@ -131,11 +144,11 @@ async def headers_handler(
 	
 		ready_event.set()
 	except BaseException as error:
-		await self.log_error(error=error)
+		await self.log_cdp_error(error=error)
 		raise error
 
 
-def auth_required_choose_func(self: "DevToolsTarget", target_data: TargetData, event: Any) -> Sequence["auth_required_actions_literal"]:
+def auth_required_choose_func(self: "DevToolsTarget", event: Any) -> List["auth_required_actions_literal"]:
 	"""
 	Default function to choose actions for a 'fetch.AuthRequired' event.
 
@@ -144,12 +157,11 @@ def auth_required_choose_func(self: "DevToolsTarget", target_data: TargetData, e
 	deciding which actions to take based on the event details.
 
 	Args:
-		self (DevToolsTarget): The DevToolsTarget instance.
-		target_data (TargetData): Data about the current browser target.
+		self ("DevToolsTarget"): The DevToolsTarget instance.
 		event (Any): The 'AuthRequired' event object.
 
 	Returns:
-		Sequence[auth_required_actions_literal]: A sequence of action names to be executed.
+		List[auth_required_actions_literal]: A list of action names to be executed.
 	"""
 	
 	return ["continue_with_auth"]

osn_selenium/dev_tools/filters.py

@@ -0,0 +1,40 @@
+from pydantic import Field
+from typing import List, Optional
+from osn_selenium._base_models import DictModel
+
+
+__all__ = ["TargetFilter", "TargetsFilters"]
+
+
+class TargetsFilters(DictModel):
+	"""
+	Configuration model for filtering target types (inclusion/exclusion).
+
+	Attributes:
+		excluded (List[str]): List of target types to exclude.
+		included (List[str]): List of target types to include.
+		entire (bool): Default behavior if a type is not explicitly listed.
+	"""
+	
+	excluded: List[str] = Field(default_factory=list)
+	included: List[str] = Field(default_factory=list)
+	
+	entire: bool = False
+
+
+class TargetFilter(DictModel):
+	"""
+	Dataclass to define a filter for discovering new browser targets.
+
+	Used in `DevToolsSettings` to specify which types of targets (e.g., "page", "iframe")
+	should be automatically attached to or excluded.
+
+	Attributes:
+		type_ (Optional[str]): The type of target to filter by (e.g., "page", "iframe").
+			If None, this filter applies regardless of type. Aliased as 'type'.
+		exclude (Optional[bool]): If True, targets matching `type_` will be excluded.
+			If False or None, targets matching `type_` will be included.
+	"""
+	
+	type_: Optional[str] = Field(default=None, alias="type")
+	exclude: Optional[bool] = None

osn_selenium/dev_tools/logger/main.py

@@ -0,0 +1,214 @@
+import trio
+from typing import (
+	Optional,
+	TYPE_CHECKING,
+	Tuple
+)
+from osn_selenium.exceptions.devtools import TrioEndExceptions
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from osn_selenium.exceptions.configuration import ConfigurationError
+from osn_selenium.dev_tools.logger.models import (
+	CDPMainLogEntry,
+	FingerprintMainLogEntry
+)
+
+
+__all__ = ["MainLogger", "build_main_logger"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.settings import LoggerSettings
+
+
+class MainLogger:
+	"""
+	Manages the main log file, summarizing overall logging activity.
+
+	This logger is responsible for writing aggregated statistics about all active
+	logging channels and target types to a designated file.
+	"""
+	
+	def __init__(
+			self,
+			logger_settings: "LoggerSettings",
+			nursery_object: trio.Nursery,
+			cdp_receive_channel: Optional[trio.MemoryReceiveChannel[CDPMainLogEntry]],
+			fingerprint_receive_channel: Optional[trio.MemoryReceiveChannel[FingerprintMainLogEntry]]
+	):
+		"""
+		Initializes the MainLogger.
+
+		Args:
+			logger_settings ("LoggerSettings"): The settings for logging, including log directory.
+			nursery_object (trio.Nursery): The Trio nursery to spawn background tasks.
+			cdp_receive_channel (Optional[trio.MemoryReceiveChannel[CDPMainLogEntry]]):
+				The channel from which CDP main log entries are received.
+			fingerprint_receive_channel (Optional[trio.MemoryReceiveChannel[FingerprintMainLogEntry]]):
+				The channel from which fingerprint main log entries are received.
+
+		Raises:
+			ValueError: If settings require logging but `dir_path` is not set.
+		"""
+		
+		self._nursery_object = nursery_object
+		self._cdp_receive_channel = cdp_receive_channel
+		self._fingerprint_receive_channel = fingerprint_receive_channel
+		self._cdp_file_path = None
+		self._cdp_log_level_filter = None
+		self._cdp_target_type_filter = None
+		self._fingerprint_file_path = None
+		self._fingerprint_log_level_filter = None
+		self._fingerprint_target_type_filter = None
+		
+		if logger_settings.dir_path is None:
+			if logger_settings.cdp_settings:
+				raise ConfigurationError("Can't log CDP without LoggerSettings.dir_path!")
+			
+			if logger_settings.fingerprint_settings:
+				raise ConfigurationError("Can't log Fingerprint without LoggerSettings.dir_path!")
+		else:
+			logdir_path = logger_settings.dir_path.joinpath("__MAIN__")
+			logdir_path.mkdir(exist_ok=True)
+			
+			if logger_settings.cdp_settings:
+				self._cdp_file_path = logdir_path.joinpath(f"cdp_log.txt")
+			
+			if logger_settings.fingerprint_settings:
+				self._fingerprint_file_path = logdir_path.joinpath(f"fingerprint_log.txt")
+		
+		self._cdp_file_writing_stopped: Optional[trio.Event] = None
+		self._fingerprint_file_writing_stopped: Optional[trio.Event] = None
+		self._is_active = False
+	
+	async def close(self):
+		"""
+		Closes the main 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 main log entries to the file.
+
+		This method continuously receives `FingerprintMainLogEntry` objects and
+		updates the log file.
+		"""
+		
+		try:
+			async with await trio.open_file(self._fingerprint_file_path, "w+", encoding="utf-8") as file:
+				async for log_entry in self._fingerprint_receive_channel:
+					await file.seek(0)
+					await file.write(log_entry.model_dump_json(indent=4))
+					await file.truncate()
+					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 main log entries to the file.
+
+		This method continuously receives `CDPMainLogEntry` objects from its channel
+		and overwrites the configured file with their string representation.
+		It runs as a background task.
+		"""
+		
+		try:
+			async with await trio.open_file(self._cdp_file_path, "w+", encoding="utf-8") as file:
+				async for log_entry in self._cdp_receive_channel:
+					await file.seek(0)
+					await file.write(log_entry.model_dump_json(indent=4))
+					await file.truncate()
+					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 main logger, setting up its receive channel and file writing task.
+
+		Raises:
+			BaseException: If an error occurs during setup or if the logger fails to activate.
+		"""
+		
+		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_main_logger(nursery_object: trio.Nursery, logger_settings: "LoggerSettings") -> Tuple[
+	Optional[trio.MemorySendChannel[CDPMainLogEntry]],
+	Optional[trio.MemorySendChannel[FingerprintMainLogEntry]],
+	MainLogger
+]:
+	"""
+	Builds and initializes a `MainLogger` instance along with its send channels.
+
+	Args:
+		nursery_object (trio.Nursery): The Trio nursery to associate with the logger for background tasks.
+		logger_settings ("LoggerSettings"): The logger configuration settings.
+
+	Returns:
+		Tuple[Optional[trio.MemorySendChannel[CDPMainLogEntry]], Optional[trio.MemorySendChannel[FingerprintMainLogEntry]], MainLogger]:
+			A tuple containing the send channels for logs and the initialized `MainLogger` 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 = MainLogger(
+			logger_settings=logger_settings,
+			nursery_object=nursery_object,
+			cdp_receive_channel=cdp_recv,
+			fingerprint_receive_channel=fp_recv,
+	)
+	
+	return cdp_send, fp_send, target_logger

osn_selenium/dev_tools/logger/models.py

@@ -0,0 +1,232 @@
+from pydantic import Field
+from datetime import datetime
+from osn_selenium._base_models import DictModel
+from osn_selenium.dev_tools.models import TargetData
+from typing import (
+	Any,
+	Dict,
+	Optional,
+	Sequence
+)
+from osn_selenium.dev_tools._typehints import (
+	CDP_LOG_LEVELS_TYPEHINT,
+	FINGERPRINT_LOG_LEVELS_TYPEHINT
+)
+
+
+__all__ = [
+	"CDPLogLevelStats",
+	"CDPLoggerChannelStats",
+	"CDPMainLogEntry",
+	"CDPTargetLogEntry",
+	"CDPTargetTypeStats",
+	"FingerprintAPIStats",
+	"FingerprintLogLevelStats",
+	"FingerprintLoggerChannelStats",
+	"FingerprintMainLogEntry",
+	"FingerprintTargetLogEntry"
+]
+
+
+class FingerprintLogLevelStats(DictModel):
+	"""
+	Statistics for a specific fingerprint log level.
+
+	Attributes:
+		num_logs (int): Number of logs recorded.
+		last_log_time (datetime): Timestamp of the last log.
+	"""
+	
+	num_logs: int
+	last_log_time: datetime
+
+
+class FingerprintTargetLogEntry(DictModel):
+	"""
+	A single log entry for fingerprint detection events.
+
+	Attributes:
+		target_data (TargetData): Information about the target.
+		level (FingerprintLogLevelsType): The log level (e.g., "Detect").
+		api (str): The API involved in the fingerprinting.
+		used_method (str): The method called.
+		datetime (datetime): When the event occurred.
+		stacktrace (Optional[str]): Stack trace of the event.
+	"""
+	
+	target_data: TargetData
+	level: FINGERPRINT_LOG_LEVELS_TYPEHINT
+	api: str
+	used_method: str
+	datetime: datetime
+	stacktrace: Optional[str]
+
+
+class FingerprintLoggerChannelStats(DictModel):
+	"""
+	Statistics for a fingerprint logging channel.
+
+	Attributes:
+		target_id (str): ID of the target.
+		title (str): Title of the target.
+		url (str): URL of the target.
+		num_logs (int): Total logs for this channel.
+		last_log_time (datetime): Time of the last log.
+		log_level_stats (Dict[str, FingerprintLogLevelStats]): Stats per log level.
+	"""
+	
+	target_id: str
+	title: str
+	url: str
+	num_logs: int = 0
+	last_log_time: datetime = Field(default_factory=datetime.now)
+	log_level_stats: Dict[str, FingerprintLogLevelStats] = Field(default_factory=dict)
+	
+	async def add_log(self, log_entry: FingerprintTargetLogEntry):
+		"""
+		Updates the channel statistics based on a new log entry.
+
+		Args:
+			log_entry (FingerprintTargetLogEntry): The new log entry to incorporate into the statistics.
+		"""
+		
+		self.num_logs += 1
+		self.last_log_time = log_entry.datetime
+		
+		if log_entry.level not in self.log_level_stats:
+			self.log_level_stats[log_entry.level] = FingerprintLogLevelStats(num_logs=1, last_log_time=log_entry.datetime)
+		else:
+			self.log_level_stats[log_entry.level].num_logs += 1
+			self.log_level_stats[log_entry.level].last_log_time = log_entry.datetime
+
+
+class FingerprintAPIStats(DictModel):
+	"""
+	Statistics for a specific Fingerprint API.
+
+	Attributes:
+		num_logs (int): Number of targets accessing this API.
+		methods_stats (Dict[str, int]): Count of calls per method.
+	"""
+	
+	num_logs: int
+	methods_stats: Dict[str, int]
+
+
+class FingerprintMainLogEntry(DictModel):
+	"""
+	Summary log entry for all fingerprinting activity.
+
+	Attributes:
+		num_channels (int): Total active channels.
+		apis_stats (Dict[str, FingerprintAPIStats]): Stats per API.
+		num_logs (int): Total logs recorded.
+		log_level_stats (Dict[str, FingerprintLogLevelStats]): Stats per log level.
+		channels_stats (Sequence[FingerprintLoggerChannelStats]): Stats for each channel.
+	"""
+	
+	num_channels: int
+	apis_stats: Dict[str, FingerprintAPIStats]
+	num_logs: int
+	log_level_stats: Dict[str, FingerprintLogLevelStats]
+	channels_stats: Sequence[FingerprintLoggerChannelStats]
+
+
+class CDPLogLevelStats(DictModel):
+	"""
+	Dataclass to store statistics for a specific log level.
+
+	Attributes:
+		num_logs (int): The total number of logs recorded for this level.
+		last_log_time (datetime): The timestamp of the most recent log entry for this level.
+	"""
+	
+	num_logs: int
+	last_log_time: datetime
+
+
+class CDPTargetLogEntry(DictModel):
+	"""
+	Represents a single log entry with detailed information.
+
+	Attributes:
+		target_data (TargetData): Data about the target (browser tab/session) from which the log originated.
+		message (str): The main log message.
+		level (CDPLogLevelsType): The severity level of the log (e.g., "INFO", "ERROR").
+		datetime (datetime): The exact time when the log entry was created.
+		extra_data (Optional[Dict[str, Any]]): Optional additional data associated with the log.
+	"""
+	
+	target_data: TargetData
+	message: str
+	level: CDP_LOG_LEVELS_TYPEHINT
+	datetime: datetime
+	extra_data: Optional[Dict[str, Any]] = None
+
+
+class CDPLoggerChannelStats(DictModel):
+	"""
+	Dataclass to store statistics for a specific logging channel (per target).
+
+	Attributes:
+		target_id (str): The unique ID of the target associated with this channel.
+		title (str): The title of the target (e.g., page title).
+		url (str): The URL of the target.
+		num_logs (int): The total number of log entries for this channel.
+		last_log_time (datetime): The timestamp of the most recent log entry for this channel.
+		log_level_stats (Dict[str, CDPLogLevelStats]): A dictionary mapping log levels to their specific statistics.
+	"""
+	
+	target_id: str
+	title: str
+	url: str
+	num_logs: int = 0
+	last_log_time: datetime = Field(default_factory=datetime.now)
+	log_level_stats: Dict[str, CDPLogLevelStats] = Field(default_factory=dict)
+	
+	async def add_log(self, log_entry: CDPTargetLogEntry):
+		"""
+		Updates the channel statistics based on a new log entry.
+
+		Args:
+			log_entry (CDPTargetLogEntry): The new log entry to incorporate into the statistics.
+		"""
+		
+		self.num_logs += 1
+		self.last_log_time = log_entry.datetime
+		
+		if log_entry.level not in self.log_level_stats:
+			self.log_level_stats[log_entry.level] = CDPLogLevelStats(num_logs=1, last_log_time=log_entry.datetime)
+		else:
+			self.log_level_stats[log_entry.level].num_logs += 1
+			self.log_level_stats[log_entry.level].last_log_time = log_entry.datetime
+
+
+class CDPTargetTypeStats(DictModel):
+	"""
+	Dataclass to store statistics for a specific target type.
+
+	Attributes:
+		num_targets (int): The count of targets of this type.
+	"""
+	
+	num_targets: int
+
+
+class CDPMainLogEntry(DictModel):
+	"""
+	Represents a summary log entry for the entire logging system.
+
+	Attributes:
+		num_channels (int): The total number of active logging channels (targets).
+		targets_types_stats (Dict[str, CDPTargetTypeStats]): Statistics grouped by target type.
+		num_logs (int): The total number of log entries across all channels.
+		log_level_stats (Dict[str, CDPLogLevelStats]): Overall statistics for each log level.
+		channels_stats (Sequence[CDPLoggerChannelStats]): A List of statistics for each active logging channel.
+	"""
+	
+	num_channels: int
+	targets_types_stats: Dict[str, CDPTargetTypeStats]
+	num_logs: int
+	log_level_stats: Dict[str, CDPLogLevelStats]
+	channels_stats: Sequence[CDPLoggerChannelStats]