ReflectionIRCd

ReflectionIRCd is an IRCd that bridges Matrix, allowing you to use an IRC client to chat on Matrix. See the support matrix (pun intended) for what it can do. The issue tracker is here: https://todo.sr.ht/~emerson/reflectionircd

Highlights

• IRC first: The goal is for modern IRC clients to have feature parity with any other Matrix client
• Standalone: Uses the Client-Server API, so you can use it with any homeserver

Running

Copy config.example.json to config.json, and edit the values:

• serverName is the name of the IRC server
• port is the listening port of the server
• certFile and keyFile are the SSL cert and key for Reflection to use
• lazyLoadLimit is the limit for "lazy load" mode. In lazy load mode, only room members with PL > 0 are shown right away, everyone else is joined once they send an event to the room. This prevents clients crashing or lagging on large rooms.
• syncTimeout is the number of milliseconds to ask the homeserver to hold the sync open. 15000 seems to be the de-facto number.
• lagWarningLimit is the number of milliseconds that will trigger a "Sync is lagging" message to warn of a lagging homeserver. If you run your own HS, setting it to 2000 more than syncTimeout will help you diagnose issues. Larger servers like matrix.org often have a 5-10 second lag time, so increase this to prevent your screen filling with lag warnings.
• mxid is the MXID of your Matrix user
• homeserver is the URL of your homeserver. You get this value in Element by going to Settings > Help and About > Advanced
• accessToken is the access token to use. You get this value underneath the homserver URL in Element.
• saslPassword is the SASL password to use when connecting to Reflection

If you're running multiple instances, use multiple config files, i.e. config-matrix.json or config-aria.json.

Then npm ci, npm run build, and node reflection.js config.json (replace config.json if you named your config differently). You'll see a message about starting initial sync, and then "Synced to network!". Once it's synced, you can connect with your client, specifying the SASL password you put in the config (SASL username doesn't matter).

Known issues

• Encrypted rooms don't work. In theory you can use pantalaimon, however I haven't tried it yet.
• You can't /join channels. However, if you join a channel via Element (other clients are available), it will auto-join your IRC client to it.
• You can't open a PM to individual users, since a "PM" in Matrix is just another room, and you can't join rooms from IRC.
• There's no IRC equivalent to Spaces. Since they are just regular rooms, they show up in IRC as just regular rooms, however, you can't send messages to them.
• In order to highlight users, you need to prefix their nick with an @, so @emerson: hi. Reflection automatically expands this to the user's MXID, so even though it's annoying, it's needed to stop inadvertent highlights for now.
• In general, Reflection trusts IRC clients to do the right thing, and doesn't have a lot of error-checking of IRC messages (it does have robust error checking for the Matrix side because Matrix sends a lot of error-filled messages).

Compatibility

Because Matrix and IRC are open protocols, there's no way for me to test every single implementation, so here's a list of what I test on. If you see a bug in a specific Matrix or IRC client, please join the support channel and report it. If it's a closed instance, please DM/PM me a login and I'll look into it.

Matrix

Reflection implements features straight from the Client-Server spec, so any homeserver that conforms to the specification will be compatible. I only test Synapse right now, if you know of an open Dendrite or Conduit homeserver, let me know!

IRC

I regularly test on Weechat, Gamja (using Soju), and The Lounge. Any actively maintained IRC client will be able to have basic functionality, although no free IRC clients currently support things like reactions, message editing/deleting, and channel renaming. If you're using multiple clients, it's best to use a bouncer like Soju to connect to Reflection, and then connect your clients to Soju.

FAQs

Who is this for?

It's for people who want to use their IRC client to chat on Matrix. It's like Bitlbee or Matterbridge, but focused specifically on IRC <-> Matrix, as well as being a reference server for IRCv3 specifications.

Why are there different channel prefixes?

Because matrix room names are often long and have characters that IRC channel names can't use, Reflection attempts to find a suitable IRC equivalent

# channels are channels that have a canonical alias to use. & channels are DMs. ! channels are the room IDs of channels whose names can't be converted into IRC-friendly names.

Why do messages appear out of order?

If you have server-time enabled on your client, you might find messages arriving late or out of order. Similarly, if you're joined to the same channel from different homeservers, you may see messages appear on one several minutes/hours before the other(s). This is called "federation", and is considered a feature of Matrix.

What does "Sync is lagging" mean?

The matrix sync is set with a timeout of 15 seconds (configurable in milliseconds as the syncTimeout value in the config file). The server is supposed to return an HTTP response after the timeout (if not sooner). If the server doesn't respond after 20 seconds (also configurable as lagWarningLimit), that message is printed to the console to warn you that the homeserver is lagging.

Why is there a random JSON object in my console?

That means you were sent an event type that I didn't know existed. Please hop into the chat and tell me what the type value is.

Support

The main chat is #reflectionircd on Libera (webchat), which is available on Matrix at #reflectionircd:matrix.org. Testing channels are #reflectionircd-test on Libera, #reflectionircd-test:matrix.org (portal to Libera), and #reflection-matrix-test:matrix.org (not linked to IRC). Please test in the testing channels and not in the main channel.

On Libera I'm emerson, on Matrix I'm @emersonveenstra:matrix.org, feel free to ping me in the channel with any questions/bug reports/complaints.

Feature support

✅ - Implemented
🟨 - Partially implemented, see notes
❌ - Not implemented

(IRCv3) denotes IRC features that might not be available in all clients

Name	M->I	I->M	Notes
text, notice, emote messages	✅	✅
image, sticker, file, audio, video messages	🟨	❌	Show up as links on IRC
Channel joins	✅	❌	#1
Channel parts	✅	✅
Channel kicks	✅	✅
Channel bans	🟨	❌	#24 Single-user bans show up on IRC as kicks, there's no banlist yet
Channel invites	✅	✅
Channel topics	✅	✅
Channel powers	✅	❌	#6
Channel lists/searching	❌	❌	#30
Encrypted rooms	❌	❌	#20
Rich text	❌	❌	#31
Presence	✅	✅	Not all homeservers have presence enabled
Channel renaming (IRCv3)	✅	❌	#16
Message replies (IRCv3)	✅	✅	Clients without support will still receive the reply message, but it won't be marked as a reply
Message reactions (IRCv3)	✅	✅
Extended invites (IRCv3)	✅	✅
Typing notifications (IRCv3)	✅	✅	Not all servers or clients send typing indicators
Chat history (IRCv3)	❌	❌	#9
Multiline messages (IRCv3)	✅	✅
Global display names (IRCv3)	❌	❌	#11
Per-room display names (IRCv3)	❌	❌	#13
Message editing (IRCv3)	❌	❌	#14
Message deletion/redaction (IRCv3)	✅	✅