arthexis 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

ocpp/evcs_discovery.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from ipaddress import IPv4Address
+from typing import Iterable, Sequence
+
+DEFAULT_TOP_PORTS = 200
+DEFAULT_CONSOLE_PORT = 8900
+PORT_PREFERENCES: Sequence[int] = (
+    DEFAULT_CONSOLE_PORT,
+    8443,
+    9443,
+    443,
+    8080,
+    8800,
+    8000,
+    8001,
+    8880,
+    80,
+)
+HTTPS_PORTS = {443, 8443, 9443}
+
+
+@dataclass(frozen=True)
+class ConsoleEndpoint:
+    host: str
+    port: int
+    secure: bool = False
+
+    @property
+    def url(self) -> str:
+        return build_console_url(self.host, self.port, self.secure)
+
+
+def scan_open_ports(
+    host: str,
+    *,
+    nmap_path: str = "nmap",
+    full: bool = False,
+    top_ports: int = DEFAULT_TOP_PORTS,
+) -> list[int]:
+    """Return the list of open TCP ports discovered with nmap.
+
+    The function mirrors the behaviour of the ``evcs_discover`` shell script.
+    It uses nmap's grepable output so the caller can avoid touching the
+    filesystem and parse the results quickly.
+    """
+
+    port_args: list[str]
+    if full:
+        port_args = ["-p-"]
+    else:
+        if top_ports <= 0:
+            raise ValueError("top_ports must be greater than zero")
+        port_args = ["--top-ports", str(top_ports)]
+
+    args = [
+        nmap_path,
+        "-sS",
+        "-Pn",
+        "-n",
+        "-T4",
+        "--open",
+        *port_args,
+        host,
+        "-oG",
+        "-",
+    ]
+
+    try:
+        proc = subprocess.run(
+            args,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.SubprocessError:
+        return []
+
+    if proc.returncode != 0:
+        return []
+
+    return _parse_nmap_open_ports(proc.stdout)
+
+
+def _parse_nmap_open_ports(output: str) -> list[int]:
+    ports: list[int] = []
+    for line in output.splitlines():
+        if "Ports:" not in line:
+            continue
+        try:
+            _, ports_section = line.split("Ports:", 1)
+        except ValueError:
+            continue
+        for entry in ports_section.split(","):
+            entry = entry.strip()
+            if not entry:
+                continue
+            parts = entry.split("/")
+            if len(parts) < 2:
+                continue
+            state = parts[1].strip().lower()
+            if state != "open":
+                continue
+            try:
+                port = int(parts[0])
+            except ValueError:
+                continue
+            if port not in ports:
+                ports.append(port)
+    return ports
+
+
+def prioritise_ports(ports: Iterable[int]) -> list[int]:
+    """Order ports so the most likely console endpoints are tried first."""
+
+    unique = []
+    seen = set()
+    available = list(dict.fromkeys(ports))
+    for preferred in PORT_PREFERENCES:
+        if preferred in available and preferred not in seen:
+            unique.append(preferred)
+            seen.add(preferred)
+    for port in available:
+        if port not in seen:
+            unique.append(port)
+            seen.add(port)
+    return unique
+
+
+def select_console_port(ports: Sequence[int]) -> ConsoleEndpoint | None:
+    """Pick the best console port from a list of open ports."""
+
+    if not ports:
+        return None
+    ordered = prioritise_ports(ports)
+    if not ordered:
+        return None
+    port = ordered[0]
+    secure = port in HTTPS_PORTS
+    return ConsoleEndpoint(host="", port=port, secure=secure)
+
+
+def build_console_url(host: str, port: int, secure: bool) -> str:
+    scheme = "https" if secure else "http"
+    host_part = host
+    if ":" in host and not host.startswith("["):
+        host_part = f"[{host}]"
+    return f"{scheme}://{host_part}:{port}"
+
+
+def normalise_host(host: str | IPv4Address) -> str:
+    if isinstance(host, IPv4Address):
+        return str(host)
+    return str(host)

ocpp/models.py

@@ -1,9 +1,12 @@
+import re
 import socket
 from decimal import Decimal, InvalidOperation
 
 from django.conf import settings
 from django.contrib.sites.models import Site
 from django.db import models
+from django.db.models import Q
+from django.core.exceptions import ValidationError
 from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
 
@@ -17,7 +20,9 @@ from core.models import (
     ElectricVehicle as CoreElectricVehicle,
     Brand as CoreBrand,
     EVModel as CoreEVModel,
+    SecurityGroup,
 )
+from .reference_utils import url_targets_local_loopback
 
 
 class Location(Entity):
@@ -42,6 +47,19 @@ class Location(Entity):
 class Charger(Entity):
     """Known charge point."""
 
+    _PLACEHOLDER_SERIAL_RE = re.compile(r"^<[^>]+>$")
+
+    OPERATIVE_STATUSES = {
+        "Available",
+        "Preparing",
+        "Charging",
+        "SuspendedEV",
+        "SuspendedEVSE",
+        "Finishing",
+        "Reserved",
+    }
+    INOPERATIVE_STATUSES = {"Unavailable", "Faulted"}
+
     charger_id = models.CharField(
         _("Serial Number"),
         max_length=100,
@@ -60,7 +78,7 @@ class Charger(Entity):
         help_text="Optional connector identifier for multi-connector chargers.",
     )
     public_display = models.BooleanField(
-        _("Show on Public Dashboard"),
+        _("Public"),
         default=True,
         help_text="Display this charger on the public status dashboard.",
     )
@@ -70,21 +88,21 @@ class Charger(Entity):
         help_text="Require a valid RFID before starting a charging session.",
     )
     firmware_status = models.CharField(
-        _("Firmware Status"),
+        _("Status"),
         max_length=32,
         blank=True,
         default="",
         help_text="Latest firmware status reported by the charger.",
     )
     firmware_status_info = models.CharField(
-        _("Firmware Status Details"),
+        _("Status Details"),
         max_length=255,
         blank=True,
         default="",
         help_text="Additional information supplied with the firmware status.",
     )
     firmware_timestamp = models.DateTimeField(
-        _("Firmware Status Timestamp"),
+        _("Status Timestamp"),
         null=True,
         blank=True,
         help_text="When the charger reported the current firmware status.",
@@ -95,6 +113,58 @@ class Charger(Entity):
     last_error_code = models.CharField(max_length=64, blank=True)
     last_status_vendor_info = models.JSONField(null=True, blank=True)
     last_status_timestamp = models.DateTimeField(null=True, blank=True)
+    availability_state = models.CharField(
+        _("State"),
+        max_length=16,
+        blank=True,
+        default="",
+        help_text=(
+            "Current availability reported by the charger "
+            "(Operative/Inoperative)."
+        ),
+    )
+    availability_state_updated_at = models.DateTimeField(
+        _("State Updated At"),
+        null=True,
+        blank=True,
+        help_text="When the current availability state became effective.",
+    )
+    availability_requested_state = models.CharField(
+        _("Requested State"),
+        max_length=16,
+        blank=True,
+        default="",
+        help_text="Last availability state requested via ChangeAvailability.",
+    )
+    availability_requested_at = models.DateTimeField(
+        _("Requested At"),
+        null=True,
+        blank=True,
+        help_text="When the last ChangeAvailability request was sent.",
+    )
+    availability_request_status = models.CharField(
+        _("Request Status"),
+        max_length=16,
+        blank=True,
+        default="",
+        help_text=(
+            "Latest response status for ChangeAvailability "
+            "(Accepted/Rejected/Scheduled)."
+        ),
+    )
+    availability_request_status_at = models.DateTimeField(
+        _("Request Status At"),
+        null=True,
+        blank=True,
+        help_text="When the last ChangeAvailability response was received.",
+    )
+    availability_request_details = models.CharField(
+        _("Request Details"),
+        max_length=255,
+        blank=True,
+        default="",
+        help_text="Additional details from the last ChangeAvailability response.",
+    )
     temperature = models.DecimalField(
         max_digits=5, decimal_places=1, null=True, blank=True
     )
@@ -134,10 +204,60 @@ class Charger(Entity):
         blank=True,
         related_name="managed_chargers",
     )
