ldaptic 0.2.0

data/lib/ldaptic/error_set.rb

@@ -0,0 +1,34 @@
+module Ldaptic
+  class ErrorSet < Hash
+    def initialize(base)
+      @base = base
+      super() { |h, k| h[k] = [] }
+    end
+
+    def add(attribute, message)
+      self[attribute] << message
+    end
+
+    def each
+      each_key do |attribute|
+        self[attribute].each do |message|
+          yield attribute, message
+        end
+      end
+    end
+
+    def full_messages
+      map do |attribute, message|
+        "#{@base.class.human_attribute_name(attribute)} #{message}"
+      end
+    end
+
+    def to_a
+      full_messages
+    end
+
+    def size
+      full_messages.size
+    end
+  end
+end

data/lib/ldaptic/errors.rb

@@ -0,0 +1,136 @@
+module Ldaptic
+
+  class Error < ::RuntimeError
+  end
+
+  class EntryNotSaved < Error
+  end
+
+  # All server errors are instances of this class.  The error message and error
+  # code can be accessed with <tt>exception.message</tt> and
+  # <tt>exception.code</tt> respectively.
+  class ServerError < Error
+    attr_accessor :code
+  end
+
+  # The module houses all subclasses of Ldaptic::ServerError.  The methods
+  # contained within are for internal use only.
+  module Errors
+
+    #{
+    #  0=>"Success",
+    #  1=>"Operations error",
+    #  2=>"Protocol error",
+    #  3=>"Time limit exceeded",
+    #  4=>"Size limit exceeded",
+    #  5=>"Compare False",
+    #  6=>"Compare True",
+    #  7=>"Authentication method not supported"
+    #  8=>"Strong(er) authentication required",
+    #  9=>"Partial results and referral received",
+    #  10=>"Referral",
+    #  11=>"Administrative limit exceeded",
+    #  12=>"Critical extension is unavailable",
+    #  13=>"Confidentiality required",
+    #  14=>"SASL bind in progress",
+    #  16=>"No such attribute",
+    #  17=>"Undefined attribute type",
+    #  18=>"Inappropriate matching",
+    #  19=>"Constraint violation",
+    #  20=>"Type or value exists",
+    #  21=>"Invalid syntax",
+    #  32=>"No such object",
+    #  33=>"Alias problem",
+    #  34=>"Invalid DN syntax",
+    #  35=>"Entry is a leaf",
+    #  36=>"Alias dereferencing problem",
+    #  47=>"Proxy Authorization Failure",
+    #  48=>"Inappropriate authentication",
+    #  49=>"Invalid credentials",
+    #  50=>"Insufficient access",
+    #  51=>"Server is busy",
+    #  52=>"Server is unavailable",
+    #  53=>"Server is unwilling to perform",
+    #  54=>"Loop detected",
+    #  64=>"Naming violation",
+    #  65=>"Object class violation",
+    #  66=>"Operation not allowed on non-leaf",
+    #  67=>"Operation not allowed on RDN",
+    #  68=>"Already exists",
+    #  69=>"Cannot modify object class",
+    #  70=>"Results too large",
+    #  71=>"Operation affects multiple DSAs",
+    #  80=>"Internal (implementation specific) error",
+    #  81=>"Can't contact LDAP server",
+    #  82=>"Local error",
+    #  83=>"Encoding error",
+    #  84=>"Decoding error",
+    #  85=>"Timed out",
+    #  86=>"Unknown authentication method",
+    #  87=>"Bad search filter",
+    #  88=>"User cancelled operation",
+    #  89=>"Bad parameter to an ldap routine",
+    #  90=>"Out of memory",
+    #  91=>"Connect error",
+    #  92=>"Not Supported",
+    #  93=>"Control not found",
+    #  94=>"No results returned",
+    #  95=>"More results to return",
+    #  96=>"Client Loop",
+    #  97=>"Referral Limit Exceeded",
+    #}
+
+    # Error code 32.
+    class NoSuchObject < ServerError
+    end
+
+    # Error code 5.
+    class CompareFalse < ServerError
+    end
+    # Error code 6.
+    class CompareTrue < ServerError
+    end
+
+    EXCEPTIONS = {
+      32 => NoSuchObject,
+      5  => CompareFalse,
+      6  => CompareTrue
+    }
+
+    class << self
+
+      # Provides a backtrace minus all files shipped with Ldaptic.
+      def application_backtrace
+        dir = File.dirname(File.dirname(__FILE__))
+        c = caller
+        c.shift while c.first[0,dir.length] == dir
+        c
+      end
+
+      # Raise an exception (object only, no strings or classes) with the
+      # backtrace stripped of all Ldaptic files.
+      def raise(exception)
+        exception.set_backtrace(application_backtrace)
+        Kernel.raise exception
+      end
+
+      def for(code, message = nil) #:nodoc:
+        message ||= "Unknown error #{code}"
+        klass = EXCEPTIONS[code] || ServerError
+        exception = klass.new(message)
+        exception.code = code
+        exception
+      end
+
+      # Given an error code and a message, raise an Ldaptic::ServerError unless
+      # the code is zero.  The right subclass is selected automatically if it
+      # is available.
+      def raise_unless_zero(code, message = nil)
+        raise self.for(code, message) unless code.zero?
+      end
+
+    end
+
+  end
+
+end

