passenger-jmazzi 2.2.9

data/doc/users_guide_snippets/global_queueing_explained.txt

@@ -0,0 +1,78 @@
+.What does this option do?
+
+Recall that Phusion Passenger spawns multiple backend processes (e.g. multiple
+Ruby on Rails processes), each which processes HTTP requests serially. One of
+Phusion Passenger's jobs is to forward HTTP requests to a suitable backend
+process. A backend process may take an arbitrary amount of time to process a
+specific HTTP request. If the websites are (temporarily) under high load, and
+the backend processes cannot process the requests fast enough, then some
+requests may have to be queued.
+
+If global queuing is turned off, then Phusion Passenger will use 'fair load
+balancing'. This means that each backend process will have its own private
+queue. Phusion Passenger will forward an HTTP request to the backend process
+that has the least amount of requests in its queue.
+
+If global queuing is turned on, then Phusion Passenger will use a global queue
+that's shared between all backend processes. If an HTTP request comes in, and
+all the backend processes are still busy, then Phusion Passenger will wait until
+at least one backend process is done, and will then forward the request to that
+process.
+
+.When to turn on global queuing?
+
+You should turn on global queuing if one of your web applications may have
+long-running requests.
+
+For example suppose that:
+
+- global queuing is turned off.
+- we're currently in a state where all backend processes have 3 requests in
+  their queue, except for a single backend process, which has 1 request in its
+  queue.
+
+The situation looks like this:
+
+--------------------------------------------------
+Backend process A:  [*     ]  (1 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Each process is currently serving short-running requests.
+
+Phusion Passenger will forward the next request to backend process A. A will
+now have 2 items in its queue. We'll mark this new request with an X:
+
+--------------------------------------------------
+Backend process A:  [*X    ]  (2 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Assuming that B, C and D still aren't done with their current request, the next
+HTTP request - let's call this Y - will be forwarded to backend process A as
+well, because it has the least number of items in its queue:
+
+--------------------------------------------------
+Backend process A:  [*XY   ]  (3 requests in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+But if request X happens to be a long-running request that needs 60 seconds to
+complete, then we'll have a problem. Y won't be processed for at least 60
+seconds. It would have been a better idea if Y was forward to processes B, C or
+D instead, because they only have short-living requests in their queues.
+
+This problem will be avoided entirely if you turn global queuing on. With global
+queuing, all backend processes will share the same queue. The first backend
+process that becomes available will take from the queue, and so this
+``queuing-behind-long-running-request'' problem will never occur.
+
+Turning global queuing off will yield a minor performance improvement (about 5%,
+depending on how fast/slow your web application is), which is why it's off by
+default.

data/doc/users_guide_snippets/rackup_specifications.txt

@@ -0,0 +1,71 @@
+This subsection shows example 'config.ru' files for various web frameworks.
+
+==== Camping ====
+------------------------------------------------------
+require 'rubygems'
+require 'rack'
+require 'camping'
+
+##### Begin Camping application
+Camping.goes :Blog
+
+...your application code here...
+##### End Camping application
+
+run Rack::Adapter::Camping.new(Blog)
+------------------------------------------------------
+
+For Camping versions 2.0 and up, using `run Blog` as the final line will do.
+
+==== Halcyon ====
+------------------------------------------------------
+require 'rubygems'
+require 'halcyon'
+$LOAD_PATH.unshift(Halcyon.root / 'lib')
+Halcyon::Runner.load_config Halcyon.root/'config'/'config.yml'
+run Halcyon::Runner.new
+------------------------------------------------------
+
+==== Mack ====
+------------------------------------------------------
+ENV["MACK_ENV"] = ENV["RACK_ENV"]
+load("Rakefile")
+require 'rubygems'
+require 'mack'
+run Mack::Utils::Server.build_app
+------------------------------------------------------
+
+==== Merb ====
+------------------------------------------------------
+require 'rubygems'
+require 'merb-core'
+
+Merb::Config.setup(
+  :merb_root   => ::File.expand_path(::File.dirname(__FILE__)),
+  :environment => ENV['RACK_ENV']
+)
+Merb.environment = Merb::Config[:environment]
+Merb.root = Merb::Config[:merb_root]
+Merb::BootLoader.run
+
+run Merb::Rack::Application.new
+------------------------------------------------------
+
+==== Ramaze ====
+------------------------------------------------------
+require "rubygems"
+require "ramaze"
+Ramaze.trait[:essentials].delete Ramaze::Adapter
+require "start"
+Ramaze.start!
+run Ramaze::Adapter::Base
+------------------------------------------------------
+
+==== Sinatra ====
+------------------------------------------------------
+require 'rubygems'
+require 'sinatra'
+require 'app.rb'
+
+run Sinatra::Application
+------------------------------------------------------

data/doc/users_guide_snippets/rails_spawn_method.txt

@@ -0,0 +1,48 @@
+Internally, Phusion Passenger spawns multiple Ruby on Rails processes in order to handle
+requests. But there are multiple ways with which processes can be spawned, each having
+its own set of pros and cons. Supported spawn methods are:
+
+'smart'::
+When this spawn method is used, Phusion Passenger will attempt to cache Ruby on Rails
+framework code and application code for a limited period of time. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart spawning exactly does.
++
+*Pros:*
+This can significantly decrease spawn time (by as much as 90%). And, when Ruby Enterprise
+Edition is used, <<reducing_memory_usage,memory usage can be reduced by 33% on average>>.
++
+*Cons:*
+Some Ruby on Rails applications and libraries are not compatible with smart spawning.
+If that's the case for your application, then you should use 'conservative' as
+spawning method.
+
+'smart-lv2'::
+This spawning method is similar to 'smart' but it skips the framework spawner
+and uses the application spawner directly. This means the framework code is not
+cached between multiple applications, although it is still cached within
+instances of the same application. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart-lv2 spawning exactly does.
++
+*Pros:* It is compatible with a larger number of applications when compared to
+the 'smart' method, and still performs some caching.
++
+*Cons:* It is slower than smart spawning if you have many applications which
+use the same framework version. It is therefore advised that shared hosts use the
+'smart' method instead.
+
+'conservative'::
+This spawning method is similar to the one used in Mongrel Cluster. It does not
+perform any code caching at all. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what conservative spawning exactly does.
++
+*Pros:*
+Conservative spawning is guaranteed to be compatible with all Rails applications
+and libraries.
++
+*Cons:*
+Much slower than smart spawning. Every spawn action will be equally slow, though no slower than
+the startup time of a single server in Mongrel Cluster. Conservative spawning will also
+render <<reducing_memory_usage,Ruby Enterprise Edition's memory reduction technology>> useless.

data/doc/users_guide_snippets/tips.txt

@@ -0,0 +1,173 @@
+[[user_switching]]
+=== User switching (security) ===
+
+There is a problem that plagues most PHP web hosts, namely the fact that all PHP
+applications are run in the same user context as the web server. So for
+example, Joe's PHP application will be able to read Jane's PHP application's
+passwords. This is obviously undesirable on many servers.
+
+Phusion Passenger solves this problem by implementing 'user switching'. A Rails
+application is started as the owner of the file 'config/environment.rb',
+and a Rack application is started as the owner of the file 'config.ru'.
+So if '/home/webapps/foo/config/environment.rb' is owned by 'joe', then Phusion
+Passenger will launch the corresponding Rails application as 'joe' as well.
+
+This behavior is the default, and you don't need to configure anything. But
+there are things that you should keep in mind:
+
+- The owner of 'environment.rb' must have read access to the Rails application's
+  folder, and read/write access to the Rails application's 'logs' folder.
+  Likewise, the owner of 'config.ru' must have read access to the Rack application's
+  folder.
+- This feature is only available if Apache is started by 'root'. This is the
+  case on most Apache installations.
+- Under no circumstances will applications be run as 'root'. If
+  'environment.rb'/'config.ru' is owned as root or by an unknown user, then the
+  Rails/Rack application will run as the user specified by
+  <<PassengerDefaultUser,PassengerDefaultUser (Apache)>>/<<PassengerDefaultUser,passenger_default_user (Nginx)>>.
+
+User switching can be disabled with the
+<<PassengerUserSwitching,PassengerUserSwitching (Apache)>>/<<PassengerUserSwitching,passenger_user_switching (Nginx)>>
+option.
+
+
+[[reducing_memory_usage]]
+=== Reducing memory consumption of Ruby on Rails applications by 33% ===
+
+Is it possible to reduce memory consumption of your Rails applications by 33% on average,
+by using http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition].
+Please visit the website for details.
+
+Note that this feature does not apply to Rack applications.
+
+[[capistrano]]
+=== Capistrano recipe ===
+
+Phusion Passenger can be combined with link:http://capify.org/[Capistrano].
+The following Capistrano recipe demonstrates Phusion Passenger support.
+It assumes that you're using Git as version control system.
+
+--------------------------------------------------
+set :application, "myapp"
+set :domain,      "example.com"
+set :repository,  "ssh://#{domain}/path-to-your-git-repo/#{application}.git"
+set :use_sudo,    false
+set :deploy_to,   "/path-to-your-web-app-directory/#{application}"
+set :scm,         "git"
+
+role :app, domain
+role :web, domain
+role :db,  domain, :primary => true
+
+namespace :deploy do
+  task :start, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+  
+  task :stop, :roles => :app do
+    # Do nothing.
+  end
+  
+  desc "Restart Application"
+  task :restart, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+end
+--------------------------------------------------
+
+
+[[moving_phusion_passenger]]
+=== Moving Phusion Passenger to a different directory ===
+
+It is possible to relocate the Phusion Passenger files to a different directory. It
+involves two steps:
+
+1. Moving the directory.
+2. Updating the ``PassengerRoot'' configuration option in Apache.
+
+For example, if Phusion Passenger is located in '/opt/passenger/', and you'd like to
+move it to '/usr/local/passenger/', then do this:
+
+1. Run the following command:
++
+------------------------------------
+mv /opt/passenger /usr/local/passenger
+------------------------------------
+2. Edit your Apache configuration file, and set:
++
+------------------------------------
+PassengerRoot /usr/local/passenger
+------------------------------------
+
+=== Installing multiple Ruby on Rails versions ===
+
+Each Ruby on Rails applications that are going to be deployed may require a
+specific Ruby on Rails version. You can install a specific version with
+this command:
+-----------------------------
+gem install rails -v X.X.X
+-----------------------------
+where 'X.X.X' is the version number of Ruby on Rails.
+
+All of these versions will exist in parallel, and will not conflict with each
+other. Phusion Passenger will automatically make use of the correct version.
+
+=== Making the application restart after each request ===
+
+In some situations it might be desirable to restart the web application after
+each request, for example when developing a non-Rails application that doesn't
+support code reloading, or when developing a web framework.
+
+To achieve this, simply create the file 'tmp/always_restart.txt' in your
+application's root folder. Unlike 'restart.txt', Phusion Passenger does not
+check for this file's timestamp: Phusion Passenger will always restart the
+application, as long as 'always_restart.txt' exists.
+
+NOTE: If you're just developing a Rails application then you probably don't need
+this feature. If you set 'RailsEnv development' in your Apache configuration,
+then Rails will automatically reload your application code after each request.
+'always_restart.txt' is only useful if you're working on Ruby on Rails itself,
+or when you're not developing a Rails application and your web framework
+does not support code reloading.
+
+[[sub_uri_deployment_uri_fix]]
+=== How to fix broken images/CSS/JavaScript URIs in sub-URI deployments
+
+Some people experience broken images and other broken static assets when they
+deploy their application to a sub-URI (i.e. 'http://mysite.com/railsapp/').
+The reason for this usually is that you used a
+static URI for your image in the views. This means your 'img' source probably refers
+to something like '/images/foo.jpg'. The leading slash means that it's an absolute URI:
+you're telling the browser to always load 'http://mysite.com/images/foo.jpg' no
+matter what. The problem is that the image is actually at
+'http://mysite.com/railsapp/images/foo.jpg'. There are two ways to fix this.
+
+The first way (not recommended) is to change your view templates to refer to
+'images/foo.jpg'. This is a relative URI: note the lack of a leading slash). What
+this does is making the path relative to the current URI. The problem is that if you
+use restful URIs, then your images will probably break again when you add a level to
+the URI.
+For example, when you're at 'http://mysite.com/railsapp' the browser will look for
+'http://mysite.com/railsapp/images/foo.jpg'. But when you're at
+'http://mysite.com/railsapp/controller'. the browser will look for
+'http://mysite.com/railsapp/controller/images/foo.jpg'.
+So relative URIs usually don't work well with layout templates.
+
+The second and highly recommended way is to always use Rails helper methods to
+output tags for static assets. These helper methods automatically take care
+of prepending the base URI that you've deployed the application to. For images
+there is `image_tag`, for JavaScript there is `javascript_include_tag` and for
+CSS there is `stylesheet_link_tag`. In the above example you would simply remove
+the '<img>' HTML tag and replace it with inline Ruby like this:
+
+---------------------------------------
+<%= image_tag("foo.jpg") %>
+---------------------------------------
+
+This will generate the proper image tag to `$RAILS_ROOT/public/images/foo.jpg`
+so that your images will always work no matter what sub-URI you've deployed to.
+
+These helper methods are more valuable than you may think. For example they also
+append a timestamp to the URI to better facilitate HTTP caching. For more information,
+please refer to
+link:http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html[the Rails API docs].

data/ext/apache2/Bucket.cpp

@@ -0,0 +1,190 @@
+/*
+ *  Phusion Passenger - http://www.modrails.com/
+ *  Copyright (c) 2008, 2009 Phusion
+ *
+ *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
+ */
+#include "Bucket.h"
+
+namespace Passenger {
+
+static void bucket_destroy(void *data);
+static apr_status_t bucket_read(apr_bucket *a, const char **str, apr_size_t *len, apr_read_type_e block);
+
+static const apr_bucket_type_t apr_bucket_type_passenger_pipe = {
+	"PASSENGER_PIPE",
+	5,
+	apr_bucket_type_t::APR_BUCKET_DATA, 
+	bucket_destroy,
+	bucket_read,
+	apr_bucket_setaside_notimpl,
+	apr_bucket_split_notimpl,
+	apr_bucket_copy_notimpl
+};
+
+struct BucketData {
+	Application::SessionPtr session;
+	PassengerBucketStatePtr state;
+	int stream;
+	
+	~BucketData() {
+		/* The session here is an ApplicationPoolServer::RemoteSession.
+		 * The only reason why its destructor might fail is when sending
+		 * the 'close' command failed. We don't care about that, and we
+		 * don't want C++ exceptions to propagate onto a C stack (this
+		 * bucket is probably used by Apache's bucket brigade code, which
+		 * is written in C), so we ignore all errors in the session's
+		 * destructor.
+		 */
+		try {
+			session.reset();
+		} catch (const SystemException &e) {
+			// Do nothing.
+		}
+	}
+};
+
+static void
+bucket_destroy(void *data) {
+	BucketData *bucket_data = (BucketData *) data;
+	if (data != NULL) {
+		delete bucket_data;
+	}
+}
+
+static apr_status_t
+bucket_read(apr_bucket *bucket, const char **str, apr_size_t *len, apr_read_type_e block) {
+	char *buf;
+	ssize_t ret;
+	BucketData *data;
+	
+	data = (BucketData *) bucket->data;
+	*str = NULL;
+	*len = 0;
+	
+	if (block == APR_NONBLOCK_READ) {
+		/*
+		 * The bucket brigade that Hooks::handleRequest() passes using
+		 * ap_pass_brigade() is always passed through ap_content_length_filter,
+		 * which is a filter which attempts to read all data from the
+		 * bucket brigade and computes the Content-Length header from
+		 * that. We don't want this to happen; because suppose that the
+		 * Rails application sends back 1 GB of data, then
+		 * ap_content_length_filter will buffer this entire 1 GB of data
+		 * in memory before passing it to the HTTP client.
+		 *
+		 * ap_content_length_filter aborts and passes the bucket brigade
+		 * down the filter chain when it encounters an APR_EAGAIN, except
+		 * for the first read. So by returning APR_EAGAIN on every
+		 * non-blocking read request, we can prevent ap_content_length_filter
+		 * from buffering all data.
+		 */
+		return APR_EAGAIN;
+	}
+	
+	buf = (char *) apr_bucket_alloc(APR_BUCKET_BUFF_SIZE, bucket->list);
+	if (buf == NULL) {
+		return APR_ENOMEM;
+	}
+	
+	do {
+		ret = read(data->stream, buf, APR_BUCKET_BUFF_SIZE);
+	} while (ret == -1 && errno == EINTR);
+	
+	if (ret > 0) {
+		apr_bucket_heap *h;
+		
+		data->state->bytesRead += ret;
+		
+		*str = buf;
+		*len = ret;
+		bucket->data = NULL;
+		
+		/* Change the current bucket (which is a Passenger Bucket) into a heap bucket
+		 * that contains the data that we just read. This newly created heap bucket
+		 * will be the first in the bucket list.
+		 */
+		bucket = apr_bucket_heap_make(bucket, buf, *len, apr_bucket_free);
+		h = (apr_bucket_heap *) bucket->data;
+		h->alloc_len = APR_BUCKET_BUFF_SIZE; /* note the real buffer size */
+		
+		/* And after this newly created bucket we insert a new Passenger Bucket
+		 * which can read the next chunk from the stream.
+		 */
+		APR_BUCKET_INSERT_AFTER(bucket, passenger_bucket_create(
+			data->session, data->state, bucket->list));
+		
+		/* The newly created Passenger Bucket has a reference to the session
+		 * object, so we can delete data here.
+		 */
+		delete data;
+		
+		return APR_SUCCESS;
+		
+	} else if (ret == 0) {
+		data->state->completed = true;
+		delete data;
+		bucket->data = NULL;
+		
+		apr_bucket_free(buf);
+		
+		bucket = apr_bucket_immortal_make(bucket, "", 0);
+		*str = (const char *) bucket->data;
+		*len = 0;
+		return APR_SUCCESS;
+		
+	} else /* ret == -1 */ {
+		int e = errno;
+		data->state->completed = true;
+		data->state->errorCode = e;
+		delete data;
+		bucket->data = NULL;
+		apr_bucket_free(buf);
+		return APR_FROM_OS_ERROR(e);
+	}
+}
+
+static apr_bucket *
+passenger_bucket_make(apr_bucket *bucket, Application::SessionPtr session, PassengerBucketStatePtr state) {
+	BucketData *data = new BucketData();
+	data->session  = session;
+	data->stream   = session->getStream();
+	data->state    = state;
+	
+	bucket->type   = &apr_bucket_type_passenger_pipe;
+	bucket->length = (apr_size_t)(-1);
+	bucket->start  = -1;
+	bucket->data   = data;
+	return bucket;
+}
+
+apr_bucket *
+passenger_bucket_create(Application::SessionPtr session, PassengerBucketStatePtr state, apr_bucket_alloc_t *list) {
+	apr_bucket *bucket;
+	
+	bucket = (apr_bucket *) apr_bucket_alloc(sizeof(*bucket), list);
+	APR_BUCKET_INIT(bucket);
+	bucket->free = apr_bucket_free;
+	bucket->list = list;
+	return passenger_bucket_make(bucket, session, state);
+}
+
+} // namespace Passenger