class Mongrel2::Control

An interface to the Mongrel2 control port.

References

(mongrel2.org/static/book-finalch4.html#x6-390003.8)

Constants

DEFAULT_PORT

The default zmq connection spec to use when talking to a mongrel2 server

Attributes

socket[R]

The control port ZMQ::REQ socket

Public Class Methods

new( port=DEFAULT_PORT ) click to toggle source

Create a new control port object using the current configuration.

# File lib/mongrel2/control.rb, line 28
def initialize( port=DEFAULT_PORT )
        check_port( port )
        @socket = CZTop::Socket::REQ.new
        @socket.options.linger = 0
        @socket.connect( port.to_s )
end

Public Instance Methods

close() click to toggle source

Close the control port connection.

# File lib/mongrel2/control.rb, line 160
def close
        self.socket.close
end
conn_status() click to toggle source

Returns an Array of Hashes, one for each connection to the server.

Example:

[
  {:id=>9, :fd=>27, :type=>1, :last_ping=>0, :last_read=>0, :last_write=>0,
   :bytes_read=>319, :bytes_written=>1065}
]
# File lib/mongrel2/control.rb, line 133
def conn_status
        self.request( :status, :what => 'net' )
end
control_stop() click to toggle source

Shuts down the control port permanently in case you want to keep it from being accessed for some reason.

# File lib/mongrel2/control.rb, line 154
def control_stop
        self.request( :control_stop )
end
help() click to toggle source

Return an Array of Hashes, one for each command the server supports.

Example:

[
  {:name=>"stop", :help=>"stop the server (SIGINT)"},
  {:name=>"reload", :help=>"reload the server"},
  {:name=>"help", :help=>"this command"},
  {:name=>"control_stop", :help=>"stop control port"},
  {:name=>"kill", :help=>"kill a connection"},
  {:name=>"status", :help=>"status, what=['net'|'tasks']"},
  {:name=>"terminate", :help=>"terminate the server (SIGTERM)"},
  {:name=>"time", :help=>"the server's time"},
  {:name=>"uuid", :help=>"the server's uuid"},
  {:name=>"info", :help=>"information about this server"}
]
# File lib/mongrel2/control.rb, line 81
def help
        self.request( :help )
end
info() click to toggle source

Return information about the server.

Example:

[{:port=>7337,
  :bind_addr=>"0.0.0.0",
  :uuid=>"28F6DCCF-28EB-48A4-A5B0-ED71D224FAE0",
  :chroot=>"/var/www",
  :access_log=>"/var/www/logs/admin-access.log",
  :error_log=>"/logs/admin-error.log",
  :pid_file=>"./run/admin.pid",
  :default_hostname=>"localhost"}]
# File lib/mongrel2/control.rb, line 106
def info
        self.request( :info )
end
kill( conn_id ) click to toggle source

Does a forced close on the socket that is at the specified conn_id.

# File lib/mongrel2/control.rb, line 147
def kill( conn_id )
        self.request( :kill, :id => conn_id )
end
reload() click to toggle source

Reloads the server using a SIGHUP. Returns a hash with a ':msg' key that describes what happened on success.

# File lib/mongrel2/control.rb, line 53
def reload
        self.request( :reload )
end
Also aliased as: restart
restart()
Alias for: reload
stop() click to toggle source

Stops the server using a SIGINT. Returns a hash with a ':msg' key that describes what happened on success.

# File lib/mongrel2/control.rb, line 46
def stop
        self.request( :stop )
end
tasklist() click to toggle source

Returns an Array of Hashes, one for each currently running task.

Example:

[
  {:id=>1, :system=>false, :name=>"SERVER", :state=>"read fd", :status=>"idle"},
  {:id=>2, :system=>false, :name=>"Handler_task", :state=>"read handler", :status=>"idle"},
  {:id=>3, :system=>false, :name=>"control", :state=>"read handler", :status=>"running"},
  {:id=>4, :system=>false, :name=>"ticker", :state=>"", :status=>"idle"},
  {:id=>5, :system=>true, :name=>"fdtask", :state=>"yield", :status=>"ready"}
]
# File lib/mongrel2/control.rb, line 121
def tasklist
        self.request( :status, :what => 'tasks' )
end
terminate() click to toggle source

Terminates the server with SIGTERM. Returns a hash with a ':msg' key that describes what happened on success.

# File lib/mongrel2/control.rb, line 61
def terminate
        self.request( :terminate )
end
time() click to toggle source

Returns the server's time as a Time object.

# File lib/mongrel2/control.rb, line 139
def time
        response = self.request( :time )
        return nil if response.empty?
        return Time.at( response.first[:time].to_i )
end
uuid() click to toggle source

Returns the server’s UUID as a String.

Example:

[{:uuid=>"28F6DCCF-28EB-48A4-A5B0-ED71D224FAE0"}]
# File lib/mongrel2/control.rb, line 90
def uuid
        self.request( :uuid )
end

Protected Instance Methods

request( command, options={} ) click to toggle source

Send a raw request to the server, asking it to perform the command with the specified options hash and return the results.

# File lib/mongrel2/control.rb, line 171
def request( command, options={} )
        msg = TNetstring.dump([ command, options ])
        self.log.debug "Request: %p" % [ msg ]
        self.socket << msg

        response = self.socket.receive
        self.log.debug "Response: %p" % [ response ]
        return unpack_response( response.pop )
end

Private Instance Methods

check_port( port ) click to toggle source

Check the path of the specified port if it's an 'ipc' URL, ensuring that a pipe exists there, and raising an exception if none does.

# File lib/mongrel2/control.rb, line 214
def check_port( port )
        scheme, path = port.split( '://' )
        return unless scheme == 'ipc'

        raise "%s: not a socket" % [ path ] unless FileTest.socket?( path )

        return true
end
unpack_response( response ) click to toggle source

Unpack a Mongrel2 Control Port response (TNetString encoded table) as an Array of Hashes.

# File lib/mongrel2/control.rb, line 188
def unpack_response( response )
        table = TNetstring.parse( response ).first
        self.log.debug "Unpacking response: %p" % [ table ]

        # Success
        if table.key?( 'headers' )
                headers, rows = table.values_at( 'headers', 'rows' )
                headers.map!( &:to_sym )

                return rows.collect do |row|
                        Hash[ [headers, row].transpose ]
                end

        # Error
        elsif table.key?( 'code' )
                # {"code"=>"INVALID_ARGUMENT", "error"=>"Invalid argument type."}
                raise Mongrel2::ControlError.new( table['code'], table['error'] )

        else
                raise ScriptError, "Don't know how to handle response: %p" % [ table ]
        end
end