net-dnd 1.1.2

data/lib/net/dnd/session.rb

@@ -0,0 +1,114 @@
+folder_path = File.dirname(__FILE__)
+require "#{folder_path}/connection"
+require "#{folder_path}/profile"
+require "#{folder_path}/field"
+require "#{folder_path}/errors"
+
+module Net
+  module DND
+
+    # This is the DND session object. It provides the high-level interface for performing
+    # lookup-style searches against a given DND host. It manages the Connection object,
+    # which is the low-level socket stuff, and sends back DND Profile objects, either singly or
+    # an array, as the result of the find method.
+
+    class Session
+
+      attr_reader :fields, :connection
+
+      # Constructor method. Only called directly by unit tests (specs). The start method
+      # handles the setting up of a full DND session.
+
+      def initialize(host)
+        @connection = Connection.new(host)
+        raise ConnectionError, connection.error unless connection.open?
+      end
+
+      # Starts a new DND session/connection. Called by the module-level start methods.
+
+      def self.start(host, field_list=[])
+        session = Session.new(host)
+        session.set_fields(field_list)
+        session
+      end
+
+      # Are we still open?
+
+      def open?
+        connection.open?
+      end
+
+      # Set the list of fields used by subsequent find commands. These fields are then passed
+      # to the Profile.new method when one or more users are returned by the find command. This
+      # method will raise a couple of error messages, that you might want to trap for:
+      #
+      # FieldNotFound is raised when a specified field is not found in the list of fields known
+      #   by the currently connected to DND server.
+      #
+      # FieldAccessDenied is raised when a speficied field is one whose value is not world
+      #   readable, meaning you need to be in an authenticated session to access it.
+      #
+      # You can manually send the set_fields command, if you happen to need to change the list of
+      # fields returned by your find commands, after you've instantiated the session object.
+
+      def set_fields(field_list=[])
+        response = request(:fields, field_list)
+        @fields = []
+        raise FieldNotFound, response.error unless response.ok?
+        response.items.each do |item|
+          field = Field.from_field_line(item)
+          if field.read_all? # only world readable fields are valid for DND Profiles
+            @fields << field.to_sym
+          else
+            raise FieldAccessDenied, "#{field.to_s} is not world readable." unless field_list.empty?
+          end
+        end
+      end
+
+      # The find command is the real reason for the Net::DND libray. It provides the ability to
+      # send a 'user specifier' to a connected DND server and then parse the returned data into
+      # one or more Net::DND::Profile objects.
+      #
+      # You can send the find command in two flavors: the first, when you simply submit the look_for
+      # argument will assume that you're expecting more than one user to match the look_for string.
+      # Thus it will always return a array as its result. This array will contain zero, one or more
+      # Profile objects.
+      #
+      # In it's second flavor, you are submitting a value for the 'one' argument. Normally, this
+      # means you've sent a :one as the second argument to the call, but any non-false value will
+      # work. When called in this manner, you're telling the Session that you only want a Profile
+      # object if your 'look_for' returns a single match, otherwise the find will return nil. This
+      # flavor is recommended when you are performing a find using a 'uid' or a 'dctsnum' value.
+
+      def find(look_for, one=nil)
+        response = request(:lookup, look_for.to_s, fields)
+        if one
+          return nil unless response.items.length == 1
+          Profile.new(fields, response.items[0])
+        else
+          response.items.map { |item| Profile.new(fields, item) }
+        end
+      end
+
+      # The manual session close command. You only call this method if you aren't using the block
+      # version of the module 'start' command. If you use the block, it will automatically close
+      # the session when the block exits.
+
+      def close
+        request(:quit, nil)
+      end
+
+      private
+
+      # This method handles the sending of the raw protocol commands to the Connection object. It
+      # will only send commands if the Session is still 'open'. It always returns the Response object
+      # back from the result of calling into the Connection.
+
+      def request(type, *args)
+        raise ConnectionClosed, "Connection closed." unless open?
+        response = connection.send(type, *args)
+      end
+
+    end
+  end
+end

data/lib/net/dnd/user_spec.rb

