falcon 0.36.4 → 0.36.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f9ace03807f3082f7846ca48a45035c081304ed2c14b1d40a7ee175543b8953
-  data.tar.gz: 74256b53c57bf6319a2110931e501bee002613d15140a907639d423c93860f49
+  metadata.gz: f5f107eaf9cd170b5a399f5ad13222504f99e061292be94aab8720b7efa70c8b
+  data.tar.gz: 9787ecd87ba56f416b24abb02f55f16f7c3de3f3c89090c7724c63030995d8f7
 SHA512:
-  metadata.gz: 353e303f46674c05eb3477fa21e51a5e6caa6d85dfa49808221b093277c80b0cb14aa0e5b2409c5f5e5e6af409f67494985692fa1e49e588c1096e81667af469
-  data.tar.gz: 1039d5c30d9e826060c23f4c4a7f5916b48f55b2bdf89bd9269897e95178d17a97ffc902f6f4778bfce88572da3b35b00f29569a201501c92d78f153fb1b0e77
+  metadata.gz: '034873da8c3ca3e809bc3144879ab46521b63d279fc3622501b0ab6348d24a36428fa5d6285455091d8eb542ad5ae39b4b42a594efb6052b5b4632aed75d103b'
+  data.tar.gz: b7e68e1c275ee07ee752228ad04a90ea0da0a658f467030a4e849fc3c0661f78f706ea4243460da12cfe2e7610233d59c5ff0d91f0b5092e767d3f452f372567

data/lib/falcon/adapters/early_hints.rb

@@ -24,17 +24,25 @@ require 'protocol/http/middleware'
 
 module Falcon
 	module Adapters
+		# Provide an interface for advising the client to preload related resources.
 		class EarlyHints
 			PRELOAD = /<(?<path>.*?)>;.*?rel=preload/
 			
+			# Initialize the early hints interface.
+			#
+			# @parameter request [Protocol::HTTP::Request]
 			def initialize(request)
 				@request = request
 			end
 			
+			# Advise the request that the specified path should be preloaded.
+			# @parameter path [String]
+			# @parameter preload [Boolean] whether the client should preload the resource.
 			def push(path, preload: true, **options)
 				@request.push(path)
 			end
 			
+			# Extract link headers and invoke {push}.
 			def call(headers)
 				headers.each do |key, value|
 					if key.casecmp("link").zero? and match = PRELOAD.match(value)

data/lib/falcon/adapters/input.rb

@@ -25,8 +25,14 @@ require 'protocol/http/body/rewindable'
 
 module Falcon
 	module Adapters
-		# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be “ASCII-8BIT” and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
+		# Wraps a streaming input body into the interface required by `rack.input`.
+		#
+		# The input stream is an `IO`-like object which contains the raw HTTP POST data. When applicable, its external encoding must be `ASCII-8BIT` and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to `gets`, `each`, `read` and `rewind`.
+		#
+		# This implementation is not always rewindable, to avoid buffering the input when handling large uploads. See {Rewindable} for more details.
 		class Input
+			# Initialize the input wrapper.
+			# @parameter body [Protocol::HTTP::Body::Readable]
 			def initialize(body)
 				@body = body
 				
@@ -35,9 +41,13 @@ module Falcon
 				@finished = @body.nil?
 			end
 			
+			# The input body.
+			# @attribute [Protocol::HTTP::Body::Readable]
 			attr :body
 			
-			# each must be called without arguments and only yield Strings.
+			# Enumerate chunks of the request body.
+			# @yields {|chunk| ...}
+			# 	@parameter chunk [String]
 			def each(&block)
 				return to_enum unless block_given?
 				
@@ -46,8 +56,11 @@ module Falcon
 				end
 			end
 			
-			# rewind must be called without arguments. It rewinds the input stream back to the beginning. It must not raise Errno::ESPIPE: that is, it may not be a pipe or a socket. Therefore, handler developers must buffer the input data into some rewindable object if the underlying input stream is not rewindable.
-			# @return [Boolean] whether the body could be rewound.
+			# Rewind the input stream back to the start.
+			#
+			# `rewind` must be called without arguments. It rewinds the input stream back to the beginning. It must not raise Errno::ESPIPE: that is, it may not be a pipe or a socket. Therefore, handler developers must buffer the input data into some rewindable object if the underlying input stream is not rewindable.
+			#
+			# @returns [Boolean] Whether the body could be rewound.
 			def rewind
 				if @body and @body.respond_to? :rewind
 					# If the body is not rewindable, this will fail.
