cinch 1.1.3 → 2.0.0.pre.1

data/lib/cinch/dcc.rb

@@ -0,0 +1,12 @@
+require "cinch/dcc/outgoing"
+require "cinch/dcc/incoming"
+
+module Cinch
+  # Cinch supports the following DCC commands:
+  #
+  # - SEND (both {DCC::Incoming::Send incoming} and
+  #   {DCC::Outgoing::Send outgoing})
+  # @since 2.0.0
+  module DCC
+  end
+end

data/lib/cinch/dcc/dccable_object.rb

@@ -0,0 +1,37 @@
+module Cinch
+  module DCC
+    # This module describes the required interface for objects that should
+    # be sendable via DCC.
+    #
+    # @note `File` conforms to this interface.
+    # @since 2.0.0
+    # @abstract
+    module DCCableObject
+      # Return the next `number` bytes of the object.
+      #
+      # @param [Number] number Read `number` bytes at most
+      # @return [String] The read data
+      # @return [nil] If no more data can be read
+      def read(number)
+      end
+
+      # Seek to a specific position.
+      #
+      # @param [Number] position The position in bytes to seek to
+      # @return [void]
+      def seek(position)
+      end
+
+      # @return [String] A string representing the object's path or name.
+      #
+      # @note This is only required if calling {User#dcc_send} with only
+      #   one argument
+      def path
+      end
+
+      # @return [Number] The total size of the data, in bytes.
+      def size
+      end
+    end
+  end
+end

data/lib/cinch/dcc/incoming.rb

@@ -0,0 +1 @@
+require "cinch/dcc/incoming/send"

data/lib/cinch/dcc/incoming/send.rb

@@ -0,0 +1,131 @@
+require "socket"
+require "ipaddr"
+
+module Cinch
+  module DCC
+    module Incoming
+      # DCC SEND is a protocol for transferring files, usually found
+      # in IRC. While the handshake, i.e. the details of the file
+      # transfer, are transferred over IRC, the actual file transfer
+      # happens directly between two clients. As such it doesn't put
+      # stress on the IRC server.
+      #
+      # When someone tries to send a file to the bot, the `:dcc_send`
+      # event will be triggered, in which the DCC request can be
+      # inspected and optionally accepted.
+      #
+      # The event handler receives the plain message object as well as
+      # an instance of this class. That instance contains information
+      # about {#filename the suggested file name} (in a sanitized way)
+      # and allows for checking the origin.
+      #
+      # It is advised to reject transfers that seem to originate from
+      # a {#from_private_ip? private IP} or {#from_localhost? the
+      # local IP itself} unless that is expected. Otherwise, specially
+      # crafted requests could cause the bot to connect to internal
+      # services.
+      #
+      # Finally, the file transfer can be {#accept accepted} and
+      # written to any object that implements a `#<<` method, which
+      # includes File objects as well as plain strings.
+      #
+      # @example Saving a transfer to a temporary file
+      #   require "tempfile"
+      #
+      #   listen_to :dcc_send, method: :incoming_dcc
+      #   def incoming_dcc(m, dcc)
+      #     if dcc.from_private_ip? || dcc.from_localhost?
+      #       @bot.loggers.debug "Not accepting potentially dangerous file transfer"
+      #       return
+      #     end
+      #
+      #     t = Tempfile.new(dcc.filename)
+      #     dcc.accept(t)
+      #     t.close
+      #   end
+      class Send
+        # @private
+        PRIVATE_NETS = [IPAddr.new("fc00::/7"),
+                        IPAddr.new("10.0.0.0/8"),
+                        IPAddr.new("172.16.0.0/12"),
+                        IPAddr.new("192.168.0.0/16")]
+
+        # @private
+        LOCAL_NETS = [IPAddr.new("127.0.0.0/8"),
+                      IPAddr.new("::1/128")]
+
+        # @return [User]
+        attr_reader :user
+
+        # @return [String]
+        attr_reader :filename
+
+        # @return [Number]
+        attr_reader :size
+
+        # @return [String]
+        attr_reader :ip
+
+        # @return [Number]
+        attr_reader :port
+
+        # @param [Hash] opts
+        # @option opts [User] user
+        # @option opts [String] filename
+        # @option opts [Number] size
+        # @option opts [String] ip
+        # @option opts [Number] port
+        # @api private
+        def initialize(opts)
+          @user, @filename, @size, @ip, @port = opts.values_at(:user, :filename, :size, :ip, :port)
+        end
+
+        # @return [String] The basename of the file name, with
+        #   (back)slashes removed.
+        def filename
+          File.basename(File.expand_path(@filename)).delete("/\\")
+        end
+
+        # This method is used for accepting a DCC SEND offer. It
+        # expects an object to save the result to (usually an instance
+        # of IO or String).
+        #
+        # @param [#<<] io The object to write the data to.
+        # @return [void]
+        # @note This method blocks.
+        # @example Saving to a file
+        #   f = File.open("/tmp/foo", "w")
+        #   dcc.accept(f)
+        #   f.close
+        #
+        # @example Saving to a string
+        #   s = ""
+        #   dcc.accept(s)
+        def accept(io)
+          socket = TCPSocket.new(@ip, @port)
+          total = 0
+          while buf = socket.read(1024)
+            total += buf.bytesize
+
+            socket.write [total].pack("N")
+            io << buf
+          end
+        end
+
+        # @return [Boolean] True if the DCC originates from a private ip
+        # @see #from_localhost?
+        def from_private_ip?
+          ip   = IPAddr.new(@ip)
+          PRIVATE_NETS.any? {|n| n.include?(ip)}
+        end
+
+        # @return [Boolean] True if the DCC originates from localhost
+        # @see #from_private_ip?
+        def from_localhost?
+          ip   = IPAddr.new(@ip)
+          LOCAL_NETS.any? {|n| n.include?(ip)}
+        end
+      end
+    end
+  end
+end

