woninet 2.0.1__py3-none-any.whl

woninet/core/storage.py

@@ -0,0 +1,163 @@
+from woninet.core.models import Device, MetricRecord
+from woninet.database.tables import AlertStateTable, AlertEventTable
+from woninet.database.repositories.device_repository import DeviceRepository
+from woninet.database.repositories.metric_repository import MetricRepository
+from woninet.database.repositories.alert_state_repository import AlertStateRepository
+from woninet.database.repositories.alert_event_repository import AlertEventRepository
+
+
+class StorageEngine:
+    """
+    Provide a high-level API for storing, updating, and
+    retrieving data from the database.
+
+    Also manage database sessions and delegate persistence
+    operations to repository classes.
+
+    Attributes:
+        session_factory (SessionLocal): Factory responsible for
+            creating SQLAlchemy sessions.
+    """
+
+    def __init__(self, session_factory) -> None:
+        """
+        Initialize the storage engine.
+
+        Args:
+            session_factory (SessionLocal): Factory responsible for
+                creating SQLAlchemy sessions.
+        """
+        self.session_factory = session_factory
+
+    def store_device(self, device: Device) -> None:
+        """
+        Insert or update a collected device.
+
+        Args:
+            device (Device): Device instance to be persisted.
+        """
+        with self.session_factory() as session:
+            repo = DeviceRepository(session)
+            repo.upsert(device)
+            session.commit()
+
+    def list_device_history(self) -> list[Device]:
+        """
+        Return all stored devices in the database.
+
+        Returns:
+            list[Device]: list devices retrieved from the database.
+        """
+        with self.session_factory() as session:
+            repo = DeviceRepository(session)
+            return repo.fetch_devices()
+
+    def fetch_device_info(self, ip) -> Device | None:
+        """
+        Return a device from the database for the given IP address or
+        `None` if not found.
+        """
+        with self.session_factory() as session:
+            repo = DeviceRepository(session)
+            return repo.fetch_device(ip)
+
+    def count_devices_and_metrics(self) -> tuple[int, int]:
+        """
+        Return number of devices and metrics in the database.
+
+        Returns:
+            tuple[int,int]: Number of devices and metrics in the database.
+        """
+        with self.session_factory() as session:
+            device_repo = DeviceRepository(session)
+            metric_repo = MetricRepository(session)
+            return (
+                device_repo.count_devices(),
+                metric_repo.count_metrics(),
+            )
+
+    def store_metric(self, metric: MetricRecord) -> None:
+        """
+        Persist newly collected metric record.
+
+        Args:
+            metric (MetricRecord): A metric record captured during a scan cycle.
+        """
+        with self.session_factory() as session:
+            repo = MetricRepository(session)
+            repo.insert(metric)
+            session.commit()
+
+    def list_metric_history(self) -> list[MetricRecord]:
+        """
+        Return stored metric history.
+
+        Returns:
+            list[MetricRecord]: Metric records retrieved from the database.
+        """
+        with self.session_factory() as session:
+            repo = MetricRepository(session)
+            return repo.fetch_metrics()
+
+    def get_or_create_alert_state(
+        self, ip: str, metric: str, consecutive_checks: int
+    ) -> AlertStateTable:
+        """
+        Return the alert state for a given IP address and metric.
+
+        Returns:
+            AlertStateTable: The found alert state.
+        """
+        with self.session_factory() as session:
+            repo = AlertStateRepository(session=session)
+            return repo.fetch_or_create_alert_state(
+                ip=ip, metric=metric, consecutive_checks=consecutive_checks
+            )
+
+    def update_alert_state(self, state: AlertStateTable) -> None:
+        """
+        Update an alert state.
+
+        Args:
+            state (AlertStateTable): The updated instance of AlertStateTable class.
+        """
+        with self.session_factory() as session:
+            repo = AlertStateRepository(session=session)
+            repo.update(state=state)
+            session.commit()
+
+    def get_device_alert_state(self, ip: str) -> dict[str, str] | None:
+        """
+        Return alert state of a device for a given IP address.
+        """
+        with self.session_factory() as session:
+            repo = AlertStateRepository(session)
+            return repo.fetch_alert_state(ip=ip)
+
+    def store_alert_event(self, event: AlertEventTable) -> None:
+        """
+        Store the new alert event.
+
+        Args:
+            event (AlertEvent): Instance of the AlertEventTable class.
+        """
+        with self.session_factory() as session:
+            repo = AlertEventRepository(session=session)
+            repo.insert(event=event)
+            session.commit()
+
+    def get_recent_alert_events(self) -> list[AlertEventTable]:
+        """
+        Return recent alert events of all devices.
+        """
+        with self.session_factory() as session:
+            repo = AlertEventRepository(session)
+            return repo.fetch_recent_alert_events()
+
+    def get_recent_device_alert_events(self, ip: str) -> list[AlertEventTable]:
+        """
+        Return recent alert events of a device for a given IP address.
+        """
+        with self.session_factory() as session:
+            repo = AlertEventRepository(session=session)
+            return repo.fetch_recent_device_alert_events(ip=ip)