@@ -61,10 +74,13 @@ module Falcon
 				return false
 			end
 			
-			# read behaves like IO#read. Its signature is read([length, [buffer]]). If given, length must be a non-negative Integer (>= 0) or nil, and buffer must be a String and may not be nil. If length is given and not nil, then this method reads at most length bytes from the input stream. If length is not given or nil, then this method reads all data until EOF. When EOF is reached, this method returns nil if length is given and not nil, or “” if length is not given or is nil. If buffer is given, then the read data will be placed into buffer instead of a newly created String object.
-			# @param length [Integer] the amount of data to read
-			# @param buffer [String] the buffer which will receive the data
-			# @return a buffer containing the data
+			# Read data from the input stream.
+			# 
+			# `read` behaves like `IO#read`. Its signature is `read(length = nil, buffer = nil)`. If given, length must be a non-negative `Integer` (>= 0) or `nil`, and buffer must be a `String` and may not be nil. If `length` is given and not `nil`, then this method reads at most `length` bytes from the input stream. If `length` is not given or `nil`, then this method reads all data. When the end is reached, this method returns `nil` if `length` is given and not `nil`, or an empty `String` if `length` is not given or is `nil`. If `buffer` is given, then the read data will be placed into the `buffer` instead of a newly created `String` object.
+			#
+			# @parameter length [Integer] the amount of data to read
+			# @parameter buffer [String] the buffer which will receive the data
+			# @returns a buffer containing the data
 			def read(length = nil, buffer = nil)
 				buffer ||= Async::IO::Buffer.new
 				buffer.clear
@@ -93,12 +109,17 @@ module Falcon
 				return buffer
 			end
 			
+			# Has the input stream been read completely?
+			# @returns [Boolean]
 			def eof?
 				@finished and @buffer.nil?
 			end
 			
-			# gets must be called without arguments and return a string, or nil on EOF.
-			# @return [String, nil] The next chunk from the body.
+			# Read the next chunk of data from the input stream.
+			#
+			# `gets` must be called without arguments and return a `String`, or `nil` when the input stream has no more data.
+			#
+			# @returns [String | Nil] The next chunk from the body.
 			def gets
 				if @buffer.nil?
 					return read_next
@@ -109,7 +130,7 @@ module Falcon
 				end
 			end
 			
-			# close must never be called on the input stream. huh?
+			# Close and discard the remainder of the input stream.
 			def close
 				@body&.close
 			end

data/lib/falcon/adapters/output.rb

@@ -26,11 +26,15 @@ require 'protocol/http/body/file'
 module Falcon
 	module Adapters
 		# Wraps the rack response body.
-		# The Body must respond to each and must only yield String values. The Body itself should not be an instance of String, as this will break in Ruby 1.9. If the Body responds to close, it will be called after iteration. If the body is replaced by a middleware after action, the original body must be closed first, if it responds to close. If the Body responds to to_path, it must return a String identifying the location of a file whose contents are identical to that produced by calling each; this may be used by the server as an alternative, possibly more efficient way to transport the response. The Body commonly is an Array of Strings, the application instance itself, or a File-like object.
+		#
+		# The `rack` body must respond to `each` and must only yield `String` values. If the body responds to `close`, it will be called after iteration. If the body is replaced by a middleware after action, the original body must be closed first, if it responds to `close`. If the body responds to `to_path`, it must return a String identifying the location of a file whose contents are identical to that produced by calling `each`; this may be used by the server as an alternative, possibly more efficient way to transport the response. The body commonly is an `Array` of strings, the application instance itself, or a `File`-like object.
 		class Output < ::Protocol::HTTP::Body::Readable
 			CONTENT_LENGTH = 'content-length'.freeze
 			
 			# Wraps an array into a buffered body.
+			# @parameter status [Integer] The response status.
+			# @parameter headers [Protocol::HTTP::Headers] The response headers.
+			# @parameter body [Object] The `rack` response body.
 			def self.wrap(status, headers, body)
 				# In no circumstance do we want this header propagating out:
 				if length = headers.delete(CONTENT_LENGTH)
@@ -51,6 +55,9 @@ module Falcon
 				end
 			end
 			
