falcon 0.36.1 → 0.36.6

data/lib/falcon/command/paths.rb

@@ -24,13 +24,17 @@ require_relative '../configuration'
 
 module Falcon
 	module Command
+		# A helper for resolving wildcard configuration paths.
 		module Paths
+			# Resolve a set of `@paths` that may contain wildcards, into a sorted, unique array.
+			# @returns [Array(String)]
 			def resolved_paths(&block)
 				@paths.collect do |path|
 					Dir.glob(path)
 				end.flatten.sort.uniq.each(&block)
 			end
 			
+			# Build a configuration based on the resolved paths.
 			def configuration
 				configuration = Configuration.new
 				

data/lib/falcon/command/proxy.rb

@@ -27,31 +27,44 @@ require 'samovar'
 
 module Falcon
 	module Command
+		# Implements the `falcon proxy` command.
+		#
+		# Manages a {Controller::Proxy} instance which is responsible for proxing incoming requests.
 		class Proxy < Samovar::Command
 			self.description = "Proxy to one or more backend hosts."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option '--bind <address>', "Bind to the given hostname/address", default: "https://[::]:443"
 				
 				option '-t/--timeout <duration>', "Specify the maximum time to wait for non-blocking operations.", type: Float, default: nil
 			end
 			
+			# One or more paths to the configuration files.
+			# @name paths
+			# @attribute [Array(String)]
 			many :paths
 			
 			include Paths
 			
+			# Prepare a new controller for the command.
 			def controller
 				Controller::Proxy.new(self)
 			end
 			
+			# The container class to use.
 			def container_class
 				Async::Container.best_container_class
 			end
 			
+			# Options for the container.
+			# See {Controller::Serve#setup}.
 			def container_options
 				{}
 			end
 			
+			# Prepare the environment and run the controller.
 			def call
 				Async.logger.info(self) do |buffer|
 					buffer.puts "Falcon Proxy v#{VERSION} taking flight!"
@@ -63,6 +76,7 @@ module Falcon
 				self.controller.run
 			end
 			
+			# The endpoint to bind to.
 			def endpoint(**options)
 				Async::HTTP::Endpoint.parse(@options[:bind], timeout: @options[:timeout], **options)
 			end

data/lib/falcon/command/redirect.rb

@@ -30,6 +30,8 @@ module Falcon
 		class Redirect < Samovar::Command
 			self.description = "Redirect from insecure HTTP to secure HTTP."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option '--bind <address>', "Bind to the given hostname/address", default: "http://[::]:80"
 				option '--redirect <address>', "Redirect using this address as a template.", default: "https://[::]:443"
@@ -37,22 +39,30 @@ module Falcon
 				option '-t/--timeout <duration>', "Specify the maximum time to wait for non-blocking operations.", type: Float, default: nil
 			end
 			
+			# One or more paths to the configuration files.
+			# @name paths
+			# @attribute [Array(String)]
 			many :paths
 			
 			include Paths
 			
+			# Prepare a new controller for the command.
 			def controller
 				Controller::Redirect.new(self)
 			end
 			
+			# The container class to use.
 			def container_class
 				Async::Container.best_container_class
 			end
 			
+			# Options for the container.
+			# See {Controller::Serve#setup}.
 			def container_options
 				{}
 			end
 			
+			# Prepare the environment and run the controller.
 			def call
 				Async.logger.info(self) do |buffer|
 					buffer.puts "Falcon Redirect v#{VERSION} taking flight!"
@@ -64,10 +74,12 @@ module Falcon
 				self.controller.run
 			end
 			
+			# The endpoint to bind to.
 			def endpoint(**options)
 				Async::HTTP::Endpoint.parse(@options[:bind], timeout: @options[:timeout], **options)
 			end
 			
+			# The template endpoint to redirect to.
 			def redirect_endpoint(**options)
 				Async::HTTP::Endpoint.parse(@options[:redirect], **options)
 			end

data/lib/falcon/command/serve.rb

@@ -40,9 +40,14 @@ require 'bundler'
 
 module Falcon
 	module Command
+		# Implements the `falcon serve` command. Designed for *development*.
+		#
+		# Manages a {Controller::Serve} instance which is responsible for running applications in a development environment.
 		class Serve < Samovar::Command
 			self.description = "Run an HTTP server for development purposes."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option '-b/--bind <address>', "Bind to the given hostname/address.", default: "https://localhost:9292"
 				
@@ -63,6 +68,7 @@ module Falcon
 				option '--threads <count>', "Number of threads (hybrid only).", type: Integer
 			end
 			
+			# The container class to use.
 			def container_class
 				case @options[:container]
 				when :threaded
