pybricks-core 1.0.0b1__py3-none-any.whl

pb_core/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Shared building blocks for the Pybricks tool suite.
+
+This package holds everything both the service and the client need to agree on:
+the JSON-RPC wire protocol, the per-platform IPC transport, logging setup and
+platform paths. It deliberately depends on neither ``pb_service`` nor ``pb_client``.
+"""
+
+__version__ = "1.0.0b1"
+
+__all__ = ["__version__"]

pb_core/auth.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Shared-secret authentication between the client and the service.
+
+The service writes a random token to a file only the current user can read, and
+every client presents it in the mandatory first call. This is the X11
+magic-cookie scheme.
+
+It is required on every transport rather than only on TCP. The default
+discretionary access control list on a Windows named pipe grants Everyone read
+access, so without a secret another local user could not issue commands but
+could still watch a hub's output. It is not sufficient on its own for a service
+reachable beyond loopback, where the token crosses the network in clear and
+needs TLS or an SSH tunnel around it.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+import sys
+from pathlib import Path
+
+from pb_core import paths
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["TOKEN_BYTES", "load_token", "read_or_create_token"]
+
+TOKEN_BYTES = 32
+
+
+def read_or_create_token(path: Path | None = None) -> str:
+    """Return the service's token, creating one if there is none.
+
+    Called by the service at startup.
+
+    Args:
+        path: Override the cookie file location.
+
+    Returns:
+        The token as hexadecimal text.
+    """
+    cookie = path or paths.cookie_file()
+    paths.ensure_private_dir(cookie.parent)
+
+    if cookie.exists():
+        existing = cookie.read_text(encoding="ascii").strip()
+        if existing:
+            return existing
+
+    token = secrets.token_hex(TOKEN_BYTES)
+    # Create with restrictive permissions from the outset rather than widening
+    # then narrowing, which would leave a window where the token is readable.
+    descriptor = cookie.open("w", encoding="ascii")
+
+    try:
+        if sys.platform != "win32":
+            import os
+
+            os.fchmod(descriptor.fileno(), 0o600)
+
+        descriptor.write(token)
+    finally:
+        descriptor.close()
+
+    logger.debug("wrote a new authentication token to %s", cookie)
+    return token
+
+
+def load_token(path: Path | None = None) -> str | None:
+    """Return the service's token if it can be read.
+
+    Called by clients before connecting.
+
+    Args:
+        path: Override the cookie file location.
+
+    Returns:
+        The token, or ``None`` if no service has ever run for this user.
+    """
+    cookie = path or paths.cookie_file()
+
+    try:
+        token = cookie.read_text(encoding="ascii").strip()
+    except OSError:
+        return None
+
+    return token or None

pb_core/ipc/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Transport between the client and the service.
+
+The user never types an address: :func:`pb_core.ipc.address.resolve` picks the
+right one for the platform. Everything above this package deals only in
+:class:`anyio.abc.ByteStream`, so neither the service nor the client contains any
+platform-specific code.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+
+from anyio.abc import ByteStream
+
+from pb_core.ipc.address import ENDPOINT_ENV_VAR, Endpoint, default, resolve
+from pb_core.ipc.backend import IpcBackend, IpcListener, StreamHandler, get_backend
+from pb_core.ipc.errors import AddressInUseError, EndpointError
+
+__all__ = [
+    "ENDPOINT_ENV_VAR",
+    "AddressInUseError",
+    "Endpoint",
+    "EndpointError",
+    "IpcBackend",
+    "IpcListener",
+    "StreamHandler",
+    "connect",
+    "create_listener",
+    "default",
+    "get_backend",
+    "resolve",
+]
+
+
+def connect(endpoint: Endpoint) -> AbstractAsyncContextManager[ByteStream]:
+    """Connect to the service listening at ``endpoint``.
+
+    Args:
+        endpoint: Where the service is listening.
+
+    Returns:
+        An async context manager yielding the connected stream.
+
+    Raises:
+        ConnectionRefusedError: If nothing is listening. Callers treat this as
+            "the service is not running" and may start one.
+    """
+    return get_backend(endpoint).connect(endpoint)
+
+
+def create_listener(endpoint: Endpoint) -> AbstractAsyncContextManager[IpcListener]:
+    """Listen for clients at ``endpoint``.
+
+    Args:
+        endpoint: Where to listen.
+
+    Returns:
+        An async context manager yielding the listener.
+
+    Raises:
+        AddressInUseError: If another service already holds the address.
+    """
+    return get_backend(endpoint).create_listener(endpoint)

pb_core/ipc/address.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Endpoint addressing for the service.
+
+An endpoint is written as a URI so that one string can name any transport:
+
+* ``unix:///run/user/1000/pybricks/pb-service.sock`` -- AF_UNIX socket (Linux, macOS)
+* ``pipe://pybricks-pb-service-david`` -- Windows named pipe
+* ``tcp://127.0.0.1:47823`` -- TCP, for remote services and for tests
+* ``memory://name`` -- in-process, used by the test suite
+
+Users are not expected to type these. :func:`resolve` picks the right default
+for the platform, and ``PB_ENDPOINT`` overrides it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from typing import Literal
+
+from pb_core import paths
+from pb_core.ipc.errors import EndpointError
+
+__all__ = ["ENDPOINT_ENV_VAR", "Endpoint", "Scheme", "default", "resolve"]
+
+ENDPOINT_ENV_VAR = "PB_ENDPOINT"
+
+Scheme = Literal["unix", "pipe", "tcp", "memory"]
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """A transport-independent address for the service."""
+
+    scheme: Scheme
+    target: str
+    """Socket path, pipe name, ``host:port``, or in-process key."""
+
+    @classmethod
+    def parse(cls, uri: str) -> Endpoint:
+        """Parse an endpoint URI.
+
+        Args:
+            uri: A string such as ``tcp://127.0.0.1:47823``.
+
+        Returns:
+            The parsed endpoint.
+
+        Raises:
+            EndpointError: If the URI is malformed or names an unknown
+                scheme. It is a :class:`ValueError`.
+        """
+        scheme, separator, rest = uri.partition("://")
+        if not separator:
+            raise EndpointError(f"endpoint is not a URI: {uri!r}")
+
+        if scheme not in ("unix", "pipe", "tcp", "memory"):
+            raise EndpointError(f"unknown endpoint scheme: {scheme!r}")
+
+        if not rest:
+            raise EndpointError(f"endpoint has no target: {uri!r}")
+
+        if scheme == "tcp":
+            host, colon, port = rest.rpartition(":")
+            if not colon or not host:
+                raise EndpointError(f"tcp endpoint needs host:port: {uri!r}")
+
+            try:
+                number = int(port)
+            except ValueError:
+                raise EndpointError(
+                    f"tcp endpoint port is not a number: {uri!r}"
+                ) from None
+
+            if not 0 <= number <= 65535:
+                raise EndpointError(f"tcp endpoint port out of range: {uri!r}")
+
+        return cls(scheme, rest)
+
+    @property
+    def tcp_address(self) -> tuple[str, int]:
+        """Return ``(host, port)`` for a TCP endpoint.
+
+        Raises:
+            ValueError: If this is not a TCP endpoint.
+        """
+
+        if self.scheme != "tcp":
+            raise EndpointError(f"not a tcp endpoint: {self}")
+
+        host, _, port = self.target.rpartition(":")
+        return host, int(port)
+
+    @property
+    def is_loopback(self) -> bool:
+        """Whether a TCP endpoint is confined to this machine.
+
+        Non-loopback TCP carries the shared secret over a plaintext socket, so
+        callers should require TLS or an SSH tunnel for it.
+        """
+
+        if self.scheme != "tcp":
+            return True
+
+        host, _ = self.tcp_address
+        return host in ("127.0.0.1", "::1", "localhost")
+
+    def __str__(self) -> str:
+        """Render the endpoint back as a URI."""
+        return f"{self.scheme}://{self.target}"
+
+
+def default() -> Endpoint:
+    """Return the platform's default endpoint.
+
+    Windows uses a named pipe because asyncio cannot serve AF_UNIX sockets on
+    the proactor event loop, which the service requires for other reasons.
+    """
+
+    if sys.platform == "win32":
+        return Endpoint(
+            "pipe", paths.windows_pipe_name().removeprefix(r"\.\pipe" + "\\")
+        )
+
+    return Endpoint("unix", str(paths.socket_path()))
+
+
+def resolve(uri: str | None = None) -> Endpoint:
+    """Return the endpoint to use.
+
+    Precedence is the explicit argument, then ``PB_ENDPOINT``, then the
+    platform default.
+
+    Args:
+        uri: An explicit endpoint URI, if the caller has one.
+
+    Returns:
+        The endpoint to connect to or listen on.
+    """
+
+    if uri:
+        return Endpoint.parse(uri)
+
+    from_env = os.environ.get(ENDPOINT_ENV_VAR)
+    if from_env:
+        return Endpoint.parse(from_env)
+
+    return default()

pb_core/ipc/backend/__init__.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Per-transport backends, selected by endpoint scheme."""
+
+from __future__ import annotations
+
+import sys
+
+from pb_core.ipc.address import Endpoint
+from pb_core.ipc.backend.provider import IpcBackend, IpcListener, StreamHandler
+
+__all__ = ["IpcBackend", "IpcListener", "StreamHandler", "get_backend"]
+
+
+def get_backend(endpoint: Endpoint) -> IpcBackend:
+    """Return the backend that implements ``endpoint``.
+
+    Backends are imported lazily so that, for example, importing the client on
+    Linux never touches the Windows pipe module.
+
+    Args:
+        endpoint: The endpoint to be connected to or served.
+
+    Returns:
+        A backend for that endpoint's scheme.
+
+    Raises:
+        NotImplementedError: If the scheme is not supported on this platform.
+    """
+
+    if endpoint.scheme == "memory":
+        from pb_core.ipc.backend.memory import MemoryBackend
+
+        return MemoryBackend()
+
+    if endpoint.scheme == "tcp":
+        from pb_core.ipc.backend.tcp import TcpBackend
+
+        return TcpBackend()
+
+    if endpoint.scheme == "pipe":
+        if sys.platform != "win32":
+            raise NotImplementedError("named pipes are only available on Windows")
+
+        from pb_core.ipc.backend.windows import WindowsPipeBackend
+
+        return WindowsPipeBackend()
+
+    if sys.platform == "win32":
+        raise NotImplementedError(
+            "asyncio cannot serve AF_UNIX sockets on the Windows proactor loop; "
+            "use a pipe:// endpoint"
+        )
+
+    from pb_core.ipc.backend.posix import PosixBackend
+
+    return PosixBackend()

