customrp-core 0.1.2__py3-none-any.whl

customrp_core/__init__.py

@@ -0,0 +1,35 @@
+"""customrp-core: the platform-independent parts of CustomRP, as a library.
+
+Build a :class:`Presence`, then either turn it into a payload with :func:`build_activity` and send it
+with :class:`DiscordIPC`, or let :class:`PresenceSession` handle connecting, retrying and resending.
+"""
+
+__version__ = "0.1.2"
+
+from .errors import AssetsError, CustomRPError, PresenceError, PresetError  # noqa: E402
+from .ipc import DiscordIPC, display_name, ipc_paths, open_transport  # noqa: E402
+from .presence import (  # noqa: E402
+    DEFAULT_APPLICATION_ID,
+    MAX_LENGTH,
+    Activity,
+    ActivityType,
+    Button,
+    Issue,
+    Presence,
+    StatusDisplay,
+    TimestampMode,
+    build_activity,
+    check,
+    normalize,
+    validate,
+)
+from .preset import dump_preset, load_preset, parse_preset, save_preset  # noqa: E402
+from .session import PresenceSession, SessionState  # noqa: E402
+
+__all__ = [
+    "Activity", "ActivityType", "AssetsError", "Button", "CustomRPError", "DEFAULT_APPLICATION_ID",
+    "DiscordIPC", "Issue", "MAX_LENGTH", "Presence", "PresenceError", "PresenceSession", "PresetError",
+    "SessionState", "StatusDisplay", "TimestampMode", "build_activity", "check", "display_name",
+    "dump_preset", "ipc_paths", "load_preset", "normalize", "open_transport", "parse_preset",
+    "save_preset", "validate",
+]

customrp_core/assets.py

