vines 0.4.9 → 0.4.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a444c695d79a88f165a9f86f2989eb27e128e79
-  data.tar.gz: 3b271ce86f7ada201e8788daef5d8c207190615b
+  metadata.gz: 377b65dfeb6ebd0ed33d7dcd0ddb99e125114597
+  data.tar.gz: 0a3addc473971d37aad7c4011909e22162fcf382
 SHA512:
-  metadata.gz: 8c258a7e3237ec24854ade1d9ac66de591440c48635e4a184a89abe0bf9171f4b48fea23f391fe665da6938a2d0c2964f4b0beb99e4f8959f1e225477fec0fa7
-  data.tar.gz: 30f2397168e45ac1e8ed911b6110750b2deb823f64e1f0908a60355f5a6732d4d938fa370945156b18c662e4091f8cb88653065a073c79dd7c1ebe728a48a1b8
+  metadata.gz: a10339115953bedabc5b5fae4ec56cd4281f4ac9ecc9b5484a870826f687238240d48350bd7b1dadc99f5d88b6bf5710572542794a74c3332dc8fe15a3a0ba5d
+  data.tar.gz: 8d65071c1112f5df81cbb347060f9a416520809f4d794b99bab6a1cfee4bc2c532ff299fa2fb8a8bb793df942dd56253351336189772de7d0a674169693213ff

data/README.md

@@ -1,4 +1,4 @@
-# Welcome to Vines
+# Vines XMPP Server
 
 Vines is an XMPP chat server that supports thousands of simultaneous connections,
 using EventMachine for asynchronous IO. User data is stored in a

data/lib/vines.rb

@@ -72,6 +72,7 @@ end
   resolv
   set
   socket
+  uri
   yaml
 
   vines/cli

data/lib/vines/cluster/subscriber.rb

@@ -2,7 +2,7 @@
 
 module Vines
   class Cluster
-    # Subscribes to the redis nodes:all broadcast channel to listen for
+    # Subscribes to the redis `nodes:all` broadcast channel to listen for
     # heartbeats from other cluster members. Also subscribes to a channel
     # exclusively for this particular node, listening for stanzas routed to us
     # from other nodes.
@@ -22,6 +22,8 @@ module Vines
       # Create a new redis connection and subscribe to the nodes:all broadcast
       # channel as well as the channel for this cluster node. Redis connections
       # in subscribe mode cannot be used for other key/value operations.
+      #
+      # Returns nothing.
       def subscribe
         conn = @cluster.connect
         conn.subscribe(ALL)
@@ -35,6 +37,8 @@ module Vines
 
       # Recursively process incoming messages from the queue, guaranteeing they
       # are processed in the order they are received.
+      #
+      # Returns nothing.
       def process_messages
         @messages.pop do |channel, message|
           Fiber.new do
@@ -46,6 +50,11 @@ module Vines
 
       # Process messages as they arrive on the pubsub channels to which we're
       # subscribed.
+      #
+      # channel - The String channel name on which the message was received.
+      # message - The JSON formatted message String.
+      #
+      # Returns nothing.
       def on_message(channel, message)
         doc = JSON.parse(message)
         case channel
@@ -56,9 +65,13 @@ module Vines
         log.error("Cluster subscription message failed: #{e}")
       end
 
-      # Process a message sent to the nodes:all broadcast channel. In the case
+      # Process a message sent to the `nodes:all` broadcast channel. In the case
       # of node heartbeats, we update the last time we heard from this node so
       # we can cleanup its session if it goes offline.
+      #
+      # message - The parsed Hash of received message data.
+      #
+      # Returns nothing.
       def to_all(message)
         case message[TYPE]
         when ONLINE, HEARTBEAT
@@ -71,6 +84,10 @@ module Vines
       # Process a message published to this node's channel. Messages sent to
       # this channel are stanzas that need to be routed to connections attached
       # to this node.
+      #
+      # message - The parsed Hash of received message data.
+      #
+      # Returns nothing.
       def to_node(message)
         case message[TYPE]
         when STANZA then route_stanza(message)
@@ -80,6 +97,10 @@ module Vines
 
       # Send the stanza, from a remote cluster node, to locally connected
       # streams for the destination user.
+      #
+      # message - The parsed Hash of received message data.
+      #
+      # Returns nothing.
       def route_stanza(message)
         node = Nokogiri::XML(message[STANZA]).root rescue nil
         return unless node
@@ -95,6 +116,10 @@ module Vines
 
       # Update the roster information, that's cached in locally connected
       # streams, for this user.
