Module | PhusionPassenger::Utils
In: | lib/phusion_passenger/utils.rb lib/phusion_passenger/utils/file_system_watcher.rb lib/phusion_passenger/utils/hosts_file_parser.rb lib/phusion_passenger/utils/rewindable_input.rb lib/phusion_passenger/utils/tmpdir.rb lib/phusion_passenger/utils/unseekable_socket.rb

Utility functions.

### Methods

after_handling_requests after_loading_app_code assert_valid_directory assert_valid_file assert_valid_groupname assert_valid_username at_exit before_handling_requests canonicalize_path check_directory_tree_permissions close_all_io_objects_for_fds connect_to_server generate_random_id get_socket_address_type global_backtrace_report local_socket_address? lower_privilege lower_privilege_called marshal_exception new opens_files? passenger_tmpdir passenger_tmpdir passenger_tmpdir= prepare_app_process print_exception private_class_method process_is_alive? report_app_init_status safe_fork sanitize_spawn_options split_by_null_into_hash split_by_null_into_hash to_boolean unmarshal_and_raise_errors unmarshal_exception

### Classes and Modules

Class PhusionPassenger::Utils::FileSystemWatcher
Class PhusionPassenger::Utils::HostsFileParser
Class PhusionPassenger::Utils::PseudoIO
Class PhusionPassenger::Utils::RewindableInput
Class PhusionPassenger::Utils::UnseekableSocket

### Constants

NULL | = | "\0".freeze
FileSystemWatcher | = | NativeSupport::FileSystemWatcher

### Public Class methods

new(filenames, termination_pipe = nil)
opens_files?()

### Protected Class methods

lower_privilege_called()

No-op, hook for unit tests.

passenger_tmpdir(create = true)

Returns the directory in which to store Phusion Passenger-specific temporary files. If `create` is true, then this method creates the directory if it doesn‘t exist.

passenger_tmpdir=(dir)

### Protected Instance methods

after_handling_requests()

To be called after the request handler main loop is exited. This function will fire off necessary events perform necessary cleanup tasks.

after_loading_app_code(options)

This method is to be called after loading the application code but before forking a worker process.

assert_valid_directory(path)

Assert that `path` is a directory. Raises `InvalidPath` if it isn‘t.

assert_valid_file(path)

Assert that `path` is a file. Raises `InvalidPath` if it isn‘t.

assert_valid_groupname(groupname)

Assert that `groupname` is a valid group name. Raises ArgumentError if that is not the case.

assert_valid_username(username)

Assert that `username` is a valid username. Raises ArgumentError if that is not the case.

at_exit(&block)
before_handling_requests(forked, options)

To be called before the request handler main loop is entered, but after the app startup file has been loaded. This function will fire off necessary events and perform necessary preparation tasks.

`forked` indicates whether the current worker process is forked off from an ApplicationSpawner that has preloaded the app code. `options` are the spawn options that were passed.

canonicalize_path(path)

Return the canonicalized version of `path`. This path is guaranteed to to be "normal", i.e. it doesn‘t contain stuff like ".." or "/", and it fully resolves symbolic links.

Raises SystemCallError if something went wrong. Raises ArgumentError if `path` is nil. Raises InvalidPath if `path` does not appear to be a valid path.

check_directory_tree_permissions(dir)

Checks the permissions of all parent directories of `dir` as well as `dir` itself.

`dir` must be a canonical path.

If one of the parent directories has wrong permissions, causing `dir` to be inaccessible by the current process, then this function returns [path, true] where `path` is the path of the top-most directory with wrong permissions.

If `dir` itself is not executable by the current process then this function returns [dir, false].

Otherwise, nil is returned.

close_all_io_objects_for_fds(file_descriptors_to_leave_open)
connect_to_server(address)
generate_random_id(method)

Generate a long, cryptographically secure random ID string, which is also a valid filename.

get_socket_address_type(address)
global_backtrace_report()

Returns a string which reports the backtraces for all threads, or if that‘s not supported the backtrace for the current thread.

local_socket_address?(address)
lower_privilege(startup_file, options)

Lowers the current process‘s privilege based on the documented rules for the "user", "group", "default_user" and "default_group" options.

marshal_exception(exception)
passenger_tmpdir(create = true)
prepare_app_process(startup_file, options)

Prepare an application process using rules for the given spawn options. This method is to be called before loading the application code.

`startup_file` is the application type‘s startup file, e.g. "config/environment.rb" for Rails apps and "config.ru" for Rack apps. See SpawnManager#spawn_application for options.

This function may modify `options`. The modified options are to be passed to the request handler.

print_exception(current_location, exception, destination = nil)

Print the given exception, including the stack trace, to STDERR.

`current_location` is a string which describes where the code is currently at. Usually the current class name will be enough.

private_class_method(name)
process_is_alive?(pid)

Checks whether the given process exists.

report_app_init_status(channel, sink = STDERR) {|| ...}

Run the given block. A message will be sent through `channel` (a MessageChannel object), telling the remote side whether the block raised an exception, called exit(), or succeeded.

If sink is non-nil, then every operation on $stderr/STDERR inside the block will be performed on sink as well. If sink is nil then all operations on $stderr/STDERR inside the block will be silently discarded, i.e. if one writes to $stderr/STDERR then nothing will be actually written to the console.

Returns whether the block succeeded, i.e. whether it didn‘t raise an exception.

Exceptions are not propagated, except SystemExit and a few non-StandardExeption classes such as SignalException. Of the exceptions that are propagated, only SystemExit will be reported.

safe_fork(current_location = self.class, double_fork = false) {|| ...}

Fork a new process and run the given block inside the child process, just like fork(). Unlike fork(), this method is safe, i.e. there‘s no way for the child process to escape the block. Any uncaught exceptions in the child process will be printed to standard output, citing `current_location` as the source. Futhermore, the child process will exit by calling Kernel#exit!, thereby bypassing any at_exit or ensure blocks.

If `double_fork` is true, then the child process will fork and immediately exit. This technique can be used to avoid zombie processes, at the expense of not being able to waitpid() the second child.

sanitize_spawn_options(options)
split_by_null_into_hash(data)

Split the given string into an hash. Keys and values are obtained by splitting the string using the null character as the delimitor.

split_by_null_into_hash(data)
to_boolean(value)
unmarshal_and_raise_errors(channel, print_exception = nil, app_type = "rails")

Receive status information that was sent to `channel` by report_app_init_status. If an error occured according to the received information, then an appropriate exception will be raised.

If `print_exception` evaluates to true, then the exception message and the backtrace will also be printed. Where it is printed to depends on the type of `print_exception`:

- If it responds to puts, then the exception information will be printed using this method.
- If it responds to to_str, then the exception information will be appended to the file whose filename equals the return value of the to_str call.
- Otherwise, it will be printed to STDERR.

Raises:

- AppInitError: this class wraps the exception information received through the channel.
- IOError, SystemCallError, SocketError: these errors are raised if an error occurred while receiving the information through the channel.

unmarshal_exception(data)

[Validate]