1# hii23A file-based IRC client inspired by [ii(1)][ii homepage].45## Motivation67I originally only intended to write a frontend for ii instead of8completely rewriting it from scratch. However, while working on the9frontend I noticed that I couldn't implement certain features in the10frontend without changes to the backend (ii). I briefly considered11patching ii but ultimately decided for a rewrite. During the rewrite,12various features have been implemented that are not supported by ii13(e.g. various IRCv3 features, builtin TLS and IPv6 support, et cetera).1415## Status1617I currently consider hii feature complete and use it myself daily in18combination with [insomnia][insomnia github] and a per-server19[runit][runit homepage] [user service][runit user] for automatically20starting and supervising hii processes.2122## Features2324New features (compared to ii):2526* Memory safety27* A proper IRC protocol implementation through [girc][girc repo]28* Support for automatically joining channels on startup29* Support for [IRCv3.2 monitoring][ircv3.2 monitor]30* Support for a per-channel nick list using a UNIX domain socket31* Support for recording messages mentioning the users32* Support for authentication using TLS client certificates (CertFP)33 * [Most][libera certfp] [IRC][oftc certfp] [networks][hackint certfp] support CertFP34 * This can be used in conjunction with the [SASL EXTERNAL][sasl mechanisms] mechanism35* Built-in TLS support36* Built-in IPv6 support3738Features intentionally not implemented:3940* Automatic authorization using the [PASS command][password message] is41 not implemented (ii `-k` flag).42* Shortcut commands, e.g. `/j`. If you need them write yourself a shell43 script for mapping shortcut commands to real commands.4445While hii has more features than ii it is still supposed to have a limit46feature set and shouldn't ["expand until it can read mail"][jwz's law].4748### Compatibility with ii4950Backwards compatibility with ii wasn't a goal. While the directory51structure is mostly backwards compatible everything else is pretty much52different. This is the case because proper backwards compatibility would53have been a lot of work and I personally didn't need it.5455## Installation5657The program can be installed either using `go install` or `make`.5859### go install6061To install to the program using `go install` run the following command:6263 $ go install github.com/nmeum/hii@latest6465Note that this will not install additional documentation files, e.g. man pages.6667### make6869To install to the program using `make` run the following commands:7071 $ git clone https://github.com/nmeum/hii.git72 $ cd hii73 $ make && make install7475This will also install documentation files to the correct location and76may thus be preferable when packaging this software for a distribution.7778## FAQ7980**Q:** Sockets cannot be used with standard utilities such as `grep(1)`.81Why are nick names served using a unix domain socket anyhow?8283**A:** Several ways of implementing a nick list have been considered.84Using a regular file has various obvious disadvantages. For instance,85the file would need to be truncated every time the nick list changes,86which causes a lot of file system operation. Using a FUSE for serving87the nick list was also briefly considered, however, while this would88allow interaction with standard utilities it would require linking89against FUSE and would complicate things quite a bit. Serving nicks90using a unix domain socket seemed to be a reasonable compromise.9192**Q:** Why are mentions recorded in a separate file? Can't this be93implemented using inotify, kqueue, … in the frontend?9495**A:** While this might certainly be possible it would complicate the96frontend code quite a bit. Implementing this in the backend was fairly97easy and only required a few changes. Additionally, neither kqueue nor98inotify are mandated by POSIX.99100**Q:** Can feature X/Y/Z be added to hii?101102**A:** No.103104## License105106This program is free software: you can redistribute it and/or modify it107under the terms of the GNU General Public License as published by the108Free Software Foundation, either version 3 of the License, or (at your109option) any later version.110111This program is distributed in the hope that it will be useful, but112WITHOUT ANY WARRANTY; without even the implied warranty of113MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General114Public License for more details.115116You should have received a copy of the GNU General Public License along117with this program. If not, see <http://www.gnu.org/licenses/>.118119[ii homepage]: https://tools.suckless.org/ii/120[girc repo]: https://github.com/lrstanley/girc121[password message]: https://tools.ietf.org/html/rfc1459#section-4.1.1122[libera certfp]: https://libera.chat/guides/certfp123[oftc certfp]: https://www.oftc.net/NickServ/CertFP/124[hackint certfp]: https://www.hackint.org/services#NickServ125[jwz's law]: https://en.wikipedia.org/wiki/Zawinski's_law_of_software_envelopment#Principles126[ircv3.2 monitor]: https://ircv3.net/specs/core/monitor-3.2.html127[insomnia github]: https://github.com/nmeum/insomnia128[runit homepage]: http://smarden.org/runit/129[runit user]: http://smarden.org/runit/faq.html#userservices130[sasl mechanisms]: https://ircv3.net/docs/sasl-mechs