From 701f793206f60a81c2df77d84947a95b85ce1bb8 Mon Sep 17 00:00:00 2001 From: AlexMorbo Date: Tue, 17 Nov 2026 15:00:32 +0300 Subject: [PATCH] feat: support the gateway role with send_notification and notification_acknowledged --- AGENTS.md | 2 + Makefile | 46 +++++- README.md | 53 ++++++- examples/gateway_bridge.py | 183 ++++++++++++++++++++++++ src/muster_bridge/__init__.py | 28 +++- src/muster_bridge/app.py | 104 +++++++++++++- src/muster_bridge/config.py | 80 ++++++++++- src/muster_bridge/events.py | 23 ++- src/muster_bridge/gateway.py | 60 ++++++++ src/muster_bridge/messenger.py | 2 +- src/muster_bridge/problems.py | 1 + src/muster_bridge/store.py | 54 ++++++- tests/conftest.py | 70 +++++++++- tests/test_config.py | 99 ++++++++++++- tests/test_events.py | 129 +++++++++++++++++ tests/test_gateway.py | 247 +++++++++++++++++++++++++++++++++ tests/test_spec.py | 78 ++++++++--- tests/test_store.py | 41 +++++- 18 files changed, 1247 insertions(+), 53 deletions(-) create mode 100644 examples/gateway_bridge.py create mode 100644 src/muster_bridge/gateway.py create mode 100644 tests/test_gateway.py diff --git a/AGENTS.md b/AGENTS.md index 2ed83d2..95cfacc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,9 @@ In this order; an earlier source wins over a later one. | `src/muster_bridge/models.py` | generated from `api/bridge.yaml` by `make generate`; never edited by hand | | `src/muster_bridge/py.typed` | marks the package as typed | | `tests/` | the tests; `conftest.py` holds the shared helpers (the fake clock, the fake messenger, the push callbacks), `test_spec.py` validates every request and answer against the specification with openapi-core | +| `src/muster_bridge/gateway.py` | the role gateway: the protocol `Gateway` and `AcknowledgedNotification` | | `examples/memory_bridge.py` | the example: a bridge whose messenger lives in memory, which the README's quick start shows and `make conformance` runs from the built wheel | +| `examples/gateway_bridge.py` | the example of the role gateway, which the README shows and `make conformance` runs from the built wheel with `--contact` | | `api/` | the specification's copy | | `.github/` | the workflows, Renovate and the pull request template | | `pyproject.toml`, `uv.lock`, `.python-version` | the distribution `muster-bridge`, its dependencies and the tools' settings; the lock of the development tools, never edited by hand; the Python of development and of CI's single-version jobs | diff --git a/Makefile b/Makefile index 98c614c..7039571 100644 --- a/Makefile +++ b/Makefile @@ -25,6 +25,9 @@ RUN1_SKIP := press push $(GATEWAY_SKIP) RUN2_SKIP := buttons user_lookup direct_message delete press push $(GATEWAY_SKIP) RUN1_PASS := $(filter-out $(RUN1_SKIP),$(STEPS)) RUN2_PASS := $(filter-out $(RUN2_SKIP),$(STEPS)) +GATEWAY_FLAGS := --token-file /token --contact +10000000001 +GATEWAY_PASS := info poll answer notification notification_acknowledged +GATEWAY_STEPS_SKIP := $(filter-out $(GATEWAY_PASS),$(STEPS)) # The options of datamodel-code-generator: pydantic v2 models for Python 3.11, with the constraints of the # specification as Field arguments, names from the schemas' paths, the parameters of the operations as models of their @@ -114,7 +117,7 @@ build: ## Build the sdist and the wheel into dist/ ci: lint generate-check spec-check licenses test build ## The checks of a pull request, locally (conformance runs in its own CI job) -conformance: ## Run muster bridge check from MUSTER_IMAGE against examples/memory_bridge.py three times (Linux, Docker) +conformance: ## Run muster bridge check from MUSTER_IMAGE against examples/memory_bridge.py three times and examples/gateway_bridge.py once (Linux, Docker) @sh -c "$$CONFORMANCE_SH" clean: ## Remove bin/, dist/, .venv/, the caches and the coverage data @@ -171,6 +174,7 @@ $(PYTHON3) -m venv "$$dir/venv" || exit 1 "$$dir/venv/bin/python" -I -c 'import muster_bridge, uvicorn; print("muster_bridge", muster_bridge.__version__, "from", muster_bridge.__file__, "uvicorn", uvicorn.__version__)' || exit 1 python=$$dir/venv/bin/python example=$(abspath examples/memory_bridge.py) +gateway_example=$(abspath examples/gateway_bridge.py) $(DOCKER) pull --quiet $(MUSTER_IMAGE) || exit 1 echo "muster image: $$($(DOCKER) image inspect --format '{{index .RepoDigests 0}}' $(MUSTER_IMAGE))" $(DOCKER) run --rm $(MUSTER_IMAGE) version || exit 1 @@ -268,6 +272,38 @@ interactive() { verify "$$1" "$$status" "$(filter-out $(GATEWAY_SKIP),$(STEPS))" "$(GATEWAY_SKIP)" } +# gateway_interactive : run the check against the gateway example with --contact and a person: the person +# acknowledges the notification that the WAIT notification_acknowledged line names through POST /demo/acknowledge. +gateway_interactive() { + $(DOCKER) run --rm --network host -v "$$dir/token:/token:ro" $(MUSTER_IMAGE) bridge check \ + http://$(EXAMPLE_LISTEN) $(GATEWAY_FLAGS) > "$$dir/$$1.out" 2> "$$dir/$$1.err" & + check=$$! + id= + n=0 + while [ "$$n" -lt 1200 ]; do + id=$$(sed -n 's/^WAIT notification_acknowledged: .*, notification_id \(.*\)$$/\1/p' "$$dir/$$1.out") + if [ -n "$$id" ] || ! kill -0 "$$check" 2>/dev/null; then break; fi + n=$$((n + 1)) + sleep 0.1 + done + if [ -n "$$id" ]; then + code=$$($(CURL) -sS -X POST -H 'Content-Type: application/json' \ + -d "$$(printf '{"notification_id":"%s"}' "$$id")" \ + -o "$$dir/$$1.ack" -w '%{http_code}' http://$(EXAMPLE_LISTEN)/demo/acknowledge) + case $$code in + 2??) ;; + *) echo "conformance $$1: the acknowledgement answered $$code: $$(cat "$$dir/$$1.ack" 2>/dev/null)" ;; + esac + else + echo "conformance $$1: no WAIT notification_acknowledged line" + fi + wait "$$check" + status=$$? + check= + cat "$$dir/$$1.out" + verify "$$1" "$$status" "$(GATEWAY_PASS)" "$(GATEWAY_STEPS_SKIP)" +} + echo "== memory 1: every feature, --no-interactive" if start memory-all "$$python" -I "$$example"; then unattended memory-all "$(RUN1_PASS)" "$(RUN1_SKIP)" @@ -293,6 +329,14 @@ else fi stop +echo "== gateway: the gateway example, interactive with --contact" +if start gateway "$$python" -I "$$gateway_example"; then + gateway_interactive gateway +else + failed=1 +fi +stop + exit $$failed endef export CONFORMANCE_SH diff --git a/README.md b/README.md index e7d85cd..8c1dd89 100644 --- a/README.md +++ b/README.md @@ -206,6 +206,54 @@ A few more things to know: every exception it logs; keep anything else secret, such as an event's Account link token, out of the exceptions of your messenger and your store. +## The role gateway + +A bridge can be a Notification gateway: it reaches people outside messengers, by phone call or SMS for example, and +Muster calls it with `sendNotification`. Declare the role and give the bridge its `Gateway`; a bridge whose only role is +`gateway` takes no `Messenger`, and its capabilities stay empty and its `user_lookup` `none`: + +```python +config = Config( + name="my gateway", + version="1.0.0", + messenger_name="My phone provider", + bots=[Bot(name="main", token=token)], + limits=Limits(max_body_length=4000, edit_max_age_seconds=None), + roles=["gateway"], # ["messenger", "gateway"] for a bridge of both, with a Messenger as before + gateway=MyGateway(), +) +bridge = BridgeApp(config) +``` + +1. Implement the protocol `Gateway`: `send_notification(bot, notification)`, which reaches `notification.contact`, reads + out or sends `notification.text` in `notification.language`, and answers `NotificationSent(notification_id=..., + replayed=False)`; and `answer(bot, event, text)`, which shows Muster's answer to the person who acknowledged, + during the call when it is a call. Raise `Invalid` for a contact the provider refuses for good and `Forbidden` for + credentials it refuses. `BridgeApp` raises `ConfigError` when `roles` and what each role needs do not fit. +2. The library keeps the idempotency of the call: a repeated `Idempotency-Key` answers the first `notification_id` + with `replayed` `true` without calling the gateway, and refuses a request beyond the protocol — `action.data` over 64 + bytes, a text over 1,000 code points — as `invalid` before the gateway is called. Neither the contact nor the text + reaches the library's logs or answers. +3. When the person acknowledges, as `notification.action.label` told them, call `await bridge.acknowledge(bot, + notification_id)` with the id `send_notification` answered. It queues `notification_acknowledged` with the + `action.data` of that notification, which the library keeps for 24 hours (`MemoryStore` does; a `Store` of your own + also implements `NotificationStore`), delivered by polling and by push. An id the library did not issue, or a + notification without `action`, raises `UnknownNotificationError`, a `ValueError`. Pass `chat`, such as a call id, + to get it back in `AcknowledgedNotification.chat`. +4. Muster answers the event with `answerEvent` while the person waits, and the library hands it to `Gateway.answer`. + +[`examples/gateway_bridge.py`](https://github.com/muster-io/muster-bridge-python/blob/master/examples/gateway_bridge.py) +is a whole gateway in one file: it prints each notification and acknowledges it from `POST /demo/acknowledge` +`{"notification_id": "n1"}`. Let Muster's check run against it, with a contact, interactively: + +```sh +python examples/gateway_bridge.py --token-file /tmp/bt & +docker run --rm --network host -v /tmp/bt:/token:ro ghcr.io/muster-io/muster:edge bridge check \ + http://127.0.0.1:18095 --token-file /token --contact +10000000001 +# WAIT notification_acknowledged: …, notification_id n1 → in another terminal: +curl -s -X POST -d '{"notification_id":"n1"}' -H 'Content-Type: application/json' 127.0.0.1:18095/demo/acknowledge +``` + ## Mentions of groups and of everyone in the chat A `Mention` of the message names a person (`kind` `user`, which a Mention without `kind` is), a group of the messenger @@ -315,7 +363,8 @@ prints `PASS`, `FAIL` or `SKIP` for each; `--forbidden-channel` and `--handle` e push (`push`): it prints `PUSH ` once its listener (`--push-listen`) is up — point the bridge's push target there, with the secret of `--push-secret-file` — and `WAIT press: …, message_id ` before it waits. `make conformance` plays that person through the example's `POST /demo/press`; do the same in your bridge's tests with your messenger's -own means. +own means. A bridge in the role `gateway` runs the steps `notification` and `notification_acknowledged` instead, with +`--contact`: see _The role gateway_. ## The protocol copy @@ -340,7 +389,7 @@ only entry point; `make help` lists the targets. | `make licenses` | fails on a runtime dependency outside MIT, MIT-0, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, PSF-2.0 and MPL-2.0 | | `make build` | builds the sdist and the wheel into `dist/` | | `make ci` | `lint`, `generate-check`, `spec-check`, `licenses`, `test` and `build`, as a pull request runs them | -| `make conformance` | installs the built wheel and uvicorn into a fresh virtual environment, runs the example from it with `python -I`, and runs `muster bridge check` from `ghcr.io/muster-io/muster:edge` (`MUSTER_IMAGE`) against it three times: every feature, only `thread_messages`, and interactively with push | +| `make conformance` | installs the built wheel and uvicorn into a fresh virtual environment, runs the example from it with `python -I`, and runs `muster bridge check` from `ghcr.io/muster-io/muster:edge` (`MUSTER_IMAGE`) against it three times: every feature, only `thread_messages`, and interactively with push; then runs the check against `examples/gateway_bridge.py` with `--contact`, interactively | | `make clean` | removes `bin/`, `dist/`, `.venv/`, the caches and the coverage data | ## Contributing, security and licence diff --git a/examples/gateway_bridge.py b/examples/gateway_bridge.py new file mode 100644 index 0000000..e6411fb --- /dev/null +++ b/examples/gateway_bridge.py @@ -0,0 +1,183 @@ +# SPDX-License-Identifier: MIT +# Copyright The Muster Authors + +"""A bridge in the role gateway whose phone lives in memory and writes every notification to its log. + +Muster, muster bridge check or a person with curl can try the role without a phone provider: + + printf example-token > /tmp/bt + python examples/gateway_bridge.py --token-file /tmp/bt + +Every notification the bot is asked to send is printed. Outside the protocol it serves +POST /demo/acknowledge {"notification_id"}, which acknowledges that notification as the person called would, by +pressing 1. Unlike the protocol, which needs the token, it has no authentication of its own: the example listens on +loopback by default. +""" + +from __future__ import annotations + +import argparse +import json +import logging +import sys +from dataclasses import dataclass, field +from http import HTTPStatus +from pathlib import Path + +import uvicorn +from starlette.applications import Starlette +from starlette.requests import Request +from starlette.responses import PlainTextResponse, Response +from starlette.routing import Mount, Route + +import muster_bridge +from muster_bridge import ( + AcknowledgedNotification, + Bot, + BridgeApp, + Config, + Limits, + NotificationInput, + NotificationSent, + NotOfferedError, + PushTarget, + UnknownNotificationError, +) + +BOT = "main" +MAX_DEMO_BODY = 64 << 10 + +log = logging.getLogger("gateway_bridge") + + +def read_secret(path: str) -> str: + """Return the token or push secret a file holds, without the white space around it.""" + secret = Path(path).read_text(encoding="utf-8").strip() + if not secret: + raise ValueError("it holds no secret") + return secret + + +def parse_listen(listen: str) -> tuple[str, int]: + """Return the host, without the brackets of an IPv6 address, and the port of --listen.""" + host, _, port = listen.rpartition(":") + if not host or not port.isdigit(): + raise ValueError(f"--listen: {listen!r} is not host:port") + return host.removeprefix("[").removesuffix("]"), int(port) + + +@dataclass +class MemoryPhone: + """Implements Gateway: the notifications it was asked to send, numbered n1, n2 and so on.""" + + sent: dict[str, NotificationInput] = field(default_factory=dict) + last: int = 0 + + async def send_notification(self, bot: str, notification: NotificationInput) -> NotificationSent: + """Print the notification and answer its id.""" + self.last += 1 + notification_id = f"n{self.last}" + self.sent[notification_id] = notification + action = notification.action.label if notification.action else "none" + # The example prints the contact and the text to show the call; a real gateway keeps them out of its logs. + log.info( + "notification sent: bot=%s notification_id=%s contact=%s language=%s action=%r text=%r", + bot, + notification_id, + notification.contact, + notification.language.value, + action, + notification.text, + ) + return NotificationSent(notification_id=notification_id, replayed=False) + + async def answer(self, bot: str, event: AcknowledgedNotification, text: str) -> None: + """Print what Muster says to the person who acknowledged.""" + log.info("answer read out: bot=%s notification_id=%s text=%r", bot, event.notification_id, text) + + async def demo_acknowledge(self, request: Request, bridge: BridgeApp) -> Response: + """Acknowledge a notification: what the person on the phone does by pressing 1.""" + body = bytearray() + async for chunk in request.stream(): + body += chunk + if len(body) > MAX_DEMO_BODY: + return PlainTextResponse("the body is larger than 64 KiB", HTTPStatus.BAD_REQUEST) + try: + ack = json.loads(body) + except ValueError: + ack = None + if not isinstance(ack, dict) or not isinstance(ack.get("notification_id"), str): + return PlainTextResponse('the body is not {"notification_id": …}', HTTPStatus.BAD_REQUEST) + notification_id = ack["notification_id"] + try: + await bridge.acknowledge(BOT, notification_id, chat=f"call-{notification_id}") + except UnknownNotificationError: + return PlainTextResponse( + f"no notification {json.dumps(notification_id)} with an action is kept", HTTPStatus.BAD_REQUEST + ) + except NotOfferedError: + return PlainTextResponse("this bridge does not have the role gateway", HTTPStatus.CONFLICT) + except Exception: + log.exception("the acknowledgement could not be reported") + return PlainTextResponse("the acknowledgement could not be reported", HTTPStatus.INTERNAL_SERVER_ERROR) + log.info("notification acknowledged: bot=%s notification_id=%s", BOT, notification_id) + return Response(status_code=HTTPStatus.NO_CONTENT) + + +def configure(args: argparse.Namespace) -> tuple[Config, MemoryPhone]: + """Return the bridge's Config and its in-memory phone, from the flags.""" + try: + token = read_secret(args.token_file) + except (OSError, ValueError) as error: + raise ValueError(f"--token-file: {error}") from None + if (args.push_url is None) != (args.push_secret_file is None): + raise ValueError("--push-url and --push-secret-file go together") + push = None + if args.push_url is not None: + try: + push = PushTarget(url=args.push_url, secret=read_secret(args.push_secret_file)) + except (OSError, ValueError) as error: + raise ValueError(f"--push-secret-file: {error}") from None + phone = MemoryPhone() + config = Config( + name="muster-bridge-python gateway example", + version=muster_bridge.__version__, + messenger_name="Memory phone", + bots=[Bot(name=BOT, token=token, push=push)], + limits=Limits(max_body_length=4000, edit_max_age_seconds=None), + roles=["gateway"], + gateway=phone, + ) + return config, phone + + +def main() -> None: + """Serve the protocol and /demo/acknowledge until SIGINT or SIGTERM, then stop the server and the pushers.""" + parser = argparse.ArgumentParser(description="A gateway bridge whose phone lives in memory.") + parser.add_argument("--listen", default="127.0.0.1:18095", help="the address to listen on") + parser.add_argument("--token-file", required=True, help="the file that holds the bot's token") + parser.add_argument("--push-url", help="where to push the events, the callback URL of the Bridge Connection") + parser.add_argument("--push-secret-file", help="the file that holds the push secret, whsec_…") + args = parser.parse_args() + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s") + + try: + host, port = parse_listen(args.listen) + config, phone = configure(args) + bridge = BridgeApp(config) + except ValueError as error: + log.error("stopped: %s", error) + sys.exit(2) + + async def demo_acknowledge(request: Request) -> Response: + return await phone.demo_acknowledge(request, bridge) + + app = Starlette( + routes=[Route("/demo/acknowledge", demo_acknowledge, methods=["POST"]), Mount("/", app=bridge)], + lifespan=bridge.lifespan, + ) + uvicorn.run(app, host=host, port=port, log_level="info", timeout_graceful_shutdown=5) + + +if __name__ == "__main__": + main() diff --git a/src/muster_bridge/__init__.py b/src/muster_bridge/__init__.py index 1facf5c..39d8fe4 100644 --- a/src/muster_bridge/__init__.py +++ b/src/muster_bridge/__init__.py @@ -10,7 +10,8 @@ from muster_bridge.app import BridgeApp, ClosedError from muster_bridge.config import Bot, Config, ConfigError, PushTarget -from muster_bridge.events import InvalidEventError, NotOfferedError, UnknownBotError +from muster_bridge.events import InvalidEventError, NotOfferedError, UnknownBotError, UnknownNotificationError +from muster_bridge.gateway import AcknowledgedNotification, Gateway from muster_bridge.mentions import replace_mentions from muster_bridge.messenger import ( Deleter, @@ -35,6 +36,7 @@ DirectMessageInput, DirectMessageSent, InfoEventDelivery, + InfoRole, InfoUserLookup, Layout, LayoutAlerts, @@ -55,17 +57,31 @@ MessageInput, MessageKind, MessagePosted, + NotificationAction, + NotificationInput, + NotificationInputLanguage, + NotificationSent, Person, Status, ThreadReplyInput, ThreadReplyPosted, ) from muster_bridge.problems import BridgeError, Forbidden, Gone, Invalid, RateLimited, Transient -from muster_bridge.store import KeyClaim, KeyState, MemoryStore, Store, StoredAnswer, StoredEvent, UnknownCursorError +from muster_bridge.store import ( + KeyClaim, + KeyState, + MemoryStore, + NotificationStore, + Store, + StoredAnswer, + StoredEvent, + UnknownCursorError, +) __version__ = "0.1.1" __all__ = [ + "AcknowledgedNotification", "AnswerShownShownAs", "Bot", "BridgeApp", @@ -88,8 +104,10 @@ "DirectMessenger", "EventType", "Forbidden", + "Gateway", "Gone", "InfoEventDelivery", + "InfoRole", "InfoUserLookup", "Invalid", "InvalidEventError", @@ -117,6 +135,11 @@ "MessagePosted", "Messenger", "NotOfferedError", + "NotificationAction", + "NotificationInput", + "NotificationInputLanguage", + "NotificationSent", + "NotificationStore", "Person", "PushTarget", "RateLimited", @@ -130,6 +153,7 @@ "Transient", "UnknownBotError", "UnknownCursorError", + "UnknownNotificationError", "UserFinder", "idempotency_key", "replace_mentions", diff --git a/src/muster_bridge/app.py b/src/muster_bridge/app.py index c887dd2..8ecc075 100644 --- a/src/muster_bridge/app.py +++ b/src/muster_bridge/app.py @@ -32,14 +32,17 @@ NotOfferedError, StoredEventError, UnknownBotError, + UnknownNotificationError, WaitError, account_link_token, stop, ) +from muster_bridge.gateway import AcknowledgedNotification from muster_bridge.messenger import bind_idempotency_key, unbind_idempotency_key from muster_bridge.models import ( AnswerInput, AnswerShown, + AnswerShownShownAs, ChannelCheck, CheckChannelParameters, DeleteMessageParameters, @@ -48,10 +51,13 @@ EditMessageParameters, EventBatch, FindUsersParameters, + InfoRole, MessageContent, MessageEdited, MessageInput, MessagePosted, + NotificationInput, + NotificationSent, Person, PersonList, PollEventsParameters, @@ -91,8 +97,10 @@ from starlette.types import Receive, Scope, Send from muster_bridge.config import Clock, Config, PushTarget + from muster_bridge.gateway import Gateway from muster_bridge.messenger import Deleter, DirectMessenger, EventType, Messenger, UserFinder from muster_bridge.models import Button, CapabilitiesButtons + from muster_bridge.store import NotificationStore __all__ = ["BridgeApp", "ClosedError"] @@ -104,6 +112,7 @@ and so about 1.2 MB per request with the body and the layout, which already exceeds 1 MiB; 4 MiB leaves a wide margin. """ MAX_CHANNEL_NAME = 200 +MAX_NOTIFICATION_ID = 512 KEY_CLAIM_TTL = timedelta(minutes=2) KEY_RETENTION = timedelta(hours=24) @@ -157,10 +166,14 @@ def __post_init__(self) -> None: "sendDirectMessage", "POST", "/v1/direct-messages", HTTPStatus.CREATED, DirectMessageSent, idempotent=True ), Operation("answerEvent", "POST", "/v1/answers", HTTPStatus.OK, AnswerShown, idempotent=True), + Operation("sendNotification", "POST", "/v1/notifications", HTTPStatus.CREATED, NotificationSent, idempotent=True), Operation("pollEvents", "GET", "/v1/events", HTTPStatus.OK, EventBatch), ) """The operations of api/bridge.yaml that the library serves.""" +_ROLE_FREE = frozenset({"getInfo", "answerEvent", "pollEvents", "sendNotification"}) +"""The operations a bridge serves whatever its roles are; the others are the messenger's.""" + class ClosedError(RuntimeError): """set_push after aclose.""" @@ -317,24 +330,30 @@ class BridgeApp: It serves every operation of api/bridge.yaml under /v1/ for the bots of its Config and calls the messenger: serve it with an ASGI server such as uvicorn, or mount it under a path of a Starlette or FastAPI application. The bridge - reports what happens in the messenger with press, thread_message, message_deleted and direct_message; the events - wait for pollEvents and are pushed to the bots' push targets. It raises ConfigError for a configuration it refuses, - naming every problem. It runs on the event loop that serves it, and on the next one when that loop ends, as with - Starlette's TestClient without `with`: the loops take turns, never run at once in two threads. The - leading-underscore parameters are for tests. + reports what happens in the messenger with press, thread_message, message_deleted and direct_message, and what + happens to a notification with acknowledge; the events wait for pollEvents and are pushed to the bots' push + targets. A bridge in the role gateway calls Config.gateway, and takes no Messenger when it is only a gateway. It + raises ConfigError for a configuration it refuses, naming every problem. It runs on the event loop that serves it, + and on the next one when that loop ends, as with Starlette's TestClient without `with`: the loops take turns, never + run at once in two threads. The leading-underscore parameters are for tests. """ def __init__( self, config: Config, - messenger: Messenger, + messenger: Messenger | None = None, *, _clock: Clock | None = None, _random: Callable[[int], bytes] | None = None, _transport: httpx.AsyncBaseTransport | None = None, ) -> None: prepared = prepare(config, messenger) - self._messenger = messenger + # None only for a bridge without the role messenger, which never routes an operation that calls it. + self._messenger = cast("Messenger", messenger) + self._has_messenger = messenger is not None + self._gateway: Gateway | None = config.gateway + self._roles = prepared.roles + self._notifications: NotificationStore = cast("NotificationStore", prepared.store) self._info = prepared.info self._info_body = prepared.info_body self._store = prepared.store @@ -359,6 +378,7 @@ def __init__( "findUsers": self._find_users, "sendDirectMessage": self._send_direct_message, "answerEvent": self._answer_event, + "sendNotification": self._send_notification, } self._served = tuple(op for op in OPERATIONS if self._offers(op)) self._bots = frozenset(bot.name for bot in prepared.bots) @@ -473,10 +493,43 @@ async def direct_message( answer_event answers there. Every bridge takes Account link tokens; the rest is as for press. """ self._check_bot(bot) + if InfoRole.messenger not in self._roles: + raise NotOfferedError("direct_message needs the role messenger") token = account_link_token(text) if token is not None: await self._report(bot, "account_link", {"token": token, "user": user}, update_id, at, chat) + async def acknowledge( + self, + bot: str, + notification_id: str, + *, + update_id: str | None = None, + at: datetime | None = None, + chat: str | None = None, + ) -> None: + """Report that the person acknowledged a notification of the bot, as its action told them. + + notification_id is the one Gateway.send_notification answered. The event carries the action.data of that + notification, which the library kept for 24 hours, and the rest is as for press: it returns once the event is + queued, update_id queues an update reported twice once, at is when it happened and chat, such as a call id, + comes back in AcknowledgedNotification.chat when Muster's answer reaches Gateway.answer. If the store failed + to keep the action when the notification was sent, which the library logs without failing the call (a retry + would call the person twice), the notification is unknown here. + + Raises UnknownBotError, NotOfferedError without the role gateway, UnknownNotificationError (a ValueError) + for a notification this library did not issue, no longer keeps or that carried no action, InvalidEventError + for an event that would not match api/bridge.yaml, and what the store raises. + """ + self._check_bot(bot) + if InfoRole.gateway not in self._roles: + raise NotOfferedError("acknowledge needs the role gateway") + data = await self._notifications.find_notification(bot, notification_id, self._clock.now()) + if data is None: + raise UnknownNotificationError("no notification with this id and an action is kept for the bot") + members = {"notification_id": notification_id, "data": data} + await self._report(bot, "notification_acknowledged", members, update_id, at, chat) + def set_push(self, bot: str, target: PushTarget | None) -> None: """Push the events of the bot to target from now on; None stops pushing. @@ -540,6 +593,8 @@ async def _report( def _offers(self, op: Operation) -> bool: capabilities = self._info.capabilities + if op.op_id not in _ROLE_FREE and InfoRole.messenger not in self._roles: + return False if op.op_id == "deleteMessage": return capabilities.delete is not None if op.op_id == "findUsers": @@ -564,6 +619,8 @@ async def _handle(self, request: Request) -> Response | None: "invalid", "This bridge does not serve this operation.", status=HTTPStatus.NOT_FOUND ) op, value = routed + if op.op_id == "sendNotification" and InfoRole.gateway not in self._roles: + return problem_response("invalid", "This bridge does not have the role gateway.") if op.op_id == "getInfo": return _json_response(HTTPStatus.OK, self._info_body) if op.op_id == "pollEvents": @@ -873,6 +930,32 @@ async def _send_direct_message(self, call: _Call) -> object: message = await call.body(DirectMessageInput) return await cast("DirectMessenger", self._messenger).send_direct_message(call.bot, message) + async def _send_notification(self, call: _Call) -> object: + notification = await call.body(NotificationInput) + call.extras += [notification.contact, notification.text] + sent: object = await cast("Gateway", self._gateway).send_notification(call.bot, notification) + action = notification.action + if ( + action is not None + and isinstance(sent, NotificationSent) + and 1 <= len(sent.notification_id) <= MAX_NOTIFICATION_ID + ): + await self._keep_notification(call, sent.notification_id, action.data) + return sent + + async def _keep_notification(self, call: _Call, notification_id: str, data: str) -> None: + """Keep the action data of a sent notification for acknowledge; a failure is logged, as the call was made.""" + until = self._clock.now() + KEY_RETENTION + try: + await self._notifications.save_notification(call.bot, notification_id, data, until) + except Exception as error: + self._log.error( + "cannot keep the action of a notification: operation=%s bot=%s error=%s", + call.op.op_id, + call.bot, + self._redact(describe(error), *call.extras), + ) + async def _answer_event(self, call: _Call) -> object: """Give the messenger the event the answer is for. @@ -890,6 +973,13 @@ async def _answer_event(self, call: _Call) -> object: event, token = found if token is not None: call.extras.append(token) + if isinstance(event, AcknowledgedNotification): + if self._gateway is None: + raise _Refusal("gone", "The bridge does not know this event, or no longer keeps it.") + await self._gateway.answer(call.bot, event, answer.text) + return AnswerShown(shown_as=AnswerShownShownAs.notification, replayed=False) + if not self._has_messenger: + raise _Refusal("gone", "The bridge does not know this event, or no longer keeps it.") shown: object = await self._messenger.answer_event(call.bot, event, answer.text) try: return AnswerShown.model_validate({"shown_as": shown, "replayed": False}) diff --git a/src/muster_bridge/config.py b/src/muster_bridge/config.py index c716f04..cde2caa 100644 --- a/src/muster_bridge/config.py +++ b/src/muster_bridge/config.py @@ -16,13 +16,15 @@ from pydantic import BaseModel, ValidationError -from muster_bridge.models import Capabilities, Info, InfoEventDelivery, InfoUserLookup, Limits +from muster_bridge.models import Capabilities, Info, InfoEventDelivery, InfoRole, InfoUserLookup, Limits from muster_bridge.problems import encode_json, validation_problems -from muster_bridge.store import MemoryStore, Store +from muster_bridge.store import MemoryStore, NotificationStore, Store if TYPE_CHECKING: from collections.abc import Sequence + from muster_bridge.gateway import Gateway + __all__ = ["Bot", "Config", "ConfigError", "PushTarget"] MAX_BODY_LENGTH_CAP = 100_000 @@ -30,6 +32,7 @@ """Opens every push secret; the signing key follows it, in base64.""" _MESSENGER_METHODS = ("post_message", "edit_message", "reply_in_thread", "check_channel", "answer_event") +_GATEWAY_METHODS = ("send_notification", "answer") _SPEC_MISMATCH = "the info this configuration makes does not match api/bridge.yaml: " @@ -73,6 +76,12 @@ class Config: """The optional features; a member left None is a feature the bridge does not offer.""" user_lookup: InfoUserLookup | Literal["email", "login", "username", "user_id", "none"] = "none" """What findUsers searches by.""" + roles: Sequence[InfoRole | Literal["messenger", "gateway"]] = (InfoRole.messenger,) + """What the bridge is: "messenger" needs the Messenger given to BridgeApp, "gateway" needs Config.gateway, and both + make a bridge of both. A bridge whose only role is "gateway" takes no Messenger, and its capabilities stay empty and + its user_lookup "none".""" + gateway: Gateway | None = None + """The calls to the provider of a bridge in the role gateway; None for a bridge without the role.""" event_delivery: Sequence[InfoEventDelivery | Literal["poll", "push"]] | None = None """The event delivery modes the bridge offers; None is both, poll and push.""" link_url_template: str | None = None @@ -135,6 +144,7 @@ class Prepared: logger: logging.Logger poll_offered: bool push_offered: bool + roles: frozenset[InfoRole] def parse_push_target(target: PushTarget) -> tuple[ParsedTarget | None, list[str]]: @@ -202,7 +212,8 @@ def _prune(model: BaseModel, data: dict[str, Any]) -> dict[str, Any]: def prepare(config: Config, messenger: object) -> Prepared: """Check the configuration with its messenger and return it prepared; raise ConfigError naming every problem.""" - problems = _check_messenger(config, messenger) + _check_bots(config) + roles, problems = _check_roles(config, messenger) + problems += _check_bots(config) types = [ f"{name} is not a muster_bridge.{model.__name__}" for name, value, model in ( @@ -216,7 +227,7 @@ def prepare(config: Config, messenger: object) -> Prepared: if types: problems += types else: - info_body, info, info_problems = _build_info(config) + info_body, info, info_problems = _build_info(config, roles) problems += info_problems if problems or info is None: raise ConfigError(problems) @@ -232,6 +243,7 @@ def prepare(config: Config, messenger: object) -> Prepared: logger=config.logger if config.logger is not None else logging.getLogger("muster_bridge"), poll_offered="poll" in info.event_delivery, push_offered="push" in info.event_delivery, + roles=frozenset(roles), ) @@ -239,9 +251,62 @@ def _has_coroutine(messenger: object, name: str) -> bool: return inspect.iscoroutinefunction(getattr(messenger, name, None)) +def _check_roles(config: Config, messenger: object) -> tuple[tuple[InfoRole, ...], list[str]]: + """Return the roles of the configuration and the problems of the roles and of what each needs.""" + problems: list[str] = [] + roles: list[InfoRole] = [] + if isinstance(config.roles, str) or not config.roles: + problems.append("roles is empty: a bridge needs at least one role, messenger or gateway") + else: + for role in config.roles: + try: + parsed = InfoRole(role) + except ValueError: + problems.append(f'roles has {role!r}, which is neither "messenger" nor "gateway"') + continue + if parsed in roles: + problems.append(f'roles has "{parsed.value}" twice') + else: + roles.append(parsed) + kept = frozenset(roles) + if InfoRole.messenger in kept: + problems += _check_messenger(config, messenger) + elif messenger is not None: + problems.append('a messenger is given, but roles lacks "messenger"') + elif kept: + capabilities, lookup = config.capabilities, config.user_lookup + if capabilities != Capabilities() or lookup != "none": + problems.append('a bridge without the role "messenger" offers no capabilities and has user_lookup "none"') + if InfoRole.gateway in kept: + problems += _check_gateway(config) + elif config.gateway is not None: + problems.append('a gateway is given, but roles lacks "gateway"') + return tuple(roles), problems + + +def _check_gateway(config: Config) -> list[str]: + gateway = config.gateway + if gateway is None: + return ['roles has "gateway", which needs Config.gateway, but it is None'] + problems = [] + for name in _GATEWAY_METHODS: + if not hasattr(gateway, name): + problems.append(f"the gateway lacks {name}") + elif not _has_coroutine(gateway, name): + problems.append( + f"{name} of the gateway is not a coroutine function: define it with async def, or mark a wrapper " + "that returns a coroutine with inspect.markcoroutinefunction" + ) + if config.store is not None and not isinstance(config.store, NotificationStore): + problems.append( + "the store lacks save_notification and find_notification (NotificationStore), which a gateway needs" + ) + return problems + + def _check_messenger(config: Config, messenger: object) -> list[str]: if messenger is None: - return ["the messenger is None"] + return ['the messenger is None, which the role "messenger" needs'] problems = [] for name in _MESSENGER_METHODS: if not hasattr(messenger, name): @@ -299,7 +364,7 @@ def _check_bots(config: Config) -> list[str]: return problems -def _build_info(config: Config) -> tuple[bytes, Info | None, list[str]]: +def _build_info(config: Config, roles: tuple[InfoRole, ...]) -> tuple[bytes, Info | None, list[str]]: """Return info as served, and as checked against the specification, or the problems that stop it.""" problems = [] if config.limits.max_body_length > MAX_BODY_LENGTH_CAP: @@ -315,6 +380,9 @@ def _build_info(config: Config) -> tuple[bytes, Info | None, list[str]]: "user_lookup": config.user_lookup, "event_delivery": list(config.event_delivery) if config.event_delivery is not None else ["poll", "push"], } + if roles and roles != (InfoRole.messenger,): + # A messenger-only bridge leaves roles out, as before roles existed, so that an older Muster still reads it. + info["roles"] = [role.value for role in roles] if config.link_url_template is not None: info["link_url_template"] = config.link_url_template try: diff --git a/src/muster_bridge/events.py b/src/muster_bridge/events.py index 920eb0e..1e4636d 100644 --- a/src/muster_bridge/events.py +++ b/src/muster_bridge/events.py @@ -16,6 +16,7 @@ from pydantic import BaseModel, ValidationError from muster_bridge.config import to_json_object +from muster_bridge.gateway import AcknowledgedNotification from muster_bridge.messenger import ReportedEvent from muster_bridge.models import ( AccountLinkEvent, @@ -36,7 +37,7 @@ from muster_bridge.messenger import EventType from muster_bridge.store import Store -__all__ = ["InvalidEventError", "NotOfferedError", "UnknownBotError"] +__all__ = ["InvalidEventError", "NotOfferedError", "UnknownBotError", "UnknownNotificationError"] EVENT_RETENTION = timedelta(hours=24) POLL_BATCH = 100 @@ -49,6 +50,10 @@ class UnknownBotError(LookupError): """A report, or set_push, for a bot that is not in Config.bots.""" +class UnknownNotificationError(ValueError): + """acknowledge for a notification the library did not issue, no longer keeps, or that carried no action.""" + + class NotOfferedError(Exception): """A report of an event that needs a feature the bridge does not offer.""" @@ -268,11 +273,10 @@ async def poll( finally: await stop(sleeper, changed) - async def find(self, bot: str, wanted: str) -> tuple[ReportedEvent, str | None] | None: + async def find(self, bot: str, wanted: str) -> tuple[ReportedEvent | AcknowledgedNotification, str | None] | None: """Return the kept event that answerEvent names, with its Account link token, or None. - None also for a deleted message, which no person caused, and for a gateway's notification_acknowledged, which - this messenger-only library never reports. Raise StoredEventError for a stored body that is not + None also for a deleted message, which no person caused. Raise StoredEventError for a stored body that is not an event's. """ stored = await self._store.find_event(bot, wanted, self._clock.now()) @@ -282,8 +286,17 @@ async def find(self, bot: str, wanted: str) -> tuple[ReportedEvent, str | None] event = Event.model_validate_json(stored.body, strict=True).root except ValidationError: raise StoredEventError("a stored event is not the JSON of an event") from None - if isinstance(event, MessageDeletedEvent | NotificationAcknowledgedEvent): + if isinstance(event, MessageDeletedEvent): return None + if isinstance(event, NotificationAcknowledgedEvent): + acknowledged = AcknowledgedNotification( + id=event.id, + notification_id=event.notification_id, + data=event.data, + chat=stored.chat, + occurred_at=event.occurred_at.astimezone(UTC), + ) + return acknowledged, None reported = ReportedEvent( id=event.id, type=event.type, diff --git a/src/muster_bridge/gateway.py b/src/muster_bridge/gateway.py new file mode 100644 index 0000000..fafc445 --- /dev/null +++ b/src/muster_bridge/gateway.py @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: MIT +# Copyright The Muster Authors + +"""The role gateway: the calls a bridge to a phone or SMS provider implements, and the acknowledgement it reports.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Protocol, runtime_checkable + +if TYPE_CHECKING: + from datetime import datetime + + from muster_bridge.models import NotificationInput, NotificationSent + +__all__ = ["AcknowledgedNotification", "Gateway"] + + +@dataclass(frozen=True, slots=True, kw_only=True) +class AcknowledgedNotification: + """A notification_acknowledged event the bridge reported, as Gateway.answer is given it.""" + + id: str + """The id of the event, which answerEvent names.""" + notification_id: str + """The notification_id that Gateway.send_notification answered.""" + data: str + """The action.data of the notification, unchanged.""" + chat: str | None + """What the bridge passed with the report, such as a call id; it is never sent to Muster.""" + occurred_at: datetime + """When it happened, in UTC.""" + + +@runtime_checkable +class Gateway(Protocol): + """What a bridge in the role gateway implements: the calls to its provider. + + Each method is given the bot whose token Muster sent, by its name in Config.bots. It raises a BridgeError to + answer its class (Invalid for a contact the provider refuses for good, Forbidden for credentials it refuses); any + other exception is answered transient with a generic detail. The library validates every request before it calls + a method and every answer before it sends it. + """ + + async def send_notification(self, bot: str, notification: NotificationInput) -> NotificationSent: + """Reach the person at notification.contact and read out or send notification.text. + + With notification.action the person can acknowledge, as action.label tells them: the bridge then reports it + with BridgeApp.acknowledge, which is valid only once this method has returned: the library keeps the action + when it does. The answer's notification_id names the notification there. Muster's + Idempotency-Key makes a repeated request answer the first result again, without a call to this method. + """ + ... + + async def answer(self, bot: str, event: AcknowledgedNotification, text: str) -> None: + """Show text to the person who acknowledged, during the call when it is a call. + + Muster sends it while the person waits, so a gateway whose person is on the phone reads it out at once. + """ + ... diff --git a/src/muster_bridge/messenger.py b/src/muster_bridge/messenger.py index 8169084..6dca754 100644 --- a/src/muster_bridge/messenger.py +++ b/src/muster_bridge/messenger.py @@ -35,7 +35,7 @@ "idempotency_key", ] -EventType = Literal["press", "thread_message", "account_link", "message_deleted"] +EventType = Literal["press", "thread_message", "account_link", "message_deleted", "notification_acknowledged"] """The type of an event the bridge reports.""" diff --git a/src/muster_bridge/problems.py b/src/muster_bridge/problems.py index 7fdb1e5..e20e953 100644 --- a/src/muster_bridge/problems.py +++ b/src/muster_bridge/problems.py @@ -130,6 +130,7 @@ class Invalid(BridgeError): # noqa: N818 (named after the protocol's class, as "findUsers": frozenset({"invalid", "rate_limited", "transient"}), "sendDirectMessage": frozenset({"invalid", "forbidden", "rate_limited", "transient"}), "answerEvent": frozenset({"invalid", "gone", "rate_limited", "transient"}), + "sendNotification": frozenset({"invalid", "forbidden", "rate_limited", "transient"}), "pollEvents": frozenset({"invalid", "rate_limited", "transient"}), } """The classes each operation declares in api/bridge.yaml, besides 401.""" diff --git a/src/muster_bridge/store.py b/src/muster_bridge/store.py index 1a70852..db60fa2 100644 --- a/src/muster_bridge/store.py +++ b/src/muster_bridge/store.py @@ -13,14 +13,23 @@ from dataclasses import dataclass, field from itertools import count from operator import itemgetter -from typing import TYPE_CHECKING, Protocol +from typing import TYPE_CHECKING, Protocol, runtime_checkable if TYPE_CHECKING: from datetime import datetime from muster_bridge.messenger import EventType -__all__ = ["KeyClaim", "KeyState", "MemoryStore", "Store", "StoredAnswer", "StoredEvent", "UnknownCursorError"] +__all__ = [ + "KeyClaim", + "KeyState", + "MemoryStore", + "NotificationStore", + "Store", + "StoredAnswer", + "StoredEvent", + "UnknownCursorError", +] class KeyState(enum.Enum): @@ -123,6 +132,22 @@ async def find_event(self, bot: str, event_id: str, now: datetime) -> StoredEven ... +@runtime_checkable +class NotificationStore(Protocol): + """Keeps, per bot, the action data of each notification that carried an action, for a bridge in the role gateway. + + A Store that also implements it serves a gateway; MemoryStore does. Config checks it when the role is declared. + """ + + async def save_notification(self, bot: str, notification_id: str, data: str, until: datetime) -> None: + """Keep the action data of the notification, at least until `until`.""" + ... + + async def find_notification(self, bot: str, notification_id: str, now: datetime) -> str | None: + """Return the action data kept for the notification, or None when none is kept or its time ended.""" + ... + + @dataclass(slots=True) class _KeyEntry: """A claim, named by claim_id, or the stored answer of a key.""" @@ -187,10 +212,13 @@ def __init__(self) -> None: self._expiry_order = count() self._claims = count(1) self._queues: dict[str, _Queue] = {} + self._notifications: dict[tuple[str, str], tuple[str, datetime]] = {} + self._notification_expiry: list[tuple[datetime, int, tuple[str, str]]] = [] async def claim_key(self, bot: str, key: str, now: datetime, until: datetime) -> KeyClaim: """See Store.claim_key.""" self._purge_keys(now) + self._purge_notifications(now) entry = self._keys.get((bot, key)) if entry is not None and entry.until > now: if entry.answer is not None: @@ -261,6 +289,28 @@ async def find_event(self, bot: str, event_id: str, now: datetime) -> StoredEven return None return event + async def save_notification(self, bot: str, notification_id: str, data: str, until: datetime) -> None: + """See NotificationStore.save_notification.""" + ref = (bot, notification_id) + self._notifications[ref] = (data, until) + heapq.heappush(self._notification_expiry, (until, next(self._expiry_order), ref)) + + async def find_notification(self, bot: str, notification_id: str, now: datetime) -> str | None: + """See NotificationStore.find_notification.""" + self._purge_notifications(now) + kept = self._notifications.get((bot, notification_id)) + if kept is None or kept[1] <= now: + return None + return kept[0] + + def _purge_notifications(self, now: datetime) -> None: + """Forget the notifications whose time ended; a later save of the same id has its own expiry.""" + while self._notification_expiry and self._notification_expiry[0][0] <= now: + until, _, ref = heapq.heappop(self._notification_expiry) + kept = self._notifications.get(ref) + if kept is not None and kept[1] == until: + del self._notifications[ref] + def _set_key(self, ref: tuple[str, str], entry: _KeyEntry) -> None: self._keys[ref] = entry heapq.heappush(self._key_expiry, (entry.until, next(self._expiry_order), ref)) diff --git a/tests/conftest.py b/tests/conftest.py index dfe9b7c..95a2a1b 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -21,6 +21,7 @@ import pytest from muster_bridge import ( + AcknowledgedNotification, AnswerShownShownAs, Bot, BridgeApp, @@ -42,6 +43,8 @@ MessageEdited, MessageInput, MessagePosted, + NotificationInput, + NotificationSent, Person, PushTarget, ReportedEvent, @@ -304,6 +307,50 @@ async def answer_event(self, bot: str, event: ReportedEvent, text: str) -> Answe return AnswerShownShownAs.thread +@dataclass +class GatewayCall: + """A call of the fake gateway.""" + + method: str + bot: str + notification: NotificationInput | None = None + event: AcknowledgedNotification | None = None + text: str | None = None + key: str | None = field(default_factory=idempotency_key) + + +class FakeGateway: + """Implements Gateway; each call is recorded, and answered by its override or with notifications n1, n2, …""" + + def __init__(self) -> None: + self.calls: list[GatewayCall] = [] + self.send: Callable[[str, NotificationInput], Awaitable[NotificationSent]] | None = None + self.answering: Callable[[str, AcknowledgedNotification, str], Awaitable[None]] | None = None + + def count(self, method: str) -> int: + return sum(1 for call in self.calls if call.method == method) + + async def send_notification(self, bot: str, notification: NotificationInput) -> NotificationSent: + self.calls.append(GatewayCall("send_notification", bot, notification=notification)) + if self.send is not None: + return await self.send(bot, notification) + return NotificationSent(notification_id=f"n{self.count('send_notification')}", replayed=False) + + async def answer(self, bot: str, event: AcknowledgedNotification, text: str) -> None: + self.calls.append(GatewayCall("answer", bot, event=event, text=text)) + if self.answering is not None: + await self.answering(bot, event, text) + + +NOTIFICATION_BODY = '{"contact":"+10000000001","text":"HighErrorRate firing","language":"en"}' +ACTION_BODY = ( + '{"contact":"+10000000001","text":"HighErrorRate firing","language":"ru",' + '"action":{"data":"signed-data-1","label":"Press 1 to acknowledge"}}' +) +ACK_UPDATE = "a1" +BOTH_ROLES = ("messenger", "gateway") + + def all_capabilities() -> Capabilities: """Return the capabilities of every feature.""" return Capabilities( @@ -513,6 +560,7 @@ class Harness: store: Store client: httpx.AsyncClient callbacks: Callbacks + gateway: FakeGateway async def call( self, @@ -558,6 +606,7 @@ async def __call__( messenger: FakeMessenger | None = None, store: Store | None = None, random: Callable[[int], bytes] | None = None, + gateway_only: bool = False, **changes: Any, ) -> Harness: ... @@ -572,14 +621,23 @@ async def make( messenger: FakeMessenger | None = None, store: Store | None = None, random: Callable[[int], bytes] | None = None, + gateway_only: bool = False, **changes: Any, ) -> Harness: + """Make a bridge; gateway_only makes one without a messenger, without capabilities and with only that role.""" messenger = messenger or FakeMessenger() store = store or MemoryStore() + if gateway_only: + changes = {"roles": ("gateway",), "capabilities": Capabilities(), "user_lookup": "none", **changes} + if "gateway" in changes.get("roles", ()): + changes.setdefault("gateway", FakeGateway()) config = make_config(store=store, **changes) - app = BridgeApp(config, messenger, _clock=clock, _random=random, _transport=callbacks.transport) + gateway = config.gateway if isinstance(config.gateway, FakeGateway) else FakeGateway() + app = BridgeApp( + config, None if gateway_only else messenger, _clock=clock, _random=random, _transport=callbacks.transport + ) client = httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://bridge") - made.append(Harness(app, messenger, clock, store, client, callbacks)) + made.append(Harness(app, messenger, clock, store, client, callbacks, gateway)) return made[-1] yield make @@ -658,6 +716,14 @@ async def find_event(self, bot: str, event_id: str, now: datetime) -> StoredEven await self._check("find_event") return await self.inner.find_event(bot, event_id, now) + async def save_notification(self, bot: str, notification_id: str, data: str, until: datetime) -> None: + await self._check("save_notification") + await self.inner.save_notification(bot, notification_id, data, until) + + async def find_notification(self, bot: str, notification_id: str, now: datetime) -> str | None: + await self._check("find_notification") + return await self.inner.find_notification(bot, notification_id, now) + def logged(caplog: pytest.LogCaptureFixture) -> str: """Return the log lines of the test as "LEVEL message".""" diff --git a/tests/test_config.py b/tests/test_config.py index f60f2ca..4ce372e 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -10,7 +10,7 @@ import httpx import pytest -from conftest import TEST_SECRET, TOKEN_MAIN, FakeMessenger, MinimalMessenger, make_config +from conftest import TEST_SECRET, TOKEN_MAIN, FakeGateway, FakeMessenger, MinimalMessenger, make_config import muster_bridge from muster_bridge import ( @@ -24,6 +24,7 @@ CapabilitiesPrivateAnswer, Config, ConfigError, + InfoRole, Limits, MemoryStore, Messenger, @@ -41,10 +42,13 @@ async def get_info(app: BridgeApp, token: str = TOKEN_MAIN) -> httpx.Response: return await client.get("/v1/info", headers={"Authorization": f"Bearer {token}"}) -def refusal(config: Config, messenger: object | None = None) -> str: - """Return the ConfigError of the configuration, with a FakeMessenger unless another messenger is given.""" +DEFAULT: Any = object() + + +def refusal(config: Config, messenger: object = DEFAULT) -> str: + """Return the ConfigError of the configuration, with a FakeMessenger unless another messenger, or None, is given.""" with pytest.raises(ConfigError) as caught: - BridgeApp(config, cast("Messenger", FakeMessenger() if messenger is None else messenger)) + BridgeApp(config, cast("Messenger", FakeMessenger() if messenger is DEFAULT else messenger)) assert str(caught.value) == "\n".join(caught.value.problems) return str(caught.value) @@ -194,7 +198,7 @@ def test_refuses_methods_that_are_not_coroutines() -> None: assert 'user_lookup "login" needs a messenger that implements UserFinder (find_user)' in error assert "the messenger lacks reply_in_thread" not in error with pytest.raises(ConfigError, match="the messenger is None"): - BridgeApp(make_config(), cast("Messenger", None)) + BridgeApp(make_config(), None) def limits(**values: Any) -> Limits: @@ -448,3 +452,88 @@ async def test_group_and_everyone_mentions_are_declared_in_info() -> None: async def test_info_declares_no_group_or_everyone_mentions_by_default() -> None: info = (await get_info(BridgeApp(minimal_config(), MinimalMessenger()), "t")).json() assert info["capabilities"] == {} + + +class NotAsyncGateway: + def send_notification(self, bot: str, notification: object) -> None: ... + + +class StoreWithoutNotifications: + """A Store of a bridge written before gateways: it has no save_notification.""" + + +async def test_roles_default_to_messenger_and_info_leaves_them_out() -> None: + assert Config.__dataclass_fields__["roles"].default == (InfoRole.messenger,) + info = (await get_info(BridgeApp(minimal_config(), MinimalMessenger()), "t")).json() + assert "roles" not in info + explicit = minimal_config(roles=["messenger"]) + assert "roles" not in (await get_info(BridgeApp(explicit, MinimalMessenger()), "t")).json() + + +async def test_info_declares_the_roles() -> None: + both = BridgeApp(minimal_config(roles=("messenger", InfoRole.gateway), gateway=FakeGateway()), MinimalMessenger()) + assert (await get_info(both, "t")).json()["roles"] == ["messenger", "gateway"] + only = BridgeApp(minimal_config(roles=["gateway"], gateway=FakeGateway())) + info = (await get_info(only, "t")).json() + assert info["roles"] == ["gateway"] + assert info["capabilities"] == {} + assert info["user_lookup"] == "none" + assert info["messenger"] == {"name": "Chat"} + + +def test_a_gateway_only_bridge_runs_without_a_messenger() -> None: + app = BridgeApp(minimal_config(roles=["gateway"], gateway=FakeGateway()), None) + assert app._has_messenger is False + + +def test_refuses_the_gateway_role_without_a_gateway() -> None: + error = refusal(minimal_config(roles=["gateway"]), None) + assert error == 'roles has "gateway", which needs Config.gateway, but it is None' + both = refusal(minimal_config(roles=["messenger", "gateway"]), MinimalMessenger()) + assert both == error + + +def test_refuses_the_messenger_role_without_a_messenger() -> None: + assert refusal(minimal_config(), None) == 'the messenger is None, which the role "messenger" needs' + error = refusal(minimal_config(roles=["messenger", "gateway"], gateway=FakeGateway()), None) + assert error == 'the messenger is None, which the role "messenger" needs' + + +def test_refuses_what_a_role_does_not_have() -> None: + assert refusal(minimal_config(roles=["gateway"], gateway=FakeGateway()), MinimalMessenger()) == ( + 'a messenger is given, but roles lacks "messenger"' + ) + assert refusal(minimal_config(gateway=FakeGateway()), MinimalMessenger()) == ( + 'a gateway is given, but roles lacks "gateway"' + ) + capabilities = Capabilities(group_mentions=True) + only = minimal_config(roles=["gateway"], gateway=FakeGateway(), capabilities=capabilities) + assert ( + refusal(only, None) == 'a bridge without the role "messenger" offers no capabilities and has user_lookup "none"' + ) + lookup = minimal_config(roles=["gateway"], gateway=FakeGateway(), user_lookup="login") + assert refusal(lookup, None).startswith('a bridge without the role "messenger"') + + +@pytest.mark.parametrize( + ("roles", "want"), + [ + ([], "roles is empty: a bridge needs at least one role, messenger or gateway"), + ("gateway", "roles is empty: a bridge needs at least one role, messenger or gateway"), + (["messenger", "messenger"], 'roles has "messenger" twice'), + (["voice"], 'roles has \'voice\', which is neither "messenger" nor "gateway"'), + ], +) +def test_refuses_roles(roles: Any, want: str) -> None: + assert want in refusal(minimal_config(roles=roles), MinimalMessenger()).split("\n") + + +def test_refuses_a_gateway_that_is_not_async_or_a_store_without_notifications() -> None: + config = minimal_config(roles=["gateway"], gateway=NotAsyncGateway()) + error = refusal(config, None) + assert "the gateway lacks answer" in error + assert "send_notification of the gateway is not a coroutine function" in error + store = cast("Any", StoreWithoutNotifications()) + error = refusal(minimal_config(roles=["gateway"], gateway=FakeGateway(), store=store), None) + assert error == "the store lacks save_notification and find_notification (NotificationStore), which a gateway needs" + BridgeApp(minimal_config(store=store), MinimalMessenger()) diff --git a/tests/test_events.py b/tests/test_events.py index f0092f2..4a88aab 100644 --- a/tests/test_events.py +++ b/tests/test_events.py @@ -13,11 +13,15 @@ import httpx import pytest from conftest import ( + ACTION_BODY, ALICE, + BOTH_ROLES, LINK_TOKEN, + NOTIFICATION_BODY, START, TOKEN_MAIN, TOKEN_OTHER, + Callbacks, FailingStore, FakeClock, FakeMessenger, @@ -31,9 +35,11 @@ make_config, problem_of, raising, + two_bots, ) from muster_bridge import ( + AcknowledgedNotification, AnswerShownShownAs, BridgeApp, Forbidden, @@ -42,6 +48,7 @@ NotOfferedError, Person, ReportedEvent, + StoredEvent, UnknownBotError, ) from muster_bridge.events import BotSignal, Wakeup, stop @@ -558,3 +565,125 @@ async def test_answer_event_account_link_token_is_redacted(bridge: Harness, capl assert "cannot answer the link [redacted]" in log assert "class=forbidden" in log assert LINK_TOKEN not in log + + +async def test_acknowledge_queues_notification_acknowledged_with_the_action_data(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(roles=BOTH_ROLES) + at = datetime(2026, 10, 18, 9, 0, tzinfo=UTC) + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + await bridge.app.acknowledge("main", "n1", update_id="a1", at=at, chat="call-7") + await bridge.app.acknowledge("main", "n1", update_id="a1") + polled = await bridge.poll("?wait=0") + (event,) = polled.events + assert event == { + "id": event_id_of("main", "notification_acknowledged", "a1"), + "type": "notification_acknowledged", + "occurred_at": "2026-10-18T09:00:00Z", + "notification_id": "n1", + "data": "signed-data-1", + } + assert (await bridge.poll("?wait=0", token=TOKEN_OTHER)).events == [] + + +async def test_acknowledge_is_pushed(make_bridge: MakeBridge, callbacks: Callbacks) -> None: + callback = callbacks.add() + bridge = await make_bridge(bots=two_bots(main=callback.target()), roles=BOTH_ROLES) + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + await bridge.app.acknowledge("main", "n1") + pushed = json.loads((await callback.next()).body) + assert (pushed["type"], pushed["notification_id"], pushed["data"]) == ( + "notification_acknowledged", + "n1", + "signed-data-1", + ) + + +async def test_acknowledge_of_an_unknown_notification_raises_a_value_error(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(roles=BOTH_ROLES) + await bridge.call("POST", "/v1/notifications", key="k1", body=NOTIFICATION_BODY) + for notification_id in ("n1", "nobody"): + with pytest.raises(ValueError, match="no notification"): + await bridge.app.acknowledge("main", notification_id) + assert (await bridge.poll("?wait=0")).events == [] + + +async def test_acknowledge_with_a_time_zone_less_time_is_invalid(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + with pytest.raises(InvalidEventError): + await bridge.app.acknowledge("main", "n1", at=datetime(2026, 10, 18, 9, 0)) + + +async def test_answer_event_reaches_the_gateway(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + at = datetime(2026, 10, 18, 9, 0, tzinfo=UTC) + await bridge.app.acknowledge("main", "n1", update_id="a1", at=at, chat="call-7") + event_id = event_id_of("main", "notification_acknowledged", "a1") + response = await bridge.call("POST", "/v1/answers", key="k2", body=answer_body(event_id)) + assert response.status_code == 200 + assert response.text == '{"shown_as":"notification","replayed":false}' + first, second = bridge.gateway.calls + assert first.method == "send_notification" + assert (second.method, second.bot, second.text, second.key) == ("answer", "main", "Done", "k2") + assert second.event == AcknowledgedNotification( + id=event_id, notification_id="n1", data="signed-data-1", chat="call-7", occurred_at=at + ) + replayed = await bridge.call("POST", "/v1/answers", key="k2", body=answer_body(event_id)) + assert replayed.json() == {"shown_as": "notification", "replayed": True} + assert bridge.gateway.count("answer") == 1 + + +async def test_answer_event_of_both_roles_goes_to_the_role_of_the_event(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(roles=BOTH_ROLES) + press_id = await bridge.report_press("u1") + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + await bridge.app.acknowledge("main", "n1", update_id="a1") + assert (await bridge.call("POST", "/v1/answers", key="k2", body=answer_body(press_id))).status_code == 200 + ack = event_id_of("main", "notification_acknowledged", "a1") + assert (await bridge.call("POST", "/v1/answers", key="k3", body=answer_body(ack))).status_code == 200 + assert (bridge.messenger.count("answer_event"), bridge.gateway.count("answer")) == (1, 1) + + +async def test_answer_event_of_a_gateway_in_error(make_bridge: MakeBridge, caplog: pytest.LogCaptureFixture) -> None: + bridge = await make_bridge(gateway_only=True) + await bridge.call("POST", "/v1/notifications", key="k1", body=ACTION_BODY) + await bridge.app.acknowledge("main", "n1", update_id="a1") + event_id = event_id_of("main", "notification_acknowledged", "a1") + bridge.gateway.answering = raising(Gone("The call has ended.")) + response = await bridge.call("POST", "/v1/answers", key="k2", body=answer_body(event_id)) + assert problem_of(response, 404, "gone")["detail"] == "The call has ended." + bridge.gateway.answering = raising(RuntimeError("the line dropped")) + problem_of(await bridge.call("POST", "/v1/answers", key="k3", body=answer_body(event_id)), 500, "transient") + assert "the line dropped" in logged(caplog) + + +async def test_a_gateway_without_the_role_messenger_reports_no_messenger_event(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + with pytest.raises(NotOfferedError): + await bridge.app.direct_message("main", user=ALICE, text=LINK_TOKEN) + with pytest.raises(NotOfferedError): + await bridge.app.press("main", message_id="m1", user=ALICE, data="d") + assert (await bridge.poll("?wait=0")).events == [] + + +async def test_a_messenger_event_in_the_store_of_a_gateway_is_gone(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + event = {"id": "e1", "type": "message_deleted", "occurred_at": "2026-10-18T09:00:00Z", "message_id": "m1"} + press = {**event, "type": "press", "user": json.loads(ALICE_JSON), "data": "d"} + stored = StoredEvent(id="e1", type="press", body=json.dumps(press).encode(), chat=None, until=START + timedelta(1)) + await bridge.store.append_event("main", stored, START) + response = await bridge.call("POST", "/v1/answers", key="k1", body=answer_body("e1")) + assert problem_of(response, 404, "gone")["detail"] == GONE + + +async def test_a_stored_acknowledgement_of_a_bridge_without_the_gateway_is_gone(make_bridge: MakeBridge) -> None: + bridge = await make_bridge() + ack = {"id": "e1", "type": "notification_acknowledged", "occurred_at": "2026-10-18T09:00:00Z"} + ack |= {"notification_id": "n1", "data": "d"} + stored = StoredEvent( + id="e1", type="notification_acknowledged", body=json.dumps(ack).encode(), chat=None, until=START + timedelta(1) + ) + await bridge.store.append_event("main", stored, START) + response = await bridge.call("POST", "/v1/answers", key="k1", body=answer_body("e1")) + assert problem_of(response, 404, "gone")["detail"] == GONE diff --git a/tests/test_gateway.py b/tests/test_gateway.py new file mode 100644 index 0000000..b1ce41e --- /dev/null +++ b/tests/test_gateway.py @@ -0,0 +1,247 @@ +# SPDX-License-Identifier: MIT +# Copyright The Muster Authors + +import json +from typing import Any + +import pytest +from conftest import ( + ACTION_BODY, + BOTH_ROLES, + NOTIFICATION_BODY, + TOKEN_OTHER, + FailingStore, + MakeBridge, + logged, + problem_of, + raising, +) + +from muster_bridge import ( + Forbidden, + Invalid, + NotificationInputLanguage, + NotificationSent, + NotOfferedError, + RateLimited, + UnknownBotError, + UnknownNotificationError, +) +from muster_bridge.problems import DETAIL_MESSENGER + +pytestmark = pytest.mark.anyio + +NOTIFY = "/v1/notifications" + + +def body(**changes: Any) -> str: + """Return a notification request with the members changed; a member set to None is left out.""" + notification: dict[str, Any] = json.loads(ACTION_BODY) + notification.update(changes) + return json.dumps({name: value for name, value in notification.items() if value is not None}) + + +async def test_send_notification_reaches_the_gateway(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(roles=BOTH_ROLES) + gateway = bridge.gateway + response = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + assert response.status_code == 201 + assert response.text == '{"notification_id":"n1","replayed":false}' + (call,) = gateway.calls + assert (call.bot, call.key) == ("main", "k1") + notification = call.notification + assert notification is not None + assert (notification.contact, notification.text) == ("+10000000001", "HighErrorRate firing") + assert notification.language is NotificationInputLanguage.ru + assert notification.action is not None + assert (notification.action.data, notification.action.label) == ("signed-data-1", "Press 1 to acknowledge") + + +async def test_send_notification_without_an_action(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + response = await bridge.call("POST", NOTIFY, key="k1", body=NOTIFICATION_BODY) + assert response.status_code == 201 + (call,) = bridge.gateway.calls + assert call.notification is not None + assert call.notification.action is None + with pytest.raises(UnknownNotificationError): + await bridge.app.acknowledge("main", "n1") + + +async def test_send_notification_is_idempotent(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + first = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + again = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + other = await bridge.call("POST", NOTIFY, key="k2", body=ACTION_BODY) + assert first.json() == {"notification_id": "n1", "replayed": False} + assert again.status_code == 201 + assert again.json() == {"notification_id": "n1", "replayed": True} + assert other.json() == {"notification_id": "n2", "replayed": False} + assert bridge.gateway.count("send_notification") == 2 + assert (await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY, token=TOKEN_OTHER)).json()[ + "notification_id" + ] == "n3" + + +@pytest.mark.parametrize("key", [None, "", "has space", "k" * 256]) +async def test_send_notification_needs_an_idempotency_key(make_bridge: MakeBridge, key: str | None) -> None: + bridge = await make_bridge(gateway_only=True) + problem_of(await bridge.call("POST", NOTIFY, key=key, body=ACTION_BODY), 400, "invalid") + assert bridge.gateway.calls == [] + + +@pytest.mark.parametrize( + ("request_body", "reason"), + [ + (body(action={"data": "x" * 65, "label": "l"}), "/action/data"), + (body(action={"data": "d" * 64, "label": "l"}), None), + (body(action={"data": "bad data", "label": "l"}), "/action/data"), + (body(action={"data": "", "label": "l"}), "/action/data"), + (body(action={"data": "d", "label": ""}), "/action/label"), + (body(text="é" * 1000), None), + (body(text="é" * 1001), "/text"), + (body(text=""), "/text"), + (body(contact="1" * 201), "/contact"), + (body(contact=""), "/contact"), + (body(language="de"), "/language"), + (body(language=None), "/language"), + ('{"contact":"c"', "body"), + ("[]", "body"), + ], +) +async def test_send_notification_refuses_what_the_specification_refuses( + make_bridge: MakeBridge, request_body: str, reason: str | None +) -> None: + bridge = await make_bridge(gateway_only=True) + response = await bridge.call("POST", NOTIFY, key="k1", body=request_body) + if reason is None: + assert response.status_code == 201 + return + problem = problem_of(response, 400, "invalid") + assert reason in problem["detail"] + assert bridge.gateway.calls == [] + + +async def test_a_bridge_without_the_role_refuses_the_call(make_bridge: MakeBridge) -> None: + bridge = await make_bridge() + response = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + assert problem_of(response, 400, "invalid")["detail"] == "This bridge does not have the role gateway." + assert bridge.gateway.calls == [] + problem_of(await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY, token="wrong"), 401, "forbidden") + + +async def test_a_gateway_without_the_role_messenger_serves_no_messenger_operation(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + for method, path in ( + ("POST", "/v1/messages"), + ("PATCH", "/v1/messages/m1"), + ("DELETE", "/v1/messages/m1"), + ("POST", "/v1/messages/m1/thread-replies"), + ("POST", "/v1/channels/alerts/check"), + ("GET", "/v1/users?handle=alice"), + ("POST", "/v1/direct-messages"), + ): + response = await bridge.call(method, path, key="k1", body="{}") + problem_of(response, 404, "invalid") + assert (await bridge.call("GET", "/v1/info")).status_code == 200 + assert (await bridge.call("GET", "/v1/events?wait=0")).status_code == 200 + assert (await bridge.call("POST", "/v1/answers", key="k1", body='{"event_id":"e","text":"t"}')).status_code == 404 + + +@pytest.mark.parametrize( + ("error", "status", "error_class"), + [ + (Invalid("The contact cannot be called."), 400, "invalid"), + (Forbidden("The provider refused the credentials."), 403, "forbidden"), + (RateLimited("Slow down.", retry_after=2, scope="bot"), 429, "rate_limited"), + (RuntimeError("the provider's socket broke"), 500, "transient"), + ], +) +async def test_the_gateways_errors_are_answered_by_class( + make_bridge: MakeBridge, error: BaseException, status: int, error_class: str +) -> None: + bridge = await make_bridge(gateway_only=True) + bridge.gateway.send = raising(error) + response = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + problem = problem_of(response, status, error_class) + if error_class == "transient": + assert problem["detail"] == DETAIL_MESSENGER + else: + assert problem["detail"] == error.detail # type: ignore[attr-defined] + bridge.gateway.send = None + assert (await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY)).json()["replayed"] is False + + +async def test_the_contact_and_the_text_never_reach_the_answer_or_the_log( + make_bridge: MakeBridge, caplog: pytest.LogCaptureFixture +) -> None: + bridge = await make_bridge(gateway_only=True) + for key, error, status in ( + ("k1", Invalid("cannot call +10000000001"), 400), + ("k2", RuntimeError("cannot read out HighErrorRate firing to +10000000001"), 500), + ): + bridge.gateway.send = raising(error) + response = await bridge.call("POST", NOTIFY, key=key, body=ACTION_BODY) + assert response.status_code == status + assert "+10000000001" not in response.text + assert "HighErrorRate" not in response.text + log = logged(caplog) + assert "messenger call failed" in log + assert "+10000000001" not in log + assert "HighErrorRate" not in log + + +async def test_an_answer_that_is_not_a_notification_sent_is_transient( + make_bridge: MakeBridge, caplog: pytest.LogCaptureFixture +) -> None: + bridge = await make_bridge(gateway_only=True) + + async def wrong(*_: object) -> Any: + return NotificationSent.model_construct(notification_id="", replayed=False) + + bridge.gateway.send = wrong + problem = problem_of(await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY), 500, "transient") + assert problem["detail"] == DETAIL_MESSENGER + assert "does not match api/bridge.yaml" in logged(caplog) + with pytest.raises(UnknownNotificationError): + await bridge.app.acknowledge("main", "") + + +async def test_the_action_is_kept_for_24_hours(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + await bridge.call("POST", NOTIFY, key="k2", body=ACTION_BODY) + bridge.clock.advance(24 * 3600 - 1) + await bridge.app.acknowledge("main", "n1") + bridge.clock.advance(1) + with pytest.raises(UnknownNotificationError): + await bridge.app.acknowledge("main", "n2") + with pytest.raises(UnknownNotificationError): + await bridge.app.acknowledge("other", "n1") + + +async def test_a_store_that_cannot_keep_the_action_does_not_fail_the_call( + make_bridge: MakeBridge, caplog: pytest.LogCaptureFixture +) -> None: + store = FailingStore() + store.fail("save_notification", RuntimeError("down +10000000001")) + bridge = await make_bridge(store=store, gateway_only=True) + response = await bridge.call("POST", NOTIFY, key="k1", body=ACTION_BODY) + assert response.status_code == 201 + assert "cannot keep the action of a notification" in logged(caplog) + assert "+10000000001" not in logged(caplog) + with pytest.raises(UnknownNotificationError): + await bridge.app.acknowledge("main", "n1") + store.fail("save_notification", None) + store.fail("find_notification", RuntimeError("down")) + with pytest.raises(RuntimeError, match="down"): + await bridge.app.acknowledge("main", "n1") + + +async def test_acknowledge_needs_the_role_and_a_bot(make_bridge: MakeBridge) -> None: + messenger_only = await make_bridge() + with pytest.raises(NotOfferedError): + await messenger_only.app.acknowledge("main", "n1") + gateway = await make_bridge(gateway_only=True) + with pytest.raises(UnknownBotError): + await gateway.app.acknowledge("nobody", "n1") diff --git a/tests/test_spec.py b/tests/test_spec.py index 8e16227..dd3a402 100644 --- a/tests/test_spec.py +++ b/tests/test_spec.py @@ -11,21 +11,27 @@ import httpx import pytest from conftest import ( + ACK_UPDATE, + ACTION_BODY, ALICE, + BOTH_ROLES, DM_BODY, EDIT_BODY, LINK_TOKEN, + NOTIFICATION_BODY, POST_BODY, REPLY_BODY, TOKEN_MAIN, Callbacks, FailingStore, + FakeGateway, FakeMessenger, Harness, MakeBridge, all_capabilities, answer_body, event_id_of, + problem_of, raising, two_bots, with_body, @@ -44,6 +50,7 @@ CapabilitiesPrivateAnswer, Forbidden, Gone, + InfoRole, Invalid, KeyClaim, KeyState, @@ -73,10 +80,13 @@ CHECK = "/v1/channels/alerts/check" USERS = "/v1/users" DM = "/v1/direct-messages" +NOTIFY = "/v1/notifications" ANSWERS = "/v1/answers" EVENTS = "/v1/events" ANSWER = answer_body(event_id_of("main", "press", "u1")) """The body of an answer to the press reported before every answerEvent exchange.""" +ANSWER_NOTIFICATION = answer_body(event_id_of("main", "notification_acknowledged", ACK_UPDATE)) +"""The body of an answer to a notification_acknowledged that its exchange's setup reports.""" def spec_operations() -> dict[str, tuple[str, str, dict[str, Any]]]: @@ -145,6 +155,12 @@ async def every_event(bridge: Harness, _: FailingStore) -> None: await app.message_deleted("main", update_id="5", message_id="m1") +async def acknowledged(bridge: Harness, _: FailingStore) -> None: + sent = await bridge.call("POST", NOTIFY, key="k0", body=ACTION_BODY) + assert sent.status_code == 201, sent.text + await bridge.app.acknowledge("main", sent.json()["notification_id"], update_id=ACK_UPDATE) + + @dataclass(frozen=True) class Exchange: """One request of an operation and the status its answer must have.""" @@ -236,6 +252,26 @@ class Exchange: Exchange("answerEvent", "404", "POST", ANSWERS, 404, answer_body("nope")), Exchange("answerEvent", "429", "POST", ANSWERS, 429, ANSWER, error=limited), Exchange("answerEvent", "500", "POST", ANSWERS, 500, ANSWER, error=broken), + Exchange("answerEvent", "200 notification", "POST", ANSWERS, 200, ANSWER_NOTIFICATION, setup=acknowledged), + Exchange("sendNotification", "201", "POST", NOTIFY, 201, NOTIFICATION_BODY), + Exchange("sendNotification", "201 action", "POST", NOTIFY, 201, ACTION_BODY), + Exchange("sendNotification", "201 replayed", "POST", NOTIFY, 201, ACTION_BODY, setup=replay(NOTIFY, ACTION_BODY)), + Exchange("sendNotification", "400 spec", "POST", NOTIFY, 400, "{}", invalid=True), + Exchange( + "sendNotification", + "400 text", + "POST", + NOTIFY, + 400, + NOTIFICATION_BODY.replace("HighErrorRate", "x" * 1001), + invalid=True, + ), + Exchange("sendNotification", "400 contact", "POST", NOTIFY, 400, NOTIFICATION_BODY, error=invalid), + Exchange("sendNotification", "401", "POST", NOTIFY, 401, NOTIFICATION_BODY, token="wrong"), + Exchange("sendNotification", "403", "POST", NOTIFY, 403, NOTIFICATION_BODY, error=forbidden), + Exchange("sendNotification", "429", "POST", NOTIFY, 429, NOTIFICATION_BODY, error=limited), + Exchange("sendNotification", "500", "POST", NOTIFY, 500, NOTIFICATION_BODY, error=broken), + Exchange("sendNotification", "500 running", "POST", NOTIFY, 500, NOTIFICATION_BODY, setup=running_key), Exchange("pollEvents", "200 every event", "GET", EVENTS + "?wait=0", 200, setup=every_event), Exchange("pollEvents", "200 empty", "GET", EVENTS + "?wait=0", 200), Exchange("pollEvents", "400 cursor", "GET", EVENTS + "?cursor=x", 400), @@ -285,16 +321,8 @@ def test_the_copy_is_the_3_1_document_under_mit() -> None: assert DOCUMENT["info"]["license"]["identifier"] == "MIT" -GATEWAY_OPERATIONS = frozenset({"sendNotification"}) -"""The operations of the role gateway, which this messenger-only library does not serve.""" - - def test_every_operation_of_the_specification_is_routed() -> None: - spec = sorted( - f"{method} {path} {op_id}" - for op_id, (method, path, _) in spec_operations().items() - if op_id not in GATEWAY_OPERATIONS - ) + spec = sorted(f"{method} {path} {op_id}" for op_id, (method, path, _) in spec_operations().items()) table = sorted(f"{op.method} {op.template} {op.op_id}" for op in OPERATIONS) assert spec == table assert set(DECLARED) == {op.op_id for op in OPERATIONS} @@ -302,8 +330,6 @@ def test_every_operation_of_the_specification_is_routed() -> None: def test_declared_classes_match_the_specification() -> None: for op_id, (_, _, operation) in spec_operations().items(): - if op_id in GATEWAY_OPERATIONS: - continue statuses = set(operation["responses"]) unknown = {s for s in statuses if s not in STATUS_CLASS and s != "401" and not s.startswith("2")} assert not unknown, f"{op_id} declares {unknown}, which no class has" @@ -322,8 +348,9 @@ def test_every_operation_has_an_exchange() -> None: async def test_requests_and_answers_match_the_specification(make_bridge: MakeBridge, exchange: Exchange) -> None: store = FailingStore() messenger = FakeMessenger() - bridge = await make_bridge(messenger=messenger, store=store) - if exchange.op == "answerEvent": + gateway = FakeGateway() + bridge = await make_bridge(messenger=messenger, store=store, roles=BOTH_ROLES, gateway=gateway) + if exchange.op == "answerEvent" and exchange.setup is None: await bridge.report_press("u1") if exchange.setup is not None: await exchange.setup(bridge, store) @@ -331,18 +358,27 @@ async def test_requests_and_answers_match_the_specification(make_bridge: MakeBri failure = raising(exchange.error()) for name in ("post", "edit", "reply", "check", "answer", "find", "dm", "delete"): setattr(messenger, name, failure) + gateway.send = failure key = "k1" if exchange.op in IDEMPOTENT else None response = await bridge.call(exchange.method, exchange.path, token=exchange.token, key=key, body=exchange.body) assert response.status_code == exchange.status, response.text check_exchange(exchange.op, response, valid_request=not exchange.invalid and exchange.token == TOKEN_MAIN) -async def test_info_claims_no_gateway_role_and_notifications_are_not_served(make_bridge: MakeBridge) -> None: +async def test_info_claims_no_role_and_notifications_are_refused_by_a_messenger(make_bridge: MakeBridge) -> None: bridge = await make_bridge() info = (await bridge.call("GET", "/v1/info")).json() assert "roles" not in info - response = await bridge.call("POST", "/v1/notifications", key="k1", body="{}") - assert response.status_code == 404 + response = await bridge.call("POST", NOTIFY, key="k1", body=NOTIFICATION_BODY) + problem_of(response, 400, "invalid") + check_exchange("sendNotification", response, valid_request=True) + + +async def test_info_of_a_gateway_matches_the_specification(make_bridge: MakeBridge) -> None: + bridge = await make_bridge(gateway_only=True) + response = await bridge.call("GET", "/v1/info") + assert response.json()["roles"] == [InfoRole.gateway] + check_exchange("getInfo", response, valid_request=True) async def test_info_with_every_member_matches_the_specification(make_bridge: MakeBridge) -> None: @@ -354,6 +390,7 @@ async def test_info_with_every_member_matches_the_specification(make_bridge: Mak bridge = await make_bridge( capabilities=capabilities, link_url_template="https://chat.example.org/bots/muster?start={token}", + roles=BOTH_ROLES, limits=Limits( max_body_length=100_000, edit_max_age_seconds=172800, @@ -372,6 +409,7 @@ async def test_info_with_every_member_matches_the_specification(make_bridge: Mak "user_lookup", "event_delivery", "link_url_template", + "roles", } assert len(info["capabilities"]) == len(type(capabilities).model_fields) assert len(info["limits"]) == len(Limits.model_fields) @@ -407,15 +445,17 @@ class Push: async def test_pushes_match_the_webhook(make_bridge: MakeBridge, callbacks: Callbacks) -> None: callback = callbacks.add() - bridge = await make_bridge(bots=two_bots(main=callback.target())) + bridge = await make_bridge(bots=two_bots(main=callback.target()), roles=BOTH_ROLES) await every_event(bridge, FailingStore()) types = set() - for _ in range(5): + await bridge.call("POST", NOTIFY, key="k0", body=ACTION_BODY) + await bridge.app.acknowledge("main", "n1") + for _ in range(6): pushed = await callback.next() headers = Headers(list(pushed.headers.items())) SPEC.validate_webhook_request(Push(pushed.body, RequestParameters(header=headers))) types.add(json.loads(pushed.body)["type"]) - assert types == {"press", "thread_message", "account_link", "message_deleted"} + assert types == {"press", "thread_message", "account_link", "message_deleted", "notification_acknowledged"} async def test_a_push_without_its_signature_does_not_match(make_bridge: MakeBridge, callbacks: Callbacks) -> None: diff --git a/tests/test_store.py b/tests/test_store.py index 406412f..228e26a 100644 --- a/tests/test_store.py +++ b/tests/test_store.py @@ -7,7 +7,15 @@ import pytest from conftest import START -from muster_bridge import KeyClaim, KeyState, MemoryStore, StoredAnswer, StoredEvent, UnknownCursorError +from muster_bridge import ( + KeyClaim, + KeyState, + MemoryStore, + NotificationStore, + StoredAnswer, + StoredEvent, + UnknownCursorError, +) from muster_bridge.store import _Queue pytestmark = pytest.mark.anyio @@ -223,3 +231,34 @@ def test_queue_find_of_a_number_not_queued() -> None: queue.events.append((2, stored_event("e2", NOW))) assert queue.find(1) is None assert queue.find(3) is None + + +async def test_notifications_are_kept_until_their_time_ends() -> None: + store = MemoryStore() + assert isinstance(store, NotificationStore) + await store.save_notification("main", "n1", "data-1", NOW + RETENTION) + await store.save_notification("main", "n2", "data-2", NOW + timedelta(hours=1)) + await store.save_notification("other", "n1", "data-other", NOW + RETENTION) + assert await store.find_notification("main", "n1", NOW) == "data-1" + assert await store.find_notification("other", "n1", NOW) == "data-other" + assert await store.find_notification("main", "nobody", NOW) is None + assert await store.find_notification("main", "n2", NOW + timedelta(minutes=59)) == "data-2" + assert await store.find_notification("main", "n2", NOW + timedelta(hours=1)) is None + assert await store.find_notification("main", "n1", NOW + RETENTION - timedelta(seconds=1)) == "data-1" + assert await store.find_notification("main", "n1", NOW + RETENTION) is None + assert store._notifications == {} + + +async def test_a_notification_saved_again_is_kept_by_its_last_time() -> None: + store = MemoryStore() + await store.save_notification("main", "n1", "old", NOW + timedelta(hours=1)) + await store.save_notification("main", "n1", "new", NOW + RETENTION) + assert await store.find_notification("main", "n1", NOW + timedelta(hours=2)) == "new" + + +async def test_claims_forget_notifications_whose_time_ended() -> None: + store = MemoryStore() + await store.save_notification("main", "n1", "data-1", NOW + timedelta(hours=1)) + await claim(store, "main", "k1", NOW + timedelta(hours=2), KeyState.CLAIMED) + assert store._notifications == {} + assert store._notification_expiry == []