pygira 0.0.1__py3-none-any.whl

pygira/__init__.py

@@ -0,0 +1 @@
+"""pygira provisioning library."""

pygira/_http.py

@@ -0,0 +1,142 @@
+"""Minimal stdlib HTTP client — the small slice of httpx this project used.
+
+Why: httpx is pre-1.0 (no stable API). We only used sync Client with cookie
+persistence (the session-login handshake depends on it), verify=False for the
+device's self-signed TLS, basic auth, and .json()/.content/.raise_for_status().
+That maps cleanly onto urllib + http.cookiejar + ssl, so no third-party dep.
+"""
+
+import base64
+import json as _json
+import ssl
+import urllib.error
+import urllib.request
+from http.cookiejar import CookieJar
+from types import TracebackType
+from typing import Literal, cast
+from urllib.parse import urlencode
+
+
+# ponytail: one exception type. raise_for_status (HTTP 4xx/5xx) and transport
+# failures (connection refused, timeout) both raise this — matches the single
+# `except httpx.HTTPError` the callers rely on.
+class HTTPError(Exception):
+    """Request failed (connection error or, via raise_for_status, 4xx/5xx)."""
+
+
+HTTP_ERROR_STATUS = 400
+
+_UNVERIFIED = ssl.create_default_context()
+_UNVERIFIED.check_hostname = False
+_UNVERIFIED.verify_mode = ssl.CERT_NONE
+
+
+class Response:
+    def __init__(self, status_code: int, content: bytes) -> None:
+        self.status_code = status_code
+        self.content = content
+
+    def json(self: "Response") -> object:
+        return _json.loads(self.content)
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= HTTP_ERROR_STATUS:
+            msg = f"HTTP {self.status_code}"
+            raise HTTPError(msg)
+
+
+class Client:
+    """Context-managed session. Cookies persist across requests on one instance."""
+
+    def __init__(
+        self,
+        base_url: str = "",
+        headers: dict | None = None,
+        auth: tuple[str, str] | None = None,
+        verify: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._headers = dict(headers or {})
+        if auth is not None:
+            token = base64.b64encode(f"{auth[0]}:{auth[1]}".encode()).decode()
+            self._headers.setdefault("Authorization", f"Basic {token}")
+        handlers: list[urllib.request.BaseHandler] = [
+            urllib.request.HTTPCookieProcessor(CookieJar()),
+        ]
+        if not verify:
+            handlers.append(urllib.request.HTTPSHandler(context=_UNVERIFIED))
+        self._opener = urllib.request.build_opener(*handlers)
+
+    def __enter__(self: "Client") -> "Client":
+        return self
+
+    def __exit__(
+        self: "Client",
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        return False
+
+    def _url(self, path: str, params: dict[str, object] | None = None) -> str:
+        url = path if path.startswith("http") else f"{self.base_url}{path}"
+        if params:
+            url = f"{url}?{urlencode(params)}"
+        return url
+
+    def _request(self, method: str, path: str, **kwargs: object) -> Response:
+        params = cast("dict[str, object] | None", kwargs.get("params"))
+        json_payload = cast("dict[str, object] | None", kwargs.get("json"))
+        content = cast("bytes | None", kwargs.get("content"))
+        headers = cast("dict[str, str] | None", kwargs.get("headers"))
+
+        body = content
+        hdrs = {**self._headers, **(headers or {})}
+        if json_payload is not None:
+            body = _json.dumps(json_payload).encode()
+            hdrs.setdefault("Content-Type", "application/json")
+        req = urllib.request.Request(
+            self._url(path, params),
+            data=body,
+            headers=hdrs,
+            method=method,
+        )
+        try:
+            with self._opener.open(req, timeout=self.timeout) as resp:
+                return Response(resp.status, resp.read())
+        except urllib.error.HTTPError as e:
+            # 4xx/5xx: a response, not a failure yet — surfaced via raise_for_status.
+            return Response(e.code, e.read())
+        except (urllib.error.URLError, OSError) as e:
+            raise HTTPError(str(e)) from e
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, object] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        return self._request("GET", path, params=params, headers=headers)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: dict[str, object] | None = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        return self._request("POST", path, json=json, content=content, headers=headers)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: dict[str, object] | None = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        return self._request("PUT", path, json=json, content=content, headers=headers)

pygira/api.py

@@ -0,0 +1,292 @@
+"""iscwebservice HTTP client — port 80 (via nginx proxy).
+
+Auth: Authorization: Basic <base64(user:password)>  (capital "Basic")
+Handles firmware update commands.
+"""
+
+import base64
+import hashlib
+import time
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from pygira import _http as httpx
+from pygira.models import NetworkConfig
+
+
+def _auth_header(username: str, password: str) -> str:
+    token = base64.b64encode(f"{username}:{password}".encode()).decode()
+    return f"Basic {token}"
+
+
+class ApiClient:
+    """HTTP client for the iscwebservice API on port 80."""
+
+    def __init__(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        timeout: float = 60.0,
+        api_prefix: str = "/api",
+    ) -> None:
+        """Initialize the ApiClient.
+
+        Args:
+            host: Hostname or IP of the device (no scheme, e.g. "192.168.1.100").
+            username: Username for basic auth.
+            password: Password for basic auth.
+            timeout: Request timeout in seconds.
+            api_prefix: URL path prefix, e.g. "/api" (G1) or "/webservice" (X1).
+
+        """
+        self.host = host
+        self.username = username
+        self.password = password
+        self.api_prefix = api_prefix.rstrip("/")
+        self._headers = {
+            "Authorization": _auth_header(username, password),
+            "Content-Type": "application/json",
+        }
+        self.timeout = timeout
+
+    def _post(self, payload: dict[str, Any]) -> dict:
+        with httpx.Client(base_url=f"http://{self.host}", timeout=self.timeout) as client:
+            resp = client.post(f"{self.api_prefix}", json=payload, headers=self._headers)
+            resp.raise_for_status()
+            data = cast("dict[str, Any]", resp.json() if resp.content else {})
+            if (
+                isinstance(data, dict)
+                and data.get("error")
+                and self.api_prefix in {"/api", "/webservice"}
+            ):
+                recovered = self._post_with_session_fallback(payload, data)
+                if recovered is not None:
+                    return recovered
+                msg = (
+                    f"API error {data.get('id', '?')}: {data.get('error')}"
+                    " (session auth also failed — check password)"
+                )
+                raise RuntimeError(
+                    msg,
+                )
+            return data
+
+    @staticmethod
+    def _sha256_hex(value: str) -> str:
+        return hashlib.sha256(value.encode()).hexdigest()
+
+    @staticmethod
+    def _sha256_hex_upper(value: str) -> str:
+        return hashlib.sha256(value.encode()).hexdigest().upper()
+
+    def _compute_auth_token(self, password: str, salt: str, session_salt: str, version: str) -> str:
+        if version == "GDS_1":
+            digest = hashlib.sha256((password + salt).encode("utf-8")).digest()
+            password_hash = base64.b64encode(digest).decode()[:43]
+        else:
+            first = self._sha256_hex(password)
+            password_hash = self._sha256_hex(f"{first}+{salt}")
+        return self._sha256_hex_upper(f"{password_hash}+{session_salt}")
+
+    def _ws_payload(self, command: str, data: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"command": command, "keepAlive": True}
+        if data is not None:
+            payload["data"] = data
+        return payload
+
+    def _post_with_session_fallback(
+        self,
+        payload: dict[str, Any],
+        first_error: dict[str, Any],
+    ) -> dict | None:
+        # Only retry on auth/session-style errors.
+        if str(first_error.get("id", "")) not in {"220", "235"}:
+            return None
+
+        path = self.api_prefix
+        with httpx.Client(base_url=f"http://{self.host}", timeout=self.timeout) as client:
+            salt_resp = client.post(
+                path,
+                json=self._ws_payload("getPasswordSalt", {"username": self.username}),
+            )
+            salt_resp.raise_for_status()
+            salt_data = cast("dict[str, Any]", salt_resp.json() if salt_resp.content else {})
+            session_data = (salt_data or {}).get("data") or {}
+            salt = session_data.get("salt")
+            session_salt = session_data.get("sessionSalt")
+            version = session_data.get("version", "1")
+            if not salt or not session_salt:
+                return None
+
+            token = self._compute_auth_token(self.password, salt, session_salt, version)
+            auth_resp = client.post(
+                path,
+                json=self._ws_payload(
+                    "doAuthenticateSession",
+                    {"username": self.username, "token": token},
+                ),
+            )
+            auth_resp.raise_for_status()
+            auth_data = cast("dict[str, Any]", auth_resp.json() if auth_resp.content else {})
+            if isinstance(auth_data, dict) and auth_data.get("error"):
+                return None
+
+            cmd = payload["command"]
+            retry_data = {k: v for k, v in payload.items() if k != "command"}
+            ws_data = (
+                retry_data.get("data")
+                if set(retry_data.keys()) == {"data"}
+                else (retry_data or None)
+            )
+            retry_resp = client.post(path, json=self._ws_payload(cmd, ws_data))
+            retry_resp.raise_for_status()
+            return cast("dict[str, Any]", retry_resp.json() if retry_resp.content else {})
+
+    def check_online_update(self) -> dict:
+        """Query available online firmware update info."""
+        return self._post({"command": "infoonline"})
+
+    def get_firmware_status(self) -> dict:
+        """Query firmware status (used by X1 web UI polling)."""
+        return self._post({"command": "getFirmwareStatus"})
+
+    def get_device_info(self, *, force_long: bool = False) -> dict:
+        """Fetch device info from webservice API."""
+        payload: dict[str, Any] = {"command": "getDeviceInfo"}
+        if force_long:
+            payload["data"] = {"forceLong": True}
+        return self._post(payload)
+
+    def get_diagnostic_page(self, *, completely: bool = True) -> dict:
+        """Fetch diagnostic page data from webservice API."""
+        return self._post({"command": "getDiagnosticPage", "data": {"completely": completely}})
+
+    def set_ntp_config(self, *, enabled: bool, server: str, interval_minutes: int) -> dict:
+        """Set NTP configuration via webservice API."""
+        return self._post(
+            {
+                "command": "setNtpConfig",
+                "data": {
+                    "Ntp": enabled,
+                    "NtpServerAddress": server,
+                    "NtpInterval": str(interval_minutes),
+                },
+            },
+        )
+
+    def set_ip_config(self, cfg: NetworkConfig) -> dict:
+        """Set network configuration via webservice API."""
+        data: dict[str, Any] = {
+            "Dhcp": cfg.dhcp,
+        }
+        if not cfg.dhcp:
+            data["IpAddress"] = cfg.ip_address
+            data["SubnetMask"] = cfg.subnet_mask
+            data["DefaultGateway"] = cfg.default_gateway
+            data["NameServer"] = cfg.primary_dns
+            if cfg.secondary_dns:
+                data["SecondaryDns"] = cfg.secondary_dns
+        return self._post({"command": "setIpConfig", "data": data})
+
+    def get_logfile(self) -> bytes:
+        """Fetch diagnostic logfile ZIP returned by webservice command getLogfile."""
+        result = self._post({"command": "getLogfile"})
+        content_b64 = ((result or {}).get("data") or {}).get("content")
+        if not content_b64:
+            msg = f"getLogfile returned no content: {result}"
+            raise RuntimeError(msg)
+        return base64.b64decode(content_b64)
+
+    def trigger_online_update(self) -> dict:
+        """Start online firmware update from Gira download server."""
+        return self._post({"command": "startonlineupdate"})
+
+    def get_upgrade_progress(self) -> dict:
+        """Get current firmware update progress."""
+        return self._post({"command": "progress"})
+
+    def upload_firmware(self, firmware_path: Path) -> None:
+        """Upload a local firmware ZIP file to the device."""
+        data = firmware_path.read_bytes()
+        with httpx.Client(base_url=f"http://{self.host}", timeout=300.0) as client:
+            resp = client.post(
+                f"{self.api_prefix}/upload/v2",
+                content=data,
+                headers={
+                    "Authorization": self._headers["Authorization"],
+                    "Content-Type": "application/x-zip-compressed",
+                },
+            )
+            resp.raise_for_status()
+
+    def initiate_local_install(self) -> dict:
+        """Trigger installation of the previously uploaded firmware file."""
+        return self._post({"command": "initlocalupload"})
+
+    def wait_for_completion(self, poll_interval: float = 5.0, max_wait: float = 300.0) -> bool:
+        """Poll progress until done or timeout. Returns True if completed."""
+        deadline = time.monotonic() + max_wait
+        while time.monotonic() < deadline:
+            try:
+                resp = self.get_upgrade_progress()
+                state = resp.get("state", resp.get("status", ""))
+                if state in ("done", "completed", "finished", "success"):
+                    return True
+                if state in ("error", "failed"):
+                    error_msg = f"Firmware update failed: {resp}"
+                    raise RuntimeError(error_msg)
+            except httpx.HTTPError:
+                # Device may be rebooting
+                pass
+            time.sleep(poll_interval)
+        return False
+
+    def control_service(self, service: str, control: str) -> dict:
+        """Control a system service (e.g. enable/disable/start/stop)."""
+        return self._post({"command": "controlService", "service": service, "control": control})
+
+    def enable_ssh(self, *, persistent: bool = True) -> None:
+        """Enable SSH access on the device.
+
+        persistent=True: touches /opt/userdata/.ssh-enabled (survives reboot) then starts sshd.
+        persistent=False: starts sshd once without persisting (start-once).
+        """
+        if persistent:
+            self.control_service("S50sshd", "enable")
+            self.control_service("S50sshd", "start")
+        else:
+            self.control_service("S50sshd", "start-once")
+
+    def disable_ssh(self) -> None:
+        """Stop sshd and remove the persistent-enable marker."""
+        self.control_service("S50sshd", "stop")
+        self.control_service("S50sshd", "disable")
+
+    def start_ssh(self, mode: Literal["persistent", "once"] = "persistent") -> None:
+        """Start SSH in the given mode.
+
+        Args:
+            mode: "persistent" to enable and start sshd persistently, or
+                  "once" to start sshd for this session only.
+
+        """
+        if mode == "persistent":
+            self.enable_ssh(persistent=True)
+        else:
+            self.enable_ssh(persistent=False)
+
+    def reboot(self) -> None:
+        """Reboot the device via JSON API."""
+        self._post({"command": "reboot"})
+
+    def factory_reset(self) -> None:
+        """Reset the device via JSON API."""
+        self._post({"command": "factoryReset"})
+
+    def commissioning_test(self) -> dict:
+        """Run the built-in commissioning test (GET /api/commissioningtest)."""
+        with httpx.Client(base_url=f"http://{self.host}", timeout=self.timeout) as client:
+            resp = client.get(f"{self.api_prefix}/commissioningtest", headers=self._headers)
+            resp.raise_for_status()
+            return cast("dict[str, Any]", resp.json() if resp.content else {})

pygira/cli.py

@@ -0,0 +1,49 @@
+"""pygira - Gira provisioning CLI."""
+
+import click
+
+from pygira.commands import bootstrap, config, device, firmware, gds, maintenance
+from pygira.core.types import DeviceType
+
+
+@click.group()
+@click.option(
+    "--device",
+    type=click.Choice(["g1", "x1"]),
+    default=None,
+    help="Expected device type",
+)
+@click.option("--name", "device_name", default=None, help="Named device from devices.toml")
+@click.option("--location", default=None, help="Optional location name from devices.toml")
+@click.option(
+    "--config",
+    "config_path",
+    default="devices.toml",
+    show_default=True,
+    help="Path to devices.toml",
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    device: str | None,
+    device_name: str | None,
+    location: str | None,
+    config_path: str,
+) -> None:
+    """Provision and manage Gira devices."""
+    ctx.ensure_object(dict)
+    ctx.obj["requested_device"] = DeviceType(device) if device else None
+    ctx.obj["device_name"] = device_name
+    ctx.obj["location"] = location
+    ctx.obj["config_path"] = config_path
+
+
+config.register(main)
+device.register(main)
+gds.register(main)
+maintenance.register(main)
+firmware.register(main)
+bootstrap.register(main)
+
+if __name__ == "__main__":
+    main()

pygira/commands/__init__.py

@@ -0,0 +1 @@
+"""Command handlers for pygira."""