falcon 0.36.3 → 0.37.0

data/lib/falcon/{configuration → environments}/rack.rb

@@ -22,11 +22,23 @@
 
 load :application
 
-add(:rack, :application) do
+# A rack application environment.
+#
+# Derived from {.application}.
+#
+# @scope Falcon Environments
+# @name rack
+environment(:rack, :application) do
+	# The rack configuration path.
+	# @attribute [String]
 	config_path {::File.expand_path("config.ru", root)}
 	
+	# Whether to enable the application layer cache.
+	# @attribute [String]
 	cache false
 	
+	# The middleware stack for the rack application.
+	# @attribute [Protocol::HTTP::Middleware]
 	middleware do
 		app, _ = ::Rack::Builder.parse_file(config_path)
 		
@@ -35,4 +47,4 @@ add(:rack, :application) do
 			cache: cache
 		)
 	end
-end
+end

data/lib/falcon/{configuration → environments}/self_signed_tls.rb

@@ -22,9 +22,17 @@
 
 require 'localhost/authority'
 
-add(:self_signed_tls) do
+# A self-signed SSL context environment.
+#
+# @scope Falcon Environments
+# @name self_signed_tls
+environment(:self_signed_tls) do
+	# The default session identifier for the session cache.
+	# @attribute [String]
 	ssl_session_id {"falcon"}
 	
+	# The SSL context to use for incoming connections.
+	# @attribute [OpenSSL::SSL::SSLContext]
 	ssl_context do
 		contexts = Localhost::Authority.fetch(authority)
 		

data/lib/falcon/{configuration → environments}/supervisor.rb

@@ -22,15 +22,29 @@
 
 require_relative '../service/supervisor'
 
-add(:supervisor) do
-	start true
-	
+# A application process monitor environment.
+#
+# @scope Falcon Environments
+# @name supervisor
+environment(:supervisor) do
+	# The name of the supervisor
+	# @attribute [String]
 	name "supervisor"
 	
-	ipc_path {::File.expand_path("supervisor.ipc", root)}
+	# The IPC path to use for communication with the supervisor.
+	# @attribute [String]
+	ipc_path do
+		::File.expand_path("supervisor.ipc", root)
+	end
 	
-	endpoint {Async::IO::Endpoint.unix(ipc_path)}
+	# The endpoint the supervisor will bind to.
+	# @attribute [Async::IO::Endpoint]
+	endpoint do
+		Async::IO::Endpoint.unix(ipc_path)
+	end
 	
+	# The service class to use for the supervisor.
+	# @attribute [Class]
 	service do
 		::Falcon::Service::Supervisor
 	end

data/lib/falcon/{configuration → environments}/tls.rb

@@ -24,19 +24,53 @@ require_relative '../extensions/openssl'
 require_relative '../controller/proxy'
 require_relative '../tls'
 
-add(:tls) do
+# A general SSL context environment.
+#
+# @scope Falcon Environments
+# @name tls
+environment(:tls) do
+	# The default session identifier for the session cache.
+	# @attribute [String]
 	ssl_session_id "falcon"
+	
+	# The supported ciphers.
+	# @attribute [Array(String)]
 	ssl_ciphers Falcon::TLS::SERVER_CIPHERS
 	
-	ssl_certificate_path {File.expand_path("ssl/certificate.pem", root)}
-	ssl_certificates {OpenSSL::X509.load_certificates(ssl_certificate_path)}
+	# The public certificate path.
+	# @attribute [String]
+	ssl_certificate_path do
+		File.expand_path("ssl/certificate.pem", root)
+	end
+	
+	# The list of certificates loaded from that path.
+	# @attribute [Array(OpenSSL::X509::Certificate)]
+	ssl_certificates do
+		OpenSSL::X509.load_certificates(ssl_certificate_path)
+	end
 	
+	# The main certificate.
+	# @attribute [OpenSSL::X509::Certificate]
 	ssl_certificate {ssl_certificates[0]}
+	
+	# The certificate chain.
+	# @attribute [Array(OpenSSL::X509::Certificate)]
 	ssl_certificate_chain {ssl_certificates[1..-1]}
 	
-	ssl_private_key_path {File.expand_path("ssl/private.key", root)}
-	ssl_private_key {OpenSSL::PKey::RSA.new(File.read(ssl_private_key_path))}
+	# The private key path.
+	# @attribute [String]
+	ssl_private_key_path do
+		File.expand_path("ssl/private.key", root)
+	end
+	
+	# The private key.
+	# @attribute [OpenSSL::PKey::RSA]
+	ssl_private_key do
+		OpenSSL::PKey::RSA.new(File.read(ssl_private_key_path))
+	end
 	