+			# Initialize the output wrapper.
+			# @parameter body [Object] The rack response body.
+			# @parameter length [Integer] The rack response length.
 			def initialize(body, length)
 				@length = length
 				@body = body
@@ -64,10 +71,17 @@ module Falcon
 			# The content length of the rack response body.
 			attr :length
 			
+			# Whether the body is empty.
 			def empty?
 				@length == 0 or (@body.respond_to?(:empty?) and @body.empty?)
 			end
 			
+			# Whether the body can be read immediately.
+			def ready?
+				true
+			end
+			
+			# Close the response body.
 			def close(error = nil)
 				if @body and @body.respond_to?(:close)
 					@body.close
@@ -79,12 +93,17 @@ module Falcon
 				super
 			end
 			
+			# Enumerate the response body.
+			# @yields {|chunk| ...}
+			# 	@parameter chunk [String]
 			def each(&block)
 				@body.each(&block)
 			ensure
 				self.close($!)
 			end
 			
+			# Read the next chunk from the response body.
+			# @returns [String | Nil]
 			def read
 				@chunks ||= @body.to_enum(:each)
 				

data/lib/falcon/adapters/rack.rb

@@ -31,40 +31,48 @@ require 'async/logger'
 module Falcon
 	module Adapters
 		class Rack
-			# CGI keys (https://tools.ietf.org/html/rfc3875#section-4.1)
-			HTTP_HOST = 'HTTP_HOST'.freeze
-			PATH_INFO = 'PATH_INFO'.freeze
-			REQUEST_METHOD = 'REQUEST_METHOD'.freeze
-			REQUEST_PATH = 'REQUEST_PATH'.freeze
-			REQUEST_URI = 'REQUEST_URI'.freeze
-			SCRIPT_NAME = 'SCRIPT_NAME'.freeze
-			QUERY_STRING = 'QUERY_STRING'.freeze
-			SERVER_PROTOCOL = 'SERVER_PROTOCOL'.freeze
-			SERVER_NAME = 'SERVER_NAME'.freeze
-			SERVER_PORT = 'SERVER_PORT'.freeze
-			REMOTE_ADDR = 'REMOTE_ADDR'.freeze
-			CONTENT_TYPE = 'CONTENT_TYPE'.freeze
-			CONTENT_LENGTH = 'CONTENT_LENGTH'.freeze
+			# CGI keys <https://tools.ietf.org/html/rfc3875#section-4.1>:
 			
-			# Rack environment variables
-			RACK_VERSION = 'rack.version'.freeze
-			RACK_ERRORS = 'rack.errors'.freeze
-			RACK_LOGGER = 'rack.logger'.freeze
-			RACK_INPUT = 'rack.input'.freeze
-			RACK_MULTITHREAD = 'rack.multithread'.freeze
-			RACK_MULTIPROCESS = 'rack.multiprocess'.freeze
-			RACK_RUNONCE = 'rack.run_once'.freeze
-			RACK_URL_SCHEME = 'rack.url_scheme'.freeze
-			RACK_HIJACK = 'rack.hijack'.freeze
-			RACK_IS_HIJACK = 'rack.hijack?'.freeze
-			RACK_HIJACK_IO = 'rack.hijack_io'.freeze
-			RACK_EARLY_HINTS = "rack.early_hints".freeze
+			HTTP_HOST = 'HTTP_HOST'
+			PATH_INFO = 'PATH_INFO'
+			REQUEST_METHOD = 'REQUEST_METHOD'
+			REQUEST_PATH = 'REQUEST_PATH'
+			REQUEST_URI = 'REQUEST_URI'
+			SCRIPT_NAME = 'SCRIPT_NAME'
+			QUERY_STRING = 'QUERY_STRING'
+			SERVER_PROTOCOL = 'SERVER_PROTOCOL'
+			SERVER_NAME = 'SERVER_NAME'
+			SERVER_PORT = 'SERVER_PORT'
+			REMOTE_ADDR = 'REMOTE_ADDR'
+			CONTENT_TYPE = 'CONTENT_TYPE'
+			CONTENT_LENGTH = 'CONTENT_LENGTH'
 			
-			ASYNC_HTTP_REQUEST = "async.http.request".freeze
+			# Rack environment variables:
 			
