treequel 1.0.1 → 1.0.4

data/lib/treequel/directory.rb

@@ -13,18 +13,6 @@ require 'treequel/constants'
 
 # The object in Treequel that represents a connection to a directory, the
 # binding to that directory, and the base from which all DNs start.
-#
-# == Authors
-#
-# * Michael Granger <ged@FaerieMUD.org>
-# * Mahlon E. Smith <mahlon@martini.nu>
-#
-# :include: LICENSE
-#
-#--
-#
-# Please see the file LICENSE in the base directory for licensing details.
-#
 class Treequel::Directory
 	include Treequel::Loggable,
 	        Treequel::Constants,
@@ -99,33 +87,37 @@ class Treequel::Directory
 
 	### Create a new Treequel::Directory with the given +options+. Options is a hash with one
 	### or more of the following key-value pairs:
-	###
-	### [:host]
-	###   The LDAP host to connect to.
-	### [:port]
-	###   The port to connect to.
-	### [:connect_type]
-	###   The type of connection to establish. Must be one of +:plain+, +:tls+, or +:ssl+.
-	### [:base_dn]
-	###   The base DN of the directory.
-	### [:bind_dn]
-	###   The DN of the user to bind as.
-	### [:pass]
-	###   The password to use when binding.
+	### 
+	### @param [Hash] options the connection options
+	### @option options [String] :host ('localhost')
+	###    The LDAP host to connect to
+	### @option options [Fixnum] :port (LDAP::LDAP_PORT)
+	###    The port number to connect to
+	### @option options [Symbol] :connect_type (:tls)
+	###    The type of connection to establish; :tls, :ssl, or :plain.
+	### @option options [String] :base_dn (nil)
+	###    The base DN of the directory; defaults to the first naming context of
+	###    the directory's root DSE.
+	### @option options [String] :bind_dn (nil)
+	###    The DN of the user to bind as; if unset, binds anonymously.
+	### @option options [String] :pass (nil)
+	###    The password to use when binding.
 	def initialize( options={} )
-		options         = DEFAULT_OPTIONS.merge( options )
+		options       = DEFAULT_OPTIONS.merge( options )
 
-		@host           = options[:host]
-		@port           = options[:port]
-		@connect_type   = options[:connect_type]
+		@host         = options[:host]
+		@port         = options[:port]
+		@connect_type = options[:connect_type]
 
-		@conn           = nil
-		@bound_as       = nil
+		@conn         = nil
+		@bound_user   = nil
 
-		@base_dn        = options[:base_dn] || self.get_default_base_dn
-		@syntax_mapping = DEFAULT_SYNTAX_MAPPING.dup
+		@base_dn      = options[:base_dn] || self.get_default_base_dn
 
-		@base           = nil
+		@base         = nil
+
+		@syntax_mapping      = DEFAULT_SYNTAX_MAPPING.dup
+		@registered_controls = []
 
 		# Immediately bind if credentials are passed to the initializer.
 		if ( options[:bind_dn] && options[:pass] )
@@ -141,38 +133,57 @@ class Treequel::Directory
 	# Delegate some methods to the #base Branch.
 	def_method_delegators :base, *DELEGATED_BRANCH_METHODS
 
+	# Delegate some methods to the connection via the #conn method
+	def_method_delegators :conn, :controls, :referrals
+
+
 	# The host to connect to.
+	# @return [String]
 	attr_accessor :host
 
 	# The port to connect to.
+	# @return [Fixnum]
 	attr_accessor :port
 
 	# The type of connection to establish
+	# @return [Symbol]
 	attr_accessor :connect_type
 
 	# The base DN of the directory
+	# @return [String]
 	attr_accessor :base_dn
 
+	# The control modules that are registered with the directory
+	# @return [Array<Module>]
+	attr_reader :registered_controls
+
+	# The DN of the user the directory is bound as
+	# @return [String]
+	attr_reader :bound_user
+
 
 	### Fetch the Branch for the base node of the directory.
+	### @return [Treequel::Branch]
 	def base
 		return @base ||= Treequel::Branch.new( self, self.base_dn )
 	end
 
 
 	### Returns a string that describes the directory
+	### @return [String]
 	def to_s
 		return "%s:%d (%s, %s, %s)" % [
 			self.host,
 			self.port,
 			self.base_dn,
 			self.connect_type,
-			self.bound? ? @bound_as : 'anonymous'
+			self.bound? ? @bound_user : 'anonymous'
 		  ]
 	end
 
 
 	### Return a human-readable representation of the object suitable for debugging
