colouringcode-passenger 0.1

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

data/ext/apache2/Bucket.h

@@ -0,0 +1,87 @@
+/*
+ *  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.
+ */
+#ifndef _PASSENGER_BUCKET_H_
+#define _PASSENGER_BUCKET_H_
+
+#include <boost/shared_ptr.hpp>
+#include <apr_buckets.h>
+#include "Application.h"
+
+namespace Passenger {
+
+using namespace boost;
+
+struct PassengerBucketState {
+	/** The number of bytes that this PassengerBucket has read so far. */
+	unsigned long bytesRead;
+	
+	/** Whether this PassengerBucket is completed, i.e. no more data
+	 * can be read from the underlying file descriptor. When true,
+	 * this can either mean that EOF has been reached, or that an I/O
+	 * error occured. Use errorCode to check whether an error occurred.
+	 */
+	bool completed;
+	
+	/** When completed is true, errorCode contains the errno value of
+	 * the last read() call.
+	 *
+	 * A value of 0 means that no error occured.
+	 */
+	int errorCode;
+	
+	PassengerBucketState() {
+		bytesRead = 0;
+		completed = false;
+		errorCode = 0;
+	}
+};
+
+typedef shared_ptr<PassengerBucketState> PassengerBucketStatePtr;
+
+/**
+ * We used to use an apr_bucket_pipe for forwarding the backend process's
+ * response to the HTTP client. However, apr_bucket_pipe has a number of
+ * issues:
+ * - It closes the pipe's file descriptor when it has reached
+ *   end-of-stream, but not when an error has occurred. This behavior is
+ *   undesirable because it can easily cause file descriptor leaks.
+ * - It does weird non-blocking-I/O related things which can cause it
+ *   to read less data than can actually be read.
+ *
+ * PassengerBucket is like apr_bucket_pipe, but:
+ * - It also holds a reference to a Session. When a read error has occured
+ *   or when end-of-stream has been reached, the Session will be
+ *   dereferenced, so that the underlying file descriptor is closed.
+ * - It ignores the APR_NONBLOCK_READ flag because that's known to cause
+ *   strange I/O problems.
+ * - It can store its current state in a PassengerBucketState data structure.
+ */
+apr_bucket *passenger_bucket_create(Passenger::Application::SessionPtr session,
+                                    PassengerBucketStatePtr state,
+                                    apr_bucket_alloc_t *list);
+
+} // namespace Passenger
+
+#endif /* _PASSENGER_BUCKET_H_ */