Class: PhusionPassenger::AbstractServer

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/phusion_passenger/abstract_server.rb

Overview

An abstract base class for a server that has the following properties:

  • The server listens on a password protected Unix socket.

  • The server is multithreaded and handles one client per thread.

  • The server is owned by one or more processes. If all processes close their reference to the server, then the server will quit.

  • The server’s main loop may be run in a child process (and so is asynchronous from the parent process).

  • One can communicate with the server through discrete MessageChannel messages, as opposed to byte streams.

  • The server can pass file descriptors (IO objects) back to the client.

The server will also reset all signal handlers. That is, it will respond to all signals in the default manner. The only exception is SIGHUP, which is ignored. One may define additional signal handlers using define_signal_handler().

Before an AbstractServer can be used, it must first be started by calling start(). When it is no longer needed, stop() should be called.

Here’s an example on using AbstractServer:

class MyServer < PhusionPassenger::AbstractServer
   def initialize
      super()
      define_message_handler(:hello, :handle_hello)
   end

   def hello(first_name, last_name)
      connect do |channel|
         channel.write('hello', first_name, last_name)
         reply, pointless_number = channel.read
         puts "The server said: #{reply}"
         puts "In addition, it sent this pointless number: #{pointless_number}"
      end
   end

private
   def handle_hello(channel, first_name, last_name)
      channel.write("Hello #{first_name} #{last_name}, how are you?", 1234)
   end
end

server = MyServer.new
server.start
server.hello("Joe", "Dalton")
server.stop

Defined Under Namespace

Classes: InvalidPassword, ServerAlreadyStarted, ServerError, ServerNotStarted, UnknownMessage

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils

process_is_alive?

Constructor Details

#initialize(socket_filename = nil, password = nil) ⇒ AbstractServer

Returns a new instance of AbstractServer.



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/phusion_passenger/abstract_server.rb', line 116

def initialize(socket_filename = nil, password = nil)
  @socket_filename = socket_filename
  @password = password
  @socket_filename ||= "#{passenger_tmpdir}/spawn-server/socket.#{Process.pid}.#{object_id}"
  @password ||= generate_random_id(:base64)
  
  @message_handlers = {}
  @signal_handlers = {}
  @orig_signal_handlers = {}
end

Instance Attribute Details

#ignore_password_errors ⇒ Object

Returns the value of attribute ignore_password_errors.



104
105
106
 
# File 'lib/phusion_passenger/abstract_server.rb', line 104

def ignore_password_errors
  @ignore_password_errors
end

#max_idle_time ⇒ Object

The maximum time that this AbstractServer may be idle. Used by AbstractServerCollection to determine when this object should be cleaned up. nil or 0 indicate that this object should never be idle cleaned.



110
111
112
 
# File 'lib/phusion_passenger/abstract_server.rb', line 110

def max_idle_time
  @max_idle_time
end

#next_cleaning_time ⇒ Object

Used by AbstractServerCollection to remember when this AbstractServer should be idle cleaned.



114
115
116
 
# File 'lib/phusion_passenger/abstract_server.rb', line 114

def next_cleaning_time
  @next_cleaning_time
end

#password ⇒ Object (readonly)

Returns the value of attribute password.



103
104
105
 
# File 'lib/phusion_passenger/abstract_server.rb', line 103

def password
  @password
end

Instance Method Details

#connect ⇒ Object

Connects to the server and yields a channel for communication. The first message’s name must match a handler name. The connection can only be used for a single handler cycle; after the handler is done, the connection will be closed.

server.connect do |channel|
   channel.write("a message")
   ...
end

Raises: SystemCallError, IOError, SocketError



267
268
269
270
271
272
273
274
275
 
# File 'lib/phusion_passenger/abstract_server.rb', line 267

def connect
  channel = MessageChannel.new(UNIXSocket.new(@socket_filename))
  begin
    channel.write_scalar(@password)
    yield channel
  ensure
    channel.close
  end
end

#server_pid ⇒ Object

Return the PID of the started server. This is only valid if #start has been called.



252
253
254
 
# File 'lib/phusion_passenger/abstract_server.rb', line 252

