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
57 changes: 54 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ or with the package installed beside uvicorn (`pip install muster-bridge uvicorn
It listens on `127.0.0.1:18095` (`--listen`), knows the channels `alerts` and `ops` (`--channels`) and the people
`alice` and `bob` (`--users`), and offers every feature of the protocol, or only those that `BRIDGE_FEATURES` lists:
`buttons`, `thread_messages`, `direct_messages` (which also turns on `user_lookup` `login`), `private_answers`,
`native_mentions`, `quiet_messages`, `status_color`, `deletion_events` and `delete`. With `--push-url` and
`--push-secret-file` it pushes its events as well. In another terminal:
`native_mentions`, `group_mentions`, `everyone_mentions`, `quiet_messages`, `status_color`, `deletion_events` and
`delete`. With `--push-url` and `--push-secret-file` it pushes its events as well. In another terminal:

```sh
curl -s -o /dev/null -w '%{http_code}\n' 127.0.0.1:18095/v1/info # 401: no token
Expand Down Expand Up @@ -179,7 +179,8 @@ reach Muster late.
`UnknownBotError`, `NotOfferedError` for a feature the bridge does not offer and `InvalidEventError` for an event
that would not match the protocol. From another thread, hand the coroutine to the loop with
`asyncio.run_coroutine_threadsafe`.
5. Turn Mention markers into native mentions or plain names with `replace_mentions(body, mentions, render)`.
5. Turn Mention markers into native mentions or plain names with `replace_mentions(body, mentions, render)`; see
_Mentions of groups and of everyone in the chat_ below.
6. For pushes, give a bot a `PushTarget` — the callback URL and the push secret that its Bridge Connection in Muster
shows — in `Bot(push=...)` or later with `bridge.set_push(bot, target)`, from the thread of the event loop that
serves the bridge (from another thread, `loop.call_soon_threadsafe(bridge.set_push, bot, target)`). The pushers
Expand All @@ -205,6 +206,56 @@ 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.

## 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
(`group`) or everyone in the chat (`everyone`). For a group, `external_id` and `display_name` both carry the name an
Admin typed, which the bridge maps to its messenger's group; for everyone in the chat they carry the symbolic name:
`channel`, `here`, `all` or `everyone`. Declare what the messenger has in `Capabilities`: `group_mentions=True`, and
`everyone_mentions` with the symbolic names, each once, as `CapabilitiesEveryoneMention` members. A name outside the
four fails when `Capabilities` is built (pydantic's `ValidationError`), and a repeated one makes `BridgeApp` raise
`ConfigError`. Muster sends a group or everyone mention only while its copy of
`info` declares it, whether or not the bridge has `native_mentions`.

`replace_mentions` hands `render` the whole entry, with its `kind`. The library never refuses a Mention for its kind,
because Muster decides from a copy of `info` that may be older than the bridge's own: when `render` returns `None` for
a kind the bridge did not declare, the marker becomes its link text.
The protocol's own models stay closed, so a `kind` beyond `user`, `group` and `everyone` is answered `invalid`, as the
specification says; Muster sends no other kind in protocol version 1.

```python
from muster_bridge import Capabilities, CapabilitiesEveryoneMention, Mention, MentionKind, replace_mentions

capabilities = Capabilities(
native_mentions=True,
group_mentions=True,
everyone_mentions=[CapabilitiesEveryoneMention.EveryoneMentionHere],
)


def render_mention(mention: Mention) -> str | None:
"""Render a Mention for a messenger that writes <@id> for a person, <!group:name> and <!here>."""
if mention.kind == MentionKind.MentionKindGroup and capabilities.group_mentions:
return f"<!group:{mention.external_id}>"
if mention.kind == MentionKind.MentionKindEveryone:
names = [name.value for name in capabilities.everyone_mentions or []]
return f"<!{mention.external_id}>" if mention.external_id in names else None
if mention.kind == MentionKind.MentionKindUser:
return f"<@{mention.external_id}>"
return None


body = "[@Alice](muster-mention:m1) [@oncall](muster-mention:m2) [@here](muster-mention:m3) [@all](muster-mention:m4)"
mentions = [
Mention(ref="m1", external_id="u-alice", display_name="Alice"),
Mention(ref="m2", kind=MentionKind.MentionKindGroup, external_id="oncall", display_name="oncall"),
Mention(ref="m3", kind=MentionKind.MentionKindEveryone, external_id="here", display_name="here"),
Mention(ref="m4", kind=MentionKind.MentionKindEveryone, external_id="all", display_name="all"),
]
text = replace_mentions(body, mentions, render_mention)
assert text == "<@u-alice> <!group:oncall> <!here> @all" # all is not declared: its link text
```

## Rendering the layout

A Root message and a test message carry their content twice: as CommonMark in `body`, and as plain-text data in
Expand Down
56 changes: 53 additions & 3 deletions api/bridge.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,12 @@ info:
paragraphs, hard line breaks, emphasis, strong emphasis, strikethrough, code spans, links, bullet lists and block
quotes; never headings, tables, images or raw HTML. Alert data in the body is already escaped for CommonMark and
cannot mention anyone. Links are `http(s)` links, plus Mention markers: a link `[@Display Name](muster-mention:<ref>)`
whose `ref` names an entry of `mentions`. A bridge with `native_mentions` renders the marker as its messenger's
mention of that account; any other bridge renders the link text alone, as plain text. Muster keeps the body within
whose `ref` names an entry of `mentions`. A bridge with `native_mentions` renders the marker of a person as its
messenger's mention of that account; any other bridge renders the link text alone, as plain text. Muster sends the
marker of a group, whose entry has the `kind` `group`, only while its copy of `info`, at most `bridge.info_max_age`
(10 minutes) old, declares `group_mentions`, and that of everyone in the chat, of the `kind` `everyone`, only while
that copy lists its symbolic name in `everyone_mentions`; the bridge renders either as its messenger's mention of
the group or of everyone in the chat, whether or not it declares `native_mentions`. Muster keeps the body within
`limits.max_body_length` code points; the bridge makes the final cut where its rendered markup needs it — never inside
an entity, a tag or a surrogate pair — and reports it with `truncated`.

Expand Down Expand Up @@ -826,6 +830,29 @@ components:
native_mentions:
type: boolean
description: Mention markers become the messenger's own mentions, which notify the person.
group_mentions:
type: boolean
description: The bridge renders a group mention that Muster sends as a `mentions` entry of the kind `group`;
the Team mentions and group entries of a Destination need it. Missing or false, Muster offers no group
mention for the bridge's Connections.
everyone_mentions:
type: array
description: The mentions of everyone in the chat that the bridge's messenger has, by their symbolic names.
Muster sends only those listed here, each as a `mentions` entry of the kind `everyone`; missing or empty,
none.
uniqueItems: true
items:
type: string
enum:
- channel
- here
- all
- everyone
x-enum-varnames:
- EveryoneMentionChannel
- EveryoneMentionHere
- EveryoneMentionAll
- EveryoneMentionEveryone
quiet_messages:
type: boolean
description: The messenger can post a new message without notifying anyone (`notify` false).
Expand Down Expand Up @@ -899,6 +926,11 @@ components:
pattern: ^[!-~]{1,64}$
Mention:
type: object
description: 'One Mention of the envelope, which a marker `[@Display Name](muster-mention:<ref>)` in the body
places: a person (`kind` `user`, the default), a group of the messenger (`group`), or everyone in the chat
(`everyone`). Muster sends `group` only while its copy of the bridge''s `info`, at most `bridge.info_max_age`
(10 minutes) old, declares `group_mentions`, and `everyone` only with a symbolic name that copy lists in
`everyone_mentions`; it sends a person without `kind`.'
required:
- ref
- external_id
Expand All @@ -908,15 +940,33 @@ components:
type: string
description: Names the marker `muster-mention:<ref>` in the body.
pattern: ^[a-z0-9]{1,16}$
kind:
type: string
description: What the Mention names; missing, it is `user`. Muster sends the Mention of a person without
it.
enum:
- user
- group
- everyone
default: user
x-enum-varnames:
- MentionKindUser
- MentionKindGroup
- MentionKindEveryone
external_id:
type: string
minLength: 1
maxLength: 512
description: The account's id in the messenger, as the bridge reported it when the account was linked.
description: 'For a person, the account''s id in the messenger, as the bridge reported it when the account
was linked; for a group, the name an Admin typed for the Team mention or the Destination''s entry, 1 to 64
letters, digits, `.`, `_` and `-` starting with a letter or a digit, which the bridge maps to its
messenger''s group; for everyone in the chat, the symbolic name: `channel`, `here`, `all` or `everyone`.'
display_name:
type: string
minLength: 1
maxLength: 200
description: The name the marker shows; for a group its name and for everyone in the chat its symbolic
name, as `external_id`.
Link:
type: object
required:
Expand Down
34 changes: 29 additions & 5 deletions examples/memory_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,11 @@
python examples/memory_bridge.py --token-file /tmp/bt

It offers every feature, or with BRIDGE_FEATURES only those it lists, comma-separated: buttons, thread_messages,
direct_messages (which also turns on user_lookup login), private_answers, native_mentions, quiet_messages,
status_color, deletion_events and delete. Outside the protocol it serves POST /demo/press {"message_id", "user"},
which presses the first button of the message as the person with that login. Unlike the protocol, which needs the
token, it has no authentication of its own: the example listens on loopback by default.
direct_messages (which also turns on user_lookup login), private_answers, native_mentions, group_mentions,
everyone_mentions (channel and here), quiet_messages, status_color, deletion_events and delete. Outside the protocol it
serves POST /demo/press {"message_id", "user"}, which presses the first button of the message as the person with that
login. 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
Expand Down Expand Up @@ -44,6 +45,7 @@
CapabilitiesButtons,
CapabilitiesDelete,
CapabilitiesDirectMessages,
CapabilitiesEveryoneMention,
CapabilitiesPrivateAnswer,
CapabilitiesThreadMessages,
Config,
Expand All @@ -53,6 +55,7 @@
Gone,
Limits,
Mention,
MentionKind,
MessageContent,
MessageEdited,
MessageInput,
Expand All @@ -73,11 +76,17 @@
"direct_messages",
"private_answers",
"native_mentions",
"group_mentions",
"everyone_mentions",
"quiet_messages",
"status_color",
"deletion_events",
"delete",
)
EVERYONE_MENTIONS = [
CapabilitiesEveryoneMention.EveryoneMentionChannel,
CapabilitiesEveryoneMention.EveryoneMentionHere,
]
MAX_DEMO_BODY = 64 << 10

log = logging.getLogger("memory_bridge")
Expand Down Expand Up @@ -146,6 +155,8 @@ def capabilities(on: set[str]) -> Capabilities:
direct_messages=CapabilitiesDirectMessages(bot_can_start=True) if "direct_messages" in on else None,
private_answers=[CapabilitiesPrivateAnswer.ephemeral] if "private_answers" in on else None,
native_mentions=True if "native_mentions" in on else None,
group_mentions=True if "group_mentions" in on else None,
everyone_mentions=EVERYONE_MENTIONS if "everyone_mentions" in on else None,
quiet_messages=True if "quiet_messages" in on else None,
status_color=True if "status_color" in on else None,
delete=CapabilitiesDelete(max_age_seconds=None) if "delete" in on else None,
Expand Down Expand Up @@ -178,6 +189,8 @@ class MemoryChat:
people: dict[str, Person]
private: bool
native: bool
groups: bool = False
everyone: bool = False
id_prefix: str = field(default_factory=lambda: secrets.token_hex(3))
messages: dict[str, Message] = field(default_factory=dict)
last: int = 0
Expand Down Expand Up @@ -332,7 +345,16 @@ def _next_id(self) -> str:

def _mentions(self, body: str, mentions: list[Mention]) -> str:
"""Return body with its Mention markers as the messenger shows them: @login or the name."""
return replace_mentions(body, mentions, lambda m: f"@{m.external_id}" if self.native else m.display_name)
return replace_mentions(body, mentions, self._mention)

def _mention(self, mention: Mention) -> str | None:
"""Return how the messenger shows a Mention, or None for a kind it does not offer: the marker's link text."""
if mention.kind == MentionKind.MentionKindGroup:
return f"@{mention.external_id}" if self.groups else None
if mention.kind == MentionKind.MentionKindEveryone:
listed = {name.value for name in EVERYONE_MENTIONS}
return f"@{mention.external_id}" if self.everyone and mention.external_id in listed else None
return f"@{mention.external_id}" if self.native else mention.display_name


def labels(buttons: list[Button]) -> list[str]:
Expand Down Expand Up @@ -370,6 +392,8 @@ def configure(args: argparse.Namespace) -> tuple[Config, MemoryChat]:
people=people,
private="private_answers" in on,
native="native_mentions" in on,
groups="group_mentions" in on,
everyone="everyone_mentions" in on,
)
return config, chat

