falcon 0.43.0 → 0.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5ddd9c37ee1b6095a034bee5bbc77dde5936b1c474b0a4077cc4488226b81be
-  data.tar.gz: b436f4b618ccb3ced4f88d2cdfba936c64143b7f3c54953cfcca293b68596363
+  metadata.gz: 1d8e9452c5073ac195044198c1b7c4739ddf69e0c506b362c401b99e29f71642
+  data.tar.gz: b628ae3f08f08c4493cf053ce6a1b258b0671ae81260e625f13adc2fe289552f
 SHA512:
-  metadata.gz: 261381a8fceacb86e4456c2e7abcc39ab544000005e71436e4962c2e0aed26897e9de2366b7710d51c47d92721c6d60072a4da678a7acad28ba8671b46abf318
-  data.tar.gz: e21ae1cf91c6539ee497c5e37d363d5554c26ef6d0c9d951b65cfd0e3b775a977bb69bc1a2a0775c695db246afe98b1dc6269a645866e39aa6251e8add9f0809
+  metadata.gz: aa6ed0e298e9f4ee972d30bdb378c119c691ba9c291c6ceb9fec2b2e6476c931c63042ee88f968d2d1c519d243f6a23196e9ce7f679840e9c01897db30987281
+  data.tar.gz: 60000766f699c5002bfb069db4ad4324ca8ae9775133bf9cfc3aef53cea0316bba227dd43c1c125773108dfc7e6b15a41e25abd07ea169877cf296a9e186f625

checksums.yaml.gz.sig

@@ -1 +1 @@
-/B����
+g��Ѧ=�dٚ?0A��i��o��U��r����:��ơ"�G)4�v�x����W49�JJ]j7�������

data/changes.md

@@ -0,0 +1,36 @@
+# Changes
+
+# v0.45.0
+
+## Compatibility Fixes
+
+During the `v0.44.0` release cycle, the workflows for testing older rack releases were accidentally dropped. As such, `v0.44.0` was not compatible with older versions of rack. This release restores compatibility with older versions of rack.
+
+Specifically, `protocol-rack` now provides `Protocol::Rack::Adapter.parse_file` to load Rack applications. Rack 2's `Rack::Builder.parse_file` returns both the application and a set of options (multi-value return). Rack 3 changed this to only return the application, as the prior multi-value return was confusing at best. This change allows `protocol-rack` to work with both versions of rack, and `falcon` adopts that interface.
+
+In addition, `falcon serve` provides two new options:
+
+1. `--[no]-restart` which controls what happens when `async-container` instances crash. By default, `falcon serve` will restart the container when it crashes. This can be disabled with `--no-restart`.
+
+2. `--graceful-stop [timeout]` which allows you to specify a timeout for graceful shutdown. This is useful when you want to stop the server, but allow existing connections to finish processing before the server stops. This feature is highly experimental and doesn't work correctly in all cases yet, but we are aiming to improve it.
+
+# v0.44.0
+
+## Falcon Host
+
+`async-service` is a new gem that exposes a generic service interface on top of `async-container`. Previously, `falcon host` used `async-container` directly and `build-environment` for configuration. In order to allow for more generic service definitions and configuration, `async-service` now provides a similar interface to `build-environment` and exposes this in a way that can be used for services other tha falcon. This makes it simpler to integrate multiple services into a single application.
+
+The current configuration format uses definitions like this:
+
+```ruby
+rack 'hello.localhost', :self_signed_tls
+```
+
+This changes to:
+
+```ruby
+service 'hello.localhost' do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::SelfSignedTLS
+end
+```

data/lib/falcon/command/host.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require_relative '../controller/host'
-require_relative '../configuration'
+require_relative 'paths'
 require_relative '../version'
 
 require 'samovar'
-require 'bundler'
+require 'async/service/controller'
 
 module Falcon
 	module Command
@@ -23,28 +22,13 @@ module Falcon
 			# @attribute [Array(String)]
 			many :paths, "Service configuration paths.", default: ["falcon.rb"]
 			
+			include Paths
+			
 			# The container class to use.
 			def container_class
 				Async::Container.best_container_class
 			end
 			
