Class
PhusionPassenger::AbstractServer

In: | lib/phusion_passenger/abstract_server.rb
Parent: | Object

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

Methods

- before_fork
- connect
- define_message_handler
- define_signal_handler
- fileno_of
- finalize_server
- initialize_server
- new
- server_pid
- start
- start_synchronously
- started?
- stop

Included Modules

- Utils

Classes and Modules
Class PhusionPassenger::AbstractServer::InvalidPassword
Class PhusionPassenger::AbstractServer::ServerAlreadyStarted
Class PhusionPassenger::AbstractServer::ServerError
Class PhusionPassenger::AbstractServer::ServerNotStarted
Class PhusionPassenger::AbstractServer::UnknownMessage
Attributes

[RW] | ignore_password_errors |
[RW] | max_idle_time | 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.
[RW] | next_cleaning_time | Used by AbstractServerCollection to remember when this AbstractServer should be idle cleaned.
[R] | password |

Public Class methods
new(socket_filename = nil, password = nil)

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 116
    116:         def initialize(socket_filename = nil, password = nil)
    117:                 @socket_filename = socket_filename
    118:                 @password = password
    119:                 @socket_filename ||= "#{passenger_tmpdir}/spawn-server/socket.#{Process.pid}.#{object_id}"
    120:                 @password ||= generate_random_id(:base64)
    121:
    122:                 @message_handlers = {}
    123:                 @signal_handlers = {}
    124:                 @orig_signal_handlers = {}
    125:         end

Public Instance methods
connect() {|channel| ...}

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

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 267
    267:         def connect
    268:                 channel = MessageChannel.new(UNIXSocket.new(@socket_filename))
    269:                 begin
    270:                         channel.write_scalar(@password)
    271:                         yield channel
    272:                 ensure
    273:                         channel.close
    274:                 end
    275:         end

server_pid()

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

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 252
    252:         def server_pid
    253:                 return @pid
    254:         end

start()

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.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 134
    134:         def start
    135:                 if started?
    136:                         raise ServerAlreadyStarted, "Server is already started"
    137:                 end
    138:
    139:                 a, b = UNIXSocket.pair
    140:                 File.unlink(@socket_filename) rescue nil
    141:                 server_socket = UNIXServer.new(@socket_filename)
    142:                 File.chmod(0700, @socket_filename)
    143:
    144:                 before_fork
    145:                 @pid = fork
    146:                 if @pid.nil?
    147:                         has_exception = false
    148:                         begin
    149:                                 STDOUT.sync = true
    150:                                 STDERR.sync = true
    151:                                 a.close
    152:
    153:                                 # During Passenger's early days, we used to close file descriptors based
    154:                                 # on a white list of file descriptors. That proved to be way too fragile:
    155:                                 # too many file descriptors are being left open even though they shouldn't
    156:                                 # be. So now we close file descriptors based on a black list.
    157:                                 #
    158:                                 # Note that STDIN, STDOUT and STDERR may be temporarily set to
    159:                                 # different file descriptors than 0, 1 and 2, e.g. in unit tests.
    160:                                 # We don't want to close these either.
    161:                                 file_descriptors_to_leave_open = [0, 1, 2,
    162:                                         b.fileno, server_socket.fileno,
    163:                                         fileno_of(STDIN), fileno_of(STDOUT), fileno_of(STDERR)
    164:                                 ].compact.uniq
    165:                                 NativeSupport.close_all_file_descriptors(file_descriptors_to_leave_open)
    166:                                 # In addition to closing the file descriptors, one must also close
    167:                                 # the associated IO objects. This is to prevent IO.close from
    168:                                 # double-closing already closed file descriptors.
    169:                                 close_all_io_objects_for_fds(file_descriptors_to_leave_open)
    170:
    171:                                 # At this point, RubyGems might have open file handles for which
    172:                                 # the associated file descriptors have just been closed. This can
    173:                                 # result in mysterious 'EBADFD' errors. So we force RubyGems to
    174:                                 # clear all open file handles.
    175:                                 Gem.clear_paths
    176:
    177:                                 # Reseed pseudo-random number generator for security reasons.
    178:                                 srand
    179:
    180:                                 start_synchronously(@socket_filename, @password, server_socket, b)
    181:                         rescue Interrupt
    182:                                 # Do nothing.
    183:                                 has_exception = true
    184:                         rescue Exception => e
    185:                                 has_exception = true
    186:                                 print_exception(self.class.to_s, e)
    187:                         ensure
    188:                                 exit!(has_exception ? 1 : 0)
    189:                         end
    190:                 end
    191:                 server_socket.close
    192:                 b.close
    193:                 @owner_socket = a
    194:         end