data/lib/cinch/dcc/outgoing.rb

@@ -0,0 +1 @@
+require "cinch/dcc/outgoing/send"

data/lib/cinch/dcc/outgoing/send.rb

@@ -0,0 +1,115 @@
+require "socket"
+require "ipaddr"
+require "timeout"
+
+module Cinch
+  module DCC
+    module Outgoing
+      # DCC SEND is a protocol for transferring files, usually found
+      # in IRC. While the handshake, i.e. the details of the file
+      # transfer, are transferred over IRC, the actual file transfer
+      # happens directly between two clients. As such it doesn't put
+      # stress on the IRC server.
+      #
+      # Cinch allows sending files by either using
+      # {Cinch::User#dcc_send}, which takes care of all parameters as
+      # well as setting up resume support, or by creating instances of
+      # this class directly. The latter will only be useful to people
+      # working on the Cinch code itself.
+      #
+      # {Cinch::User#dcc_send} expects an object to send as well as
+      # optionaly a file name, which is sent to the receiver as a
+      # suggestion where to save the file. If no file name is
+      # provided, the method will use the object's `#path` method to
+      # determine it.
+      #
+      # Any object that implements {DCC::DCCableObject} can be sent,
+      # but sending files will probably be the most common case.
+      #
+      # If you're behind a NAT it is necessary to explicitly set the
+      # external IP using the {file:bot_options.md#dccownip dcc.own_ip
+      # option}.
+      #
+      # @example Sending a file to a user
+      #   match "send me something"
+      #   def execute(m)
+      #     m.user.dcc_send(open("/tmp/cookies"))
+      #   end
+      class Send
+        # @param [Hash] opts
+        # @option opts [User] receiver
+        # @option opts [String] filename
+        # @option opts [File] io
+        # @option opts [String] own_ip
+        def initialize(opts = {})
+          @receiver, @filename, @io, @own_ip = opts.values_at(:receiver, :filename, :io, :own_ip)
+        end
+
+        # Start the server
+        #
+        # @return [void]
+        def start_server
+          @socket = TCPServer.new(0)
+          @socket.listen(1)
+        end
+
+        # Send the handshake to the user.
+        #
+        # @return [void]
+        def send_handshake
+          handshake = "\001DCC SEND %s %d %d %d\001" % [@filename, IPAddr.new(@own_ip).to_i, port, @io.size]
+          @receiver.send(handshake)
+        end
+
+        # Listen for an incoming connection.
+        #
+        # This starts listening for an incoming connection to the server
+        # started by {#start_server}. After a client successfully
+        # connected, the server socket will be closed and the file
+        # transferred to the client.
+        #
+        # @raise [Timeout::Error] Raised if the receiver did not connect
+        #   within 30 seconds
+        # @return [void]
+        # @note This method blocks.
+        def listen
+          begin
+            fd = nil
+            Timeout.timeout(30) do
+              fd, _ = @socket.accept
+              send_data(fd)
+              fd.close
+            end
+          ensure
+            @socket.close
+          end
+        end
+
+        # Seek to `pos` in the data.
+        #
+        # @param [Number] pos
+        # @return [void]
+        # @api private
+        def seek(pos)
+          @io.seek(pos)
+        end
+
+        # @return [Number] The port used for the socket
+        def port
+          @port ||= @socket.addr[1]
+        end
+
+        private
+        def send_data(fd)
+          @io.advise(:sequential)
+
+          while chunk = @io.read(8096)
+            rs, ws = IO.select([fd], [fd])
+            rs.first.recv         unless rs.empty?
+            ws.first.write(chunk) unless ws.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cinch/exceptions.rb