-			# Generate a configuration based on the specified {paths}.
-			def configuration
-				configuration = Configuration.new
-				
-				@paths.each do |path|
-					path = File.expand_path(path)
-					configuration.load_file(path)
-				end
-				
-				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
 				Console.logger.info(self) do |buffer|
@@ -54,17 +38,7 @@ module Falcon
 					buffer.puts "- To reload: kill -HUP #{Process.pid}"
 				end
 				
-				begin
-					Bundler.require(:preload)
-				rescue Bundler::GemfileNotFound
-					# Ignore.
-				end
-				
-				if GC.respond_to?(:compact)
-					GC.compact
-				end
-				
-				self.controller.run
+				Async::Service::Controller.run(self.configuration, container_class: self.container_class)
 			end
 		end
 	end

data/lib/falcon/command/proxy.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
-require_relative '../controller/proxy'
+require_relative '../environment/proxy'
 require_relative 'paths'
 
 require 'samovar'
@@ -31,20 +31,21 @@ module Falcon
 			
 			include Paths
 			
-			# Prepare a new controller for the command.
-			def controller
-				Controller::Proxy.new(self)
+			def environment(**options)
+				Async::Service::Environment.new(Falcon::Environment::Proxy).with(
+					root: Dir.pwd,
+					name: self.class.name,
+					verbose: self.parent&.verbose?,
+					url: @options[:bind],
+					timeout: @options[:timeout],
+					**options
+				)
 			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
-				{}
+			def configuration
+				Configuration.for(
+					self.environment(environments: super.environments)
+				)
 			end
 			
 			# Prepare the environment and run the controller.
@@ -54,9 +55,13 @@ module Falcon
 					buffer.puts "- Binding to: #{@options[:bind]}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"
 					buffer.puts "- To reload: kill -HUP #{Process.pid}"
+					
+					self.resolved_paths.each do |path|
+						buffer.puts "- Loading configuration from #{path}"
+					end
 				end
 				
-				self.controller.run
+				Async::Service::Controller.run(self.configuration)
 			end
 			
 			# The endpoint to bind to.

data/lib/falcon/command/redirect.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
-require_relative '../controller/redirect'
+require_relative '../environment/redirect'
 require_relative 'paths'
 
 require 'samovar'
@@ -29,20 +29,22 @@ module Falcon
 			
 			include Paths
 			
-			# Prepare a new controller for the command.
-			def controller
-				Controller::Redirect.new(self)
+			def environment(**options)
+				Async::Service::Environment.new(Falcon::Environment::Redirect).with(
+					root: Dir.pwd,
+					name: self.class.name,
+					verbose: self.parent&.verbose?,
+					url: @options[:bind],
+					redirect_url: @options[:redirect],
+					timeout: @options[:timeout],
+					**options
+				)
 			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
-				{}
+			def configuration
+				Configuration.for(
+					self.environment(environments: super.environments)
+				)
 			end
 			
 			# Prepare the environment and run the controller.
@@ -52,9 +54,13 @@ module Falcon
 					buffer.puts "- Binding to: #{@options[:bind]}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"
 					buffer.puts "- To reload: kill -HUP #{Process.pid}"
+					
+					self.resolved_paths.each do |path|
+						buffer.puts "- Loading configuration from #{path}"
+					end
 				end
 				
-				self.controller.run
+				Async::Service::Controller.run(self.configuration)
 			end
 			
 			# The endpoint to bind to.

data/lib/falcon/command/serve.rb

@@ -1,28 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 # Copyright, 2018, by Mitsutaka Mimura.
 
 require_relative '../server'
 require_relative '../endpoint'
-require_relative '../controller/serve'
+require_relative '../configuration'
+require_relative '../service/server'
+require_relative '../environment/rackup'
 
 require 'async/container'
-
-require 'async/io/trap'
-require 'async/io/host_endpoint'
-require 'async/io/shared_endpoint'
-require 'async/io/ssl_endpoint'
-
 require 'async/http/client'
-
 require 'samovar'
 
-require 'rack/builder'
-
-require 'bundler'
-
 module Falcon
 	module Command
 		# Implements the `falcon serve` command. Designed for *development*.
@@ -51,6 +42,45 @@ module Falcon
 				
 				option '--forks <count>', "Number of forks (hybrid only).", type: Integer
 				option '--threads <count>', "Number of threads (hybrid only).", type: Integer
