treequel 1.2.2 → 1.3.0pre384

data/lib/treequel.rb

@@ -25,7 +25,7 @@ end
 
 # A library for interacting with LDAP modelled after Sequel.
 #
-# @version 1.2.2
+# @version 1.3.0
 # 
 # @example
 #   # Connect to the directory at the specified URL
@@ -53,10 +53,10 @@ end
 module Treequel
 
 	# Library version
-	VERSION = '1.2.2'
+	VERSION = '1.3.0'
 
 	# VCS revision
-	REVISION = %q$Revision: 0c2883d2074a $
+	REVISION = %q$Revision: 554028334395 $
 
 	# Common paths for ldap.conf
 	COMMON_LDAP_CONF_PATHS = %w[
@@ -80,6 +80,16 @@ module Treequel
 
 
 	### Logging
+	# Log levels
+	LOG_LEVELS = {
+		'debug' => Logger::DEBUG,
+		'info'  => Logger::INFO,
+		'warn'  => Logger::WARN,
+		'error' => Logger::ERROR,
+		'fatal' => Logger::FATAL,
+	}.freeze
+	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
+
 	@default_logger = Logger.new( $stderr )
 	@default_logger.level = $DEBUG ? Logger::DEBUG : Logger::WARN
 

data/lib/treequel/behavior/control.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require 'rspec'
+
+require 'treequel'
+require 'treequel/control'
+
+
+# This is a shared behavior for specs which different Treequel::Controls share in 
+# common. If you're creating a Treequel::Control implementation, you can test
+# its conformity to the expectations placed on them by adding this to your spec:
+# 
+#    require 'treequel/behavior/control'
+#
+#    describe YourControl do
+#
+#      it_should_behave_like "A Treequel::Control"
+#
+#    end
+
+shared_examples_for "A Treequel::Control" do
+
+	let( :control ) do
+		described_class
+	end
+
+
+	it "implements one of either #get_client_controls or #get_server_controls" do
+		methods = [
+			'get_client_controls',		# 1.8.x
+			'get_server_controls',
+			:get_client_controls,		# 1.9.x
+			:get_server_controls
+		]
+		(control.instance_methods( false ) | methods).should_not be_empty()
+	end
+
+end
+
+

data/lib/treequel/branch.rb

@@ -38,11 +38,17 @@ class Treequel::Branch
 	# [Boolean] Whether or not to include operational attributes by default.
 	@include_operational_attrs = false
 
+	# [Boolean] Whether or not to freeze values cached in @values. This helps
+	#   prevent you from accidentally doing branch[:attr] << 'value', which
+	#   modifies the cached values, but not the entry.
+	@freeze_converted_values = true
+
 	# Whether or not to include operational attributes when fetching the
 	# entry for branches.
 	class << self
 		extend Treequel::AttributeDeclarations
 		predicate_attr :include_operational_attrs
+		predicate_attr :freeze_converted_values
 	end
 
 
@@ -54,8 +60,12 @@ class Treequel::Branch
 	### @return [Treequel::Branch]  The new branch object.
 	def self::new_from_entry( entry, directory )
 		entry = Treequel::HashUtilities.stringify_keys( entry )
-		Treequel.logger.debug "Creating Branch from entry: %p in directory: %p" % [ entry, directory ]
-		return self.new( directory, entry['dn'].first, entry )
+		dnvals = entry.delete( 'dn' ) or
+			raise ArgumentError, "no 'dn' attribute for entry"
+
+		Treequel.logger.debug "Creating Branch from entry: %p in directory: %s" %
+			[ dnvals.first, directory ]
+		return self.new( directory, dnvals.first, entry )
 	end
 
 
@@ -72,6 +82,7 @@ class Treequel::Branch
 	### @param [String] dn  The DN of the entry the Branch is wrapping.
 	### @param [LDAP::Entry, Hash] entry  The entry object if it's already been fetched.
 	def initialize( directory, dn, entry=nil )
+		raise ArgumentError, "nil DN" unless dn
 		raise ArgumentError, "invalid DN" unless
 			dn.match( Patterns::DISTINGUISHED_NAME ) || dn.empty?
 		raise ArgumentError, "can't cast a %s to an LDAP::Entry" % [entry.class.name] unless
@@ -93,7 +104,7 @@ class Treequel::Branch
 	######
 
 	# Delegate some other methods to a new Branchset via the #branchset method
-	def_method_delegators :branchset, :filter, :scope, :select, :limit, :timeout, :order
+	def_method_delegators :branchset, :filter, :scope, :select, :limit, :timeout, :order, :as
 
 	# Delegate some methods to the Branch's directory via its accessor
 	def_method_delegators :directory, :controls, :referrals
@@ -204,7 +215,8 @@ class Treequel::Branch
 	### Return the Branch's immediate parent node.
 	### @return [Treequel::Branch]
 	def parent
-		return self.class.new( self.directory, self.parent_dn )
+		pardn = self.parent_dn or return nil
+		return self.class.new( self.directory, pardn )
 	end
 
 
@@ -267,7 +279,7 @@ class Treequel::Branch
 		self.log.debug "  making LDIF from an entry: %p" % [ entry ]
 
 		entry.keys.reject {|k| k == 'dn' }.each do |attribute|
-			entry[ attribute ].each do |val|
+			Array( entry[attribute] ).each do |val|
 				ldif << ldif_for_attr( attribute, val, width )
 			end
 		end
@@ -299,14 +311,16 @@ class Treequel::Branch
 	def []( attrname )
 		attrsym = attrname.to_sym
 
-		unless @values.key?( attrsym )
+		if @values.key?( attrsym )
+			self.log.debug "  value for %p is cached (%p)." % [ attrname, @values[attrsym] ]
+		else
 			self.log.debug "  value for %p is NOT cached." % [ attrsym ]
 			value = self.get_converted_object( attrsym )
 			self.log.debug "  converted value is: %p" % [ value ]
-			value.freeze if value.respond_to?( :freeze )
+			value.freeze if
+				self.class.freeze_converted_values? &&
+				value.respond_to?( :freeze )
 			@values[ attrsym ] = value
-		else
-			self.log.debug "  value for %p is cached." % [ attrname ]
 		end
 
 		return @values[ attrsym ]
@@ -366,23 +380,33 @@ class Treequel::Branch
 	### 
 	### @return [TrueClass] if the delete succeeded
 	def delete( *attributes )
+
+		# If no attributes are given, delete the whole entry
 		if attributes.empty?
 			self.log.info "No attributes specified; deleting entire entry for %s" % [ self.dn ]
 			self.directory.delete( self )
+
+		# Otherwise, gather up the LDAP::Mod objects that will delete the given attributes
 		else
 			self.log.debug "Deleting attributes: %p" % [ attributes ]
 			mods = attributes.flatten.collect do |attribute|
+
+				# Delete particular values of the attribute
 				if attribute.is_a?( Hash )
 					attribute.collect do |key,vals|
-						vals = Array( vals ).collect {|val| val.to_s }
+						vals = [ vals ] unless vals.is_a?( Array )
+						vals.collect! {|val| self.get_converted_attribute(key, val) }
 						LDAP::Mod.new( LDAP::LDAP_MOD_DELETE, key.to_s, vals )
 					end
+
+				# Delete all values of the attribute
 				else
 					LDAP::Mod.new( LDAP::LDAP_MOD_DELETE, attribute.to_s, [] )
 				end
-			end.flatten
 
-			self.directory.modify( self, mods )
+			end
+
+			self.directory.modify( self, mods.flatten )
 		end
 
 		self.clear_caches
@@ -394,9 +418,10 @@ class Treequel::Branch
 	### Create the entry for this Branch with the specified +attributes+. The +attributes+ should,
 	### at a minimum, contain the pair `:objectClass => :someStructuralObjectClass`.
 	### 
-	### @param [Hash<Symbol,String => Object>] attributes
+	### @see Treequel::Directory#create
 	def create( attributes={} )
 		self.directory.create( self, attributes )
+		self.clear_caches
 		return self
 	end
 
@@ -432,7 +457,10 @@ class Treequel::Branch
 	### @param [Hash<String, Symbol => Object>] attributes 
 	def move( rdn )
 		self.log.debug "Asking the directory to move me to an entry called %p" % [ rdn ]
-		return self.directory.move( self, rdn )
+		self.directory.move( self, rdn )
+		self.clear_caches
+
+		return self
 	end
 
 
@@ -493,9 +521,8 @@ class Treequel::Branch
 		schema = self.directory.schema
 
 		oc_oids = self[:objectClass] || []
-		self.log.debug "  objectClass OIDs are: %p" % [ oc_oids ]
 		oc_oids |= additional_classes.collect {|str| str.to_sym }
-		oc_oids << :top if oc_oids.empty?
+		oc_oids << 'top' if oc_oids.empty?
 
 		oclasses = []
 		oc_oids.each do |oid|
@@ -504,7 +531,7 @@ class Treequel::Branch
 			oclasses << oc
 		end
 
-		self.log.debug "  found %d objectClasses: %p" % [  oclasses.length, oclasses ]
+		self.log.debug "  found %d objectClasses: %p" % [  oclasses.length, oclasses.map(&:name) ]
 		return oclasses.uniq
 	end
 
@@ -539,7 +566,7 @@ class Treequel::Branch
 		 	[ oclasses.map(&:name) ]
 
 		oclasses.each do |oc|
-			self.log.debug "  adding %p from %p" % [ oc.must, oc ]
+			self.log.debug "  adding %p from %p" % [ oc.must.map(&:name), oc.name ]
 			types |= oc.must
 		end
 
@@ -571,10 +598,10 @@ class Treequel::Branch
 		attrhash = {}
 
 		self.must_attribute_types( *additional_object_classes ).each do |attrtype|
-			self.log.debug "  adding attrtype %p to the MUST attributes hash" % [ attrtype ]
+			# self.log.debug "  adding attrtype %p to the MUST attributes hash" % [ attrtype.name ]
 
 			if attrtype.name == :objectClass
-				attrhash[ :objectClass ] = [:top] | additional_object_classes
+				attrhash[ :objectClass ] = ['top'] | additional_object_classes
 			elsif attrtype.single?
 				attrhash[ attrtype.name ] = ''
 			else
@@ -625,7 +652,7 @@ class Treequel::Branch
 		attrhash = {}
 
 		self.may_attribute_types( *additional_object_classes ).each do |attrtype|
-			self.log.debug "  adding attrtype %p to the MAY attributes hash" % [ attrtype ]
+			# self.log.debug "  adding attrtype %p to the MAY attributes hash" % [ attrtype.named ]
 
 			if attrtype.single?
 				attrhash[ attrtype.name ] = nil
@@ -772,15 +799,16 @@ class Treequel::Branch
 	### Get the value associated with +attrsym+, convert it to a Ruby object if the Branch's
 	### directory has a conversion rule, and return it.
 	def get_converted_object( attrsym )
-		return nil unless self.entry
-		value = self.entry[ attrsym.to_s ] or return nil
+		value = self.entry ? self.entry[ attrsym.to_s ] : nil
 
 		if attribute = self.directory.schema.attribute_types[ attrsym ]
+			syntax_oid = attribute.syntax.oid
+
 			if attribute.single?
-				value = self.directory.convert_to_object( attribute.syntax.oid, value.first )
+				value = self.directory.convert_to_object( syntax_oid, value.first ) if value
 			else
-				value = value.collect do |raw|
-					self.directory.convert_to_object( attribute.syntax.oid, raw )
+				value = Array( value ).collect do |raw|
+					self.directory.convert_to_object( syntax_oid, raw )
 				end
 			end
 		else
@@ -795,8 +823,8 @@ class Treequel::Branch
 	### and return it.
 	def get_converted_attribute( attrsym, object )
 		if attribute = self.directory.schema.attribute_types[ attrsym ]
-			self.log.debug "converting %p object to a %p attribute" %
-				[ attrsym, attribute.syntax.desc ]
+			self.log.debug "converting %p object (a %p) to a %p attribute" %
+				[ attrsym, object.class, attribute.syntax.desc ]
 			return self.directory.convert_to_attribute( attribute.syntax.oid, object )
 		else
 			self.log.info "no attributeType for %p" % [ attrsym ]

data/lib/treequel/branchset.rb

@@ -77,9 +77,17 @@ class Treequel::Branchset
 	def initialize( branch, options={} )
 		@branch = branch
 		@options = DEFAULT_OPTIONS.merge( options )
+		self.log.debug "Setting up %p for branch %p with options: %p" %
+			[ self.class, @branch, @options ]
 
-		self.extend( *@branch.directory.registered_controls ) unless
-			@branch.directory.registered_controls.empty?
+		if @branch.directory.registered_controls.empty?
+			self.log.debug "  no registered controls."
+		else
+			@branch.directory.registered_controls.each do |control|
+				self.log.debug "  extending with %p" % [ control ]
+				self.extend( control )
+			end
+		end
 
 		super()
 	end

data/lib/treequel/controls/pagedresults.rb

@@ -47,7 +47,7 @@ module Treequel::PagedResultsControl
 
 	### Add the control's instance variables to including Branchsets.
 	def initialize
-		@paged_results_cookie = ''
+		@paged_results_cookie = nil
 		@paged_results_setsize = nil
 	end
 
@@ -75,8 +75,10 @@ module Treequel::PagedResultsControl
 		newset = self.clone
 
 		if setsize.nil? || setsize.zero?
+			self.log.debug "Removing paged results control."
 			newset.paged_results_setsize = nil
 		else
+			self.log.debug "Adding paged results control with page size = %d." % [ setsize ]
 			newset.paged_results_setsize = setsize
 		end
 
@@ -96,7 +98,7 @@ module Treequel::PagedResultsControl
 	### Remove any paging control associated with the receiving Branchset.
 	### @return [void]
 	def without_paging!
-		self.paged_results_cookie = ''
+		self.paged_results_cookie = nil
 		self.paged_results_setsize = nil
 	end
 

data/lib/treequel/directory.rb

@@ -99,7 +99,7 @@ class Treequel::Directory
 
 
 	#################################################################
-	###	C L A S S   M E T H O D S
+	###	I N S T A N C E   M E T H O D S
 	#################################################################
 
 	### Create a new Treequel::Directory with the given +options+. Options is a hash with one
@@ -132,14 +132,14 @@ class Treequel::Directory
 		@conn                  = nil
 		@bound_user            = nil
 
-		@base_dn               = options[:base_dn] || self.get_default_base_dn
-
-		@base                  = nil
 
 		@object_conversions    = DEFAULT_OBJECT_CONVERSIONS.dup
 		@attribute_conversions = DEFAULT_ATTRIBUTE_CONVERSIONS.dup
 		@registered_controls   = []
 
+		@base_dn               = options[:base_dn] || self.get_default_base_dn
+		@base                  = nil
+
 		# Immediately bind if credentials are passed to the initializer.
 		if ( options[:bind_dn] && options[:pass] )
 			self.bind( options[:bind_dn], options[:pass] )
@@ -155,7 +155,7 @@ class Treequel::Directory
 	def_method_delegators :base, *DELEGATED_BRANCH_METHODS
 
 	# Delegate some methods to the connection via the #conn method
-	def_method_delegators :conn, :controls, :referrals, :root_dse
+	def_method_delegators :conn, :controls, :referrals
 
 
 	# The host to connect to.
@@ -187,6 +187,12 @@ class Treequel::Directory
 	attr_reader :bound_user
 
 
+	### Fetch the root DSE as a Treequel::Branch.
+	def root_dse
+		return self.search( '', :base, '(objectClass=*)', :selectattrs => ['+'] ).first
+	end
+
+
 	### Fetch the Branch for the base node of the directory.
 	### @return [Treequel::Branch]
 	def base
@@ -231,6 +237,23 @@ class Treequel::Directory
 	end
 
 
+	### Drop the existing connection and establish a new one.
+	### @return [Boolean]  +true+ if the connection was re-established
+	### @raise [RuntimeError]  if the re-connection failed
+	def reconnect
+		self.log.info "Reconnecting to %s..." % [ self.uri ]
+		@conn = self.connect
+		self.log.info "...reconnected."
+
+		return true
+	rescue LDAP::ResultError => err
+		self.log.error "%s while attempting to reconnect to %s: %s" %
+			[ err.class.name, self.uri, err.message ]
+		raise "Couldn't reconnect to %s: %s: %s" %
+			[ self.uri, err.class.name, err.message ]
+	end
+
+
 	### Return the URI object that corresponds to the directory.
 	### @return [URI::LDAP]
 	def uri
@@ -457,7 +480,7 @@ class Treequel::Directory
 			self.log.debug "Modifying %s with LDAP mod objects: %p" % [ branch.dn, mods ]
 			self.conn.modify( branch.dn, mods )
 		else
-			normattrs = self.normalize_attributes( mods )
+			normattrs = normalize_attributes( mods )
 			self.log.debug "Modifying %s with: %p" % [ branch.dn, normattrs ]
 			self.conn.modify( branch.dn, normattrs )
 		end
@@ -472,28 +495,13 @@ class Treequel::Directory
 
 
 	### Create the entry for the given +branch+, setting its attributes to +newattrs+.
+	### @param [Treequel::Branch, #to_s] branch   the branch to create (or a DN string)
+	### @param [Hash, Array<LDAP::Mod>] newattrs  the attributes to create the entry with. This
+	###                                   can be either a Hash of attributes, or an Array of
+	###                                   LDAP::Mod objects.
 	def create( branch, newattrs={} )
-		newdn = branch.dn
-		schema = self.schema
-
-		# Merge RDN attributes with existing ones, combining any that exist in both
-		self.log.debug "Smushing rdn attributes %p into %p" % [ branch.rdn_attributes, newdn ]
-		newattrs.merge!( branch.rdn_attributes ) do |key, *values|
-			values.flatten.uniq
-		end
-
-		normattrs = self.normalize_attributes( newattrs )
-		raise ArgumentError, "Can't create an entry with no objectClasses" unless
-			normattrs.key?( 'objectClass' )
-		normattrs['objectClass'].each do |oc|
-			raise ArgumentError, "No such objectClass #{oc.inspect}" unless
-				schema.object_classes.key?(oc.to_sym)
-		end
-		raise ArgumentError, "Can't create an entry with no structural objectClass" unless
-			normattrs['objectClass'].any? {|oc| schema.object_classes[oc.to_sym].structural? }
-
-		self.log.debug "Creating an entry at %s with the attributes: %p" % [ newdn, normattrs ]
-		self.conn.add( newdn, normattrs )
+		newattrs = normalize_attributes( newattrs ) if newattrs.is_a?( Hash )
+		self.conn.add( branch.to_s, newattrs )
 
 		return true
 	end
@@ -565,6 +573,7 @@ class Treequel::Directory
 			end
 		end
 	end
+	alias_method :register_control, :register_controls
 
 
 	### Map the specified LDAP +attribute+ to its Ruby datatype if one is registered for the given 
@@ -605,7 +614,7 @@ class Treequel::Directory
 	### Return an Array of OID strings representing the controls supported by the Directory, 
 	### as listed in the directory's root DSE.
 	def supported_control_oids
-		return self.conn.root_dse.first['supportedControl']
+		return self.root_dse[:supportedControl]
 	end
 
 
@@ -620,7 +629,7 @@ class Treequel::Directory
 	### Return an Array of OID strings representing the extensions supported by the Directory, 
 	### as listed in the directory's root DSE.
 	def supported_extension_oids
-		return self.conn.root_dse.first['supportedExtension']
+		return self.root_dse[:supportedExtension]
 	end
 
 
@@ -635,7 +644,7 @@ class Treequel::Directory
 	### Return an Array of OID strings representing the features supported by the Directory, 
 	### as listed in the directory's root DSE.
 	def supported_feature_oids
-		return self.conn.root_dse.first['supportedFeatures']
+		return self.root_dse[:supportedFeatures]
 	end
 
 
@@ -675,9 +684,7 @@ class Treequel::Directory
 
 	### Fetch the default base dn for the server from the server's Root DSE.
 	def get_default_base_dn
-		dse = self.root_dse
-		return '' if dse.nil? || dse.empty?
-		return dse.first['namingContexts'].first
+		return self.root_dse[:namingContexts].first.dn
 	end
 
 
@@ -694,23 +701,6 @@ class Treequel::Directory
 	end
 
 
-	### Normalize the attributes in +hash+ to be of the form expected by the
-	### LDAP library (i.e., keys as Strings, values as Arrays of Strings)
-	def normalize_attributes( hash )
-		normhash = {}
-		hash.each do |key,val|
-			val = [ val ] unless val.is_a?( Array )
-			val.collect! {|obj| obj.to_s }
-
-			normhash[ key.to_s ] = val
-		end
-
-		normhash.delete( 'dn' )
-
-		return normhash
-	end
-
-
 	### Normalize the parameters to the #search method into the format expected by 
 	### the LDAP::Conn#Search_ext2 method and return them as a Hash.
 	def normalize_search_parameters( base, scope, filter, parameters )