vines 0.4.9 → 0.4.10

data/lib/vines/store.rb

@@ -1,7 +1,6 @@
 # encoding: UTF-8
 
 module Vines
-
   # An X509 certificate store that validates certificate trust chains.
   # This uses the conf/certs/*.crt files as the list of trusted root
   # CA certificates.
@@ -10,19 +9,25 @@ module Vines
 
     # Create a certificate store to read certificate files from the given
     # directory.
+    #
+    # dir - The String directory name (absolute or relative).
     def initialize(dir)
       @dir = File.expand_path(dir)
       @store = OpenSSL::X509::Store.new
-      certs.each {|c| @store.add_cert(c) }
+      certs.each {|cert| append(cert) }
     end
 
     # Return true if the certificate is signed by a CA certificate in the
     # store. If the certificate can be trusted, it's added to the store so
     # it can be used to trust other certs.
+    #
+    # pem - The PEM encoded certificate String.
+    #
+    # Returns true if the certificate is trusted.
     def trusted?(pem)
       if cert = OpenSSL::X509::Certificate.new(pem) rescue nil
         @store.verify(cert).tap do |trusted|
-          @store.add_cert(cert) if trusted rescue nil
+          append(cert) if trusted
         end
       end
     end
@@ -30,6 +35,11 @@ module Vines
     # Return true if the domain name matches one of the names in the
     # certificate. In other words, is the certificate provided to us really
     # for the domain to which we think we're connected?
+    #
+    # pem    - The PEM encoded certificate String.
+    # domain - The domain name String.
+    #
+    # Returns true if the certificate was issued for the domain.
     def domain?(pem, domain)
       if cert = OpenSSL::X509::Certificate.new(pem) rescue nil
         OpenSSL::SSL.verify_certificate_identity(cert, domain) rescue false
@@ -39,8 +49,10 @@ module Vines
     # Return the trusted root CA certificates installed in conf/certs. These
     # certificates are used to start the trust chain needed to validate certs
     # we receive from clients and servers.
+    #
+    # Returns an Array of OpenSSL::X509::Certificate objects.
     def certs
-      unless @@sources
+      @@sources ||= begin
         pattern = /-{5}BEGIN CERTIFICATE-{5}\n.*?-{5}END CERTIFICATE-{5}\n/m
         pairs = Dir[File.join(@dir, '*.crt')].map do |name|
           File.open(name, "r:UTF-8") do |f|
@@ -50,7 +62,7 @@ module Vines
             [name, certs]
           end
         end
-        @@sources = Hash[pairs]
+        Hash[pairs]
       end
       @@sources.values.flatten
     end
@@ -60,26 +72,43 @@ module Vines
     # wildcard certificate files to serve several subdomains.
     #
     # Finding the certificate and private key file for a domain follows these steps:
-    # - look for <domain>.crt and <domain>.key files in the conf/certs directory.
-    #   if found, return those file names, else
-    # - inspect all conf/certs/*.crt files for certificates that contain the
+    #
+    # - Look for <domain>.crt and <domain>.key files in the conf/certs
+    #   directory. If found, return those file names, otherwise . . .
+    #
+    # - Inspect all conf/certs/*.crt files for certificates that contain the
     #   domain name either as the subject common name (CN) or as a DNS
     #   subjectAltName. The corresponding private key must be in a file of the
     #   same name as the certificate's, but with a .key extension.
     #
-    # So in the simplest configuration, the tea.wonderland.lit encryption files would
-    # be named conf/certs/tea.wonderland.lit.crt and conf/certs/tea.wonderland.lit.key.
+    # So in the simplest configuration, the tea.wonderland.lit encryption files
+    # would be named:
+    #
+    # - conf/certs/tea.wonderland.lit.crt
+    # - conf/certs/tea.wonderland.lit.key
     #