+				
+				option '--[no]-restart', "Enable/disable automatic restart.", default: true
+				option '--graceful-stop <timeout>', "Duration to wait for graceful stop.", type: Float, default: 1.0
+			end
+			
+			def container_options
+				@options.slice(:count, :forks, :threads, :restart)
+			end
+			
+			def endpoint_options
+				@options.slice(:hostname, :port, :timeout)
+			end
+			
+			def environment
+				Async::Service::Environment.new(Falcon::Environment::Server).with(
+					Falcon::Environment::Rackup,
+					
+					root: Dir.pwd,
+					
+					verbose: self.parent&.verbose?,
+					cache: @options[:cache],
+					
+					container_options: self.container_options,
+					endpoint_options: self.endpoint_options,
+					
+					rackup_path: @options[:config],
+					preload: [@options[:preload]].compact,
+					url: @options[:bind],
+					
+					name: "server",
+					
+					endpoint: ->{Endpoint.parse(url, **endpoint_options)}
+				)
+			end
+			
+			def configuration
+				Configuration.new.tap do |configuration|
+					configuration.add(self.environment)
+				end
 			end
 			
 			# The container class to use.
@@ -65,37 +95,6 @@ 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
-			
-			# Options for the container.
-			# See {Controller::Serve#setup}.
-			def container_options
-				@options.slice(:count, :forks, :threads)
-			end
-			
-			# Options for the {endpoint}.
-			def endpoint_options
-				@options.slice(:hostname, :port, :reuse_port, :timeout)
-			end
-			
 			# The endpoint to bind to.
 			def endpoint
 				Endpoint.parse(@options[:bind], **endpoint_options)
@@ -111,11 +110,6 @@ module Falcon
 				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
 				Console.logger.info(self) do |buffer|
@@ -125,22 +119,7 @@ module Falcon
 					buffer.puts "- To reload configuration: kill -HUP #{Process.pid}"
 				end
 				
-				if path = @options[:preload]
-					full_path = File.expand_path(path)
-					load(full_path)
-				end
-				
-				begin
-					Bundler.require(:preload)
-				rescue Bundler::GemfileNotFound
-					# Ignore.
-				end
-				
-				if GC.respond_to?(:compact)
-					GC.compact
-				end
-				
-				self.controller.run
+				Async::Service::Controller.run(self.configuration, container_class: self.container_class, graceful_stop: @options[:graceful_stop])
 			end
 		end
 	end

data/lib/falcon/command/top.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
 require_relative 'serve'
 require_relative 'host'

data/lib/falcon/command/virtual.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
-require_relative '../controller/virtual'
+require_relative '../service/virtual'
 require_relative 'paths'
 
 require 'samovar'
@@ -30,26 +30,20 @@ module Falcon
 			# @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]
+			def environment
+				Async::Service::Environment.new(Falcon::Service::Virtual::Environment).with(
+					verbose: self.parent&.verbose?,
+					configuration_paths: self.paths,
+					bind_insecure: @options[:bind_insecure],
+					bind_secure: @options[:bind_secure],
+					timeout: @options[:timeout],
+				)
 			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]
+			def configuration
+				Async::Service::Configuration.new.tap do |configuration|
+					configuration.add(self.environment)
+				end
 			end
 			
 			# Prepare the environment and run the controller.
@@ -60,9 +54,7 @@ module Falcon
 					buffer.puts "- To reload all sites: kill -HUP #{Process.pid}"
 				end
 				
-				ENV['CONSOLE_LEVEL'] = 'debug'
-				
-				self.controller.run
+				Async::Service::Controller.run(self.configuration)
 			end
 			
 			# The insecure endpoint for connecting to the {Redirect} instance.

data/lib/falcon/configuration.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2019, by Sho Ito.
 
-require 'build/environment'
+require 'async/service'
 
 module Falcon
 	# Manages environments which describes how to host a specific application.
@@ -25,177 +25,79 @@ module Falcon
 	#	end
 	#	~~~
 	#
