quii-helper 0.1.0__tar.gz

quii_helper-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# Mobile-app account credentials. CLOUD_USERNAME is also accepted as a legacy
+# alias for CLOUD_ACCOUNT.
+CLOUD_ACCOUNT=""
+CLOUD_PASSWORD=""
+DEVICE_ID=""
+CAMERA_DEVICE_HOST=""
+
+# Stable per-install client id. Generate one with:
+# python -c "import uuid; print(uuid.uuid4().hex)"
+CLOUD_CLIENT_UUID=""
+
+# Camera/app identity and cloud endpoints extracted from the APK or discovered
+# with: python -m examples.discover_env_values
+CLOUD_AUTH_URL=""
+CLOUD_SERVICE_URL=""
+CAMERA_OEM=""
+CAMERA_APP_ID=
+CAMERA_CLIENT_TYPE=
+IP_REGION_ID=
+CLOUD_AUTH_VERSION=""
+
+CAMERA_CHANNEL=1
+CAMERA_STREAM=2
+
+# Optional. AUTH_CODE is used by local /tdkcgi helpers and TCP/CGI
+# probe helpers, not by the normal cloud/P2P preview flow.
+AUTH_CODE=""
+DEVICE_PASSWORD=""
+
+# Required only by Camera.open_door(). This is the door-opening password,
+# separate from AUTH_CODE, DEVICE_PASSWORD, and CLOUD_PASSWORD.
+UNLOCK_PASSWORD=""  # Optional.
+
+TLS_VERIFY=true
+LOG_LEVEL=info

quii_helper-0.1.0/.github/scripts/check_distribution.py

@@ -0,0 +1,115 @@
+"""Reject incomplete/private release archives and mismatched release tags."""
+
+import os
+import sys
+import tarfile
+import zipfile
+from email.parser import BytesParser
+from pathlib import Path, PurePosixPath
+
+from packaging.version import Version
+
+
+def check_tag(tag: str, version: str) -> None:
+    """Require a v-prefixed tag whose PEP 440 version matches the package."""
+    if not tag.startswith("v") or Version(tag[1:]) != Version(version):
+        raise ValueError("release tag does not match distribution version")
+
+
+def check_members(names: set[str]) -> None:
+    """Keep credentials, extracted binaries and generated data out of archives."""
+    for name in names:
+        path = PurePosixPath(name)
+        if path.is_absolute() or ".." in path.parts or "\\" in name:
+            raise ValueError("unsafe archive member")
+        if (
+            set(path.parts)
+            & {"assets", "data", "venv", ".venv", "__pycache__"}
+            or any(
+                part.startswith(".env") and part != ".env.example"
+                for part in path.parts
+            )
+            or path.suffix.lower()
+            in {".pem", ".key", ".so", ".pyc", ".mp4", ".jpg", ".h264", ".log"}
+        ):
+            raise ValueError("private or generated file in distribution")
+
+
+def check_distributions(directory: Path, tag: str = "") -> str:
+    """Check both archives, SPDX metadata, type marker and source parity."""
+    wheels = list(directory.glob("*.whl"))
+    sources = list(directory.glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sources) != 1:
+        raise ValueError("expected exactly one wheel and one sdist")
+    with zipfile.ZipFile(wheels[0]) as archive:
+        wheel = {name: archive.read(name) for name in archive.namelist()}
+    with tarfile.open(sources[0]) as archive:
+        source = {}
+        for member in archive.getmembers():
+            if not member.isfile():
+                if not member.isdir():
+                    raise ValueError("links or special files in sdist")
+                continue
+            stream = archive.extractfile(member)
+            if stream is not None:
+                source[member.name] = stream.read()
+    check_members(set(wheel) | set(source))
+    metadata_names = [
+        name for name in wheel if name.endswith(".dist-info/METADATA")
+    ]
+    if len(metadata_names) != 1:
+        raise ValueError("expected one wheel metadata record")
+    metadata_path = PurePosixPath(metadata_names[0])
+    metadata = BytesParser().parsebytes(wheel[str(metadata_path)])
+    version = metadata["Version"]
+    if (
+        metadata["Name"] != "quii-helper"
+        or metadata["License-Expression"] != "MIT"
+        or metadata.get_all("License-File") != ["LICENSE"]
+        or str(metadata_path.parent / "licenses/LICENSE") not in wheel
+    ):
+        raise ValueError("missing package identity or SPDX license metadata")
+    root = "quii_helper-" + version + "/"
+    required = {
+        "PKG-INFO",
+        "LICENSE",
+        "README.md",
+        ".env.example",
+        "pyproject.toml",
+        "docs/README.md",
+        "examples/snapshot.py",
+        "tests/package/test_public_api.py",
+        ".github/scripts/check_distribution.py",
+    }
+    if not all(root + name in source for name in required):
+        raise ValueError("sdist is missing required sources or documentation")
+    source_metadata = BytesParser().parsebytes(source[root + "PKG-INFO"])
+    if source_metadata["Version"] != version:
+        raise ValueError("wheel and sdist versions differ")
+    package = {
+        name: data
+        for name, data in wheel.items()
+        if name.startswith("quii_helper/")
+    }
+    source_package = {
+        name[len(root) :]: data
+        for name, data in source.items()
+        if name.startswith(root + "quii_helper/")
+    }
+    if "quii_helper/py.typed" not in package or package != source_package:
+        raise ValueError("wheel and sdist package contents differ")
+    if tag:
+        check_tag(tag, version)
+    return version
+
+
+if __name__ == "__main__":
+    release_tag = (
+        os.environ.get("GITHUB_REF_NAME", "")
+        if os.environ.get("GITHUB_REF_TYPE") == "tag"
+        else ""
+    )
+    print(
+        "Checked distributions:",
+        check_distributions(Path(sys.argv[1]), release_tag),
+    )

