Class: Flexo::Sender

Inherits:
Object
  • Object
show all
Defined in:
lib/flexo/sender.rb

Overview

One of the important classes. This contains convenience-functions for sending almost every IRC command imaginable. And if that’s not enough, it’ll also have a raw()-function. This is the only class that’s supposed to interact with Server, to make sure that only sanitized content is sent out from Flexo.

Most documentation for the functions are grabbed from RFC2812 available at tools.ietf.org/html/rfc2812.

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Sender

Sets up the link to the manager, and creates a send queue.



12
13
14
15
16
17
18
19
20
21
22
 
# File 'lib/flexo/sender.rb', line 12

def initialize
  @manager = Flexo::Manager.instance
  @queue   = Queue.new

  @manager.thread do
    while cmd = @queue.pop
      @manager.server.quote cmd
      sleep 1
    end
  end
end

Instance Method Details

#chanmode(channel, *modes) ⇒ Object

3.2.3 Channel mode message Command: MODE Parameters: <channel> *( ( “-” / “+” ) *<modes> *<modeparams> )

The MODE command is provided so that users may query and change the characteristics of a channel. Note that there is a maximum limit of three (3) changes per command for modes that take a parameter.

Numeric Replies:

ERR_NEEDMOREPARAMS              
ERR_KEYSET
ERR_NOCHANMODES                 
ERR_CHANOPRIVSNEEDED
ERR_USERNOTINCHANNEL            
ERR_UNKNOWNMODE
RPL_CHANNELMODEIS
RPL_BANLIST                     
RPL_ENDOFBANLIST
RPL_EXCEPTLIST                  
RPL_ENDOFEXCEPTLIST
RPL_INVITELIST                  
RPL_ENDOFINVITELIST
RPL_UNIQOPIS

Information about channel modes and how they work can be found in RFC2811 (tools.ietf.org/html/rfc2811)



372
373
374
 
# File 'lib/flexo/sender.rb', line 372

def chanmode(channel, *modes)
  quote "MODE #{channel.to_s} #{modes.join(' ')}"
end

#invite(nick, channel) ⇒ Object

3.2.7 Invite message Command: INVITE Parameters: <nickname> <channel>

The INVITE command is used to invite a user to a channel. The parameter <nickname> is the nickname of the person to be invited to the target channel <channel>. There is no requirement that the channel the target user is being invited to must exist or be a valid channel. However, if the channel exists, only members of the channel are allowed to invite other users. When the channel has invite-only flag set, only channel operators may issue INVITE command.

Only the user inviting and the user being invited will receive notification of the invitation. Other channel members are not notified. (This is unlike the MODE changes, and is occasionally the source of trouble for users.)

Numeric Replies:

ERR_NEEDMOREPARAMS
ERR_NOSUCHNICK
ERR_NOTONCHANNEL                
ERR_USERONCHANNEL
ERR_CHANOPRIVSNEEDED
RPL_INVITING
RPL_AWAY

Examples:

:[email protected] INVITE Wiz #Dust # Message to WiZ when he has 
                                      # been invited by user Angel 
                                      # to channel #Dust
INVITE Wiz #Twilight_Zone             # Command to invite WiZ to
                                      # #Twilight_zone



440
441
442
 
# File 'lib/flexo/sender.rb', line 440

def invite(nick, channel)
  quote "INVITE #{nick.to_s} #{channel.to_s}"
end

#join(channels, key = "") ⇒ Object

3.2.1 Join message Command: JOIN Parameters: <channel>, <key>

The JOIN command is used by a user to request to start listening to the specific channel. Servers MUST be able to parse arguments in the form of a list of target, but SHOULD NOT use lists when sending JOIN messages to clients.

Once a user has joined a channel, he receives information about all commands his server receives affecting the channel. This includes JOIN, MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE. This allows channel members to keep track of the other channel members, as well as channel modes.

If a JOIN is successful, the user receives a JOIN message as confirmation and is then sent the channel’s topic (using RPL_TOPIC) and the list of users who are on the channel (using RPL_NAMREPLY), which MUST include the user joining.

Note that this message accepts a special argument (“0”), which is a special request to leave all channels the user is currently a member of. The server will process this message as if the user had sent a PART command (See Section 3.2.2) for each channel he is a member of.

