treequel 1.0.1 → 1.0.4

data/lib/treequel/control.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/ruby
+
+require 'ldap'
+require 'ldap/control'
+
+require 'treequel'
+
+
+# Virtual interface methods for Control modules.
+#
+# @abstract To make a concrete derivative, include this module in a module that
+#   implements either {#get_client_controls} or {#get_server_controls} and #each. 
+#   Your implementation of #each should +super+ with a block that does the 
+#   necessary extraction of the result controls and yields back to the original
+#   block.
+# 
+# @example
+#   module Treequel::MyControl
+#       include Treequel::Control
+#   
+#       # The control's OID
+#       OID = '1.3.6.1.4.1.984454.16.1'
+#   
+#       # If your control has some value associated with it, you can provide
+#       # an initializer to set up an instance variable or two.
+#       def initialize
+#           @my_control_value = 18
+#       end
+#   
+#       attr_accessor :my_control_value
+#   
+#       # This is the interface users will use to set values used in the control,
+#       # like so:
+#       #   branchset.controlled_somehow( value )
+#       def controlled_somehow( value )
+#           self.my_control_value = value
+#       end
+#   
+#       # This is overridden so you can fetch controls set by the server before
+#       # iterating. The #each in Treequel::Branchset will yield to this block
+#       # after performing a search.
+#       def each( &block )
+#           super do |branch|
+#               if my_control = branch.controls.find {|control| control.oid == OID }
+#                   server_control_value = my_control.decode
+#                   # ... do something with the returned server_control_value
+#               end
+#   
+#               block.call( branch )
+#           end
+#       end
+#   
+#       # This is how you inject your control into the search; Treequel::Branchset
+#       # will call this before running the search and add the results to its
+#       # server_controls. If you're implementing a client control, override
+#       # the #get_client_controls method instead. Be sure to super() so that any
+#       # controls registered before yours have a chance to add their objects too.
+#       def get_server_controls
+#           controls = super
+#           if self.my_control_value
+#               value = LDAP::Control.encode( self.my_control_value )
+#               controls << LDAP::Control.new( OID, value, true )
+#           end
+#   
+#           return controls
+#       end
+#   
+#   end
+# 
+module Treequel::Control
+
+	### Control API interface method.
+	###
+	### If your control is a client control, you should super() to this method
+	### and add your control (in the form of an LDAP::Control object) to the
+	### resulting Array before returning it.
+	def get_client_controls
+		return []
+	end
+
+
+	### Control API interface method.
+	###
+	### If your control is a server control, you should super() to this method
+	### and add your control (in the form of an LDAP::Control object) to the
+	### resulting Array before returning it.
+	def get_server_controls
+		return []
+	end
+
+end # module Treequel::Control
+
+# vim: set nosta noet ts=4 sw=4:
+
+