quii_helper-0.1.0/.github/scripts/check_install.py

@@ -0,0 +1,150 @@
+"""Install both archives outside the checkout without camera or cloud I/O."""
+
+import argparse
+import importlib.metadata
+import shutil
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+from unittest.mock import patch
+
+
+def smoke() -> None:
+    """Verify installed imports, explicit configuration and host logging."""
+    from loguru import logger
+
+    Path(".env").write_text("CAMERA_APP_ID=invalid\n", encoding="utf-8")
+    messages: list[str] = []
+    sink = logger.add(lambda message: messages.append(str(message)))
+    with (
+        patch(
+            "dotenv.dotenv_values",
+            side_effect=AssertionError("implicit env read"),
+        ),
+        patch(
+            "dotenv.load_dotenv",
+            side_effect=AssertionError("implicit env load"),
+        ),
+        patch("socket.socket.connect", side_effect=AssertionError("network")),
+        patch("socket.socket.sendto", side_effect=AssertionError("network")),
+        patch("threading.Thread.start", side_effect=AssertionError("thread")),
+        patch(
+            "pathlib.Path.mkdir", side_effect=AssertionError("directory write")
+        ),
+    ):
+        import quii_helper
+        from quii_helper import AutonomousConfig, Camera
+
+        package = Path(quii_helper.__file__).resolve().parent
+        assert package.is_relative_to(Path(sys.prefix).resolve())
+        assert (package / "py.typed").is_file()
+        camera = Camera(AutonomousConfig(app_id=17))
+        assert camera.config.app_id == 17
+        assert camera.data_dir == (Path.cwd() / "data").resolve()
+        assert camera.config.assets_dir == (Path.cwd() / "assets").resolve()
+    logger.info("host sink survived")
+    logger.remove(sink)
+    assert len(messages) == 1 and "host sink survived" in messages[0]
+    assert not Path("data").exists() and not Path("assets").exists()
+    print("Installed library OK:", importlib.metadata.version("quii-helper"))
+
+
+def check_install(directory: Path, *, soak_seconds: float = 0) -> None:
+    """Install wheel and sdist into distinct disposable virtual environments."""
+    for suffix in ("*.whl", "*.tar.gz"):
+        artifacts = list(directory.resolve().glob(suffix))
+        if len(artifacts) != 1:
+            raise ValueError("expected one artifact of each distribution type")
+        with tempfile.TemporaryDirectory(prefix="quii-install-") as temporary:
+            root = Path(temporary)
+            venv.EnvBuilder(with_pip=True).create(root / "env")
+            executable = (
+                root
+                / "env"
+                / (
+                    "Scripts/python.exe"
+                    if sys.platform == "win32"
+                    else "bin/python"
+                )
+            )
+            subprocess.run(
+                [str(executable), "-m", "pip", "install", str(artifacts[0])],
+                cwd=root,
+                check=True,
+            )
+            subprocess.run(
+                [str(executable), "-m", "pip", "check"], cwd=root, check=True
+            )
+            subprocess.run(
+                [
+                    str(executable),
+                    "-I",
+                    str(Path(__file__).resolve()),
+                    "--smoke",
+                ],
+                cwd=root,
+                check=True,
+            )
+            # Test the installed artifact, not an editable checkout.
+            subprocess.run(
+                [
+                    str(executable),
+                    "-m",
+                    "pip",
+                    "install",
+                    f"{artifacts[0]}[dev]",
+                ],
+                cwd=root,
+                check=True,
+            )
+            source = Path(__file__).resolve().parents[2]
+            consumer = root / "consumer"
+            consumer.mkdir()
+            shutil.copytree(source / "examples", consumer / "examples")
+            subprocess.run(
+                [
+                    str(executable),
+                    "-I",
+                    "-B",
+                    "-c",
+                    "import sys; from pathlib import Path; "
+                    "sys.path.insert(0, str(Path.cwd())); "
+                    "import quii_helper, pytest; "
+                    "assert Path(quii_helper.__file__).resolve().is_relative_to("
+                    "Path(sys.prefix).resolve()); "
+                    "raise SystemExit(pytest.main(['-q', '--import-mode=importlib', "
+                    "'-p', 'no:cacheprovider', sys.argv[1]]))",
+                    str(source / "tests"),
+                ],
+                cwd=consumer,
+                check=True,
+            )
+            if suffix == "*.whl" and soak_seconds:
+                subprocess.run(
+                    [
+                        str(executable),
+                        "-I",
+                        "-B",
+                        str(source / ".github/scripts/check_rtsp_soak.py"),
+                        "--seconds",
+                        str(soak_seconds),
+                    ],
+                    cwd=consumer,
+                    check=True,
+                )
+            subprocess.run(
+                [str(executable), "-m", "pip", "check"], cwd=root, check=True
+            )
+
+
+if __name__ == "__main__":
+    if sys.argv[1:] == ["--smoke"]:
+        smoke()
+    else:
+        parser = argparse.ArgumentParser(description=__doc__)
+        parser.add_argument("directory", type=Path)
+        parser.add_argument("--soak-seconds", type=float, default=0)
+        arguments = parser.parse_args()
+        check_install(arguments.directory, soak_seconds=arguments.soak_seconds)

