123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721 |
- // Copyright (c) 2016-2017 Daniel Oaks <daniel@danieloaks.net>
- // released under the MIT license
-
- package irc
-
- import (
- "fmt"
- "sort"
- "strings"
-
- "github.com/oragono/oragono/irc/languages"
- )
-
- // HelpEntryType represents the different sorts of help entries that can exist.
- type HelpEntryType int
-
- const (
- // CommandHelpEntry is a help entry explaining a client command.
- CommandHelpEntry HelpEntryType = iota
- // InformationHelpEntry is a help entry explaining general server info.
- InformationHelpEntry
- // ISupportHelpEntry is a help entry explaining a specific RPL_ISUPPORT token.
- ISupportHelpEntry
- )
-
- // HelpEntry represents an entry in the Help map.
- type HelpEntry struct {
- oper bool
- text string
- textGenerator func(*Client) string
- helpType HelpEntryType
- duplicate bool
- }
-
- // used for duplicates
- var (
- cmodeHelpText = `== Channel Modes ==
-
- Oragono supports the following channel modes:
-
- +b | Client masks that are banned from the channel (e.g. *!*@127.0.0.1)
- +e | Client masks that are exempted from bans.
- +I | Client masks that are exempted from the invite-only flag.
- +i | Invite-only mode, only invited clients can join the channel.
- +k | Key required when joining the channel.
- +l | Client join limit for the channel.
- +m | Moderated mode, only privileged clients can talk on the channel.
- +n | No-outside-messages mode, only users that are on the channel can send
- | messages to it.
- +R | Only registered users can talk in the channel.
- +s | Secret mode, channel won't show up in /LIST or whois replies.
- +t | Only channel opers can modify the topic.
-
- = Prefixes =
-
- +q (~) | Founder channel mode.
- +a (&) | Admin channel mode.
- +o (@) | Operator channel mode.
- +h (%) | Halfop channel mode.
- +v (+) | Voice channel mode.`
- umodeHelpText = `== User Modes ==
-
- Oragono supports the following user modes:
-
- +a | User is marked as being away. This mode is set with the /AWAY command.
- +i | User is marked as invisible (their channels are hidden from whois replies).
- +o | User is an IRC operator.
- +R | User only accepts messages from other registered users.
- +s | Server Notice Masks (see help with /HELPOP snomasks).
- +Z | User is connected via TLS.`
- snomaskHelpText = `== Server Notice Masks ==
-
- Oragono supports the following server notice masks for operators:
-
- a | Local announcements.
- c | Local client connections.
- j | Local channel actions.
- k | Local kills.
- n | Local nick changes.
- o | Local oper actions.
- q | Local quits.
- t | Local /STATS usage.
- u | Local client account actions.
- x | Local X-lines (DLINE/KLINE/etc).
-
- To set a snomask, do this with your nickname:
-
- /MODE <nick> +s <chars>
-
- For instance, this would set the kill, oper, account and xline snomasks on dan:
-
- /MODE dan +s koux`
- )
-
- // Help contains the help strings distributed with the IRCd.
- var Help = map[string]HelpEntry{
- // Commands
- "acc": {
- text: `ACC REGISTER <accountname> [callback_namespace:]<callback> [cred_type] :<credential>
- ACC VERIFY <accountname> <auth_code>
-
- Used in account registration. See the relevant specs for more info:
- https://oragono.io/specs.html`,
- },
- "ambiance": {
- text: `AMBIANCE <target> <text to be sent>
-
- The AMBIANCE command is used to send a scene notification to the given target.`,
- },
- "authenticate": {
- text: `AUTHENTICATE
-
- Used during SASL authentication. See the IRCv3 specs for more info:
- http://ircv3.net/specs/extensions/sasl-3.1.html`,
- },
- "away": {
- text: `AWAY [message]
-
- If [message] is sent, marks you away. If [message] is not sent, marks you no
- longer away.`,
- },
- "cap": {
- text: `CAP <subcommand> [:<capabilities>]
-
- Used in capability negotiation. See the IRCv3 specs for more info:
- http://ircv3.net/specs/core/capability-negotiation-3.1.html
- http://ircv3.net/specs/core/capability-negotiation-3.2.html`,
- },
- "chanserv": {
- text: `CHANSERV <subcommand> [params]
-
- ChanServ controls channel registrations.`,
- },
- "chathistory": {
- text: `CHATHISTORY [params]
-
- CHATHISTORY is an experimental history replay command. See these documents:
- https://github.com/MuffinMedic/ircv3-specifications/blob/chathistory/extensions/chathistory.md
- https://gist.github.com/DanielOaks/c104ad6e8759c01eb5c826d627caf80d`,
- },
- "cs": {
- text: `CS <subcommand> [params]
-
- ChanServ controls channel registrations.`,
- },
- "debug": {
- oper: true,
- text: `DEBUG <option>
-
- Prints debug information about the IRCd. <option> can be one of:
-
- * GCSTATS: Garbage control statistics.
- * NUMGOROUTINE: Number of goroutines in use.
- * STARTCPUPROFILE: Starts the CPU profiler.
- * STOPCPUPROFILE: Stops the CPU profiler.
- * PROFILEHEAP: Writes out the CPU profiler info.`,
- },
- "dline": {
- oper: true,
- text: `DLINE [ANDKILL] [MYSELF] [duration] <ip>/<net> [ON <server>] [reason [| oper reason]]
- DLINE LIST
-
- Bans an IP address or network from connecting to the server. If the duration is
- given then only for that long. The reason is shown to the user themselves, but
- everyone else will see a standard message. The oper reason is shown to
- operators getting info about the DLINEs that exist.
-
- Bans are saved across subsequent launches of the server.
-
- "ANDKILL" means that all matching clients are also removed from the server.
-
- "MYSELF" is required when the DLINE matches the address the person applying it is connected
- from. If "MYSELF" is not given, trying to DLINE yourself will result in an error.
-
- [duration] can be of the following forms:
- 1y 12mo 31d 10h 8m 13s
-
- <net> is specified in typical CIDR notation. For example:
- 127.0.0.1/8
- 8.8.8.8/24
-
- ON <server> specifies that the ban is to be set on that specific server.
-
- [reason] and [oper reason], if they exist, are separated by a vertical bar (|).
-
- If "DLINE LIST" is sent, the server sends back a list of our current DLINEs.`,
- },
- "help": {
- text: `HELP <argument>
-
- Get an explanation of <argument>, or "index" for a list of help topics.`,
- },
- "helpop": {
- text: `HELPOP <argument>
-
- Get an explanation of <argument>, or "index" for a list of help topics.`,
- },
- "history": {
- text: `HISTORY <target> [limit]
-
- Replay message history. <target> can be a channel name, "me" to replay direct
- message history, or a nickname to replay another client's direct message
- history (they must be logged into the same account as you). At most [limit]
- messages will be replayed.`,
- },
- "hostserv": {
- text: `HOSTSERV <command> [params]
-
- HostServ lets you manage your vhost (a string displayed in place of your
- real hostname).`,
- },
- "hs": {
- text: `HS <command> [params]
-
- HostServ lets you manage your vhost (a string displayed in place of your
- real hostname).`,
- },
- "info": {
- text: `INFO
-
- Sends information about the server, developers, etc.`,
- },
- "invite": {
- text: `INVITE <nickname> <channel>
-
- Invites the given user to the given channel, so long as you have the
- appropriate channel privs.`,
- },
- "ison": {
- text: `ISON <nickname>{ <nickname>}
-
- Returns whether the given nicks exist on the network.`,
- },
- "join": {
- text: `JOIN <channel>{,<channel>} [<key>{,<key>}]
-
- Joins the given channels with the matching keys.`,
- },
- "kick": {
- text: `KICK <channel> <user> [reason]
-
- Removes the user from the given channel, so long as you have the appropriate
- channel privs.`,
- },
- "kill": {
- oper: true,
- text: `KILL <nickname> [reason]
-
- Removes the given user from the network, showing them the reason if it is
- supplied.`,
- },
- "kline": {
- oper: true,
- text: `KLINE [ANDKILL] [MYSELF] [duration] <mask> [ON <server>] [reason [| oper reason]]
- KLINE LIST
-
- Bans a mask from connecting to the server. If the duration is given then only for that
- long. The reason is shown to the user themselves, but everyone else will see a standard
- message. The oper reason is shown to operators getting info about the KLINEs that exist.
-
- Bans are saved across subsequent launches of the server.
-
- "ANDKILL" means that all matching clients are also removed from the server.
-
- "MYSELF" is required when the KLINE matches the address the person applying it is connected
- from. If "MYSELF" is not given, trying to KLINE yourself will result in an error.
-
- [duration] can be of the following forms:
- 1y 12mo 31d 10h 8m 13s
-
- <mask> is specified in typical IRC format. For example:
- dan
- dan!5*@127.*
-
- ON <server> specifies that the ban is to be set on that specific server.
-
- [reason] and [oper reason], if they exist, are separated by a vertical bar (|).
-
- If "KLINE LIST" is sent, the server sends back a list of our current KLINEs.`,
- },
- "language": {
- text: `LANGUAGE <code>{ <code>}
-
- Sets your preferred languages to the given ones.`,
- },
- "list": {
- text: `LIST [<channel>{,<channel>}] [<elistcond>{,<elistcond>}]
-
- Shows information on the given channels (or if none are given, then on all
- channels). <elistcond>s modify how the channels are selected.`,
- //TODO(dan): Explain <elistcond>s in more specific detail
- },
- "lusers": {
- text: `LUSERS [<mask> [<server>]]
-
- Shows statistics about the size of the network. If <mask> is given, only
- returns stats for servers matching the given mask. If <server> is given, the
- command is processed by that server.`,
- },
- "mode": {
- text: `MODE <target> [<modestring> [<mode arguments>...]]
-
- Sets and removes modes from the given target. For more specific information on
- mode characters, see the help for "modes".`,
- },
- "monitor": {
- text: `MONITOR <subcmd>
-
- Allows the monitoring of nicknames, for alerts when they are online and
- offline. The subcommands are:
-
- MONITOR + target{,target}
- Adds the given names to your list of monitored nicknames.
-
- MONITOR - target{,target}
- Removes the given names from your list of monitored nicknames.
-
- MONITOR C
- Clears your list of monitored nicknames.
-
- MONITOR L
- Lists all the nicknames you are currently monitoring.
-
- MONITOR S
- Lists whether each nick in your MONITOR list is online or offline.`,
- },
- "motd": {
- text: `MOTD [server]
-
- Returns the message of the day for this, or the given, server.`,
- },
- "names": {
- text: `NAMES [<channel>{,<channel>}]
-
- Views the clients joined to a channel and their channel membership prefixes. To
- view the channel membership prefixes supported by this server, see the help for
- "PREFIX".`,
- },
- "nick": {
- text: `NICK <newnick>
-
- Sets your nickname to the new given one.`,
- },
- "nickserv": {
- text: `NICKSERV <subcommand> [params]
-
- NickServ controls accounts and user registrations.`,
- },
- "notice": {
- text: `NOTICE <target>{,<target>} <text to be sent>
-
- Sends the text to the given targets as a NOTICE.`,
- },
- "npc": {
- text: `NPC <target> <sourcenick> <text to be sent>
-
- The NPC command is used to send a message to the target as the source.
-
- Requires the roleplay mode (+E) to be set on the target.`,
- },
- "npca": {
- text: `NPCA <target> <sourcenick> <text to be sent>
-
- The NPC command is used to send an action to the target as the source.
-
- Requires the roleplay mode (+E) to be set on the target.`,
- },
- "ns": {
- text: `NS <subcommand> [params]
-
- NickServ controls accounts and user registrations.`,
- },
- "oper": {
- text: `OPER <name> <password>
-
- If the correct details are given, gives you IRCop privs.`,
- },
- "part": {
- text: `PART <channel>{,<channel>} [reason]
-
- Leaves the given channels and shows people the given reason.`,
- },
- "pass": {
- text: `PASS <password>
-
- When the server requires a connection password to join, used to send us the
- password.`,
- },
- "ping": {
- text: `PING <args>...
-
- Requests a PONG. Used to check link connectivity.`,
- },
- "pong": {
- text: `PONG <args>...
-
- Replies to a PING. Used to check link connectivity.`,
- },
- "privmsg": {
- text: `PRIVMSG <target>{,<target>} <text to be sent>
-
- Sends the text to the given targets as a PRIVMSG.`,
- },
- "rename": {
- text: `RENAME <channel> <newname> [<reason>]
-
- Renames the given channel with the given reason, if possible.
-
- For example:
- RENAME #ircv2 #ircv3 :Protocol upgrades!`,
- },
- "sajoin": {
- oper: true,
- text: `SAJOIN [nick] #channel{,#channel}
-
- Forcibly joins a user to a channel, ignoring restrictions like bans, user limits
- and channel keys. If [nick] is omitted, it defaults to the operator.`,
- },
- "sanick": {
- oper: true,
- text: `SANICK <currentnick> <newnick>
-
- Gives the given user a new nickname.`,
- },
- "samode": {
- oper: true,
- text: `SAMODE <target> [<modestring> [<mode arguments>...]]
-
- Forcibly sets and removes modes from the given target -- only available to
- opers. For more specific information on mode characters, see the help for
- "cmode" and "umode".`,
- },
- "scene": {
- text: `SCENE <target> <text to be sent>
-
- The SCENE command is used to send a scene notification to the given target.`,
- },
- "setname": {
- text: `SETNAME <realname>
-
- The SETNAME command updates the realname to be the newly-given one.`,
- },
- "tagmsg": {
- text: `@+client-only-tags TAGMSG <target>{,<target>}
-
- Sends the given client-only tags to the given targets as a TAGMSG. See the IRCv3
- specs for more info: http://ircv3.net/specs/core/message-tags-3.3.html`,
- },
- "quit": {
- text: `QUIT [reason]
-
- Indicates that you're leaving the server, and shows everyone the given reason.`,
- },
- "rehash": {
- oper: true,
- text: `REHASH
-
- Reloads the config file and updates TLS certificates on listeners`,
- },
- "resume": {
- text: `RESUME <oldnick> [timestamp]
-
- Sent before registration has completed, this indicates that the client wants to
- resume their old connection <oldnick>.`,
- },
- "time": {
- text: `TIME [server]
-
- Shows the time of the current, or the given, server.`,
- },
- "topic": {
- text: `TOPIC <channel> [topic]
-
- If [topic] is given, sets the topic in the channel to that. If [topic] is not
- given, views the current topic on the channel.`,
- },
- "undline": {
- oper: true,
- text: `UNDLINE <ip>/<net>
-
- Removes an existing ban on an IP address or a network.
-
- <net> is specified in typical CIDR notation. For example:
- 127.0.0.1/8
- 8.8.8.8/24`,
- },
- "unkline": {
- oper: true,
- text: `UNKLINE <mask>
-
- Removes an existing ban on a mask.
-
- For example:
- dan
- dan!5*@127.*`,
- },
- "user": {
- text: `USER <username> 0 * <realname>
-
- Used in connection registration, sets your username and realname to the given
- values (though your username may also be looked up with Ident).`,
- },
- "userhost": {
- text: `USERHOST <nickname>{ <nickname>}
-
- Shows information about the given users. Takes up to 10 nicknames.`,
- },
- "version": {
- text: `VERSION [server]
-
- Views the version of software and the RPL_ISUPPORT tokens for the given server.`,
- },
- "webirc": {
- oper: true, // not really, but it's restricted anyways
- text: `WEBIRC <password> <gateway> <hostname> <ip> [:<flags>]
-
- Used by web<->IRC gateways and bouncers, the WEBIRC command allows gateways to
- pass-through the real IP addresses of clients:
- ircv3.net/specs/extensions/webirc.html
-
- <flags> is a list of space-separated strings indicating various details about
- the connection from the client to the gateway, such as:
-
- - tls: this flag indicates that the client->gateway connection is secure`,
- },
- "who": {
- text: `WHO <name> [o]
-
- Returns information for the given user.`,
- },
- "whois": {
- text: `WHOIS <client>{,<client>}
-
- Returns information for the given user(s).`,
- },
- "whowas": {
- text: `WHOWAS <nickname>
-
- Returns historical information on the last user with the given nickname.`,
- },
-
- // Informational
- "modes": {
- textGenerator: modesTextGenerator,
- helpType: InformationHelpEntry,
- },
- "cmode": {
- text: cmodeHelpText,
- helpType: InformationHelpEntry,
- },
- "cmodes": {
- text: cmodeHelpText,
- helpType: InformationHelpEntry,
- duplicate: true,
- },
- "umode": {
- text: umodeHelpText,
- helpType: InformationHelpEntry,
- },
- "umodes": {
- text: umodeHelpText,
- helpType: InformationHelpEntry,
- duplicate: true,
- },
- "snomask": {
- text: snomaskHelpText,
- helpType: InformationHelpEntry,
- oper: true,
- duplicate: true,
- },
- "snomasks": {
- text: snomaskHelpText,
- helpType: InformationHelpEntry,
- oper: true,
- },
-
- // RPL_ISUPPORT
- "casemapping": {
- text: `RPL_ISUPPORT CASEMAPPING
-
- Oragono supports an experimental unicode casemapping designed for extended
- Unicode support. This casemapping is based off RFC 7613 and the draft rfc7613
- casemapping spec here: https://oragono.io/specs.html`,
- helpType: ISupportHelpEntry,
- },
- "prefix": {
- text: `RPL_ISUPPORT PREFIX
-
- Oragono supports the following channel membership prefixes:
-
- +q (~) | Founder channel mode.
- +a (&) | Admin channel mode.
- +o (@) | Operator channel mode.
- +h (%) | Halfop channel mode.
- +v (+) | Voice channel mode.`,
- helpType: ISupportHelpEntry,
- },
- }
-
- // modesTextGenerator generates the text for the 'modes' help entry.
- // it exists only so we can translate this entry appropriately.
- func modesTextGenerator(client *Client) string {
- return client.t(cmodeHelpText) + "\n\n" + client.t(umodeHelpText)
- }
-
- // HelpIndex contains the list of all help topics for regular users.
- var HelpIndex map[string]string
-
- // HelpIndexOpers contains the list of all help topics for opers.
- var HelpIndexOpers map[string]string
-
- // GenerateHelpIndex is used to generate HelpIndex.
- func GenerateHelpIndex(lm *languages.Manager, forOpers bool) map[string]string {
- // generate the help entry lists
- var commands, isupport, information []string
-
- var line string
- for name, info := range Help {
- if info.duplicate {
- continue
- }
- if info.oper && !forOpers {
- continue
- }
-
- line = fmt.Sprintf(" %s", name)
-
- if info.helpType == CommandHelpEntry {
- commands = append(commands, line)
- } else if info.helpType == ISupportHelpEntry {
- isupport = append(isupport, line)
- } else if info.helpType == InformationHelpEntry {
- information = append(information, line)
- }
- }
-
- // create the strings
- sort.Strings(commands)
- commandsString := strings.Join(commands, "\n")
- sort.Strings(isupport)
- isupportString := strings.Join(isupport, "\n")
- sort.Strings(information)
- informationString := strings.Join(information, "\n")
-
- // sub them in
- defaultHelpIndex := `= Help Topics =
-
- Commands:
- %[1]s
-
- RPL_ISUPPORT Tokens:
- %[2]s
-
- Information:
- %[3]s`
-
- newHelpIndex := make(map[string]string)
-
- newHelpIndex["en"] = fmt.Sprintf(defaultHelpIndex, commandsString, isupportString, informationString)
-
- lm.RLock()
- defer lm.RUnlock()
-
- for langCode := range lm.Info {
- translatedHelpIndex := lm.Translate([]string{langCode}, defaultHelpIndex)
- if translatedHelpIndex != defaultHelpIndex {
- newHelpIndex[langCode] = fmt.Sprintf(translatedHelpIndex, commandsString, isupportString, informationString)
- }
- }
-
- return newHelpIndex
- }
-
- // GenerateHelpIndices generates our help indexes and confirms we have HELP entries for every command.
- func GenerateHelpIndices(lm *languages.Manager) error {
- // startup check that we have HELP entries for every command
- if len(HelpIndex) == 0 && len(HelpIndexOpers) == 0 {
- for name := range Commands {
- _, exists := Help[strings.ToLower(name)]
- if !exists {
- return fmt.Errorf("Help entry does not exist for command %s", name)
- }
- }
- }
-
- // generate help indexes
- HelpIndex = GenerateHelpIndex(lm, false)
- HelpIndexOpers = GenerateHelpIndex(lm, true)
- return nil
- }
-
- // sendHelp sends the client help of the given string.
- func (client *Client) sendHelp(name string, text string, rb *ResponseBuffer) {
- splitName := strings.Split(name, " ")
- textLines := strings.Split(text, "\n")
-
- for i, line := range textLines {
- args := splitName
- args = append(args, line)
- if i == 0 {
- rb.Add(nil, client.server.name, RPL_HELPSTART, args...)
- } else {
- rb.Add(nil, client.server.name, RPL_HELPTXT, args...)
- }
- }
- args := splitName
- args = append(args, client.t("End of /HELPOP"))
- rb.Add(nil, client.server.name, RPL_ENDOFHELP, args...)
- }
-
- // GetHelpIndex returns the help index for the given language.
- func GetHelpIndex(languages []string, helpIndex map[string]string) string {
- for _, lang := range languages {
- index, exists := helpIndex[lang]
- if exists {
- return index
- }
- }
- // 'en' always exists
- return helpIndex["en"]
- }
|