bedger 0.0.9__py3-none-any.whl

bedger/edge/client.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import copy
+import json
+import socket
+import jsonpatch
+import logging
+from http.client import HTTPConnection
+from typing import Any
+
+from .config import Config
+from .entities.device_event import DeviceEvent
+from . import entities
+from .errors import (
+    ConnectionError,
+    SendError,
+    HTTPRequestError,
+    map_socket_error,
+)
+from .entities.device_twin import DeviceTwin, DeviceTwinPatch
+
+logger = logging.getLogger("bedger.edge.client")
+
+
+class UnixSocketHTTPConnection(HTTPConnection):
+    """HTTPConnection subclass that communicates via UNIX domain sockets."""
+
+    def __init__(self, unix_socket_path: str):
+        super().__init__("localhost")  # dummy host
+        self.unix_socket_path = unix_socket_path
+
+    def connect(self):
+        """Override to connect to a UNIX socket instead of TCP."""
+        try:
+            self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self.sock.connect(self.unix_socket_path)
+        except Exception as e:
+            raise map_socket_error(e, self.unix_socket_path)
+
+
+class Client:
+    """
+    Bedger Edge Client that communicates with the local agent's HTTP API
+    over a UNIX socket. Matches BedgerConnection interface.
+    """
+
+    def __init__(self, config: Config = Config()):
+        self._config = config
+        self._connection: UnixSocketHTTPConnection | None = None
+
+    def __enter__(self) -> Client:
+        self._connect()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self._disconnect()
+
+    def _connect(self) -> None:
+        socket_path = self._config.socket_path
+        logger.info(f"Connecting to Bedger Edge API at {socket_path}")
+        try:
+            self._connection = UnixSocketHTTPConnection(socket_path)
+        except Exception as e:
+            raise ConnectionError(socket_path, e)
+
+    def _disconnect(self) -> None:
+        if self._connection:
+            try:
+                self._connection.close()
+                logger.info("Connection closed")
+            except Exception as e:
+                logger.warning(f"Error closing connection: {e}")
+            finally:
+                self._connection = None
+
+    def is_healthy(self) -> bool:
+        """Ping the Bedger Edge API health endpoint."""
+        if not self._connection:
+            raise ConnectionError(self._config.socket_path)
+
+        try:
+            self._connection.request("GET", "/health")
+            response = self._connection.getresponse()
+            raw_data = response.read().decode("utf-8")
+
+            if response.status != 200:
+                return False
+
+            logger.debug(f"Health response: {raw_data}")
+            return True
+        except Exception as e:
+            return False
+
+    def send_event(self, event_type: str, severity: entities.Severity, payload: dict[str, Any]) -> None:
+        """Send a DeviceEvent to /device/events."""
+        if not self._connection:
+            raise ConnectionError(self._config.socket_path)
+
+        event = DeviceEvent(event_type=event_type, severity=severity, details=payload)
+        serialized = event.model_dump_json(by_alias=True).encode("utf-8")
+
+        try:
+            self._connection.request(
+                "POST",
+                "/device/events",
+                body=serialized,
+                headers={"Content-Type": "application/json"},
+            )
+
+            response = self._connection.getresponse()
+            response_data = response.read().decode("utf-8")
+
+            if response.status != 200:
+                raise HTTPRequestError(response.status, response_data)
+
+            logger.info(f"Event sent successfully: {response_data}")
+        except HTTPRequestError:
+            raise
+        except Exception as e:
+            raise SendError("Failed to send DeviceEvent", e)
+
+
+class DeviceTwinClient(Client):
+    """Manages device twin synchronization over the Bedger Edge API."""
+
+    def __init__(self, config: Config = Config()) -> None:
+        super().__init__(config)
+
+    def __enter__(self) -> DeviceTwinClient:
+        super().__enter__()
+        self._twin = self._get_twin()
+        return self
+
+    def get_twin(self) -> DeviceTwin:
+        return copy.deepcopy(self._twin)
+
+    def _get_twin(self) -> DeviceTwin:
+        """Fetch and parse the full DeviceTwin model from the Bedger Edge API."""
+        if not self._connection:
+            raise ConnectionError(self._config.socket_path)
+
+        try:
+            self._connection.request("GET", "/device/twin")
+            response = self._connection.getresponse()
+            raw_data = response.read().decode("utf-8")
+
+            if response.status != 200:
+                raise HTTPRequestError(response.status, raw_data)
+
+            logger.debug(f"Fetched raw device twin: {raw_data}")
+            twin = DeviceTwin.model_validate_json(raw_data)
+            logger.info("✅ DeviceTwin loaded for device")
+            return twin
+
+        except HTTPRequestError:
+            raise
+        except Exception as e:
+            raise SendError("Failed to get device twin", e)
+
+    def patch(self, device_twin: DeviceTwin) -> DeviceTwin:
+        if not self._connection:
+            raise ConnectionError(self._config.socket_path)
+
+        try:
+            current_reported = self._twin.properties_reported.model_dump(by_alias=True)
+            new_reported = device_twin.properties_reported.model_dump(by_alias=True)
+
+            patch_ops = jsonpatch.make_patch(current_reported, new_reported)
+
+            if not patch_ops:
+                logger.info("No changes detected in reported properties; skipping patch.")
+                return device_twin
+
+            twin_patch = DeviceTwinPatch(
+                patch=patch_ops,
+                from_version=self._twin.version,
+                to_version=self._twin.version + 1,
+            )
+
+            print(patch_ops)
+
+            payload = json.dumps(twin_patch.model_dump(by_alias=True), ensure_ascii=False).encode("utf-8")
+
+            self._connection.request(
+                "PATCH",
+                "/device/twin/reported",
+                body=payload,
+                headers={"Content-Type": "application/json"},
+            )
+
+            response = self._connection.getresponse()
+            raw_data = response.read().decode("utf-8")
+
+            if response.status != 200:
+                raise HTTPRequestError(response.status, raw_data)
+
+            twin = DeviceTwin.model_validate_json(raw_data)
+            self._last_twin = twin
+            return twin
+
+        except HTTPRequestError:
+            raise
+        except Exception as e:
+            raise SendError("Failed to patch reported properties", e)

