Multi User Chat 2: a multi-channel group-communication component for XMPP (rooms with text, voice and feed channels, MUC-compatible), full Tcl on libtacky
  • Tcl 92.6%
  • Python 5.2%
  • Makefile 1.2%
  • Shell 0.8%
  • Dockerfile 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-21 15:43:08 +02:00
component tests: the MUC face's owner and admin paths the first coverage run found uncalled -- muc#owner configure (moderated, subject, private messages, members-only, the name) and destroy of the lobby with every channel's sessions told, a mediated invitation pre-adding the invitee under a free nick and a member's without the invite permission filed as a knock, the owner's vCard as the room's avatar, muc#admin roles as voice overwrites and the moderator hat, the last owner kept and an unban by affiliation none, a voice channel's disco from the service; mucface.tcl loses available, which nothing calls since setup serves the face. test_mucwire 22. 2026-11-21 15:38:20 +02:00
docs docs: README's Building and running names make e2e and both lease kinds; docs/files.md maps standby.tcl, register.tcl, mucsub.tcl and tests/e2e/ and says how the MUC face shares the handlers; CHANGELOG's Unreleased gains the round's MUC face, passive delivery, active/standby instances and the end-to-end suite. 2026-11-21 15:30:36 +02:00
libtacky@e4ce7510f0 libtacky pinned at integ/1.3 e4ce7510: the tree with tacky::xmpp::mucservice (the XEP-0045 service over a backend, with the reflected hook, extra identities, node pass-through and gone/redirect addresses the MUC face adapter needs) and the component's standby, warm-up and lease; from here main.tcl's -lease and component/mucface.tcl can be served. 2026-11-21 15:00:13 +02:00
tests tests: the MUC face's owner and admin paths the first coverage run found uncalled -- muc#owner configure (moderated, subject, private messages, members-only, the name) and destroy of the lobby with every channel's sessions told, a mediated invitation pre-adding the invitee under a free nick and a member's without the invite permission filed as a knock, the owner's vCard as the room's avatar, muc#admin roles as voice overwrites and the moderator hat, the last owner kept and an unban by affiliation none, a voice channel's disco from the service; mucface.tcl loses available, which nothing calls since setup serves the face. test_mucwire 22. 2026-11-21 15:38:20 +02:00
tools The numbers, as the sibling repositories keep them: tools/stats.py (after deltagram's, Tcl only) counts code and test lines per component of the design (store, perm, rooms and addressing, pubsub, members, invites, hats, mucface, service and main; the Makefile, Dockerfile, harness and tools as everything else, outside the totals; libtacky not counted), the test cases each family defines and the procedure coverage of a run; tools/cov.tcl records which procedures of component/ are called, by the unit suites (tests/unit/common.tcl sources it under MUC2_COVER) and by dist/muc2 under the e2e (tools/cov-main.tcl as the packed main.tcl, make component-cov). make coverage-all runs both into _build/cov and writes REPORT.md (with the procedures never called) and README's generated sections; make stats rewrites them from the tree keeping the last run's coverage, make stats-check fails when they are stale. 2026-11-21 15:38:20 +02:00
.gitignore muc2: the repository of Multi User Chat 2, a multi-channel group-communication component for XMPP written in Tcl on libtacky (the design: another-im's muc2-design.md of 2026-11-21): libtacky as the submodule libtacky/, pinned at v1.3.0-beta2 (99a29433, the integ/1.3 line both gateways build on), and the ignore list for dist/ and _build/ as the sibling components have them. The component itself follows in the next commits. 2026-11-21 13:40:12 +02:00
.gitmodules libtacky pinned at develop 410c99bf (1.3.0-beta3 plus the merge of integ/1.3 e4ce7510): develop is the 1.3 line now and carries tacky::xmpp::mucservice and the component's lease, so .gitmodules follows develop; dist/muc2 rebuilt on it, make test 226/226. 2026-11-21 15:43:08 +02:00
CHANGELOG.md docs: README's Building and running names make e2e and both lease kinds; docs/files.md maps standby.tcl, register.tcl, mucsub.tcl and tests/e2e/ and says how the MUC face shares the handlers; CHANGELOG's Unreleased gains the round's MUC face, passive delivery, active/standby instances and the end-to-end suite. 2026-11-21 15:30:36 +02:00
Dockerfile The build skeleton, as the sibling gateways have it minus their engines: make component packs component/ onto a copy of libtacky's dist/tackyd as the one executable dist/muc2, make test runs the unit suites of tests/unit/ one interpreter each in libtacky's build image with this checkout mounted, make image puts dist/muc2 on Debian slim with the data volume /var/lib/muc2; component/load.tcl sources the component's files in their order for main.tcl and the suites alike, component/util.tcl holds what every file uses (the log, an injectable clock, node accessors, the namespaces, the error rule's shorthand, base64url and a constant-time compare); the licence is GPL-3.0 like the siblings'. 2026-11-21 14:20:37 +02:00
LICENSE The build skeleton, as the sibling gateways have it minus their engines: make component packs component/ onto a copy of libtacky's dist/tackyd as the one executable dist/muc2, make test runs the unit suites of tests/unit/ one interpreter each in libtacky's build image with this checkout mounted, make image puts dist/muc2 on Debian slim with the data volume /var/lib/muc2; component/load.tcl sources the component's files in their order for main.tcl and the suites alike, component/util.tcl holds what every file uses (the log, an injectable clock, node accessors, the namespaces, the error rule's shorthand, base64url and a constant-time compare); the licence is GPL-3.0 like the siblings'. 2026-11-21 14:20:37 +02:00
Makefile The numbers, as the sibling repositories keep them: tools/stats.py (after deltagram's, Tcl only) counts code and test lines per component of the design (store, perm, rooms and addressing, pubsub, members, invites, hats, mucface, service and main; the Makefile, Dockerfile, harness and tools as everything else, outside the totals; libtacky not counted), the test cases each family defines and the procedure coverage of a run; tools/cov.tcl records which procedures of component/ are called, by the unit suites (tests/unit/common.tcl sources it under MUC2_COVER) and by dist/muc2 under the e2e (tools/cov-main.tcl as the packed main.tcl, make component-cov). make coverage-all runs both into _build/cov and writes REPORT.md (with the procedures never called) and README's generated sections; make stats rewrites them from the tree keeping the last run's coverage, make stats-check fails when they are stale. 2026-11-21 15:38:20 +02:00
README.md README figures by make coverage-all at 6e7f873: 4,599 lines of Tcl in nine components, 2,265 lines of tests, 198 test cases defined; every one of component/'s 358 procedures called by the unit suites (226 passed) or by dist/muc2 under the e2e on ejabberd (10 passed), 100.0 % of procs; make stats-check clean. 2026-11-21 15:40:15 +02:00

Multi User Chat 2 (MUC2)

A group-communication component for XMPP: rooms that hold several channels (text, voice, feed), with persistent membership, named roles and invite links, served as an external component (muc2.example.org) next to any ejabberd or Prosody. Plain MUC clients join its text channels as ordinary XEP-0045 rooms; MUC2-aware clients get the rest. Written entirely in Tcl on libtacky, the same library the Another IM clients and the Telegram and Delta Chat gateways run on.

Status (2026-11-21): design complete (docs/design.md), implementation in progress. Nothing here is deployed yet.

For users

  • A room is a place, not a chat. Think of a TeamSpeak server or a Discord guild: it has an owner, admins, moderators, members, and inside it channels. You join the room once; you are a member whether you are online or not.
  • Channels are text (a chat), voice (a standing call you drop into, with camera and screen sharing) or a feed (posts with comments and reactions). A channel can be open to every member, limited to people who wear a given role ("support", "team"), or invite-only.
  • Roles are hats: the room owner names them, orders them and says what each may do (post, pin, moderate, mute, invite, speak in voice, publish to the feed). Moderators get timeouts, bans that cover the whole room, slow mode, a report inbox and an audit log that is just another hidden channel.
  • Invite links work like you expect: https://muc2.example.org/i/#… or an xmpp: URI, with an expiry, a use count, a preview card, and a role the link grants. A link can be revoked; a banned person cannot use one.
  • Your existing client keeps working. Conversations, Dino, Gajim, Monal and every other MUC client can join a text channel, read history, react, reply, correct and be moderated. They cannot create rooms, join voice or read feeds, and they never see a channel that is end-to-end encrypted.
  • Encryption in MUC2-native text channels is MLS (RFC 9420), one group per channel, with the component ordering the handshake. Voice media is encrypted end to end with keys passed through that MLS group.

For client developers

The wire is standard XMPP wherever a XEP exists; the component's own pieces are few and live under urn:tacky:muc2:*, each specified in docs/protocol/.

You want You speak
find the service and its public channels XEP-0030 disco like any MUC service (disco#items on the domain lists public text channels), XEP-0128 forms, XEP-0433 search
see a room's channels and get told when they change the room JID is a pubsub service; its XEP-0503 space node (urn:xmpp:spaces:0) lists channels as XEP-0402 <conference> items with a small urn:tacky:muc2:0 extension (kind, position, category)
join a text channel as a plain MUC XEP-0045 with XEP-0421 occupant ids, XEP-0313 MAM, XEP-0359 stanza ids, XEP-0424/0425 retraction and moderation (tombstones, never deletion), XEP-0317 hats, XEP-0463 affiliation versions, XEP-0410 self-ping, XEP-0486 avatars, XEP-0500 slow mode, XEP-0444/0461/0308 as usual
join the room, not just a channel one IQ <join xmlns='urn:tacky:muc2:0'/> to the room: you get your occupant id, your effective permissions and your subscriptions; presence is optional afterwards
get messages while not "in" the channel ejabberd's MUC/Sub wire (urn:xmpp:mucsub:0) on every text channel, delivered to your bare JID so your server stores and pushes it
invite someone XEP-0488 tokens in the password key of a ?join URI, plus a preview IQ; XEP-0249 and mediated invites still work
know what a member may do hats carry permission sets; your self-presence and the join result carry <permissions xmlns='urn:tacky:muc2:perm:0'/>; per-channel overrides are one IQ
join voice <join xmlns='urn:tacky:muc2:voice:0'/> to the voice channel returns a LiveKit URL and token; who is in the call is a pubsub node everyone in the room can read without joining the media
read a feed channel XEP-0060 on the channel JID: a XEP-0472 feed node, XEP-0277 comment nodes, XEP-0470 reactions, XEP-0442 archive

Design rules that shape what you will see on the wire:

  • Every text channel is one bare JID (myproject.dev@muc2.example.org); the room JID (myproject@muc2.example.org) is also the room's default text channel, so any invite link lands in a chat a MUC client can open. Do not parse JIDs for structure; disco and the space node tell you.
  • One occupant id per person per room, shared by all its channels, on both the MUC face and the native face.
  • The component never trusts a client's own <occupant-id/>, <nick/> or <stanza-id/>; it stamps them itself.
  • Rooms are created explicitly (ad-hoc command or IQ), never by a presence to a new JID. Who may create is the component's policy, published in its disco#info.
  • Nothing is asked of your home server. That is the lesson of MIX.

How it relates to MUC, MIX, GC3 and New MUC

MUC (XEP-0045) stays as the compatibility face, in full. MIX (XEP-0369) gave the ideas of persistent membership, pubsub-backed structure and stable participant ids, but needed every home server to change, so it never shipped; MUC2 takes the ideas and drops the requirement. The XSF community's "GC3" notes (Matthew Wild, Jonas Schäfer, Kevin Smith) settled many of the same questions; MUC2 follows their agreed points and Jonas's element names where they fit. "New MUC" (Dave Cridland, 2026) used the shortname MUC2 for a narrower proposal that Council sent back; MUC2 here is a successor that keeps its requirement list. The aim is a ProtoXEP once two implementations exist.

The code

One executable, dist/muc2: the component's Tcl (component/) appended to libtacky's tackyd, the interpreter with libtacky inside. State is SQLite (or PostgreSQL in a cluster); several instances share it and one holds the component connection at a time through a lease. Builds and tests run in libtacky's container image: make component, make test. Layout and build model follow the sibling gateways tackygram and deltagram, minus their engines: MUC2 has no foreign protocol to wrap, so there is no second language.

License: see LICENSE.

The code by component, generated by tools/stats.py (make stats; the coverage column by make coverage-all):

component language what it is code tests coverage
store Tcl store.tcl: the SQLite store, its schema, migrations and fencing (§10) 751 241 100.0 % procs
perm Tcl perm.tcl: the permission engine: catalogue, built-in hats, evaluation, hierarchy, legacy projection (§4.1-4.3) 255 161 100.0 % procs
rooms and addressing Tcl rooms.tcl: rooms and channels created, updated, destroyed; addr.tcl: slugs, aliases, gone; policy.tcl: who may create (§2.1, §5.1) 661 222 100.0 % procs
pubsub Tcl pubsub.tcl: the room as a pubsub service, the XEP-0503 space node (§2.3) 306 153 100.0 % procs
members Tcl members.tcl: the native join and leave, subscriptions, participants, summary, nick (§3) 362 177 100.0 % procs
invites Tcl invites.tcl: XEP-0488 tokens with MUC2's extensions, preview (§5.3) 282 143 100.0 % procs
hats Tcl hats.tcl: the XEP-0317 commands, overwrites, catalogue (§4.4) 312 134 100.0 % procs
mucface Tcl mucface.tcl: text channels as XEP-0045 rooms over libtacky's mucservice (§6); register.tcl: jabber:iq:register, the knock form; mucsub.tcl: MUC/Sub and XEP-0452 passive delivery (§3.4) 1,066 869 100.0 % procs
service and main Tcl service.tcl: setup, the iq dispatcher, warm-up, disco (§2.2); main.tcl: options, the component; standby.tcl: the lease (§10); util.tcl, load.tcl 604 165 100.0 % procs
everything else make, Dockerfile, sh, Python, Tcl the Makefile, Dockerfile, test harness and tools/ 603 296 --
total (without everything else) Tcl 4,599 4,599 2,265 Tcl 100.0 % procs

code: lines without blanks and comments; libtacky is not counted, and the everything else row is not in the total. tests: test lines per component (COMPONENTS in tools/stats.py). coverage: procedures of component/ called by the unit suites or by the component under the e2e (ejabberd), from the make coverage-all run on 2026-11-21 at commit 6e7f873.

4,599 lines of code (Tcl 4,599), 2,265 lines of tests, 198 test cases defined. Coverage: Tcl 100.0 % procs (make coverage-all on 2026-11-21 at commit 6e7f873).

suite family files cases
unit (fakepeer): store 1 28
unit (fakepeer): perm 1 17
unit (fakepeer): rooms and addressing 1 26
unit (fakepeer): pubsub 1 16
unit (fakepeer): members 1 18
unit (fakepeer): invites 1 14
unit (fakepeer): hats 1 14
unit (fakepeer): mucface 3 40
unit (fakepeer): service and main 2 15
e2e: dist/muc2 on ejabberd and Prosody, libtacky's client (tests/e2e/) 1 10
total 13 198

cases: the tests a tcltest suite defines (a test in a loop counts once). make stats regenerates these numbers; the coverage comes from the last make coverage-all, its full report (with the procedures never called) in _build/cov/REPORT.md.

Building and running

Everything builds and tests in libtacky's container image (podman or docker):

goal does
make component (make build) dist/muc2: libtacky's tackyd with component/ appended
make test the unit suites (tests/unit/test_*.tcl), SUITES=test_perm.tcl for one
make stats, make stats-check README's generated numbers rewritten, or checked for staleness
make coverage-all the unit suites and the e2e recording the procedures they call; the figures into README
make e2e end to end: dist/muc2 on libtacky's ejabberd rig, driven by libtacky's own client (tests/e2e/); E2E_SERVER=prosody for the Prosody rig, E2E_PORT_BASE (63000) for its ports
make image the runtime image: dist/muc2 on Debian slim, data volume /var/lib/muc2
make clean dist/, _build/ and the submodule's build
muc2 -domain muc2.example.org -data /var/lib/muc2

The secret is COMPONENT_SECRET in the environment; MUC2_DOMAIN, MUC2_SERVER, MUC2_HOST, MUC2_PORT and MUC2_CREATION_TOKENS stand in for their options. The rest (who may create rooms, room and invite limits, the rules URL, the invite landing base, -lease sqlite or -lease file for active and standby instances, of which only the lease holder connects) is in the header of component/main.tcl. Where each part of the design lives: docs/files.md.