From f45ed8e4ec955d0b101707c8c621b82a8f23367a Mon Sep 17 00:00:00 2001 From: chelsealong Date: Fri, 18 Sep 2026 07:20:51 +0000 Subject: [PATCH] docs(matrix): document the <=2-member DM auto-classification and its config bypass _resolve_room_identity() classifies any room with <=2 joined members as a DM regardless of m.direct or an explicit room name, so those rooms silently bypass MATRIX_ALLOWED_ROOMS, MATRIX_FREE_RESPONSE_ROOMS, and MATRIX_REQUIRE_MENTION, and use DM threading instead of MATRIX_AUTO_THREAD/MATRIX_SESSION_SCOPE. This was previously only visible in an inline code comment, not in the env-var docs an operator would read. Fixes #114733 --- plugins/platforms/matrix/adapter.py | 8 ++++++++ .../matrix/test_dm_classification_doc.py | 16 ++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 tests/plugins/platforms/matrix/test_dm_classification_doc.py diff --git a/plugins/platforms/matrix/adapter.py b/plugins/platforms/matrix/adapter.py index dfe7a25270..fe3b82f701 100644 --- a/plugins/platforms/matrix/adapter.py +++ b/plugins/platforms/matrix/adapter.py @@ -13,6 +13,14 @@ Env vars (config.yaml ``matrix:`` keys alias several — env wins): MATRIX_SESSION_SCOPE auto|room|thread; MATRIX_MAX_MESSAGE_LENGTH (default 16000), MATRIX_MAX_MEDIA_BYTES, MATRIX_ROOM_IDENTITY_TTL_SECONDS; MATRIX_APPROVAL_REQUIRE_SENDER (default true), MATRIX_APPROVAL_TIMEOUT_SECONDS (default 300). + +Note: any room with <=2 joined members is auto-classified as a DM (see +``_resolve_room_identity``), regardless of ``m.direct`` account data or an explicit room name — +clients auto-name DMs like "Alice & Bot", so name alone can't be trusted. A DM-classified room +therefore bypasses MATRIX_ALLOWED_ROOMS, MATRIX_FREE_RESPONSE_ROOMS, and MATRIX_REQUIRE_MENTION, +and follows MATRIX_DM_AUTO_THREAD / MATRIX_DM_MENTION_THREADS instead of MATRIX_AUTO_THREAD / +MATRIX_SESSION_SCOPE. To make a deliberately-created 2-person room behave like a regular room, +add a third member so it has >2 joined members. """ from __future__ import annotations diff --git a/tests/plugins/platforms/matrix/test_dm_classification_doc.py b/tests/plugins/platforms/matrix/test_dm_classification_doc.py new file mode 100644 index 0000000000..470f0b153a --- /dev/null +++ b/tests/plugins/platforms/matrix/test_dm_classification_doc.py @@ -0,0 +1,16 @@ +"""The module docstring documents env vars near MATRIX_ALLOWED_ROOMS/MATRIX_REQUIRE_MENTION/ +MATRIX_AUTO_THREAD as if they applied uniformly to rooms, but _resolve_room_identity classifies +any room with <=2 joined members as a DM regardless of m.direct or an explicit room name, which +silently bypasses those settings (#114733). Assert the docstring actually says so.""" + +from plugins.platforms.matrix import adapter + + +def test_module_docstring_covers_member_count_dm_classification(): + doc = adapter.__doc__ + + assert "<=2 joined members" in doc + assert "MATRIX_ALLOWED_ROOMS" in doc.split("Note:", 1)[1] + assert "MATRIX_FREE_RESPONSE_ROOMS" in doc.split("Note:", 1)[1] + assert "MATRIX_REQUIRE_MENTION" in doc.split("Note:", 1)[1] + assert "MATRIX_DM_AUTO_THREAD" in doc.split("Note:", 1)[1]