Class: Ladle::Server

Inherits:
Object
  • Object
show all
Defined in:
lib/ladle/server.rb

Overview

Controller for Ladle’s core feature, the embedded LDAP server.

Defined Under Namespace

Classes: ApacheDSController, LogStreamWatcher

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Server

Returns a new instance of Server.

Parameters:

  • opts (Hash) (defaults to: {}) —

    the options for the server

Options Hash (opts):

  • :port (Fixnum) — default: 3897 —

    The port to serve from.

  • :ldif (String) — default: {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.

  • :domain (String) — default: "dc=example,dc=org" —

    the domain for the data provided in the :ldif option.

  • :verbose (Boolean) — default: false —

    if true, detailed information about the execution of the server will be printed to standard error.

  • :quiet (Boolean) — default: false —

    if true no information about regular execution will be printed. Error information will still be printed. This trumps ‘:verbose`.

  • :timeout (Fixnum) — default: 15 —

    the amount of time to wait (seconds) for the server process to start before giving up.

  • :tmpdir (String) — default: 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.

  • :java_bin (String) — default: "java" or File.join(ENV["JAVA_HOME"], "bin", "java") —

    the java executable to use to run the embedded server.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/ladle/server.rb', line 65

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

Instance Attribute Details

#domain ⇒ String (readonly)

The domain for the served data.

Returns:

  • (String) 


15
16
17
 
# File 'lib/ladle/server.rb', line 15

def domain
  @domain
end

#java_bin ⇒ String (readonly)

The java executable to use to run the embedded server.

Returns:

  • (String) 


39
40
41
 
# File 'lib/ladle/server.rb', line 39

def java_bin
  @java_bin
end

#ldif ⇒ String (readonly)

The filename of the LDIF data loaded into this server before it started.

Returns:

  • (String) 


21
22
23
 
# File 'lib/ladle/server.rb', line 21

def ldif
  @ldif
end

#port ⇒ Fixnum (readonly)

The port from which this server will be available.

Returns:

  • (Fixnum) 


10
11
12
 
# File 'lib/ladle/server.rb', line 10

def port
  @port
end

#timeout ⇒ Fixnum (readonly)

The time to wait for the server to start up before giving up (seconds).

Returns:

  • (Fixnum) 


27
28
29
 
# File 'lib/ladle/server.rb', line 27

def timeout
  @timeout
end

#tmpdir ⇒ String (readonly)

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.

Returns:

  • (String) 


34
35
36
 
# File 'lib/ladle/server.rb', line 34

def tmpdir
  @tmpdir
end

Instance Method Details

#log(msg) ⇒ Object

Visible for collaborators.



165
166
167
 
# File 'lib/ladle/server.rb', line 165

def log(msg)
  $stderr.puts(msg) unless quiet?
end

#log_error(msg) ⇒ Object

Visible for collaborators.



158
159
160
 
# File 'lib/ladle/server.rb', line 158

def log_error(msg)
  $stderr.puts(msg)
end

#quiet? ⇒ Boolean

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?.

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/ladle/server.rb', line 182

def quiet?
  @quiet
end

#start ⇒ Server

Starts up the server in a separate process. This method will not return until the server is listening on the specified port. The same Ladle::Server instance can be started and stopped multiple times, but the runs will be independent.

Returns:



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/ladle/server.rb', line 102

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

#stop ⇒ Object

Stops the server that was started with #start.



142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/ladle/server.rb', line 142

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

#trace(msg) ⇒ Object

Visible for collaborators.



172
173
174
 
# File 'lib/ladle/server.rb', line 172

def trace(msg)
  $stderr.puts(msg) if verbose? && !quiet?
end

#verbose? ⇒ Boolean

Whether the controller will print detailed information about what it is doing to stderr. This includes information from the embedded ApacheDS instance.

Returns:

  • (Boolean) 


192
193
194
 
# File 'lib/ladle/server.rb', line 192

def verbose?
  @verbose
end