-    # However, in the case of a wildcard certificate for *.wonderland.lit, the
-    # files would be conf/certs/wonderland.lit.crt and conf/certs/wonderland.lit.key.
-    # These same two files would be returned for the subdomains of tea.wonderland.lit,
-    # crumpets.wonderland.lit, etc.
+    # However, in the case of a wildcard certificate for *.wonderland.lit,
+    # the files would be:
+    #
+    # - conf/certs/wonderland.lit.crt
+    # - conf/certs/wonderland.lit.key
+    #
+    # These same two files would be returned for the subdomains of:
+    #
+    # - tea.wonderland.lit
+    # - crumpets.wonderland.lit
+    # - etc.
+    #
+    # domain - The String domain name.
+    #
+    # Returns a two element String array for the certificate and private key
+    #   file names or nil if not found.
     def files_for_domain(domain)
       crt = File.expand_path("#{domain}.crt", @dir)
       key = File.expand_path("#{domain}.key", @dir)
       return [crt, key] if File.exists?(crt) && File.exists?(key)
 
-      # might be a wildcard cert file
+      # Might be a wildcard cert file.
       @@sources.each do |file, certs|
         certs.each do |cert|
           if OpenSSL::SSL.verify_certificate_identity(cert, domain)
@@ -90,5 +119,19 @@ module Vines
       end
       nil
     end
+
+    private
+
+    # Add a trusted certificate to the store, suppressing any OpenSSL errors
+    # caused by the certificate already being stored.
+    #
+    # cert - The OpenSSL::X509::Certificate to add.
+    #
+    # Returns nothing.
+    def append(cert)
+      @store.add_cert(cert)
+    rescue OpenSSL::X509::StoreError
+      # Already added to store.
+    end
   end
 end

data/lib/vines/stream.rb

@@ -17,6 +17,11 @@ module Vines
       @config = config
     end
 
+    # Initialize the stream after its connection to the server has completed.
+    # EventMachine calls this method when an incoming connection is accepted
+    # into the event loop.
+    #
+    # Returns nothing.
     def post_init
       @remote_addr, @local_addr = addresses
       @user, @closed, @stanza_size = nil, false, 0
@@ -33,23 +38,34 @@ module Vines
     # stream is first connected as well as for stream restarts during
     # negotiation. Subclasses can override this method to provide a different
     # type of parser (e.g. HTTP).
+    #
+    # Returns nothing.
     def create_parser
-      @parser = Parser.new.tap do |p|
-        p.stream_open {|node| @nodes.push(node) }
-        p.stream_close { close_connection }
-        p.stanza {|node| @nodes.push(node) }
+      @parser = Parser.new.tap do |parser|
+        parser.stream_open {|node| @nodes.push(node) }
+        parser.stream_close { close_connection }
+        parser.stanza {|node| @nodes.push(node) }
       end
     end
 
-    # Advance the state machine into the +Closed+ state so any remaining queued
+    # Advance the state machine into the `Closed` state so any remaining queued
     # nodes are not processed while we're waiting for EM to actually close the
     # connection.
+    #
+    # Returns nothing.
     def close_connection(after_writing=false)
       super
       @closed = true
       advance(Client::Closed.new(self))
     end
 
+    # Read bytes off the stream and feed them into the XML parser. EventMachine
+    # is responsible for calling this method on its event loop as connections
+    # become readable.
+    #
+    # data - The byte String sent to the server from the client, hopefully XML.
+    #
+    # Returns nothing.
     def receive_data(data)
       return if @closed
       @stanza_size += data.bytesize
@@ -62,6 +78,8 @@ module Vines
 
     # Reset the connection's XML parser when a new <stream:stream> header
     # is received.
+    #
+    # Returns nothing.
     def reset
       create_parser
     end
@@ -72,7 +90,7 @@ module Vines
       @config.storage(domain || self.domain)
     end
 
-    # Returns the Vines::Config::Host virtual host for the stream's domain.
+    # Returns the Config::Host virtual host for the stream's domain.
     def vhost
       @config.vhost(domain)
     end
@@ -80,6 +98,10 @@ module Vines
     # Reload the user's information into their active connections. Call this
     # after storage.save_user() to sync the new user state with their other
     # connections.
+    #
+    # user - The User whose connection info needs refreshing.
+    #
+    # Returns nothing.
     def update_user_streams(user)
       connected_resources(user.jid.bare).each do |stream|
         stream.user.update_from(user)
@@ -112,6 +134,10 @@ module Vines
     end
 
     # Send the data over the wire to this client.