+	### @return [String]
 	def inspect
 		return %{#<%s:0x%0x %s:%d (%s) base_dn=%p, bound as=%s, schema=%s>} % [
 			self.class.name,
@@ -181,7 +192,7 @@ class Treequel::Directory
 			self.port,
 			@conn ? "connected" : "not connected",
 			self.base_dn,
-			@bound_as ? @bound_as.dump : "anonymous",
+			@bound_user ? @bound_user.dump : "anonymous",
 			@schema ? @schema.inspect : "(schema not loaded)",
 		]
 	end
@@ -189,12 +200,14 @@ class Treequel::Directory
 
 	### Return the LDAP::Conn object associated with this directory, creating it with the
 	### current options if necessary.
+	### @return [LDAP::Conn, LDAP::SSLConn]
 	def conn
 		return @conn ||= self.connect
 	end
 
 
 	### Return the URI object that corresponds to the directory.
+	### @return [URI::LDAP]
 	def uri
 		uri_parts = {
 			:scheme => self.connect_type == :ssl ? 'ldaps' : 'ldap',
@@ -208,30 +221,41 @@ class Treequel::Directory
 
 
 	### Bind as the specified +user_dn+ and +password+.
+	### 
+	### @param [String, #dn] user_dn  the DN of the user to bind as
+	### @param [String] password      the password to bind with
+	### 
+	### @return [void]
 	def bind( user_dn, password )
 		user_dn = user_dn.dn if user_dn.respond_to?( :dn )
 
 		self.log.info "Binding with connection %p as: %s" % [ self.conn, user_dn ]
 		self.conn.bind( user_dn.to_s, password )
-		@bound_as = user_dn.to_s
+		@bound_user = user_dn.to_s
 	end
+	alias_method :bind_as, :bind
 
 
 	### Execute the provided +block+ after binding as +user_dn+ with the given +password+. After
 	### the block returns, the original binding (if any) will be restored.
+	### 
+	### @param (see #bind)
+	### 
+	### @return [void]
 	def bound_as( user_dn, password )
 		raise LocalJumpError, "no block given" unless block_given?
-		previous_bind_dn = @bound_as
+		previous_bind_dn = @bound_user
 		self.with_duplicate_conn do
 			self.bind( user_dn, password )
 			yield
 		end
 	ensure
-		@bound_as = previous_bind_dn
+		@bound_user = previous_bind_dn
 	end
 
 
-	### Returns +true+ if the directory's connection has already established a binding.
+	### Returns +true+ if the directory's connection is already bound to the directory.
+	### @return [Boolean]
 	def bound?
 		return self.conn.bound?
 	end
@@ -239,6 +263,7 @@ class Treequel::Directory
 
 
 	### Ensure that the the receiver's connection is unbound.
+	### @return [void]
 	def unbind
 		if @conn.bound?
 			old_conn = @conn
@@ -249,6 +274,7 @@ class Treequel::Directory
 
 
 	### Return the RDN string to the given +dn+ from the base of the directory.
+	### @param [#to_s] dn  the DN of the entry
 	def rdn_to( dn )
 		base_re = Regexp.new( ',' + Regexp.quote(self.base_dn) + '$' )
 		return dn.to_s.sub( base_re, '' )
@@ -257,6 +283,8 @@ class Treequel::Directory
 
 	### Given a Treequel::Branch object, find its corresponding LDAP::Entry and return
 	### it.
+	### 
+	### @param [Treequel::Branch] branch  the branch to look up
 	def get_entry( branch )
 		self.log.debug "Looking up entry for %p" % [ branch.dn ]
 		return self.conn.search_ext2( branch.dn, SCOPE[:base], '(objectClass=*)' ).first
@@ -269,6 +297,8 @@ class Treequel::Directory
 	### Given a Treequel::Branch object, find its corresponding LDAP::Entry and return
 	### it with its operational attributes (http://tools.ietf.org/html/rfc4512#section-3.4)
 	### included.
+	### 
+	### @param [Treequel::Branch] branch  the branch to look up
 	def get_extended_entry( branch )
 		self.log.debug "Looking up entry (with operational attributes) for %p" % [ branch.dn ]
 		return self.conn.search_ext2( branch.dn, SCOPE[:base], '(objectClass=*)', %w[* +] ).first
@@ -289,47 +319,96 @@ class Treequel::Directory
 	end
 
 
-	### Perform a +scope+ search at +base+ using the specified +filter+. The +scope+ argument
-	### can be one of +:onelevel+, +:base+, or +:subtree+. Results will be returned as instances
-	### of the given +collectclass+.
-	def search( base, scope=:subtree, filter='(objectClass=*)', parameters={} )
+	### Perform a +scope+ search at +base+ using the specified +filter+.
+	### 
+	### @param [String, #dn] base  The base DN of the search.
+	### @param [Symbol] scope      The scope to use in the search; can be one of 
+	###                            +:onelevel+, +:base+, or +:subtree+. 
+	### @param [#to_s] filter      The search filter (RFC4515), either as a String 
+	###                            or something that stringifies to an filter string.
+	### @param [Hash] options      Search options.
+	### 
+	### @option options [Class] :results_class (Treequel::Branch)
+	###    The Class to use when wrapping results; if not specified, defaults to the class 
+	###    of +base+ if it responds to #new_from_entry, or Treequel::Branch 
+	###    if it does not.
+	### @option options [Array<String, Symbol>] :selectattrs (['*'])
+	###    The attributes to return from the search; defaults to '*', which means to
+	###    return all non-operational attributes. Specifying '+' will cause the search
+	###    to include operational parameters as well.
+	### @option options [Boolean] :attrsonly (false)
+	###    If +true, the LDAP::Entry objects returned from the search won't have attribute values.
+	###    This has no real effect on Treequel::Branches, but is provided in case other 
+	###    +results_class+ classes need it.
+	### @option options [Array<LDAP::Control>] :server_controls (nil)
+	###    Any server controls that should be sent with the search.
+	### @option options [Array<LDAP::Control>] :client_controls (nil)
+	###    Any client controls that should be applied to the search.
+	### @option options [Fixnum] :timeout_s (0)
+	###    The number of seconds (in addition to :timeout_us) after which the search request should 
+	###    be aborted.
+	### @option options [Fixnum] :timeout_us (0)
+	###    The number of microseconds (in addition to :timeout_s) after which the search request 
+	###    should be aborted.
+	### @option options [Fixnum] :limit
+	###    The maximum number of results to return from the server.
+	### @option options [Array<String>] :sort_attribute
+	###    An Array of String attribute names to sort by. 
+	### @option options [Proc] :sort_func
+	###    A function that will provide sorting.
+	### 
+	### @return [Array] the array of results, each of which is wrapped in the
+	###    options[:results_class]. If a block is given, it acts like a filter:
+	###    the return vaule from the block is returned instead.
+	### 
+	### @yield [branch]  an optional block, which will receive the results one at a time
+	### @yieldparam [Treequel::Branch] branch  the resulting entry, wrapped in 
+	###    the options[:results_class].
+	def search( base, scope=:subtree, filter='(objectClass=*)', options={} )
 		collectclass = nil
 
 		# If the base argument is an object whose class knows how to create instances of itself
 		# from an LDAP::Entry, use it instead of Treequel::Branch to wrap results
-		if parameters.key?( :results_class )
-			collectclass = parameters.delete( :results_class )
+		if options.key?( :results_class )
+			collectclass = options.delete( :results_class )
 		else
 			collectclass = base.class.respond_to?( :new_from_entry ) ? base.class : Treequel::Branch
 		end
 
 		# Format the arguments in the way #search_ext2 expects them
-		base, scope, filter, searchparams =
-			self.normalize_search_parameters( base, scope, filter, parameters )
+		base_dn, scope, filter, searchopts =
+			self.normalize_search_parameters( base, scope, filter, options )
 
-		# Unwrap the search parameters from the hash in the correct order
+		# Unwrap the search options from the hash in the correct order
 		self.log.debug {
 			attrlist = SEARCH_PARAMETER_ORDER.inject([]) do |list, param|
-				list << "%s: %p" % [ param, searchparams[param] ]
+				list << "%s: %p" % [ param, searchopts[param] ]
 			end
 			"searching with base: %p, scope: %p, filter: %p, %s" %
-				[ base, scope, filter, attrlist.join(', ') ]
+				[ base_dn, scope, filter, attrlist.join(', ') ]
 		}
-		parameters = searchparams.values_at( *SEARCH_PARAMETER_ORDER )
+		parameters = searchopts.values_at( *SEARCH_PARAMETER_ORDER )
 
 		# Wrap each result in the class derived from the 'base' argument
 		self.log.debug "Searching via search_ext2 with arguments: %p" % [[
-			base, scope, filter, *parameters
+			base_dn, scope, filter, *parameters
 		]]
-		if block_given?
-			self.conn.search_ext2( base, scope, filter, *parameters ).each do |entry|
-				yield collectclass.new_from_entry( entry, self )
+
+		results = []
+
+		self.conn.search_ext2( base_dn, scope, filter, *parameters ).each do |entry|
+			branch = collectclass.new_from_entry( entry, self )
+			branch.include_operational_attrs = base.include_operational_attrs? if
+				base.respond_to?( :include_operational_attrs? )
+
+			if block_given?
+				results << yield( branch )
+			else
+				results << branch
 			end
-		else
-			return self.conn.search_ext2( base, scope, filter, *parameters ).
-				collect {|entry| collectclass.new_from_entry(entry, self) }
 		end
 
+		return results
 	rescue RuntimeError => err
 		conn = self.conn
 
@@ -347,9 +426,14 @@ class Treequel::Directory
 	### Modify the entry specified by the given +dn+ with the specified +mods+, which can be
 	### either an Array of LDAP::Mod objects or a Hash of attribute/value pairs.
 	def modify( branch, mods )
-		normattrs = self.normalize_attributes( mods )
-		self.log.debug "Modifying %s with attributes: %p" % [ branch.dn, normattrs ]
-		self.conn.modify( branch.dn, normattrs )
+		if mods.first.respond_to?( :mod_op )
+			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 )
+			self.log.debug "Modifying %s with: %p" % [ branch.dn, normattrs ]
+			self.conn.modify( branch.dn, normattrs )
+		end
 	end
 
 
