falcon 0.36.3 → 0.37.0

data/lib/falcon/controller/host.rb

@@ -26,7 +26,13 @@ require 'async/container/controller'
 
 module Falcon
 	module Controller
+		# A generic controller for serving an application.
+		# Hosts several {Services} based on the command configuration.
+		#
+		# The configuration is provided by {Command::Host} and is typically loaded from a `falcon.rb` file. See {Configuration#load_file} for more details.
 		class Host < Async::Container::Controller
+			# Initialize the virtual controller.
+			# @parameter command [Command::Host] The user-specified command-line options.
 			def initialize(command, **options)
 				@command = command
 				
@@ -36,20 +42,26 @@ module Falcon
 				super(**options)
 			end
 			
+			# Create the controller as specified by the command.
+			# e.g. `Async::Container::Forked`.
 			def create_container
 				@command.container_class.new
 			end
 			
+			# Start all specified services.
 			def start
 				@services.start
 				
 				super
 			end
 			
+			# Setup all specified services into the container.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				@services.setup(container)
 			end
 			
+			# Stop all specified services.
 			def stop(*)
 				@services.stop
 				

data/lib/falcon/controller/proxy.rb

@@ -30,9 +30,14 @@ require_relative '../tls'
 
 module Falcon
 	module Controller
+		# A controller for proxying requests.
 		class Proxy < Serve
+			# The default SSL session identifier.
 			DEFAULT_SESSION_ID = "falcon"
 			
+			# Initialize the proxy controller.
+			# @parameter command [Command::Proxy] The user-specified command-line options.
+			# @parameter session_id [String] The SSL session identifier to use for the session cache.
 			def initialize(command, session_id: DEFAULT_SESSION_ID, **options)
 				super(command, **options)
 				
@@ -40,14 +45,19 @@ module Falcon
 				@hosts = {}
 			end
 			
+			# Load the {Middleware::Proxy} application with the specified hosts.
 			def load_app
 				return Middleware::Proxy.new(Middleware::BadRequest, @hosts)
 			end
 			
+			# The name of the controller which is used for the process title.
 			def name
 				"Falcon Proxy Server"
 			end
 			
+			# Look up the host context for the given hostname, and update the socket hostname if necessary.
+			# @parameter socket [OpenSSL::SSL::SSLSocket] The incoming connection.
+			# @parameter hostname [String] The negotiated hostname.
 			def host_context(socket, hostname)
 				if host = @hosts[hostname]
 					Async.logger.debug(self) {"Resolving #{hostname} -> #{host}"}
@@ -62,6 +72,7 @@ module Falcon
 				end
 			end
 			
+			# Generate an SSL context which delegates to {host_context} to multiplex based on hostname.
 			def ssl_context
 				@server_context ||= OpenSSL::SSL::SSLContext.new.tap do |context|
 					context.servername_cb = Proc.new do |socket, hostname|
@@ -81,6 +92,7 @@ module Falcon
 				end
 			end
 			
+			# The endpoint the server will bind to.
 			def endpoint
 				@command.endpoint.with(
 					ssl_context: self.ssl_context,
@@ -88,6 +100,7 @@ module Falcon
 				)
 			end
 			
+			# Builds a map of host redirections.
 			def start
 				configuration = @command.configuration
 				

data/lib/falcon/controller/redirect.rb

@@ -28,27 +28,34 @@ require_relative '../service/proxy'
 
 module Falcon
 	module Controller
+		# A controller for redirecting requests.
 		class Redirect < Serve
+			# Initialize the redirect controller.
+			# @parameter command [Command::Redirect] The user-specified command-line options.
 			def initialize(command, **options)
 				super(command, **options)
 				
 				@hosts = {}
 			end
 			
+			# Load the {Middleware::Redirect} application with the specified hosts.
 			def load_app
 				return Middleware::Redirect.new(Middleware::NotFound, @hosts, @command.redirect_endpoint)
 			end
 			
+			# The name of the controller which is used for the process title.
 			def name
 				"Falcon Redirect Server"
 			end
 			
+			# The endpoint the server will bind to.
 			def endpoint
 				@command.endpoint.with(
 					reuse_address: true,
 				)
 			end
 			
+			# Builds a map of host redirections.
 			def start
 				configuration = @command.configuration
 				

data/lib/falcon/controller/serve.rb

@@ -29,7 +29,11 @@ require 'async/io/shared_endpoint'
 
 module Falcon
 	module Controller
+		# A generic controller for serving an application.
+		# Uses {Server} for handling incoming requests.
 		class Serve < Async::Container::Controller