data/lib/ldaptic/escape.rb

@@ -0,0 +1,110 @@
+module Ldaptic
+
+  # Encode an object with LDAP semantics.  Generally this is just to_s, but
+  # dates and booleans get special treatment.
+  #
+  # If a symbol is passed in, underscores are replaced by dashes, aiding in
+  # bridging the gap between LDAP and Ruby conventions.
+  def self.encode(value)
+    if value.respond_to?(:utc)
+      value.dup.utc.strftime("%Y%m%d%H%M%S") + ".%06dZ" % value.usec
+    elsif [true, false].include?(value)
+      value.to_s.upcase
+    elsif value.respond_to?(:dn)
+      value.dn.dup
+    elsif value.kind_of?(Symbol)
+      value.to_s.gsub('_', '-')
+    else
+      value.to_s.dup
+    end
+  end
+
+  # Escape a string for use in an LDAP filter, or in a DN.  If the second
+  # argument is +true+, asterisks are not escaped.
+  #
+  # If the first argument is not a string, it is handed off to LDAP::encode.
+  def self.escape(string, allow_asterisks = false)
+    string = Ldaptic.encode(string)
+    enc = lambda { |l| "\\%02X" % l.ord }
+    string.gsub!(/[()\\\0-\37"+,;<>]/, &enc)
+    string.gsub!(/\A[# ]| \Z/, &enc)
+    if allow_asterisks
+      string.gsub!('**', '\\\\2A')
+    else
+      string.gsub!('*', '\\\\2A')
+    end
+    string
+  end
+
+  def self.unescape(string)
+    dest = ""
+    string = string.strip # Leading and trailing whitespace MUST be encoded
+    if string[0,1] == "#"
+      [string[1..-1]].pack("H*")
+    else
+      backslash = nil
+      string.each_byte do |byte|
+        case backslash
+        when true
+          char = byte.chr
+          if ('0'..'9').include?(char) || ('a'..'f').include?(char.downcase)
+            backslash = char
+          else
+            dest << byte
+            backslash = nil
+          end
+
+        when String
+          dest << (backslash << byte).to_i(16)
+          backslash = nil
+
+        else
+          backslash = nil
+          if byte == 92 # ?\\
+            backslash = true
+          else
+            dest << byte
+          end
+        end
+      end
+      dest
+    end
+  end
+
+  # Split on a given character where it is not escaped.  Either an integer or
+  # string represenation of the character may be used.
+  #
+  #   Ldaptic.split("a*b", '*')    # => ["a","b"]
+  #   Ldaptic.split("a\\*b", '*')  # => ["a\\*b"]
+  #   Ldaptic.split("a\\\\*b", ?*) # => ["a\\\\","b"]
+  def self.split(string, character)
+    return [] if string.empty?
+    array = [""]
+    character = character.to_str.ord if character.respond_to?(:to_str)
+    backslash = false
+
+    string.each_byte do |byte|
+      if backslash
+        array.last << byte
+        backslash = false
+      elsif byte == 92 # ?\\
+        array.last << byte
+        backslash = true
+      elsif byte == character
+        array << ""
+      else
+        array.last << byte
+      end
+    end
+    array
+  end
+
+end
+
+class String
+  unless method_defined?(:ord)
+    def ord
+      self[0].to_i
+    end
+  end
+end

data/lib/ldaptic/filter.rb

@@ -0,0 +1,282 @@
+require 'ldaptic/escape'
+
+module Ldaptic
+
+  # If the argument is already a valid Ldaptic::Filter object, return it
+  # untouched.  Otherwise, pass it to the appropriate constructer of the
+  # appropriate subclass.
+  #
+  #   Ldaptic::Filter("(cn=Wu*)").to_s        #=> '(cn=Wu*)'
+  #   Ldaptic::Filter({:cn=>"Wu*"}).to_s      #=> '(cn=Wu\2A)'
+  #   Ldaptic::Filter(["(cn=?*)","Wu*"]).to_s #=> '(cn=Wu\2A*)'
+  def self.Filter(argument)
+    case argument
+    when Filter::Abstract then argument
+    when [],nil then nil
+    when Array  then Filter::Array    .new(argument)
+    when Hash   then Filter::Hash     .new(argument)
+    when String then Filter::String   .new(argument)
+    when Symbol then Filter::Attribute.new(argument)
+    when Proc, Method
+      Ldaptic::Filter(if argument.arity > 0
+        argument.call(Filter::Spawner)
+      elsif Filter::Spawner.respond_to?(:instance_exec)
+        Filter::Spawner.instance_exec(&argument)
+      else
+        Filter::Spawner.instance_eval(&argument)
+      end)
+    else raise TypeError, "Unknown LDAP Filter type", caller
+    end
+  end
+
+  # See Ldaptic.Filter for the contructor and Ldaptic::Filter::Abstract for
+  # methods common to all filters.
+  #
+  # Useful subclasses include String, Array, and Hash.
+  module Filter
+
+    # The filter class from which all others derive.
+    class Abstract
+
+      # Combine two filters with a logical AND.
+      def &(other)
+        And.new(self, other)
+      end
+
+      # Combine two filters with a logical OR.
+      def |(other)
+        Or.new(self, other)
+      end
+
+      # Negate a filter.
+      #
+      #   ~Ldaptic::Filter("(a=1)").to_s # => "(!(a=1))"
+      def ~
+        Not.new(self)
+      end
+
+      # Generates the filter as a string.
+      def to_s
+        process || "(objectClass=*)"
+      end
+
+      alias to_str to_s
+
+      def inspect
+        if string = process
+          "#<#{Ldaptic::Filter.inspect} #{string}>"
+        else
+          "#<#{Ldaptic::Filter.inspect} invalid>"
+        end
+      end
+
+      def to_net_ldap_filter #:nodoc:
+        Net::LDAP::Filter.construct(process)
+      end
+
+      def to_ber #:nodoc:
+        to_net_ldap_filter.to_ber
+      end
+
+    end
+
+    module Spawner # :nodoc:
+      def self.method_missing(method)
+        Attribute.new(method)
+      end
+    end
+
+    class Attribute < Abstract
+      def initialize(name)
+        if name.kind_of?(Symbol)
+          name = name.to_s.tr('_-', '-_')
+        end
+        @name = name
+      end
+      %w(== =~ >= <=).each do |method|
+        define_method(method) do |other|
+          Pair.new(@name, other, method)
+        end
+      end
+      def process
+        "(#{@name}=*)"
+      end
+    end
+
+    # This class is used for raw LDAP queries.  Note that the outermost set of
+    # parentheses *must* be used.
+    #
+    #   Ldaptic::Filter("a=1")   # Wrong
+    #   Ldaptic::Filter("(a=1)") # Correct
+    class String < Abstract
+
+      def initialize(string) #:nodoc:
+        @string = string
+      end
+
+      # Returns the original string
+      def process
+        @string
+      end
+
+    end
+
+    # Does ? parameter substitution.
+    #
+    #   Ldaptic::Filter(["(cn=?*)", "Sm"]).to_s #=> "(cn=Sm*)"
+    class Array < Abstract
+      def initialize(array) #:nodoc:
+        @template = array.first
+        @parameters = array[1..-1]
+      end
+      def process
+        parameters = @parameters.dup
+        string = @template.gsub('?') { Ldaptic.escape(parameters.pop) }
+      end
+    end
+
+    # Used in the implementation of Ldaptic::Filter::And and
+    # Ldaptic::Filter::Or.  For internal use only.
+    class Join < Abstract
+      def initialize(operator, *args) #:nodoc:
+        @array = [operator] + args.map {|arg| Ldaptic::Filter(arg)}
+      end
+      def process
+        "(#{@array*''})" if @array.compact.size > 1
+      end
+      def to_net_ldap_filter #:nodoc
+        @array[1..-1].inject {|m, o| m.to_net_ldap_filter.send(@array.first, o.to_net_ldap_filter)}
+      end
+    end
+
+    class And < Join
+      def initialize(*args)
+        super(:&, *args)
+      end
+    end
+
+    class Or < Join
+      def initialize(*args)
+        super(:|, *args)
+      end
+    end
+
+    class Not < Abstract
+      def initialize(object)
+        @object = Ldaptic::Filter(object)
+      end
+      def process
+        process = @object.process and "(!#{process})"
+      end
+      def to_net_ldap_filter #:nodoc:
+        ~ @object.to_net_ldap_filter
+      end
+    end
+
+    # A hash is the most general and most useful type of filter builder.
+    #
+    #   Ldaptic::Filter(
+    #     :givenName => "David",
+    #     :sn! => "Thomas",
+    #     :postalCode => (70000..80000)
+    #   ).to_s # => "(&(givenName=David)(&(postalCode>=70000)(postalCode<=80000))(!(sn=Thomas)))"
+    #
+    # Including :* => true allows asterisks to pass through unaltered.
+    # Otherwise, they are escaped.
+    #
+    #    Ldaptic::Filter(:givenName => "Dav*", :* => true).to_s # => "(givenName=Dav*)"
+    class Hash < Abstract
+
+      attr_accessor :escape_asterisks
+      attr_reader   :hash
+      # Call Ldaptic::Filter(hash) instead of instantiating this class
+      # directly.
+      def initialize(hash)
+        @hash = hash.dup
+        @escape_asterisks = !@hash.delete(:*)
+      end
+
+      def process
+        string = @hash.map {|k, v| [k.to_s, v]}.sort.map do |(k, v)|
+          Pair.new(k, v, @escape_asterisks ? "==" : "=~").process
+        end.join
+        case @hash.size
+        when 0 then nil
+        when 1 then string
+        else "(&#{string})"
+        end
+      end
+    end
+
+    # Internal class used to process a single entry from a hash.
+    class Pair < Abstract
+      INVERSE_OPERATORS = {
+        "!=" => "==",
+        "!~" => "=~",
+        ">"  => "<=",
+        "<"  => ">="
+      }
+      def initialize(key, value, operator)
+        @key, @value, @operator = key.to_s.dup, value, operator.to_s
+        @inverse = !!@key.sub!(/!$/, '')
+        if op = INVERSE_OPERATORS[@operator]
+          @inverse ^= true
+          @operator = op
+        end
+      end
+
+      def process
+        k = @key
+        v = @value
+        if @operator == "=~"
+          operator = "=="
+          star = true
+        else
+          operator = @operator
+          star = false
+        end
+        inverse = @inverse
+        operator = "=" if operator == "=="
+        if v.respond_to?(:to_ary)
+          q = "(|" + v.map {|e| "(#{Ldaptic.encode(k)}=#{Ldaptic.escape(e, star)})"}.join + ")"
+        elsif v.kind_of?(Range)
+          q = []
+          if v.first != -1.0/0
+            q << "(#{Ldaptic.encode(k)}>=#{Ldaptic.escape(v.first, star)})"
+          end
+          if v.last != 1.0/0
+            if v.exclude_end?
+              q << "(!(#{Ldaptic.encode(k)}>=#{Ldaptic.escape(v.last, star)}))"
+            else
+              q << "(#{Ldaptic.encode(k)}<=#{Ldaptic.escape(v.last, star)})"
+            end
+          end
+          q = "(&#{q*""})"
+        elsif v == true || v == :*
+          q = "(#{Ldaptic.encode(k)}=*)"
+        elsif !v
+          q = "(#{Ldaptic.encode(k)}=*)"
+          inverse ^= true
+        else
+          q = "(#{Ldaptic.encode(k)}#{operator}#{Ldaptic.escape(v, star)})"
+        end
+        inverse ? "(!#{q})" : q
+      end
+    end
+
+    module Conversions #:nodoc:
+      def to_ldap_filter
+        Ldaptic::Filter(self)
+      end
+    end
+
+  end
+
+end
+
+class Hash
+  include Ldaptic::Filter::Conversions
+end
+class String
+  include Ldaptic::Filter::Conversions
+end