Better replies support

[selfhoster1312]

There's a few shortcomings with the current implementation of message replies:

• sending a message to a network currently expects to return the associated message ID immediately, but this prevents an asynchronous design:
  • most networks will require a response from the server to assign the ID, blocking the main thread
  • XMPP does not even get the assigned ID as a response to the sending action, but in a separate message
• a bridged message may be split into several message for sending, and the current implementation only allows to return 1 message ID:
  • a message may be split because of length limit
  • or because separate attachments (eg. images) require separate messages
• matterbridge does not store original message bodies internally, and thus requires each bridge to destructure/reformat the original message quote on its own (which is error prone, and would force each bridge to implement a message cache to keep the texts around)
• from my understanding, the mapping of original ID -> bridge IDs is untyped, therefore collisions are possible actually it's not exactly typed but all IDs are prefixed with the protocol, see here

We should definitely come up with a new architecture which would allow us to send every new message in a separate goroutine and stop blocking the main thread.

[selfhoster1312]

Some thoughts by @kousu here #134 (comment) :

It would make sense to implement in xmppo/go-xmpp#226 and replace this loop with it before merging. If so, I propose we'll have to add a new config.Message.ParentText and fill it in in this PR. Then it would be good enough to merge.

Then i propose we would:

• In the short term, adapt all the other bridges to read and write ParentText. (e.g. adjust Support Discord Reply (fix #43) #124 to write into ParentText instead of preparing a quote)
• In the medium term, add a local message cache to gateway.go, and replace ParentText with a helper method ParentText(), so that there's no need for blocking calls to look it up like in Support Discord Reply (fix #43) #124 .

If you don't mind continuing the discussion on this issue!

[selfhoster1312]

I would propose going the other way around. Filling Message.ParentText manually means duplicating the effort.

Very initial draft idea, add three fields to gateway:

• MessageText map<ORIGINBRIDGE, map<ORIGINID, BODY>>
• SentMessageIDs map<ORIGINBRIDGE, map<ORIGINID, list<tuple(DESTINATIONBRIDGE, DESTINATIONID)>>>
• ReverseMessageIDs map<DESTINATIONBRIDGE, map<DESTINATIONID, (ORIGINBRIDGE, ORIGINID)>>`

SendMessageIDs is used when the same bridge which relayed a message receives a response for that message, so the gateway can add the list of destination IDs it replies to in eg. Message.LocalParents for processing by the remote bridges.

ReverseMessageIDs is used when a different bridge receives a reply, so the receiving bridge can set Message.LocalParents to the local ID it received a response to, the the gateway:

• finds the original text and populates the Message.ParentText field
• find the original message ID, then find all corresponding destination IDs for each bridge in Message.LocalParents

That's a very rough first idea. It's far from optimized but:

• keeping a 1000 messages for each bridge, for ~1000 characters per message for 10 bridges is on the order of magnitude of 10MB RAM (more than OK)
• the complex mappings require hashing therefore CPU cycles, but that's entirely negligible unless you're running channels with thousands of members on a potato (modern hash tables perform in ns-µs per operation)

Two more questions:

• could we remove some nesting in the mappings by storing them in the bridger instances?
• can/should we store replies (LRU or FIFO cache) on disk so it's saved across restarts and we don't lose that useful context?

Ideas are welcome. Critique is very welcome too!

[kousu]

SentMessageIDs exists already as gw.Messages. It's a Map<MatterbridgeID, Set<MatterbridgeID>>, if you'll excuse the pseudo-types. It's also used in lieu of ReverseMessageIDs.

And a MatterbridgeID is a string that looks like "{PROTOCOL} {PROTOCOL_SPECIFIC_ID}" (note line 66).

Code tracing

gw.Messages is examined here:

matterbridge/gateway/gateway.go

Lines 64 to 82 in 47b80d7

	// FindCanonicalMsgID returns the ID under which a message was stored in the cache.
	func (gw *Gateway) FindCanonicalMsgID(protocol string, mID string) string {
	ID := protocol + " " + mID
	if gw.Messages.Contains(ID) {
	return ID
	}
	// If not keyed, iterate through cache for downstream, and infer upstream.
	for _, mid := range gw.Messages.Keys() {
	v, _ := gw.Messages.Peek(mid)
	ids := v.([]*BrMsgID)
	for _, downstreamMsgObj := range ids {
	if ID == downstreamMsgObj.ID {
	return mid.(string)
	}
	}
	}
	return ""
	}

via

matterbridge/gateway/handlers.go

Lines 180 to 183 in 47b80d7

	var canonicalParentMsgID string
	if rmsg.ParentID != "" && dest.GetBool("PreserveThreading") {
	canonicalParentMsgID = gw.FindCanonicalMsgID(rmsg.Protocol, rmsg.ParentID)
	}

and used by the reply system (this line essentially is the reply "system" as far as I can tell)

matterbridge/gateway/gateway.go

Lines 491 to 494 in 47b80d7

	msg.ParentID = gw.getDestMsgID(canonicalParentMsgID, dest, channel)
	if msg.ParentID == "" {
	msg.ParentID = strings.Replace(canonicalParentMsgID, dest.Protocol+" ", "", 1)
	}

In the trace you can see ParentID gets rewritten from 16f00813-76d2-47b9-aeb5-c94553e9a696 (in XMPP space) to 1474864894833856658 (in Discord space).

Example trace

[0015] DEBUG xmpp:         [handleXMPP:bridge/xmpp/xmpp.go:393] <= Sending message from kousu on xmpp.bridge to gateway
[0015] DEBUG xmpp:         [handleXMPP:bridge/xmpp/xmpp.go:394] <= Message is config.Message{Text:"Y", Channel:"testing", Username:"kousu", UserID:"testing@example.im/kousu", Avatar:"", Account:"xmpp.bridge", Event:"", Protocol:"", Gateway:"", ParentID:"16f00813-76d2-47b9-aeb5-c94553e9a696", Timestamp:time.Date(1, time.January, 1, 0, 0, 0, 0, time.UTC), ID:"8d6eca35-4579-4152-95d5-ec48205382b8", Extra:map[string][]interface {}(nil)}
[0015] DEBUG gateway:      [SendMessage:gateway/gateway.go:513] => Sending config.Message{Text:"Y", Channel:"testing", Username:"kousu", UserID:"testing@example.im/kousu", Avatar:"", Account:"xmpp.bridge", Event:"", Protocol:"xmpp", Gateway:"sunny-test", ParentID:"16f00813-76d2-47b9-aeb5-c94553e9a696", Timestamp:time.Date(2026, time.February, 21, 15, 26, 37, 275108467, time.Local), ID:"8d6eca35-4579-4152-95d5-ec48205382b8", Extra:map[string][]interface {}(nil)} from xmpp.bridge (testing) to discord.bridge (ID:289432897427348374)
[0015] DEBUG discord:      [Send:bridge/discord/discord.go:259] => Receiving config.Message{Text:"Y", Channel:"ID:289432897427348374", Username:"<kousu> ", UserID:"testing@example.im/kousu", Avatar:"", Account:"xmpp.bridge", Event:"", Protocol:"xmpp", Gateway:"sunny-test", ParentID:"1474864894833856658", Timestamp:time.Date(2026, time.February, 21, 15, 26, 37, 275108467, time.Local), ID:"", Extra:map[string][]interface {}(nil)}

Pencilling

I think it's cleaner to keep a single source of truth and translate bridge ID -> matterbridge ID -> bridge ID instead of trying to remember all bridge -> bridge pairs and follow different code paths for incoming and outgoing. So no, don't try to hide those in the bridges at all, keep a single control list in gateway.

But the types and names could use work.

Let's maybe make MatterbridgeID explicit

type MatterbridgeID struct {
    Bridge string  # e.g. "xmpp.bridge", whatever is in the config file
    mID string      # e.g. "8d6eca35-4579-4152-95d5-ec48205382b8""
}

gw.Messages is better named gw.MessageMap.

Then could gw.MessageText be gw.Messages Map<MatterbridgeID, config.Message>? I suspect we'll find we need to look at the metadata later, too.

config.Message.ParentID should be canonicalized (i.e. converted to a MatterbridgeID) when received from the incoming bridge right around here (though tricky if we add stronger typing but I'm sure we'll sort it):

matterbridge/gateway/router.go

Lines 143 to 145 in 47b80d7

	// Set message protocol based on the account it came from
	msg.Protocol = r.getBridge(msg.Account).Protocol

Storage

can/should we store replies (LRU or FIFO cache) on disk so it's saved across restarts and we don't lose that useful context?

I would like this 🌟 ! I would really like to improve bridging fidelity and being able to reply to long ago messages is a part of that.

It's a big change though! It makes matterbridge stateful. It's nice to be able to move the bridge around cleanly with the only input being matterbridge.toml, and it's really nice to not have to worry about leaking data.

It's too bad more protocols don't supply reply tags; then we could rely on examining, let's see, something like

LocalParents = [m.ID for m in gw.MessageMap.Get(gw.Messages.Get(canonicalID).ParentID) where m.Bridge == br.Name]

and only forward IDs and not store contents. I would still in any case like to store the IDs to disk to improve fidelity, and, I guess, we're pretty much convinced we can't support all the protocols without caching the contents too.

[selfhoster1312]

Sidenote about whether to store message text in a gateway map, or in each bridge: if we want to support replies in the matterbridge API, then it makes sense to store them in the gateway and not force the API consumer to perform that on its own.

[selfhoster1312]

Wow, thanks for this great investigation @kousu! You really outlined how upstream actually implemented most of what we need already, even though it lacks documentation and an async message-passing design.

Let's maybe make MatterbridgeID explicit

That looks great! However are we sure all protocols guarantee unique message IDs across all rooms? Maybe that's not needed because it would be implemented at the Gateway level and not at the global Router level? Still worth thinking through. So my understanding is either use BrMsgID everywhere or deprecate it entirely in favor of MatterbridgeID?

It's nice to be able to move the bridge around cleanly with the only input being matterbridge.toml

I think you would not lose features compared to today if we added message storage. You could still move around matterbridge.toml and it would still work, albeit with a degraded reply experience until the message cache is populated again. We could also probably repopulate the message cache on startup on some networks, such as xmpp/matrix/ircv3 so i don't think it's a blocker.

and it's really nice to not have to worry about leaking data.

That's a good point! I think the retention policy is another thing we have to think through (especially with the mediaserver integration). In the meantime, i think a FIFO with both a maximum duration (eg. 1 week) and a maximum number of items (eg. 1000 per channel) is an acceptable tradeoff.

[kousu]

However are we sure all protocols guarantee unique message IDs across all rooms?

either use BrMsgID everywhere or deprecate it entirely in favor of MatterbridgeID?

I think we need to keep both. The gateway needs to remember the mapping.

if we want to support replies in the matterbridge API, then it makes sense to store them in the gateway and not force the API consumer to perform that on its own.

100% #134 stores the reply IDs in the bridge but only out of actual necessity 🙄

[selfhoster1312]

Also we need to make sure that the message ID map design allows us to:

• avoid propagating a reply on the origin bridge back to the origin bridge
• avoid propagating a reply for every split message to a destination bridge, eg. on xmpp with several file uploads, we may want to reply only to the canonical message announcing the first file upload with the caption… while still allowing replies to any of the split messages on destination (xmpp) to be mapped back to the same origin message

[kousu]

Note to remember:

#124 added QuoteDisable as a setting on the source bridge -- currently only for Discord.

This setting should:

1. be attached to destination bridges, especially ones that do not support reply tags (so, IRC).
2. be named QuoteEnable to avoid double negatives

The receiving bridge deciding on whether to inject a quote means that every sending bridge has to suffer clutter even if they are perfectly capable of doing reply links (see e.g. #152 for a result of this).

[kousu]

• Consider detecting and filtering out RemoteNickFormat from the Quote; be careful not to filter it unless it's a reply to a message the bridge sent
• Perhaps add config.EventReply to the list of possible events? But a reply is usually also a message so it's ambiguous...