data/lib/treequel/controls/contentsync.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'ldap'
+require 'openssl'
+
+require 'treequel'
+require 'treequel/control'
+require 'treequel/constants'
+
+
+# A Treequel::Control module that implements the "Content Sync"
+# control (RFC 4533)
+# 
+# *NOTICE:* This control currently doesn't do anything, as it depends on 
+# Intermediate Responses, which the underlying Ruby-LDAP library doesn't 
+# support (yet). 
+# 
+# == Usage
+# 
+# As with all Controls, you must first register the control with the
+# Treequel::Directory object you're intending to search:
+#   
+#   dir = Treequel.directory( 'ldap://ldap.acme.com/dc=acme,dc=com' )
+#   dir.register_controls( Treequel::ContentSyncControl )
+# 
+# Once that's done, any Treequel::Branchset you create will have the #on_sync
+# method:
+# 
+#   # Build DHCP records out of all the hosts in the directory, then rebuild
+#   # everything when a host record changes.
+#   hosts = dir.filter( :ou => Hosts ).collection
+#   hosts.filter( :objectClass => :ipHost ).on_sync do ||
+#       # 
+#   end
+# 
+# @see http://deveiate.org/projects/Treequel/ticket/6  Ticket: Add support for 
+#      the RFC4533 Content Sync operation
+# 
+module Treequel::ContentSyncControl
+	include Treequel::Control,
+	        Treequel::Constants
+
+	# The control's OID
+	OID = CONTROL_OIDS[:sync]
+
+	# Sync mode constants (from RFC4533, section 2.2)
+	SYNC_MODE_REFRESH = 1
+	SYNC_MODE_REFRESH_AND_PERSIST = 3
+
+	### Add the requisite instance variables to including Branchsets.
+	def initialize
+		self.log.notice "The ContentSync control doesn't work yet -- it requires support for " +
+			"IntermediateResponses, which Ruby-LDAP doesn't do yet. " +
+			"See http://deveiate.org/projects/Treequel/ticket/6 for updates on the " +
+			"status of this."
+		@content_sync_callback = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The callback to call when results change
+	attr_accessor :content_sync_callback
+
+
+	### Clone the Branchset with a persistent change callback.
+	def on_sync( &callback )
+		newset = self.clone
+		newset.content_sync_callback = callback
+
+		return newset
+	end
+
+
+	### Override the Enumerable method to update the cookie value each time a page 
+	### is fetched.
+	def each( &block )
+		super do |branch|
+			self.log.debug "Looking for the sync control in controls: %p" % [ branch.controls ]
+			branch.controls.each do |control|
+				self.log.debug "  got a %s control: %p" % [
+					CONTROL_NAMES[control.oid],
+					control.decode,
+				]
+
+				case control.oid
+				when CONTROL_OIDS[:sync_state]
+					self.log.debug "  got a 'state' control"
+					block.call( branch )
+				when CONTROL_OIDS[:sync_done]
+					self.log.debug "  got a 'done' control"
+					break
+				else
+					self.log.info "  got an unexpected control (%p)" % [ control ]
+				end
+			end
+		end
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Make the ASN.1 string for the control value out of the given +mode+, 
+	### +cookie+, +reload_hint+.
+	def make_sync_control_value( mode, cookie, reload_hint )
+		# (http://tools.ietf.org/html/rfc4533#section-2.2):
+		# syncRequestValue ::= SEQUENCE {
+		#     mode ENUMERATED {
+		#         -- 0 unused
+		#         refreshOnly       (1),
+		#         -- 2 reserved
+		#         refreshAndPersist (3)
+		#     },
+		#     cookie     syncCookie OPTIONAL,
+		#     reloadHint BOOLEAN DEFAULT FALSE
+		# }
+		encoded_vals = [
+			OpenSSL::ASN1::Enumerated.new( SYNC_MODE_REFRESH_AND_PERSIST )
+		]
+		return OpenSSL::ASN1::Sequence.new( encoded_vals ).to_der
+	end
+
+
+	### Treequel::Control API -- Get a configured LDAP::Control object for this
+	### Branchset.
+	def get_server_controls
+		controls = super
+		value = self.make_sync_control_value( 1, '', false )
+		return controls << LDAP::Control.new( OID, value, true )
+	end
+
+end # module Treequel::ContentSyncControl
+

