mirror of
https://github.com/kuhyx/signal-bot.git
synced 2026-11-21 20:02:22 +01:00
Today the bot was up, healthy and answering nothing for three hours. A host
firewall change (fixed in testsAndMisc 334c0cd9) cut every Docker container
off the internet; signal-cli lost Signal and reconnected in a loop from
15:32:50 onward. Nothing noticed:
- the container's own healthcheck answered 204
- /v1/groups answered 200 out of local state, so discovery saw no change
- the bot's WebSocket to the container stayed OPEN, so the transport's
reconnect logic never fired
- /healthz answered {"status": "ok"} the entire time
The only symptom was silence, which is also what a quiet evening looks like.
signal_bot/liveness.py asks the one question that cannot be answered from a
cache -- GET /v1/devices, which needs a live round trip -- but only after
SILENCE_SECONDS (120) with no frame of any kind, so a busy group costs
nothing and an idle one costs one request per window. Three consecutive
failures and /healthz answers 503 with the reason. Verified end to end in
scripts/e2e.sh against the real process: 503 after 84s with the fake's
connection cut, back to 200 on its own 30s after restoring it.
scripts/signal_api_watchdog.sh + a two-minute user timer do the recovery the
bot cannot do for itself, since a wedged bot cannot restart the container it
depends on. Two tiers, so the steady state costs no Signal round trip at
all: the bot's own /healthz first, the authenticated probe only when that is
not 200. It stops after 3 restarts in 6 hours and escalates instead -- a
deregistered account or a blocked network is not fixable by restarting, and
a restart loop would hide it. Its own bash suite stubs curl and docker and
drives every branch including the give-up cap.
signal_bot/trust.py answers the other half: TRUSTED_INVITERS decides who may
put this bot in a group. The gate sits in GroupDirectory._permitted, which
both _join_pending and _adopt already route through -- gating only invites
would gate the door nobody uses, since prime_profile.sh exists precisely so
that an add becomes a direct join. Evidence is either the group-update
envelope, which is the only frame naming an inviter, or a trusted identity
being a full member in the listing. A refusal is logged once, with that
group's members, so the operator can see which string to add.
verify_allowlist moved to membership.py to keep discovery.py under the
250-line gate; it was already the module that owns MembershipError.
Verified live, by stopping the container by hand and touching nothing else:
18:54:35 docker stop signal-api
18:56:36 liveness: failure 1 of 3 after 123s of silence
18:57:36 failure 3 of 3 -> /healthz answers 503 from 18:57:45
18:58:18 watchdog: probe failed (1/2)
19:00:28 watchdog: probe failed (2/2) -> docker restart signal-api
19:00:36 liveness: receive path recovered after 8 failed probe(s)
19:01:13 watchdog: signal-api is back
Six minutes, unattended, against three hours of silence this afternoon. All
four real groups are still adopted with TRUSTED_INVITERS=+48123456789 set,
and no group was refused.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KbjfWdAyHbCubac7wJKJZW
136 lines
5.0 KiB
Python
136 lines
5.0 KiB
Python
# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
|
|
"""Invited is not joined.
|
|
|
|
Signal only adds an account to a group outright when whoever adds it already
|
|
holds its profile key; otherwise the add becomes a pending invitation. A
|
|
non-member looks perfectly healthy from outside -- the group is listed, the
|
|
websocket is up, /healthz answers -- and not one message ever arrives. This
|
|
module is the part that tells the two states apart and tries to fix the
|
|
second one.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from typing import TYPE_CHECKING, Any, Final
|
|
from urllib.parse import quote
|
|
|
|
import httpx
|
|
|
|
from signal_bot.groups import group_id_aliases
|
|
|
|
if TYPE_CHECKING:
|
|
from signal_bot.config import Config
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
MEMBER_KEY: Final = "member"
|
|
|
|
|
|
class MembershipError(RuntimeError):
|
|
"""Raised when the account is not a full member of a required group."""
|
|
|
|
|
|
def entry_matches(entry: dict[str, Any], group_id: str) -> bool:
|
|
"""True when a /v1/groups row is the group with this id, in any spelling.
|
|
|
|
Args:
|
|
entry: One row of the group listing.
|
|
group_id: The canonical id being looked for.
|
|
|
|
Returns:
|
|
True when the row describes that group.
|
|
"""
|
|
return bool({entry.get("id"), entry.get("internal_id")} & group_id_aliases(group_id))
|
|
|
|
|
|
def find_entry(entries: list[dict[str, Any]], group_id: str) -> dict[str, Any] | None:
|
|
"""Return the listing row for one group, or None when it is absent."""
|
|
return next((entry for entry in entries if entry_matches(entry, group_id)), None)
|
|
|
|
|
|
class JoinAttempts:
|
|
"""Remembers which invitations could not be accepted.
|
|
|
|
signal-cli cannot accept an invite addressed to a phone number at all
|
|
("Cannot find service ID for self"). Without this, the refresh loop would
|
|
retry that same impossible join every 30 seconds forever, logging a
|
|
warning each time and burying anything worth reading.
|
|
"""
|
|
|
|
def __init__(self) -> None:
|
|
"""Start with nothing known to have failed."""
|
|
self._failed: dict[str, str] = {}
|
|
|
|
def has_failed(self, group_id: str) -> bool:
|
|
"""True when joining this group has already been tried and refused."""
|
|
return group_id in self._failed
|
|
|
|
def reason(self, group_id: str) -> str:
|
|
"""Return why the last join attempt for this group failed."""
|
|
return self._failed.get(group_id, "not attempted")
|
|
|
|
def record_failure(self, group_id: str, detail: str) -> None:
|
|
"""Remember that this group could not be joined, and why."""
|
|
self._failed[group_id] = detail
|
|
|
|
def forget(self, group_id: str) -> None:
|
|
"""Drop the memory of a failure, once the group is joined."""
|
|
self._failed.pop(group_id, None)
|
|
|
|
|
|
async def attempt_join(client: httpx.AsyncClient, config: Config, group_id: str) -> str:
|
|
"""Try to accept a pending invitation, reporting what the API said.
|
|
|
|
This never raises. The join endpoint is a best-effort self-heal, and the
|
|
authority on whether it worked is the caller's membership re-check, not
|
|
this response -- returning the outcome as text only keeps it available
|
|
for the error message when the re-check still says non-member.
|
|
|
|
Args:
|
|
client: HTTP client for the REST API.
|
|
config: Resolved runtime configuration.
|
|
group_id: The canonical group id to join.
|
|
|
|
Returns:
|
|
A short description of the attempt.
|
|
"""
|
|
# Percent-encoded: the internal spelling contains '/' and '+', which do
|
|
# not survive being a path segment.
|
|
quoted = quote(group_id, safe="")
|
|
url = f"{config.api_base_url}/v1/groups/{config.phone_number}/{quoted}/join"
|
|
try:
|
|
response = await client.post(url)
|
|
except httpx.HTTPError as exc:
|
|
return f"join request failed: {exc}"
|
|
return f"join returned HTTP {response.status_code}: {response.text.strip()[:200]}"
|
|
|
|
|
|
def verify_allowlist(config: Config, groups: tuple[str, ...], joins: JoinAttempts) -> None:
|
|
"""Refuse to start when GROUP_IDS names a group the bot is not in.
|
|
|
|
Only applies when the operator pinned the bot to specific groups. An
|
|
unpinned bot watches whatever it has been added to, including nothing at
|
|
all, and that is not an error -- it is a bot waiting to be added.
|
|
|
|
Args:
|
|
config: Resolved runtime configuration.
|
|
groups: The groups the bot actually discovered.
|
|
joins: Why a join failed, for the error message.
|
|
|
|
Raises:
|
|
MembershipError: A pinned group is missing or unjoinable.
|
|
"""
|
|
if not config.is_pinned:
|
|
logger.info("watching every group this account is a member of")
|
|
return
|
|
missing = [group_id for group_id in config.group_ids if group_id not in groups]
|
|
if missing:
|
|
details = ", ".join(f"{gid} ({joins.reason(gid)})" for gid in missing)
|
|
msg = (
|
|
f"GROUP_IDS pins the bot to {len(config.group_ids)} group(s) but it is "
|
|
f"not a joined member of: {details}. Have an admin add the bot again now that "
|
|
"it has a profile, or drop the id from GROUP_IDS."
|
|
)
|
|
raise MembershipError(msg)
|