def server_pid
  return @pid
end

#start ⇒ Object

Start the server. This method does not block since the server runs asynchronously from the current process.

You may only call this method if the server is not already started. Otherwise, a ServerAlreadyStarted will be raised.

Derived classes may raise additional exceptions.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/phusion_passenger/abstract_server.rb', line 134

def start
  if started?
    raise ServerAlreadyStarted, "Server is already started"
  end
  
  a, b = UNIXSocket.pair
  File.unlink(@socket_filename) rescue nil
  server_socket = UNIXServer.new(@socket_filename)
  File.chmod(0700, @socket_filename)
  
  before_fork
  @pid = fork
  if @pid.nil?
    has_exception = false
    begin
      STDOUT.sync = true
      STDERR.sync = true
      a.close
      
      # During Passenger's early days, we used to close file descriptors based
      # on a white list of file descriptors. That proved to be way too fragile:
      # too many file descriptors are being left open even though they shouldn't
      # be. So now we close file descriptors based on a black list.
      #
      # Note that STDIN, STDOUT and STDERR may be temporarily set to
      # different file descriptors than 0, 1 and 2, e.g. in unit tests.
      # We don't want to close these either.
      file_descriptors_to_leave_open = [0, 1, 2,
        b.fileno, server_socket.fileno,
        fileno_of(STDIN), fileno_of(STDOUT), fileno_of(STDERR)
      ].compact.uniq
      NativeSupport.close_all_file_descriptors(file_descriptors_to_leave_open)
      # In addition to closing the file descriptors, one must also close
      # the associated IO objects. This is to prevent IO.close from
      # double-closing already closed file descriptors.
      close_all_io_objects_for_fds(file_descriptors_to_leave_open)
      
      # At this point, RubyGems might have open file handles for which
      # the associated file descriptors have just been closed. This can
      # result in mysterious 'EBADFD' errors. So we force RubyGems to
      # clear all open file handles.
      Gem.clear_paths
      
      # Reseed pseudo-random number generator for security reasons.
      srand
      
      start_synchronously(@socket_filename, @password, server_socket, b)
    rescue Interrupt
      # Do nothing.
      has_exception = true
    rescue Exception => e
      has_exception = true
      print_exception(self.class.to_s, e)
    ensure
      exit!(has_exception ? 1 : 0)
    end
  end
  server_socket.close
  b.close
  @owner_socket = a
end

#start_synchronously(socket_filename, password, server_socket, owner_socket) ⇒ Object

Start the server, but in the current process instead of in a child process. This method blocks until the server’s main loop has ended.

All hooks will be called, except before_fork().



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/phusion_passenger/abstract_server.rb', line 200

def start_synchronously(socket_filename, password, server_socket, owner_socket)
  @owner_socket = owner_socket
  begin
    reset_signal_handlers
    initialize_server
    begin
      server_main_loop(password, server_socket)
    ensure
      finalize_server
    end
  rescue Interrupt
    # Do nothing
  ensure
    @owner_socket = nil
    revert_signal_handlers
    File.unlink(socket_filename) rescue nil
    server_socket.close
  end
end

#started? ⇒ Boolean

Return whether the server has been started.

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/phusion_passenger/abstract_server.rb', line 247

def started?
  return !!@owner_socket
end

#stop ⇒ Object

Stop the server. The server will quit as soon as possible. This method waits until the server has been stopped.

When calling this method, the server must already be started. If not, a ServerNotStarted will be raised.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/phusion_passenger/abstract_server.rb', line 225

def stop
  if !started?
    raise ServerNotStarted, "Server is not started"
  end
  
  begin
    @owner_socket.write("x")
  rescue Errno::EPIPE
  end
  @owner_socket.close
  @owner_socket = nil
  File.unlink(@socket_filename) rescue nil
  
  # Wait at most 4 seconds for server to exit. If it doesn't do that,
  # we kill it forcefully with SIGKILL.
  if !Process.timed_waitpid(@pid, 4)
    Process.kill('SIGKILL', @pid) rescue nil
    Process.timed_waitpid(@pid, 1)
  end
end