+    owner_users = models.ManyToManyField(
+        settings.AUTH_USER_MODEL,
+        blank=True,
+        related_name="owned_chargers",
+        help_text=_("Users who can view this charge point."),
+    )
+    owner_groups = models.ManyToManyField(
+        SecurityGroup,
+        blank=True,
+        related_name="owned_chargers",
+        help_text=_("Security groups that can view this charge point."),
+    )
 
     def __str__(self) -> str:  # pragma: no cover - simple representation
         return self.charger_id
 
+    @classmethod
+    def visible_for_user(cls, user):
+        """Return chargers marked for display that the user may view."""
+
+        qs = cls.objects.filter(public_display=True)
+        if getattr(user, "is_superuser", False):
+            return qs
+        if not getattr(user, "is_authenticated", False):
+            return qs.filter(
+                owner_users__isnull=True, owner_groups__isnull=True
+            ).distinct()
+        group_ids = list(user.groups.values_list("pk", flat=True))
+        visibility = Q(owner_users__isnull=True, owner_groups__isnull=True) | Q(
+            owner_users=user
+        )
+        if group_ids:
+            visibility |= Q(owner_groups__pk__in=group_ids)
+        return qs.filter(visibility).distinct()
+
+    def has_owner_scope(self) -> bool:
+        """Return ``True`` when owner restrictions are defined."""
+
+        return self.owner_users.exists() or self.owner_groups.exists()
+
+    def is_visible_to(self, user) -> bool:
+        """Return ``True`` when ``user`` may view this charger."""
+
+        if getattr(user, "is_superuser", False):
+            return True
+        if not self.has_owner_scope():
+            return True
+        if not getattr(user, "is_authenticated", False):
+            return False
+        if self.owner_users.filter(pk=user.pk).exists():
+            return True
+        user_group_ids = user.groups.values_list("pk", flat=True)
+        return self.owner_groups.filter(pk__in=user_group_ids).exists()
+
     class Meta:
         verbose_name = _("Charge Point")
         verbose_name_plural = _("Charge Points")
