ldaptic 0.2.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Tim Pope
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,104 @@
+= Ldaptic
+
+This is an object-oriented LDAP wrapper library I started back in 2007 but
+only recently polished up and released.  It's unique in that it creates a
+class hierarchy (in a namespace your provide) that exactly mirrors the class
+hierarchy on the server.  For example, on a typical server, you'll get an
++InetOrgPerson+ class which inherits from +OrganizationalPerson+ which
+inherits from +Person+ which inherits from +Top+.  You can reopen any of these
+classes to add additional client side behavior.
+
+Ldaptic started as mainly a tool to interact with my company's Active
+Directory server, and I lost interest in it when I left that job.  Recently,
+I've become motivated to work on it again, as some of the blocking issues I
+faced are now potentially solvable with Active Model.
+
+== Getting Started
+
+You need to have either the ruby-ldap or net-ldap gem installed.  The former
+is preferred because it's faster native C.  Ldaptic is configured by including
+a dynamically created module into a namespace of your choosing.
+
+  module Example
+    include Ldaptic::Module(
+      :adapter => :ldap_conn,
+      :base => 'ou=Users,dc=example,dc=com',
+      :host => 'example.com',
+      :username => 'cn=admin,ou=Users,dc=example,dc=com',
+      :password => 'password'
+    )
+  end
+
+The adapter field can usually be omitted as it defaults to :ldap_conn or
+:net_ldap, based on which of the above two gems can be found (though you might
+want to use the :active_directory adapter, which depends on ruby-ldap,
+instead).  If the base is omitted, it will use the first naming context on the
+server (usually what you want).
+
+Entries are retrieved using the search method.  Named parameters include
+:base, :filter, :sort, :limit, :scope, and :attributes.  All are optional.
+
+  entries = Example.search(
+    :filter => {:objectClass => 'inetOrgPerson'}
+    :sort => :cn,
+    :limit => 10
+  )
+
+A Ruby class is created for each objectClass defined on the server.  Entries
+are instances of these classes.
+
+  >> entry = Example.find('cn=admin,ou=Users,dc=example,dc=com')
+  => #<Example::InetOrgPerson cn=admin,ou=Users,dc=example,dc=com ...>
+  >> entry.class.superclass
+  => Example::OrganizationalPerson
+
+Predictably, entries have attribute readers and writers.
+
+  >> entry.cn
+  => <["admin"]>
+  >> entry.cn = "root"
+  >> entry[:cn]
+  => <["root"]>
+  >> entry[:cn] = "admin"
+
+The returned object is an attribute set and behaves similar to an array.  Some
+attributes are marked by the server as "single value;" those will return the
+first element on method access but an attribute set on indexing access, for
+programmatic convenience.
+
+  >> entry.uidNumber
+  => 0
+  >> entry[:uidNumber]
+  => <[0]>
+
+The indexing syntax can also be used to create and fetch children.
+
+  >> users
+  => #<Example::OrganizationalUnit ou=Users,dc=example,dc=com ...>
+  >> users[:cn=>'admin'] = Example::InetOrgPerson.new
+  => #<Example::InetOrgPerson cn=admin,ou=Users,dc=example,dc=com ...>
+  >> users[:cn=>'admin']
+  => #<Example::InetOrgPerson cn=admin,ou=Users,dc=example,dc=com ...>
+
+Entries also implement many of the standard methods you've come to expect in
+an Active Record world (save, valid?, errors, to_param, attributes, ...).
+In fact, it is fully Active Model compliant.
+
+For more information, see in particular Ldaptic::Methods (for namespace
+methods like search), Ldaptic::Entry, and Ldaptic::AttributeSet.
+
+== To Do
+
+* Verify everything still works.  The tests take care of much of this, but
+  there are no integration tests for the adapters.  In particular, I have no
+  way to verify the Active Directory adapter still works.
+
+* The test suite (reflecting my fledgling testing abilities from 2007) is more
+  smoke test than BDD.  Perhaps switch to RSpec in the quest to rectify this.
+
+* Potential new features (mostly along the lines of "make it more like Active
+  Record") are in the GitHub issue tracker.  Vote for and comment on the ones
+  you would find useful, as most are on hold until someone has a real use
+  case.
+
+* Pick a better name?  Ldaptic has an ambiguous spelling.

data/Rakefile

@@ -0,0 +1,41 @@
+begin
+  require 'rubygems'
+rescue LoadError
+end
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = Dir['test/*_test.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.add('README.rdoc', 'lib')
+  rdoc.main     = 'README.rdoc'
+  rdoc.title    = 'Ldaptic'
+  rdoc.options << '--inline-source'
+  rdoc.options << '-d' if `which dot` =~ /\/dot/
+end
+
+spec = eval(File.read(File.join(File.dirname(__FILE__), 'ldaptic.gemspec')))
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.test_files = Dir['test/*_test.rb']
+    t.verbose = true
+    t.rcov_opts << "--exclude '/(rcov|net-ldap|i18n|active(?:support|model))-'"
+  end
+rescue LoadError
+end

data/lib/ldaptic.rb

@@ -0,0 +1,151 @@
+#!/usr/bin/env ruby
+
+require 'ldaptic/dn'
+require 'ldaptic/filter'
+require 'ldaptic/errors'
+require 'ldaptic/schema'
+require 'ldaptic/syntaxes'
+require 'ldaptic/adapters'
+require 'ldaptic/entry'
+require 'ldaptic/methods'
+
+# = Getting started
+#
+# See the methods of the Ldaptic module (below) for information on connecting.
+#
+# See the Ldaptic::Methods module for information on searching with your
+# connection object.
+#
+# Search results are Ldaptic::Entry objects.  See the documentation for this
+# class for information on manipulating and updating them, as well as creating
+# new entries.
+module Ldaptic
+
+  SCOPES = {
+    :base     => 0, # ::LDAP::LDAP_SCOPE_BASE,
+    :onelevel => 1, # ::LDAP::LDAP_SCOPE_ONELEVEL,
+    :subtree  => 2  # ::LDAP::LDAP_SCOPE_SUBTREE
+  }
+
+  # Default logger.  If none given, creates a new logger on $stderr.
+  def self.logger
+    unless @logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        return Rails.logger
+      else
+        require 'logger'
+        @logger = Logger.new($stderr)
+        @logger.level = Logger::WARN
+      end
+    end
+    @logger
+  end
+
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  # Returns an object that can be assigned directly to a variable.  This allows
+  # for an "anonymous" Ldaptic object.
+  #   @my_company = Ldaptic::Object(options)
+  #   @my_company::User.class_eval do
+  #     alias login sAMAccountName
+  #   end
+  def self.Object(options={}, &block)
+    base = ::Module.new do
+      include Ldaptic::Module(options)
+    end
+    if block_given?
+      base.class_eval(&block)
+    end
+    base
+  end
+
+  # Similar to Ldaptic::Class, accepting the same options.  Instead of
+  # returning an anonymous class that activates upon inheritance, it returns an
+  # anonymous module that activates upon inclusion.
+  #   module MyCompany
+  #     include Ldaptic::Module(options)
+  #     # This class and many others are created automatically based on
+  #     # information from the server.
+  #     class User
+  #       alias login sAMAccountName
+  #     end
+  #   end
+  #
+  #   me = MyCompany.search(:filter => {:cn => "Name, My"}).first
+  #   puts me.login
+  def self.Module(options={})
+    Ldaptic::Module.new(options)
+  end
+
+  # The core constructor of Ldaptic.  This method returns an anonymous class
+  # which can then be inherited from.
+  #
+  # The new class is not intended to be instantiated, instead serving as a
+  # namespace. Included in this namespace is a set of class methods, as found
+  # in Ldaptic::Methods, and a class hierarchy mirroring the object classes
+  # found on the server.
+  #
+  #   options = {
+  #     :adapter  => :active_directory,
+  #     :host     => "pdc.mycompany.com",
+  #     :username => "mylogin@mycompany.com",
+  #     :password => "mypassword"
+  #   }
+  #
+  #   class MyCompany < Ldaptic::Class(options)
+  #     # This class and many others are created automatically based on
+  #     # information from the server.
+  #     class User
+  #       alias login sAMAccountName
+  #     end
+  #   end
+  #
+  #   me = MyCompany.search(:filter => {:cn => "Name, My"}).first
+  #   puts me.login
+  #
+  # Options given to this method are relayed to Ldaptic::Adapters.for.  The
+  # documentation for this method should be consulted for further information.
+  def self.Class(options={})
+    klass = ::Class.new(Class)
+    klass.instance_variable_set(:@options, Ldaptic::Adapters.for(options))
+    klass
+  end
+
+  class << self
+    alias Namespace Class
+  end
+
+  # An instance of this subclass of ::Module is returned by the Ldaptic::Module
+  # method.
+  class Module < ::Module #:nodoc:
+    def initialize(options={})
+      super()
+      @options = options
+    end
+    def append_features(base)
+      base.extend(Methods)
+      base.instance_variable_set(:@adapter, Ldaptic::Adapters.for(@options))
+      base.module_eval { build_hierarchy }
+    end
+  end
+
+  # The anonymous class returned by the Ldaptic::Class method descends from
+  # this class.
+  class Class #:nodoc:
+    class << self
+      # Callback which triggers the magic.
+      def inherited(subclass)
+        if options = @options
+          subclass.class_eval { include Ldaptic::Module.new(options) }
+        else
+          subclass.instance_variable_set(:@adapter, @adapter)
+        end
+        super
+      end
+      private :inherited, :new
+    end
+  end
+
+end

data/lib/ldaptic/active_model.rb

@@ -0,0 +1,37 @@
+require 'active_model'
+require 'ldaptic'
+
+ActiveModel::EachValidator.class_eval do
+  def validate(record)
+    attributes.each do |attribute|
+      values = record.read_attribute_for_validation(attribute)
+      values = [values] unless values.respond_to?(:before_type_cast)
+      values.each do |value|
+        next if (value.nil? && options[:allow_nil]) || (value.blank? && options[:allow_blank])
+        validate_each(record, attribute, value)
+      end
+    end
+  end
+end
+
+class Ldaptic::Entry
+  include ActiveModel::Validations
+  include ActiveModel::Serializers::Xml
+  include ActiveModel::Serializers::JSON
+  include ActiveModel::Dirty
+  include ActiveModel::Callbacks
+
+  def read_attribute_for_validation(attribute)
+    read_attribute(attribute.to_sym, true)
+  end
+
+  # define_model_callbacks(:save, :destroy)
+
+  validate do
+    @attributes.keys.each do |key|
+      self[key].errors.each do |error|
+        errors.add(key, error)
+      end
+    end
+  end if respond_to?(:validate)
+end

data/lib/ldaptic/adapters.rb

@@ -0,0 +1,90 @@
+module Ldaptic
+  # RFC1823 - The LDAP Application Program Interface
+  module Adapters
+
+    @adapters ||= {}
+
+    class <<self
+
+      # Internally used by adapters to make themselves available.
+      def register(name, mod) #:nodoc:
+        @adapters[name.to_sym] = mod
+        @adapters
+      end
+
+      # Returns a new adapter for a given set of options.  This method is not
+      # for end user use but is instead called by the Ldaptic::Class,
+      # Ldaptic::Module, and Ldaptic::Object methods.
+      #
+      # The <tt>:adapter</tt> key of the +options+ hash selects which adapter
+      # to use.  The following adapters are included with Ldaptic.
+      #
+      # * <tt>:ldap_conn</tt>: a Ruby/LDAP LDAP::Conn connection.
+      # * <tt>:ldap_sslconn</tt>: a Ruby/LDAP LDAP::SSLConn connection.
+      # * <tt>:active_directory</tt>: A wrapper around Ruby/LDAP which takes
+      #   into account some of the idiosyncrasies of Active Directory.
+      # * <tt>:net_ldap</tt>: a net-ldap Net::LDAP connection.
+      #
+      # All other options given are passed directly to the adapter.  While
+      # different adapters support different options, the following are
+      # typically supported.
+      #
+      # * <tt>:host</tt>: The host to connect to.  The default is localhost.
+      # * <tt>:port</tt>: The TCP port to use.  Default is provided by the
+      #   underlying connection.
+      # * <tt>:username</tt>: The DN to bind with.  If not given, an anonymous
+      #   bind is used.
+      # * <tt>:password</tt>: Password for binding.
+      # * <tt>:base</tt>: The default base DN.  Derived from the server by
+      #   default.
+      def for(options)
+        require 'ldaptic/adapters/abstract_adapter'
+        # Allow an adapter to be passed directly in for backwards compatibility.
+        if defined?(::LDAP::Conn) && options.kind_of?(::LDAP::Conn)
+          options = {:adapter => :ldap_conn, :connection => options}
+        elsif defined?(::Net::LDAP) && options.kind_of?(::Net::LDAP)
+          options = {:adapter => :net_ldap, :connection => options}
+        end
+        if options.kind_of?(Hash)
+          options = options.inject({}) {|h,(k,v)| h[k.to_sym] = v; h}
+          if options.has_key?(:connection) && !options.has_key?(:adapter)
+            options[:adapter] = options[:connection].class.name.downcase.gsub('::','_')
+          end
+          options[:adapter] ||= default_adapter
+          unless options[:adapter]
+            Ldaptic::Errors.raise(ArgumentError.new("No adapter specfied"))
+          end
+          begin
+            require "ldaptic/adapters/#{options[:adapter]}_adapter"
+          rescue LoadError
+          end
+          if adapter = @adapters[options[:adapter].to_sym]
+            adapter.new(options)
+          else
+            Ldaptic::Errors.raise(ArgumentError.new("Adapter #{options[:adapter]} not found"))
+          end
+        else
+          if options.kind_of?(::Ldaptic::Adapters::AbstractAdapter)
+            options
+          else
+            Ldaptic::Errors.raise(TypeError.new("#{options.class} is not a valid connection type"))
+          end
+        end
+      end
+
+      private
+      def default_adapter
+        require 'ldap'
+        :ldap_conn
+      rescue LoadError
+        begin
+          require 'net/ldap'
+          :net_ldap
+        rescue LoadError
+        end
+      end
+
+    end
+
+  end
+end