blur 1.5.3 → 1.6

data/library/blur.rb

@@ -5,15 +5,37 @@ require 'majic'
 require 'socket'
 require 'ostruct'
 require 'openssl'
+require 'eventmachine'
 
-Dir.glob("#{File.dirname __FILE__}/blur/**/*.rb").each &method(:require)
+# Require all library files.
+require 'blur/client'
+require 'blur/script'
+require 'blur/network'
+require 'blur/encryption'
+require 'blur/enhancements'
+require 'blur/script/cache'
+require 'blur/network/user'
+require 'blur/network/channel'
+require 'blur/network/command'
+require 'blur/network/connection'
+require 'blur/script/messageparsing'
 
+# Blur is a very modular IRC-framework for ruby.
+#
+# It allows the developer to extend it in multiple ways.
+# It can be by handlers, scripts, communications, and what have you.
 module Blur
-  class << Version = [1,5,3]
-    def to_s; join '.' end
-  end
+  # The major and minor version-values of Blur.
+  Version = "1.6"
 
-  def self.connect options, &block
+  # Instantiates a client with given options and then makes the client instance
+  # evaluate the given block to form a DSL.
+  #
+  # @note The idea is that this should never stop or return anything.
+  # @param [Hash] options the options for the client.
+  # @option options [Array] networks list of hashes that contain network
+  #   options.
+  def self.connect options = {}, &block
     Client.new(options).tap do |client|
       client.instance_eval &block
     end.connect

data/library/blur/client.rb

@@ -3,35 +3,59 @@
 require 'blur/handling'
 
 module Blur
+  # The +Client+ class is the controller of the low-level access.
+  #
+  # It stores networks, scripts and callbacks, and is also encharge of
+  # distributing the incoming commands to the right networks and scripts.
   class Client
     include Handling
     
-    attr_accessor :options, :scripts, :networks
+    # @return [Array] the options that is passed upon initialization.
+    attr_accessor :options
+    # @return [Array] a list of scripts that is loaded during runtime.
+    attr_accessor :scripts
+    # @return [Array] a list of instantiated networks.
+    attr_accessor :networks
     
+    # Instantiates the client, stores the options, instantiates the networks
+    # and then loads available scripts.
+    #
+    # @param [Hash] options the options for the client.
+    # @option options [Array] networks list of hashes that contain network
+    #   options.
     def initialize options
       @options   = options
       @scripts   = []
       @networks  = []
       @callbacks = {}
-      @connected = true
       
-      @networks = @options[:networks].map { |options| Network.new options }
+      @networks = @options[:networks].map {|options| Network.new options }
       
       load_scripts
       trap 2, &method(:quit)
     end
     
+    # Connect to each network available that is not already connected, then
+    # proceed to start the run-loop.
     def connect
-      networks = @networks.select { |network| not network.connected? }
+      networks = @networks.select {|network| not network.connected? }
       
-      networks.each do |network|
-        network.delegate = self
-        network.connect
+      EventMachine.run do
+        networks.each do |network|
+          network.delegate = self
+          network.connect
+        end
+
+        EventMachine.error_handler{|e| p e }
       end
-      
-      run_loop
     end
     
+    # Is called when a command have been received and parsed, this distributes
+    # the command to the loader, which then further distributes it to events
+    # and scripts.
+    #
+    # @param [Network] network the network that received the command.
+    # @param [Network::Command] command the received command.
     def got_command network, command
       puts "<- #{network.inspect ^ :bold} | #{command}"
       name = :"got_#{command.name.downcase}"
@@ -41,6 +65,7 @@ module Blur
       end
     end
     
+    # Searches for scripts in working_directory/scripts and then loads them.
     def load_scripts
       script_path = File.dirname $0
       
@@ -52,50 +77,38 @@ module Blur
       end
     end
     
+    # Unload all scripts gracefully that have been loaded into the client.
+    #
+    # @see Script#unload!
     def unload_scripts
       @scripts.each do |script|
         script.unload!
       end.clear
     end
     
-    def quit signal
+    # Try to gracefully disconnect from each network, unload all scripts and
+    # exit properly.
+    #
+    # @param [optional, Symbol] signal The signal received by the system, if any.
+    def quit signal = :SIGINT
       @networks.each do |network|
         network.transmit :QUIT, "Got SIGINT?"
-        network.transcieve
         network.disconnect
       end
       
-      @connected = false
       unload_scripts
       
-      exit 0
-    end
-    
-  private
-    
-    def run_loop
-      puts "Starting run loop ..."
-      
-      while @connected
-        @networks.select(&:connected?).each do |network|
-          begin
-            network.transcieve
-            sleep 0.05
-          rescue StandardError => exception
-            if network.connected?
-              network.disconnect
-            end
-
-            emit :connection_terminated, network
-
-            puts "#{"Network error" ^ :red} (#{exception.class.name}): #{exception.message}"
-          end
-        end
-      end
-
-      puts "Ended run loop ..."
+      EventMachine.stop
     end
     
