treequel 1.0.4 → 1.1.0

data/lib/treequel/model.rb

@@ -0,0 +1,363 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'set'
+
+require 'treequel'
+require 'treequel/branch'
+require 'treequel/branchset'
+
+
+# An object interface to LDAP entries.
+class Treequel::Model < Treequel::Branch
+	include Treequel::Loggable,
+	        Treequel::Constants,
+	        Treequel::Normalization,
+	        Treequel::Constants::Patterns
+
+	require 'treequel/model/objectclass'
+
+
+	# A prototype Hash that autovivifies its members as Sets, for use in
+	# the objectclass_registry and the base_registry
+	SET_HASH = Hash.new {|h,k| h[k] = Set.new }
+
+
+	#################################################################
+	###	C L A S S   M E T H O D S
+	#################################################################
+
+	@objectclass_registry = SET_HASH.dup
+	@base_registry = SET_HASH.dup
+
+	class << self
+		attr_reader :objectclass_registry
+		attr_reader :base_registry
+	end
+
+
+	### Inheritance callback -- add a class-specific objectclass registry to inheriting classes.
+	### @param [Class] subclass  the inheriting class
+	def self::inherited( subclass )
+		super
+		subclass.instance_variable_set( :@objectclass_registry, SET_HASH.dup )
+		subclass.instance_variable_set( :@base_registry, SET_HASH.dup )
+	end
+
+
+	### Register the given +mixin+ for the specified +objectclasses+. Instances that 
+	### have all the specified +objectclasses+ will be extended with the +mixin+.
+	###
+	### @param [Module] mixin                 the mixin to be applied; it should be extended with 
+	###                                       Treequel::Model::ObjectClass.
+	def self::register_mixin( mixin )
+		objectclasses = mixin.model_objectclasses
+		bases = mixin.model_bases
+		bases << '' if bases.empty?
+
+		Treequel.logger.debug "registering %p [objectClasses: %p, base DNs: %p]" %
+			[ mixin, objectclasses, bases ]
+
+		# Register it with each of its objectClasses
+		objectclasses.each do |oc|
+			@objectclass_registry[ oc.to_sym ].add( mixin )
+		end
+
+		# ...and each of its bases
+		bases.each do |dn|
+			@base_registry[ dn.downcase ].add( mixin )
+		end
+	end
+
+
+	### Unregister the given +mixin+ for the specified +objectclasses+.
+	### @param [Module] mixin  the mixin that should no longer be applied
+	def self::unregister_mixin( mixin )
+		objectclasses = mixin.model_objectclasses
+		bases = mixin.model_bases
+		bases << '' if bases.empty?
+
+		Treequel.logger.debug "un-registering %p [objectclasses: %p, base DNs: %p]" %
+			[ mixin, objectclasses, bases ]
+
+		# Unregister it from each of its bases
+		bases.each do |dn|
+			@base_registry[ dn.downcase ].delete( mixin )
+		end
+
+		# ...and each of its objectClasses
+		objectclasses.each do |oc|
+			@objectclass_registry[ oc.to_sym ].delete( mixin )
+		end
+	end
+
+
+	### Return the mixins that should be applied to an entry with the given +objectclasses+.
+	### @param [Array<Symbol>] objectclasses  the objectclasses from the entry
+	### @return [Set<Module>] the Set of mixin modules which apply
+	def self::mixins_for_objectclasses( *objectclasses )
+		ocsymbols = objectclasses.flatten.collect {|oc| oc.untaint.to_sym }
+
+		# Get the union of all of the mixin sets for the objectclasses in question
+		mixins = self.objectclass_registry.
+			values_at( *ocsymbols ).
+			inject {|set1,set2| set1 | set2 }
+
+		# Return the mixins whose objectClass requirements are met by the 
+		# specified objectclasses
+		return mixins.delete_if do |mixin|
+			!mixin.model_objectclasses.all? {|oc| ocsymbols.include?(oc) }
+		end
+	end
+
+
+	### Return the mixins that should be applied to an entry with the given +dn+.
+	### @param [String] dn  the DN of the entry
+	### @return [Set<Module>] the Set of mixin modules which apply
+	def self::mixins_for_dn( dn )
+		dn_tuples = dn.downcase.split( /\s*,\s*/ )
+		dn_keys = dn_tuples.reverse.inject(['']) do |keys, dnpair|
+			dnpair += ',' + keys.last unless keys.last.empty?
+			keys << dnpair
+		end
+
+		# Get the union of all of the mixin sets for the DN and all of its parents
+		union = self.base_registry.
+			values_at( *dn_keys ).
+			inject {|set1,set2| set1 | set2 }
+
+		return union
+	end
+
+
+
+	#################################################################
+	###	I N S T A N C E   M E T H O D S
+	#################################################################
+
+	### Override the default to extend new instances with applicable mixins if their
+	### entry is set.
+	def initialize( *args )
+		super
+		self.apply_applicable_mixins( @dn, @entry ) if @entry
+	end
+
+
+	######
+	public
+	######
+
+	### Override Branch#search to inject the 'objectClass' attribute to the
+	### selected attribute list if there is one.
+	def search( scope=:subtree, filter='(objectClass=*)', parameters={}, &block )
+		parameters[:selectattrs] |= ['objectClass'] unless
+			!parameters.key?( :selectattrs ) || parameters[ :selectattrs ].empty?
+
+		super
+	end
+
+
+	### Returns +true+ if the receiver responds to the given method.
+	### @param [Symbol,String] sym  the name of the method to test for
+	### @return [Boolean]
+	def respond_to?( sym, include_priv=false )
+		return super if caller(1).first =~ %r{/spec/} &&
+			caller(1).first !~ /respond_to/ # RSpec workaround
+		return true if super
+		plainsym, _ = attribute_from_method( sym )
+		return self.find_attribute_type( plainsym ) ? true : false
+	end
+
+
+	### Return the Treequel::Model::ObjectClass mixins that have been applied to the receiver.
+	### @return [Array<Module>]
+	def extensions
+		eigenclass = ( class << self; self; end )
+		return eigenclass.included_modules.find_all do |mod|
+			(class << mod; self; end).include?(Treequel::Model::ObjectClass)
+		end
+	end
+
+
+	### Return a human-readable representation of the receiving object, suitable for debugging.
+	def inspect
+		return "#<%s:0x%x (%s)>" % [
+			self.class.name,
+			self.object_id * 2,
+			self.extensions.map( &:name ).join( ', ' )
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Search for the Treequel::Schema::AttributeType associated with +sym+.
+	### 
+	### @param [Symbol,String] name  the name of the attribute to find
+	### @return [Treequel::Schema::AttributeType,nil]  the associated attributeType, or nil
+	###                                                if there isn't one
+	def find_attribute_type( name )
+		attrtype = nil
+
+		# If the attribute doesn't match as-is, try the camelCased version of it
+		camelcased_sym = name.to_s.gsub( /_(\w)/ ) { $1.upcase }.to_sym
+		attrtype = self.valid_attribute_type( name ) ||
+		           self.valid_attribute_type( camelcased_sym )
+
+		return attrtype
+	end
+
+
+	### Proxy method -- Handle calls to missing methods by searching for an attribute.
+	def method_missing( sym, *args )
+
+		# First, if the entry hasn't yet been loaded, try loading it to make sure the 
+		# object is already extended with any applicable objectClass mixins. If that ends
+		# up defining the method in question, call it.
+		if !@entry && self.entry
+			meth = begin
+				self.method( sym )
+			rescue NoMethodError, NameError
+				nil
+			end
+			return meth.call( *args ) if meth
+		end
+
+		# Next, super to rdn-traversal if it looks like a reader but has arguments
+		plainsym, methodtype = attribute_from_method( sym )
+		return super if methodtype == :reader && !args.empty?
+
+		# Now make a method body for a new method based on what attributeType it is if 
+		# it's a valid attribute
+		attrtype = self.find_attribute_type( plainsym ) or return super
+		methodbody = case methodtype
+			when :writer
+				self.make_writer( attrtype )
+			when :predicate
+				self.make_predicate( attrtype )
+			else
+				self.make_reader( attrtype )
+			end
+
+		# Define the new method and call it by fetching the corresponding Method object
+		# so we don't loop back through #method_missing if something goes wrong
+		self.class.send( :define_method, sym, &methodbody )
+		return self.method( sym ).call( *args )
+	end
+
+
+	### Make a reader method body for the given +attrtype+.
+	###
+	### @param [Treequel::Mode::AttributeType] attrtype  the attributeType to create the reader
+	###                                                  for.
+	### @return [Proc]  the body of the reader method.
+	def make_reader( attrtype )
+		self.log.debug "Generating an attribute reader for %p" % [ attrtype ]
+		attrname = attrtype.name
+		return lambda {|*args|
+			if args.empty?
+				self[ attrname ]
+			else
+				self.traverse_branch( attrname, *args )
+			end
+		}
+	end
+
+
+	### Make a writer method body for the given +attrtype+.
+	###
+	### @param [Treequel::Mode::AttributeType] attrtype  the attributeType to create the accessor
+	###                                                  for.
+	### @return [Proc]  the body of the writer method.
+	def make_writer( attrtype )
+		self.log.debug "Generating an attribute writer for %p" % [ attrtype ]
+		attrname = attrtype.name
+		if attrtype.single?
+			self.log.debug "  attribute is SINGLE, so generating a scalar writer..."
+			return lambda {|newvalue| self[attrname] = newvalue }
+		else
+			self.log.debug "  attribute isn't SINGLE, so generating an array writer..."
+			return lambda {|*newvalues| self[attrname] = newvalues }
+		end
+	end
+
+
+	### Make a predicate method body for the given +attrtype+.
+	###
+	### @param [Treequel::Mode::AttributeType] attrtype  the attributeType to create the method
+	###                                                  for.
+	### @return [Proc]  the body of the predicate method.
+	def make_predicate( attrtype )
+		self.log.debug "Generating an attribute predicate for %p" % [ attrtype ]
+		attrname = attrtype.name
+		if attrtype.single?
+			self.log.debug "  attribute is SINGLE, so generating a scalar predicate..."
+			return lambda { self[attrname] ? true : false }
+		else
+			self.log.debug "  attribute isn't SINGLE, so generating an array predicate..."
+			return lambda { self[attrname].any? {|val| val} }
+		end
+	end
+
+
+	### Overridden to apply applicable mixins to lazily-loaded objects once their entry 
+	### has been looked up.
+	### @return [LDAP::Entry]  the fetched entry object
+	def lookup_entry
+		if entry = super
+			self.log.debug "  applying mixins to %p" % [ entry ]
+			self.apply_applicable_mixins( self.dn, entry )
+		end
+		return entry
+	end
+
+
+	### Apply mixins that are applicable considering the receiver's DN and the 
+	### objectClasses from its entry.
+	def apply_applicable_mixins( dn, entry )
+		ocs = entry.object_classes.collect do |explicit_oc|
+			explicit_oc.ancestors.collect {|oc| oc.name }
+		end.flatten.uniq
+
+		oc_mixins = self.class.mixins_for_objectclasses( *ocs )
+		dn_mixins = self.class.mixins_for_dn( dn )
+
+		# The applicable mixins are those in the intersection of the ones
+		# inferred by its objectclasses and those that apply to its DN
+		mixins = ( oc_mixins & dn_mixins )
+
+		self.log.debug "  %d mixins apply to %s: %p" % [ mixins.length, dn, mixins.to_a ]
+		mixins.each {|mod| self.extend(mod) }
+	end
+
+
+	#######
+	private
+	#######
+
+	### Given the symbol from an attribute accessor or predicate, return the
+	### name of the corresponding LDAP attribute/
+	### @param [Symbol] methodname  the method being called
+	### @return [Symbol] the attribute name that corresponds to the method
+	def attribute_from_method( methodname )
+
+		case methodname.to_s
+		when /^(?:has_)?([a-z]\w+)\?$/i
+			return $1.to_sym, :predicate
+		when /^([a-z]\w+)(=)?$/i
+			return $1.to_sym, ($2 ? :writer : :reader )
+		end
+	end
+
+
+	### Turn a String DN into a reversed set of DN attribute/value pairs
+	def make_dn_tuples( dn )
+		return dn.split( /\s*,\s*/ ).reverse
+	end
+
+end # class Treequel::Model
+
+
+

data/lib/treequel/monkeypatches.rb

@@ -26,4 +26,69 @@ class LDAP::Control
 end
 
 
+### Extensions to the Time class to add LDAP (RFC4517) Generalized Time syntax
+module Treequel::TimeExtensions
+
+	### Return +self+ as a String formatted as specified in RFC4517 
+	### (LDAP Generalized Time).
+	def ldap_generalized( fraction_digits=0 )
+		fractional_seconds =
+			if fraction_digits == 0
+				''
+			elsif fraction_digits <= 6
+				'.' + sprintf('%06d', usec)[0, fraction_digits]
+			else
+				'.' + sprintf('%06d', usec) + '0' * (fraction_digits - 6)
+			end
+		tz =
+			if self.utc?
+				'Z'
+			else
+				off  = utc_offset
+				sign = off < 0 ? '-' : '+'
+				"%s%02d%02d" % [ sign, *(off.abs / 60).divmod(60) ]
+			end
+
+		return "%02d%02d%02d%02d%02d%02d%s%s" % [
+			year,
+			mon,
+			day,
+			hour,
+			min,
+			sec,
+			fractional_seconds,
+			tz
+		]
+
+	end
+
+	### Returns +self+ as a String formatted as specified in RFC4517
+	### (UTC Time)
+	def ldap_utc
+		tz =
+			if utc?
+				'Z'
+			else
+				off  = utc_offset
+				sign = off < 0 ? '-' : '+'
+				"%s%02d%02d" % [ sign, *(off.abs / 60).divmod(60) ]
+			end
+
+		return "%02d%02d%02d%02d%02d%02d%s" % [
+			year.divmod(100).last,
+			mon,
+			day,
+			hour,
+			min,
+			sec,
+			tz
+		]
+	end
+
+end # module Treequel::TimeExtensions
+
+class Time
+	include Treequel::TimeExtensions
+end
+
 

data/lib/treequel/schema/attributetype.rb

@@ -28,6 +28,30 @@ class Treequel::Schema::AttributeType
 
 	extend Treequel::AttributeDeclarations
 
+	# Regex for splitting a syntax OID from its length specifier
+	OID_SPLIT_PATTERN = /
+		^
+		#{SQUOTE}?
+		(#{OID})					# OID = $1
+		#{SQUOTE}?
+		(?:
+			#{LCURLY}
+			(#{LEN})				# Length = $2
+			#{RCURLY}
+		)?$
+	/x
+
+	# The default USAGE type: "Usage of userApplications, the default,
+	# indicates that attributes of this type represent user information.
+	# That is, they are user attributes." (RFC4512)
+	DEFAULT_USAGE_TYPE = 'userApplications'.freeze
+
+	# A usage of directoryOperation, distributedOperation, or dSAOperation
+	# indicates that attributes of this type represent operational and/or
+	# administrative information.  That is, they are operational
+	# attributes. (RFC4512)
+	OPERATIONAL_ATTRIBUTE_USAGES = %w[directoryOperation distributedOperation dSAOperation].freeze
+
 
 	#############################################################
 	###	C L A S S   M E T H O D S
@@ -63,7 +87,7 @@ class Treequel::Schema::AttributeType
 			:single          => single,
 			:collective      => collective,
 			:user_modifiable => nousermod ? false : true,
-			:usagetype       => usagetype,
+			:usagetype       => usagetype || DEFAULT_USAGE_TYPE,
 			:extensions      => extensions
 		  )
 	end
@@ -92,7 +116,7 @@ class Treequel::Schema::AttributeType
 		@usagetype       = attributes[:usagetype]
 		@extensions      = attributes[:extensions]
 
-		@syntax_oid, @syntax_len = self.split_syntax_oid( attributes[:syntax_oid] ) if
+		@syntax_oid, @syntax_len = split_syntax_oid( attributes[:syntax_oid] ) if
 			attributes[:syntax_oid]
 
 		super()
@@ -147,6 +171,8 @@ class Treequel::Schema::AttributeType
 
 	# The application of this attributeType
 	attr_accessor :usagetype
+	alias_method :usage, :usagetype
+	alias_method :usage=, :usagetype=
 
 	# The attributeType's extensions (as a String)
 	attr_accessor :extensions
@@ -181,16 +207,43 @@ class Treequel::Schema::AttributeType
 	end
 
 
+	### Returns the attributeType as a String, which is the RFC4512-style schema
+	### description.
+	def to_s
+		parts = [ self.oid ]
+
+		parts << "NAME %s" % Treequel::Schema.qdescrs( self.names ) unless self.names.empty?
+
+		parts << "DESC '%s'" % [ self.desc ]           if self.desc
+		parts << "OBSOLETE"                            if self.obsolete?
+		parts << "SUP %s" % [ self.sup_oid ]           if self.sup_oid
+		parts << "EQUALITY %s" % [ self.eqmatch_oid ]  if self.eqmatch_oid
+		parts << "ORDERING %s" % [ self.ordmatch_oid ] if self.ordmatch_oid
+		parts << "SUBSTR %s" % [ self.submatch_oid ]   if self.submatch_oid
+		if self.syntax_oid
+			parts << "SYNTAX %s" % [ self.syntax_oid ]
+			parts.last << "{%d}" % [ self.syntax_len ] if self.syntax_len
+		end
+		parts << "SINGLE-VALUE"                        if self.is_single?
+		parts << "COLLECTIVE"                          if self.is_collective?
+		parts << "NO-USER-MODIFICATION"            unless self.is_user_modifiable?
+		parts << "USAGE %s" % [ self.usagetype ]       if self.usagetype
+		parts << self.extensions.strip             unless self.extensions.empty?
+
+		return "( %s )" % [ parts.join(' ') ]
+	end
+
+
 	### Return a human-readable representation of the object suitable for debugging
 	def inspect
-		return "#<%s:0x%0x %s(%s) %p %sSYNTAX: %p (length: %s)>" % [
+		return "#<%s:0x%0x %s(%s) %p %sSYNTAX: %s (length: %s)>" % [
 			self.class.name,
 			self.object_id / 2,
 			self.name,
 			self.oid,
 			self.desc,
 			self.is_single? ? '(SINGLE) ' : '',
-			self.syntax_oid,
+			self.syntax,
 			self.syntax_len ? self.syntax_len : 'unlimited',
 		]
 	end
@@ -247,21 +300,58 @@ class Treequel::Schema::AttributeType
 	end
 
 
-	#########
-	protected
-	#########
+	# Usage of userApplications, the default, indicates that attributes of
+	# this type represent user information.  That is, they are user
+	# attributes.
 
-	OID_SPLIT_PATTERN = /
-		^
-		#{SQUOTE}?
-		(#{OID})					# OID = $1
-		#{SQUOTE}?
-		(?:
-			#{LCURLY}
-			(#{LEN})				# Length = $2
-			#{RCURLY}
-		)?$
-	/x
+	### Test whether or not the attrinbute is a user applications attribute.
+	### @return [Boolean]  true if the attribute's USAGE is 'userApplications' (or nil)
+	def is_user?
+		return !self.is_operational?
+	end
+	alias_method :user?, :is_user?
+
+
+	### Test whether or not the attribute is an operational attribute.
+	### @return [Boolean]  true if the attribute's usage is one of the OPERATIONAL_ATTRIBUTE_USAGES
+	def is_operational?
+		usage_type = self.usage || DEFAULT_USAGE_TYPE
+		return OPERATIONAL_ATTRIBUTE_USAGES.map( &:downcase ).include?( usage_type.downcase )
+	end
+	alias_method :operational?, :is_operational?
+
+
+	### Test whether or not the attribute is a directory operational attribute.
+	### @return [Boolean]  true if the attribute's usage is 'directoryOperation'
+	def is_directory_operational?
+		usage_type = self.usage || DEFAULT_USAGE_TYPE
+		return usage_type == 'directoryOperation'
+	end
+	alias_method :directory_operational?, :is_directory_operational?
+
+
+	### Test whether or not the attribute is a distributed operational attribute.
+	### @return [Boolean]  true if the attribute's usage is 'distributedOperation'
+	def is_distributed_operational?
+		usage_type = self.usage || DEFAULT_USAGE_TYPE
+		return usage_type == 'distributedOperation'
+	end
+	alias_method :distributed_operational?, :is_distributed_operational?
+
+
+	### Test whether or not the attribute is a DSA-specific operational attribute.
+	### @return [Boolean]  true if the attribute's usage is 'dSAOperation'
+	def is_dsa_operational?
+		usage_type = self.usage || DEFAULT_USAGE_TYPE
+		return usage_type == 'dSAOperation'
+	end
+	alias_method :dsa_operational?, :is_dsa_operational?
+	alias_method :dsa_specific?, :is_dsa_operational?
+
+
+	#######
+	private
+	#######
 
 	### Split a numeric OID with an optional length qualifier into a numeric OID and length. If
 	### no length qualifier is present, it will be nil.

data/lib/treequel/schema/ldapsyntax.rb

@@ -69,6 +69,21 @@ class Treequel::Schema::LDAPSyntax
 	# The syntax's extensions (as a String)
 	attr_accessor :extensions
 
+	# SyntaxDescription = LPAREN WSP
+	# 	numericoid                 ; object identifier
+	# 	[ SP "DESC" SP qdstring ]  ; description
+	# 	extensions WSP RPAREN      ; extensions
+
+	### Returns the SyntaxDescription as a String, which is the RFC4512-style schema
+	### description.
+	def to_s
+		parts = [ self.oid ]
+		parts << "DESC '%s'" % [ self.desc ] if self.desc
+		parts << self.extensions.strip unless self.extensions.empty?
+
+		return "( %s )" % [ parts.join(' ') ]
+	end
+
 
 	### Return a human-readable representation of the object suitable for debugging
 	def inspect

data/lib/treequel/schema/matchingrule.rb

@@ -89,6 +89,30 @@ class Treequel::Schema::MatchingRule
 	end
 
 
+	# MatchingRuleDescription = LPAREN WSP
+	#	numericoid                 ; object identifier
+	#	[ SP "NAME" SP qdescrs ]   ; short names (descriptors)
+	#	[ SP "DESC" SP qdstring ]  ; description
+	#	[ SP "OBSOLETE" ]          ; not active
+	#	SP "SYNTAX" SP numericoid  ; assertion syntax
+	#	extensions WSP RPAREN      ; extensions
+
+	### Returns the matchingRule as a String, which is the RFC4512-style schema
+	### description.
+	def to_s
+		parts = [ self.oid ]
+
+		parts << "NAME %s" % Treequel::Schema.qdescrs( self.names ) unless self.names.empty?
+
+		parts << "DESC '%s'" % [ self.desc ]           if self.desc
+		parts << "OBSOLETE"                            if self.obsolete?
+		parts << "SYNTAX %s" % [ self.syntax_oid ]
+		parts << self.extensions.strip             unless self.extensions.empty?
+
+		return "( %s )" % [ parts.join(' ') ]
+	end
+
+
 	### Return a human-readable representation of the object suitable for debugging
 	def inspect
 		return "#<%s:0x%0x %s(%s) %s %sSYNTAX: %p>" % [

data/lib/treequel/schema/matchingruleuse.rb

@@ -90,6 +90,30 @@ class Treequel::Schema::MatchingRuleUse
 	end
 
 
+	# MatchingRuleUseDescription = LPAREN WSP
+	# 	numericoid                 ; object identifier
+	# 	[ SP "NAME" SP qdescrs ]   ; short names (descriptors)
+	# 	[ SP "DESC" SP qdstring ]  ; description
+	# 	[ SP "OBSOLETE" ]          ; not active
+	# 	SP "APPLIES" SP oids       ; attribute types
+	# 	extensions WSP RPAREN      ; extensions
+
+	### Returns the matchingRuleUse as a String, which is the RFC4512-style schema
+	### description.
+	def to_s
+		parts = [ self.oid ]
+
+		parts << "NAME %s" % Treequel::Schema.qdescrs( self.names ) unless self.names.empty?
+
+		parts << "DESC '%s'" % [ self.desc ]           if self.desc
+		parts << "OBSOLETE"                            if self.obsolete?
+		parts << "APPLIES %s" % [ Treequel::Schema.oids(self.attr_oids) ]
+		parts << self.extensions.strip             unless self.extensions.empty?
+
+		return "( %s )" % [ parts.join(' ') ]
+	end
+
+
 	### Return a human-readable representation of the object suitable for debugging
 	def inspect
 		return "#<%s:0x%0x %s(%s) %p -> %p >" % [