-			# Header constants
-			HTTP_X_FORWARDED_PROTO = 'HTTP_X_FORWARDED_PROTO'.freeze
+			RACK_VERSION = 'rack.version'
+			RACK_ERRORS = 'rack.errors'
+			RACK_LOGGER = 'rack.logger'
+			RACK_INPUT = 'rack.input'
+			RACK_MULTITHREAD = 'rack.multithread'
+			RACK_MULTIPROCESS = 'rack.multiprocess'
+			RACK_RUNONCE = 'rack.run_once'
+			RACK_URL_SCHEME = 'rack.url_scheme'
+			RACK_HIJACK = 'rack.hijack'
+			RACK_IS_HIJACK = 'rack.hijack?'
+			RACK_HIJACK_IO = 'rack.hijack_io'
+			RACK_EARLY_HINTS = "rack.early_hints"
 			
+			# Async::HTTP specific metadata:
+			
+			ASYNC_HTTP_REQUEST = "async.http.request"
+			
+			# Header constants:
+			
+			HTTP_X_FORWARDED_PROTO = 'HTTP_X_FORWARDED_PROTO'
+			
+			# Initialize the rack adaptor middleware.
+			# @parameter app [Object] The rack middleware.
+			# @parameter logger [Console::Logger] The logger to use.
 			def initialize(app, logger = Async.logger)
 				@app = app
 				
@@ -73,7 +81,12 @@ module Falcon
 				@logger = logger
 			end
 			
-			# Rack separates multiple headers with the same key, into a single field with multiple "lines".
+			# Unwrap raw HTTP headers into the CGI-style expected by Rack middleware.
+			#
+			# Rack separates multiple headers with the same key, into a single field with multiple lines.
+			#
+			# @parameter headers [Protocol::HTTP::Headers] The raw HTTP request headers.
+			# @parameter env [Hash] The rack request `env`.
 			def unwrap_headers(headers, env)
 				headers.each do |key, value|
 					http_key = "HTTP_#{key.upcase.tr('-', '_')}"
@@ -86,7 +99,15 @@ module Falcon
 				end
 			end
 			
-			# Process the incoming request into a valid rack env.
+			# Process the incoming request into a valid rack `env`.
+			#
+			# - Set the `env['CONTENT_TYPE']` and `env['CONTENT_LENGTH']` based on the incoming request body. 
+			# - Set the `env['HTTP_HOST']` header to the request authority.
+			# - Set the `env['HTTP_X_FORWARDED_PROTO']` header to the request scheme.
+			# - Set `env['REMOTE_ADDR']` to the request remote adress.
+			#
+			# @parameter request [Protocol::HTTP::Request] The incoming request.
+			# @parameter env [Hash] The rack `env`.
 			def unwrap_request(request, env)
 				if content_type = request.headers.delete('content-type')
 					env[CONTENT_TYPE] = content_type
@@ -113,6 +134,9 @@ module Falcon
 				end
 			end
 			
+			# Build a rack `env` from the incoming request and apply it to the rack middleware.
+			#
+			# @parameter request [Protocol::HTTP::Request] The incoming request.
 			def call(request)
 				request_path, query_string = request.path.split('?', 2)
 				server_name, server_port = (request.authority || '').split(':', 2)
@@ -194,6 +218,9 @@ module Falcon
 				return failure_response(exception)
 			end
 			
+			# Generate a suitable response for the given exception.
+			# @parameter exception [Exception]
+			# @returns [Protocol::HTTP::Response]
 			def failure_response(exception)
 				Protocol::HTTP::Response.for_exception(exception)
 			end

data/lib/falcon/adapters/response.rb

@@ -29,10 +29,22 @@ require 'time'
 
 module Falcon
 	module Adapters
+		# A wrapper for a `Rack` response.
+		#
+		# A Rack response consisting of `[status, headers, body]` includes various rack-specific elements, including:
+		#
+		# - A `headers['rack.hijack']` callback which bypasses normal response handling.
+		# - Potentially invalid content length.
+		# - Potentially invalid body when processing a `HEAD` request.
+		# - Newline-separated header values.
+		# - Other `rack.` specific header key/value pairs.
+		#
+		# This wrapper takes those issues into account and adapts the rack response tuple into a {Protocol::HTTP::Response}.
 		class Response < ::Protocol::HTTP::Response
 			IGNORE_HEADERS = Middleware::Proxy::HOP_HEADERS
 			