+	# The SSL context to use for incoming connections.
+	# @attribute [OpenSSL::SSL::SSLContext]
 	ssl_context do
 		OpenSSL::SSL::SSLContext.new.tap do |context|
 			context.add_certificate(ssl_certificate, ssl_private_key, ssl_certificate_chain)

data/lib/falcon/extensions/openssl.rb

@@ -25,6 +25,7 @@ require 'openssl/x509'
 module OpenSSL::X509
 	CERTIFICATE_PATTERN = /-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----/m
 	
+	# An extension to load an array of certificates from a file at the given path.
 	def self.load_certificates(path)
 		File.read(path).scan(CERTIFICATE_PATTERN).collect do |text|
 			Certificate.new(text)

data/lib/falcon/middleware/proxy.rb

@@ -26,6 +26,7 @@ require 'protocol/http/middleware'
 
 module Falcon
 	module Middleware
+		# A static middleware which always returns a 400 bad request response.
 		module BadRequest
 			def self.call(request)
 				return Protocol::HTTP::Response[400, {}, []]
@@ -35,14 +36,17 @@ module Falcon
 			end
 		end
 		
+		# A HTTP middleware for proxying requests to a given set of hosts.
+		# Typically used for implementing virtual servers.
 		class Proxy < Protocol::HTTP::Middleware
-			FORWARDED = 'forwarded'.freeze
-			X_FORWARDED_FOR = 'x-forwarded-for'.freeze
-			X_FORWARDED_PROTO = 'x-forwarded-proto'.freeze
+			FORWARDED = 'forwarded'
+			X_FORWARDED_FOR = 'x-forwarded-for'
+			X_FORWARDED_PROTO = 'x-forwarded-proto'
 			
-			VIA = 'via'.freeze
-			CONNECTION = 'connection'.freeze
+			VIA = 'via'
+			CONNECTION = 'connection'
 			
+			# HTTP hop headers which *should* not be passed through the proxy.
 			HOP_HEADERS = [
 				'connection',
 				'keep-alive',
@@ -52,6 +56,9 @@ module Falcon
 				'upgrade',
 			]
 			
+			# Initialize the proxy middleware.
+			# @parameter app [Protocol::HTTP::Middleware] The middleware to use if a request can't be proxied.
+			# @parameter hosts [Array(Service::Proxy)] The host applications to proxy to.
 			def initialize(app, hosts)
 				super(app)
 				
@@ -63,18 +70,26 @@ module Falcon
 				@count = 0
 			end
 			
+			# The number of requests that have been proxied.
+			# @attribute [Integer]
 			attr :count
 			
+			# Close all the connections to the upstream hosts.
 			def close
 				@clients.each_value(&:close)
 				
 				super
 			end
 			
+			# Establish a connection to the specified upstream endpoint.
+			# @parameter endpoint [Async::HTTP::Endpoint]
 			def connect(endpoint)
 				@clients[endpoint] ||= Async::HTTP::Client.new(endpoint)
 			end
 			
+			# Lookup the appropriate host for the given request.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Service::Proxy]
 			def lookup(request)
 				# Trailing dot and port is ignored/normalized.
 				if authority = request.authority&.sub(/(\.)?(:\d+)?$/, '')
@@ -82,6 +97,8 @@ module Falcon
 				end
 			end
 			
+			# Prepare the headers to be sent to an upstream host.
+			# In particular, we delete all connection and hop headers.
 			def prepare_headers(headers)
 				if connection = headers[CONNECTION]
 					headers.extract(connection)
@@ -90,6 +107,8 @@ module Falcon
 				headers.extract(HOP_HEADERS)
 			end
 			
+			# Prepare the request to be proxied to the specified host.
+			# In particular, we set appropriate {VIA}, {FORWARDED}, {X_FORWARDED_FOR} and {X_FORWARDED_PROTO} headers.
 			def prepare_request(request, host)
 				forwarded = []
 				
@@ -124,6 +143,8 @@ module Falcon
 				return request
 			end
 			
+			# Proxy the request if the authority matches a specific host.
+			# @parameter request [Protocol::HTTP::Request]
 			def call(request)
 				if host = lookup(request)
 					@count += 1

data/lib/falcon/middleware/redirect.rb

@@ -24,6 +24,7 @@ require 'async/http/client'
 
 module Falcon
 	module Middleware