@@ -74,57 +80,58 @@ module Falcon
 				end
 			end
 			
+			# Whether verbose logging is enabled.
+			# @returns [Boolean]
 			def verbose?
 				@parent&.verbose?
 			end
 			
+			# Whether to enable the application HTTP cache.
+			# @returns [Boolean]
 			def cache?
 				@options[:cache]
 			end
 			
+			# Load the rack application from the specified configuration path.
+			# @returns [Protocol::HTTP::Middleware]
 			def load_app
 				rack_app, _ = Rack::Builder.parse_file(@options[:config])
 				
 				return Server.middleware(rack_app, verbose: self.verbose?, cache: self.cache?)
 			end
 			
-			def slice_options(*keys)
-				# TODO: Ruby 2.5 introduced Hash#slice
-				options = {}
-				
-				keys.each do |key|
-					if @options.key?(key)
-						options[key] = @options[key]
-					end
-				end
-				
-				return options
-			end
-			
+			# Options for the container.
+			# See {Controller::Serve#setup}.
 			def container_options
-				slice_options(:count, :forks, :threads)
+				@options.slice(:count, :forks, :threads)
 			end
 			
+			# Options for the {endpoint}.
 			def endpoint_options
-				slice_options(:hostname, :port, :reuse_port, :timeout)
+				@options.slice(:hostname, :port, :reuse_port, :timeout)
 			end
 			
+			# The endpoint to bind to.
 			def endpoint
 				Endpoint.parse(@options[:bind], **endpoint_options)
 			end
 			
+			# The endpoint suitable for a client to connect.
 			def client_endpoint
 				Async::HTTP::Endpoint.parse(@options[:bind], **endpoint_options)
 			end
 			
+			# Create a new client suitable for accessing the application.
 			def client
 				Async::HTTP::Client.new(client_endpoint)
 			end
 			
+			# Prepare a new controller for the command.
 			def controller
 				Controller::Serve.new(self)
 			end
 			
+			# Prepare the environment and run the controller.
 			def call
 				Async.logger.info(self) do |buffer|
 					buffer.puts "Falcon v#{VERSION} taking flight! Using #{self.container_class} #{self.container_options}."

data/lib/falcon/command/supervisor.rb

@@ -29,24 +29,33 @@ require 'async/io/unix_endpoint'
 
 module Falcon
 	module Command
+		# Implements the `falcon supervisor` command.
+		#
+		# Talks to an instance of the supervisor to issue commands and print results.
 		class Supervisor < Samovar::Command
-			self.description = "Control and query a specific host."
+			self.description = "Control and query a specific supervisor."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option "--path <path>", "The control IPC path.", default: "supervisor.ipc"
 			end
 			
+			# Implements the `falcon supervisor restart` command.
 			class Restart < Samovar::Command
 				self.description = "Restart the process group."
 				
+				# Send the restart message to the supervisor.
 				def call(stream)
 					stream.puts({please: 'restart'}.to_json, separator: "\0")
 				end
 			end
 			
+			# Implements the `falcon supervisor metrics` command.
 			class Metrics < Samovar::Command
 				self.description = "Show metrics about the falcon processes."
 				
+				# Send the metrics message to the supervisor and print the results.
 				def call(stream)
 					stream.puts({please: 'metrics'}.to_json, separator: "\0")
 					response = JSON.parse(stream.gets("\0"), symbolize_names: true)
@@ -55,15 +64,20 @@ module Falcon
 				end
 			end
 			
+			# The nested command to execute.
+			# @name nested
+			# @attribute [Command]
 			nested :command, {
 				'restart' => Restart,
 				'metrics' => Metrics,
 			}, default: 'metrics'
 			
+			# The endpoint the supervisor is bound to.
 			def endpoint
 				Async::IO::Endpoint.unix(@options[:path])
 			end
 			
+			# Connect to the supervisor and execute the requested command.
 			def call
 				Async do
 					endpoint.connect do |socket|

data/lib/falcon/command/top.rb

@@ -33,9 +33,12 @@ require 'samovar'
 
 module Falcon
 	module Command
+		# The top level command for the `falcon` executable.
 		class Top < Samovar::Command
 			self.description = "An asynchronous HTTP server."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option '--verbose | --quiet', "Verbosity of output for debugging.", key: :logging
 				option '-h/--help', "Print out help information."
@@ -43,6 +46,9 @@ module Falcon
 				option '-e/--encoding', "Specify the default external encoding of the server.", default: "UTF-8"
 			end
 			
