ruggby 0.3.0

data/CHANGELOG.rdoc

@@ -0,0 +1,2 @@
+= Version 0.1.0
+* Basic functionality: login, change status, send messages, receive messages

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Maciej Mensfeld
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -0,0 +1,38 @@
+CHANGELOG.rdoc
+Gemfile
+MIT-LICENSE
+README.md
+Rakefile
+init.rb
+lib/ruggby.rb
+lib/ruggby/action/base.rb
+lib/ruggby/action/change_status.rb
+lib/ruggby/action/create_message.rb
+lib/ruggby/action/login.rb
+lib/ruggby/action/mark.rb
+lib/ruggby/action/new_message.rb
+lib/ruggby/action/ping.rb
+lib/ruggby/action/read.rb
+lib/ruggby/callback.rb
+lib/ruggby/client.rb
+lib/ruggby/converter.rb
+lib/ruggby/logger.rb
+lib/ruggby/packet/factory.rb
+lib/ruggby/packet/incoming/base.rb
+lib/ruggby/packet/incoming/login_status.rb
+lib/ruggby/packet/incoming/message.rb
+lib/ruggby/packet/incoming/welcome.rb
+lib/ruggby/packet/outgoing/base.rb
+lib/ruggby/packet/outgoing/change_status.rb
+lib/ruggby/packet/outgoing/login.rb
+lib/ruggby/packet/outgoing/mark.rb
+lib/ruggby/packet/outgoing/message.rb
+lib/ruggby/packet/outgoing/ping.rb
+lib/ruggby/password.rb
+lib/ruggby/socket.rb
+lib/ruggby/string_encoder.rb
+lib/ruggby/threader.rb
+lib/ruggby/version.rb
+spec/callback_spec.rb
+spec/spec_helper.rb
+Manifest

data/README.md