+			# Initialize the server controller.
+			# @parameter command [Command::Serve] The user-specified command-line options.
 			def initialize(command, **options)
 				@command = command
 				
@@ -40,34 +44,44 @@ module Falcon
 				super(**options)
 			end
 			
+			# Create the controller as specified by the command.
+			# e.g. `Async::Container::Forked`.
 			def create_container
 				@command.container_class.new
 			end
 			
+			# The endpoint the server will bind to.
 			def endpoint
 				@command.endpoint
 			end
 			
+			# @returns [Protocol::HTTP::Middleware] an instance of the application to be served.
 			def load_app
 				@command.load_app
 			end
 			
+			# Prepare the bound endpoint for the server.
 			def start
 				@endpoint ||= self.endpoint
 				
-				@bound_endpoint = Async::Reactor.run do
+				@bound_endpoint = Async do
 					Async::IO::SharedEndpoint.bound(@endpoint)
 				end.wait
 				
+				Async.logger.info(self) { "Starting #{name} on #{@endpoint.to_url}" }
+				
 				@debug_trap.ignore!
 				
 				super
 			end
 			
+			# The name of the controller which is used for the process title.
 			def name
 				"Falcon Server"
 			end
 			
+			# Setup the container with the application instance.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				container.run(name: self.name, restart: true, **@command.container_options) do |instance|
 					Async do |task|
@@ -88,7 +102,7 @@ module Falcon
 							end
 						end
 						
-						server = Falcon::Server.new(app, @bound_endpoint, @endpoint.protocol, @endpoint.scheme)
+						server = Falcon::Server.new(app, @bound_endpoint, protocol: @endpoint.protocol, scheme: @endpoint.scheme)
 						
 						server.run
 						
@@ -99,6 +113,7 @@ module Falcon
 				end
 			end
 			
+			# Close the bound endpoint.
 			def stop(*)
 				@bound_endpoint&.close
 				

data/lib/falcon/controller/virtual.rb

@@ -24,7 +24,13 @@ require 'async/container/controller'
 
 module Falcon
 	module Controller
+		# A controller which mananages several virtual hosts.
+		# Spawns instances of {Proxy} and {Redirect} to handle incoming requests.
+		#
+		# A virtual host is an application bound to a specific authority (essentially a hostname). The virtual controller manages multiple hosts and allows a single server to host multiple applications easily.
 		class Virtual < Async::Container::Controller
+			# Initialize the virtual controller.
+			# @parameter command [Command::Virtual] The user-specified command-line options.
 			def initialize(command, **options)
 				@command = command
 				
@@ -33,6 +39,8 @@ module Falcon
 				trap(SIGHUP, &self.method(:reload))
 			end
 			
+			# Drop privileges according to the user and group of the specified path.
+			# @parameter path [String] The path to the application directory.
 			def assume_privileges(path)
 				stat = File.stat(path)
 				
@@ -46,6 +54,10 @@ module Falcon
 				}
 			end
 			
+			# Spawn an application instance from the specified path.
+			# @parameter path [String] The path to the application directory.
+			# @parameter container [Async::Container::Generic] The container to spawn into.
+			# @parameter options [Options] The options which are passed to `exec`.
 			def spawn(path, container, **options)
 				container.spawn(name: "Falcon Application", restart: true, key: path) do |instance|
 					env = assume_privileges(path)
@@ -56,10 +68,15 @@ module Falcon
 				end
 			end
 			
+			# The path to the falcon executable from this gem.
+			# @returns [String]
 			def falcon_path
 				File.expand_path("../../../bin/falcon", __dir__)
 			end
 			
+			# Setup the container with {Redirect} and {Proxy} child processes.
+			# These processes are gracefully restarted if they are already running.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				if proxy = container[:proxy]
 					proxy.kill(:HUP)

data/lib/falcon/endpoint.rb

@@ -24,11 +24,19 @@ require 'async/http/endpoint'
 require 'localhost/authority'
 
 module Falcon
+	# An HTTP-specific endpoint which adds localhost TLS.
 	class Endpoint < Async::HTTP::Endpoint
+		# The SSL context to use, which invokes {build_ssl_context} if not otherwise specified.
+		# @returns [OpenSSL::SSL::SSLContext]
 		def ssl_context
 			@options[:ssl_context] || build_ssl_context
 		end
 		