Numeric Replies:

ERR_NEEDMOREPARAMS
ERR_BANNEDFROMCHAN
ERR_INVITEONLYCHAN
ERR_BADCHANNELKEY
ERR_CHANNELISFULL
ERR_BADCHANMASK
ERR_NOSUCHCHANNEL
ERR_TOOMANYCHANNELS
ERR_TOOMANYTARGETS
ERR_UNAVAILRESOURCE
RPL_TOPIC

Examples:

JOIN #foobar                    # Command to join channel #foobar.
JOIN &foo fubar                 # Command to join channel &foo using
                                # key "fubar".
JOIN #foo,&bar fubar            # Command to join channel #foo using
                                # key "fubar" and &bar using no key.
JOIN #foo,#bar fubar,foobar     # Command to join channel #foo using
                                # key "fubar", and channel #bar using
                                # key "foobar".
JOIN #foo,#bar                  # Command to join channels #foo and
                                # #bar.
JOIN 0                          # Leave all currently joined
                                # channels.



310
311
312
313
314
 
# File 'lib/flexo/sender.rb', line 310

def join(channels, key="")
  channels.each do |channel|
    quote "JOIN #{channel.to_s} #{key.to_s}"
  end
end

#kick(channel, user, message = "") ⇒ Object

3.2.8 Kick command Command: KICK Parameters: <channel> <user> [<comment>]

The KICK command can be used to request the forced removal of a user from a channel. It causes the <user> to PART from the <channel> by force. For the message to be syntactically correct, there MUST be either one channel parameter and multiple user parameter, or as many channel parameters as there are user parameters. If a “comment” is given, this will be sent instead of the default message, the nickname of the user issuing the KICK.

Numeric Replies:

ERR_NEEDMOREPARAMS
ERR_NOSUCHCHANNEL
ERR_BADCHANMASK
ERR_CHANOPRIVSNEEDED
ERR_USERNOTINCHANNEL
ERR_NOTONCHANNEL



463
464
465
 
# File 'lib/flexo/sender.rb', line 463

def kick(channel, user, message="")
  quote "KICK #{channel} #{user} :#{message}"
end

#motd(target = "") ⇒ Object

3.4.1 Motd message Command: MOTD Parameters: [ <target> ]

The MOTD command is used to get the “Message Of The Day” of the given server, or current server if <target> is omitted.

Wildcards are allowed in the <target> parameter.

Numeric Replies:

RPL_MOTDSTART
RPL_MOTD
RPL_ENDOFMOTD
ERR_NOMOTD



532
533
534
 
# File 'lib/flexo/sender.rb', line 532

def motd(target="")
  quote "MOTD #{target}"
end

#nick(nickname) ⇒ Object

3.1.2 Nick message Command: NICK Parameters: <nickname>

NICK message is used to give the user a nickname if connecting, or change the previous one if already connected

Numeric Replies:

ERR_NONICKNAMEGIVEN 
ERR_ERRONEUSNICKNAME
ERR_NICKNAMEINUSE
ERR_NICKCOLLISION

Example:

NICK Wiz 		# Introducing new nick "Wiz".
:WiZ NICK Kilroy	# WiZ changed his nickname to Kilroy.



66
67
68
 
# File 'lib/flexo/sender.rb', line 66

def nick(nickname)
  quote "NICK #{nickname.to_s}"
end

#notice(target, text) ⇒ Object

3.3.2 Notice Command: NOTICE Parameters: <target> <text>

The NOTICE command is used similarly to PRIVMSG. The difference between NOTICE and PRIVMSG is that automatic replies MUST NEVER be sent in response to a NOTICE message. This rule applies to servers too - they MUST NOT send any error reply back to the client on receipt of a notice. The object of this rule is to avoid loops between clients automatically sending something in response to something it received.

This command is available to services as well as users. This is typically used by services, and automatons (clients with either an AI or other interactive program controlling their actions).

See PRIVMSG for more details on replies.



514
515
516
 
# File 'lib/flexo/sender.rb', line 514

def notice(target, text)
  quote "NOTICE #{target.to_s} :#{text.to_s}"
end

#oper(name, password) ⇒ Object

3.1.4 Oper message Command: OPER Parameters: <name> <password>