+      #
+      # message - The parsed Hash of received message data.
+      #
+      # Returns nothing.
       def update_user(message)
         jid = JID.new(message['jid']).bare
         if user = @cluster.storage(jid.domain).find_user(jid)

data/lib/vines/storage.rb

@@ -10,6 +10,10 @@ module Vines
 
     # Register a nickname that can be used in the config file to specify this
     # storage implementation.
+    #
+    # name - The String name for this storage backend.
+    #
+    # Returns nothing.
     def self.register(name)
       @@nicks[name.to_sym] = self
     end
@@ -25,15 +29,18 @@ module Vines
     # with blocking IO don't need to worry about threading or blocking the
     # EventMachine reactor thread if they wrap their methods with this one.
     #
-    # For example:
-    # def find_user(jid)
-    #   some_blocking_lookup(jid)
-    # end
-    # defer :find_user
+    # Examples
+    #
+    #   def find_user(jid)
+    #     some_blocking_lookup(jid)
+    #   end
+    #   defer :find_user
     #
     # Storage classes that use asynchronous IO (through an EventMachine
     # enabled library like em-http-request or em-redis) don't need any special
     # consideration and must not use this method.
+    #
+    # Returns nothing.
     def self.defer(method)
       old = instance_method(method)
       define_method method do |*args|
@@ -50,11 +57,14 @@ module Vines
     # authenticate method as usual. This allows storage classes to implement
     # their native authentication logic and not worry about handling LDAP.
     #
-    # For example:
-    # def authenticate(username, password)
-    #   some_user_lookup_by_password(username, password)
-    # end
-    # wrap_ldap :authenticate
+    # Examples
+    #
+    #   def authenticate(username, password)
+    #     some_user_lookup_by_password(username, password)
+    #   end
+    #   wrap_ldap :authenticate
+    #
+    # Returns nothing.
     def self.wrap_ldap(method)
       old = instance_method(method)
       define_method method do |*args|
@@ -64,21 +74,24 @@ module Vines
 
     # Wrap a method with Fiber yield and resume logic. The method must yield
     # its result to a block. This makes it easier to write asynchronous
-    # implementations of +authenticate+, +find_user+, and +save_user+ that
+    # implementations of `authenticate`, `find_user`, and `save_user` that
     # block and return a result rather than yielding.
     #
-    # For example:
-    # def find_user(jid)
-    #   http = EM::HttpRequest.new(url).get
-    #   http.callback { yield build_user_from_http_response(http) }
-    # end
-    # fiber :find_user
+    # Examples
     #
-    # Because +find_user+ has been wrapped in Fiber logic, we can call it
+    #   def find_user(jid)
+    #     http = EM::HttpRequest.new(url).get
+    #     http.callback { yield build_user_from_http_response(http) }
+    #   end
+    #   fiber :find_user
+    #
+    # Because `find_user` has been wrapped in Fiber logic, we can call it
     # synchronously even though it uses asynchronous EventMachine calls.
     #
-    # user = storage.find_user('alice@wonderland.lit')
-    # puts user.nil?
+    #   user = storage.find_user('alice@wonderland.lit')
+    #   puts user.nil?
+    #
+    # Returns nothing.
     def self.fiber(method)
       old = instance_method(method)
       define_method method do |*args|
@@ -90,21 +103,26 @@ module Vines
       end
     end
 
-    # Return +true+ if users are authenticated against an LDAP directory.
+    # Return true if users are authenticated against an LDAP directory.
     def ldap?
       !!ldap
     end
 
-    # Validate the username and password pair and return a +Vines::User+ object
-    # on success. Return +nil+ on failure.
+    # Validate the username and password pair.
+    #
+    # username - The String login JID to verify.
+    # password - The String password the user presented to the server.
     #
-    # For example:
-    # user = storage.authenticate('alice@wonderland.lit', 'secr3t')
-    # puts user.nil?
+    # Examples
+    #
+    #   user = storage.authenticate('alice@wonderland.lit', 'secr3t')
+    #   puts user.nil?
     #
     # This default implementation validates the password against a bcrypt hash
     # of the password stored in the database. Sub-classes not using bcrypt
     # passwords must override this method.
+    #
+    # Returns a Vines::User object on success, nil on failure.
     def authenticate(username, password)
       user = find_user(username)
       hash = BCrypt::Password.new(user.password) rescue nil
@@ -112,92 +130,141 @@ module Vines
     end
     wrap_ldap :authenticate
 