woninet/core/subnet_enumerator.py

@@ -0,0 +1,32 @@
+import logging
+from woninet.core.models import Device
+
+core_logger = logging.getLogger("core")
+
+
+class SubnetEnumerator:
+    """
+    Build a dictionary of candidate devices for a given IPv4 /24 subnet.
+    """
+
+    def enumerate(self, ip: str) -> dict[str, Device]:
+        """
+        Build a dictionary of candidate devices based on the /24 subnet
+        of the provided IPv4 address.
+
+        Args:
+            ip (str): IPv4 address used to derive the subnet.
+
+        Returns:
+            dict[str,Device]: Dictionary of candidate devices containing host
+                IP addresses and the related `Device` instances. Hosts range
+                from `.1` to `.254`.
+        """
+        ip_split = ip.split(".")
+        subnet = f"{ip_split[0]}.{ip_split[1]}.{ip_split[2]}"
+        core_logger.debug(f"Building a dictionaty of IP addresses base on {subnet}.x")
+        devices = {}
+        for i in range(1, 255):
+            ip = f"{subnet}.{i}"
+            devices[ip] = Device(ip)
+        return devices

woninet/database/__init__.py

@@ -0,0 +1,2 @@
+# woninet/database/__init__.py
+# (This file intentionally left blank)

woninet/database/base.py

@@ -0,0 +1,9 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """
+    Used as the base for new declarative mappings.
+    """
+
+    pass

woninet/database/engine.py

@@ -0,0 +1,44 @@
+from sqlalchemy import create_engine, Engine
+from sqlalchemy.orm import sessionmaker, Session
+from woninet.database.base import Base
+
+
+class DatabaseEngine:
+    """
+    Encapsulate database engine creation and initialization logic.
+
+    Attributes:
+        database_path (str): Path to the SQLite database file.
+    """
+
+    def __init__(self, database_path: str) -> None:
+        """
+        Create a SQLAlchemy engine and session factory for the given database.
+
+        Args:
+            database_path (str): Path to the SQLite database file.
+        """
+        self.engine = create_engine(
+            f"sqlite:///{database_path}", echo=False, future=True
+        )
+        self.SessionLocal = sessionmaker(bind=self.engine, autoflush=False)
+
+    def init_db(self) -> None:
+        """
+        Initialize the database and create missing tables.
+        """
+        import woninet.database.tables  # noqa: F401
+
+        Base.metadata.create_all(bind=self.engine)
+
+    def get_database_enigne(self) -> Engine:
+        """
+        Return the SQLAlchemy Engine instance.
+        """
+        return self.engine
+
+    def get_session_factory(self) -> sessionmaker[Session]:
+        """
+        Return the SQLAlchemy session factory used to create sessions.
+        """
+        return self.SessionLocal

woninet/database/repositories/__init__.py

@@ -0,0 +1,2 @@
+# woninet/database/repositories/__init__.py
+# (This file intentionally left blank)

woninet/database/repositories/alert_event_repository.py