@@ -0,0 +1,56 @@
+module Net
+  module DND
+
+    # This is a container class for the User Specifier portion of the DND protocol lookup command.
+    # Something like this isn't expressly needed, but because there are 3 types of specifier,
+    # based around 4 different patterns of specifier, which leads to three slightly different
+    # types of output, it seemed like a class was the best way to abstract those determinations.
+
+    # Once a string specifier is passed into the constructer method, it's stored and then
+    # matched against one of several patterns to determine it's type. This type is then used
+    # to choose the output format of the specifier, when the instantiated class object is
+    # coerced back to a string.
+
+    class UserSpec
+
+      attr_reader :type
+
+      # Construct our specifier object and set its type attribute.
+
+      def initialize(specifier)
+        @spec = specifier.to_s
+        @type = case @spec.downcase
+          when /^\d+$/
+            :uid
+          when /^z\d+$/
+            :did
+          when /^\d+[a-z]\d*$/
+            :did
+          else
+            :name
+          end
+      end
+
+      # Output the correct 'string' format for our specifier. The :uid and :did types have
+      # special characters prepended to their value, so that they are correctly formatted
+      # for use in a DND connection/protocol lookup command.
+
+      def to_s
+        case @type
+        when :uid
+          "##{@spec}"
+        when :did
+          "#*#{@spec}"
+        else
+          @spec
+        end
+      end
+
+      # Inspection string for the specifier object.
+
+      def inspect
+        "#<#{self.class} specifier=\"#{@spec}\" type=:#{@type}>"
+      end
+    end
+  end
+end

data/lib/net/dnd/version.rb

@@ -0,0 +1,11 @@
+module Net
+  module DND
+
+      MAJOR = 1
+      MINOR = 1
+      PATCH  = 2
+
+      VERSION  = [MAJOR, MINOR, PATCH].join(".")
+
+  end
+end