pb_core/ipc/backend/_anyio_listener.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Adapter presenting an anyio listener through the :class:`IpcListener` API."""
+
+from __future__ import annotations
+
+from typing import Any, final
+
+from anyio.abc import Listener, TaskGroup
+from typing_extensions import override
+
+from pb_core.ipc.backend.provider import IpcListener, StreamHandler, owned
+
+__all__ = ["AnyioListener"]
+
+
+@final
+class AnyioListener(IpcListener):
+    """Wraps :class:`anyio.abc.Listener` so all backends share one interface."""
+
+    def __init__(self, inner: Listener[Any]) -> None:
+        self._inner = inner
+
+    @override
+    async def serve(self, handler: StreamHandler, task_group: TaskGroup) -> None:
+        await self._inner.serve(owned(handler), task_group)
+
+    @override
+    async def aclose(self) -> None:
+        await self._inner.aclose()

pb_core/ipc/backend/memory.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""An in-process transport, used by the test suite.
+
+Running the whole service and client stack in one process with no OS resources
+makes the integration tests fast and identical on every platform, which leaves
+the real per-platform backends needing only a conformance suite.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
+from typing import ClassVar, final
+
+import anyio
+from anyio.abc import ByteStream, TaskGroup
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from anyio.streams.stapled import StapledObjectStream
+from typing_extensions import override
+
+from pb_core.ipc.address import Endpoint
+from pb_core.ipc.backend.provider import IpcBackend, IpcListener, StreamHandler, owned
+from pb_core.ipc.errors import AddressInUseError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["MemoryBackend"]
+
+_BUFFER = 64
+
+
+@final
+class _MemoryByteStream(ByteStream):
+    """Adapts an object stream of ``bytes`` to the byte-stream interface.
+
+    A byte stream must honour ``max_bytes``, so anything left over from a
+    received chunk is buffered until the next call.
+    """
+
+    def __init__(self, inner: StapledObjectStream[bytes]) -> None:
+        self._inner = inner
+        self._pending = b""
+
+    @override
+    async def receive(self, max_bytes: int = 65536) -> bytes:
+        if not self._pending:
+            self._pending = await self._inner.receive()
+
+        chunk, self._pending = self._pending[:max_bytes], self._pending[max_bytes:]
+        return chunk
+
+    @override
+    async def send(self, item: bytes) -> None:
+        await self._inner.send(item)
+
+    @override
+    async def send_eof(self) -> None:
+        await self._inner.send_eof()
+
+    @override
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+def _pair() -> tuple[ByteStream, ByteStream]:
+    """Create two byte streams connected to each other."""
+    a_tx, b_rx = anyio.create_memory_object_stream[bytes](_BUFFER)
+    b_tx, a_rx = anyio.create_memory_object_stream[bytes](_BUFFER)
+    return (
+        _MemoryByteStream(StapledObjectStream(a_tx, a_rx)),
+        _MemoryByteStream(StapledObjectStream(b_tx, b_rx)),
+    )
+
+
+@final
+class _MemoryListener(IpcListener):
+    """Accepts connections handed over through a queue."""
+
+    def __init__(
+        self,
+        key: str,
+        tx: MemoryObjectSendStream[ByteStream],
+        rx: MemoryObjectReceiveStream[ByteStream],
+    ) -> None:
+        self.key = key
+        self.tx = tx
+        self._rx = rx
+
+    @override
+    async def serve(self, handler: StreamHandler, task_group: TaskGroup) -> None:
+        wrapped = owned(handler)
+
+        async for stream in self._rx:
+            task_group.start_soon(wrapped, stream)
+
+    @override
+    async def aclose(self) -> None:
+        self.tx.close()
+
+        # Close anything accepted but never served, or it leaks on shutdown.
+        with suppress(anyio.WouldBlock, anyio.EndOfStream, anyio.ClosedResourceError):
+            while True:
+                await self._rx.receive_nowait().aclose()
+
+        self._rx.close()
+
+
+@final
+class MemoryBackend(IpcBackend):
+    """A process-global registry of in-process listeners keyed by name."""
+
+    _listeners: ClassVar[dict[str, _MemoryListener]] = {}
+
+    @override
+    def connect(self, endpoint: Endpoint) -> AbstractAsyncContextManager[ByteStream]:
+        return self._do_connect(endpoint)
+
+    @asynccontextmanager
+    async def _do_connect(self, endpoint: Endpoint) -> AsyncGenerator[ByteStream, None]:
+        listener = self._listeners.get(endpoint.target)
+        if listener is None:
+            raise ConnectionRefusedError(f"no listener at {endpoint}")
+
+        client, server = _pair()
+
+        try:
+            listener.tx.send_nowait(server)
+        except (anyio.WouldBlock, anyio.ClosedResourceError, anyio.BrokenResourceError):
+            await client.aclose()
+            await server.aclose()
+            raise ConnectionRefusedError(
+                f"listener at {endpoint} is not accepting"
+            ) from None
+
+        logger.debug("memory: connected to %s", endpoint)
+
+        async with client:
+            yield client
+
+    @override
+    def create_listener(
+        self, endpoint: Endpoint
+    ) -> AbstractAsyncContextManager[IpcListener]:
+        return self._do_listen(endpoint)
+
+    @asynccontextmanager
+    async def _do_listen(self, endpoint: Endpoint) -> AsyncGenerator[IpcListener, None]:
+        if endpoint.target in self._listeners:
+            raise AddressInUseError(f"address already in use: {endpoint}")
+
+        tx, rx = anyio.create_memory_object_stream[ByteStream](_BUFFER)
+        listener = _MemoryListener(endpoint.target, tx, rx)
+        self._listeners[endpoint.target] = listener
+        logger.debug("memory: listening on %s", endpoint)
+
+        try:
+            yield listener
+        finally:
+            del self._listeners[endpoint.target]
+            await listener.aclose()

pb_core/ipc/backend/posix.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""AF_UNIX transport for Linux and macOS.
+
+anyio supports UNIX sockets natively, so this backend is mostly about getting
+the filesystem details right: a private parent directory, mode ``0600`` on the
+socket itself, and safe removal of a socket left behind by a crashed service.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
+from pathlib import Path
+from typing import final
+
+import anyio
+import anyio.to_thread
+from anyio.abc import ByteStream
+from typing_extensions import override
+
+from pb_core import paths
+from pb_core.ipc.address import Endpoint
+from pb_core.ipc.backend._anyio_listener import AnyioListener
+from pb_core.ipc.backend.provider import IpcBackend, IpcListener
+from pb_core.ipc.errors import AddressInUseError, is_address_in_use
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["PosixBackend"]
+
+
+@final
+class PosixBackend(IpcBackend):
+    """AF_UNIX sockets."""
+
+    @override
+    def connect(self, endpoint: Endpoint) -> AbstractAsyncContextManager[ByteStream]:
+        return self._connect(endpoint)
+
+    @asynccontextmanager
+    async def _connect(self, endpoint: Endpoint) -> AsyncGenerator[ByteStream, None]:
+        try:
+            stream = await anyio.connect_unix(endpoint.target)
+        except FileNotFoundError:
+            # No socket file: the service is not running. Callers may start one.
+            raise ConnectionRefusedError(f"no service at {endpoint}") from None
+
+        logger.debug("unix: connected to %s", endpoint)
+
+        async with stream:
+            yield stream
+
+    @override
+    def create_listener(
+        self, endpoint: Endpoint
+    ) -> AbstractAsyncContextManager[IpcListener]:
+        return self._listen(endpoint)
+
+    @asynccontextmanager
+    async def _listen(self, endpoint: Endpoint) -> AsyncGenerator[IpcListener, None]:
+        socket = anyio.Path(endpoint.target)
+        # Blocking stat/mkdir, so off the event loop thread.
+        await anyio.to_thread.run_sync(paths.ensure_private_dir, Path(socket.parent))
+
+        # A socket file on its own says nothing about whether anyone is behind
+        # it, and binding would replace a live service's socket with ours --
+        # leaving it running and unreachable. So ask: a connection that is
+        # accepted is proof, and anything else means the file is debris from a
+        # crash and can go. The service also holds the single-instance lock by
+        # this point, which is the real guard; this is what makes the backend
+        # honest on its own, and what makes "address already in use" mean the
+        # same thing on every transport.
+        if await _is_live(endpoint):
+            raise AddressInUseError(f"address already in use: {endpoint}")
+
+        with suppress(FileNotFoundError):
+            await socket.unlink()
+
+        try:
+            inner = await anyio.create_unix_listener(socket, mode=0o600)
+        except OSError as exc:
+            if is_address_in_use(exc):
+                raise AddressInUseError(f"address already in use: {endpoint}") from exc
+
+            raise
+
+        logger.info("unix: listening on %s", endpoint)
+        listener = AnyioListener(inner)
+
+        try:
+            yield listener
+        finally:
+            await listener.aclose()
+
+            with suppress(FileNotFoundError):
+                await socket.unlink()
+
+
+async def _is_live(endpoint: Endpoint) -> bool:
+    """Whether something is already accepting connections on this socket.
+
+    Args:
+        endpoint: The socket to try.
+
+    Returns:
+        True if a connection was accepted, which only a running service can do.
+    """
+
+    try:
+        stream = await anyio.connect_unix(endpoint.target)
+    except (FileNotFoundError, ConnectionRefusedError, OSError):
+        return False
+
+    await stream.aclose()
+    return True