bedger/edge/config.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    socket_path: str = "/tmp/bedger.sock"
+
+    max_payload_size: int = 1024 * 1024  # 1 MB

bedger/edge/entities/__init__.py

@@ -0,0 +1,5 @@
+from .device_event import DeviceEvent
+from .severity import Severity
+
+
+__all__ = [DeviceEvent, Severity]

bedger/edge/entities/device.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class DeviceTag(BaseModel):
+    name: str
+    value: str

bedger/edge/entities/device_event.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from typing import Dict, Any, Annotated
+from pydantic import BaseModel, Field, field_validator, field_serializer
+from .severity import Severity
+
+
+class DeviceEvent(BaseModel):
+    """
+    Represents a stored or transmitted device event.
+    This model is compatible with the local /device/events API.
+    """
+
+    event_type: Annotated[
+        str,
+        Field(
+            description="Event type in PascalCase format",
+            pattern=r"^[A-Z][a-zA-Z0-9]*$",
+        ),
+    ]
+    severity: Severity
+    details: Annotated[
+        Dict[str, Any],
+        Field(description="Event-specific details, must be JSON serializable"),
+    ]
+
+    @field_validator("details")
+    @classmethod
+    def validate_details(cls, value: Dict[str, Any]) -> Dict[str, Any]:
+        try:
+            json.dumps(value)
+        except TypeError:
+            raise ValueError("details must be a JSON serializable dictionary")
+        return value
+
+    @field_serializer("severity")
+    def serialize_severity(self, severity: Severity) -> str:
+        return severity.value

