{"id":18082974,"url":"https://github.com/progval/matrix2051","last_synced_at":"2025-04-07T14:11:33.046Z","repository":{"id":40592445,"uuid":"404474138","full_name":"progval/matrix2051","owner":"progval","description":"A Matrix gateway for IRC: connect to Matrix from your favorite IRC client.","archived":false,"fork":false,"pushed_at":"2025-03-28T22:35:36.000Z","size":849,"stargazers_count":86,"open_issues_count":43,"forks_count":11,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-31T13:15:41.580Z","etag":null,"topics":["chat","irc","ircv3","matrix"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/progval.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-08T19:40:28.000Z","updated_at":"2025-03-28T22:35:40.000Z","dependencies_parsed_at":"2023-02-18T16:32:33.589Z","dependency_job_id":"c40364b8-7288-4d0a-919c-aa09bfcc5675","html_url":"https://github.com/progval/matrix2051","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progval%2Fmatrix2051","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progval%2Fmatrix2051/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progval%2Fmatrix2051/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progval%2Fmatrix2051/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/progval","download_url":"https://codeload.github.com/progval/matrix2051/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247666014,"owners_count":20975788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chat","irc","ircv3","matrix"],"created_at":"2024-10-31T14:06:36.016Z","updated_at":"2025-04-07T14:11:33.025Z","avatar_url":"https://github.com/progval.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matrix2051\n\n*Join Matrix from your favorite IRC client*\n\nMatrix2051 (or M51 for short) is an IRC server backed by Matrix. You can also see it\nas an IRC bouncer that connects to Matrix homeservers instead of IRC servers.\nIn other words:\n\n```\n         IRC client\n  (eg. weechat or hexchat)\n             |\n             |     IRC protocol\n             v\n         Matrix2051\n             |\n             |     Matrix protocol\n             v\n     Your Homeserver\n     (eg. matrix.org)\n```\n\n\nGoals:\n\n1. Make it easy for IRC users to join Matrix seamlessly\n2. Support existing relay bots, to allows relays that behave better on IRC than\n   existing IRC/Matrix bridges\n3. Bleeding-edge IRCv3 implementation\n4. Very easy to install. This means:\n   1. as little configuration and database as possible (ideally zero)\n   2. small set of depenencies.\n\nNon-goals:\n\n1. Being a hosted service (it would require spam countermeasures, and that's a lot of work).\n2. TLS support (see previous point). Just run it on localhost. If you really need it to be remote, access it via a VPN or a reverse proxy.\n3. Connecting to multiple accounts per IRC connection or to other protocols (à la [Bitlbee](https://www.bitlbee.org/)). This conflicts with goals 1 and 4.\n4. Implementing any features not natively by **both** protocols (ie. no need for service bots that you interract with using PRIVMSG)\n\n## Major features\n\n* Registration and password authentication\n* Joining rooms\n* Sending and receiving messages (supports formatting, multiline, highlights, replying, reacting to messages)\n* Partial [IRCv3 ChatHistory](https://ircv3.net/specs/extensions/chathistory) support;\n  enough for Gamja to work.\n  [open chathistory issues](https://github.com/progval/matrix2051/milestone/3)\n* [Partial](https://github.com/progval/matrix2051/issues/14) display name support\n\n## Shortcomings\n\n* [Direct chats are shown as regular channels, with random names](https://github.com/progval/matrix2051/issues/11)\n* Does not \"feel\" like a real IRC network (yet?)\n* User IDs and room names are uncomfortably long\n* Loading the nick list of huge rooms like #matrix:matrix.org overloads some IRC clients\n* IRC clients without [hex color](https://modern.ircdocs.horse/formatting.html#hex-color)\n  support will see some garbage instead of colors. (Though colored text seems very uncommon on Matrix)\n* IRC clients without advanced IRCv3 support work miss out on many features:\n  [quote replies](https://github.com/progval/matrix2051/issues/16), reacts, display names.\n\n## Screenshot\n\n![screenshot of #synapse:matrix.org with Element and IRCCloud side-by-side](https://raw.githubusercontent.com/progval/matrix2051/assets/screenshot_element_irccloud.png)\n\nTwo notes on this screenshot:\n\n* [Message edits](https://spec.matrix.org/v1.4/client-server-api/#event-replacements) are rendered with a fallback, as message edits are [not yet supported by IRC](https://github.com/ircv3/ircv3-specifications/pull/425),\n* Replies on IRCCloud are rendered with colored icons, and clicking these icons opens a column showing the whole thread. Other clients may render replies differently.\n\n## Usage\n\n* Install system dependencies. For example, on Debian: `sudo apt install elixir erlang erlang-dev erlang-inets erlang-xmerl`\n* Install Elixir dependencies: `mix deps.get`\n* Run tests to make sure everything is working: `mix test`\n* Run: `mix run matrix2051.exs`\n* Connect a client to `localhost:2051`, with the following config:\n  * no SSL/TLS\n  * SASL username: your full matrix ID (`user:homeserver.example.org`)\n  * SASL password: your matrix password\n\nSee below for extra instructions to work with web clients.\n\nSee `INSTALL.md` for a more production-oriented guide.\n\n## Architecture\n\n* `matrix2051.exs` starts M51.Application, which starts M51.Supervisor, which\n  supervises:\n  * `config.ex`: global config agent\n  * `irc_server.ex`: a `DynamicSupervisor` that receives connections from IRC clients.\n\nEvery time `irc_server.ex` receives a connection, it spawns `irc_conn/supervisor.ex`,\nwhich supervises:\n\n* `irc_conn/state.ex`: stores the state of the connection\n* `irc_conn/writer.ex`: genserver holding the socket and allowing\n  to write lines to it (and batches of lines in the future)\n* `irc_conn/handler.ex`: task busy-waiting on the incoming commands\n  from the reader, answers to the simple ones, and dispatches more complex\n  commands\n* `matrix_client/state.ex`: keeps the state of the connection to a Matrix homeserver\n* `matrix_client/client.ex`: handles one connection to a Matrix homeserver, as a single user\n* `matrix_client/sender.ex`: sends events to the Matrix homeserver and with retries on failure\n* `matrix_client/poller.ex`: repeatedly asks the Matrix homeserver for new events (including the initial sync)\n* `irc_conn/reader.ex`: task busy-waiting on the incoming lines,\n  and sends them to the handler\n\nUtilities:\n\n* `matrix/raw_client.ex`: low-level Matrix client / thin wrapper around HTTP requests\n* `irc/command.ex`: IRC line manipulation, including \"downgrading\" them for clients\n  that don't support some capabilities.\n* `irc/word_wrap.ex`: generic line wrapping\n* `format/`: Convert between IRC's formatting and `org.matrix.custom.html`\n* `matrix_client/chat_history.ex`: fetches message history from Matrix, when requested\n  by the IRC client\n\n## Questions\n\n### Why?\n\nThere are many great IRC clients, but I can't find a Matrix client I like.\nYet, some communities are moving from IRC to Matrix, so I wrote this so I can\njoin them with a comfortable client.\n\nThis is also a way to prototype the latest IRCv3 features easily,\nand for me to learn the Matrix protocol.\n\n### What IRC clients are supported?\n\nIn theory, any IRC client should work. In particular, I test it with\n[Gamja](https://git.sr.ht/~emersion/gamja/), [IRCCloud](https://www.irccloud.com/),\n[The Lounge](https://thelounge.chat/), and [WeeChat](https://weechat.org/).\n\nPlease open an issue if your client has any issue.\n\n### What Matrix homeservers are supported?\n\nIn theory, any, as I wrote this by reading the Matrix specs.\nIn practice, this is only tested with [Synapse](https://github.com/matrix-org/synapse/).\n\nA notable exception is registration, which uses a Synapse-specific API\nas Matrix itself does not specify registration.\n\nPlease open an issue if you have any issue with your homeserver\n(a dummy login/password I can use to connect to it would be appreciated).\n\n### Are you planning to support features X, Y, ...?\n\nAt the time of writing, if both Matrix and IRC/IRCv3 support them, Matrix2051 likely will.\nTake a look at [the list of open 'enhancement' issues](https://github.com/progval/matrix2051/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement).\n\nA notable exception is [direct messages](https://github.com/progval/matrix2051/issues/11),\nbecause Matrix's model differs significantly from IRC's.\n\n### Can I connect with a web client?\n\nTo connect web clients, you need a websocket gateway.\nMatrix2051 was tested with [KiwiIRC's webircgateway](https://github.com/kiwiirc/webircgateway)\n(try [this patch](https://github.com/kiwiirc/webircgateway/pull/91) if you need to run it on old Go versions).\n\nHere is how you can configure it to connect to Matrix2051 with [Gamja](https://git.sr.ht/~emersion/gamja/):\n\n```toml\n[fileserving]\nenabled = true\nwebroot = \"/path/to/gamja\"\n\n\n[upstream.1]\nhostname = \"localhost\"\nport = 2051\ntls = false\n# Connection timeout in seconds\ntimeout = 20\n# Throttle the lines being written by X per second\nthrottle = 100\nwebirc = \"\"\nserverpassword = \"\"\n```\n\n### What's with the name?\n\nThis is a reference to [xkcd 1782](https://xkcd.com/1782/):\n\n![2004: Our team stays in touch over IRC. 2010: Our team mainly uses Skype, but some of us prefer to stick to IRC. 2017: We've got almost everyone on Slack, But three people refuse to quit IRC and connect via gateway. 2051: All consciousnesses have merged with the Galactic Singularity, Except for one guy who insists on joining through his IRC client. \"I just have it set up the way I want, okay?!\" *Sigh*](https://imgs.xkcd.com/comics/team_chat.png)\n\n### I still have a question, how can I contact you?\n\nJoin [#matrix2051 at irc.interlinked.me](ircs://irc.interlinked.me/matrix2051).\n(No I am not eating my own dogfood, I still prefer \"native\" IRC.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogval%2Fmatrix2051","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogval%2Fmatrix2051","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogval%2Fmatrix2051/lists"}