+  private    
+    # Finds all callbacks with name `name` and then calls them.
+    # It also sends `name` to {Script} if the script responds to `name`, to all
+    #   available scripts.
+    #
+    # @param [Symbol] name the corresponding event-handlers name.
+    # @param [...] args Arguments that is passed to the event-handler.
+    # @private
     def emit name, *args
       @callbacks[name].each do |callback|
         callback.call *args
@@ -110,6 +123,11 @@ module Blur
       end
     end
     
+    # Stores the block as an event-handler with name `name`.
+    #
+    # @param [Symbol] name the corresponding event-handlers name.
+    # @param [Block] block the event-handlers block that serves as a trigger.
+    # @private
     def catch name, &block
       (@callbacks[name] ||= []) << block
     end

data/library/blur/encryption.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+module Blur
+  # The +Encryption+ module extends the communication-functionality of
+  # the client. It is intended to enable helpers but also core functionality
+  # that encrypts the incoming and outgoing data of Blur.
+  #
+  # Encryption modules are not loaded into the VM until it's required.
+  module Encryption
+    # Indicates that user-input (a channel user message, e.g.) is in invalid
+    # format to a certain encryption algorithm.
+    class BadInputError < StandardError; end
+
+    autoload :FiSH,   "blur/encryption/fish"
+    autoload :Base64, "blur/encryption/base64"
+  end
+end

data/library/blur/encryption/base64.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+module Blur
+  module Encryption
+    # The +Encryption::Base64+ module differs from the original Base64
+    # implementation. I'm not sure how exactly, perhaps the charset?
+    #
+    # I originally found the Ruby implementation of FiSH on a website where
+    # it was graciously submitted by an anonymous user, since then I've
+    # implemented it in a weechat script, and now I've refactored it for use in
+    # Blur.
+    #
+    # @see http://maero.dk/pub/sources/weechat/ruby/autoload/fish.rb
+    module Base64
+      # The difference I suspect between the original Base64 implementation
+      # and the one used in FiSH.
+      Charset = "./0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+      # Decode a base64-encoded string.
+      #
+      # @return [String] Base64-decoded string.
+      def self.decode string
+        unless string.length % 12 == 0
+          raise BadInputError, "input has to be a multiple of 12 characters."
+        end
+
+        String.new.tap do |buffer|
+          j = -1
+          
+          while j < string.length - 1
+            right, left = 0, 0
+
+            6.times{|i| right |= Charset.index(string[j += 1]) << (i * 6) }
+            6.times{|i| left  |= Charset.index(string[j += 1]) << (i * 6) }
+
+            4.times do |i|
+              buffer << ((left & (0xFF << ((3 - i) * 8))) >> ((3 - i) * 8)).chr
+            end
+
+            4.times do |i|
+              buffer << ((right & (0xFF << ((3 - i) * 8))) >> ((3 - i) * 8)).chr
+            end
+          end
+        end
+      end
+
+      # Encode a string-cipher.
+      #
+      # @return [String] Base64-encoded string.
+      def self.encode string
+        unless string.length % 8 == 0
+          raise BadInputError, "input has to be a multiple of 8 characters."
+        end
+
+        left = 0
+        right = 0
+        decimals = [24, 16, 8, 0]
+
+        String.new.tap do |buffer|
+          string.each_block do |block|
+            4.times{|i| left  += (block[i].ord << decimals[i]) }
+            4.times{|i| right += (block[i+4].ord << decimals[i]) }
+
+            6.times{|i| buffer << Charset[right & 0x3F].chr; right = right >> 6 }
+            6.times{|i| buffer << Charset[left  & 0x3F].chr; left = left >> 6 }
+          end
+        end
+      end
+    end
+  end
+end