+			# The nested command to execute.
+			# @name nested
+			# @attribute [Command]
 			nested :command, {
 				'serve' => Serve,
 				'host' => Host,
@@ -52,15 +58,23 @@ module Falcon
 				'supervisor' => Supervisor,
 			}, default: 'serve'
 			
+			# Whether verbose logging is enabled.
+			# @returns [Boolean]
 			def verbose?
 				@options[:logging] == :verbose
 			end
 			
+			# Whether quiet logging was enabled.
+			# @returns [Boolean]
 			def quiet?
 				@options[:logging] == :quiet
 			end
 			
+			# Update the external encoding.
+			#
 			# If you don't specify these, it's possible to have issues when encodings mismatch on the server.
+			#
+			# @parameter encoding [Encoding] Defaults to `Encoding::UTF_8`.
 			def update_external_encoding!(encoding = Encoding::UTF_8)
 				if Encoding.default_external != encoding
 					Console.logger.warn(self) {"Updating Encoding.default_external from #{Encoding.default_external} to #{encoding}"}
@@ -68,12 +82,14 @@ module Falcon
 				end
 			end
 			
+			# The desired external encoding.
 			def encoding
 				if name = @options[:encoding]
 					Encoding.find(name)
 				end
 			end
 			
+			# Prepare the environment and invoke the sub-command.
 			def call
 				if encoding = self.encoding
 					update_external_encoding!(encoding)

data/lib/falcon/command/virtual.rb

@@ -27,9 +27,14 @@ require 'samovar'
 
 module Falcon
 	module Command
+		# Implements the `falcon virtual` command. Designed for *deployment*.
+		#
+		# Manages a {Controller::Virtual} instance which is responsible for running the {Proxy} and {Redirect} instances.
 		class Virtual < Samovar::Command
 			self.description = "Run one or more virtual hosts with a front-end proxy."
 			
+			# The command line options.
+			# @attribute [Samovar::Options]
 			options do
 				option '--bind-insecure <address>', "Bind redirection to the given hostname/address", default: "http://[::]:80"
 				option '--bind-secure <address>', "Bind proxy to the given hostname/address", default: "https://[::]:443"
@@ -37,26 +42,34 @@ module Falcon
 				option '-t/--timeout <duration>', "Specify the maximum time to wait for non-blocking operations.", type: Float, default: 30
 			end
 			
+			# One or more paths to the configuration files.
+			# @name paths
+			# @attribute [Array(String)]
 			many :paths
 			
 			include Paths
 			
+			# Prepare a new controller for the command.
 			def controller
 				Controller::Virtual.new(self)
 			end
 			
+			# The URI to bind the `HTTPS` -> `falcon host` proxy.
 			def bind_secure
 				@options[:bind_secure]
 			end
 			
+			# The URI to bind the `HTTP` -> `HTTPS` redirector.
 			def bind_insecure
 				@options[:bind_insecure]
 			end
 			
+			# The connection timeout to use for incoming connections.
 			def timeout
 				@options[:timeout]
 			end
 			
+			# Prepare the environment and run the controller.
 			def call
 				Async.logger.info(self) do |buffer|
 					buffer.puts "Falcon Virtual v#{VERSION} taking flight!"
@@ -67,10 +80,12 @@ module Falcon
 				self.controller.run
 			end
 			
+			# The insecure endpoint for connecting to the {Redirect} instance.
 			def insecure_endpoint(**options)
 				Async::HTTP::Endpoint.parse(@options[:bind_insecure], **options)
 			end
 			
+			# The secure endpoint for connecting to the {Proxy} instance.
 			def secure_endpoint(**options)
 				Async::HTTP::Endpoint.parse(@options[:bind_secure], **options)
 			end

data/lib/falcon/configuration.rb

@@ -23,13 +23,36 @@
 require 'build/environment'
 
 module Falcon
+	# Manages environments which describes how to host a specific application.
+	#
+	# Environments are key-value maps with lazy value resolution. An environment can inherit from a parent environment, which can provide defaults
+	#
+	# A typical configuration file might look something like:
+	#
+	#	~~~ ruby
+	#	#!/usr/bin/env falcon-host
+	#	# frozen_string_literal: true
+	#	
+	#	load :rack, :self_signed_tls, :supervisor
+	#	
+	#	supervisor
+	#	
+	#	rack 'hello.localhost', :self_signed_tls do
+	#	end
+	#	~~~
+	#
 	class Configuration
-		def initialize(verbose = false)
+		# Initialize an empty configuration.
+		def initialize
 			@environments = {}
 		end
 		
+		# The map of named environments.
+		# @attribute [Hash(String, Build::Environment)]
 		attr :environments
 		
