signal-bot/signal_bot/transport_rest.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Transport adapter for bbernhard/signal-cli-rest-api.

Receive is a WebSocket, which the container only exposes when it runs in one
of the json-rpc modes; in normal/native mode the same path silently degrades
to a polling GET, so the mode is verified at startup rather than assumed.
"""

from __future__ import annotations

import asyncio
import logging
from collections.abc import AsyncIterator, Awaitable, Callable
from typing import TYPE_CHECKING, Any, Final

from websockets.asyncio.client import connect as ws_connect
from websockets.exceptions import WebSocketException

if TYPE_CHECKING:
    import httpx

    from signal_bot.config import Config
    from signal_bot.quoting import Quote

logger = logging.getLogger(__name__)

INITIAL_BACKOFF: Final = 1.0
MAX_BACKOFF: Final = 30.0
# Exactly this mode. See verify_mode for why "json-rpc-native" is not enough.
REQUIRED_MODE: Final = "json-rpc"
BACKOFF_FACTOR: Final = 2.0
_OK_STATUSES: Final = frozenset({200, 201, 204})
# A body is only expected from a plain 200; the others carry none.
_HTTP_OK: Final = 200

Connector = Callable[[str], Any]
Sleeper = Callable[[float], Awaitable[None]]


class TransportError(RuntimeError):
    """Raised when the Signal REST API rejects a request."""


class RestTransport:
    """Talks to the signal-cli-rest-api container over REST plus a WebSocket."""

    def __init__(
        self,
        config: Config,
        client: httpx.AsyncClient,
        *,
        connector: Connector | None = None,
        sleeper: Sleeper | None = None,
        max_reconnects: int | None = None,
    ) -> None:
        """Wire the adapter to its config and its injectable I/O.

        Args:
            config: Resolved runtime configuration.
            client: HTTP client used for every REST call.
            connector: WebSocket connect callable. Injected by the tests.
            sleeper: Async sleep used for reconnect backoff.
            max_reconnects: Stop after this many reconnects. None means forever.
        """
        self._config = config
        self._client = client
        self._connect = connector if connector is not None else ws_connect
        self._sleep = sleeper if sleeper is not None else asyncio.sleep
        self._max_reconnects = max_reconnects

    async def verify_mode(self) -> str:
        """Return the container's mode, raising unless it exposes a WebSocket.

        Raises:
            TransportError: The container is not running a json-rpc mode.
        """
        response = await self._client.get(self._config.about_url)
        response.raise_for_status()
        body = response.json()
        mode = str(body.get("mode", "")) if isinstance(body, dict) else ""
        if mode != REQUIRED_MODE:
            msg = (
                f"signal-cli-rest-api is running in mode {mode!r}, not "
                f"{REQUIRED_MODE!r}. 'normal' exposes no receive WebSocket at "
                "all, and 'json-rpc-native' is a GraalVM build with no AWT, so "
                'every attachment send fails with "Can\'t load library: awt" '
                "while text replies keep working. Recreate the container with "
                f"MODE={REQUIRED_MODE}."
            )
            raise TransportError(msg)
        return mode

    async def receive(self) -> AsyncIterator[str]:
        """Yield raw envelope frames, reconnecting with backoff when dropped."""
        backoff = INITIAL_BACKOFF
        reconnects = 0
        while True:
            try:
                async with self._connect(self._config.receive_url) as socket:
                    backoff = INITIAL_BACKOFF
                    async for frame in socket:
                        yield frame if isinstance(frame, str) else frame.decode()
            except (WebSocketException, OSError) as exc:
                logger.warning("signal websocket dropped: %s", exc)
            if self._max_reconnects is not None and reconnects >= self._max_reconnects:
                return
            reconnects += 1
            await self._sleep(backoff)
            backoff = min(backoff * BACKOFF_FACTOR, MAX_BACKOFF)

    async def _post_send(self, payload: dict[str, Any]) -> None:
        """POST one send payload and raise unless the API accepted it."""
        response = await self._client.post(self._config.send_url, json=payload)
        if response.status_code not in _OK_STATUSES:
            msg = f"send failed with HTTP {response.status_code}: {response.text}"
            raise TransportError(msg)

    async def send_text(self, text: str, recipient: str, quote: Quote | None = None) -> None:
        """Send a plain-text message, optionally quoting one message."""
        payload: dict[str, Any] = {
            "message": text,
            "number": self._config.phone_number,
            "recipients": [recipient],
        }
        if quote is not None:
            payload.update(quote.payload())
        await self._post_send(payload)

    async def send_image(
        self,
        image_base64: str,
        recipient: str,
        quote: Quote | None = None,
        caption: str = "",
    ) -> None:
        """Send an image attachment, captioned in the same payload.

        Verified against the container on 2026-08-30: a non-empty "message"
        alongside base64_attachments comes back as one timestamp, so Signal
        renders it as a single captioned photo rather than two messages.
        """
        await self.send_media(image_base64, recipient, quote, caption)

    async def send_media(
        self,
        payload_base64: str,
        recipient: str,
        quote: Quote | None = None,
        caption: str = "",
        media_type: str = "",
        filename: str = "",
    ) -> None:
        """Send one attachment, naming its type when the caller knows it.

        The data-URI spelling is the container's own, read off its
        /swagger/doc.json rather than remembered: api.SendMessageV2 documents
        base64_attachments as accepting bare base64,
        "data:<MIME-TYPE>;base64,<DATA>" or
        "data:<MIME-TYPE>;filename=<FILENAME>;base64,<DATA>". With no type
        the bare form goes out, byte for byte what send_image always sent.
        """
        attachment = payload_base64
        if media_type:
            named = f"filename={filename};" if filename else ""
            attachment = f"data:{media_type};{named}base64,{payload_base64}"
        payload: dict[str, Any] = {
            "message": caption,
            "base64_attachments": [attachment],
            "number": self._config.phone_number,
            "recipients": [recipient],
        }
        if quote is not None:
            payload.update(quote.payload())
        await self._post_send(payload)

    async def list_attachments(self) -> list[str]:
        """Return the ids of attachments stored server-side."""
        response = await self._client.get(self._config.attachments_url)
        response.raise_for_status()
        body = response.json()
        if not isinstance(body, list):
            return []
        return [str(item) for item in body]

    async def fetch_attachment(self, attachment_id: str) -> bytes:
        """Download one stored attachment by id.

        Raises:
            TransportError: The container refused or does not have it.
        """
        response = await self._client.get(f"{self._config.attachments_url}/{attachment_id}")
        if response.status_code != _HTTP_OK:
            msg = f"attachment fetch failed with HTTP {response.status_code}"
            raise TransportError(msg)
        return bytes(response.content)

    async def delete_attachment(self, attachment_id: str) -> None:
        """Delete one stored attachment by id."""
        response = await self._client.delete(f"{self._config.attachments_url}/{attachment_id}")
        if response.status_code not in _OK_STATUSES:
            msg = f"attachment delete failed with HTTP {response.status_code}"
            raise TransportError(msg)