signal-bot/signal_bot/membership.py
Krzysztof kuhy Rudnicki d5c63b423b feat: refuse to look healthy while deaf, and heal the container by itself
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
2026-08-29 19:01:55 +02:00

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)