+		# Enumerate all environments that have the specified key.
+		# @parameter key [Symbol] Filter environments that don't have this key.
 		def each(key = :authority)
 			return to_enum(key) unless block_given?
 			
@@ -42,6 +65,7 @@ module Falcon
 			end
 		end
 		
+		# Add the named environment to the configuration.
 		def add(environment)
 			name = environment.name
 			
@@ -56,11 +80,17 @@ module Falcon
 			@environments[name] = environment
 		end
 		
+		# Load the specified configuration file. See {Loader#load_file} for more details.
 		def load_file(path)
 			Loader.load_file(self, path)
 		end
 		
+		# The domain specific language for loading configuration files.
 		class Loader
+			# Initialize the loader, attached to a specific configuration instance.
+			# Any environments generated by the loader will be added to the configuration.
+			# @parameter configuration [Configuration]
+			# @parameter root [String] The file-system root path for relative path computations.
 			def initialize(configuration, root = nil)
 				@loaded = {}
 				@configuration = configuration
@@ -68,9 +98,17 @@ module Falcon
 				@root = root
 			end
 			
-			attr :path
+			# The file-system root path which is injected into the environments as required.
+			# @attribute [String]
+			attr :root
+			
+			# The attached configuration instance.
+			# @attribute [Configuration]
 			attr :configuration
 			
+			# Load the specified file into the given configuration.
+			# @parameter configuration [Configuration]
+			# @oaram path [String] The path to the configuration file, e.g. `falcon.rb`.
 			def self.load_file(configuration, path)
 				path = File.realpath(path)
 				root = File.dirname(path)
@@ -80,11 +118,16 @@ module Falcon
 				loader.instance_eval(File.read(path), path)
 			end
 			
+			# Load specific features into the current configuration.
+			#
+			# Falcon provides default environments for different purposes. These are included in the gem, in the `environments/` directory. This method loads the code in those files into the current configuration.
+			#
+			# @parameter features [Array(Symbol)] The features to load.
 			def load(*features)
 				features.each do |feature|
 					next if @loaded.include?(feature)
 					
-					relative_path = File.join(__dir__, "configuration", "#{feature}.rb")
+					relative_path = File.join(__dir__, "environments", "#{feature}.rb")
 					
 					self.instance_eval(File.read(relative_path), relative_path)
 					
@@ -92,11 +135,18 @@ module Falcon
 				end
 			end
 			
-			def add(name, *parents, &block)
+			# Add the named environment, with zero or more parent environments, defined using the specified `block`.
+			# @parameter name [String] The name of the environment.
+			# @parameter parents [Array(Symbol)] The names of the parent environments to inherit.
+			# @yields {...} The block that will generate the environment.
+			def environment(name, *parents, &block)
 				raise KeyError.new("#{name} is already set", key: name) if @environments.key?(name)
 				@environments[name] = merge(name, *parents, &block)
 			end
-				
+			
+			# Define a host with the specified name.
+			# Adds `root` and `authority` keys.
+			# @parameter name [String] The name of the environment, usually a hostname.
 			def host(name, *parents, &block)
 				environment = merge(name, :host, *parents, &block)
 				
@@ -106,6 +156,9 @@ module Falcon
 				@configuration.add(environment.flatten)
 			end
 			
+			# Define a proxy with the specified name.
+			# Adds `root` and `authority` keys.
+			# @parameter name [String] The name of the environment, usually a hostname.
 			def proxy(name, *parents, &block)
 				environment = merge(name, :proxy, *parents, &block)
 				
@@ -115,6 +168,9 @@ module Falcon
 				@configuration.add(environment.flatten)
 			end
 			
+			# Define a rack application with the specified name.
+			# Adds `root` and `authority` keys.
+			# @parameter name [String] The name of the environment, usually a hostname.
 			def rack(name, *parents, &block)
 				environment = merge(name, :rack, *parents, &block)
 				
@@ -124,9 +180,11 @@ module Falcon
 				@configuration.add(environment.flatten)
 			end
 			
-			def supervisor
+			# Define a supervisor instance
+			# Adds `root` key.
+			def supervisor(&block)
 				name = File.join(@root, "supervisor")
-				environment = merge(name, :supervisor)
+				environment = merge(name, :supervisor, &block)
 				
 				environment[:root] = @root
 				
@@ -135,6 +193,10 @@ module Falcon
 				
 			private
 			
+			# Build a new environment with the specified name and the given parents.
+			# @parameter name [String]
+			# @parameter parents [Array(Build::Environment)]
+			# @yields {...} The block that will generate the environment.
 			def merge(name, *parents, &block)
 				environments = parents.map{|name| @environments.fetch(name)}