data/lib/treequel/controls/pagedresults.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'ldap'
+
+require 'treequel'
+require 'treequel/control'
+
+
+# A Treequel::Control module that implements the "LDAP Control Extension
+# for Simple Paged Results Manipulation" (RFC 2696).
+# 
+# == Usage
+# 
+# As with all Controls, you must first register the control with the
+# Treequel::Directory object you're intending to search:
+# 
+#   dir = Treequel.directory( 'ldap://ldap.acme.com/dc=acme,dc=com' )
+#   dir.register_controls( Treequel::PagedResultsControl )
+# 
+# Once that's done, any Treequel::Branchset you create will have the
+# #with_paged_results method that will allow you to specify the number
+# of results you wish to be returned per "page":
+# 
+#   # Fetch people in pages
+#   people = dir.ou( :People )
+#   paged_people = people.filter( :objectClass => :person ).with_paged_results( 25 )
+# 
+# The Branchset will also respond to #has_more_results?, which will
+# be true while there are additional pages to be fetched, or before
+# the search has taken place:
+# 
+#   # Display each set of 25, waiting for keypress between each set
+#   while paged_people.has_more_results?
+#       # do something with this set of 25 people...
+#   end
+#   
+module Treequel::PagedResultsControl
+	include Treequel::Control
+
+	# The control's OID
+	OID = '1.2.840.113556.1.4.319'
+
+	# The default number of results per page
+	DEFAULT_PAGE_SIZE = 100
+
+
+	### Add the control's instance variables to including Branchsets.
+	def initialize
+		@paged_results_cookie = ''
+		@paged_results_setsize = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The number of results per page
+	attr_accessor :paged_results_setsize
+
+	# The (opaque) cookie value that will be sent to the server on the next search.
+	attr_accessor :paged_results_cookie
+
+
+	### Clone the Branchset with a paged results control.
+	### @param [Fixnum] setsize  The size of each result set. If this is nil or 0, removes 
+	###                          paging from the Branchset.
+	### @return [Treequel::Branchset]  a clone of the receiver with paging set to +setsize+
+	def with_paged_results( setsize=DEFAULT_PAGE_SIZE )
+		self.log.warn "This control will likely not work in ruby-ldap versions " +
+			" <= 0.9.9. See http://code.google.com/p/ruby-activeldap/issues/" +
+			"detail?id=38 for details." if LDAP::PATCH_VERSION < 10
+
+		newset = self.clone
+
+		if setsize.nil? || setsize.zero?
+			newset.paged_results_setsize = nil
+		else
+			newset.paged_results_setsize = setsize
+		end
+
+		return newset
+	end
+
+
+	### Clone the Branchset without paging and return it.
+	### @return [Treequel::Branchset]  a clone of the receiver, stripped of its paging
+	def without_paging
+		copy = self.clone
+		copy.without_paging!
+		return copy
+	end
+
+
+	### Remove any paging control associated with the receiving Branchset.
+	### @return [void]
+	def without_paging!
+		self.paged_results_cookie = ''
+		self.paged_results_setsize = nil
+	end
+
+
+	### Returns +true+ if the first page of results has been fetched and there are
+	### more pages remaining.
+	### @return [Boolean]
+	def has_more_results?
+		return true unless self.done_paging?
+	end
+
+
+	### Returns +true+ if results have yet to be fetched, or if they have all been 
+	### fetched.
+	### @return [Boolean]
+	def done_paging?
+		return self.paged_results_cookie == ''
+	end
+
+
+	### Override the Enumerable method to update the cookie value each time a page 
+	### is fetched.
+	### @yieldparam [Treequel::Branch] branch  the branch that's a result of the search.
+	def each( &block )
+		super do |branch|
+			if paged_control = branch.controls.find {|control| control.oid == OID }
+				returned_size, cookie = paged_control.decode
+				self.log.debug "Paged control in result with size = %p, cookie = %p" %
+					[ returned_size, cookie ]
+				self.paged_results_cookie = cookie
+			else
+				self.log.debug "No paged control in results. Setting cookie to ''."
+				self.paged_results_cookie = ''
+			end
+
+			block.call( branch )
+		end
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Treequel::Control API -- Get the set of server controls currently configured for 
+	### the receiver.
+	### @return [Array<LDAP::Control>]  the configured controls
+	def get_server_controls
+		controls = super
+		if pagesize = self.paged_results_setsize && self.paged_results_setsize.nonzero?
+			self.log.debug "Setting up paging for sets of %d" % [ pagesize ]
+			value = LDAP::Control.encode( pagesize.to_i, self.paged_results_cookie.to_s )
+			controls << LDAP::Control.new( OID, value, true )
+		else
+			self.log.debug "No paging for this %p; not adding the PagedResults control" %
+				[ self.class ]
+		end
+
+		return controls
+	end
+
+end # module Treequel::PagedResultsControl
+

