ladle 0.1.0-java

data/lib/ladle/java/net/detailedbalance/ladle/Server.java

@@ -0,0 +1,170 @@
+package net.detailedbalance.ladle;
+
+import org.apache.commons.io.FileUtils;
+import org.apache.directory.server.configuration.MutableServerStartupConfiguration;
+import org.apache.directory.server.core.configuration.Configuration;
+import org.apache.directory.server.core.configuration.MutablePartitionConfiguration;
+import org.apache.directory.server.core.configuration.ShutdownConfiguration;
+import org.apache.log4j.Logger;
+
+import javax.naming.Context;
+import javax.naming.NamingException;
+import javax.naming.directory.Attribute;
+import javax.naming.directory.Attributes;
+import javax.naming.directory.BasicAttribute;
+import javax.naming.directory.BasicAttributes;
+import javax.naming.directory.InitialDirContext;
+import java.io.File;
+import java.io.IOException;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Hashtable;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * The class that creates and controls an embedded ApacheDS instance.  This runner is not designed
+ * for thread-safety or even to be used in the same JVM as anything else -- it's intended to be run
+ * in its own process to provide LDAP access over TCP.
+ * <p>
+ * The idea of using ApacheDS for this was from Spring Security's LDAP test support.  The details
+ * are from the ApacheDS embedding and unit testing documentation.
+ */
+public class Server {
+    private final Logger log = Logger.getLogger(getClass());
+
+    private final int port;
+    private final String domainComponent;
+    private final File tempDir;
+    private final File ldifDir;
+    private boolean running = false;
+
+    public Server(int port, String domainComponent, File ldifFile, File tempDirBase) {
+        this.port = port;
+        this.domainComponent = domainComponent;
+        this.tempDir = createTempDir(tempDirBase);
+        this.ldifDir = prepareLdif(ldifFile);
+    }
+
+    ////// SETUP
+
+    private File createTempDir(File tempDirBase) {
+        File temp = new File(tempDirBase, "ladle-server-" + UUID.randomUUID());
+        
+        if (temp.mkdir()) {
+            return temp;
+        } else {
+            throw new LadleFatalException("Could not create temporary directory " + temp);
+        }
+    }
+
+    private static Hashtable<String, String> baseEnvironment() {
+        Hashtable<String, String> env = new Hashtable<String, String>();
+        env.put(Context.PROVIDER_URL, "");
+        env.put(Context.INITIAL_CONTEXT_FACTORY,
+            "org.apache.directory.server.jndi.ServerContextFactory");
+
+        // these values are apparently hardcoded in ApacheDS
+        env.put(Context.SECURITY_PRINCIPAL, "uid=admin,ou=system");
+        env.put(Context.SECURITY_CREDENTIALS, "secret");
+        env.put(Context.SECURITY_AUTHENTICATION, "simple");
+
+        return env;
+    }
+
+    private File prepareLdif(File ldifFile) {
+        File dir = new File(tempDir, "ldif");
+        if (!dir.mkdir()) {
+            throw new LadleFatalException("Could not create LDIF directory " + dir);
+        }
+
+        try {
+            FileUtils.copyFileToDirectory(ldifFile, dir);
+        } catch (IOException e) {
+            throw new LadleFatalException("Copying " + ldifFile + " to " + dir + " failed.", e);
+        }
+
+        return dir;
+    }
+
+    ////// RUNNING
+
+    public void start() {
+        if (running) return;
+
+        try {
+            MutableServerStartupConfiguration cfg = new MutableServerStartupConfiguration();
+            cfg.setWorkingDirectory(tempDir);
+            cfg.setLdifDirectory(ldifDir);
+            cfg.setEnableNetworking(true);
+            cfg.setLdapPort(port);
+            cfg.setAllowAnonymousAccess(true);
+            cfg.setAccessControlEnabled(false);
+            cfg.setShutdownHookEnabled(false);
+            cfg.setContextPartitionConfigurations(
+                Collections.singleton(createPartitionConfiguration()));
+
+            new InitialDirContext(createJndiEnvironment(cfg));
+        } catch (NamingException e) {
+            throw new LadleFatalException("Startup failed", e);
+        }
+
+        running = true;
+    }
+
+    // Derived from http://directory.apache.org/apacheds/1.0/using-apacheds-for-unit-tests.html
+    private MutablePartitionConfiguration createPartitionConfiguration() throws NamingException {
+        MutablePartitionConfiguration pCfg = new MutablePartitionConfiguration();
+        pCfg.setName("ladle");
+        pCfg.setSuffix(domainComponent);
+
+        Set<String> indexedAttrs = new HashSet<String>();
+        indexedAttrs.add("objectClass");
+        indexedAttrs.add("dc");
+        indexedAttrs.add("uid");
+        pCfg.setIndexedAttributes( indexedAttrs );
+
+        // Create the root entry
+        {
+            Attributes attrs = new BasicAttributes(true);
+
+            Attribute attr = new BasicAttribute("objectClass");
+            attr.add("top");
+            attr.add("domain");
+            attrs.put(attr);
+
+            attr = new BasicAttribute("dc");
+            attr.add(domainComponent.split(",")[0].substring(3));
+            attrs.put(attr);
+
+            pCfg.setContextEntry(attrs);
+        }
+
+        return pCfg;
+    }
+
+    @SuppressWarnings({ "unchecked" })
+    private Hashtable<String, String> createJndiEnvironment(Configuration cfg) {
+        Hashtable<String, String> env = baseEnvironment();
+        env.putAll(cfg.toJndiEnvironment());
+        return env;
+    }
+
+    public void stop() {
+        if (!running) return;
+        try {
+            new InitialDirContext(createJndiEnvironment(new ShutdownConfiguration()));
+        } catch (NamingException e) {
+            throw new LadleFatalException("Shutdown failed", e);
+        }
+        running = false;
+
+        if (tempDir.exists()) {
+            try {
+                FileUtils.deleteDirectory(tempDir);
+            } catch (IOException e) {
+                log.error("Deleting the temporary directory " + tempDir + " failed", e);
+            }
+        }
+    }
+}

