passenger 5.0.25 → 5.0.26

data/src/cxx_supportlib/ResourceLocator.h

@@ -60,6 +60,7 @@ private:
 	string docDir;
 	string rubyLibDir;
 	string nodeLibDir;
+	string buildSystemDir;
 
 	static string getOption(const string &file, const IniFileSectionPtr &section, const string &key) {
 		if (section->hasKey(key)) {
@@ -69,13 +70,20 @@ private:
 		}
 	}
 
+	static string getOptionalSection(const string &file, const IniFileSectionPtr &section, const string &key) {
+		if (section->hasKey(key)) {
+			return section->get(key);
+		} else {
+			return string();
+		}
+	}
+
 public:
 	ResourceLocator() { }
 
-	ResourceLocator(const string &rootOrFile) {
-		root = rootOrFile;
-		if (getFileType(rootOrFile) == FT_REGULAR) {
-			string file = rootOrFile;
+	ResourceLocator(const string &installSpec) {
+		if (getFileType(installSpec) == FT_REGULAR) {
+			const string &file = installSpec;
 			IniFileSectionPtr options = IniFile(file).section("locations");
 			binDir              = getOption(file, options, "bin_dir");
 			supportBinariesDir  = getOption(file, options, "support_binaries_dir");
@@ -84,8 +92,9 @@ public:
 			docDir              = getOption(file, options, "doc_dir");
 			rubyLibDir          = getOption(file, options, "ruby_libdir");
 			nodeLibDir          = getOption(file, options, "node_libdir");
+			buildSystemDir      = getOptionalSection(file, options, "node_libdir");
 		} else {
-			string root = rootOrFile;
+			const string &root = installSpec;
 			binDir              = root + "/bin";
 			supportBinariesDir  = root + "/buildout/support-binaries";
 			helperScriptsDir    = root + "/src/helper-scripts";
@@ -93,14 +102,19 @@ public:
 			docDir              = root + "/doc";
 			rubyLibDir          = root + "/src/ruby_supportlib";
 			nodeLibDir          = root + "/src/nodejs_supportlib";
+			buildSystemDir      = root;
 		}
 	}
 
-	string getRoot() const {
+	const string &getRoot() const {
 		return root;
 	}
 
-	string getSupportBinariesDir() const {
+	const string &getBinDir() const {
+		return binDir;
+	}
+
+	const string &getSupportBinariesDir() const {
 		return supportBinariesDir;
 	}
 
@@ -132,27 +146,31 @@ public:
 		return result;
 	}
 
-	string getHelperScriptsDir() const {
+	const string &getHelperScriptsDir() const {
 		return helperScriptsDir;
 	}
 
-	string getResourcesDir() const {
+	const string &getResourcesDir() const {
 		return resourcesDir;
 	}
 
-	string getDocDir() const {
+	const string &getDocDir() const {
 		return docDir;
 	}
 
-	// Can be empty.
-	string getRubyLibDir() const {
+	const string &getRubyLibDir() const {
 		return rubyLibDir;
 	}
 
-	string getNodeLibDir() const {
+	const string &getNodeLibDir() const {
 		return nodeLibDir;
 	}
 
+	// Can be empty.
+	const string &getBuildSystemDir() const {
+		return buildSystemDir;
+	}
+
 	string findSupportBinary(const string &name) {
 		string path = getSupportBinariesDir() + "/" + name;
 		bool found;
@@ -170,7 +188,8 @@ public:
 			return path;
 		}
 
-		throw RuntimeException("Support binary " + name + " not found (tried: " + getSupportBinariesDir() + "/" + name + " and " + path + ")");
+		throw RuntimeException("Support binary " + name + " not found (tried: "
+			+ getSupportBinariesDir() + "/" + name + " and " + path + ")");
 	}
 };
 

data/src/cxx_supportlib/ServerKit/Channel.h

@@ -1,6 +1,6 @@
 /*
  *  Phusion Passenger - https://www.phusionpassenger.com/
- *  Copyright (c) 2014 Phusion Holding B.V.
+ *  Copyright (c) 2014-2016 Phusion Holding B.V.
  *
  *  "Passenger", "Phusion Passenger" and "Union Station" are registered
  *  trademarks of Phusion Holding B.V.
@@ -58,8 +58,20 @@ using namespace boost;
  *
  * Writing all this code is complicated, error-prone, its flow is hard to test (because
  * it depends on network conditions), and it's ridden with boilerplate. The Channel class
- * solves this problem with a nice abstraction. First, you attach a data callback to a
- * Channel. Whatever is written to the Channel, will be forwarded to the data callback.
+ * solves this problem with a nice abstraction. A Channel is used in combination with a
+ * callback. Channel allows you to:
+ *
+ *  - Pass data to the callback, which can consume the data at its own pace.
+ *  - Be notified when the data has fully consumed by the callback.
+ *  - Be notified when the callback is refusing to consume further data (e.g. because
+ *    it is done consuming or because it has encountered an error).
+ *  - Pass error conditions to the callback.
+ *
+ *
+ * ## Typical usage
+ *
+ * First, you attach a data callback to a Channel. Whatever is written to the Channel
+ * will be forwarded to the data callback.
  *
  * The data callback can consume the buffer immediately, and tell Channel how many bytes
  * it has consumed, and whether it accepts any further data, by returning a Channel::Result.
@@ -131,11 +143,21 @@ using namespace boost;
  *     {
  *         if (buffer.size() > 0) {
  *             int bytesProcessed;
+ *             int errcode;
  *             bool acceptFurtherData;
  *
  *             ...process buffer....
  *
- *             return Channel::Result(bytesProcessed, !acceptFurtherData);
+ *             if (errcode == 0) {
+ *                 // Everything OK.
+ *                 return Channel::Result(bytesProcessed, !acceptFurtherData);
+ *             } else {
+ *                 // An error occurred.
+ *                 feedError(errcode);
+ *                 // If you called feedError() then it doesn't matter what
+ *                 // you return.
+ *                 return Channel::Result(0, false);
+ *             }
  *         } else if (errcode == 0) {
  *             // EOF reached. Result doesn't matter in this case.
  *             return Channel::Result(0, false);
@@ -146,12 +168,66 @@ using namespace boost;
  *         }
  *     }
  *
- * A good example of this is FdInputChannel. It reads data from a file descriptor using
+ * ### Recommended example: FdSourceChannel
+ *
+ * A good example is FdSourceChannel. It reads data from a file descriptor using
  * `read()`, then writes them to a Channel. It stops reading from the file descriptor
  * when the Channel is not accepting reads, and it starts reading from the file
  * descriptor when the channel is accepting reads again.
  *
- * ## Asynchronous consumption
+ *
+ * ## The data callback
+ *
+ * The data callback is called when the Channel wants to pass data to the callback,
+ * or when the channel wants to notify the callback of an error.
+ *
+ * ### Arguments
+ *
+ *  - `channel` -- the Channel object that called it.
+ *  - `buffer` -- a buffer containing data. This buffer may be empty because
+ *    the writer called `channel.feed()` with an empty buffer, or because of
+ *    an error.
+ *  - `error` -- an error code. A value of 0 means that there is no error. All
+ *    other values indicate an error.
+ *
+ *  If an error occurred then the buffer is always empty. If the buffer is non-empty
+ *  then errcode is always zero.
+ *
+ *  Be sure to check for errors correctly: you may only use `buffer` if `errcode` is 0.
+ *
+ * ### Returning consumption result
+ *
+ * The data callback is to return a `Channel::Result` object in order to tell Channel
+ * how many bytes have been consumed (the `consumed` field), and whether it accepts
+ * further data (the `end` field).
+ *
+ * Returning `end == true` will set the Channel to the "end acknowledged" state. This
+ * causes the Channel to stop accepting and/or forwarding further data or error to the
+ * callback (even if there is pending unconsumed data). The writer can detect this state
+ * by calling:
+ *
+ *  - `channel.acceptingInput()` -- will return false.
+ *  - `channel.mayAcceptInputLater()` -- will return false.
+ *  - `channel.ended()` -- will return true.
+ *  - `channel.endAcked()` -- will return true.
+ *  - `channel.hasError()` -- will return false.
+ *
+ * ### Returning error result
+ *
+ * The data callback can tell the Channel that an error during consumption has occurred
+ * by calling `channel.feedError()` with a non-zero error code. Once `feedError()` has
+ * been called, it doesn't matter what the data callback returns: anything is fine.
+ * The Channel will enter the "end acknowledged with error" state and/or will stop
+ * forwarding further data or error to the callback (even if there is pending unconsumed
+ * data). The writer will observe:
+ *
+ *  - `channel.acceptingInput()` -- will return false.
+ *  - `channel.mayAcceptInputLater()` -- will return false.
+ *  - `channel.ended()` -- will return true.
+ *  - `channel.endAcked()` -- will return true.
+ *  - `channel.hasError()` -- will return true.
+ *
+ * ### Asynchronous consumption
  *
  * The data callback can also tell Channel that it wants to consume the buffer
  * *asynchronously*, by returning a Channel::Result with a negative consumption size.
@@ -159,7 +235,22 @@ using namespace boost;
  * by calling `channel.consumed()`. Until that happens, the Channel will tell the
  * writer that it is not accepting any new data, so that the writer can stop writing
  * temporarily. When the buffer is consumed, the Channel notifies the writer about
- * this so that it can continue writing.
+ * this (via `consumedCallback`) so that it can continue writing.
+ *
+ * The arguments passed to `channel.consumed()` are the same as those used to create
+ * a `Channel::Result`. The `size` arguments tells Channel how many bytes have been
+ * consumed. The `end` argument tells whether the callback is done consuming.
+ *
+ * If Channel has no further pending data to be passed to the callback, then Channel
+ * immediately calls `consumedCallback`. Otherwise, Channel will pass the remaining
+ * data in the next event loop iteration.
+ *
+ * ### Asynchronous consumption error reporting
+ *
+ * If you are using asynchronous consumption (by returning a Channel::Result with a
+ * negative consumption size) then the way to signal a consumption error is by calling
+ * `channel.feedError()` instead of calling `channel.consumed()`. This will cause the
+ * channel to immediately enter the "end acknowledged with error" state.
  */
 class Channel: public boost::noncopyable {
 public:
@@ -232,19 +323,20 @@ public:
 		 * An end-of-file or error has been passed to the callback, and we're
 		 * now waiting for the callback to return.
 		 */
-		CALLING_WITH_EOF,
+		CALLING_WITH_EOF_OR_ERROR,
 
 		/**
 		 * An end-of-file or error has been passed to the callback, but the
-		 * callback hasn't called `consumed()` yet.
+		 * callback hasn't called `consumed()` yet. We're now waiting for
+		 * that call.
 		 */
-		EOF_WAITING,
+		WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR,
 
 		/**
 		 * An end-of-file or error has been passed to the callback, and the
 		 * callback has returned and completed.
 		 */
-		EOF_REACHED
+		EOF_OR_ERROR_ACKNOWLEDGED
 	};
 
 protected:
@@ -270,9 +362,9 @@ protected:
 
 		begin:
 
-		assert(state == CALLING || state == CALLING_WITH_EOF);
+		assert(state == CALLING || state == CALLING_WITH_EOF_OR_ERROR);
 		assert(state != CALLING || !buffer.empty());
-		assert(state != CALLING_WITH_EOF || buffer.empty());
+		assert(state != CALLING_WITH_EOF_OR_ERROR || buffer.empty());
 
 		{
 			// Make a copy of the buffer so that if the callback calls
@@ -291,7 +383,7 @@ protected:
 		assert(state != STOPPED);
 		assert(state != STOPPED_WHILE_WAITING);
 		assert(state != PLANNING_TO_CALL);
-		assert(state != EOF_WAITING);
+		assert(state != WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR);
 
 		if (cbResult.consumed >= 0) {
 			bytesConsumed += cbResult.consumed;
@@ -305,7 +397,7 @@ protected:
 			switch (state) {
 			case CALLING:
 				if (cbResult.end) {
-					state = EOF_REACHED;
+					state = EOF_OR_ERROR_ACKNOWLEDGED;
 					callConsumedCallback();
 					return bytesConsumed;
 				} else if (buffer.empty()) {
@@ -325,21 +417,20 @@ protected:
 				}
 			case STOPPED_WHILE_CALLING:
 				if (cbResult.end) {
-					state = EOF_REACHED;
+					state = EOF_OR_ERROR_ACKNOWLEDGED;
 					callConsumedCallback();
 					return bytesConsumed;
 				} else {
 					state = STOPPED;
 					return -1;
 				}
-			case CALLING_WITH_EOF:
-				state = EOF_REACHED;
+			case CALLING_WITH_EOF_OR_ERROR:
+				state = EOF_OR_ERROR_ACKNOWLEDGED;
 				callConsumedCallback();
 				return bytesConsumed;
-			case EOF_REACHED:
+			case EOF_OR_ERROR_ACKNOWLEDGED:
 				// feedError() called inside callback, so we
 				// don't callConsumedCallback() here.
-				state = EOF_REACHED;
 				return bytesConsumed;
 			default:
 				P_BUG("Unknown state" << toString((int) state));
@@ -354,9 +445,9 @@ protected:
 			case STOPPED_WHILE_CALLING:
 				state = STOPPED_WHILE_WAITING;
 				break;
-			case CALLING_WITH_EOF:
-			case EOF_REACHED:
-				state = EOF_WAITING;
+			case CALLING_WITH_EOF_OR_ERROR:
+			case EOF_OR_ERROR_ACKNOWLEDGED:
+				state = WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR;
 				break;
 			default:
 				P_BUG("Unknown state" << toString((int) state));
@@ -407,7 +498,7 @@ public:
 	 * you call `setContext()`.
 	 */
 	Channel()
-		: state(EOF_REACHED),
+		: state(EOF_OR_ERROR_ACKNOWLEDGED),
 		  planId(0),
 		  errcode(0),
 		  generation(0),
@@ -473,7 +564,8 @@ public:
 	}
 
 	/**
-	 * Feed data to the Channel. The data will be passed to the callback.
+	 * Feed data to the Channel. The data will be passed to the callback. You can signal
+	 * EOF by feeding an empty buffer.
 	 *
 	 * @pre acceptingInput()
 	 */
@@ -503,7 +595,7 @@ public:
 		P_ASSERT_EQ(state, IDLE);
 		P_ASSERT_EQ(bytesConsumed, 0);
 		if (mbuf.empty()) {
-			state = CALLING_WITH_EOF;
+			state = CALLING_WITH_EOF_OR_ERROR;
 		} else {
 			state = CALLING;
 		}
@@ -514,37 +606,54 @@ public:
 	/**
 	 * Tell the Channel that an error has occurred.
 	 *
-	 * If this method is called while the data callback is not active, and the
-	 * channel is idle, then the error will be passed to the callback immediately.
-	 * Otherwise (if the channel isn't idle), it will be passed to the callback
-	 * when the channel becomes idle.
+	 * This method can be called with two purposes. You can either use it to
+	 * pass an error to the data callback, or you can use it to register an
+	 * error that occurred inside the data callback (a consumption error).
+	 *
+	 * ## Passing an error to the data callback
+	 *
+	 * If you want to pass an error to the data callback then you can only do that
+	 * when `acceptingInput()` is true. Calling `feedError()` in this state will
+	 * call the data callback immediately.
+	 *
+	 * ## Registering a consumption error
+	 *
+	 * The data callback can tell the Channel about a consumption error by calling
+	 * this method inside the data callback, or (if the data callback is using
+	 * asynchronous consumption by having returned -1) by calling this method
+	 * in place of `consumed()`.
 	 *
-	 * If this method is called inside the data callback, or (if the data callback returned -1)
-	 * when the data callback hasn't called `consumed()` yet, then the channel transitions
-	 * to the end state immediately, and stops calling the data callback even when the
-	 * current invocation of the data callback doesn't fully consume the buffer.
+	 * ## Effect
 	 *
-	 * Once an error has been fed, no more data will be accepted by `feed()`.
+	 * In both of the above cases, the Channel will begin transitioning to an end error state:
+	 *
+	 *   acceptingInput() -- will return false.
+	 *   mayAcceptInputLater() -- will return false.
+	 *   ended() -- will return true.
+	 *   endAcked() -- depending on the situation, will return true immediately,
+	 *                 or will return true eventually.
+	 *   hasError() -- will return true.
+	 *
+	 * No more data will be accepted by `feed()`.
 	 */
 	void feedError(int errcode) {
 		assert(errcode != 0);
 		switch (state) {
 		case IDLE:
 			this->errcode = errcode;
-			state = CALLING_WITH_EOF;
+			state = CALLING_WITH_EOF_OR_ERROR;
 			callDataCallback();
 			break;
 		case CALLING:
 		case WAITING_FOR_CALLBACK:
-		case CALLING_WITH_EOF:
-		case EOF_WAITING:
+		case CALLING_WITH_EOF_OR_ERROR:
+		case WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR:
 			this->errcode = errcode;
-			state = EOF_REACHED;
+			state = EOF_OR_ERROR_ACKNOWLEDGED;
 			callConsumedCallback();
 			break;
-		case EOF_REACHED:
+		case EOF_OR_ERROR_ACKNOWLEDGED:
 			this->errcode = errcode;
-			state = EOF_REACHED;
 			break;
 		case STOPPED:
 		case STOPPED_WHILE_CALLING:
@@ -556,7 +665,7 @@ public:
 			ctx->libev->cancelCommand(planId);
 			planId = 0;
 			this->errcode = errcode;
-			state = EOF_REACHED;
+			state = EOF_OR_ERROR_ACKNOWLEDGED;
 			callConsumedCallback();
 			break;
 		default:
@@ -574,9 +683,9 @@ public:
 		case CALLING:
 		case PLANNING_TO_CALL:
 		case WAITING_FOR_CALLBACK:
-		case CALLING_WITH_EOF:
-		case EOF_WAITING:
-		case EOF_REACHED:
+		case CALLING_WITH_EOF_OR_ERROR:
+		case WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR:
+		case EOF_OR_ERROR_ACKNOWLEDGED:
 			break;
 		case STOPPED:
 			planNextActivity();
@@ -602,9 +711,9 @@ public:
 		case STOPPED:
 		case STOPPED_WHILE_CALLING:
 		case STOPPED_WHILE_WAITING:
-		case CALLING_WITH_EOF:
-		case EOF_WAITING:
-		case EOF_REACHED:
+		case CALLING_WITH_EOF_OR_ERROR:
+		case WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR:
+		case EOF_OR_ERROR_ACKNOWLEDGED:
 			break;
 		case IDLE:
 		case PLANNING_TO_CALL:
@@ -636,8 +745,8 @@ public:
 		assert(state != STOPPED);
 		assert(state != STOPPED_WHILE_CALLING);
 		assert(state != PLANNING_TO_CALL);
-		assert(state != CALLING_WITH_EOF);
-		assert(state != EOF_REACHED);
+		assert(state != CALLING_WITH_EOF_OR_ERROR);
+		assert(state != EOF_OR_ERROR_ACKNOWLEDGED);
 
 		size = std::min<unsigned int>(size, buffer.size());
 		bytesConsumed += size;
@@ -651,7 +760,7 @@ public:
 		switch (state) {
 		case WAITING_FOR_CALLBACK:
 			if (end) {
-				state = EOF_REACHED;
+				state = EOF_OR_ERROR_ACKNOWLEDGED;
 				callConsumedCallback();
 			} else {
 				planNextActivity();
@@ -659,14 +768,14 @@ public:
 			break;
 		case STOPPED_WHILE_WAITING:
 			if (end) {
-				state = EOF_REACHED;
+				state = EOF_OR_ERROR_ACKNOWLEDGED;
 				callConsumedCallback();
 			} else {
 				state = STOPPED;
 			}
 			break;
-		case EOF_WAITING:
-			state = EOF_REACHED;
+		case WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR:
+			state = EOF_OR_ERROR_ACKNOWLEDGED;
 			callConsumedCallback();
 			break;
 		default:
@@ -693,10 +802,13 @@ public:
 	 * Returns whether this Channel accepts more input right now.
 	 * There are three reasons why this might not be the case:
 	 *
-	 * 1. The callback isn't done yet.
-	 * 2. EOF has been fed, or the data callback has ended consumption.
-	 *    Use `ended()` to check for this.
-	 * 3. An error had been fed. Use `hasError()` to check for this.
+	 * 1. The callback isn't done yet, or the callback is done but the Channel
+	 *    isn't done updating internal book keeping yet. Use `mayAcceptInputLater()`
+	 *    to check for this.
+	 * 2. EOF has been fed (by passing an empty buffer to `feed()`), or the data callback
+	 *    has ended consumption (by returning a Channel::Result with end == true, or by calling
+	 *    consumed() with end == true). Use `ended()` to check for this.
+	 * 3. An error had been fed (using `feedError()`). Use `hasError()` to check for this.
 	 */
 	OXT_FORCE_INLINE
 	bool acceptingInput() const {
@@ -705,9 +817,9 @@ public:
 
 	/**
 	 * Returns whether this Channel's callback is currently processing the
-	 * fed data, and is not accepting any more input now, but may accept
-	 * more input later. You should wait for that event by setting
-	 * `consumedCallback`.
+	 * fed data, and is not accepting any more input now. However, no EOF or
+	 * error has been reported so far, so it may accept more input later. You
+	 * should wait for that event by setting `consumedCallback`.
 	 */
 	bool mayAcceptInputLater() const {
 		// Branchless code
@@ -715,9 +827,15 @@ public:
 	}
 
 	/**
-	 * Returns whether an error flag has been set. Note that this does not
-	 * necessarily mean that the callback has consumed the error yet.
-	 * Use `hasError() && endAcked()` to check for that.
+	 * Returns whether an error flag has been set. This happens if `feedError()`
+	 * was called.
+	 *
+	 * `hasError()` always implies `end()`.
+	 *
+	 * Note that `hasError()` does not necessarily mean that the callback has
+	 * consumed the error yet. The callback may be called at a later time to
+	 * notify it about the error. When the callback is done consuming the error,
+	 * `hasError() && endAcked()` will be true.
 	 */
 	OXT_FORCE_INLINE
 	bool hasError() const {
@@ -730,17 +848,28 @@ public:
 	}
 
 	/**
-	 * Returns whether the EOF flag has been set. Note that this does not
-	 * necessarily mean that the callback has consumed the EOF yet.
-	 * Use `endAcked()` to check for that.
+	 * Returns whether the EOF flag has been set. This happens if `feed()` was
+	 * called with an empty buffer.
+	 *
+	 * Note that this does not necessarily mean that the callback has consumed
+	 * the EOF yet. The callback may be called at a later time to notify it about
+	 * the EOF event. When the callback is done consuming the EOF event, `endAcked()`
+	 * will be true.
 	 */
 	bool ended() const {
-		return state == CALLING_WITH_EOF || state == EOF_WAITING || state == EOF_REACHED;
+		return state == CALLING_WITH_EOF_OR_ERROR
+			|| state == WAITING_FOR_CALLBACK_WITH_EOF_OR_ERROR
+			|| state == EOF_OR_ERROR_ACKNOWLEDGED;
 	}
 
+	/**
+	 * Returns whether the data callback has consumed an EOF event.
+	 *
+	 * `endAcked()` always implies `ended()`.
+	 */
 	OXT_FORCE_INLINE
 	bool endAcked() const {
-		return state == EOF_REACHED;
+		return state == EOF_OR_ERROR_ACKNOWLEDGED;
 	}
 
 	Json::Value inspectAsJson() const {