pybricks-service 1.0.0b1__py3-none-any.whl

pb_service/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The Pybricks service.
+
+Owns every hub connection and outlives any single CLI invocation, so a hub
+stays connected between commands and several clients can talk to one hub at
+once.
+"""
+
+__version__ = "1.0.0b1"
+
+__all__ = ["__version__"]

pb_service/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+from pb_service.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pb_service/backend.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Choosing how the service reaches hubs.
+
+Imported lazily so that a service running against the simulated backend, as the
+tests and CI do, never loads the Bluetooth stack at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, cast
+
+import anyio
+
+from pb_service.hub.transport import HubTransport
+
+if TYPE_CHECKING:
+    from aio_rfcomm import Bluetooth
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "HUB_BACKEND_ENV_VAR",
+    "PERMISSION_NAME",
+    "get_hub_transport",
+    "open_hub_transport",
+]
+
+HUB_BACKEND_ENV_VAR = "PB_HUB_BACKEND"
+"""Selects the transport.
+
+Left alone, the service uses every transport together, which is what lets a hub
+be found whichever way it happens to be reachable. Set it to ``usb``, ``ble`` or
+``rfcomm`` to use only one, or to ``fake`` for a simulated hub.
+"""
+
+
+PERMISSION_NAME = "Pybricks RFCOMM Service"
+"""What macOS calls this service when it asks about Bluetooth.
+
+Shown in the permission dialog and under Privacy & Security, and what the
+answer is remembered against, so changing it asks every user again. pb-cli
+repeats it in what it tells the user, and a test holds the two together.
+
+Not plain "Pybricks": among the other entries in Privacy & Security that
+reads as the Pybricks app or Pybricks Code, and says nothing about what is
+asking or why. This is the part of pb-service that reaches EV3 and NXT hubs
+over Bluetooth Classic, and only that part is asked about: BLE is bleak's,
+inside the service itself.
+"""
+
+
+def _usb() -> HubTransport:
+    from pb_service.hub.usb import UsbHubTransport
+
+    return UsbHubTransport()
+
+
+def _ble() -> HubTransport:
+    from pb_service.hub.ble import BleHubTransport
+
+    return BleHubTransport()
+
+
+def _rfcomm(bluetooth: Bluetooth | None) -> tuple[HubTransport, ...]:
+    if bluetooth is None:
+        return ()
+
+    from pb_service.hub.rfcomm import RfcommHubTransport
+
+    return (RfcommHubTransport(bluetooth),)
+
+
+def _backend() -> str:
+    return os.environ.get(HUB_BACKEND_ENV_VAR, "").lower()
+
+
+def get_hub_transport(bluetooth: Bluetooth | None = None) -> HubTransport:
+    """Return the transport this service should use.
+
+    Every import here is inside the branch that needs it, so a service running
+    against the simulated backend loads neither the Bluetooth stack nor the
+    serial one, and a machine using only one of the real transports does not
+    pay for the other.
+
+    Returns:
+        Always a :class:`~pb_service.hub.combined.CombinedTransport`, holding
+        USB and Bluetooth or whichever single transport ``PB_HUB_BACKEND``
+        names. Always, even for one transport, so that choosing between
+        transports and honouring a request for a particular one are implemented
+        in exactly one place rather than once per backend. The simulated backend
+        is what lets the whole service be exercised on a CI runner with no radio
+        and nothing plugged in.
+
+    Args:
+        bluetooth: Bluetooth Classic, already open, or None to leave RFCOMM
+            out. :func:`open_hub_transport` opens it when it is wanted.
+    """
+    from pb_service.hub.combined import CombinedTransport
+
+    backend = _backend()
+
+    if backend == "fake":
+        from pb_service.hub.fake import FakeHub, FakeHubTransport
+
+        logger.warning("using the simulated hub backend; no real hub will be found")
+        return CombinedTransport(
+            FakeHubTransport(
+                FakeHub(name="Pybricks Hub", address="00:11:22:33:44:55"),
+                FakeHub(name="Spare Hub", address="66:77:88:99:AA:BB"),
+            )
+        )
+
+    if backend == "usb":
+        return CombinedTransport(_usb())
+
+    if backend == "ble":
+        return CombinedTransport(_ble())
+
+    if backend == "rfcomm":
+        return CombinedTransport(*_rfcomm(bluetooth))
+
+    if backend:
+        logger.warning(
+            "unknown %s=%r; using every transport", HUB_BACKEND_ENV_VAR, backend
+        )
+
+    # In TRANSPORT_PREFERENCE order, which is what makes USB the one chosen when
+    # a hub is reachable both ways. A test holds the two together.
+    return CombinedTransport(_usb(), _ble(), *_rfcomm(bluetooth))
+
+
+@asynccontextmanager
+async def open_hub_transport() -> AsyncGenerator[HubTransport, None]:
+    """Open the transport this service should use, for as long as the block lasts.
+
+    Bluetooth Classic is held open in this scope when RFCOMM is in use, and
+    nowhere else: aio-rfcomm allows it open once per process, and everything
+    opened through it stops working when its block ends, so it has to outlive
+    every hub. It is opened the first time RFCOMM needs it, not here, so the
+    service never waits on it to start (see
+    :mod:`pb_service.hub.rfcomm.lazy`). If it cannot be opened, RFCOMM
+    reports Bluetooth as unusable and the other transports carry on.
+
+    Yields:
+        What :func:`get_hub_transport` returns.
+    """
+    backend = _backend()
+
+    if backend in ("fake", "usb", "ble"):
+        yield get_hub_transport()
+        return
+
+    import aio_rfcomm.macos
+
+    from pb_service.hub.rfcomm.lazy import LazyBluetooth
+
+    # macOS asks the responsible process for Bluetooth permission, and a
+    # service started from a command line has no application to speak for it,
+    # so without this it is refused rather than asked. The answer is
+    # remembered under the name, so changing it asks the user again.
+    aio_rfcomm.macos.prompt_under_name(
+        name=PERMISSION_NAME, reason="to connect to LEGO hubs over Bluetooth"
+    )
+
+    async with anyio.create_task_group() as tg:
+        # Cast: it offers only the calls the RFCOMM transport makes.
+        bluetooth = cast("Bluetooth", LazyBluetooth(tg))
+
+        try:
+            yield get_hub_transport(bluetooth)
+        finally:
+            tg.cancel_scope.cancel()

pb_service/cli.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The service's command line.
+
+Plain argparse rather than the CLI framework used by ``pb``: the service must not
+depend on the presentation layer, and it is not a program people interact with
+directly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import signal
+import sys
+from typing import Any
+
+import anyio
+
+# Imported for the side effect: importing a method module registers its RPCs,
+# so nothing here reads the names. Said on each line, because a comment is
+# not something a linter can read.
+import pb_service.methods.hub  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.program  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.service  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.stdio  # noqa: F401 # pyright: ignore[reportUnusedImport]
+from pb_core import ipc, lock
+from pb_core.ipc import AddressInUseError
+from pb_core.logging import setup_logging
+from pb_core.paths import log_file
+from pb_service import __version__
+from pb_service import service as service_module
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["main"]
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_ALREADY_RUNNING = 3
+
+_LEVELS = {
+    "trace": 5,
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+}
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pb-service",
+        description="The Pybricks service. Normally started automatically.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"pb-service {__version__}"
+    )
+    parser.add_argument(
+        "--endpoint",
+        help="Where to listen, for example tcp://127.0.0.1:47823. "
+        "Defaults to the platform's socket or named pipe.",
+    )
+    parser.add_argument(
+        "--foreground",
+        action="store_true",
+        help="Log to stderr instead of only to the log file.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=sorted(_LEVELS),
+        default="info",
+        help="Verbosity (default: info).",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=float,
+        default=service_module.DEFAULT_IDLE_TIMEOUT,
+        help="Seconds with no clients and no hubs before exiting. "
+        "Use 0 to run until stopped.",
+    )
+    return parser
+
+
+async def _watch_signals(service: service_module.Service) -> None:
+    """Turn termination signals into an orderly shutdown.
+
+    On Windows ``anyio.open_signal_receiver`` is unavailable, because the
+    proactor loop has no ``add_signal_handler``. A plain handler that pokes the
+    loop is used instead, and it needs nothing else to make it prompt: asyncio
+    sets the signal wakeup socket, so the byte written by the C-level handler
+    -- from the thread Windows spawns to deliver a console control event --
+    completes the loop's own overlapped read and the wait returns at once.
+    Measured on Windows 11 against a loop parked in ``sleep_forever``: the
+    handler ran 0.7 ms after the event was sent, with nothing else waking the
+    loop.
+    """
+
+    if sys.platform == "win32":
+        import asyncio
+
+        loop = asyncio.get_running_loop()
+        event = anyio.Event()
+
+        def handler(signum: int, frame: Any) -> None:
+            loop.call_soon_threadsafe(event.set)
+
+        previous = [
+            (sig, signal.signal(sig, handler))
+            for sig in (signal.SIGINT, signal.SIGBREAK)
+        ]
+
+        try:
+            await event.wait()
+            service.request_shutdown("signal")
+        finally:
+            for sig, old in previous:
+                signal.signal(sig, old)
+
+        return
+
+    with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as signals:
+        async for _ in signals:
+            service.request_shutdown("signal")
+            return
+
+
+async def _serve(args: argparse.Namespace) -> int:
+    endpoint = ipc.resolve(args.endpoint)
+    service_module.log_banner(endpoint, __version__)
+
+    try:
+        async with service_module.run_service(
+            endpoint, idle_timeout=args.idle_timeout
+        ) as service:
+            async with anyio.create_task_group() as tg:
+                tg.start_soon(_watch_signals, service)
+                await service.wait_for_shutdown()
+                tg.cancel_scope.cancel()
+
+            logger.info("shutting down: %s", service.shutdown_reason)
+    except AddressInUseError:
+        # The common case is two clients racing to start a service. One wins,
+        # and both clients then connect to it, so this is not an error.
+        logger.info("another service is already listening on %s", endpoint)
+        return EXIT_ALREADY_RUNNING
+
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the service.
+
+    Args:
+        argv: Command line arguments, defaulting to ``sys.argv``.
+
+    Returns:
+        The process exit code.
+    """
+    args = _parser().parse_args(argv)
+    level = _LEVELS[args.log_level]
+
+    setup_logging(
+        level=level,
+        style="plain" if args.foreground else "file",
+        log_file=None if args.foreground else log_file(),
+    )
+
+    # The first thing written, before anything that could fail or block.
+    # A process that gets no further than here still leaves evidence that
+    # it existed, which is exactly what a leftover service with nothing in
+    # the log did not.
+    logger.info(
+        "pb-service starting (pid=%d, argv=%s)",
+        os.getpid(),
+        argv if argv is not None else sys.argv[1:],
+    )
+
+    try:
+        with lock.single_instance():
+            return anyio.run(_serve, args, backend="asyncio")
+    except lock.AlreadyRunningError:
+        logger.info("another service already holds the lock; exiting")
+        return EXIT_ALREADY_RUNNING
+    except Exception:
+        logger.exception("service failed")
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pb_service/errors.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Turning a hub failure into the wire error that describes it.
+
+Anything that reaches the dispatcher untranslated becomes ``INTERNAL_ERROR``,
+which tells a user only that something went wrong and leaves the real reason in
+a log they have to be told to go and read. That is the worst outcome for the
+most ordinary situations -- a hub that is busy, or asked to start a program it
+does not have -- so every failure a hub can produce is named here.
+
+The raw ``pbio_pybricks_error_t`` value travels in ``error.data``, because the
+client should be able to be exact about what the firmware said rather than
+paraphrasing a paraphrase.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+from pb_core.jsonrpc import ErrorCode, JsonRpcError
+from pb_service.hub import protocol as p
+from pb_service.hub.connection import HubDisconnectedError
+from pb_service.hub.manager import HubAlreadyConnectedError, HubNotFoundError
+from pb_service.hub.transport import HubCommandError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["HUB_FAILURES", "as_wire_error", "hub_errors"]
+
+HUB_FAILURES = (
+    HubCommandError,
+    HubDisconnectedError,
+    HubNotFoundError,
+    HubAlreadyConnectedError,
+)
+"""Everything a hub can fail with that has a wire error of its own."""
+
+
+def _refusal(exc: HubCommandError, doing: str | None) -> JsonRpcError:
+    """Describe a command the hub said no to."""
+    code = (
+        ErrorCode.HUB_BUSY
+        if exc.error == p.HubError.BUSY
+        else ErrorCode.HUB_INVALID_COMMAND
+    )
+    name = exc.error.name if isinstance(exc.error, p.HubError) else None
+    data: dict[str, Any] = {"hub_error": int(exc.error), "hub_error_name": name}
+    # "hub refused the command: INVALID_COMMAND" is true and useless. Where the
+    # caller said what it was attempting, say that instead.
+    message = f"the hub would not {doing}" if doing else str(exc)
+    # Worth a line in the log even though the client is told: which code the
+    # firmware chose is the difference between "nothing is stored there" and
+    # "that program is not valid", and only the log keeps it.
+    logger.info("hub refused: %s (%s)", message, name or f"{int(exc.error):#04x}")
+    return JsonRpcError(code, message, data)
+
+
+def as_wire_error(exc: Exception, doing: str | None = None) -> JsonRpcError:
+    """Translate a hub failure into the error to send back.
+
+    Args:
+        exc: What went wrong.
+        doing: What was being attempted, phrased to follow "the hub would not"
+            -- for example ``"start that program"``. Used only for a refusal,
+            where the firmware's own wording is a bare error name.
+
+    Returns:
+        The equivalent :class:`JsonRpcError`. Anything unrecognised becomes
+        ``INTERNAL_ERROR``, which is the honest answer for a bug.
+    """
+
+    if isinstance(exc, HubCommandError):
+        return _refusal(exc, doing)
+
+    if isinstance(exc, HubNotFoundError):
+        return JsonRpcError(ErrorCode.HUB_NOT_FOUND, str(exc))
+
+    if isinstance(exc, HubAlreadyConnectedError):
+        return JsonRpcError(ErrorCode.HUB_ALREADY_CONNECTED, str(exc))
+
+    if isinstance(exc, HubDisconnectedError):
+        return JsonRpcError(ErrorCode.HUB_DISCONNECTED, str(exc))
+
+    logger.error("unexpected hub failure", exc_info=exc)
+    return JsonRpcError(ErrorCode.INTERNAL_ERROR, str(exc))
+
+
+@contextmanager
+def hub_errors(doing: str | None = None) -> Generator[None]:
+    """Translate any hub failure raised inside the block.
+
+    Args:
+        doing: What is being attempted, as for :func:`as_wire_error`.
+
+    Yields:
+        Nothing; this only shapes what escapes.
+    """
+
+    try:
+        yield
+    except HUB_FAILURES as exc:
+        raise as_wire_error(exc, doing) from exc

pb_service/hub/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Hub protocol and connections."""