+    #
+    # data - The XML String or XML::Node to write to the socket.
+    #
+    # Returns nothing.
     def write(data)
       log_node(data, :out)
       if data.respond_to?(:to_xml)
@@ -139,7 +165,11 @@ module Vines
     end
 
     # Advance the stream's state machine to the new state. XML nodes received
-    # by the stream will be passed to this state's +node+ method.
+    # by the stream will be passed to this state's `node` method.
+    #
+    # state - The Stream::State to process the stanzas next.
+    #
+    # Returns the new Stream::State.
     def advance(state)
       @state = state
     end
@@ -147,6 +177,10 @@ module Vines
     # Stream level errors close the stream while stanza and SASL errors are
     # written to the client and leave the stream open. All exceptions should
     # pass through this method for consistent handling.
+    #
+    # e - The StandardError, usually XmppError, that occurred.
+    #
+    # Returns nothing.
     def error(e)
       case e
       when SaslError, StanzaError
@@ -167,7 +201,9 @@ module Vines
 
     private
 
-    # Return the remote and local socket addresses used by this connection.
+    # Determine the remote and local socket addresses used by this connection.
+    #
+    # Returns a two-element Array of String addresses.
     def addresses
       [get_peername, get_sockname].map do |addr|
         addr ? Socket.unpack_sockaddr_in(addr)[0, 2].reverse.join(':') : 'unknown'
@@ -176,12 +212,21 @@ module Vines
 
     # Write the StreamError's xml to the stream. Subclasses can override
     # this method with custom error writing behavior.
+    #
+    # A call to `close_stream` should follow this method. Stream level errors
+    # are fatal to the connection.
+    #
+    # e - The StreamError that caused the connection to close.
+    #
+    # Returns nothing.
     def send_stream_error(e)
       write(e.to_xml)
     end
 
-    # Write a closing stream tag to the stream then close the stream. Subclasses
-    # can override this method for custom close behavior.
+    # Write a closing stream tag and close the connection. Subclasses can
+    # override this method for custom close behavior.
+    #
+    # Returns nothing.
     def close_stream
       write('</stream:stream>')
       close_connection_after_writing
@@ -194,7 +239,14 @@ module Vines
 
     # Schedule a queue pop on the EM thread to handle the next element. This
     # guarantees all stanzas received on this stream are processed in order.
-    # http://tools.ietf.org/html/rfc6120#section-10.1
+    #
+    #   http://tools.ietf.org/html/rfc6120#section-10.1
+    #
+    # Once a node is processed, this method recursively schedules itself to pop
+    # the next node and so on. A single call to this method effectively begins
+    # an asynchronous node processing loop.
+    #
+    # Returns nothing.
     def process_node_queue
       @nodes.pop do |node|
         Fiber.new do
@@ -232,14 +284,20 @@ module Vines
         ["#{label} stanza:".ljust(PAD), from, to, node])
     end
 
-    # Returns the current +State+ of the stream's state machine. Provided as a
+    # Inspects the current state of the stream's state machine. Provided as a
     # method so subclasses can override the behavior.
+    #
+    # Returns the current Stream::State.
     def state
       @state
     end
 
-    # Return +true+ if this is a valid domain-only JID that can be used in
+    # Determine if this is a valid domain-only JID that can be used in
     # stream initiation stanza headers.
+    #
+    # jid - The String or JID to verify (e.g. 'wonderland.lit').
+    #
+    # Return true if the jid is domain-only.
     def valid_address?(jid)
       JID.new(jid).domain? rescue false
     end

data/lib/vines/stream/client.rb

@@ -60,21 +60,25 @@ module Vines
 
       private
 
-      # The +to+ domain address set on the initial stream header must not change
+      # The `to` domain address set on the initial stream header must not change
       # during stream restarts. This prevents a user from authenticating in one
       # domain, then using a stream in a different domain.