@@ -0,0 +1,69 @@
+from sqlalchemy.orm import Session
+from woninet.database.tables import AlertEventTable
+
+
+class AlertEventRepository:
+    """
+    Repository for presisting Alert Event entries.
+
+    Encapsulate ORM operations on `AlertEventTable`.
+
+    Attributes:
+        session (Session): SQLAlchemy session used for
+            database operations
+    """
+
+    def __init__(self, session: Session) -> None:
+        """
+        Initialize the repository.
+
+        Args:
+            session (Session): SQLAlchemy session used for all database operations.
+        """
+        self.session = session
+
+    def insert(self, event: AlertEventTable) -> None:
+        """
+        Insert new alert event in the database.
+
+        Args:
+            event (AlertEvent): Instance of the AlertEventTable class.
+        """
+        self.session.add(event)
+
+    def fetch_recent_alert_events(self, limit: int = 10) -> list[AlertEventTable]:
+        """
+        Return the last 10 alert events of all devices.
+
+        Args:
+            limit (int): Apply a limit to search.
+
+        Returns: List of found events, or an empty list if found none
+        """
+        return (
+            self.session.query(AlertEventTable)
+            .order_by(AlertEventTable.id.desc())
+            .limit(limit)
+            .all()
+        )
+
+    def fetch_recent_device_alert_events(
+        self, ip: str, limit: int = 10
+    ) -> list[AlertEventTable]:
+        """
+        Returns the last 10 alert events of a device for a given IP address.
+
+        Args:
+            ip (str): IP address to search for.
+            limit (int): Apply a limit to search.
+
+        Returns:
+            list[AlertEventTable]: List of found event, or an empty list if found none.
+        """
+        return (
+            self.session.query(AlertEventTable)
+            .filter_by(device_ip=ip)
+            .order_by(AlertEventTable.id.desc())
+            .limit(limit)
+            .all()
+        )

woninet/database/repositories/alert_state_repository.py

@@ -0,0 +1,81 @@
+from sqlalchemy.orm import Session
+from woninet.database.tables import AlertStateTable
+
+
+class AlertStateRepository:
+    """
+    Repository for presisting and updating Alert State entries.
+
+    Encapsulate ORM operations on `AlertStateTable`.
+
+    Attributes:
+        session (Session): SQLAlchemy session used for
+            database operations
+    """
+
+    def __init__(self, session: Session) -> None:
+        """
+        Initialize the repository.
+
+        Args:
+            session (Session): SQLAlchemy session used for all database operations.
+        """
+        self.session = session
+
+    def fetch_or_create_alert_state(
+        self, ip: str, metric: str, consecutive_checks: int
+    ) -> AlertStateTable:
+        """
+        Return an alert state for a specfic IP address and metric; Create a new one
+        if it already doesn't exist.
+
+        Args:
+            ip (str): IP address of host.
+            metric (str): Name of the metric beaing monitored.
+            consecutive_checks (int): Number of consecutive evaluations required
+                before a state change.
+
+        Returns:
+            AlertStateTable: The found alert state for a given IP and metric,
+                or a new alert state for new entries.
+        """
+        state = (
+            self.session.query(AlertStateTable)
+            .filter_by(device_ip=ip, metric=metric)
+            .one_or_none()
+        )
+
+        if state is None:
+            state = AlertStateTable(device_ip=ip, metric=metric)
+            state.state = "ok"
+            state.consecutive_checks = consecutive_checks
+            self.session.add(state)
+
+        return state
+
+    def update(self, state: AlertStateTable) -> None:
+        """
+        Update an alert state.
+
+        Args:
+            state (AlertStateTable): The updated instance of AlertStateTable class.
+        """
+        self.session.add(state)
+
+    def fetch_alert_state(self, ip: str) -> dict[str, str] | None:
+        """
+        Return current alert state for a given IP address.
+
+        Args:
+            ip (str): IP address to search for.
+
+        Returns:
+            dict[str,str]|None: A Dictionary containing `metric` and `state`.
+        """
+        device_state = self.session.query(AlertStateTable).filter_by(device_ip=ip).all()
+        if device_state is None:
+            return None
+        result = {}
+        for state in device_state:
+            result[state.metric] = state.state
+        return result