-	class Configuration
-		# 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?
-			
-			@environments.each do |name, environment|
-				environment = environment.flatten
-				
-				if environment.include?(key)
-					yield environment
-				end
-			end
-		end
-		
-		# Add the named environment to the configuration.
-		def add(environment)
-			name = environment.name
-			
-			unless name
-				raise ArgumentError, "Environment name is nil #{environment.inspect}"
-			end
-			
-			environment = environment.flatten
-			
-			raise KeyError.new("#{name.inspect} is already set", key: name) if @environments.key?(name)
-			
-			@environments[name] = environment
-		end
-		
+	class Configuration < ::Async::Service::Configuration
 		# 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
-				@environments = {}
-				@root = root
-			end
-			
-			# 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)
-				
-				loader = self.new(configuration, root)
-				
-				loader.instance_eval(File.read(path), path)
-			end
-			
+		class Loader < ::Async::Service::Loader
 			# 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.
-			#
+			# @deprecated Use `require` instead.
 			# @parameter features [Array(Symbol)] The features to load.
 			def load(*features)
 				features.each do |feature|
-					next if @loaded.include?(feature)
-					
 					case feature
 					when Symbol
-						relative_path = File.join(__dir__, "environments", "#{feature}.rb")
-						
-						self.instance_eval(File.read(relative_path), relative_path)
-						
-						@loaded[feature] = relative_path
-					when Module
-						feature.load(self)
-						
-						@loaded[feature] = feature
+						require File.join(__dir__, "environment", "#{feature}.rb")
 					else
 						raise LoadError, "Unsure about how to load #{feature}!"
 					end
 				end
 			end
 			
-			# 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.
+			# @deprecated Use `service` and `include Falcon::Environment::Server` instead.
 			# @parameter name [String] The name of the environment, usually a hostname.
 			def host(name, *parents, &block)
-				environment = merge(name, *parents, &block)
-				
-				environment[:root] = @root
-				environment[:authority] = name
-				
-				@configuration.add(environment.flatten)
+				@configuration.add(
+					merge(*parents, name: name, root: @root, authority: name, &block)
+				)
 			end
 			
 			# Define a proxy with the specified name.
 			# Adds `root` and `authority` keys.
+			# @deprecated Use `service` and `include Falcon::Environment::Proxy` instead.
 			# @parameter name [String] The name of the environment, usually a hostname.
 			def proxy(name, *parents, &block)
-				environment = merge(name, :proxy, *parents, &block)
-				
-				environment[:root] = @root
-				environment[:authority] = name
-				
-				@configuration.add(environment.flatten)
+				@configuration.add(
+					merge(:proxy, *parents, name: name, root: @root, authority: name, &block)
+				)
 			end
 			
 			# Define a rack application with the specified name.
 			# Adds `root` and `authority` keys.
+			# @deprecated Use `service` and `include Falcon::Environment::Rack` instead.
 			# @parameter name [String] The name of the environment, usually a hostname.
 			def rack(name, *parents, &block)
-				environment = merge(name, :rack, *parents, &block)
-				
-				environment[:root] = @root
-				environment[:authority] = name
-				
-				@configuration.add(environment.flatten)
+				@configuration.add(
+					merge(:rack, *parents, name: name, root: @root, authority: name, &block)
+				)
 			end
 			
 			# Define a supervisor instance
-			# Adds `root` key.
+			# @deprecated Use `service` and `include Falcon::Environment::Supervisor` instead.
 			def supervisor(&block)
 				name = File.join(@root, "supervisor")
-				environment = merge(name, :supervisor, &block)
 				
-				environment[:root] = @root
-				
-				@configuration.add(environment.flatten)
+				@configuration.add(
+					merge(:supervisor, name: name, root: @root, &block)
+				)
 			end
 				
 			private
 			
 			# Build a new environment with the specified name and the given parents.
 			# @parameter name [String]
-			# @parameter parents [Array(Build::Environment)]
+			# @parameter parents [Array(Symbol)]
 			# @yields {...} The block that will generate the environment.
-			def merge(name, *parents, &block)
-				environments = parents.map{|name| @environments.fetch(name)}
-				
-				parent = Build::Environment.combine(*environments)
+			def merge(*parents, **initial, &block)
+				facets = parents.map{|parent| Environment::LEGACY_ENVIRONMENTS.fetch(parent)}
 				
-				Build::Environment.new(parent, name: name, &block)
+				::Async::Service::Environment.build(*facets, **initial, &block)
 			end
 		end
 	end