-    # Return the +Vines::User+ associated with the JID. Return +nil+ if the user
-    # could not be found. JID may be +nil+, a +String+, or a +Vines::JID+
-    # object. It may be a bare JID or a full JID. Implementations of this method
-    # must convert the JID to a bare JID before searching for the user in the
-    # database.
+    # Find the user in the storage database by their unique JID.
     #
-    # user = storage.find_user('alice@wonderland.lit')
-    # puts user.nil?
+    # jid - The String or JID of the user, possibly nil. This may be either a
+    #       bare JID or full JID. Implementations of this method must convert
+    #       the JID to a bare JID before searching for the user in the database.
+    #
+    # Examples
+    #
+    #   # Bare JID lookup.
+    #   user = storage.find_user('alice@wonderland.lit')
+    #   puts user.nil?
+    #
+    #   # Full JID lookup.
+    #   user = storage.find_user('alice@wonderland.lit/tea')
+    #   puts user.nil?
+    #
+    # Returns the User identified by the JID, nil if not found.
     def find_user(jid)
       raise 'subclass must implement'
     end
 
-    # Persist the +Vines::User+ object to the database and return when the save
-    # is complete.
+    # Persist the user to the database, and return when the save is complete.
+    #
+    # user - The User to persist.
     #
-    # alice = Vines::User.new(:jid => 'alice@wonderland.lit')
-    # storage.save_user(alice)
-    # puts 'saved'
+    # Examples
+    #
+    #   alice = Vines::User.new(jid: 'alice@wonderland.lit')
+    #   storage.save_user(alice)
+    #   puts 'saved'
+    #
+    # Returns nothing.
     def save_user(user)
       raise 'subclass must implement'
     end
 
-    # Return the Nokogiri::XML::Node for the vcard stored for this JID. Return
-    # nil if the vcard could not be found. JID may be +nil+, a +String+, or a
-    # +Vines::JID+ object. It may be a bare JID or a full JID. Implementations
-    # of this method must convert the JID to a bare JID before searching for the
-    # vcard in the database.
+    # Find the user's vcard by their unique JID.
+    #
+    # jid - The String or JID of the user, possibly nil. This may be either a
+    #       bare JID or full JID. Implementations of this method must convert
+    #       the JID to a bare JID before searching for the vcard in the database.
+    #
+    # Examples
+    #
+    #   card = storage.find_vcard('alice@wonderland.lit')
+    #   puts card.nil?
     #
-    # card = storage.find_vcard('alice@wonderland.lit')
-    # puts card.nil?
+    # Returns the vcard's Nokogiri::XML::Node, nil if not found.
     def find_vcard(jid)
       raise 'subclass must implement'
     end
 
-    # Save the vcard to the database and return when the save is complete. JID
-    # may be a +String+ or a +Vines::JID+ object.  It may be a bare JID or a
-    # full JID. Implementations of this method must convert the JID to a bare
-    # JID before saving the vcard. Card is a +Nokogiri::XML::Node+ object.
+    # Save the vcard to the database, and return when the save is complete.
     #
-    # card = Nokogiri::XML('<vCard>...</vCard>').root
-    # storage.save_vcard('alice@wonderland.lit', card)
-    # puts 'saved'
+    # jid  - The String or JID of the user, possibly nil. This may be either a
+    #        bare JID or full JID. Implementations of this method must convert
+    #        the JID to a bare JID before saving the vcard.
+    # card - The vcard's Nokogiri::XML::Node.
+    #
+    # Examples
+    #
+    #   card = Nokogiri::XML('<vCard>...</vCard>').root
+    #   storage.save_vcard('alice@wonderland.lit', card)
+    #   puts 'saved'
+    #
+    # Returns nothing.
     def save_vcard(jid, card)
       raise 'subclass must implement'
     end
 
-    # Return the Nokogiri::XML::Node for the XML fragment stored for this JID.
-    # Return nil if the fragment could not be found. JID may be +nil+, a
-    # +String+, or a +Vines::JID+ object. It may be a bare JID or a full JID.
-    # Implementations of this method must convert the JID to a bare JID before
-    # searching for the fragment in the database.
-    #
-    # Private XML storage uniquely identifies fragments by JID, root element name,
+    # Find the private XML fragment previously stored by the user. Private
+    # XML storage uniquely identifies fragments by JID, root element name,
     # and root element namespace.
     #