+		# A static middleware which always returns a 404 not found response.
 		module NotFound
 			def self.call(request)
 				return Protocol::HTTP::Response[404, {}, []]
@@ -33,7 +34,13 @@ module Falcon
 			end
 		end
 		
+		# A HTTP middleware for redirecting a given set of hosts to a different endpoint.
+		# Typically used for implementing HTTP -> HTTPS redirects.
 		class Redirect < Protocol::HTTP::Middleware
+			# Initialize the redirect middleware.
+			# @parameter app [Protocol::HTTP::Middleware] The middleware to wrap.
+			# @parameter hosts [Hash(String, Service::Proxy)] The map of hosts.
+			# @parameter endpoint [Endpoint] The template endpoint to use to build the redirect location.
 			def initialize(app, hosts, endpoint)
 				super(app)
 				
@@ -41,6 +48,8 @@ module Falcon
 				@endpoint = endpoint
 			end
 			
+			# Lookup the appropriate host for the given request.
+			# @parameter request [Protocol::HTTP::Request]
 			def lookup(request)
 				# Trailing dot and port is ignored/normalized.
 				if authority = request.authority&.sub(/(\.)?(:\d+)?$/, '')
@@ -48,6 +57,8 @@ module Falcon
 				end
 			end
 			
+			# Redirect the request if the authority matches a specific host.
+			# @parameter request [Protocol::HTTP::Request]
 			def call(request)
 				if host = lookup(request)
 					if @endpoint.default_port?

data/lib/falcon/{verbose.rb → middleware/verbose.rb}

@@ -24,36 +24,44 @@ require 'async/logger'
 require 'async/http/statistics'
 
 module Falcon
-	class Verbose < Protocol::HTTP::Middleware
-		def initialize(app, logger = Async.logger)
-			super(app)
-			
-			@logger = logger
-		end
-		
-		def annotate(request)
-			task = Async::Task.current
-			address = request.remote_address
-			
-			@logger.info(request) {"Headers: #{request.headers.to_h} from #{address.inspect}"}
-			
-			task.annotate("#{request.method} #{request.path} from #{address.inspect}")
-		end
-		
-		def call(request)
-			annotate(request)
-			
-			statistics = Async::HTTP::Statistics.start
-			
-			response = super
+	module Middleware
+		# A HTTP middleware for logging requests and responses.
+		class Verbose < Protocol::HTTP::Middleware
+			# Initialize the verbose middleware.
+			# @parameter app [Protocol::HTTP::Middleware] The middleware to wrap.
+			# @parameter logger [Console::Logger] The logger to use.
+			def initialize(app, logger = Async.logger)
+				super(app)
+				
+				@logger = logger
+			end
 			
-			statistics.wrap(response) do |statistics, error|
-				@logger.info(request) {"Responding with: #{response.status} #{response.headers.to_h}; #{statistics.inspect}"}
+			# Log details of the incoming request.
+			def annotate(request)
+				task = Async::Task.current
+				address = request.remote_address
+				
+				@logger.info(request) {"Headers: #{request.headers.to_h} from #{address.inspect}"}
 				
-				@logger.error(request) {"#{error.class}: #{error.message}"} if error
+				task.annotate("#{request.method} #{request.path} from #{address.inspect}")
 			end
 			
-			return response
+			# Log details of the incoming request using {annotate} and wrap the response to log response details too.
+			def call(request)
+				annotate(request)
+				
+				statistics = Async::HTTP::Statistics.start
+				
+				response = super
+				
+				statistics.wrap(response) do |statistics, error|
+					@logger.info(request) {"Responding with: #{response.status} #{response.headers.to_h}; #{statistics.inspect}"}
+					
+					@logger.error(request) {"#{error.class}: #{error.message}"} if error
+				end
+				
+				return response
+			end
 		end
 	end
 end

data/lib/falcon/proxy_endpoint.rb

@@ -23,7 +23,10 @@
 require 'async/io/unix_endpoint'
 
 module Falcon
+	# An endpoint suitable for proxing requests, typically via a unix pipe.
 	class ProxyEndpoint < Async::IO::Endpoint
+		# Initialize the proxy endpoint.
+		# @parameter endpoint [Async::IO::Endpoint] The endpoint which will be used for connecting/binding.
 		def initialize(endpoint, **options)
 			super(**options)
 			
@@ -34,28 +37,44 @@ module Falcon
 			"\#<#{self.class} endpoint=#{@endpoint}>"
 		end
 		
+		# The actual endpoint for I/O.
+		# @attribute [Async::IO::Endpoint]
 		attr :endpoint
 		