quii_helper-0.1.0/.github/scripts/check_rtsp_soak.py

@@ -0,0 +1,180 @@
+"""Exercise the installed RTSP server with synthetic loopback-only video."""
+
+import argparse
+import gc
+import json
+import socket
+import threading
+import time
+import tracemalloc
+
+from quii_helper.streaming.rtsp.server import RtspH264Server
+
+
+def read_exact(sock: socket.socket, size: int) -> bytes:
+    data = bytearray()
+    while len(data) < size:
+        chunk = sock.recv(size - len(data))
+        if not chunk:
+            raise EOFError("RTSP viewer disconnected")
+        data.extend(chunk)
+    return bytes(data)
+
+
+class Viewer:
+    """A real TCP viewer; the slow variant deliberately never reads RTP."""
+
+    def __init__(self, server: RtspH264Server, *, slow: bool = False):
+        self.sock = socket.socket()
+        self.sock.settimeout(3)
+        if slow:
+            self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 1024)
+        self.sock.connect(("127.0.0.1", server.port))
+        self.stopped = threading.Event()
+        self.packets = 0
+        self.frames = 0
+        self.error: BaseException | None = None
+        self.thread: threading.Thread | None = None
+        try:
+            for cseq, method in enumerate(("SETUP", "PLAY"), 1):
+                request = (
+                    f"{method} {server.url} RTSP/1.0\r\nCSeq: {cseq}\r\n"
+                    "Transport: RTP/AVP/TCP;unicast;interleaved=0-1\r\n\r\n"
+                )
+                self.sock.sendall(request.encode("ascii"))
+                response = bytearray()
+                while not response.endswith(b"\r\n\r\n"):
+                    response.extend(read_exact(self.sock, 1))
+                    if len(response) > 4096:
+                        raise AssertionError("oversized RTSP response")
+                assert response.startswith(b"RTSP/1.0 200 "), response
+            self.sock.settimeout(0.5)
+            if not slow:
+                self.thread = threading.Thread(
+                    target=self._receive, name="release-gate-viewer"
+                )
+                self.thread.start()
+        except BaseException:
+            self.close()
+            raise
+
+    def _receive(self) -> None:
+        previous_sequence = None
+        try:
+            while not self.stopped.is_set():
+                try:
+                    header = read_exact(self.sock, 4)
+                except socket.timeout:
+                    continue
+                assert header[:2] == b"$\0", header
+                packet = read_exact(
+                    self.sock, int.from_bytes(header[2:], "big")
+                )
+                assert len(packet) >= 12 and packet[0] == 0x80
+                sequence = int.from_bytes(packet[2:4], "big")
+                if previous_sequence is not None:
+                    assert sequence == (previous_sequence + 1) & 0xFFFF
+                previous_sequence = sequence
+                self.packets += 1
+                self.frames += bool(packet[1] & 0x80)
+        except BaseException as exc:
+            if not self.stopped.is_set():
+                self.error = exc
+
+    def close(self) -> None:
+        self.stopped.set()
+        try:
+            self.sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        self.sock.close()
+        if self.thread is not None:
+            self.thread.join(2)
+            assert not self.thread.is_alive(), "viewer thread leaked"
+
+
+def run_soak(seconds: float) -> dict[str, object]:
+    """Bound retained Python memory and exercise shutdown every 30 seconds."""
+    if seconds < 3:
+        raise ValueError("soak duration must be at least 3 seconds")
+    unit = b"\0\0\0\1\x65" + b"x" * (16 * 1024)
+    frames = packets = cycles = slow_disconnects = 0
+    started = time.monotonic()
+    deadline = started + seconds
+    baseline = None
+    growth = 0
+    tracemalloc.start()
+    try:
+        while time.monotonic() < deadline:
+            server = RtspH264Server(host="127.0.0.1", port=0).start()
+            fast = slow = None
+            workers = [server._accept_thread]
+            try:
+                fast = Viewer(server)
+                slow = Viewer(server, slow=True)
+                with server._clients_lock:
+                    clients = list(server._clients)
+                for client in clients:
+                    workers.extend([client._thread, client._sender_thread])
+                    if client.address[1] == slow.sock.getsockname()[1]:
+                        client.sock.setsockopt(
+                            socket.SOL_SOCKET, socket.SO_SNDBUF, 1024
+                        )
+                cycle_started = time.monotonic()
+                cycle_end = min(deadline, cycle_started + 30)
+                slow_checked = False
+                while time.monotonic() < cycle_end:
+                    server.publish(unit)
+                    assert fast.error is None, repr(fast.error)
+                    with server._clients_lock:
+                        assert all(
+                            client._outgoing_bytes <= 4 * 1024 * 1024
+                            for client in server._clients
+                        )
+                    if time.monotonic() - cycle_started >= 2:
+                        assert server.client_count == 1, "slow viewer retained"
+                        slow_checked = True
+                    time.sleep(0.1)
+                assert fast.frames > 0, "fast viewer received no media"
+                assert fast.error is None, repr(fast.error)
+                frames += fast.frames
+                packets += fast.packets
+                slow_disconnects += slow_checked
+            finally:
+                for viewer in (fast, slow):
+                    if viewer is not None:
+                        viewer.close()
+                server.close()
+                for worker in workers:
+                    if worker is not None:
+                        worker.join(2)
+                        assert not worker.is_alive(), worker.name
+            cycles += 1
+            gc.collect()
+            retained, _ = tracemalloc.get_traced_memory()
+            if baseline is None:
+                baseline = retained
+            growth = max(growth, retained - baseline)
+            assert growth <= 8 * 1024 * 1024, "retained Python memory grew"
+        _, peak = tracemalloc.get_traced_memory()
+    finally:
+        tracemalloc.stop()
+    assert slow_disconnects > 0, "slow-client test did not run"
+    return {
+        "elapsed_seconds": round(time.monotonic() - started, 3),
+        "cycles": cycles,
+        "received_frames": frames,
+        "received_rtp_packets": packets,
+        "slow_disconnects": slow_disconnects,
+        "retained_python_growth_bytes": growth,
+        "peak_traced_python_bytes": peak,
+        "worker_cleanup": "passed",
+        "scope": "synthetic loopback TCP; not camera, codec, UDP or RSS proof",
+    }
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--seconds", type=float, default=120)
+    arguments = parser.parse_args()
+    print(json.dumps(run_soak(arguments.seconds), indent=2))