+		# Build an appropriate SSL context for the given hostname.
+		#
+		# Uses {Localhost::Authority} to generate self-signed certficates.
+		#
+		# @returns [OpenSSL::SSL::SSLContext]
 		def build_ssl_context(hostname = self.hostname)
 			authority = Localhost::Authority.fetch(hostname)
 			

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -20,8 +20,12 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-add(:proxy) do
-	endpoint {::Async::HTTP::Endpoint.parse(url)}
-	
-	service ::Falcon::Service::Proxy
+require 'build/environment'
+
+module Falcon
+	# Pre-defined environments for hosting web applications.
+	#
+	# See {Configuration::Loader#load} for more details.
+	module Environments
+	end
 end

data/lib/falcon/environments/application.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+require_relative '../proxy_endpoint'
+require_relative '../server'
+
+require_relative '../service/application'
+
+# A general application environment.
+# Suitable for use with any {Protocol::HTTP::Middleware}.
+#
+# @scope Falcon Environments
+# @name application
+environment(:application) do
+	# The middleware stack for the application.
+	# @attribute [Protocol::HTTP::Middleware]
+	middleware do
+		::Protocol::HTTP::Middleware::HelloWorld
+	end
+	
+	# The scheme to use to communicate with the application.
+	# @attribute [String]
+	scheme 'https'
+	
+	# The protocol to use to communicate with the application.
+	#
+	# Typically one of {Async::HTTP::Protocol::HTTP1} or {Async::HTTP::Protocl::HTTP2}.
+	#
+	# @attribute [Async::HTTP::Protocol]
+	protocol {Async::HTTP::Protocol::HTTP2}
+	
+	# The IPC path to use for communication with the application.
+	# @attribute [String]
+	ipc_path {::File.expand_path("application.ipc", root)}
+	
+	# The endpoint that will be used for communicating with the application server.
+	# @attribute [Async::IO::Endpoint]
+	endpoint do
+		::Falcon::ProxyEndpoint.unix(ipc_path,
+			protocol: protocol,
+			scheme: scheme,
+			authority: authority
+		)
+	end
+	
+	# The service class to use for the application.
+	# @attribute [Class]
+	service ::Falcon::Service::Application
+	
+	# Number of instances to start.
+	# @attribute [Integer | nil]
+	count nil
+end

data/lib/falcon/{configuration/application.rb → environments/lets_encrypt_tls.rb}

@@ -20,27 +20,28 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative '../proxy_endpoint'
-require_relative '../server'
+load(:tls)
 
-require_relative '../service/application'
-
-add(:application) do
-	middleware do
-		::Protocol::HTTP::Middleware::HelloWorld
-	end
+# A Lets Encrypt SSL context environment.
+#
+# Derived from {.tls}.
+#
+# @scope Falcon Environments
+# @name lets_encrypt_tls
+environment(:lets_encrypt_tls, :tls) do
+	# The Lets Encrypt certificate store path.
+	# @parameter [String]
+	lets_encrypt_root '/etc/letsencrypt/live'
 	
-	scheme 'https'
-	protocol {Async::HTTP::Protocol::HTTP2}
-	ipc_path {::File.expand_path("application.ipc", root)}
-	
-	endpoint do
-		::Falcon::ProxyEndpoint.unix(ipc_path,
-			protocol: protocol,
-			scheme: scheme,
-			authority: authority
-		)
+	# The public certificate path.
+	# @attribute [String]
+	ssl_certificate_path do
+		File.join(lets_encrypt_root, authority, "fullchain.pem")
 	end
 	
-	service ::Falcon::Service::Application
-end
+	# The private key path.
+	# @attribute [String]
+	ssl_private_key_path do
+		File.join(lets_encrypt_root, authority, "privkey.pem")
+	end
+end

data/lib/falcon/{configuration/lets_encrypt_tls.rb → environments/proxy.rb}

@@ -20,11 +20,18 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-load(:tls)
-
-add(:lets_encrypt_tls, :tls) do
-	lets_encrypt_root '/etc/letsencrypt/live'
+# A HTTP proxy environment.
+#
+# Derived from {.application}.
+#
+# @scope Falcon Environments
+# @name rack
+environment(:proxy) do
+	# The upstream endpoint that will handle incoming requests.
+	# @attribute [Async::HTTP::Endpoint]
+	endpoint {::Async::HTTP::Endpoint.parse(url)}
 	
-	ssl_certificate_path {File.join(lets_encrypt_root, authority, "fullchain.pem")}
-	ssl_private_key_path {File.join(lets_encrypt_root, authority, "privkey.pem")}
+	# The service class to use for the proxy.
+	# @attribute [Class]
+	service ::Falcon::Service::Proxy
 end