Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
46 changes: 45 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -268,6 +272,38 @@ interactive() {
verify "$$1" "$$status" "$(filter-out $(GATEWAY_SKIP),$(STEPS))" "$(GATEWAY_SKIP)"
}

# gateway_interactive <name>: 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)"
Expand All @@ -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
53 changes: 51 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -315,7 +363,8 @@ prints `PASS`, `FAIL` or `SKIP` for each; `--forbidden-channel` and `--handle` e
push (`push`): it prints `PUSH <url>` 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 <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

Expand All @@ -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
Expand Down
183 changes: 183 additions & 0 deletions examples/gateway_bridge.py
Original file line number Diff line number Diff line change
@@ -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()
Loading
Loading