@@ -1,9 +1,11 @@
 module Cinch
+  # A collection of exceptions.
   module Exceptions
     # Generic error. Superclass for all Cinch-specific errors.
     class Generic < ::StandardError
     end
 
+    # Generic error when an argument is too long.
     class ArgumentTooLong < Generic
     end
 
@@ -19,15 +21,20 @@ module Cinch
     class KickReasonTooLong < ArgumentTooLong
     end
 
+    # Raised whenever Cinch discovers a feature it doesn't support
+    # yet.
     class UnsupportedFeature < Generic
     end
 
+    # Raised when Cinch discovers a user or channel mode, which it
+    # doesn't support yet.
     class UnsupportedMode < Generic
       def initialize(mode)
-        super "Cinch does not support the mode #{mode} yet."
+        super "Cinch does not support the mode '#{mode}' yet."
       end
     end
 
+    # Error stating that an invalid mode string was encountered.
     class InvalidModeString < Generic
     end
   end

data/lib/cinch/formatting.rb

@@ -0,0 +1,106 @@
+module Cinch
+  # @since 2.0.0
+  #
+  # List of valid colors
+  # =========================
+  # - aqua
+  # - black
+  # - blue
+  # - brown
+  # - green
+  # - grey
+  # - lime
+  # - orange
+  # - pink
+  # - purple
+  # - red
+  # - royal
+  # - silver
+  # - teal
+  # - white
+  # - yellow
+  #
+  # List of valid attributes
+  # ========================
+  # - bold
+  # - italic
+  # - reverse/reversed
+  # - underline/underlined
+  #
+  # Other
+  # =====
+  # - reset (Resets all formatting to the client's defaults)
+  module Formatting
+    # @private
+    Colors = {
+      :white  => "00",
+      :black  => "01",
+      :blue   => "02",
+      :green  => "03",
+      :red    => "04",
+      :brown  => "05",
+      :purple => "06",
+      :orange => "07",
+      :yellow => "08",
+      :lime   => "09",
+      :teal   => "10",
+      :aqua   => "11",
+      :royal  => "12",
+      :pink   => "13",
+      :grey   => "14",
+      :silver => "15",
+    }
+
+    # @private
+    Attributes = {
+      :bold       => 2.chr,
+      :underlined => 31.chr,
+      :underline  => 31.chr,
+      :reversed   => 22.chr,
+      :reverse    => 22.chr,
+      :italic     => 22.chr,
+      :reset      => 15.chr,
+    }
+
+    # @param [Array<Symbol>] *settings The colors and attributes to apply.
+    #   When supplying two colors, the first will be used for the
+    #   foreground and the second for the background.
+    # @param [String] string The string to format.
+    # @return [String] The formatted string
+    # @since 2.0.0
+    # @raise [ArgumentError] When passing more than two colors as arguments.
+    # @see Helpers#Format Helpers#Format for easier access to this method.
+    #
+    # @example Nested formatting, combining text styles and colors
+    #   reply = Format(:underline, "Hello %s! Is your favourite color %s?" % [Format(:bold, "stranger"), Format(:red, "red")])
+    def self.format(*settings, string)
+      string   = string.dup
+
+      attributes = settings.select {|k| Attributes.has_key?(k)}.map {|k| Attributes[k]}
+      colors = settings.select {|k| Colors.has_key?(k)}.map {|k| Colors[k]}
+      if colors.size > 2
+        raise ArgumentError, "At most two colors (foreground and background) might be specified"
+      end
+
+      attribute_string = attributes.join
+      color_string = if colors.empty?
+                       ""
+                     else
+                       "\x03#{colors.join(",")}"
+                     end
+
+      prepend = attribute_string + color_string
+      append  = Attributes[:reset]
+
+      # attributes act as toggles, so e.g. underline+underline = no
+      # underline. We thus have to delete all duplicate attributes
+      # from nested strings.
+      string.delete!(attribute_string)
+
+      # Replace the reset code of nested strings to continue the
+      # formattings of the outer string.
+      string.gsub!(/#{Attributes[:reset]}/, Attributes[:reset] + prepend)
+      return prepend + string + append
+    end
+  end
+end

data/lib/cinch/handler.rb

@@ -0,0 +1,104 @@
+module Cinch
+  # @since 2.0.0
+  class Handler
+    # @return [Bot]
+    attr_reader :bot
+
+    # @return [Symbol]
+    attr_reader :event
+
+    # @return [Pattern]
+    attr_reader :pattern
+
+    # @return [Array]
+    attr_reader :args
+
+    # @return [Proc]
+    attr_reader :block
+
+    # @return [Symbol]
+    attr_reader :group
+
+    # @return [ThreadGroup]
+    # @api private
+    attr_reader :thread_group
+
+    # @param [Bot] bot
+    # @param [Symbol] event
+    # @param [Pattern] pattern
+    # @param [Hash] options
+    # @option options [Symbol] :group (nil) Match group the h belongs
+    #   to.
+    # @option options [Boolean] :execute_in_callback (false) Whether
+    #   to execute the handler in an instance of {Callback}
+    # @option options [Array] :args ([]) Additional arguments to pass
+    #   to the block
+    def initialize(bot, event, pattern, options = {}, &block)
+      options              = {:group => nil, :execute_in_callback => false, :args => []}.merge(options)
+      @bot                 = bot
+      @event               = event
+      @pattern             = pattern
+      @group               = options[:group]
+      @execute_in_callback = options[:execute_in_callback]
+      @args                = options[:args]
+      @block               = block
+
+      @thread_group = ThreadGroup.new
+    end
+
+    # Unregisters the handler.
+    #
+    # @return [void]
+    def unregister
+      @bot.handlers.unregister(self)
+    end
+
+    # Stops execution of the handler. This means stopping and killing
+    # all associated threads.
+    #
+    # @return [void]
+    def stop
+      @bot.loggers.debug "[Stopping handler] Stopping all threads of handler #{self}: #{@thread_group.list.size} threads..."
+      @thread_group.list.each do |thread|
+        Thread.new do
+          @bot.loggers.debug "[Ending thread] Waiting 10 seconds for #{thread} to finish..."
+          thread.join(10)
+          @bot.loggers.debug "[Killing thread] Killing #{thread}"
+          thread.kill
+        end
+      end
+    end
+
+    # Executes the handler.
+    #
+    # @param [Message] message Message that caused the invocation
+    # @param [Array] captures Capture groups of the pattern that are
+    #   being passed as arguments
+    # @return [void]
+    def call(message, captures, arguments)
+      bargs = captures + arguments
+
+      @thread_group.add Thread.new {
+        @bot.loggers.debug "[New thread] For #{self}: #{Thread.current} -- #{@thread_group.list.size} in total."
+
+        begin
+          if @execute_in_callback
+            @bot.callback.instance_exec(message, *@args, *bargs, &@block)
+          else
+            @block.call(message, *@args, *bargs)
+          end
+        rescue => e
+          @bot.loggers.exception(e)
+        ensure
+          @bot.loggers.debug "[Thread done] For #{self}: #{Thread.current} -- #{@thread_group.list.size - 1} remaining."
+        end
+      }
+    end
+
+    # @return [String]
+    def to_s
+      # TODO maybe add the number of running threads to the output?
+      "#<Cinch::Handler @event=#{@event.inspect} pattern=#{@pattern.inspect}>"
+    end
+  end
+end