Expand Down
4 changes: 4 additions & 0 deletions src/muster_bridge/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
CapabilitiesButtons,
CapabilitiesDelete,
CapabilitiesDirectMessages,
CapabilitiesEveryoneMention,
CapabilitiesPrivateAnswer,
CapabilitiesThreadMessages,
DirectMessageInput,
Expand All @@ -48,6 +49,7 @@
Limits,
Link,
Mention,
MentionKind,
MessageContent,
MessageEdited,
MessageInput,
Expand All @@ -74,6 +76,7 @@
"CapabilitiesButtons",
"CapabilitiesDelete",
"CapabilitiesDirectMessages",
"CapabilitiesEveryoneMention",
"CapabilitiesPrivateAnswer",
"CapabilitiesThreadMessages",
"ClosedError",
Expand Down Expand Up @@ -106,6 +109,7 @@
"Link",
"MemoryStore",
"Mention",
"MentionKind",
"MessageContent",
"MessageEdited",
"MessageInput",
Expand Down
1 change: 1 addition & 0 deletions src/muster_bridge/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -329,6 +329,7 @@ def _build_info(config: Config) -> tuple[bytes, Info | None, list[str]]:
("/event_delivery", checked.event_delivery),
("/capabilities/buttons/styles", checked.capabilities.buttons.styles if checked.capabilities.buttons else []),
("/capabilities/private_answers", checked.capabilities.private_answers or []),
("/capabilities/everyone_mentions", checked.capabilities.everyone_mentions or []),
):
if len(set(items)) != len(items):
problems.append(f"{_SPEC_MISMATCH}{pointer}: the items are not unique")
Expand Down
17 changes: 12 additions & 5 deletions src/muster_bridge/mentions.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,18 @@
_REF = re.compile(r"\]\(muster-mention:([a-z0-9]{1,16})\)")


