grinch 1.0.0

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 [Integer] 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 [Integer] 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 [Integer] 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,147 @@
+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
+      #
+      # @attr_reader filename
+      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 [Integer]
+        attr_reader :size
+
+        # @return [String]
+        attr_reader :ip
+
+        # @return [Fixnum]
+        attr_reader :port
+
+        # @param [Hash] opts
+        # @option opts [User] user
+        # @option opts [String] filename
+        # @option opts [Integer] size
+        # @option opts [String] ip
+        # @option opts [Fixnum] 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 [Boolean] True if the transfer finished
+        #   successfully, false otherwise.
+        # @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.readpartial(8192)
+            total += buf.bytesize
+
+            begin
+              socket.write_nonblock [total].pack("N")
+            rescue Errno::EWOULDBLOCK, Errno::AGAIN
+              # Nobody cares about ACKs, really. And if the sender
+              # couldn't receive it at this point, they probably don't
+              # care, either.
+            end
+            io << buf
+
+            # Break here in case the sender doesn't close the
+            # connection on the final ACK.
+            break if total == @size
+          end
+
+          socket.close
+          return true
+        rescue EOFError
+          return false
+        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,122 @@
+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:docs/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
+            end
+            send_data(fd)
+            fd.close
+          ensure
+            @socket.close
+          end
+        end
+
+        # Seek to `pos` in the data.
+        #
+        # @param [Integer] pos
+        # @return [void]
+        # @api private
+        def seek(pos)
+          @io.seek(pos)
+        end
+
+        # @return [Fixnum] 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)
+            while true
+              rs, ws = IO.select([fd], [fd])
+              if !rs.empty?
+                rs.first.recv(8096)
+              end
+              if !ws.empty?
+                ws.first.write(chunk)
+                break
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cinch/exceptions.rb

@@ -0,0 +1,46 @@
+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
+
+    # Error that is raised when a topic is too long to be set.
+    class TopicTooLong < ArgumentTooLong
+    end
+
+    # Error that is raised when a nick is too long to be used.
+    class NickTooLong < ArgumentTooLong
+    end
+
+    # Error that is raised when a kick reason is too long.
+    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."
+      end
+    end
+
+    # Error stating that an invalid mode string was encountered.
+    class InvalidModeString < Generic
+    end
+
+    # Raised when a synced attribute hasn't been available for too
+    # long.
+    class SyncedAttributeNotAvailable < Generic
+    end
+  end
+end

data/lib/cinch/formatting.rb

@@ -0,0 +1,125 @@
+module Cinch
+  # This module can be used for adding and removing colors and
+  # formatting to/from messages.
+  #
+  # The format codes used are those defined by mIRC, which are also
+  # the ones supported by most clients.
+  #
+  # For usage instructions and examples, see {.format}.
+  #
+  # 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)
+  #
+  # @since 2.0.0
+  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     => 29.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
+
+    # Deletes all mIRC formatting codes from the string. This strips
+    # formatting for bold, underline and so on, as well as color
+    # codes. This does include removing the numeric arguments.
+    #
+    # @param [String] string The string to filter
+    # @return [String] The filtered string
+    # @since 2.2.0
+    def self.unformat(string)
+      string.gsub(/[\x02\x0f\x16\x1f\x12]|\x03(\d{1,2}(,\d{1,2})?)?/, '')
+    end
+  end
+end