signal-bot/signal_bot/transport_rest.py
Krzysztof kuhy Rudnicki e3c7bbfe23 !good bot: thank the asker with an emoji on their message, not a reply
A compliment gets a reaction drawn from a small warm set (❤️ 🥰 😊 👍 🎉 🙏
😸) put on the compliment itself, and nothing in the group -- the one
answer that adds no line. Same cooldown as every other command.

The transport learns reactions: send_reaction on the Protocol, POST
/v1/reactions/<number> on the REST adapter with the four fields
api.SendReactionRequest requires (204 back), a recorded list on the fake.
CommandContext.react() names the target the way a quote does, and falls
back to the emoji as text for an envelope with no timestamp, so a shape
this bot has never seen is visible rather than swallowed.

The fake container gains the endpoint, strict about the schema, and
records reactions in order with the sends; a scenario can now expect
{kind: reaction, quotes: true}. First two-word trigger: fold() keeps the
inner space and the registry matches whole text first, so "!good bot"
resolves and "!good" does not; one-word spellings cover a double space.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-04 21:48:03 +02:00

223 lines
8.6 KiB
Python

# 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(self, url: str, payload: dict[str, Any], what: str) -> None:
"""POST one payload and raise unless the API accepted it."""
response = await self._client.post(url, json=payload)
if response.status_code not in _OK_STATUSES:
msg = f"{what} failed with HTTP {response.status_code}: {response.text}"
raise TransportError(msg)
async def _post_send(self, payload: dict[str, Any]) -> None:
await self._post(self._config.send_url, payload, "send")
async def send_reaction(
self, emoji: str, recipient: str, target_author: str, timestamp: int
) -> None:
"""React to one message; the container answers 204 with no body.
Field names are api.SendReactionRequest's from /swagger/doc.json,
all four required there -- which is why the caller resolves the
target the way a quote is resolved and sends nothing when it cannot.
"""
payload = {
"reaction": emoji,
"recipient": recipient,
"target_author": target_author,
"timestamp": timestamp,
}
await self._post(self._config.reactions_url, payload, "reaction")
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)