@@ -0,0 +1,64 @@
+"""Looking up the art assets uploaded to a Discord application.
+
+CustomRP fills its image dropdowns from the same public endpoint; it needs no token.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+from . import __version__
+from .errors import AssetsError
+
+ASSETS_URL = "https://discord.com/api/oauth2/applications/{}/assets"
+ASSETS_PAGE_URL = "https://discord.com/developers/applications/{}/rich-presence/assets"
+
+
+@dataclass(frozen=True)
+class Asset:
+    id: str
+    name: str
+    #: Discord's asset type number, passed through as is (CustomRP doesn't use it)
+    type: int
+
+
+def _check_id(application_id: str):
+    if not (application_id.isdigit() and application_id.isascii()):
+        raise AssetsError(f"{application_id!r} isn't a valid application ID")
+
+
+def assets_page_url(application_id: str) -> str:
+    """The Developer Portal page where the application's assets are managed."""
+    _check_id(application_id)
+    return ASSETS_PAGE_URL.format(application_id)
+
+
+def fetch_assets(application_id: str, *, timeout: float = 10.0) -> list[Asset]:
+    """Fetches the list of assets uploaded to an application. Raises :class:`AssetsError` on failure."""
+    _check_id(application_id)
+    request = urllib.request.Request(ASSETS_URL.format(application_id),
+                                     headers={"User-Agent": f"customrp-core/{__version__}"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            data = json.load(response)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            raise AssetsError(f"There's no application with the ID {application_id}") from e
+        raise AssetsError(f"Discord answered with HTTP {e.code} {e.reason}") from e
+    except (urllib.error.URLError, OSError) as e:
+        reason = getattr(e, "reason", e)
+        raise AssetsError(f"Couldn't reach Discord: {reason}") from e
+    except ValueError as e:
+        raise AssetsError("Discord sent something that isn't JSON") from e
+
+    return parse_assets(data)
+
+
+def parse_assets(data) -> list[Asset]:
+    if not isinstance(data, list):
+        raise AssetsError("Unexpected answer from Discord")
+    return [Asset(str(item.get("id", "")), str(item.get("name", "")), int(item.get("type", 0) or 0))
+            for item in data if isinstance(item, dict)]

customrp_core/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions raised by customrp-core."""
+
+from __future__ import annotations
+
+
+class CustomRPError(Exception):
+    """Base class for every error this library raises on purpose."""
+
+
+class PresenceError(CustomRPError, ValueError):
+    """A presence can't be sent as it is.
+
+    ``field`` names the :class:`~customrp_core.presence.Presence` attribute at fault
+    (for example ``"large_image"`` or ``"button1.url"``), or is ``None`` when the problem
+    isn't tied to one field.
+    """
+
+    def __init__(self, message: str, field: str | None = None):
+        super().__init__(f"{field}: {message}" if field else message)
+        self.message = message
+        self.field = field
+
+
+class PresetError(CustomRPError):
+    """A ``.crp`` preset file can't be read or written."""
+
+
+class AssetsError(CustomRPError):
+    """The list of an application's art assets couldn't be fetched."""

customrp_core/ipc.py

@@ -0,0 +1,337 @@
+"""A minimal Discord RPC client speaking the local IPC protocol.
+
+Discord listens on a Unix domain socket (Linux, macOS) or a named pipe (Windows) called
+``discord-ipc-N`` with N from 0 to 9. Every message is a frame: a little-endian int32 opcode,
+a little-endian int32 payload length, then a UTF-8 JSON payload.
+
+All socket I/O happens on one worker thread. That matters on Windows, where a blocking read
+on a synchronous pipe handle would also block writes to it from another thread.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import queue
+import select
+import socket
+import struct
+import sys
+import threading
+import time
+import uuid
+
+OP_HANDSHAKE = 0
+OP_FRAME = 1
+OP_CLOSE = 2
+OP_PING = 3
+OP_PONG = 4
+
+HEADER = struct.Struct("<ii")
+MAX_PAYLOAD = 64 * 1024 * 1024
+
+log = logging.getLogger("customrp_core.ipc")
+
+
+# --- Transports ----------------------------------------------------------------
+
+class SocketTransport:
+    """A connected stream socket (a Unix socket in practice, any socket in tests)."""
+
+    def __init__(self, sock: socket.socket):
+        self.sock = sock
+
+    def send(self, data: bytes):
+        self.sock.sendall(data)
+
+    def poll(self, timeout: float) -> bool:
+        readable, _, _ = select.select([self.sock], [], [], timeout)
+        return bool(readable)
+
+    def recv(self, size: int) -> bytes:
+        chunks = []
+        while size > 0:
+            chunk = self.sock.recv(size)
+            if not chunk:
+                raise ConnectionError("Discord closed the connection")
+            chunks.append(chunk)
+            size -= len(chunk)
+        return b"".join(chunks)
+
+    def close(self):
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+
+
+class PipeTransport:
+    """A Windows named pipe opened in synchronous mode; polling is done with PeekNamedPipe."""
+
+    def __init__(self, path: str):
+        import ctypes
+        import msvcrt
+        from ctypes import wintypes
+
+        self.file = open(path, "r+b", buffering=0)
+        self.handle = msvcrt.get_osfhandle(self.file.fileno())
+        self._ctypes = ctypes
+        self._peek = ctypes.windll.kernel32.PeekNamedPipe
+        self._peek.argtypes = [wintypes.HANDLE, wintypes.LPVOID, wintypes.DWORD,
+                               wintypes.LPVOID, ctypes.POINTER(wintypes.DWORD), wintypes.LPVOID]
+        self._peek.restype = wintypes.BOOL
+        self._available = wintypes.DWORD()
+
+    def send(self, data: bytes):
+        self.file.write(data)
+
+    def poll(self, timeout: float) -> bool:
+        deadline = time.monotonic() + timeout
+        while True:
+            if not self._peek(self.handle, None, 0, None, self._ctypes.byref(self._available), None):
+                raise ConnectionError("Discord closed the connection")
+            if self._available.value:
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.02)
+
+    def recv(self, size: int) -> bytes:
+        chunks = []
+        while size > 0:
+            chunk = self.file.read(size)
+            if not chunk:
+                raise ConnectionError("Discord closed the connection")
+            chunks.append(chunk)
+            size -= len(chunk)
+        return b"".join(chunks)
+
+    def close(self):
+        try:
+            self.file.close()
+        except OSError:
+            pass
+
+
+def _unix_candidate_dirs():
+    bases = []
+    for var in ("XDG_RUNTIME_DIR", "TMPDIR", "TMP", "TEMP"):
+        value = os.environ.get(var)
+        if value and value not in bases:
+            bases.append(value)
+    if sys.platform == "darwin":
+        # Discord uses the per-user temporary folder, which is $TMPDIR in a login session.
+        # Programs started by launchd may not have TMPDIR set, so also ask the system.
+        try:
+            user_tmp = os.confstr("CS_DARWIN_USER_TEMP_DIR")
+        except (ValueError, OSError, AttributeError):
+            user_tmp = None
+        if user_tmp and user_tmp.rstrip("/") not in (b.rstrip("/") for b in bases):
+            bases.append(user_tmp)
+    if "/tmp" not in bases:
+        bases.append("/tmp")
+
+    # Sandboxed clients put the socket in a subdirectory
+    subdirs = ["", "app/com.discordapp.Discord", "app/com.discordapp.DiscordCanary",
+               "app/com.discordapp.DiscordPTB", "snap.discord", "snap.discord-canary",
+               ".flatpak/dev.vencord.Vesktop/xdg-run", "app/dev.vencord.Vesktop"]
+
+    for base in bases:
+        for sub in subdirs:
+            yield os.path.join(base, sub) if sub else base
+
+
+def ipc_paths(pipe: int):
+    """Possible locations of Discord's IPC endpoint. ``pipe`` of -1 means "try 0 to 9"."""
+    numbers = range(10) if pipe < 0 else [pipe]
+
+    if sys.platform == "win32":
+        for n in numbers:
+            yield rf"\\.\pipe\discord-ipc-{n}"
+        return
+
+    for n in numbers:
+        for directory in _unix_candidate_dirs():
+            yield os.path.join(directory, f"discord-ipc-{n}")
+
+
+def connect_path(path: str):
+    """Opens one IPC endpoint: a named pipe on Windows, a Unix socket elsewhere."""
+    if sys.platform == "win32":
+        return PipeTransport(path)
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        sock.connect(path)
+    except OSError:
+        sock.close()
+        raise
+    return SocketTransport(sock)
+
+
+def open_transport(pipe: int = -1):
+    """Connects to the first Discord IPC endpoint that accepts a connection.
+
+    Raises :class:`ConnectionError` when none does, which usually means Discord isn't running.
+    """
+    errors = []
+
+    for path in ipc_paths(pipe):
+        if sys.platform != "win32" and not os.path.exists(path):
+            continue
+        try:
+            transport = connect_path(path)
+        except OSError as e:
+            errors.append(f"{path}: {e}")
+            continue
+
+        log.info("Connected to %s", path)
+        return transport
+
+    raise ConnectionError("Couldn't find a running Discord client" + (" (" + "; ".join(errors[-3:]) + ")" if errors else ""))
+
+
+# --- Client --------------------------------------------------------------------
+
+class DiscordIPC:
+    """A Rich Presence connection to the Discord client.
+
+    The connection runs on a background thread, and all the ``on_*`` callbacks are invoked
+    from that thread:
+
+    * ``on_ready(user)`` - handshake succeeded; ``user`` is Discord's user object
+    * ``on_presence_update(activity)`` - Discord accepted a SET_ACTIVITY call
+    * ``on_error(code, message)`` - Discord rejected something or closed the connection on purpose
+    * ``on_connection_failed(message)`` - couldn't connect, or the connection dropped
+    """
+
+    def __init__(self, client_id: str, pipe: int = -1, *, on_ready=None, on_presence_update=None,
+                 on_error=None, on_connection_failed=None, transport_factory=open_transport):
+        self.client_id = client_id
+        self.pipe = pipe
+        self.user = None
+
+        self.on_ready = on_ready or (lambda user: None)
+        self.on_presence_update = on_presence_update or (lambda activity: None)
+        self.on_error = on_error or (lambda code, message: None)
+        self.on_connection_failed = on_connection_failed or (lambda message: None)
+
+        self._transport_factory = transport_factory
+        self._outgoing = queue.Queue()
+        self._stop = threading.Event()
+        self._thread = None
+
+    # Public API
+
+    def start(self):
+        self._thread = threading.Thread(target=self._run, name="discord-ipc", daemon=True)
+        self._thread.start()
+
+    def set_activity(self, activity):
+        """Queues a presence update; it's sent as soon as the handshake is done."""
+        self._outgoing.put({
+            "cmd": "SET_ACTIVITY",
+            "args": {"pid": os.getpid(), "activity": activity},
+            "nonce": str(uuid.uuid4()),
+        })
+
+    def close(self):
+        """Stops the connection. Callbacks won't fire after this returns."""
+        self._stop.set()
+        if self._thread and self._thread is not threading.current_thread():
+            self._thread.join(timeout=2)
+
+    @property
+    def closed(self) -> bool:
+        return self._stop.is_set()
+
+    # Worker thread
+
+    def _run(self):
+        transport = None
+        try:
+            transport = self._transport_factory(self.pipe)
+            self._send(transport, OP_HANDSHAKE, {"v": 1, "client_id": self.client_id})
+
+            while not self._stop.is_set():
+                if self.user is not None:
+                    self._flush(transport)
+
+                if transport.poll(0.1):
+                    if not self._handle(transport, *self._read(transport)):
+                        break
+        except (OSError, ConnectionError, ValueError) as e:
+            if not self._stop.is_set():
+                log.debug("Connection failed: %s", e)
+                self.on_connection_failed(str(e))
+        finally:
+            if transport is not None:
+                transport.close()
+            log.debug("Connection closed")
+
+    def _flush(self, transport):
+        while True:
+            try:
+                payload = self._outgoing.get_nowait()
+            except queue.Empty:
+                return
+            self._send(transport, OP_FRAME, payload)
+
+    def _send(self, transport, op, payload):
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        log.debug("-> op %d %s", op, data.decode("utf-8"))
+        transport.send(HEADER.pack(op, len(data)) + data)
+
+    def _read(self, transport):
+        op, length = HEADER.unpack(transport.recv(HEADER.size))
+        if not 0 <= length <= MAX_PAYLOAD:
+            raise ValueError(f"Bad frame length {length}")
+        data = transport.recv(length) if length else b"{}"
+        log.debug("<- op %d %s", op, data.decode("utf-8", "replace"))
+        return op, json.loads(data)
+
+    def _handle(self, transport, op, payload) -> bool:
+        """Processes a frame; returns False if the connection should end."""
+        if self._stop.is_set():
+            return False
+
+        if op == OP_PING:
+            self._send(transport, OP_PONG, payload)
+            return True
+
+        if op == OP_CLOSE:
+            code = payload.get("code", 0)
+            message = payload.get("message", "Connection closed by Discord")
+            log.debug("Closed by Discord: %s %s", code, message)
+            self.on_error(code, message)
+            return False
+
+        if op != OP_FRAME:
+            return True
+
+        cmd = payload.get("cmd")
+        evt = payload.get("evt")
+        data = payload.get("data") or {}
+
+        if evt == "ERROR":
+            code = data.get("code", 0)
+            message = data.get("message", "Unknown error")
+            log.debug("Error %s: %s", code, message)
+            self.on_error(code, message)
+        elif cmd == "DISPATCH" and evt == "READY":
+            self.user = data.get("user") or {}
+            self.on_ready(self.user)
+        elif cmd == "SET_ACTIVITY":
+            self.on_presence_update(data)
+
+        return True
+
+
+def display_name(user: dict) -> str:
+    """A user's name as Discord shows it: ``name``, or ``name#1234`` for legacy accounts."""
+    name = user.get("username", "")
+    discriminator = user.get("discriminator")
+    if discriminator and discriminator != "0":
+        return f"{name}#{discriminator}"
+    return name