@@ -368,7 +452,7 @@ class Treequel::Directory
 		# 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
+			values.flatten.uniq
 		end
 
 		normattrs = self.normalize_attributes( newattrs )
@@ -421,6 +505,25 @@ class Treequel::Directory
 	end
 
 
+	### Register the specified +modules+
+	def register_controls( *modules )
+		dse = self.conn.root_dse.first
+		supported_controls = dse['supportedControl']
+
+		modules.each do |mod|
+			oid = mod.const_get( :OID ) if mod.const_defined?( :OID )
+			raise NotImplementedError, "%s doesn't define an OID" % [ mod.name ] if oid.nil?
+
+			if supported_controls.include?( oid )
+				@registered_controls << mod
+			else
+				raise Treequel::UnsupportedControl,
+					"%s is not supported by %s" % [ mod.name, self.uri ]
+			end
+		end
+	end
+
+
 	### Map the specified +value+ to its Ruby datatype if one is registered for the given 
 	### syntax +oid+. If there is no conversion registered, just return the +value+ as-is.
 	def convert_syntax_value( oid, value )
@@ -435,6 +538,50 @@ class Treequel::Directory
 	end
 
 
+	### Return an Array of Symbols for the controls supported by the Directory, as listed
+	### in the directory's root DSE. Any controls which aren't known (i.e., don't have an
+	### entry in Treequel::Constants::CONTROL_NAMES), the numeric OID will be returned as-is.
+	def supported_controls
+		return self.supported_control_oids.collect {|oid| CONTROL_NAMES[oid] || oid }
+	end
+
+
+	### 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']
+	end
+
+
+	### Return an Array of Symbols for the extensions supported by the Directory, as listed
+	### in the directory's root DSE. Any extensions which aren't known (i.e., don't have an
+	### entry in Treequel::Constants::EXTENSION_NAMES), the numeric OID will be returned as-is.
+	def supported_extensions
+		return self.supported_extension_oids.collect {|oid| EXTENSION_NAMES[oid] || oid }
+	end
+
+
+	### 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']
+	end
+
+
+	### Return an Array of Symbols for the features supported by the Directory, as listed
+	### in the directory's root DSE. Any features which aren't known (i.e., don't have an
+	### entry in Treequel::Constants::FEATURE_NAMES), the numeric OID will be returned as-is.
+	def supported_features
+		return self.supported_feature_oids.collect {|oid| FEATURE_NAMES[oid] || oid }
+	end
+
+
+	### 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']
+	end
+
 
 	#########
 	protected
@@ -457,10 +604,10 @@ class Treequel::Directory
 			conn = LDAP::SSLConn.new( @host, @port, true )
 		when :ssl
 			self.log.debug "Connecting using SSL to %s:%d" % [ @host, @port ]
-			conn = LDAP::SSLConn.new( host, port )
+			conn = LDAP::SSLConn.new( @host, @port )
 		else
 			self.log.debug "Connecting using an unencrypted connection to %s:%d" % [ @host, @port ]
-			conn = LDAP::Conn.new( host, port )
+			conn = LDAP::Conn.new( @host, @port )
 		end
 
 		conn.set_option( LDAP::LDAP_OPT_PROTOCOL_VERSION, 3 )