data/library/blur/encryption/fish.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+
+require 'crypt/blowfish'
+
+module Blur
+  module Encryption
+    # The +FiSH+ algorithm is a combination of Base64 encoding
+    # and the blowfish encryption.
+    #
+    # Shared text messages are prepended by "++OK+", an older implementation
+    # prepends it with "+mcps+" - Blur drops support for that implementation.
+    #
+    # There's multiple client-implementations available on the official FiSH
+    # homepage.
+    #
+    # == DH1080 Key exchange
+    # The newer FiSH implementation introduces a 1080bit Diffie-Hellman 
+    # key-exchange mechanism.
+    #
+    # Blur does currently not support key exchanges.
+    class FiSH
+      # The standard FiSH block-size.
+      BlockSize = 8
+
+      # @return [String] the blowfish salt-key.
+      attr_accessor :keyphrase      
+
+      # Change the keyphrase and instantiate a new blowfish object.
+      def keyphrase= keyphrase
+        @keyphrase = keyphrase
+        @blowfish = Crypt::Blowfish.new @keyphrase
+      end
+
+      # Instantiate a new fish-encryption object.
+      def initialize keyphrase
+        @keyphrase = keyphrase
+        @blowfish = Crypt::Blowfish.new keyphrase
+      end
+
+      # Encrypt an input string using the keyphrase stored in the +@blowfish+
+      # object.
+      #
+      # @return [String] the encrypted string.
+      def encrypt string
+        String.new.tap do |buffer|
+          nullpad(string).each_block do |block|
+            chunk = @blowfish.encrypt_block block
+            buffer.concat Base64.encode chunk
+          end
+        end
+      end
+
+      # Decrypt an input string using the keyphrase stored in the +@blowfish+
+      # object.
+      #
+      # @return [String] the decrypted string.
+      def decrypt string
+        unless string.length % 12 == 0
+          raise BadInputError, "input has to be a multiple of 12 characters."
+        end
+          
+        String.new.tap do |buffer|
+          string.each_block 12 do |block|
+            chunk = @blowfish.decrypt_block Base64.decode block
+            buffer.concat chunk
+          end
+        end.rstrip
+      end
+      
+    private
+      # Fill up the last block with null-bytes until it's a multiple of 8.
+      #
+      # @return [String] the nullpadded string.
+      def nullpad string
+        length = string.length + BlockSize - string.length % BlockSize
+        string.ljust length, ?\0
+      end
+    end
+  end
+end

data/library/blur/enhancements.rb

@@ -1,17 +1,39 @@
 # encoding: utf-8
 
+# Reopens the scope of the standard Exception-class to extend it with helpful
+# methods.
 class Exception
+  # The pattern to match against the backtrace log.
   Pattern = /^.*?:(\d+):/
   
+  # Retrieve the line on which the exception was raised from when raised inside
+  # a script.
+  #
+  # @return Fixnum the line of the script the exception was raised on.
   def line
     backtrace[0].match(Pattern)[1].to_i + 1
   end
 end
 
+# Reopens the scope of the standard String-class to extend it with helpful
+# methods.
 class String
+  # Checks if the string contains nothing but a numeric value.
+  #
+  # @return true if it is a numeric value.
   def numeric?
     self =~ /^\d+$/
   end
 
+  # Split a string up in n chunks and then iterate through them, exactly like
+  # Enumerable#each_slice.
+  #
+  # @return [Enumerator] list of slices.
+  # @yieldreturn [Array] list of elements in each slice consecutively.
+  def each_slice size = 8
+    self.chars.each_slice(size).each{|slice| yield slice.join }
+  end
+
   alias_method :starts_with?, :start_with?
+  alias_method :each_block, :each_slice
 end

data/library/blur/handling.rb

@@ -2,11 +2,41 @@
 
 module Blur
   class Client
+    # The +Handling+ module is the very core of the IRC-part in Blur.
+    #
+    # When the client receives a parsed command instance, it immediately starts
+    # looking for a got_(the command name) method inside the client, which
+    # is implemented in this module.
+    #
+    # == Implementing a handler
+    # Implementing a handler is very, very easy.
+    #
+    # All you need to do is define a method named got_(command you want to
+    # implement) that accepts 2 parameters, +network+ and +command+.
+    #
+    # You can then do whatever you need to do with the command instance,
+    # you can access the parameters of it through {Network::Command#[]}.
+    #
+    # Don't forget that this module is inside the clients scope, so you can
+    # access all instance-variables and methods.
+    #
+    # @example
+    #   # RPL_WHOISUSER
+    #   # <nick> <user> <host> * :<real name>
+    #   def got_whois_user network, command
+    #     puts "nick: #{command[0]} user: #{command[1]} host: #{command[2]} …"
+    #   end
+    #   
+    # @see http://www.irchelp.org/irchelp/rfc/chapter6.html
     module Handling
-
     protected
     
-      # End of MOTD
+      # Called when the MOTD was received, which also means it is ready.
+      #
+      # == Callbacks:
+      # Emits +:connection_ready+ with the parameter +network+.
+      #
+      # Automatically joins the channels specified in +:channels+.
       def got_end_of_motd network, command
         emit :connection_ready, network
         
@@ -15,8 +45,8 @@ module Blur
         end
       end
       
-      # The /NAMES list
-      def got_353 network, command
+      # Called when the namelist of a channel was received.
+      def got_name_reply network, command
         name  = command[2]
         users = command[3].split.map &Network::User.method(:new)
         
@@ -28,30 +58,46 @@ module Blur
             channel.users << user
           end
         else