@@ -154,6 +274,39 @@ class Charger(Entity):
             ),
         ]
 
+
+    @classmethod
+    def normalize_serial(cls, value: str | None) -> str:
+        """Return ``value`` trimmed for consistent comparisons."""
+
+        if value is None:
+            return ""
+        return str(value).strip()
+
+    @classmethod
+    def is_placeholder_serial(cls, value: str | None) -> bool:
+        """Return ``True`` when ``value`` matches the placeholder pattern."""
+
+        normalized = cls.normalize_serial(value)
+        return bool(normalized) and bool(cls._PLACEHOLDER_SERIAL_RE.match(normalized))
+
+    @classmethod
+    def validate_serial(cls, value: str | None) -> str:
+        """Return a normalized serial number or raise ``ValidationError``."""
+
+        normalized = cls.normalize_serial(value)
+        if not normalized:
+            raise ValidationError({"charger_id": _("Serial Number cannot be blank.")})
+        if cls.is_placeholder_serial(normalized):
+            raise ValidationError(
+                {
+                    "charger_id": _(
+                        "Serial Number placeholder values such as <charger_id> are not allowed."
+                    )
+                }
+            )
+        return normalized
+
     AGGREGATE_CONNECTOR_SLUG = "all"
 
     def identity_tuple(self) -> tuple[str, int | None]:
@@ -183,6 +336,19 @@ class Charger(Entity):
         except (TypeError, ValueError) as exc:
             raise ValueError(f"Invalid connector slug: {slug}") from exc
 
+    @classmethod
+    def availability_state_from_status(cls, status: str) -> str | None:
+        """Return the availability state implied by a status notification."""
+
+        normalized = (status or "").strip()
+        if not normalized:
+            return None
+        if normalized in cls.INOPERATIVE_STATUSES:
+            return "Inoperative"
+        if normalized in cls.OPERATIVE_STATUSES:
+            return "Operative"
+        return None
+
     @property
     def connector_slug(self) -> str:
         """Return the slug representing this charger's connector."""
@@ -251,7 +417,12 @@ class Charger(Entity):
         scheme = getattr(settings, "DEFAULT_HTTP_PROTOCOL", "http")
         return f"{scheme}://{domain}{self.get_absolute_url()}"
 
+    def clean(self):
+        super().clean()
+        self.charger_id = type(self).validate_serial(self.charger_id)
+
     def save(self, *args, **kwargs):
+        self.charger_id = type(self).validate_serial(self.charger_id)
         update_fields = kwargs.get("update_fields")
         update_list = list(update_fields) if update_fields is not None else None
         if not self.manager_node_id:
@@ -279,6 +450,8 @@ class Charger(Entity):
             kwargs["update_fields"] = update_list
         super().save(*args, **kwargs)
         ref_value = self._full_url()
+        if url_targets_local_loopback(ref_value):
+            return
         if not self.reference or self.reference.value != ref_value:
             self.reference = Reference.objects.create(
                 value=ref_value, alt_text=self.charger_id
@@ -612,6 +785,18 @@ class Simulator(Entity):
         default=False,
         help_text=_("Send a DoorOpen error StatusNotification when enabled."),
     )
+    configuration_keys = models.JSONField(
+        default=list,
+        blank=True,
+        help_text=_(
+            "List of configurationKey entries to return for GetConfiguration calls."
+        ),
+    )
+    configuration_unknown_keys = models.JSONField(
+        default=list,
+        blank=True,
+        help_text=_("Keys to include in the GetConfiguration unknownKey response."),
+    )
 
     def __str__(self) -> str:  # pragma: no cover - simple representation
         return self.name
@@ -638,6 +823,8 @@ class Simulator(Entity):
             repeat=self.repeat,
             username=self.username or None,
             password=self.password or None,
+            configuration_keys=self.configuration_keys or [],
+            configuration_unknown_keys=self.configuration_unknown_keys or [],
         )
 
     @property
@@ -650,6 +837,52 @@ class Simulator(Entity):
         return f"ws://{self.host}/{path}"
 
 
+class DataTransferMessage(models.Model):
+    """Persisted record of OCPP DataTransfer exchanges."""
+
+    DIRECTION_CP_TO_CSMS = "cp_to_csms"
+    DIRECTION_CSMS_TO_CP = "csms_to_cp"
+    DIRECTION_CHOICES = (
+        (DIRECTION_CP_TO_CSMS, _("Charge Point → CSMS")),
+        (DIRECTION_CSMS_TO_CP, _("CSMS → Charge Point")),
+    )
+
+    charger = models.ForeignKey(
+        "Charger",
+        on_delete=models.CASCADE,
+        related_name="data_transfer_messages",
+    )
+    connector_id = models.PositiveIntegerField(null=True, blank=True)
+    direction = models.CharField(max_length=16, choices=DIRECTION_CHOICES)
+    ocpp_message_id = models.CharField(max_length=64)
+    vendor_id = models.CharField(max_length=255, blank=True)
+    message_id = models.CharField(max_length=255, blank=True)
+    payload = models.JSONField(default=dict, blank=True)
+    status = models.CharField(max_length=64, blank=True)
+    response_data = models.JSONField(null=True, blank=True)
+    error_code = models.CharField(max_length=64, blank=True)
+    error_description = models.TextField(blank=True)
+    error_details = models.JSONField(null=True, blank=True)
+    responded_at = models.DateTimeField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(
+                fields=["ocpp_message_id"],
+                name="ocpp_datatr_ocpp_me_70d17f_idx",
+            ),
+            models.Index(
+                fields=["vendor_id"], name="ocpp_datatr_vendor__59e1c7_idx"
+            ),
+        ]
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        return f"{self.get_direction_display()} {self.vendor_id or 'DataTransfer'}"
+
+
 class RFID(CoreRFID):
     class Meta:
         proxy = True

ocpp/reference_utils.py

@@ -0,0 +1,42 @@
+"""Helpers related to console Reference creation."""
+
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlparse
+
+
+def _normalize_host(host: str | None) -> str:
+    """Return a trimmed host string without surrounding brackets."""
+
+    if not host:
+        return ""
+    host = host.strip()
+    if host.startswith("[") and host.endswith("]"):
+        return host[1:-1]
+    return host
+
+
+def host_is_local_loopback(host: str | None) -> bool:
+    """Return ``True`` when the host string points to 127.0.0.1."""
+
+    normalized = _normalize_host(host)
+    if not normalized:
+        return False
+    try:
+        return ipaddress.ip_address(normalized) == ipaddress.ip_address("127.0.0.1")
+    except ValueError:
+        return False
+
+
+def url_targets_local_loopback(url: str | None) -> bool:
+    """Return ``True`` when the parsed URL host equals 127.0.0.1."""
+
+    if not url:
+        return False
+    parsed = urlparse(url)
+    return host_is_local_loopback(parsed.hostname)
+
+
+__all__ = ["host_is_local_loopback", "url_targets_local_loopback"]
+