+      #
+      # to - The String domain JID to verify (e.g. 'wonderland.lit').
+      #
+      # Returns true if the client connection is misbehaving and should be closed.
       def domain_change?(to)
         to != @session.domain
       end
 
       def send_stream_header(to)
         attrs = {
-          'xmlns' => NAMESPACES[:client],
+          'xmlns'        => NAMESPACES[:client],
           'xmlns:stream' => NAMESPACES[:stream],
-          'xml:lang' => 'en',
-          'id' => Kit.uuid,
-          'from' => @session.domain,
-          'version' => '1.0'
+          'xml:lang'     => 'en',
+          'id'           => Kit.uuid,
+          'from'         => @session.domain,
+          'version'      => '1.0'
         }
         attrs['to'] = to if to
         write "<stream:stream %s>" % attrs.to_a.map{|k,v| "#{k}='#{v}'"}.join(' ')

data/lib/vines/stream/component.rb

@@ -46,10 +46,10 @@ module Vines
 
       def send_stream_header
         attrs = {
-          'xmlns' => NAMESPACES[:component],
+          'xmlns'        => NAMESPACES[:component],
           'xmlns:stream' => NAMESPACES[:stream],
-          'id' => @stream_id,
-          'from' => @remote_domain
+          'id'           => @stream_id,
+          'from'         => @remote_domain
         }
         write "<stream:stream %s>" % attrs.to_a.map{|k,v| "#{k}='#{v}'"}.join(' ')
       end

data/lib/vines/stream/http.rb

@@ -10,22 +10,28 @@ module Vines
         @session = Http::Session.new(self)
       end
 
-      # Override +Stream#create_parser+ to provide an HTTP parser rather than
+      # Override Stream#create_parser to provide an HTTP parser rather than
       # a Nokogiri XML parser.
+      #
+      # Returns nothing.
       def create_parser
-        @parser = ::Http::Parser.new.tap do |p|
+        @parser = ::Http::Parser.new.tap do |parser|
           body = ''
-          p.on_body = proc {|data| body << data }
-          p.on_message_complete = proc {
+          parser.on_body = proc {|data| body << data }
+          parser.on_message_complete = proc do
             process_request(Request.new(self, @parser, body))
             body = ''
-          }
+          end
         end
       end
 
       # If the session ID is valid, switch this stream's session to the new
       # ID and return true. Some clients, like Google Chrome, reuse one stream
       # for multiple sessions.
+      #
+      # sid - The String session ID.
+      #
+      # Returns true if the server previously distributed this SID to a client.
       def valid_session?(sid)
         if session = Sessions[sid]
           @session = session
@@ -62,13 +68,27 @@ module Vines
 
       # Override Stream#write to queue stanzas rather than immediately writing
       # to the stream. Stanza responses must be paired with a queued request.
+      #
+      # If a request is not waiting, the written stanzas will buffer until they
+      # can be sent in the next response.
+      #
+      # data - The XML String or XML::Node to write to the HTTP socket.
+      #
+      # Returns nothing.
       def write(data)
         @session.write(data)
       end
 
-      # Return an array of Node objects inside the body element.
+      # Parse the one or more stanzas from a single body element. BOSH clients
+      # buffer stanzas sent in quick succession, and send them as a bundle, to
+      # save on the request/response cycle.
+      #
       # TODO This parses the XML again just to strip namespaces. Figure out
       # Nokogiri namespace handling instead.
+      #
+      # body - The XML::Node containing the BOSH `body` element.
+      #
+      # Returns an Array of XML::Node stanzas.
       def parse_body(body)
         body.namespace = nil
         body.elements.map do |node|
@@ -133,8 +153,12 @@ module Vines
         @session.reply(node)
       end
 
-      # Override +Stream#send_stream_error+ to wrap the error XML in a BOSH
+      # Override Stream#send_stream_error to wrap the error XML in a BOSH
       # terminate body tag.
+      #
+      # e - The StreamError that caused the connection to close.
+      #
+      # Returns nothing.
       def send_stream_error(e)
         doc = Nokogiri::XML::Document.new
         node = doc.create_element('body',
@@ -146,12 +170,14 @@ module Vines
         @session.reply(node)
       end
 
-      # Override +Stream#close_stream+ to simply close the connection without
+      # Override Stream#close_stream to simply close the connection without
       # writing a closing stream tag.
+      #
+      # Returns nothing.
       def close_stream
         close_connection_after_writing
         @session.close
       end
     end
   end
-end
+end