-          network.channels.<< Network::Channel.new name, network, users
+          channel = Network::Channel.new name, network, users
+
+          if network.fish? and network.options[:fish].key? name
+            keyphrase = network.options[:fish][name]
+            channel.encryption = Encryption::FiSH.new keyphrase
+          end
+
+          network.channels << channel
         end
       end
       
-      # A channels topic
-      def got_332 network, command
+      # Called when a channel topic was changed.
+      #
+      # == Callbacks:
+      # Emits :topic_change with the parameters +channel+ and +topic+.
+      def got_channel_topic network, command
         me, name, topic = command.params
         
         if channel = network.channel_by_name(name)
+          emit :topic_change, channel, topic
           channel.topic = topic
         else
           channel = Network::Channel.new name, network, []
+          emit :topic_change, channel, topic
           channel.topic = topic
           
           network.channels << channel
         end
       end
       
-      # Are we still breathing?
+      # Called when the server needs to verify that we're alive.
       def got_ping network, command
         network.transmit :PONG, command[0]
       end
       
-      # Someone changed their nickname
+      # Called when a user changed nickname.
+      #
+      # == Callbacks:
+      # Emits :user_rename with the parameters +channel+, +user+ and +nickname+ 
+      # where +nickname+ is the new name.
       def got_nick network, command
         nick = command.sender.nickname
         
@@ -65,7 +111,15 @@ module Blur
         end
       end
       
-      # Someone send a message
+      # Called when a message was received (both channel and private messages).
+      #
+      # == Callbacks:
+      # === When it's a channel message:
+      # Emits +:message+ with the parameters +user+, +channel+ and +message+.
+      # === When it's a private message:
+      # Emits +:private_message+ with the parameters +user+ and +message+.
+      #
+      # @note Messages are contained as strings.
       def got_privmsg network, command
         return if command.sender.is_a? String # Ignore all server privmsgs
         name, message = command.params
@@ -74,6 +128,18 @@ module Blur
           if user = channel.user_by_nick(command.sender.nickname)
             user.name = command.sender.username
             user.host = command.sender.hostname
+
+            begin
+              if message[0..3] == "+OK " and channel.encrypted?
+                message = channel.encryption.decrypt message[4..-1]
+              end
+            rescue Encryption::BadInputError
+              # …
+            rescue => exception
+              puts "-!- There was a problem with the FiSH encryption, disabling"
+
+              channel.encryption = nil
+            end
             
             emit :message, user, channel, message
           else
@@ -89,7 +155,10 @@ module Blur
         end
       end
       
-      # Someone joined a channel
+      # Called when a user joined a channel.
+      #
+      # == Callbacks:
+      # Emits +:user_entered+ with the parameters +channel+ and +user+.
       def got_join network, command
         name = command[0]
         user = Network::User.new command.sender.nickname
@@ -106,7 +175,10 @@ module Blur
         end
       end
       
-      # Someone left a channel
+      # Called when a user left a channel.
+      #
+      # == Callbacks:
+      # Emits +:user_left+ with the parameters +channel+ and +user+.
       def got_part network, command
         name = command[0]
         
@@ -119,7 +191,10 @@ module Blur
         end
       end
       
-      # Someone quit irc
+      # Called when a user disconnected from a network.
+      #
+      # == Callbacks:
+      # Emits +:user_quit+ with the parameters +channel+ and +user+.
       def got_quit network, command
         nick = command.sender.nickname
         
@@ -134,7 +209,13 @@ module Blur
         end
       end
       
-      # Someone got kicked
+      # Called when a user was kicked from a channel.
+      #
+      # == Callbacks:
+      # Emits +:user_kicked+ with the parameters +kicker+, +channel+, +kickee+
+      # and +reason+.
+      #
+      # +kicker+ is the user that kicked +kickee+.
       def got_kick network, command
         name, target, reason = command.params
         
@@ -149,6 +230,10 @@ module Blur
         end
       end
       
+      # Called when a topic was changed for a channel.
+      #
+      # == Callbacks:
+      # Emits :topic with the parameters +user+, +channel+ and +topic+.
       def got_topic network, command
         name, topic = command.params
         
@@ -161,6 +246,13 @@ module Blur
         end
       end
 
+      # Called when a channel or a users flags was altered.
+      #
+      # == Callbacks:
+      # === When it's channel modes:
+      # Emits +:channel_mode+ with the parameters +channel+ and +modes+.
+      # === When it's user modes:
+      # Emits +:user_mode+ with the parameters +user+ and +modes+.
       def got_mode network, command
         name, modes, limit, nick, mask = command.params
 
@@ -181,8 +273,10 @@ module Blur
         end
       end
 
+      alias_method :got_353, :got_name_reply
       alias_method :got_422, :got_end_of_motd
       alias_method :got_376, :got_end_of_motd
+      alias_method :got_332, :got_channel_topic
     end
   end
 end