A normal user uses the OPER command to obtain operator privileges. The combination of <name> and <password> are REQUIRED to gain Operator privileges. Upon success, the user will receive a MODE message (see section 3.1.5) indicating the new user modes.

Numeric Replies:

ERR_NEEDMOREPARAMS
RPL_YOUREOPER
ERR_NOOPERHOST
ERR_PASSWDMISMATCH

Example:

OPER foo bar # Attempt to register as an operator
             using a username of "foo" and "bar" as the password.



118
119
120
 
# File 'lib/flexo/sender.rb', line 118

def oper(name, password)
  quote "OPER #{name.to_s} #{password.to_s}"
end

#part(channels, message = "") ⇒ Object

3.2.2 Part message Command: PART Parameters: <channel> <part message>

The PART command causes the user sending the message to be removed from the list of active members for all given channels listed in the parameter string. If a “Part Message” is given, this will be sent instead of the default message, the nickname. This request is always granted by the server.

Servers MUST be able to parse arguments in the form of a list of target, but SHOULD NOT use lists when sending PART messages to clients.

Numeric Replies:

ERR_NEEDMOREPARAMS  
ERR_NOSUCHCHANNEL
ERR_NOTONCHANNEL

Examples:

PART #twilight_zone  # Command to leave channel "#twilight_zone"
PART #oz-ops,&group5 # Command to leave both channels 
                     # "&group5" and "#oz-ops".



338
339
340
341
342
343
344
 
# File 'lib/flexo/sender.rb', line 338

def part(channels, message="")
  channels.each do |channel|
    cmd  = "PART #{channel.to_s}"
    cmd += " :#{message}" if message != ""
    quote cmd
  end
end

#pass(password) ⇒ Object

3.1.1 Password message Command: PASS Paramteres: <password>

The PASS command is used to set a ‘connection password’.

The optional password can and MUST be set before any attempt to register when the connection is made.

Currently this requires that user send a PASS command before sending the NICK/USER combination.

Numeric Replies:

ERR_NEEDMOREPARAMS 
ERR_ALREADYREGISTRED

Example:

PASS secretpasswordhere



46
47
48
 
# File 'lib/flexo/sender.rb', line 46

def pass(password)
  quote "PASS #{password.to_s}"
end

#ping(server, server2 = "") ⇒ Object

3.7.2 Ping message

Command: PING Parameters: <server1> [ <server2> ]

The PING command is used to test the presence of an active client or server at the other end of the connection. Servers send a PING message at regular intervals if no other activity detected coming from a connection. If a connection fails to respond to a PING message within a set amount of time, that connection is closed. A PING message MAY be sent even if the connection is active.

When a PING message is received, the appropriate PONG message MUST be sent as reply to <server1> (server which sent the PING message out) as soon as possible. If the <server2> parameter is specified, it represents the target of the ping, and the message gets forwarded there.

Numeric Replies:

ERR_NOORIGIN
ERR_NOSUCHSERVER

Examples:

PING tolsun.oulu.fi  # Command to send a PING message to server
PING :irc.funet.fi   # Ping message sent by server "irc.funet.fi"



573
574
575
 
# File 'lib/flexo/sender.rb', line 573

def ping(server, server2="")
  quote "PING #{server.to_s} #{server2.to_s}"
end

#pong(server, server2 = "") ⇒ Object

3.7.3 Pong message

Command: PONG Parameters: <server> [ <server2> ]

PONG message is a reply to ping message. If parameter <server2> is given, this message MUST be forwarded to given target. The <server> parameter is the name of the entity who has responded to PING message and generated this message.

Numeric Replies:

ERR_NOORIGIN
ERR_NOSUCHSERVER

Example:

PONG csd.bu.edu tolsun.oulu.fi  # PONG message from csd.bu.edu to
                                # tolsun.oulu.fi



593
594
595
 
# File 'lib/flexo/sender.rb', line 593

def pong(server, server2="")
  quote "PONG #{server.to_s} #{server2.to_s}"
end

#privmsg(target, text) ⇒ Object

3.3.1 Private messages Command: PRIVMSG Parameters: <target> <text to be sent>

PRIVMSG is used to send private messages between users, as well as to send messages to channels. <msgtarget> is usually the nickname of the recipient of the message, or a channel name.