data/lib/ladle/jruby_process.rb

@@ -0,0 +1,61 @@
+require 'ladle'
+
+require 'java'
+
+module Ladle
+  ##
+  # Implementations of platform-specific behaviors for JRuby.
+  #
+  # This separate strategy is necessary because you can't
+  # `Process.waitpid2` on the PID returned by JRuby's `IO.popen4`.
+  class JRubyProcess
+    ##
+    # Create a new process for the given command and its args.
+    def initialize(*command_and_args)
+      @command_and_args = command_and_args
+    end
+
+    ##
+    # Start the process and return pipes to its standard streams.
+    #
+    # @return [[IO, IO, IO]] stdin, stdout, and stderr for the running process.
+    def popen
+      # You can't wait for the PID returned by JRuby's IO.popen4, so
+      # this is necessary.
+      cmd = @command_and_args.collect(&:to_s).to_java(:string)
+      @process = Java::JavaLang::ProcessBuilder.new(
+        cmd
+      ).start
+
+      [
+        # java.util.Process flips the meanings of "in" and "out"
+        # relative to popen3
+        @process.output_stream.to_io,
+        @process.input_stream.to_io,
+        @process.error_stream.to_io
+      ]
+    end
+
+    ##
+    # Wait for the process to finish.
+    #
+    # @return [Fixnum] the return status of the process.
+    def wait
+      @process.waitFor
+    end
+
+    ##
+    # Send signal 15 to the process.
+    #
+    # @return [void]
+    def stop_gracefully
+      Process.kill 15, pid
+    end
+
+    ##
+    # @return [Fixnum] the PID for the process
+    def pid
+      @pid ||= Java::OrgJrubyUtil::ShellLauncher.getPidFromProcess(@process)
+    end
+  end
+end

data/lib/ladle/ruby_process.rb

@@ -0,0 +1,46 @@
+require 'ladle'
+
+require 'open4'
+
+module Ladle
+  ##
+  # Implementations of platform-specific process handling behaviors for Ruby.
+  class RubyProcess
+    ##
+    # Create a new process for the given command and its args.
+    def initialize(*command_and_args)
+      @command_and_args = command_and_args
+    end
+
+    ##
+    # Start the process and return pipes to its standard streams.
+    #
+    # @return [[IO, IO, IO]] stdin, stdout, and stderr for the running process.
+    def popen
+      @pid, i, o, e = Open4.open4(@command_and_args.join(' '))
+      [i, o, e]
+    end
+
+    ##
+    # Wait for the process to finish.
+    #
+    # @return [Fixnum] the return status of the process.
+    def wait
+      Process.waitpid2(@pid)[1]
+    end
+
+    ##
+    # Send signal 15 to the process.
+    #
+    # @return [void]
+    def stop_gracefully
+      Process.kill 15, pid
+    end
+
+    ##
+    # @return [Fixnum] the PID for the process
+    def pid
+      @pid
+    end
+  end
+end

data/lib/ladle/server.rb

