net-dnd 1.1.2

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+.DS_Store
+pkg/*
+*.gem
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in net-dnd.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2011 by the Trustees of Dartmouth College. All rights reserved.
+
+The net-dnd Ruby library, and accompanying documentation, are provided
+subject to the following license agreement. By obtaining and/or using the
+software, you agree that you have read and understood this agreement, and
+will comply with its terms and conditions.
+
+1. Permission to use, copy, modify and distribute this software and
+documentation without fee is hereby granted, provided that the copyright
+notice and this agreement appear on all copies of the software and
+documentation. 
+
+2. Any documentation and advertising material relating to this software must
+acknowledge that the software was developed by Dartmouth College.
+
+3. The name of Dartmouth College may not be used to endorse or promote
+products derived from this software without specific prior written
+permission.
+
+4. Neither the Trustees of Dartmouth College nor the authors make any
+representations about the suitability of this software for any purpose. It is
+provided "as is", without any express or implied warranty.

data/README.md

@@ -0,0 +1,22 @@
+# net-dnd
+
+Net::DND is a Ruby library for performing user finding (aka. lookup) operations on a Dartmouth Name Directory (DND) server. Inspired by the net-ssh library, net-dnd uses a familiar block construct for starting and interacting with a DND session/connection.
+
+Within the block you can submit various find commands and get back zero, one or more 'hits', in the form of Net::DND::Profile instances. Each Profile instance will contain accessors for the fields that were used to seed the DND server connection.
+
+## Installation
+
+    $ sudo gem intall net-dnd
+
+## Basic Usage
+
+Opening a connection to the main Dartmouth College DND server, requesting the return of name and email address fields, for Profiles matching the name `Smith`:
+
+```ruby
+profiles = nil
+Net::DND.start('dnd.dartmouth.edu', %w(name email)) do |dnd|
+  profiles = dnd.find('Smith')
+end
+puts profiles[0].name, profiles[0].email
+```
+

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/bin/dndwho

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+# TODO
+# require 'net/dnd/cli'
+# Net::DND::CLI.start

data/lib/net/dnd.rb

@@ -0,0 +1,82 @@
+$LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../../lib"
+require "net/dnd/session"
+
+module Net
+  
+  # Inspired by the outstanding work done by Jamis Buck on the Net::SSH family of gems/libraries,
+  # this new version of Net::DND aims to be a much better interface for working with the
+  # Dartmouth Name Directory (DND) protocol.
+  #
+  # In the first (1.0.0) release, the focus is still on providing primarily user finding
+  # facilites, however, the architecture has been re-worked to allow for fairly easy support
+  # of the rest of the DND protocol, should the need ever arise.
+  #
+  # Contained here, in the module/librtary wrapper file, is the primary 'start' method, which
+  # allows for straightforward session/connection management. The intent is to call this method
+  # with a block construct, like this:
+  #
+  #   Net::DND.start("your.dnd.server", fields) do |dnd|
+  #     profile = dnd.find("some user")
+  #   end
+  #
+  # But you don't need to use the block version. You can simply call the start method and it
+  # will return a DND session object. You can then send find commands to that object. Used in
+  # this way, you have to remember to explicitly close the DND session, as below:
+  #
+  #   dnd = Net::DND.start('dnd.dartmouth.edu', %w(name nickname uid))
+  #   profile = dnd.find('Throckmorton Scribblemonger', :one)
+  #   dnd.close
+  #   puts profile.nickname
+  #    > throckie
+  #
+  # All calls to the find command, whether it's restricted to a single match or not, will return
+  # Net::DND::Profile objects. The profile object(s) will contain getter methods for the
+  # field names specified in the start call. If no fields are supplied, the DND session, and
+  # therefore all returned profile objects will contain the full set of publicly viewable fields
+  # from the partiuclar DND server to which you've connected.
+  
+  module DND
+    
+    def self.start(host, fields=[], &block)
+      session = Session.start(host, fields)
+      if block_given?
+        yield session
+        session.close
+      else
+        return session
+      end
+    end
+    
+  end
+  
+  # Convenience modules and start methods for the three most commonly accessed DND hosts.
+  # Basically, so you don't need to remeber the exact host name, as long as you know which
+  # version of the start method to call for the DND server to which you want to send finds.
+  
+  module DartmouthDND
+    
+    HOST = 'dnd.dartmouth.edu'
+    def self.start(fields=[], &block)
+      DND.start(HOST, fields, &block)
+    end
+    
+  end
+  
+  module AlumniDND
+    
+    HOST = 'dnd.dartmouth.org'
+    def self.start(fields=[], &block)
+      DND.start(HOST, fields, &block)
+    end
+    
+  end
+  
+  module HitchcockDND
+    
+    HOST = 'dnd.hitchcock.org'
+    def self.start(fields=[], &block)
+      DND.start(HOST, fields, &block)
+    end
+    
+  end
+end

data/lib/net/dnd/connection.rb

@@ -0,0 +1,89 @@
+require 'socket'
+require 'timeout'
+
+folder_path = File.dirname(__FILE__)
+require "#{folder_path}/user_spec"
+require "#{folder_path}/response"
+
+module Net
+  module DND
+
+    # An internal class, used by the Session object, to manage the TCP Socket connection
+    # to the requested DND server. The Connection object contains the low-level protocol
+    # commands that are actually composed and sent down the socket. Once a command is sent
+    # the Connection object instantiates a new Response object to parse the returned data.
+    # The Response object is sent back to the Session as the result of calling the fields
+    # and lookup methods. The quit method is used to close down the socket connection. It
+    # doesn't actually return anything back to the Session.
+    class Connection
+
+      attr_reader :host, :socket, :error, :response
+
+      # Initialize the TCP connection to be used by the Session. Will raise errors if
+      # there's no response from port 902 on the supplied host, or if the connection
+      # attempt times out. This constructor also verifies that the connected DND server
+      # is ready to respond to protocol commands.
+
+      def initialize(hostname)
+        @host = hostname
+        @open = false
+        begin
+          @socket = Timeout::timeout(5) { TCPSocket.open(host, 902) }
+        rescue Timeout::Error
+          @error = "Connection attempt to DND server on host #{host} has timed out."
+          return
+        rescue Errno::ECONNREFUSED
+          @error = "Could not connect to DND server on host #{host}."
+          return
+        end
+        @response = Response.process(socket)
+        @open = @response.ok?
+      end
+
+      # Is the TCP socket still open/active?
+
+      def open?
+        @open
+      end
+
+      # Low-level protocol command for verifying a list of supplied fields. If no fields are
+      # supplied, the fields command will return verification data for all known fields.
+
+      def fields(field_list=[])
+        cmd = "fields #{field_list.join(' ')}".rstrip
+        read_response(cmd)
+      end
+
+      # Low-level protocol command for performing a 'find' operation. Takes a user specifier
+      # and a list of fields.
+
+      def lookup(user, field_list)
+        user_spec = UserSpec.new(user)
+        cmd = "lookup #{user_spec.to_s},#{field_list.join(' ')}"
+        read_response(cmd)
+      end
+
+      # Low-level protocol command for telling the DND server that you are closing the connection.
+      # Calling this method on the socket also closes the session's TCP connection.
+
+      def quit(noargs = nil)
+        cmd = "quit"
+        read_response(cmd)
+        @socket.close
+        response
+      end
+
+      private
+
+      # Private method for sending the protocol commands across the socket. Also handles the
+      # dispatching of any returned data to the Net::DND::Response class for processing.
+
+      def read_response(cmd="noop")
+        socket.puts(cmd)
+        @open = !socket.closed?
+        @response = Response.process(socket)
+      end
+
+    end
+  end
+end

data/lib/net/dnd/errors.rb

@@ -0,0 +1,22 @@
+module Net
+  module DND
+
+    # These classes are used to provide good class names to the various errors that might
+    # be raised during a Net::DND session. All are based off of of Ruby's standard
+    # RuntimeError class.
+    class Error < RuntimeError; end
+
+    class FieldNotFound < Net::DND::Error; end
+
+    class FieldLineInvalid < Net::DND::Error; end
+
+    class FieldAccessDenied < Net::DND::Error; end
+
+    class ConnectionError < Net::DND::Error; end
+
+    class ConnectionClosed < Net::DND::Error; end
+
+    class InvalidResponse < Net::DND::Error; end
+
+  end
+end

data/lib/net/dnd/expires.rb

@@ -0,0 +1,25 @@
+require 'date'
+
+module Net
+  module DND
+
+    # Set of methods that are conditionally added to the Profile class, when the "expires" field
+    # has been specified.
+    module Expires
+
+      def expires_on
+        @expires_date ||= Date.parse(expires) rescue nil
+      end
+
+      def expire_days
+        (expires_on - Date.today).to_i rescue nil
+      end
+
+      def expired?
+        expire_days.nil? and return false
+        expire_days < 1 ? true : false
+      end
+
+    end
+  end
+end

data/lib/net/dnd/field.rb

@@ -0,0 +1,58 @@
+folder_path = File.dirname(__FILE__)
+require "#{folder_path}/errors"
+
+module Net
+  module DND
+
+    # The Field class is another wrapper class used by the Session object. Unless you are simply
+    # performing a lookup to verify that there's at least one name match, you will be passing
+    # one or more fields to the command, which will determine the data that's returned back,
+    # once a successful match has been found.
+
+    # This class comes into play, because when the DND.start method is used, you pass in a list
+    # of fields that you want to have returned. That list is first verified against the host
+    # DND server's known list of fields, through use of the protocol's FIELDS command. When sent
+    # with a list of fields, the server responds back with each fields read and write permissions.
+    # This data, along with the fields name is captured and stored in instances of this class.
+
+    class Field
+
+      attr_reader :name, :writeable, :readable
+
+      def initialize(name, writeable, readable)
+        @name = name.to_s
+        store_access_value(:writeable, writeable)
+        store_access_value(:readable, readable)
+      end
+
+      def self.from_field_line(line)
+        args = line.split
+        raise FieldLineInvalid unless args.length == 3
+        new(args[0], args[1], args[2])
+      end
+
+      def inspect
+        "#<#{self.class} name=\"#{@name}\" writeable=\"#{@writeable}\" readable=\"#{@readable}\">"
+      end
+
+      def to_s
+        @name
+      end
+
+      def to_sym
+        @name.to_sym
+      end
+
+      def read_all?
+        @readable == 'A'
+      end
+
+      private
+
+      def store_access_value(read_write, value)
+        instance_variable_set("@#{read_write}".to_sym, value)
+      end
+
+    end
+  end
+end

data/lib/net/dnd/profile.rb

@@ -0,0 +1,74 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
+require 'errors'
+
+module Net
+  module DND
+
+    autoload :Expires, 'expires'
+
+    # Container class for a single DND Profile. Takes the current fields set in the Session, along with
+    # the returned items from a lookup command and builds a 'profile' Hash. The class then provides
+    # dynamic accessor methods for each of the fields, as well as a [] accessor method for accessing
+    # fields whose name is a Ruby reserved word, i.e. class.
+    class Profile
+
+      # The profile constructor method. Takes 2 array arguments: fields and items. From these
+      # it creates a Hash object that is the internal represenation of the profile.
+
+      def initialize(fields, items)
+        @profile = Hash[*fields.zip(items).flatten]
+
+        if @profile.has_key?(:expires)
+          self.extend Net::DND::Expires
+        end
+      end
+
+      # Inspection string for instances of the class
+
+      def inspect
+        attrib_inspect = @profile.inject("") { |s, pair| k,v = pair; s << "#{k}=\"#{v}\", " }
+        "<#{self.class} length=#{length}, #{attrib_inspect.rstrip.chomp(',')}>"
+      end
+
+      # Length of the class instance, basically the number of fields/items. Only really used
+      # by the inspect method.
+
+      def length
+        @profile.length
+      end
+
+      # Generic Hash-style accessor method. Provides access to fields in the profile hash when
+      # the name of the field is a reserved word in Ruby. Allows for field names supplied as
+      # either Strings or Symbols.
+
+      def [](field)
+        return_field(field)
+      end
+
+      private
+
+      # Handles all dynamic accessor methods for the Profile instance. This is based on the
+      # field accessor methods from Rails ActiveRecord. Fields can be directly accessed on
+      # the Profile object, either for purposes of returning their value or, if the field name
+      # is requested with a '?' on the end, a true/false is returned based on the existence of
+      # the named field in Profile instance.
+
+      def method_missing(method_id)
+        attrib_name = method_id.to_s
+        return @profile.has_key?(attrib_name.chop.to_sym) if attrib_name[-1, 1] == '?'
+        return_field(method_id)
+      end
+
+      # Private method, used by the [] method and the dynamic accessors. It will return the value
+      # of the named field, or it will raise a FieldNotFound error if the field isn't part of the
+      # current Profile.
+
+      def return_field(field)
+        field = field.to_sym
+        return @profile[field] if @profile.has_key?(field)
+        raise FieldNotFound, "Field #{field} not found."
+      end
+
+    end
+  end
+end

data/lib/net/dnd/response.rb

@@ -0,0 +1,95 @@
+module Net
+  module DND
+
+    # Container class for fetching and parsing the response lines returned down the socket
+    # after a command has been sent to the connected DND server. Checks for good responses
+    # as well as error responses.
+
+    # For good responses that contain multiple lines-- fields and lookup commands --it parses
+    # those lines into an items array that it makes avaialable back to calling method.
+
+    class Response
+
+      attr_reader :code, :error, :items, :count, :sub_count
+
+      # Constructor method for a Response object. This method is only called directly by
+      # our unit tests (specs). Normal interaction with the Response class is via the
+      # 'process' class method.
+
+      def initialize(socket)
+        @items = []
+        @count, @sub_count = 0, 0
+        @socket = socket
+      end
+
+      # Convenience method for creating a new Response object and automatically parse
+      # data items, if they exist.
+
+      def self.process(socket)
+        resp = Response.new(socket)
+        resp.status_line
+        resp.parse_items if [101, 102].include?(resp.code)
+        resp
+      end
+
+      # Was the result of the last command a 'good' respose?
+
+      def ok?
+        (200..299) === code
+      end
+
+      # The first line returned from all command sent to a DND server is the Status Line. The
+      # makup of this line not only tells us the success/failuer of the command, but whether
+      # there is more data to be read.
+      #
+      # When there is more data, it will be contained on one or more additional data lines,
+      # called 'items' internally. The status line tells us if we have 1 level of n items, or
+      # 2 levels of n items, each of which has m sub-items. In the class, n and m are the count
+      # and sub_count attributes, respectively.
+
+      def status_line
+        line = @socket.gets.chomp
+        @code = line.match(/^(\d\d\d) /).captures[0].to_i
+        case code
+          when 200..299 # Command successful, ready for next
+            true
+          when 500..599 # Command error, set the error value to the line text
+            @error = line.match(/^\d\d\d (.*)/).captures[0]
+          when 101, 102 # Data command status, set the count and sub_count values
+            counts = line.match(/^\d\d\d (\d+) *(\d*)/).captures
+            @count = counts[0].to_i
+            @sub_count = counts[1].to_i
+        end
+      end
+
+      # The result of our command has told us there are data items that need to be read and
+      # parsed. This method sets up the loops used to read the correct number of data lines.
+      # If we have a postive sub_count value, we actually build a nested array of arrays,
+      # otherwise, we build a single level array of data lines.
+
+      def parse_items
+        count.times do # loop at least count times
+          if sub_count > 0 # do we have an inner loop
+            sub_ary = []
+            sub_count.times { sub_ary << data_line }
+            @items << sub_ary
+          else
+            @items << data_line
+          end
+        end
+        status_line
+      end
+
+      private
+
+      # This private method handles the actually reading of the data item lines from the
+      # TCP socket. It reads the line and then does a quick parse on it, to return just
+      # the data item.
+
+      def data_line
+        @socket.gets.chomp.match(/^\d\d\d (.*)/).captures[0]
+      end
+
+    end
+  end
+end