@@ -0,0 +1,187 @@
+# ruGGby - Gadu Gadu protocol client implementation in pure Ruby language
+
+## Install
+
+```ruby
+gem install ruggby
+```
+
+and in your Gemfile:
+
+```ruby
+gem 'ruggby'
+```
+
+## About
+
+ruGGby is a Gadu-Gadu (Polish messenger similar to ICQ) protocol client, which allows you to:
+
+* Login to your Gadu-Gadu account
+* Set and change status and description
+* Receive messages
+* Send messages
+* Perform callbacks on almost every event connected to GG handling
+* Works with big GG numbers
+* Works with polish letters and other UTF-8 characters
+
+## Usage
+
+Let's start with a simple example:
+
+### Simple example
+```ruby
+gg = RuGGby::Client.new
+
+gg.login!(LOGIN, PASSWORD)
+gg.message(RECEIVER_GG, 'this is a message')
+gg.logout!
+```
+
+So, what have we done? We've created an Gadu-Gadu instance client, logged in, sent a message and logged out. Easy enough ;)
+
+### Login in and login out
+
+Log in/out process is fairly simple:
+
+```ruby
+gg = RuGGby::Client.new
+
+gg.login!(LOGIN, PASSWORD)
+gg.logout!
+```
+
+We can also pass two additional parameters to *login!* method:
+
+* :status - initial GG status
+* :description - initial GG description
+
+So the "full" login would look like:
+
+```ruby
+gg = RuGGby::Client.new
+
+gg.login!(LOGIN, PASSWORD, :status => :busy, :description => '2Busy')
+```
+
+### Updating status and description
+
+Sometimes we want to update our status. In order to do so, invoke a *change_status* method with two parameters:
+
+* status - status symbol
+* description (optional) - optional description for status
+
+The allowed statuses are:
+
+* :available
+* :busy
+* :invisible
+
+```ruby
+gg.change_status(:busy, 'I\'m so busy right now!')
+```
+
+### Keeping ruGGby bot alive
+
+To keep the bot working, just invoke the *wait* method and it will exit:
+
+```ruby
+gg = RuGGby::Client.new
+
+gg.on_new_message do |uid, time, message|
+  gg.message(uid, message)
+end
+
+gg.login!(LOGIN, PASSWORD)
+gg.wait
+```
+
+### Logger
+
+By default RuGGby uses a *RuGGby::Logger* logger, which only prints output to console. However, you can replace it with any logger that support following methods:
+
+* *debug*(message)
+* *info*(message)
+* *error*(message)
+* *fatal*(message)
+
+To do so, create an *RuGGby::Client* instance and assign your own logger:
+
+```ruby
+require 'logger'
+
+gg = RuGGby::Client.new
+gg.logger = Logger.new('gg.log', :weekly)
+```
+
+In order to change log level, just assing a new one like this:
+
+```ruby
+RuGGby::Client.log_level = :error
+```
+
+### Events
+
+RuGGby supports events, so you can assign your own events on demand. Events list:
+
+* :read - event triggered on each read from RuGGby::Socket
+* :ping - event triggered on each GG Server Ping
+* :new_message - event triggered on new message receive
+* :mark - event triggered when we send mark packet to GG Server
+* :login - event triggered after login
+* :create_message - event triggered after message has been send
+* :change_status - event triggered after our status/description change
+
+Each event block is triggered with parameters:
+
+* :read(packet) - *RuGGby::Packet* instance (build using *RuGGby::Packet::Factory*)
+* :ping - no parameters
+* :new_message(uin, timestamp, message)
+* :mark - no parameters
+* :login - no parameters
+* :create_message(uin, message)
+* :change_status(status, description)
+
+In order to assign an action to an event, pass a block into events hash:
+
+```ruby
+gg = RuGGby::Client.new
+
+gg.actions[:new_message] = proc do |uin, created_at, msg|
+  # uin is a sender GG number (Integer)
+  # created_at - Time.at when message has been sent
+  # msg - String containing message
+  print "#{uin}-#{created_at}: #{msg}\n"
+end
+```
+
+However most of the events don't need an action so you can use *on_new_message* method to assign a block:
+
+```ruby
+gg = RuGGby::Client.new
+
+gg.on_new_message do |uid, time, message|
+  gg.message(uid, message)
+end
+```
+
+The *:new_message* event is triggered in a separate thread so the socket read process is still going. The above code will (after login!) return a message to it's sender.
+
+## TODO
+
+* Tests (currently there is no :()
+* More sophisticated GG actions (friends, etc)
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with Rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2012 Maciej Mensfeld. See LICENSE for details.
+
+Based on http://toxygen.net/libgadu/protocol

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('ruggby', '0.3.0') do |p|
+  p.description    = 'Gadu Gadu protocol client implementation in Ruby language'
+  p.url            = 'https://github.com/mensfeld/ruGGby'
+  p.author         = 'Maciej Mensfeld'
+  p.email          = 'maciej@mensfeld.pl'
+  p.ignore_pattern = ['tmp/*', 'script/*']
+  p.development_dependencies = ['rspec >=2.0.0', 'mocha']
+end

data/init.rb

@@ -0,0 +1 @@
+require 'ruggby'

data/lib/ruggby.rb

@@ -0,0 +1,72 @@
+# RuGGby is a simple (not completed) implementation of a GG  written in Ruby
+# It allows us to login to our account and receive/send messages
+
+# Currently due to lack of time this are the only actions that are available
+
+# Usage example:
+
+# gg = RuGGby::Client.new
+#
+# gg.on_new_message do |uid, message|
+#   gg.message(uid, message)
+# end
+#
+# gg.login!(gg_nr, Pass)
+# gg.wait
+# gg.logout!
+
+$:.unshift File.dirname(__FILE__)
+
+module RuGGby
+
+  autoload :Version, 'ruggby/version.rb'
+
+  module Packet
+    # Factory used to build incoming packets out of raw socket messages
+    autoload :Factory, 'ruggby/packet/factory.rb'
+
+    # Incoming packets used to wrap the raw socket messages send by GG server
+    module Incoming
+      path = 'ruggby/packet/incoming'
+      autoload :Base,        "#{path}/base.rb"
+      autoload :LoginStatus, "#{path}/login_status.rb"
+      autoload :Message,     "#{path}/message.rb"
+      autoload :Welcome,     "#{path}/welcome.rb"
+    end
+
+    # Outgoing packets send to GG server
+    module Outgoing
+      path = 'ruggby/packet/outgoing'
+      autoload :Base,         "#{path}/base.rb"
+      autoload :Login,        "#{path}/login.rb"
+      autoload :Mark,         "#{path}/mark.rb"
+      autoload :Message,      "#{path}/message.rb"
+      autoload :Ping,         "#{path}/ping.rb"
+      autoload :ChangeStatus, "#{path}/change_status.rb"
+    end
+  end
+
+  # Available actions (we can hookup to all of them)
+  module Action
+    path = 'ruggby/action'
+    autoload :Base,          "#{path}/base.rb"
+    autoload :CreateMessage, "#{path}/create_message.rb"
+    autoload :Login,         "#{path}/login.rb"
+    autoload :Mark,          "#{path}/mark.rb"
+    autoload :NewMessage,    "#{path}/new_message.rb"
+    autoload :Ping,          "#{path}/ping.rb"
+    autoload :Read,          "#{path}/read.rb"
+    autoload :ChangeStatus,  "#{path}/change_status.rb"
+  end
+
+  # Other stuff that is needed
+  autoload :Socket,        'ruggby/socket'
+  autoload :Logger,        'ruggby/logger'
+  autoload :Callback,      'ruggby/callback'
+  autoload :Converter,     'ruggby/converter'
+  autoload :Password,      'ruggby/password'
+  autoload :Threader,      'ruggby/threader'
+  autoload :StringEncoder, 'ruggby/string_encoder'
+  autoload :Client,        'ruggby/client'
+
+end

data/lib/ruggby/action/base.rb

@@ -0,0 +1,16 @@
+module RuGGby
+
+  module Action
+
+    # Base class for all the event actions
+    class Base
+
+      def initialize(client)
+        @block = client.actions[:base]
+      end
+
+    end
+
+  end
+
+end

data/lib/ruggby/action/change_status.rb

@@ -0,0 +1,30 @@
+module RuGGby
+
+  module Action
+
+    # Action invoken when we want to change status
+    class ChangeStatus < Base
+
+      attr_reader :status, :description
+
+      def initialize(client, status, description)
+        @client      = client
+        @block       = client.actions[:change_status]
+        @status      = status
+        @description = description
+      end
+
+      def run!
+        @client.logger.debug('RuGGby::Action::ChangeStatus')
+
+        msg = Packet::Outgoing::ChangeStatus.new(@status, @description)
+        @client.socket.write(msg)
+
+        @block.call(@status, @description) if @block
+      end
+
+    end
+
+  end
+
+end

data/lib/ruggby/action/create_message.rb

@@ -0,0 +1,27 @@
+module RuGGby
+
+  module Action
+
+    # Sending message action
+    class CreateMessage < Base
+
+      def initialize(client, uin, message)
+        @client  = client
+        @block   = client.actions[:create_message]
+        @uin     = uin
+        @message = message
+      end
+
+      def run!
+        @client.logger.debug('RuGGby::Action::CreateMessage')
+
+        msg = Packet::Outgoing::Message.new(@uin, @message)
+        @client.socket.write(msg)
+        @block.call(@uin, @message) if @block
+      end
+
+    end
+
+  end
+
+end

data/lib/ruggby/action/login.rb

@@ -0,0 +1,40 @@
+module RuGGby
+
+  module Action
+
+    # Login action - will log user in to a GG account
+    class Login < Base
+
+      def initialize(client)
+        @client = client
+        @block  = client.actions[:login]
+      end
+
+      def run!
+        @client.logger.debug('RuGGby::Action::Login')
+
+        welcome = RuGGby::Packet::Factory.new(@client.socket).build
+
+        login = Packet::Outgoing::Login.new(
+          :uin         => @client.login,
+          :hash        => Password.hash(@client.password, welcome.seed),
+          :status      => @client.status,
+          :description => @client.description
+        )
+
+        @client.logger.debug('RuGGby::Action::Login sending Login packet')
+        @client.socket.write(login)
+
+        login_status = RuGGby::Packet::Factory.new(@client.socket).build
+
+        @client.logger.debug("RuGGby::Action::Login #{login_status.class}")
+        
+        @client.logged = login_status.successful?
+        @block.call if @block
+      end
+
+    end
+
+  end
+
+end