🆕 🎛️ irc: Clean up config options (fixes RITlug#113)

This commit reworks the IRC-side configuration options to support new parameters and configuration options: * **IRC_BOT_NAME**: IRC bot nick. Already existed, but now better documentation alongside other confusingly-named variables. * **IRC_BOT_REALNAME**: `REALNAME` field support. Allows freeform text. Added bot advertisement as a default option if left unset. * **IRC_BOT_IDENT**: Seldom used, but occasionally useful ident field. Overridden if NickServ credentials provided. * **IRC_NICKSERV_USER**: Explicitly set a NickServ username for a bot. Previously used the `IRC_BOT_NAME`, but those are not always identical in all situations. This commit also reworks the `env.example` file to better organize all IRC options, in addition to adding the new ones. I also expanded and reworked the config file glossary in the docs. This Pull Request does not implement tests, but I would like to ask to follow up on this in a subsequent Pull Request, preferably during the upcoming testing sprint. Fixes RITlug#113. cc: @alcir Signed-off-by: Justin W. Flory (he/him) <[email protected]>
jwflory · Oct 29, 2020 · 8aa8a21 · 8aa8a21
1 parent 7380c32
commit 8aa8a21
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 46 deletions.
diff --git a/docs/user/config-file-glossary.rst b/docs/user/config-file-glossary.rst
@@ -11,55 +11,88 @@ This glossary is intended for advanced users.
 IRC settings
 ************
 
-``IRC_BLACKLIST=""``
-    Comma-separated list of IRC nicks to ignore
-
-``IRC_BOT_NAME=teleirc``
-    IRC nickname for bot
-
-``IRC_CHANNEL="#channel"``
-    IRC channel for bot to join
-
-``IRC_CHANNEL_KEY=""``
-    IRC channel key, for password-protected channels
-
-``IRC_SEND_STICKER_EMOJI=true``
-    Send emojis associated with a sticker to IRC (when a Telegram user sends a sticker)
-
-``IRC_SEND_DOCUMENT=false``
-    Send documents and files from Telegram to IRC (`why is this false by default? <https://github.com/RITlug/teleirc/issues/115>`_)
 
-``IRC_PREFIX="<"``
-    Text displayed before Telegram name in IRC
 
-``IRC_SUFFIX=">"``
-    Text displayed after Telegram name in IRC
+Server connection settings
+==============================
 
 ``IRC_SERVER=chat.freenode.net``
     IRC server to connect to
 
 ``IRC_SERVER_PASSWORD=""``
     IRC server password
 
-``IRC_SERVER_PORT=6697``
+``IRC_PORT=6697``
     IRC server port
 
+Encryption options
+------------------
+
 ``IRC_USE_SSL=true``
     Connect to the IRC server with SSL
 
+``IRC_CERT_ALLOW_EXPIRED=false``
+    Allow connecting to IRC server with an expired TLS/SSL certificate
+
 ``IRC_CERT_ALLOW_SELFSIGNED=false``
     Allows TeleIRC to accept TLS/SSL certificates from non-trusted/unknown Certificate Authorities (CA)
 
-``IRC_CERT_ALLOW_EXPIRED=false``
-    Allow connecting to IRC server with an expired TLS/SSL certificate
+Channel settings
+================
+
+``IRC_CHANNEL="#channel"``
+    IRC channel for bot to join
+
+``IRC_CHANNEL_KEY=""``
+    IRC channel key, for password-protected channels
+
+``IRC_BLACKLIST=""``
+    Comma-separated list of IRC nicks to ignore
+
+Bot settings
+============
+
+``IRC_BOT_NAME=teleirc``
+    IRC nickname for bot.
+    Most IRC clients and bridges show this nickname.
+
+``IRC_BOT_REALNAME="Powered by TeleIRC <github.com/RITlug/teleirc>"``
+    IRC ``REALNAME`` for bot.
+    Often visible in IRC ``/whois`` reports, but most clients do not show this information by default.
+
+``IRC_BOT_IDENT=teleirc``
+    Identification metadata for bot connection.
+    This is rarely used or shown in most IRC clients and bridges, so only change this if you know what you are doing.
+    Often visible in IRC ``/whois`` reports, but most clients do not show this information by default.
+
+NickServ options
+----------------
 
 ``IRC_NICKSERV_SERVICE=NickServ``
-    IRC service used for authentication
+    IRC service used for authentication.
+
+``IRC_NICKSERV_USER=""``
+    IRC NickServ username.
 
 ``IRC_NICKSERV_PASS=""``
-    IRC account password to complete IRC authentication
+    IRC NickServ password.
 
-``IRC_EDITED_PREFIX="[EDIT] "``
+Message settings
+================
+
+``IRC_PREFIX="<"``
+    Text displayed before Telegram name in IRC
+
+``IRC_SUFFIX=">"``
+    Text displayed after Telegram name in IRC
+
+``IRC_SEND_STICKER_EMOJI=true``
+    Send emojis associated with a sticker to IRC (when a Telegram user sends a sticker)
+
+``IRC_SEND_DOCUMENT=false``
+    Send documents and files from Telegram to IRC (`why is this false by default? <https://github.com/RITlug/teleirc/issues/115>`_)
+
+``IRC_EDITED_PREFIX="(edited) "``
     Prefix to prepend to messages when a user edits a Telegram message and it is resent to IRC
 
 ``IRC_MAX_MESSAGE_LENGTH=400``
@@ -70,13 +103,15 @@ IRC settings
     Prevents users with the same Telegram and IRC username from pinging themselves across platforms.
 
 ``IRC_NO_FORWARD_PREFIX="[off]"``
-    A string users can prefix their message with to prevent it from being relayed across the bridge. Removing this option or setting it to "" disables it.
+    A string users can prefix their message with to prevent it from being relayed across the bridge.
+    Removing this option or setting it to "" disables it.
 
-``IRC_QUIT_MESSAGE``
+``IRC_QUIT_MESSAGE="TeleIRC bridge stopped."``
     A string that TeleIRC sends to the IRC channel when the application exits using IRC's "QUIT" command.
     If not specified, it simply closes the connection without providing a reason.
     The bot must be connected to a server for a certain amount of time for the server to send the quit message to the channel.
 
+
 *****************
 Telegram settings
 *****************

diff --git a/env.example b/env.example
@@ -1,3 +1,4 @@
+# vim:set filetype=sh:
 # See the Config File Glossary for instructions.
 # https://docs.teleirc.com/en/latest/config-file-glossary/
 
@@ -7,27 +8,46 @@
 #                                                                             #
 ###############################################################################
 
-IRC_BLACKLIST=""
-IRC_BOT_NAME=teleirc
-IRC_CHANNEL="#channel"
-IRC_CHANNEL_KEY=""
-IRC_SEND_STICKER_EMOJI=true
-IRC_SEND_DOCUMENT=false
-IRC_PREFIX="<"
-IRC_SUFFIX=">"
+
+#####----- IRC server connection settings -----#####
 IRC_SERVER=chat.freenode.net
 IRC_SERVER_PASSWORD=""
 IRC_PORT=6697
+
+## Encryption (SSL/TLS) options
 IRC_USE_SSL=true
-IRC_CERT_ALLOW_SELFSIGNED=false
 IRC_CERT_ALLOW_EXPIRED=false
+IRC_CERT_ALLOW_SELFSIGNED=false
+
+
+#####----- IRC channel settings -----#####
+IRC_CHANNEL="#channel"
+IRC_CHANNEL_KEY=""
+IRC_BLACKLIST=""
+
+
+#####----- IRC bot settings -----#####
+IRC_BOT_NAME=tg-bridge-bot
+IRC_BOT_REALNAME="Powered by TeleIRC <github.com/RITlug/teleirc>"
+IRC_BOT_IDENT="teleirc"
+
+# NickServ options
 IRC_NICKSERV_SERVICE=NickServ
+IRC_NICKSERV_USER=""
 IRC_NICKSERV_PASS=""
-IRC_EDITED_PREFIX="[EDIT] "
+
+
+#####----- IRC message settings -----#####
+IRC_PREFIX="<"
+IRC_SUFFIX=">"
+IRC_SEND_STICKER_EMOJI=true
+IRC_SEND_DOCUMENT=false
+IRC_EDITED_PREFIX="(edited) "
 IRC_MAX_MESSAGE_LENGTH=400
 IRC_SHOW_ZWSP=true
 IRC_NO_FORWARD_PREFIX=""
-IRC_QUIT_MESSAGE="Shutting Down"
+IRC_QUIT_MESSAGE="TeleIRC bridge stopped."
+
 
 
 ###############################################################################
@@ -45,6 +65,8 @@ SHOW_KICK_MESSAGE=true
 SHOW_LEAVE_MESSAGE=false
 SHOW_DISCONNECT_MESSAGE=true
 
+
+
 ################################################################################
 #                                                                             #
 #                      Imgur configuration settings                           #

diff --git a/internal/config.go b/internal/config.go
@@ -16,19 +16,23 @@ const defaultPath = ".env"
 // IRCSettings includes settings related to the IRC bot/message relaying
 type IRCSettings struct {
 	Server              string   `env:"IRC_SERVER,required"`
+	ServerPass          string   `env:"IRC_SERVER_PASSWORD envDefault:""`
 	Port                int      `env:"IRC_PORT" envDefault:"6667" validate:"min=0,max=65535"`
 	TLSAllowSelfSigned  bool     `env:"IRC_CERT_ALLOW_SELFSIGNED" envDefault:"true"`
 	TLSAllowCertExpired bool     `env:"IRC_CERT_ALLOW_EXPIRED" envDefault:"true"`
 	Channel             string   `env:"IRC_CHANNEL,required" validate:"notempty"`
 	ChannelKey          string   `env:"IRC_CHANNEL_KEY" envDefault:""`
-	BotName             string   `env:"IRC_BOT_NAME" envDefault:"teleirc"`
+	BotIdent            string   `env:"IRC_BOT_IDENT,required" envDefault:"teleirc"`
+	BotName             string   `env:"IRC_BOT_REALNAME" envDefault:"Powered by TeleIRC <github.com/RITlug/teleirc>"`
+	BotNick             string   `env:"IRC_BOT_NAME,required" validate:"notempty"`
 	SendStickerEmoji    bool     `env:"IRC_SEND_STICKER_EMOJI" envDefault:"true"`
 	SendDocument        bool     `env:"IRC_SEND_DOCUMENT" envDefault:"true"`
 	Prefix              string   `env:"IRC_PREFIX" envDefault:"<"`
 	Suffix              string   `env:"IRC_SUFFIX" envDefault:">"`
 	ShowJoinMessage     bool     `env:"IRC_SHOW_JOIN_MESSAGE" envDefault:"true"`
 	ShowLeaveMessage    bool     `env:"IRC_SHOW_LEAVE_MESSAGE" envDefault:"true"`
 	ShowZWSP            bool     `env:"IRC_SHOW_ZWSP" envDefault:"true"`
+	NickServUser        string   `env:"IRC_NICKSERV_USER" envDefault:""`
 	NickServPassword    string   `env:"IRC_NICKSERV_PASS" envDefault:""`
 	NickServService     string   `env:"IRC_NICKSERV_SERVICE" envDefault:""`
 	EditedPrefix        string   `env:"IRC_EDITED_PREFIX" envDefault:"[EDIT] "`

diff --git a/internal/handlers/irc/irc.go b/internal/handlers/irc/irc.go
@@ -28,16 +28,25 @@ func NewClient(settings *internal.IRCSettings, telegramSettings *internal.Telegr
 	client := girc.New(girc.Config{
 		Server: settings.Server,
 		Port:   settings.Port,
-		Nick:   settings.BotName,
-		User:   settings.BotName,
+		Nick:   settings.BotNick,
+		Name:   settings.BotName,
+		User:   settings.BotIdent,
 		SSL:    settings.UseSSL,
 	})
-	if settings.NickServPassword != "" {
-		client.Config.SASL = &girc.SASLPlain{
-			User: settings.BotName,
+
+	// IRC server authentication
+	if settings.ServerPass != "" {
+		client.Config.ServerPass = settings.ServerPass
+	}
+
+	// NickServ authentication
+	if settings.NickServUser != "" && settings.NickServPassword != "" {
+		client.Config.SASLMech = &girc.SASLPlain{
+			User: settings.NickServUser,
 			Pass: settings.NickServPassword,
 		}
 	}
+
 	return Client{client, settings, telegramSettings, logger, nil}
 }