-			# Append a list of newline encoded headers.
+			# Process the rack response headers into into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
+			# @returns [Tuple(Protocol::HTTP::Headers, Hash)]
 			def self.wrap_headers(fields)
 				headers = ::Protocol::HTTP::Headers.new
 				meta = {}
@@ -52,6 +64,11 @@ module Falcon
 				return headers, meta
 			end
 			
+			# Wrap a rack response.
+			# @parameter status [Integer] The rack response status.
+			# @parameter headers [Duck(:each)] The rack response headers.
+			# @parameter body [Duck(:each, :close) | Nil] The rack response body.
+			# @parameter request [Protocol::HTTP::Request] The original request.
 			def self.wrap(status, headers, body, request = nil)
 				headers, meta = wrap_headers(headers)
 				
@@ -83,6 +100,11 @@ module Falcon
 				return self.new(status, headers, body, protocol)
 			end
 			
+			# Initialize the response wrapper.
+			# @parameter status [Integer] The response status.
+			# @parameter headers [Protocol::HTTP::Headers] The response headers.
+			# @parameter body [Protocol::HTTP::Body] The response body.
+			# @parameter protocol [String] The response protocol for upgraded requests.
 			def initialize(status, headers, body, protocol = nil)
 				super(nil, status, headers, body, protocol)
 			end

data/lib/falcon/adapters/rewindable.rb

@@ -24,8 +24,9 @@ require 'protocol/http/body/rewindable'
 
 module Falcon
 	module Adapters
-		# Content type driven input buffering.
+		# Content-type driven input buffering, specific to the needs of `rack`.
 		class Rewindable < ::Protocol::HTTP::Middleware
+			# Media types that require buffering.
 			BUFFERED_MEDIA_TYPES = %r{
 				application/x-www-form-urlencoded|
 				multipart/form-data|
@@ -35,10 +36,15 @@ module Falcon
 			
 			POST = 'POST'.freeze
 			
+			# Initialize the rewindable middleware.
+			# @parameter app [Protocol::HTTP::Middleware] The middleware to wrap.
 			def initialize(app)
 				super(app)
 			end
 			
+			# Determine whether the request needs a rewindable body.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Boolean]
 			def needs_rewind?(request)
 				content_type = request.headers['content-type']
 				
@@ -53,8 +59,9 @@ module Falcon
 				return false
 			end
 			
-			# Wrap the request body in a rewindable buffer.
-			# @return [Protocol::HTTP::Response] the response.
+			# Wrap the request body in a rewindable buffer if required.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Protocol::HTTP::Response] the response.
 			def call(request)
 				if body = request.body and needs_rewind?(request)
 					request.body = Async::HTTP::Body::Rewindable.new(body)

data/lib/falcon/command.rb

@@ -24,6 +24,8 @@ require_relative 'command/top'
 
 module Falcon
 	module Command
+		# The main entry point for the `falcon` executable.
+		# @parameter arguments [Array(String)] The command line arguments.
 		def self.call(*arguments)
 			Top.call(*arguments)
 		end

data/lib/falcon/command/host.rb

@@ -25,20 +25,29 @@ require_relative '../configuration'
 require_relative '../version'
 
 require 'samovar'
+require 'bundler'
 
 module Falcon
 	module Command
+		# Implements the `falcon host` command. Designed for *deployment*.
+		#
+		# Manages a {Controller::Host} instance which is responsible for running applications in a production environment.
 		class Host < Samovar::Command
 			self.description = "Host the specified applications."
 			
+			# One or more paths to the configuration files.
+			# @name paths
+			# @attribute [Array(String)]
 			many :paths, "Service configuration paths.", default: ["falcon.rb"]
 			
+			# The container class to use.
 			def container_class
 				Async::Container.best_container_class
 			end
 			
-			def configuration(verbose = false)
-				configuration = Configuration.new(verbose)
+			# Generate a configuration based on the specified {paths}.
+			def configuration
+				configuration = Configuration.new
 				
 				@paths.each do |path|
 					path = File.expand_path(path)
@@ -48,10 +57,12 @@ module Falcon
 				return configuration
 			end
 			
+			# Prepare a new controller for the command.
 			def controller
 				Controller::Host.new(self)
 			end
 			
+			# Prepare the environment and run the controller.
 			def call
 				Async.logger.info(self) do |buffer|
 					buffer.puts "Falcon Host v#{VERSION} taking flight!"