bedger/edge/entities/device_twin.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field, ConfigDict, field_serializer
+
+
+class PropertyMetaData(BaseModel):
+    """Metadata describing when and how a property set was last updated."""
+
+    short_hash: Optional[str] = Field(
+        None,
+        alias="$short_hash",
+        description="Short 8-character hash representing the content state of the property set.",
+    )
+    last_updated: Optional[datetime] = Field(
+        None,
+        alias="$last_updated",
+        description="Timestamp when this property set was last updated.",
+    )
+
+    # Serialize datetimes to ISO 8601 for JSON compatibility
+    @field_serializer("last_updated")
+    def serialize_last_updated(self, value: Optional[datetime]) -> Optional[str]:
+        return value.isoformat() if value else None
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class Properties(BaseModel):
+    """Represents either desired or reported property groups for device modules."""
+
+    modules: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Arbitrary key/value structure for per-module properties.",
+    )
+    metadata: Optional[PropertyMetaData] = Field(
+        None,
+        alias="$metadata",
+        description="Metadata tracking changes for this property group.",
+    )
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class DeviceTwin(BaseModel):
+    """Data-only representation of a Device Twin document as received from the edge or cloud."""
+
+    version: Optional[int] = Field(
+        default=None,
+        description="Version number of this twin document.",
+    )
+
+    properties_desired: Optional[Properties] = Field(
+        None,
+        alias="properties.desired",
+        description="Desired properties defined by the cloud (target configuration).",
+    )
+    properties_reported: Optional[Properties] = Field(
+        None,
+        alias="properties.reported",
+        description="Reported properties coming from the device (actual state).",
+    )
+
+    metadata: Optional[PropertyMetaData] = Field(
+        None,
+        alias="$metadata",
+        description="Overall metadata for the combined twin.",
+    )
+
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        use_enum_values=True,
+        json_encoders={datetime: lambda v: v.isoformat()},  # ensure datetime → ISO string
+    )
+
+    def model_dump(self, *args, **kwargs):
+        """Force by_alias=True unless explicitly overridden."""
+        kwargs.setdefault("by_alias", True)
+        return super().model_dump(*args, **kwargs)
+
+
+class DeviceTwinPatch(BaseModel):
+    """Data-only representation of a Device Twin patch (incremental update)."""
+
+    patch: List[Dict[str, Any]] = Field(
+        ...,
+        description="JSON Patch operations to apply to the twin (RFC 6902).",
+    )
+    from_version: int = Field(
+        ...,
+        description="Source version number before applying this patch.",
+    )
+    to_version: int = Field(
+        ...,
+        description="Target version number after applying this patch.",
+    )
+
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        json_encoders={datetime: lambda v: v.isoformat()},
+    )

bedger/edge/entities/enums.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class DeviceStatus(str, Enum):
+    ACTIVE = "ACTIVE"
+    SUSPENDED = "SUSPENDED"

bedger/edge/entities/severity.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class Severity(str, Enum):
+    UNKNOWN = "UNKNOWN"
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"