woninet/database/repositories/device_repository.py

@@ -0,0 +1,105 @@
+from datetime import datetime
+from sqlalchemy.orm import Session
+from woninet.database.tables import DeviceTable
+from woninet.core.models import Device
+
+
+class DeviceRepository:
+    """
+    Repository for persisting and retrieving Device entities.
+
+    Eencapsulate ORM operations on `DeviceTable` and expose a
+    simple API in terms of the domain model `Device`.
+
+    Attributes:
+        session (Session): SQLAlchemy session used for
+            database operations
+    """
+
+    def __init__(self, session: Session) -> None:
+        """
+        Initialize the repository.
+
+        Args:
+            session (Session): SQLAlchemy session used for all database operations.
+        """
+        self.session: Session = session
+
+    def upsert(self, dev: Device) -> None:
+        """
+        Insert or update a device into the database.
+
+        If `dev.ip` is present, the existing record is looked up by IP
+        address, otherwise it is looked up by MAC address. If the record
+        is found, its IP and latency fields are updated. The `last_seen`
+        timestamp is set to `dev.last_seen` or the current time, and is only
+        updated when device is reachable (`dev.latency > 0`).
+
+        All changes are committed immediatly.
+
+        Args:
+            dev (Device): Domain `Device` instance.
+        """
+        existing = self.session.query(DeviceTable).filter(DeviceTable.ip == dev.ip).first()
+        if existing is None and dev.mac:
+            existing = self.session.query(DeviceTable).filter(DeviceTable.mac == dev.mac).first()
+        now = datetime.now()
+
+        if existing:
+            existing.ip = dev.ip
+            existing.latency = dev.latency
+            if dev.latency > 0:
+                existing.last_seen = dev.last_seen or now
+            existing.packet_loss = dev.packet_loss
+        else:
+            existing = DeviceTable(
+                ip=dev.ip,
+                mac=dev.mac,
+                latency=dev.latency,
+                packet_loss=dev.packet_loss,
+                last_seen=dev.last_seen or now,
+            )
+            self.session.add(existing)
+
+    def fetch_devices(self) -> list[Device]:
+        """
+        Return all existing devices from the database.
+
+        Returns:
+            list[Device]: A list of `Device` instances from `DeviceTable` in the database.
+        """
+        rows = self.session.query(DeviceTable).all()
+        result = []
+        for row in rows:
+            dev = Device(ip=row.ip)
+            dev.mac = row.mac
+            dev.latency = row.latency
+            dev.packet_loss = row.packet_loss
+            dev.last_seen = row.last_seen
+            result.append(dev)
+        return result
+
+    def fetch_device(self, ip: str) -> Device | None:
+        """
+        Return a device from the database for the given IP address or
+        `None` if not found.
+        """
+        row = self.session.query(DeviceTable).filter_by(ip=ip).one_or_none()
+        if row is not None:
+            device = Device(ip=row.ip)
+            device.mac = row.mac
+            device.latency = row.latency
+            device.last_seen = row.last_seen
+            device.packet_loss = row.packet_loss
+            return device
+        return None
+
+    def count_devices(self) -> int:
+        """
+        Return the number of existing devices in the database.
+
+        Returns:
+            int: Number of devices in the database.
+        """
+        total = self.session.query(DeviceTable).count()
+        return total