+		# The protocol to use for this connection.
+		# @returns [Async::HTTP::Protocol] A specific protocol, e.g. {Async::HTTP::P}
 		def protocol
 			@options[:protocol]
 		end
 		
+		# The scheme to use for this endpoint.
+		# e.g. `"http"`.
+		# @returns [String]
 		def scheme
 			@options[:scheme]
 		end
 		
+		# The authority to use for this endpoint.
+		# e.g. `"myapp.com"`.
+		# @returns [String]
 		def authority
 			@options[:authority]
 		end
 		
+		# Connect to the endpoint.
 		def connect(&block)
 			@endpoint.connect(&block)
 		end
 		
+		# Bind to the endpoint.
 		def bind(&block)
 			@endpoint.bind(&block)
 		end
 		
+		# Enumerate the endpoint.
+		# If the endpoint has multiple underlying endpoints, this will enumerate them individually.
+		# @yields {|endpoint| ...}
+		# 	@parameter endpoint [ProxyEndpoint]
 		def each
 			return to_enum unless block_given?
 			
@@ -64,6 +83,8 @@ module Falcon
 			end
 		end
 		
+		# Create a proxy unix endpoint with the specific path.
+		# @returns [ProxyEndpoint]
 		def self.unix(path, **options)
 			self.new(::Async::IO::Endpoint.unix(path), **options)
 		end

data/lib/falcon/server.rb

@@ -27,16 +27,22 @@ require 'protocol/http/content_encoding'
 
 require 'async/http/cache'
 
-require_relative 'verbose'
+require_relative 'middleware/verbose'
+
 require_relative 'adapters/rewindable'
 require_relative 'adapters/rack'
 
 module Falcon
+	# A server listening on a specific endpoint, hosting a specific middleware.
 	class Server < Async::HTTP::Server
+		# Wrap a rack application into a middleware suitable the server.
+		# @parameter rack_app [Proc | Object] A rack application/middleware.
+		# @parameter verbose [Boolean] Whether to add the {Verbose} middleware.
+		# @parameter cache [Boolean] Whether to add the {Async::HTTP::Cache} middleware.
 		def self.middleware(rack_app, verbose: false, cache: true)
 			::Protocol::HTTP::Middleware.build do
 				if verbose
-					use Verbose
+					use Middleware::Verbose
 				end
 				
 				if cache

data/lib/falcon/service/application.rb

@@ -27,6 +27,7 @@ require 'async/io/shared_endpoint'
 
 module Falcon
 	module Service
+		# Implements an application server using an internal clear-text proxy.
 		class Application < Proxy
 			def initialize(environment)
 				super
@@ -34,11 +35,20 @@ module Falcon
 				@bound_endpoint = nil
 			end
 			
+			# The middleware that will be served by this application.
+			# @returns [Protocol::HTTP::Middleware]
 			def middleware
 				# In a multi-threaded container, we don't want to modify the shared evaluator's cache, so we create a new evaluator:
 				@environment.evaluator.middleware
 			end
 			
+			# Number of instances to start.
+			# @returns [Integer | nil]
+			def count
+			  @environment.evaluator.count
+			end
+			
+			# Preload any resources specified by the environment.
 			def preload!
 				if scripts = @evaluator.preload
 					scripts.each do |path|
@@ -49,6 +59,8 @@ module Falcon
 				end
 			end
 			
+			# Prepare the bound endpoint for the application instances.
+			# Invoke {preload!} to load shared resources into the parent process.
 			def start
 				Async.logger.info(self) {"Binding to #{self.endpoint}..."}
 				
@@ -61,15 +73,24 @@ module Falcon
 				super
 			end
 			
+			# Setup instances of the application into the container.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				protocol = self.protocol
 				scheme = self.scheme
 				
-				container.run(name: self.name, restart: true) do |instance|
+				run_options = {
+					name: self.name,
+					restart: true,
+				}
+				
+				run_options[:count] = count unless count.nil?
+				
+				container.run(**run_options) do |instance|
 					Async(logger: logger) do |task|
 						Async.logger.info(self) {"Starting application server for #{self.root}..."}
 						
-						server = Server.new(self.middleware, @bound_endpoint, protocol, scheme)
+						server = Server.new(self.middleware, @bound_endpoint, protocol: protocol, scheme: scheme)
 						
 						server.run
 						
@@ -82,6 +103,7 @@ module Falcon
 				super
 			end
 			
+			# Close the bound endpoint.
 			def stop
 				@bound_endpoint&.close
 				@bound_endpoint = nil