diff --git a/CHANGELOG.md b/CHANGELOG.md index e1f0cd8..ec62f30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ This project follows the versioning policy in VERSIONING.md. +## 0.3.1 - 2026-05-17 + +- Added a backward-compatible direct `NOTICE` extension using envelope key + `K_DST = 8` for full destination identity hashes +- Added advisory `CAP_DIRECT_NOTICE = 2` to `WELCOME` capabilities so clients + can detect support before sending direct notices +- Direct `NOTICE` delivery now returns `ERROR` for mixed room-plus-destination + envelopes and for unknown or offline destination identities + ## 0.3.0 - 2026-05-16 - Added core message type `ACTION` (`T_ACTION = 22`) routing with room-content semantics diff --git a/EX1-RRCD.md b/EX1-RRCD.md index 1f5b4ad..ba0f9de 100644 --- a/EX1-RRCD.md +++ b/EX1-RRCD.md @@ -52,6 +52,50 @@ syntax to generate `ACTION` envelopes, and clients are free to render incoming `rrcd` does not parse slash commands from `ACTION` bodies. Slash-command handling remains a `MSG`/`NOTICE` convention. +## Extension: Direct NOTICE Delivery + +**Envelope Key**: `8` (`K_DST`) +**Capability Key**: `2` (`CAP_DIRECT_NOTICE`) +**Status**: Implemented (advisory) + +`rrcd` advertises `CAP_DIRECT_NOTICE` in `WELCOME` capabilities to indicate +that the hub supports client-to-client `NOTICE` delivery using an explicit +destination identity hash. + +When a client sends a `NOTICE` with `K_DST = 8`, the value must be the full +destination identity hash as bytes. The hub resolves that identity against the +currently connected sessions and forwards the `NOTICE` to exactly one link. + +Direct `NOTICE` delivery does not use room membership. `K_ROOM` must be omitted +when `K_DST` is present; if both are present, the hub rejects the message with +`ERROR` rather than guessing which delivery mode the sender intended. + +**Envelope structure**: + +```python +{ + 0: 1, # protocol version (K_V) + 1: 21, # message type T_NOTICE (K_T) + 2: <8-byte-id>, # message ID (K_ID) + 3: , # millisecond timestamp (K_TS) + 4: , # sender identity hash (K_SRC) + 6: , # notice body (K_BODY) + 8: # full destination identity hash (K_DST) +} +``` + +**Delivery semantics**: + +- The hub overwrites `K_SRC` with the authenticated sender identity for the + current link. +- The hub preserves `K_DST` on the forwarded envelope so the recipient can tell + that the `NOTICE` was direct-addressed to its identity. +- The hub may normalize or attach `K_NICK` as a display hint, just as it does + for room `MSG`/`NOTICE` forwarding. +- If the destination is not currently connected, the sender receives `ERROR`. +- Nicknames and hash prefixes are not accepted in `K_DST`; this field is full + identity bytes only. + The RRC specification has no concept of large message delivery beyond "chunk it yourself, good luck." This is fine for small messages but becomes obnoxious for: @@ -507,9 +551,11 @@ If you're implementing a client or another hub, here's what you need to know: ### Enhanced Compatibility (Recommended) - Support `T_RESOURCE_ENVELOPE` (message type 50) and Reticulum resources - Handle `ACTION` (message type 22) as room content (rendering is client-defined) +- Handle `K_DST` (envelope key 8) on incoming `NOTICE` if you want direct-message UX - Advertise `CAP_ACTION` in your `HELLO` capabilities if you support ACTION UX - Advertise `CAP_RESOURCE_ENVELOPE` in your `HELLO` capabilities if you support resources +- Wait for `CAP_DIRECT_NOTICE` in `WELCOME` before sending direct `NOTICE` with `K_DST` - Expect hub greeting to arrive via `NOTICE` messages after `WELCOME` - Handle chunked `NOTICE` messages (multiple messages with the same content type) diff --git a/README.md b/README.md index a046c4a..bcafb16 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,23 @@ Wire-level extensions (backwards-compatible): UTF-8 encodable, contain no newlines/NUL, and are at most `nick_max_chars` characters (default: 32). +- **Direct NOTICE destination**: the hub supports client-to-client `NOTICE` + delivery using an optional envelope key `K_DST = 8` (bytes), containing the + full destination identity hash. + + This extension applies only to `NOTICE`. When `K_DST` is present, the hub + delivers the message to exactly one connected client identified by that full + hash instead of broadcasting by room membership. The forwarded `NOTICE` + preserves `K_DST` so the recipient can distinguish direct delivery from + room traffic without out-of-band state. + + Direct `NOTICE` messages must not also include `K_ROOM`. Mixed room and + direct-destination semantics are rejected with `ERROR`. + + Support for this extension is advertised in `WELCOME` capabilities via + `CAP_DIRECT_NOTICE = 2`. Clients should only send `K_DST`-addressed notices + after confirming hub support. + - **Large payload transfer via RNS.Resource**: For messages that exceed the link MTU (Maximum Data Unit), `rrcd` can automatically use RNS.Resource for reliable large payload transfer instead of manual chunking. diff --git a/rrcd/__init__.py b/rrcd/__init__.py index 747d46f..7d18268 100644 --- a/rrcd/__init__.py +++ b/rrcd/__init__.py @@ -1,3 +1,3 @@ __all__ = ["__version__"] -__version__ = "0.3.0" +__version__ = "0.3.1" diff --git a/rrcd/constants.py b/rrcd/constants.py index d20bbc7..d4d12df 100644 --- a/rrcd/constants.py +++ b/rrcd/constants.py @@ -11,6 +11,7 @@ K_SRC = 4 K_ROOM = 5 K_BODY = 6 K_NICK = 7 +K_DST = 8 # Message types T_HELLO = 1 @@ -58,6 +59,7 @@ B_LIMIT_RATE_LIMIT_MSGS_PER_MINUTE = 4 # Capabilities map keys (values are advisory). Keep these small and numeric. CAP_RESOURCE_ENVELOPE = 0 CAP_ACTION = 1 +CAP_DIRECT_NOTICE = 2 # RESOURCE_ENVELOPE body keys B_RES_ID = 0 diff --git a/rrcd/envelope.py b/rrcd/envelope.py index cb7944a..fad63ed 100644 --- a/rrcd/envelope.py +++ b/rrcd/envelope.py @@ -3,7 +3,18 @@ from __future__ import annotations import os import time -from .constants import K_BODY, K_ID, K_NICK, K_ROOM, K_SRC, K_T, K_TS, K_V, RRC_VERSION +from .constants import ( + K_BODY, + K_DST, + K_ID, + K_NICK, + K_ROOM, + K_SRC, + K_T, + K_TS, + K_V, + RRC_VERSION, +) from .util import normalize_nick @@ -19,6 +30,7 @@ def make_envelope( msg_type: int, *, src: bytes, + dst: bytes | None = None, room: str | None = None, body=None, nick: str | None = None, @@ -32,6 +44,8 @@ def make_envelope( K_TS: ts or now_ms(), K_SRC: src, } + if dst is not None: + env[K_DST] = bytes(dst) if room is not None: env[K_ROOM] = room if body is not None: @@ -90,3 +104,8 @@ def validate_envelope(env: dict) -> None: nick = env[K_NICK] if not isinstance(nick, str): raise TypeError("nickname must be a string") + + if K_DST in env: + dst = env[K_DST] + if not isinstance(dst, (bytes, bytearray)): + raise TypeError("destination identity must be bytes") diff --git a/rrcd/messages.py b/rrcd/messages.py index 3ded26a..0b2b7bd 100644 --- a/rrcd/messages.py +++ b/rrcd/messages.py @@ -18,6 +18,7 @@ from .constants import ( B_WELCOME_LIMITS, B_WELCOME_VER, CAP_ACTION, + CAP_DIRECT_NOTICE, CAP_RESOURCE_ENVELOPE, T_ERROR, T_NOTICE, @@ -144,6 +145,7 @@ class MessageHelper: caps: dict[int, bool] = { CAP_ACTION: True, + CAP_DIRECT_NOTICE: True, } if self.hub.config.enable_resource_transfer: caps[CAP_RESOURCE_ENVELOPE] = True diff --git a/rrcd/router.py b/rrcd/router.py index 16d1f6e..f940c35 100644 --- a/rrcd/router.py +++ b/rrcd/router.py @@ -15,6 +15,7 @@ from .constants import ( B_RES_SHA256, B_RES_SIZE, K_BODY, + K_DST, K_NICK, K_ROOM, K_SRC, @@ -610,7 +611,11 @@ class MessageRouter: peer_still_in_room = True break - if remaining_members and self.hub.identity is not None and not peer_still_in_room: + if ( + remaining_members + and self.hub.identity is not None + and not peer_still_in_room + ): notification_body = ( [peer_hash] if self.hub.config.include_joined_member_list else None ) @@ -652,6 +657,7 @@ class MessageRouter: """Handle MSG, NOTICE, and ACTION messages.""" t = env.get(K_T) room = env.get(K_ROOM) + dst = env.get(K_DST) body = env.get(K_BODY) if t in (T_MSG, T_NOTICE) and isinstance(body, str): @@ -716,6 +722,9 @@ class MessageRouter: ) return elif t == T_NOTICE: + if dst is not None: + self._handle_direct_notice(link, sess, peer_hash, env, outgoing) + return if not isinstance(room, str) or not room: return @@ -829,6 +838,87 @@ class MessageRouter: else: self.hub.stats_manager.inc("notices_forwarded") + def _handle_direct_notice( + self, + link: RNS.Link, + sess: dict[str, Any], + peer_hash: bytes, + env: dict, + outgoing: list[tuple[RNS.Link, bytes]], + ) -> None: + """Handle client-to-client NOTICE delivery by destination identity.""" + if self.hub.identity is None: + return + + dst = env.get(K_DST) + room = env.get(K_ROOM) + + if room is not None: + self.hub.message_helper.emit_error( + outgoing, + link, + src=self.hub.identity.hash, + text="direct notice must not include room", + ) + return + + if not isinstance(dst, (bytes, bytearray)): + self.hub.message_helper.emit_error( + outgoing, + link, + src=self.hub.identity.hash, + text="direct notice requires destination identity", + ) + return + + target_link = self.hub.session_manager.get_link_by_hash(bytes(dst)) + if target_link is None: + self.hub.message_helper.emit_error( + outgoing, + link, + src=self.hub.identity.hash, + text="destination not connected", + ) + return + + env[K_SRC] = ( + bytes(peer_hash) if isinstance(peer_hash, (bytes, bytearray)) else peer_hash + ) + + incoming_nick = env.get(K_NICK) + if incoming_nick is not None: + n = normalize_nick(incoming_nick, max_bytes=self.hub.config.max_nick_bytes) + if n is not None: + old_session_nick = sess.get("nick") + if old_session_nick != n: + sess["nick"] = n + self.hub.session_manager.update_nick_index( + link, old_session_nick, n + ) + env[K_NICK] = n + else: + env.pop(K_NICK, None) + else: + nick = sess.get("nick") + n = normalize_nick(nick, max_bytes=self.hub.config.max_nick_bytes) + if n is not None: + env[K_NICK] = n + + env[K_DST] = bytes(dst) + payload = encode(env) + self.hub.message_helper.queue_payload(outgoing, target_link, payload) + + if self.log.isEnabledFor(logging.DEBUG): + self.log.debug( + "Forwarded direct NOTICE peer=%s nick=%r dst=%s body_type=%s", + self.hub._fmt_hash(peer_hash), + sess.get("nick"), + bytes(dst).hex(), + type(env.get(K_BODY)).__name__, + ) + + self.hub.stats_manager.inc("notices_forwarded") + def _handle_ping( self, link: RNS.Link, diff --git a/rrcd/session.py b/rrcd/session.py index 0779205..dd9a194 100644 --- a/rrcd/session.py +++ b/rrcd/session.py @@ -143,7 +143,12 @@ class SessionManager: peer_still_in_room = True break - if remaining_members and peer_hash and self.hub.identity and not peer_still_in_room: + if ( + remaining_members + and peer_hash + and self.hub.identity + and not peer_still_in_room + ): notification_body = ( [peer_hash] if self.hub.config.include_joined_member_list else None ) diff --git a/tests/test_action_router.py b/tests/test_action_router.py index 08f9739..fbd75d4 100644 --- a/tests/test_action_router.py +++ b/tests/test_action_router.py @@ -4,7 +4,19 @@ import threading from dataclasses import dataclass from rrcd.codec import decode -from rrcd.constants import B_WELCOME_CAPS, CAP_ACTION, CAP_RESOURCE_ENVELOPE, K_BODY, K_T, T_ACTION +from rrcd.constants import ( + B_WELCOME_CAPS, + CAP_ACTION, + CAP_DIRECT_NOTICE, + CAP_RESOURCE_ENVELOPE, + K_BODY, + K_DST, + K_NICK, + K_SRC, + K_T, + T_ACTION, + T_NOTICE, +) from rrcd.envelope import make_envelope from rrcd.messages import MessageHelper from rrcd.router import MessageRouter @@ -49,13 +61,26 @@ class _FakeRoomManager: class _FakeSessionManager: - def update_nick_index(self, link: object, old_nick: str | None, new_nick: str | None) -> None: + def __init__(self) -> None: + self.targets: dict[bytes, object] = {} + + def update_nick_index( + self, link: object, old_nick: str | None, new_nick: str | None + ) -> None: return + def get_link_by_hash(self, peer_hash: bytes) -> object | None: + return self.targets.get(bytes(peer_hash)) + class _FakeMessageHelper: - def emit_error(self, outgoing, link, *, src: bytes, text: str, room: str | None = None) -> None: - raise AssertionError(f"unexpected error emitted: {text}") + def __init__(self) -> None: + self.errors: list[tuple[object, str, str | None]] = [] + + def emit_error( + self, outgoing, link, *, src: bytes, text: str, room: str | None = None + ) -> None: + self.errors.append((link, text, room)) def queue_payload(self, outgoing, link, payload: bytes) -> None: outgoing.append((link, payload)) @@ -82,7 +107,7 @@ class _FakeLink: class _FakeHub: - def __init__(self, link: object) -> None: + def __init__(self, link: object, members: list[object] | None = None) -> None: import logging self.log = logging.getLogger("test") @@ -90,7 +115,7 @@ class _FakeHub: self.config = _FakeConfig() self.stats_manager = _FakeStats() self.command_handler = _FakeCommandHandler() - self.room_manager = _FakeRoomManager([link]) + self.room_manager = _FakeRoomManager(members if members is not None else [link]) self.session_manager = _FakeSessionManager() self.message_helper = _FakeMessageHelper() self._state_lock = threading.RLock() @@ -117,6 +142,7 @@ def test_action_is_forwarded_without_command_interpretation() -> None: router._handle_message(link, sess, b"peer", env, outgoing) assert hub.command_handler.called is False + assert hub.message_helper.errors == [] assert hub.stats_manager.counters.get("actions_forwarded") == 1 assert len(outgoing) == 1 @@ -152,4 +178,72 @@ def test_welcome_advertises_action_capability() -> None: decoded = decode(outgoing[0][1]) caps = decoded[K_BODY][B_WELCOME_CAPS] assert caps[CAP_ACTION] is True + assert caps[CAP_DIRECT_NOTICE] is True assert caps[CAP_RESOURCE_ENVELOPE] is True + + +def test_notice_is_forwarded_to_direct_destination() -> None: + sender_link = _FakeLink() + target_link = object() + hub = _FakeHub(sender_link) + hub.session_manager.targets[b"target"] = target_link + router = MessageRouter(hub) + + sess = {"rooms": set(), "nick": "alice"} + env = make_envelope(T_NOTICE, src=b"spoofed", dst=b"target", body="hello") + outgoing: list[tuple[object, bytes]] = [] + + router._handle_message(sender_link, sess, b"peer", env, outgoing) + + assert hub.message_helper.errors == [] + assert hub.stats_manager.counters.get("notices_forwarded") == 1 + assert len(outgoing) == 1 + assert outgoing[0][0] is target_link + + decoded = decode(outgoing[0][1]) + assert decoded[K_T] == T_NOTICE + assert decoded[K_SRC] == b"peer" + assert decoded[K_DST] == b"target" + assert decoded[K_NICK] == "alice" + assert decoded[K_BODY] == "hello" + + +def test_direct_notice_rejects_room_and_destination_combination() -> None: + sender_link = _FakeLink() + hub = _FakeHub(sender_link) + hub.session_manager.targets[b"target"] = object() + router = MessageRouter(hub) + + sess = {"rooms": {"#general"}, "nick": "alice"} + env = make_envelope( + T_NOTICE, + src=b"peer", + dst=b"target", + room="#general", + body="hello", + ) + outgoing: list[tuple[object, bytes]] = [] + + router._handle_message(sender_link, sess, b"peer", env, outgoing) + + assert outgoing == [] + assert hub.message_helper.errors == [ + (sender_link, "direct notice must not include room", None) + ] + + +def test_direct_notice_rejects_unknown_destination() -> None: + sender_link = _FakeLink() + hub = _FakeHub(sender_link) + router = MessageRouter(hub) + + sess = {"rooms": set(), "nick": "alice"} + env = make_envelope(T_NOTICE, src=b"peer", dst=b"missing", body="hello") + outgoing: list[tuple[object, bytes]] = [] + + router._handle_message(sender_link, sess, b"peer", env, outgoing) + + assert outgoing == [] + assert hub.message_helper.errors == [ + (sender_link, "destination not connected", None) + ] diff --git a/tests/test_envelope.py b/tests/test_envelope.py index e8b8310..ef4b98b 100644 --- a/tests/test_envelope.py +++ b/tests/test_envelope.py @@ -3,6 +3,7 @@ import pytest from rrcd.constants import ( B_HELLO_NICK_LEGACY, K_BODY, + K_DST, K_ID, K_NICK, K_SRC, @@ -26,6 +27,12 @@ def test_validate_accepts_optional_nick_extension() -> None: validate_envelope(env) +def test_validate_accepts_optional_destination_extension() -> None: + env = make_envelope(T_HELLO, src=b"peer", dst=b"target", body=None) + assert env[K_DST] == b"target" + validate_envelope(env) + + def test_validate_allows_ridiculous_or_empty_nick() -> None: env = make_envelope(T_HELLO, src=b"peer", body=None) env[K_NICK] = "" @@ -89,3 +96,8 @@ def test_validate_rejects_wrong_field_types() -> None: env[K_NICK] = 123 with pytest.raises(TypeError): validate_envelope(env) + + env = make_envelope(T_HELLO, src=b"peer", body=None) + env[K_DST] = "not-bytes" + with pytest.raises(TypeError): + validate_envelope(env)