passenger 3.0.8 → 3.0.9

data/ext/common/Utils/MessageIO.h

@@ -0,0 +1,576 @@
+/*
+ *  Phusion Passenger - http://www.modrails.com/
+ *  Copyright (c) 2011 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_MESSAGE_IO_H_
+#define _PASSENGER_MESSAGE_IO_H_
+
+/**
+ * This file contains functions for reading and writing structured messages over
+ * I/O channels. Supported message types are as follows.
+ *
+ * == 16-bit and 32-bit integers
+ * Their raw formats are binary, in big endian.
+ *
+ * == Array of strings (array messages)
+ * Each string may contain arbitrary data except for the NUL byte.
+ * Its raw format consists of a 16-bit big endian size header
+ * and a body containing all the strings in the array, each terminated
+ * by a NUL byte. The size header specifies the raw size of the body.
+ *
+ * == Arbitary binary strings (scalar messages)
+ * Its raw format consists of a 32-bit big endian size header
+ * followed by the raw string data.
+ *
+ * == File descriptor passing and negotiation
+ * Unix socket file descriptor passing is not safe without some kind
+ * of negotiation protocol. If one side passes a file descriptor, and
+ * the other side accidentally read()s past the normal data then it
+ * will read away the passed file descriptor too without actually
+ * receiving it.
+ *
+ * For example suppose that side A looks like this:
+ *
+ *   read(fd, buf, 1024)
+ *   read_io(fd)
+ *
+ * and side B:
+ *
+ *   write(fd, buf, 100)
+ *   send_io(fd_to_pass)
+ *
+ * If B completes both write() and send_io(), then A's read() call
+ * reads past the 100 bytes that B sent. On some platforms, like
+ * Linux, this will cause read_io() to fail. And it just so happens
+ * that Ruby's IO#read method slurps more than just the given amount
+ * of bytes.
+ *
+ * In order to solve this problem, we wrap the actual file descriptor
+ * passing/reading code into a negotiation protocol to ensure that
+ * this situation can never happen.
+ */
+
+// For ntohl/htonl/ntohs/htons.
+#include <sys/types.h>
+#include <arpa/inet.h>
+#include <netinet/in.h>
+
+#include <algorithm>
+#include <string>
+#include <vector>
+#include <cstring>
+#include <cstdarg>
+
+#include <boost/cstdint.hpp>
+#include <boost/bind.hpp>
+#include <boost/scoped_array.hpp>
+
+#include <oxt/macros.hpp>
+
+#include <StaticString.h>
+#include <Exceptions.h>
+#include <Utils/MemZeroGuard.h>
+#include <Utils/ScopeGuard.h>
+#include <Utils/IOUtils.h>
+#include <Utils/StrIntUtils.h>
+
+
+namespace Passenger {
+
+using namespace std;
+using namespace boost;
+
+/**
+ * Reads a 16-bit unsigned integer from the given file descriptor. The result
+ * is put into 'output'.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @return True if reading was successful, false if end-of-file was prematurely reached.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline bool
+readUint16(int fd, uint16_t &output, unsigned long long *timeout = NULL) {
+	uint16_t temp;
+	
+	if (readExact(fd, &temp, sizeof(uint16_t), timeout) == sizeof(uint16_t)) {
+		output = ntohs(temp);
+		return true;
+	} else {
+		return false;
+	}
+}
+
+/**
+ * Reads a 16-bit unsigned integer from the given file descriptor.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws EOFException End-of-file was reached before a full integer could be read.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline uint16_t
+readUint16(int fd, unsigned long long *timeout = NULL) {
+	uint16_t temp;
+	
+	if (readUint16(fd, temp, timeout)) {
+		return temp;
+	} else {
+		throw EOFException("EOF encountered before a full 16-bit integer could be read");
+	}
+}
+
+/**
+ * Reads a 32-bit unsigned integer from the given file descriptor. The result
+ * is put into 'output'.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @return True if reading was successful, false if end-of-file was prematurely reached.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline bool
+readUint32(int fd, uint32_t &output, unsigned long long *timeout = NULL) {
+	uint32_t temp;
+	
+	if (readExact(fd, &temp, sizeof(uint32_t), timeout) == sizeof(uint32_t)) {
+		output = ntohl(temp);
+		return true;
+	} else {
+		return false;
+	}
+}
+
+/**
+ * Reads a 32-bit unsigned integer from the given file descriptor.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws EOFException End-of-file was reached before a full integer could be read.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline uint32_t
+readUint32(int fd, unsigned long long *timeout = NULL) {
+	uint32_t temp;
+	
+	if (readUint32(fd, temp, timeout)) {
+		return temp;
+	} else {
+		throw EOFException("EOF encountered before a full 32-bit integer could be read");
+	}
+}
+
+
+/**
+ * Reads an array message from the given file descriptor. This version
+ * puts the result into the given collection instead of returning a
+ * new collection.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @return True if an array message was read, false if end-of-file was reached
+ *         before a full array message could be read.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+template<typename Collection>
+inline bool
+readArrayMessage(int fd, Collection &output, unsigned long long *timeout = NULL) {
+	uint16_t size;
+	if (!readUint16(fd, size, timeout)) {
+		return false;
+	}
+	
+	scoped_array<char> buffer(new char[size]);
+	MemZeroGuard g(buffer.get(), size);
+	if (readExact(fd, buffer.get(), size, timeout) != size) {
+		return false;
+	}
+	
+	output.clear();
+	if (size != 0) {
+		string::size_type start = 0, pos;
+		StaticString buffer_str(buffer.get(), size);
+		while ((pos = buffer_str.find('\0', start)) != string::npos) {
+			output.push_back(buffer_str.substr(start, pos - start));
+			start = pos + 1;
+		}
+	}
+	return true;
+}
+
+/**
+ * Reads an array message from the given file descriptor. This version returns
+ * the result immediately as a string vector.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws EOFException End-of-file was reached before a full integer could be read.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline vector<string>
+readArrayMessage(int fd, unsigned long long *timeout = NULL) {
+	vector<string> output;
+	
+	if (readArrayMessage(fd, output, timeout)) {
+		return output;
+	} else {
+		throw EOFException("EOF encountered before the full array message could be read");
+	}
+}
+
+
+/**
+ * Reads a scalar message from the given file descriptor.
+ *
+ * @param maxSize The maximum number of bytes that may be read. If the
+ *                scalar to read is larger than this, then a SecurityException
+ *                will be thrown. Set to 0 for no size limit.
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on reading the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on reading will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws EOFException End-of-file was reached before a full integer could be read.
+ * @throws SystemException Something went wrong.
+ * @throws SecurityException The message body is larger than allowed by maxSize.
+ * @throws TimeoutException Unable to read the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline string
+readScalarMessage(int fd, unsigned int maxSize = 0, unsigned long long *timeout = NULL) {
+	uint32_t size;
+	if (!readUint32(fd, size, timeout)) {
+		throw EOFException("EOF encountered before a 32-bit scalar message header could be read");
+	}
+	
+	if (maxSize != 0 && size > (uint32_t) maxSize) {
+		throw SecurityException("The scalar message body is larger than the size limit");
+	}
+	
+	string output;
+	unsigned int remaining = size;
+	output.reserve(size);
+	if (OXT_LIKELY(remaining > 0)) {
+		char buf[1024 * 32];
+		MemZeroGuard g(buf, sizeof(buf));
+		
+		while (remaining > 0) {
+			unsigned int blockSize = min((unsigned int) sizeof(buf), remaining);
+			
+			if (readExact(fd, buf, blockSize, timeout) != blockSize) {
+				throw EOFException("EOF encountered before the full scalar message body could be read");
+			}
+			output.append(buf, blockSize);
+			remaining -= blockSize;
+		}
+	}
+	return output;
+}
+
+
+/**
+ * Writes a 16-bit unsigned integer to the given file descriptor.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on writing the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on writing will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to write the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline void
+writeUint16(int fd, uint16_t value, unsigned long long *timeout = NULL) {
+	uint16_t l = htons(value);
+	writeExact(fd, &l, sizeof(uint16_t), timeout);
+}
+
+/**
+ * Writes a 32-bit unsigned integer to the given file descriptor.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on writing the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on writing will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to write the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline void
+writeUint32(int fd, uint32_t value, unsigned long long *timeout = NULL) {
+	uint32_t l = htonl(value);
+	writeExact(fd, &l, sizeof(uint32_t), timeout);
+}
+
+
+/**
+ * Writes an array message to the given file descriptor.
+ *
+ * @param args A collection of strings containing the array message's elements.
+ *             The collection must have an STL container-like interface and
+ *             the strings must have an STL string-like interface.
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on writing the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on writing will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to write the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+template<typename Collection>
+inline void
+writeArrayMessage(int fd, const Collection &args, unsigned long long *timeout = NULL) {
+	typename Collection::const_iterator it, end = args.end();
+	uint16_t bodySize = 0;
+	
+	for (it = args.begin(); it != end; it++) {
+		bodySize += it->size() + 1;
+	}
+	
+	scoped_array<char> data(new char[sizeof(uint16_t) + bodySize]);
+	uint16_t header = htons(bodySize);
+	memcpy(data.get(), &header, sizeof(uint16_t));
+	
+	char *dataEnd = data.get() + sizeof(uint16_t);
+	for (it = args.begin(); it != end; it++) {
+		memcpy(dataEnd, it->data(), it->size());
+		dataEnd += it->size();
+		*dataEnd = '\0';
+		dataEnd++;
+	}
+	
+	writeExact(fd, data.get(), sizeof(uint16_t) + bodySize, timeout);
+}
+
+inline void
+writeArrayMessage(int fd, const StaticString &name, va_list &ap, unsigned long long *timeout = NULL) {
+	vector<StaticString> args;
+	
+	args.push_back(name);
+	while (true) {
+		const char *arg = va_arg(ap, const char *);
+		if (arg == NULL) {
+			break;
+		} else {
+			args.push_back(arg);
+		}
+	}
+	writeArrayMessage(fd, args, timeout);
+}
+
+struct _VaGuard {
+	va_list &ap;
+	
+	_VaGuard(va_list &_ap)
+		: ap(_ap)
+		{ }
+	
+	~_VaGuard() {
+		va_end(ap);
+	}
+};
+
+/** Version of writeArrayMessage() that accepts a variadic list of 'const char *'
+ * arguments as message elements. The list must be terminated with a NULL.
+ */
+inline void
+writeArrayMessage(int fd, const StaticString &name, ...) {
+	va_list ap;
+	va_start(ap, name);
+	_VaGuard guard(ap);
+	writeArrayMessage(fd, name, ap);
+}
+
+/** Version of writeArrayMessage() that accepts a variadic list of 'const char *'
+ * arguments as message elements, with timeout support. The list must be terminated
+ * with a NULL.
+ */
+inline void
+writeArrayMessage(int fd, unsigned long long *timeout, const StaticString &name, ...) {
+	va_list ap;
+	va_start(ap, name);
+	_VaGuard guard(ap);
+	writeArrayMessage(fd, name, ap, timeout);
+}
+
+/**
+ * Writes a scalar message to the given file descriptor.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on writing the necessary data.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on writing will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to write the necessary data within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline void
+writeScalarMessage(int fd, const StaticString &data, unsigned long long *timeout = NULL) {
+	uint32_t header = htonl(data.size());
+	StaticString buffers[2] = {
+		StaticString((const char *) &header, sizeof(uint32_t)),
+		data
+	};
+	gatheredWrite(fd, buffers, 2, timeout);
+}
+
+inline void
+writeScalarMessage(int fd, const char *data, size_t size, unsigned long long *timeout = NULL) {
+	writeScalarMessage(fd, StaticString(data, size), timeout);
+}
+
+
+/**
+ * Receive a file descriptor over the given Unix domain socket,
+ * involving a negotiation protocol.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on receiving the file descriptor.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on receiving will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @return The received file descriptor.
+ * @throws SystemException Something went wrong.
+ * @throws IOException Whatever was received doesn't seem to be a
+ *                     file descriptor.
+ * @throws TimeoutException Unable to receive a file descriptor within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline int
+readFileDescriptorWithNegotiation(int fd, unsigned long long *timeout = NULL) {
+	writeArrayMessage(fd, timeout, "pass IO", NULL);
+	int result = readFileDescriptor(fd, timeout);
+	ScopeGuard guard(boost::bind(safelyClose, result));
+	writeArrayMessage(fd, timeout, "got IO", NULL);
+	guard.clear();
+	return result;
+}
+
+
+/**
+ * Pass the file descriptor 'fdToSend' over the Unix socket 'fd',
+ * involving a negotiation protocol.
+ *
+ * @param timeout A pointer to an integer, which specifies the maximum number of
+ *                microseconds that may be spent on trying to pass the file descriptor.
+ *                If the timeout expired then TimeoutException will be thrown.
+ *                If this function returns without throwing an exception, then the
+ *                total number of microseconds spent on writing will be deducted
+ *                from <tt>timeout</tt>.
+ *                Pass NULL if you do not want to enforce a timeout.
+ * @throws SystemException Something went wrong.
+ * @throws TimeoutException Unable to pass the file descriptor within
+ *                          <tt>timeout</tt> microseconds.
+ * @throws boost::thread_interrupted
+ */
+inline void
+writeFileDescriptorWithNegotiation(int fd, int fdToPass, unsigned long long *timeout = NULL) {
+	vector<string> args;
+	
+	args = readArrayMessage(fd, timeout);
+	if (args.size() != 1 || args[0] != "pass IO") {
+		throw IOException("FD passing pre-negotiation message expected");
+	}
+	
+	writeFileDescriptor(fd, fdToPass, timeout);
+	
+	args = readArrayMessage(fd, timeout);
+	if (args.size() != 1 || args[0] != "got IO") {
+		throw IOException("FD passing post-negotiation message expected.");
+	}
+}
+
+
+} // namespace Passenger
+
+#endif /* _PASSENGER_MESSAGE_IO_H_ */