woninet/database/repositories/metric_repository.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+from sqlalchemy.orm import Session
+from woninet.database.tables import MetricTable
+from woninet.core.models import MetricRecord
+
+
+class MetricRepository:
+    """
+    Repository for persisting and retrieving MetricRevord entities.
+
+    Encapsulate OEM operations on `MetricTable` and expose a
+    simple API in terms of the domain model `MetricRecord`.
+
+    Attributes:
+        session (Session): SQLAlchemy session used for
+            database operations
+    """
+
+    def __init__(self, session: Session) -> None:
+        """
+        Initialize the repository.
+
+        Args:
+            session (Session): SQLAlchemy session used for all database operations.
+        """
+        self.session: Session = session
+
+    def insert(self, metric: MetricRecord) -> None:
+        """
+        Insert new metric in the database.
+
+        Args:
+            metric (MetricRecord): An object of domain `MetricRecord` instance.
+        """
+        self.session.add(
+            MetricTable(
+                device_ip=metric.device_ip,
+                metric=metric.metric,
+                value=metric.value,
+                timestamp=metric.timestamp or datetime.now(),
+            )
+        )
+
+    def fetch_metrics(self) -> list[MetricRecord]:
+        """
+        Return all metric records from database.
+
+        Returns:
+            list[MetricRecord]: A list of `MetricRecord` instances from `MetricTable` in the database.
+        """
+        rows = self.session.query(MetricTable).all()
+        result = []
+        for row in rows:
+            metric = MetricTable(
+                device_ip=row.device_ip, metric=row.metric, value=row.value
+            )
+            result.append(metric)
+        return result
+
+    def remove_db_metrics(self) -> None:
+        """
+        Remove all rows from the `MetricTable`.
+        """
+        self.session.query(MetricTable).delete()
+        self.session.commit()
+
+    def count_metrics(self) -> int:
+        """
+        Return the number of metrics in the database.
+
+        Returns:
+            int: Number of metrics in the database.
+        """
+        total = self.session.query(MetricTable).count()
+        return total

woninet/database/tables.py

@@ -0,0 +1,89 @@
+from sqlalchemy import Integer, String, DateTime, Float, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+from datetime import datetime
+from woninet.database.base import Base
+
+
+class DeviceTable(Base):
+    """
+    ORM model representing a discovered network device.
+
+    Each row stores the most recently observed state for a device,
+    including IP address, MAC address, latency, and timestamp
+    of the last time device was reachable.
+    """
+
+    __tablename__ = "devices"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    ip: Mapped[str] = mapped_column(String, unique=True, index=True)
+    mac: Mapped[str | None] = mapped_column(
+        String, unique=True, index=True, nullable=True
+    )
+    latency: Mapped[float] = mapped_column(Float)
+    packet_loss: Mapped[int] = mapped_column(Integer)
+    last_seen: Mapped[datetime] = mapped_column(
+        DateTime(timezone=False), default=lambda: datetime.now(), index=True
+    )
+
+
+class MetricTable(Base):
+    """
+    ORM model representing a metric record of a device model.
+
+    Each row stores the metric record of device, including IP address,
+    metric name, value and timestamp of the time the metric was recorded.
+    """
+
+    __tablename__ = "metrics"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_ip: Mapped[str] = mapped_column(String, index=True)
+    metric: Mapped[str] = mapped_column(String, index=True)
+    value: Mapped[float] = mapped_column(Float)
+    timestamp: Mapped[datetime] = mapped_column(
+        DateTime(timezone=False), default=lambda: datetime.now(), index=True
+    )
+
+
+class AlertStateTable(Base):
+    """
+    ORM model representing an alert state for a specific device.
+
+    Each row stores the alert state of a device, including device IP address,
+    metric name, last state, and last time alert triggered.
+    """
+
+    __tablename__ = "alert_state"
+    __table_args__ = (
+        UniqueConstraint("device_ip", "metric", name="uix_device_metric"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_ip: Mapped[str] = mapped_column(String, index=True)
+    metric: Mapped[str] = mapped_column(String, index=True)
+    state: Mapped[str] = mapped_column(String, default="ok", index=True)
+    consecutive_checks: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
+    triggered_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=False), default=lambda: datetime.now(), index=True
+    )
+
+
+class AlertEventTable(Base):
+    """
+    ORM model representing an alert event occured.
+
+    Each row stores the alert event of a device, including device IP address,
+    metric name, captured value of metric, event type, and timestamp.
+    """
+
+    __tablename__ = "alert_event"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_ip: Mapped[str] = mapped_column(String, index=True)
+    metric: Mapped[str] = mapped_column(String, index=True)
+    value: Mapped[float] = mapped_column(Float)
+    event_type: Mapped[str] = mapped_column(String, index=True)
+    timestamp: Mapped[datetime] = mapped_column(
+        DateTime(timezone=False), default=lambda: datetime.now(), index=True
+    )