bedger/edge/errors.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+import socket
+
+
+class BedgerError(Exception):
+    """Base class for all Bedger-related exceptions."""
+
+    pass
+
+
+# --- Configuration and Initialization ---
+
+
+class ConfigurationError(BedgerError):
+    """Raised when configuration values are missing, invalid, or inconsistent."""
+
+    def __init__(self, message: str, path: str | None = None):
+        self.path = path
+        super().__init__(f"{message}{f' (path: {path})' if path else ''}")
+
+
+class EnvironmentError(BedgerError):
+    """Raised when the environment or system setup prevents operation (permissions, missing dirs, etc.)."""
+
+    pass
+
+
+# --- Networking / Socket Communication ---
+
+
+class ConnectionError(BedgerError):
+    """Raised when connection to a UNIX or network socket fails."""
+
+    def __init__(self, socket_path: str, original_error: Exception | None = None):
+        self.socket_path = socket_path
+        self.original_error = original_error
+        super().__init__(f"Failed to connect to socket at {socket_path}: {original_error}")
+
+
+class SendError(BedgerError):
+    """Raised when sending data to Bedger Edge fails."""
+
+    def __init__(self, message: str, original_error: Exception | None = None):
+        self.original_error = original_error
+        super().__init__(f"{message}{f' ({original_error})' if original_error else ''}")
+
+
+class ReceiveError(BedgerError):
+    """Raised when receiving acknowledgment or response fails."""
+
+    def __init__(self, message: str, original_error: Exception | None = None):
+        self.original_error = original_error
+        super().__init__(f"{message}{f' ({original_error})' if original_error else ''}")
+
+
+# --- HTTP API Errors ---
+
+
+class HTTPRequestError(BedgerError):
+    """Raised for failed HTTP requests to the local Bedger Edge API."""
+
+    def __init__(self, status_code: int, response: str):
+        self.status_code = status_code
+        self.response = response
+        super().__init__(f"Bedger API returned HTTP {status_code}: {response}")
+
+
+class JSONSerializationError(BedgerError):
+    """Raised when JSON encoding or decoding fails."""
+
+    pass
+
+
+# --- Certificates / Security ---
+
+
+class CaCertificateError(BedgerError):
+    """Raised when fetching or validating a CA certificate fails."""
+
+    pass
+
+
+class AuthenticationError(BedgerError):
+    """Raised when authentication or provisioning fails."""
+
+    pass
+
+
+# --- Device Twin / State Sync ---
+
+
+class DeviceTwinError(BedgerError):
+    """Raised when device twin synchronization or persistence fails."""
+
+    pass
+
+
+class DeviceEventError(BedgerError):
+    """Raised when processing or storing device events fails."""
+
+    pass
+
+
+# --- Utilities ---
+
+
+def map_socket_error(err: Exception, socket_path: str) -> BedgerError:
+    """Map low-level socket errors to Bedger-friendly errors."""
+    if isinstance(err, FileNotFoundError):
+        return ConnectionError(socket_path, original_error=err)
+    elif isinstance(err, PermissionError):
+        return EnvironmentError(f"Permission denied on socket {socket_path}")
+    elif isinstance(err, socket.timeout):
+        return ConnectionError(socket_path, original_error=err)
+    else:
+        return BedgerError(str(err))

bedger-0.0.9.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Henk van den Brink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bedger-0.0.9.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.1
+Name: bedger
+Version: 0.0.9
+Summary: 
+Author: Henk van den Brink
+Requires-Python: >=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: jsonpatch (>=1.33,<2.0)
+Description-Content-Type: text/markdown
+
+

bedger-0.0.9.dist-info/RECORD

@@ -0,0 +1,15 @@
+bedger/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bedger/edge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bedger/edge/client.py,sha256=lLNXjGCgSUVNB5kbmoaH9gow-gw94WypoQKb0ECQDPM,6716
+bedger/edge/config.py,sha256=0fUKThP0aJFk3WBF7JUtuKKhXlV07SX5VnqVOLNou-A,152
+bedger/edge/entities/__init__.py,sha256=BJhirUzpeOil_5cPUoSlkW0c9bXvoL9WItMfIivdF50,105
+bedger/edge/entities/device.py,sha256=gcMHacgFE5W2LTAIDe7vGhWmrSA8lyNK8HJbiilId5U,90
+bedger/edge/entities/device_event.py,sha256=BAgIpYve1s8f2PI2SZ_HxV5dz1Sotxhrp3ee4Dk9Fx0,1107
+bedger/edge/entities/device_twin.py,sha256=rix8LjeEAS8vGN1McnBP3mpwcehIZ3n095soY93rv8U,3350
+bedger/edge/entities/enums.py,sha256=Mudj_dxLOu6iCSPH583Nf-M0cNyxVgkekh-Pgq8gp4Y,105
+bedger/edge/entities/severity.py,sha256=tUN7eDSEN5cc5eAqhvKzVHD1pSEmrdwvNEGsmh4Pnfw,157
+bedger/edge/errors.py,sha256=Z3NCHj8s6oUZW0OvoFqr9fcLVaOMtTRDmPtnxQ4uDSQ,3205
+bedger-0.0.9.dist-info/LICENSE,sha256=lVrf6pfElYZ_o6ETq-XR91_7GHTzKGyeNWAKghvcNUE,1075
+bedger-0.0.9.dist-info/METADATA,sha256=rwemg9cPCXBhOXsCZN8HK7zrNm1cwk42rp5__Mp2vNQ,473
+bedger-0.0.9.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+bedger-0.0.9.dist-info/RECORD,,

bedger-0.0.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any