data/lib/treequel/controls/sortedresults.rb

@@ -0,0 +1,216 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'ldap'
+
+require 'treequel'
+require 'treequel/control'
+require 'treequel/sequel_integration'
+
+
+# A Treequel::Control module that implements the "LDAP Control Extension for Server 
+# Side Sorting of Search Results" (RFC 2891).
+# 
+# == Usage
+# 
+# As with all Controls, you must first register the control with the
+# Treequel::Directory object you're intending to search:
+#   
+#   dir = Treequel.directory( 'ldap://ldap.acme.com/dc=acme,dc=com' )
+#   dir.register_controls( Treequel::SortedResultsControl )
+# 
+# Once that's done, any Treequel::Branchset you create will have the
+# #order method that will allow you to specify one or more attributes by which the server
+# should sort results before returning them:
+# 
+#   # Fetch people sorted by their last name, then first name, then
+#   # by employeeNumber
+#   people = dir.ou( :People )
+#   sorted_people = people.filter( :objectClass => :person ).
+#       order( :sn, :givenName, :employeeNumber )
+module Treequel::SortedResultsControl
+	include Treequel::Control,
+	        Treequel::Constants
+
+	# The control's request OID
+	OID  = CONTROL_OIDS[:sortrequest]
+
+	# The control's response OID
+	RESPONSE_OID = CONTROL_OIDS[:sortresult]
+
+	# Descriptions of result codes
+	RESPONSE_RESULT_DESCRIPTIONS = {
+		# success                   (0), -- results are sorted
+		0 => 'Success',
+
+		# operationsError           (1), -- server internal failure
+		1 => 'Operations error; server internal failure',
+
+		# timeLimitExceeded         (3), -- timelimit reached before
+		#                                -- sorting was completed
+		3 => 'Time limit reached before sorting was completed',
+
+		# strongAuthRequired        (8), -- refused to return sorted
+		#                                -- results via insecure
+		#                                -- protocol
+		8 => 'Stronger auth required: refusing to return sorted results via insecure protocol',
+
+		# adminLimitExceeded       (11), -- too many matching entries
+		#                                -- for the server to sort
+		11 => 'Admin limit exceeded: too many matching entries for the server to sort',
+
+		# noSuchAttribute          (16), -- unrecognized attribute
+		#                                -- type in sort key
+		16 => 'No such attribute',
+
+		# inappropriateMatching    (18), -- unrecognized or
+		#                                -- inappropriate matching
+		#                                -- rule in sort key
+		18 => 'Inappropriate matching: unrecognized or inappropriate matching rule in sort key',
+
+		# insufficientAccessRights (50), -- refused to return sorted
+		#                                -- results to this client
+		50 => 'Insufficient access rights: refusing to return sorted results to this client',
+
+		# busy                     (51), -- too busy to process
+		51 => 'Busy: too busy to process',
+
+		# unwillingToPerform       (53), -- unable to sort
+		52 => 'Unwilling to perform: unable to sort',
+
+		# other                    (80)
+		80 => 'Other: non-specific result code (80)',
+	}
+
+
+	# A struct for tracking sorting criteria
+	Criterion = Struct.new( 'SortedResultsControlCriterion', :type, :ordering_rule, :reverse_order )
+
+
+	### Add the requisite instance variables to including Branchsets.
+	def initialize
+		self.log.debug "initializing %p" % [ self ]
+		@sort_order_criteria = []
+	end
+
+
+	######
+	public
+	######
+
+	# The ordering criteria, if any
+	attr_accessor :sort_order_criteria
+
+
+	### Clone the Branchset with a server-side sorted results control added and return it.
+	def order( *attributes )
+		self.log.warn "This control will likely not work in ruby-ldap versions " +
+			" <= 0.9.9. See http://code.google.com/p/ruby-activeldap/issues/" +
+			"detail?id=38 for details." if LDAP::PATCH_VERSION < 10
+
+		if attributes.flatten.empty?
+			self.log.debug "cloning %p with no order" % [ self ]
+			return self.unordered
+		else
+			criteria = attributes.collect do |attrspec|
+				case attrspec
+				when Symbol
+					Criterion.new( attrspec.to_s )
+
+				when Sequel::SQL::Expression
+					Criterion.new( attrspec.expression.to_s, nil, attrspec.descending )
+
+				else
+					raise ArgumentError,
+						"unsupported order specification type %s" % [ attrspec.class.name ]
+				end
+			end
+
+			self.log.debug "cloning %p with order criteria: %p" % [ self, criteria ]
+			copy = self.clone
+			copy.sort_order_criteria += criteria
+
+			return copy
+		end
+	end
+
+
+	### Clone the Branchset without a server-side sorted results control and return it.
+	def unordered
+		copy = self.clone
+		copy.unordered!
+		return copy
+	end
+
+
+	### Remove any server-side sorted results control associated with the receiving 
+	### Branchset, returning any removed criteria as an Array.
+	def unordered!
+		return self.sort_order_criteria.slice!( 0..-1 )
+	end
+
+
+	### Override the Enumerable method to update the cookie value each time a page 
+	### is fetched.
+	def each( &block )
+		super do |branch|
+			if sorted_control = branch.controls.find {|control| control.oid == RESPONSE_OID }
+				sortResult, attributeType = sorted_control.decode
+				if sortResult.nonzero?
+					self.log.error "got non-zero response code for sort: %d (%s)" %
+						[ sortResult, RESPONSE_RESULT_DESCRIPTIONS[sortResult] ]
+					raise Treequel::ControlError, RESPONSE_RESULT_DESCRIPTIONS[sortResult]
+				else
+					self.log.debug "got 'success' sort response code."
+				end
+			end
+
+			block.call( branch )
+		end
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Make the ASN.1 string for the control value out of the given +mode+, 
+	### +cookie+, +reload_hint+.
+	def make_sorted_control_value( sort_criteria )
+
+		### (http://tools.ietf.org/html/rfc2891#section-1.1):
+	    # SortKeyList ::= SEQUENCE OF SEQUENCE {
+	    #              attributeType   AttributeDescription,
+	    #              orderingRule    [0] MatchingRuleId OPTIONAL,
+	    #              reverseOrder    [1] BOOLEAN DEFAULT FALSE }
+		encoded_vals = sort_criteria.collect do |criterion|
+			seq = []
+			seq << OpenSSL::ASN1::OctetString.new( criterion.type )
+			seq << OpenSSL::ASN1::ObjectId.new( criterion.ordering_rule ) if criterion.ordering_rule
+			seq << OpenSSL::ASN1::Boolean.new( true ) if criterion.reverse_order
+			OpenSSL::ASN1::Sequence.new( seq )
+		end
+
+		return OpenSSL::ASN1::Sequence.new( encoded_vals ).to_der
+	end
+
+
+	### Treequel::Control API -- Get a configured LDAP::Control object for this
+	### Branchset.
+	def get_server_controls
+		controls = super
+		criteria = self.sort_order_criteria
+
+		if criteria.empty?
+			self.log.debug "No sort order criteria; skipping the server-side sort control"
+		else
+			self.log.debug "Found %d sort order criteria; generating a server-side sort control" %
+				[ criteria.length ]
+			asn1_string = self.make_sorted_control_value( criteria )
+			controls << LDAP::Control.new( OID, asn1_string, true )
+		end
+
+		return controls
+	end
+
+end