The <msgtarget> parameter may also be a host mask (#<mask>) or server mask ($<mask>). In both cases the server will only send the PRIVMSG to those who have a server or host matching the mask. The mask MUST have at least 1 (one) “.” in it and no wildcards following the last “.”. This requirement exists to prevent people sending messages to “#*” or “$*”, which would broadcast to all users. Wildcards are the ‘*’ and ‘?’ characters. This extension to the PRIVMSG command is only available to operators.

Numeric Replies:

ERR_NORECIPIENT
ERR_NOTEXTTOSEND
ERR_CANNOTSENDTOCHAN
ERR_NOTOPLEVEL
ERR_WILDTOPLEVEL
ERR_TOOMANYTARGETS
ERR_NOSUCHNICK
RPL_AWAY



493
494
495
 
# File 'lib/flexo/sender.rb', line 493

def privmsg(target, text)
  quote "PRIVMSG #{target.to_s} :#{text.to_s}"
end

#quit(message = "") ⇒ Object

3.1.7 Quit Command: QUIT Parameters: <Quit Message>

A client session is terminated with a quit message. The server acknowledges this by sending an ERROR message to the client.

Numeric Replies:

None.

Example:

QUIT :Gone to have lunch



223
224
225
 
# File 'lib/flexo/sender.rb', line 223

def quit(message="")
  quote "QUIT :#{message.to_s}"
end

#quote(line) ⇒ Object

Shoves the command into the queue



25
26
27
28
 
# File 'lib/flexo/sender.rb', line 25

def quote(line)
  @manager.logger.debug("Adding \"#{line.rstrip}\" to the outgoing queue")
  @queue << line.rstrip
end

#service(nickname, distribution, type, info) ⇒ Object

3.1.6 Service message Command: SERVICE Parameters: <nickname> <reserved> <distribution> <type>

<reserved> <info>

The SERVICE command to register a new service. Command parameters specify the service nickname, distribution, type and info of a new service.

The <distribution> parameter is used to specify the visibility of a service. The service may only be known to servers which have a name matching the distribution. For a matching server to have knowledge of the service, the network path between that server and the server on which the service is connected MUST be composed of servers which names all match the mask.

The <type> parameter is currently reserved for future usage.

Numeric Replies:

ERR_ALREADYREGISTRED            
ERR_NEEDMOREPARAMS
ERR_ERRONEUSNICKNAME
RPL_YOURESERVICE
RPL_YOURHOST
RPL_MYINFO

Example:

SERVICE dict * *.fr 0 0 :French Dictionary 
# Service registering itself with a name of "dict". 
# This service will only be available on servers which 
# name matches "*.fr".



208
209
210
 
# File 'lib/flexo/sender.rb', line 208

def service(nickname, distribution, type, info)
  # Won't be implemented by me
end

#squit(server, message = "") ⇒ Object

3.1.8 Squit Command: SQUIT Parameters: <server> <comment>

The SQUIT command is available only to operators. It is used to disconnect server links. Also servers can generate SQUIT messages on error conditions. A SQUIT message may also target a remote server connection. In this case, the SQUIT message will simply be sent to the remote server without affecting the servers in between the operator and the remote server.

The <comment> SHOULD be supplied by all operators who execute a SQUIT for a remote server. The server ordered to disconnect its peer generates a WALLOPS message with <comment> included, so that other users may be aware of the reason of this action.

Numeric replies:

ERR_NOPRIVILEGES
ERR_NOSUCHSERVER
ERR_NEEDMOREPARAMS

Examples:

SQUIT tolsun.oulu.fi :Bad Link ?  # Command to uplink of the server
				  # tolson.oulu.fi to terminate its
				  # connection with comment "Bad Link".
:Trillian SQUIT cm22.eng.umd.edu :Server out of control 
                                  # Command from Trillian from to 
                                  # disconnect "cm22.eng.umd.edu" 
                                  # from the net with comment 
                                  # "Server out of control".



256
257
 
# File 'lib/flexo/sender.rb', line 256

def squit(server, message="")
end

#topic(channel, topic = "") ⇒ Object

3.2.4 Topic message Command: TOPIC Parameters: <channel> [ <topic> ]

The TOPIC command is used to change or view the topic of a channel. The topic for channel <channel> is returned if there is no <topic> given. If the <topic> parameter is present, the topic for that channel will be changed, if this action is allowed for the user requesting it. If the <topic> parameter is an empty string, the topic for that channel will be removed.

Numeric Replies:

ERR_NEEDMOREPARAMS 
ERR_NOTONCHANNEL
RPL_NOTOPIC
RPL_TOPIC
ERR_CHANOPRIVSNEEDED
ERR_NOCHANMODES

Examples:

:[email protected] TOPIC #test :New  # User Wiz setting the topic.
TOPIC #test :another topic      # Command to set the topic on #test
                                # to "another topic".
TOPIC #test :                   # Command to clear the topic on #test.
TOPIC #test                     # Command to check the topic for #test.



400
401
402
403
404
 
# File 'lib/flexo/sender.rb', line 400

def topic(channel, topic="")
  cmd =  "TOPIC #{channel.to_s} "
  cmd += ":#{topic.to_s}" if topic != ""
  quote cmd
end

#user(user, mode, realname) ⇒ Object

3.1.3 User message Command: USER Parameters: <user> <mode> <unused> <realname>

The USER command is used at the beginning of connection to specify the username, hostname and realname of a new user.

The <mode> parameter should be a numeric, and can be used to automatically set user modes when registering with the server. This parameter is a bitmask, with only 2 bits having any signification: if the bit 2 is set, the user mode ‘w’ will be set and if the bit 3 is set, the user mode ‘i’ will be set. (See Section 3.1.5 “User Modes”). The <realname> may contain space characters.

Numeric Replies:

ERR_NEEDMOREPARAMS
ERR_ALREADYREGISTRED

Example:

USER guest 0 * :Ronnie Reagan   # User registering themselves with a
                                # username of "guest" and real name
                                # "Ronnie Reagan".
USER guest 8 * :Ronnie Reagan   # User registering themselves with a
                                # username of "guest" and real name
                                # "Ronnie Reagan", and asking to be set
                                # invisible.



97
98
99
 
# File 'lib/flexo/sender.rb', line 97

def user(user, mode, realname)
  quote "USER #{user.to_s} #{mode.to_i} * :#{realname.to_s}"
end

#usermode(nickname, mode) ⇒ Object

3.1.5 User mode message Command: MODE Parameters: <nickname> ±<modes>

The user MODE’s are typically changes which affect either how the client is seen by others or what ‘extra’ messages the client is sent. A user MODE command MUST only be accepted if both the sender of the message and the nickname given as a parameter are both the same. If no other parameter is given, then the server will return the current settings for the nick.

The available modes are as follows:

a - user is flagged as away;
i - marks a users as invisible;
w - user receives wallops;
r - restricted user connection;
o - operator flag;
O - local operator flag;
s - marks a user for receipt of server notices.

Additional modes may be available later on.

The flag ‘a’ SHALL NOT be toggled by the user using the MODE command, instead use of the AWAY command is REQUIRED.

If a user attempts to make themselves an operator using the “+o” or “+O” flag, the attempt SHOULD be ignored as users could bypass the authentication mechanisms of the OPER command. There is no restriction, however, on anyone ‘deopping’ themselves (using “-o” or “-O”).

On the other hand, if a user attempts to make themselves unrestricted using the “-r” flag, the attempt SHOULD be ignored. There is no restriction, however, on anyone ‘deopping’ themselves (using “+r”). This flag is typically set by the server upon connection for administrative reasons. While the restrictions imposed are left up to the implementation, it is typical that a restricted user not be allowed to change nicknames, nor make use of the channel operator status on channels.

The flag ‘s’ is obsolete but MAY still be used.

Numeric Replies:

ERR_NEEDMOREPARAMS              
ERR_USERSDONTMATCH
ERR_UMODEUNKNOWNFLAG            
RPL_UMODEIS

Examples:

MODE WiZ -w    # Command by WiZ to turn off 
               # reception of WALLOPS messages.
MODE Angel +i  # Command from Angel to make herself invisible.
MODE WiZ -o    # WiZ 'deopping' (removing operator status).



174
175
176
 
# File 'lib/flexo/sender.rb', line 174

def usermode(nickname, mode)
  quote "MODE #{nickname.to_s} #{mode.to_s}"
end