data/net-dnd.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "net/dnd/version"
+
+Gem::Specification.new do |s|
+  s.name        = "net-dnd"
+  s.version     = Net::DND::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Brian V. Hughes"]
+  s.email       = ["brianvh@dartmouth.edu"]
+  s.homepage    = %(https://github.com/brianvh/net-dnd/)
+  s.summary     = %(#{s.name}-#{s.version})
+  s.description = %(Ruby library for DND lookups.)
+
+  s.required_rubygems_version = ">= 1.3.7"
+  s.rubyforge_project = "net-dnd"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'bundler', '~> 1.0.10'
+  s.add_development_dependency 'rspec', '~> 2.5.0'
+end

data/spec/dnd/connection_spec.rb

@@ -0,0 +1,94 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'net/dnd/connection'
+
+module Net ; module DND
+
+  describe "a good socket", :shared => true do
+    before(:each) do
+      @socket = flexmock("TCP Socket")
+      @tcp = flexmock(TCPSocket)
+      @response = flexmock(Response)
+    end
+  end
+
+  describe Connection, "to a bad host" do
+
+    it_should_behave_like "a good socket"
+
+    before(:each) do
+      @tcp.should_receive(:open).and_raise(Errno::ECONNREFUSED, "Connection refused")
+      @connection = Connection.new('my.fakehost.com')
+    end
+
+    it "should not indicate an open connection" do
+      @connection.should_not be_open
+    end
+
+    it "should return the 'Could not connect' error message" do
+      @connection.error.should match(/^Could not connect to/)
+    end
+  end
+
+  describe Connection, "to a busy/slow host" do
+
+    it_should_behave_like "a good socket"
+
+    before(:each) do
+      flexmock(Timeout).should_receive(:timeout).and_raise(Timeout::Error, "Connection timed out")
+      @connection = Connection.new('my.slowhost.com')
+    end
+
+    it "should not indicate an open connection" do
+      @connection.should_not be_open
+    end
+
+    it "should return the 'Connection timed out' error message" do
+      @connection.error.should match(/^Connection attempt .* has timed out/)
+    end
+  end
+
+  describe Connection, "to a good host" do
+
+    it_should_behave_like "a good socket"
+
+    before(:each) do
+      @tcp.should_receive(:open).once.and_return(@socket)
+      @response.should_receive(:process).at_least.once.and_return(@response)
+      @response.should_receive(:ok?).at_least.once.and_return(true)
+      @connection = Connection.new('my.goodhost.com')
+    end
+
+    it "should indicate an open connection" do
+      @connection.should be_open
+    end
+
+    it "should not have any error messages" do
+      @connection.error.should be_nil
+    end
+
+    describe "sending commands" do
+
+      it "should send the correct command when fields is called with empty field list" do
+        @socket.should_receive(:puts).once.with('fields')
+        @connection.fields
+      end
+
+      it "should send the correct command when fields is called with a field list" do
+        @socket.should_receive(:puts).once.with('fields name nickname')
+        @connection.fields(['name', 'nickname'])
+      end
+
+      it "should send the correct command when lookup is called" do
+        @socket.should_receive(:puts).once.with('lookup joe user,name nickname')
+        @connection.lookup('joe user', ['name', 'nickname'])
+      end
+
+      it "should send the correct command when quit is called" do
+        @socket.should_receive(:puts).once.with('quit')
+        @socket.should_receive(:close)
+        @connection.quit
+      end
+    end
+  end
+
+end ; end

data/spec/dnd/field_spec.rb

@@ -0,0 +1,72 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'net/dnd/field'
+
+module Net ; module DND
+  
+  describe Field, "created normally" do
+    before :each do
+      @name, @write, @read = %w(nickname U A)
+      @field = Field.new(@name, @write, @read)
+    end
+    
+    it "should properly set the writeable flag" do
+      @field.writeable.should == @write
+    end
+    
+    it "should properly set the readable flag" do
+      @field.readable.should == @read
+    end
+    
+    it "should report as readable by all if readable value is 'A'" do
+      @field.should be_read_all
+    end
+    
+    it "should report back the proper name" do
+      @field.name.should == @name
+    end
+    
+    it "should report back the proper inspection string" do
+      @field.inspect.should match(/<Net::DND::Field name=".*" writeable="[AUNT]" readable="[AUNT]">/)
+    end
+    
+    it "should return the name when coerced to a string" do
+      @field.to_s.should == @name
+    end
+    
+    it "should return :name when coerced to a symbol" do
+      @field.to_sym.should == @name.to_sym
+    end
+    
+    it "should not report as readable by all if readable value is not 'A'" do
+      @read = "T"
+      @field = Field.new(@name, @write, @read)
+      @field.should_not be_read_all
+    end
+    
+  end
+  
+  describe Field, "created using from_field_line with a proper line format" do
+
+    before(:each) do
+      @values = %w(nickname U A)
+      line = @values.join(" ")
+      @field = Field.from_field_line(line)
+    end
+
+    it "should have the correct name" do
+      @field.name.should == @values[0]
+    end
+
+    it "should have to correct readable value" do
+      @field.readable.should == @values[2]
+    end
+  end
+  
+  describe Field, "created using from_field_line with an improper line format" do
+    it "should raise the proper error" do
+      line = "This is a bad field line"
+      lambda { Field.from_field_line(line) }.should raise_error(FieldLineInvalid)
+    end
+  end
+  
+end ; end

data/spec/dnd/profile_spec.rb

@@ -0,0 +1,66 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'net/dnd/profile'
+
+module Net ; module DND
+
+  describe Profile, "for Joe D. User" do
+
+    before(:each) do
+      @fields = [:name, :nickname, :deptclass, :email]
+      @items = ['Joe D. User', 'joey jdu', 'Student', 'Joe.D.User@Dartmouth.edu']
+      @profile = Profile.new(@fields, @items)
+    end
+
+    it "should return the correct object" do
+      @profile.should be_instance_of(Profile)
+    end
+
+    it "should return the correct inspection string" do
+      @profile.inspect.should match(/<Net::DND::Profile length=4, .*deptclass="Student".*>/)
+    end
+
+    it "should have the correct number of entries" do
+      @profile.length.should == 4
+    end
+
+    it "should return the correct name" do
+      @profile.name.should == @items[0]
+    end
+
+    it "should return the correct email" do
+      @profile[:email].should == @items[3]
+    end
+
+    it "should contain nickname field" do
+      @profile.should be_nickname
+    end
+
+    it "should not contain did field" do
+      @profile.should_not be_did
+    end
+
+    it "should raise Field Not Found error if did field is requested" do
+      lambda { @profile.did }.should raise_error(FieldNotFound)
+    end
+
+  end
+
+  describe Profile, "for Joe D. Expired" do
+
+    before(:each) do
+      @fields = [:name, :expires]
+      @items = ['Joe D. User', '01-Jan-2010']
+      @profile = Profile.new(@fields, @items)
+    end
+
+    it "should have a valid expire_date" do
+      @profile.expires_on.should_not be_nil
+    end
+
+    it "should be expired" do
+      @profile.should be_expired
+    end
+
+  end
+
+end ; end

data/spec/dnd/response_spec.rb

@@ -0,0 +1,161 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'net/dnd/response'
+
+module Net ; module DND
+
+  describe Response, "on initial create" do
+    before(:each) do
+      @socket = flexmock("TCP Socket")
+      @response = Response.new(@socket)
+    end
+
+    it "should have no :code value" do
+      @response.code.should be_nil
+    end
+
+    it "should have no :error value" do
+      @response.error.should be_nil
+    end
+
+    it "should have an empty :items value" do
+      @response.items.should be_empty
+    end
+  end
+
+  describe Response, "after create status to a good socket" do
+    before(:each) do
+      @socket = flexmock("TCP Socket")
+      @response = Response.new(@socket)
+      @socket.should_receive(:gets).once.and_return('220 DND server ready.')
+      @response.status_line
+    end
+
+    it "should have a :code of 220" do
+      @response.code.should == 220
+    end
+
+    it do
+      @response.should be_ok
+    end
+  end
+
+  describe Response, "parsing a bad command" do
+
+    before(:each) do
+      @code = 501
+      @msg = "unknown field name foo"
+      @socket = flexmock("DND Socket after bad :fields command")
+      @socket.should_receive(:gets).once.and_return("#{@code} #{@msg}\r\n")
+      @response = Response.process(@socket)
+    end
+
+    it "should return a code of 501" do
+      @response.code == @code
+    end
+
+    it "should have the appropriate error message" do
+      @response.error == @msg
+    end
+
+    it do
+      @response.should_not be_ok
+    end
+  end
+
+  describe Response, "parsing a :quit command" do
+
+    before(:each) do
+      @code = 200
+      @msg = "Ok"
+      @socket = flexmock("DND Socket after :quit command")
+      @socket.should_receive(:gets).once.and_return("#{@code} #{@msg}\r\n")
+      @response = Response.process(@socket)
+    end
+
+    it "should return a code of 200" do
+      @response.code == @code
+    end
+
+    it do
+      @response.should be_ok
+    end
+  end
+
+  describe Response, "parsing a :fields command" do
+
+    before(:each) do
+      @code = [102, 200]
+      @count = 2
+      @data = ['120 name N A', '120 nickname U A']
+      @status = 'Done'
+      @socket = flexmock("DND Socket after :fields command")
+      @socket.should_receive(:gets).times(4).and_return(
+          "#{@code[0]} #{@count}\r\n", "#{@data[0]}\r\n",
+          "#{@data[1]}\r\n", "#{@code[1]} #{@status}\r\n")
+      @response = Response.process(@socket)
+    end
+
+    it "should have a sub_count of 0" do
+      @response.sub_count == 0
+    end
+
+    it "should have the correct number of items" do
+      @response.should have(2).items
+    end
+
+    it "should have 'nickname' as the second item" do
+      @response.items[1].split[0] == 'nickname'
+    end
+
+    it "should have a code of 200" do
+      @response.code.should == @code[1]
+    end
+
+    it do
+      @response.should be_ok
+    end
+  end
+
+  describe Response, "parsing a :lookup command" do
+
+    before(:each) do
+      @code = [102, 201]
+      @count = 2
+      @sub_count = 2
+      @data = ['110 Joe Q. User', '110 joey, jqu', '110 Jane P. User', '110 janes, jp']
+      @status = 'Additional matches not returned'
+      @socket = flexmock("DND Socket after :lookup command")
+      @socket.should_receive(:gets).times(6).and_return(
+          "#{@code[0]} #{@count} #{@sub_count}\r\n",
+          "#{@data[0]}\r\n", "#{@data[1]}\r\n",
+          "#{@data[2]}\r\n", "#{@data[3]}\r\n",
+          "#{@code[1]} #{@status}\r\n")
+      @response = Response.process(@socket)
+    end
+  
+    it "should have the correct count" do
+      @response.count == @count
+    end
+  
+    it "should have the correct sub_count" do
+      @response.sub_count == @sub_count
+    end
+  
+    it "should have items stored as an array of arrays" do
+      @response.items[0].should be_an_instance_of(Array)
+    end
+  
+    it "should have the correct name for the sub-array of the second item" do
+      @response.items[1][0] == 'Jane P. User'
+    end
+  
+    it "should have a code of 201" do
+      @response.code.should == @code[1]
+    end
+  
+    it do
+      @response.should be_ok
+    end
+  end
+
+end; end