hii

A file-based IRC client inspired by ii

git clone https://git.8pit.net/hii.git

  1# hii
  2
  3A file-based IRC client inspired by [ii(1)][ii homepage].
  4
  5## Motivation
  6
  7I originally only intended to write a frontend for ii instead of
  8completely rewriting it from scratch. However, while working on the
  9frontend I noticed that I couldn't implement certain features in the
 10frontend without changes to the backend (ii). I briefly considered
 11patching ii but ultimately decided for a rewrite. During the rewrite,
 12various features have been implemented that are not supported by ii
 13(e.g. various IRCv3 features, builtin TLS and IPv6 support, et cetera).
 14
 15## Status
 16
 17I currently consider hii feature complete and use it myself daily in
 18combination with [insomnia][insomnia github] and a per-server
 19[runit][runit homepage] [user service][runit user] for automatically
 20starting and supervising hii processes.
 21
 22## Features
 23
 24New features (compared to ii):
 25
 26* Memory safety
 27* A proper IRC protocol implementation through [girc][girc repo]
 28* Support for automatically joining channels on startup
 29* Support for [IRCv3.2 monitoring][ircv3.2 monitor]
 30* Support for a per-channel nick list using a UNIX domain socket
 31* Support for recording messages mentioning the users
 32* Support for authentication using TLS client certificates (CertFP)
 33    * [Most][libera certfp] [IRC][oftc certfp] [networks][hackint certfp] support CertFP
 34    * This can be used in conjunction with the [SASL EXTERNAL][sasl mechanisms] mechanism
 35* Built-in TLS support
 36* Built-in IPv6 support
 37
 38Features intentionally not implemented:
 39
 40* Automatic authorization using the [PASS command][password message] is
 41  not implemented (ii `-k` flag).
 42* Shortcut commands, e.g. `/j`. If you need them write yourself a shell
 43  script for mapping shortcut commands to real commands.
 44
 45While hii has more features than ii it is still supposed to have a limit
 46feature set and shouldn't ["expand until it can read mail"][jwz's law].
 47
 48### Compatibility with ii
 49
 50Backwards compatibility with ii wasn't a goal. While the directory
 51structure is mostly backwards compatible everything else is pretty much
 52different. This is the case because proper backwards compatibility would
 53have been a lot of work and I personally didn't need it.
 54
 55## Installation
 56
 57The program can be installed either using `go install` or `make`.
 58
 59### go install
 60
 61To install to the program using `go install` run the following command:
 62
 63	$ go install github.com/nmeum/hii@latest
 64
 65Note that this will not install additional documentation files, e.g. man pages.
 66
 67### make
 68
 69To install to the program using `make` run the following commands:
 70
 71	$ git clone https://github.com/nmeum/hii.git
 72	$ cd hii
 73	$ make && make install
 74
 75This will also install documentation files to the correct location and
 76may thus be preferable when packaging this software for a distribution.
 77
 78## FAQ
 79
 80**Q:** Sockets cannot be used with standard utilities such as `grep(1)`.
 81Why are nick names served using a unix domain socket anyhow?
 82
 83**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 serving
 87the nick list was also briefly considered, however, while this would
 88allow interaction with standard utilities it would require linking
 89against FUSE and would complicate things quite a bit. Serving nicks
 90using a unix domain socket seemed to be a reasonable compromise.
 91
 92**Q:** Why are mentions recorded in a separate file? Can't this be
 93implemented using inotify, kqueue, … in the frontend?
 94
 95**A:** While this might certainly be possible it would complicate the
 96frontend code quite a bit. Implementing this in the backend was fairly
 97easy and only required a few changes. Additionally, neither kqueue nor
 98inotify are mandated by POSIX.
 99
100**Q:** Can feature X/Y/Z be added to hii?
101
102**A:** No.
103
104## License
105
106This program is free software: you can redistribute it and/or modify it
107under the terms of the GNU General Public License as published by the
108Free Software Foundation, either version 3 of the License, or (at your
109option) any later version.
110
111This program is distributed in the hope that it will be useful, but
112WITHOUT ANY WARRANTY; without even the implied warranty of
113MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
114Public License for more details.
115
116You should have received a copy of the GNU General Public License along
117with this program. If not, see <http://www.gnu.org/licenses/>.
118
119[ii homepage]: https://tools.suckless.org/ii/
120[girc repo]: https://github.com/lrstanley/girc
121[password message]: https://tools.ietf.org/html/rfc1459#section-4.1.1
122[libera certfp]: https://libera.chat/guides/certfp
123[oftc certfp]: https://www.oftc.net/NickServ/CertFP/
124[hackint certfp]: https://www.hackint.org/services#NickServ
125[jwz's law]: https://en.wikipedia.org/wiki/Zawinski's_law_of_software_envelopment#Principles
126[ircv3.2 monitor]: https://ircv3.net/specs/core/monitor-3.2.html
127[insomnia github]: https://github.com/nmeum/insomnia
128[runit homepage]: http://smarden.org/runit/
129[runit user]: http://smarden.org/runit/faq.html#userservices
130[sasl mechanisms]: https://ircv3.net/docs/sasl-mechs