-    # root = Nokogiri::XML('<custom xmlns="urn:custom:ns"/>').root
-    # fragment = storage.find_fragment('alice@wonderland.lit', root)
-    # puts fragment.nil?
+    # jid  - The String or JID of the user, possibly nil. This may be either a
+    #        bare JID or full JID. Implementations of this method must convert
+    #        the JID to a bare JID before searching for the fragment in the database.
+    # node - The XML::Node that uniquely identifies the fragment by element
+    #        name and namespace.
+    #
+    # Examples
+    #
+    #   root = Nokogiri::XML('<custom xmlns="urn:custom:ns"/>').root
+    #   fragment = storage.find_fragment('alice@wonderland.lit', root)
+    #   puts fragment.nil?
+    #
+    # Returns the fragment's Nokogiri::XML::Node or nil if not found.
     def find_fragment(jid, node)
       raise 'subclass must implement'
     end
 
-    # Save the XML fragment to the database and return when the save is complete.
-    # JID may be a +String+ or a +Vines::JID+ object.  It may be a bare JID or a
-    # full JID. Implementations of this method must convert the JID to a bare
-    # JID before saving the fragment. Fragment is a +Nokogiri::XML::Node+ object.
+    # Save the XML fragment to the database, and return when the save is complete.
+    #
+    # jid      - The String or JID of the user, possibly nil. This may be
+    #            either a bare JID or full JID. Implementations of this method
+    #            must convert the JID to a bare JID before searching for the
+    #            fragment.
+    # fragment - The XML::Node to save.
+    #
+    # Examples
     #
-    # fragment = Nokogiri::XML('<custom xmlns="urn:custom:ns">some data</custom>').root
-    # storage.save_fragment('alice@wonderland.lit', fragment)
-    # puts 'saved'
+    #   fragment = Nokogiri::XML('<custom xmlns="urn:custom:ns">some data</custom>').root
+    #   storage.save_fragment('alice@wonderland.lit', fragment)
+    #   puts 'saved'
+    #
+    # Returns nothing.
     def save_fragment(jid, fragment)
       raise 'subclass must implement'
     end
 
     private
 
-    # Return true if any of the arguments are nil or empty strings.
-    # For example:
-    # username, password = 'alice@wonderland.lit', ''
-    # empty?(username, password) #=> true
+    # Determine if any of the arguments are nil or empty strings.
+    #
+    # Examples
+    #
+    #   username, password = 'alice@wonderland.lit', ''
+    #   empty?(username, password) #=> true
+    #
+    # Returns true if any of the arguments are nil or empty strings.
     def empty?(*args)
       args.flatten.any? {|arg| (arg || '').strip.empty? }
     end
 
-    # Return a +proc+ suitable for running on the +EM.defer+ thread pool that traps
-    # and logs any errors thrown by the provided block.
+    # Create a proc suitable for running on the EM.defer thread pool, that
+    # traps and logs any errors thrown by the provided block.
+    #
+    # block - The block to wrap in error handling.
+    #
+    # Examples
+    #
+    #   op = operation { do_something_on_thread_pool() }
+    #   EM.defer(op)
+    #
+    # Returns a Proc.
     def operation
       proc do
         begin
@@ -209,10 +276,15 @@ module Vines
       end
     end
 
-    # Return a +Vines::User+ object if we are able to bind to the LDAP server
-    # using the username and password. Return +nil+ if authentication failed. If
+    # Bind to the LDAP server using the provided username and password. If
     # authentication succeeds, but the user is not yet stored in our database,
     # save the user to the database.
+    #
+    # username - The String JID to authenticate.
+    # password - The String password the user provided.
+    # block    - The block that receives the authenticated User or nil.
+    #
+    # Returns the authenticated User or nil if authentication failed.
     def authenticate_with_ldap(username, password, &block)
       op = operation { ldap.authenticate(username, password) }
       cb = proc {|user| save_ldap_user(user, &block) }
@@ -220,9 +292,14 @@ module Vines
     end
     fiber :authenticate_with_ldap
 
-    # Save missing users to the storage database after they're authenticated with
-    # LDAP. This allows admins to define users once in LDAP and have them sync
-    # to the chat database the first time they successfully sign in.
+    # Save missing users to the storage database after they're authenticated
+    # with LDAP. This allows admins to define users once in LDAP and have them
+    # sync to the chat database the first time they successfully sign in.
+    #
+    # user  - The User to persist, possibly nil.
+    # block - The block that receives the saved User, possibly nil.
+    #
+    # Returns nothing.
     def save_ldap_user(user, &block)
       Fiber.new do
         if user.nil?