def replace_mentions(body: str, mentions: Sequence[Mention], render: Callable[[Mention], str] | None) -> str:
def replace_mentions(body: str, mentions: Sequence[Mention], render: Callable[[Mention], str | None] | None) -> str:
"""Replace each Mention marker [@name](muster-mention:ref) of body by what render makes of its entry of mentions.

render makes the messenger's own mention for a bridge with native_mentions, or the plain name. A marker whose ref
names no entry, or every marker when render is None, becomes its link text, the @name as the body escapes it. The
first entry of a ref wins. The rest of body is unchanged. It takes time linear in the length of body.
render gets the whole entry and makes the messenger's own mention of it, or the plain name. Look at its kind: a
person (user, also when the entry has no kind), a group, whose external_id and display_name are the group's name,
or everyone in the chat, whose two fields are the symbolic name (channel, here, all or everyone). A bridge renders
a group or everyone mention whether or not it declares native_mentions, and never refuses an entry for its kind:
Muster decides from a copy of info that may be older than the bridge's own, so render returns None for a kind the
bridge did not declare (capabilities.group_mentions, capabilities.everyone_mentions). A marker whose ref names no
entry, a marker whose render returns None, and every marker when render is None, become the link text, the @name
as the body escapes it. The first entry of a ref wins. The rest of body is unchanged. It takes time linear in the
length of body.
"""
if _TAIL not in body:
return body
Expand All @@ -36,7 +42,8 @@ def replace_mentions(body: str, mentions: Sequence[Mention], render: Callable[[M
done = 0
for start, end, text, ref in _markers(body):
found = by_ref.get(ref)
parts += (body[done:start], render(found) if found is not None and render is not None else text)
shown = render(found) if found is not None and render is not None else None
parts += (body[done:start], text if shown is None else shown)
done = end
parts.append(body[done:])
return "".join(parts)
Expand Down
Loading
Loading