@@ -0,0 +1,334 @@
+require 'ladle'
+
+module Ladle
+  ##
+  # Controller for Ladle's core feature, the embedded LDAP server.
+  class Server
+    ##
+    # The port from which this server will be available.
+    # @return [Fixnum]
+    attr_reader :port
+
+    ##
+    # The domain for the served data.
+    # @return [String]
+    attr_reader :domain
+
+    ##
+    # The filename of the LDIF data loaded into this server before it
+    # started.
+    # @return [String]
+    attr_reader :ldif
+
+    ##
+    # The time to wait for the server to start up before giving up
+    # (seconds).
+    # @return [Fixnum]
+    attr_reader :timeout
+
+    ##
+    # The base directory into which the server should write its
+    # temporary files.  Ladle will create a directory under this path
+    # on startup and remove it on shutdown.
+    # @return [String]
+    attr_reader :tmpdir
+
+    ##
+    # The java executable to use to run the embedded server.
+    # @return [String]
+    attr_reader :java_bin
+
+    ##
+    # @param [Hash] opts the options for the server
+    # @option opts [Fixnum] :port (3897) The port to serve from.
+    # @option opts [String] :ldif ({path to the gem}/lib/ladle/default.ldif)
+    #   The filename of the LDIF-formatted data to use for this
+    #   server.  If provide your own data, be sure to set the
+    #   :domain option to match.
+    # @option opts [String] :domain ("dc=example,dc=org") the domain
+    #   for the data provided in the :ldif option.
+    # @option opts [Boolean] :verbose (false) if true, detailed
+    #   information about the execution of the server will be printed
+    #   to standard error.
+    # @option opts [Boolean] :quiet (false) if true _no_ information
+    #   about regular execution will be printed.  Error information
+    #   will still be printed.  This trumps `:verbose`.
+    # @option opts [Fixnum] :timeout (15) the amount of time to wait
+    #   (seconds) for the server process to start before giving up.
+    # @option opts [String] :tmpdir (ENV['TMPDIR'] or ENV['TEMPDIR'])
+    #   the temporary directory to use for the server's files.  If not
+    #   guessable from the environment, it must be specified.  It must
+    #   already exist.
+    # @option opts [String] :java_bin ("java" or
+    #   File.join(ENV["JAVA_HOME"], "bin", "java")) the java
+    #   executable to use to run the embedded server.
+    def initialize(opts={})
+      @port = opts[:port] || 3897
+      @domain = opts[:domain] || "dc=example,dc=org"
+      @ldif = opts[:ldif] || File.expand_path("../default.ldif", __FILE__)
+      @quiet = opts[:quiet]
+      @verbose = opts[:verbose]
+      @timeout = opts[:timeout] || 15
+      @tmpdir = opts[:tmpdir] || ENV['TMPDIR'] || ENV['TEMPDIR']
+      @java_bin = opts[:java_bin] ||
+        (ENV['JAVA_HOME'] ? File.join(ENV['JAVA_HOME'], "bin", "java") : "java")
+
+      # Additional arguments that can be passed to the java server
+      # process.  Used for testing only, so not documented.
+      @additional_args = opts[:more_args] || []
+
+      unless @domain =~ /^dc=/
+        raise "The domain component must start with 'dc='.  '#{@domain}' does not."
+      end
+
+      if tmpdir.nil?
+        raise "Cannot guess tmpdir from the environment.  Please specify it."
+      elsif !File.directory?(tmpdir)
+        raise "Tmpdir #{tmpdir.inspect} does not exist."
+      end
+
+      unless File.readable?(@ldif)
+        raise "Cannot read specified LDIF file #{@ldif}."
+      end
+    end
+
+    ##
+    # Starts up the server in a separate process.  This method will
+    # not return until the server is listening on the specified port.
+    # The same {Server} instance can be started and stopped multiple
+    # times, but the runs will be independent.
+    #
+    # @return [Server] this instance
+    def start
+      return if @running
+      log "Starting server on #{port}"
+      trace "- Server command: #{server_cmd.inspect}"
+      java_in, java_out, java_err = create_process(*server_cmd).popen
+      @running = true
+      trace "- Started subprocess #{process.pid}"
+
+      @log_watcher = LogStreamWatcher.new(java_err, self)
+      @log_watcher.start
+      @controller = ApacheDSController.new(java_in, java_out, self)
+      @controller.start
+
+      # TODO: perhaps this busywait can be replaced with select?
+      trace "- Waiting for server to start"
+      started_waiting = Time.now
+      until @controller.started? || @controller.error? || Time.now > started_waiting + timeout
+        trace "  . waited #{Time.now - started_waiting} seconds"
+        sleep 0.5
+      end
+      trace "- Stopped waiting after #{Time.now - started_waiting} seconds"
+
+      if @controller.error?
+        self.stop
+        trace "! Subprocess error (see above)"
+        raise "LDAP server failed to start"
+      elsif !@controller.started?
+        self.stop
+        trace "! Timed out"
+        raise "LDAP server startup did not complete within #{timeout} seconds"
+      end
+
+      trace "- Server started successfully"
+      at_exit { stop }
+
+      self
+    end
+
+    ##
+    # Stops the server that was started with {#start}.
+    def stop
+      return if !@running
+      log "Stopping server on #{port}"
+      trace "- Stopping server process"
+      @controller.stop if @controller
+
+      trace "- Signalling server process to stop if not already stopped"
+      process.stop_gracefully
+      process.wait
+
+      @running = false
+    end
+
+    ##
+    # Visible for collaborators.
+    # @private
+    def log_error(msg)
+      $stderr.puts(msg)
+    end
+
+    ##
+    # Visible for collaborators.
+    # @private
+    def log(msg)
+      $stderr.puts(msg) unless quiet?
+    end
+
+    ##
+    # Visible for collaborators.
+    # @private
+    def trace(msg)
+      $stderr.puts(msg) if verbose? && !quiet?
+    end
+
+    ##
+    # If the controller will print anything about what it is doing to
+    # stderr.  If this is true, all non-error output will be
+    # supressed.  This value trumps {#verbose?}.
+    #
+    # @return [Boolean]
+    def quiet?
+      @quiet
+    end
+
+    ##
+    # Whether the controller will print detailed information about
+    # what it is doing to stderr.  This includes information from the
+    # embedded ApacheDS instance.
+    #
+    # @return [Boolean]
+    def verbose?
+      @verbose
+    end
+
+    private
+
+    def create_process(*cmd)
+      @process =
+        if RUBY_PLATFORM == 'java'
+          JRubyProcess.new(*cmd)
+        else
+          RubyProcess.new(*cmd)
+        end
+    end
+
+    def process
+      @process
+    end
+
+    def server_cmd
+      [
+        java_bin,
+        "-cp", classpath,
+        "net.detailedbalance.ladle.Main",
+        "--port", port,
+        "--domain", domain,
+        "--ldif", ldif,
+        "--tmpdir", tmpdir
+      ] + @additional_args
+    end
+
+    def classpath
+      (
+        # ApacheDS
+        Dir[File.expand_path("../apacheds/*.jar", __FILE__)] +
+        # Wrapper code
+        [File.expand_path("../java", __FILE__)]
+      ).join(':')
+    end
+
+    ##
+    # Encapsulates communication with the child ApacheDS process.
+    class ApacheDSController
+      def initialize(ds_in, ds_out, server)
+        @ds_in = ds_in
+        @ds_out = ds_out
+        @server = server
+      end
+
+      def start
+        Thread.new(self) do |controller|
+          controller.watch
+        end
+      end
+
+      def watch
+        while (line = @ds_out.readline) && !error?
+          case line
+          when /^STARTED/
+            @started = true
+          when /^FATAL/
+            report_error(line)
+          when /^STOPPED/
+            @started = false
+          else
+            report_error("Unexpected server process output: #{line}")
+          end
+        end
+      end
+
+      def started?
+        @started
+      end
+
+      def error?
+        @error
+      end
+
+      def stop
+        unless @ds_in.closed?
+          @ds_in.puts("STOP")
+          @ds_in.flush
+          @ds_in.close
+        end
+      end
+
+      private
+
+      def report_error(msg)
+        @error = true
+        @server.log_error "ApacheDS process failed: #{msg}"
+        self.stop
+      end
+    end
+
+    class LogStreamWatcher
+      def initialize(ds_err, server)
+        @ds_err = ds_err
+        @server = server
+      end
+
+      def start
+        Thread.new(self) do |watcher|
+          watcher.watch
+        end
+      end
+
+      def watch
+        begin
+          while !@ds_err.closed? && (line = @ds_err.readline)
+            if is_error?(line)
+              @server.log_error("ApacheDS: #{line}")
+            else
+              @server.trace("ApacheDS: #{line}")
+            end
+          end
+        rescue EOFError
+          # stop naturally
+        end
+      end
+
+      private
+
+      def is_error?(line)
+        kind = (line =~ /^([A-Z]+):/) ? $1 : nil
+        (kind.nil? || %w(ERROR WARN).include?(kind)) && !bogus?(line)
+      end
+
+      ##
+      # Indicates whether the "error" or "warning" emitted from
+      # ApacheDS is actually an error or warning.
+      def bogus?(line)
+        [
+          %r{shutdown hook has NOT been registered},
+          %r{attributeType w/ OID 2.5.4.16 not registered},
+          %r{default.*?cache size},
+          %r{change the admin password},
+          %r{Attribute \S+ does not have normalizer}
+        ].detect { |re| line =~ re }
+      end
+    end
+  end
+end