start_synchronously(socket_filename, password, server_socket, owner_socket)

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().

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 200
    200:         def start_synchronously(socket_filename, password, server_socket, owner_socket)
    201:                 @owner_socket = owner_socket
    202:                 begin
    203:                         reset_signal_handlers
    204:                         initialize_server
    205:                         begin
    206:                                 server_main_loop(password, server_socket)
    207:                         ensure
    208:                                 finalize_server
    209:                         end
    210:                 rescue Interrupt
    211:                         # Do nothing
    212:                 ensure
    213:                         @owner_socket = nil
    214:                         revert_signal_handlers
    215:                         File.unlink(socket_filename) rescue nil
    216:                         server_socket.close
    217:                 end
    218:         end

started?()

Return whether the server has been started.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 247
    247:         def started?
    248:                 return !!@owner_socket
    249:         end

stop()

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.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 225
    225:         def stop
    226:                 if !started?
    227:                         raise ServerNotStarted, "Server is not started"
    228:                 end
    229:
    230:                 begin
    231:                         @owner_socket.write("x")
    232:                 rescue Errno::EPIPE
    233:                 end
    234:                 @owner_socket.close
    235:                 @owner_socket = nil
    236:                 File.unlink(@socket_filename) rescue nil
    237:
    238:                 # Wait at most 4 seconds for server to exit. If it doesn't do that,
    239:                 # we kill it forcefully with SIGKILL.
    240:                 if !Process.timed_waitpid(@pid, 4)
    241:                         Process.kill('SIGKILL', @pid) rescue nil
    242:                         Process.timed_waitpid(@pid, 1)
    243:                 end
    244:         end

Protected Instance methods
before_fork()

A hook which is called when the server is being started, just before forking a new process. The default implementation does nothing, this method is supposed to be overrided by child classes.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 280
    280:         def before_fork
    281:         end

define_message_handler(message_name, handler)

Define a handler for a message. message_name is the name of the message to handle, and handler is the name of a method to be called (this may either be a String or a Symbol).

A message is just a list of strings, and so handler will be called with the message as its arguments, excluding the first element. See also the example in the class description.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 300
    300:         def define_message_handler(message_name, handler)
    301:                 @message_handlers[message_name.to_s] = handler
    302:         end

define_signal_handler(signal, handler)

Define a handler for a signal.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 305
    305:         def define_signal_handler(signal, handler)
    306:                 @signal_handlers[signal.to_s] = handler
    307:         end

fileno_of(io)

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 309
    309:         def fileno_of(io)
    310:                 return io.fileno
    311:         rescue
    312:                 return nil
    313:         end

finalize_server()

A hook which is called when the server is being stopped. This is called in the child process, after the main loop has been left. The default implementation does nothing, this method is supposed to be overrided by child classes.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 292
    292:         def finalize_server
    293:         end

initialize_server()

A hook which is called when the server is being started. This is called in the child process, before the main loop is entered. The default implementation does nothing, this method is supposed to be overrided by child classes.

[ show source ]

         # File lib/phusion_passenger/abstract_server.rb, line 286
    286:         def initialize_server
    287:         end