falcon 0.43.0 → 0.44.0

data/lib/falcon/environment/application.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2020, by Daniel Evans.
+
+require_relative 'server'
+require_relative '../proxy_endpoint'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a web application that uses TLS.
+		module Application
+			include Server
+			
+			# The middleware stack for the application.
+			# @returns [Protocol::HTTP::Middleware]
+			def middleware
+				::Protocol::HTTP::Middleware::HelloWorld
+			end
+			
+			# The scheme to use to communicate with the application.
+			# @returns [String]
+			def scheme
+				'https'
+			end
+			
+			# The protocol to use to communicate with the application.
+			#
+			# Typically one of {Async::HTTP::Protocol::HTTP1} or {Async::HTTP::Protocl::HTTP2}.
+			#
+			# @returns [Async::HTTP::Protocol]
+			def protocol
+				Async::HTTP::Protocol::HTTP2
+			end
+			
+			# The IPC path to use for communication with the application.
+			# @returns [String]
+			def ipc_path
+				::File.expand_path("application.ipc", root)
+			end
+			
+			# The endpoint that will be used for communicating with the application server.
+			# @returns [Async::IO::Endpoint]
+			def endpoint
+				::Falcon::ProxyEndpoint.unix(ipc_path,
+					protocol: protocol,
+					scheme: scheme,
+					authority: authority
+				)
+			end
+			
+			# Number of instances to start.
+			# @returns [Integer | nil]
+			def count
+				nil
+			end
+		end
+	end
+end

data/lib/falcon/environment/lets_encrypt_tls.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+
+require_relative 'tls'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment that uses "Lets Encrypt" for TLS.
+		module LetsEncryptTLS
+			# The Lets Encrypt certificate store path.
+			# @parameter [String]
+			def lets_encrypt_root
+				'/etc/letsencrypt/live'
+			end
+			
+			# The public certificate path.
+			# @attribute [String]
+			def ssl_certificate_path
+				File.join(lets_encrypt_root, authority, "fullchain.pem")
+			end
+			
+			# The private key path.
+			# @attribute [String]
+			def ssl_private_key_path
+				File.join(lets_encrypt_root, authority, "privkey.pem")
+			end
+		end
+		
+		LEGACY_ENVIRONMENTS[:tls] = TLS
+	end
+end

data/lib/falcon/environment/proxy.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require_relative 'server'
+require_relative '../tls'
+require_relative '../middleware/proxy'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a TLS-capable reverse proxy using SNI.
+		module Proxy
+			include Server
+			
+			# The host that this proxy will receive connections for.
+			def url
+				"https://[::]:443"
+			end
+			
+			# The default SSL session identifier.
+			def tls_session_id
+				"falcon"
+			end
+			
+			# The services we will proxy to.
+			# @returns [Array(Async::Service::Environment)]
+			def environments
+				[]
+			end
+			
+			# The hosts we will proxy to. This is a hash of SNI authority -> evaluator.
+			# @returns [Hash(String, Async::Service::Environment::Evaluator)]
+			def hosts
+				hosts = {}
+				
+				environments.each do |environment|
+					evaluator = environment.evaluator
+					
+					# next unless environment.implements?(Falcon::Environment::Application)
+					if evaluator.key?(:authority) and evaluator.key?(:ssl_context) and evaluator.key?(:endpoint)
+						Console.info(self) {"Proxying #{self.url} to #{evaluator.authority} using #{evaluator.endpoint}"}
+						hosts[evaluator.authority] = evaluator
+						
+						if RUBY_VERSION < '3.1'
+							# Ensure the SSL context is set up before forking - it's buggy on Ruby < 3.1:
+							evaluator.ssl_context
+						end
+					end
+				end
+				
+				return hosts
+			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)
+				hosts = self.hosts
+				
+				if host = hosts[hostname]
+					Console.logger.debug(self) {"Resolving #{hostname} -> #{host}"}
+					
+					socket.hostname = hostname
+					
+					return host.ssl_context
+				else
+					Console.logger.warn(self, hosts: hosts.keys) {"Unable to resolve #{hostname}!"}
+					
+					return nil
+				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|
+						self.host_context(socket, hostname)
+					end
+					
+					context.session_id_context = @session_id
+					
+					context.ssl_version = :TLSv1_2_server
+					
+					context.set_params(
+						ciphers: ::Falcon::TLS::SERVER_CIPHERS,
+						verify_mode: ::OpenSSL::SSL::VERIFY_NONE,
+					)
+					
+					context.setup
+				end
+			end
+			
+			# The endpoint the server will bind to.
+			def endpoint
+				super.with(
+					ssl_context: self.ssl_context,
+				)
+			end
+			
+			def middleware
+				return Middleware::Proxy.new(Middleware::BadRequest, self.hosts)
+			end
+		end
+		
+		LEGACY_ENVIRONMENTS[:proxy] = Proxy
+	end
+end

data/lib/falcon/environment/rack.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require_relative 'application'
+require_relative 'rackup'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a web application that use a Rackup `config.ru` file.
+		module Rack
+			include Application
+			include Rackup
+		end
+		
+		LEGACY_ENVIRONMENTS[:rack] = Rack
+	end
+end

data/lib/falcon/environment/rackup.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require 'rack/builder'
+require_relative '../server'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting loading a Rackup `config.ru` file.
+		module Rackup
+			def rackup_path
+				'config.ru'
+			end
+			
+			def rack_app
+				::Rack::Builder.parse_file(rackup_path)
+			end
+			
+			def middleware
+				::Falcon::Server.middleware(rack_app, verbose: verbose, cache: cache)
+			end
+		end
+	end
+end

data/lib/falcon/environment/redirect.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+
+require_relative 'server'
+require_relative '../middleware/redirect'
+
+module Falcon
+	module Environment
+		# Provides an environment for redirecting insecure web traffic to a secure endpoint.
+		module Redirect
+			include Server
+			
+			def redirect_url
+				"https://[::]:443"
+			end
+			
+			def redirect_endpoint
+				Async::HTTP::Endpoint.parse(redirect_url)
+			end
+			
+			# The services we will redirect to.
+			# @returns [Array(Async::Service::Environment)]
+			def environments
+				[]
+			end
+			
+			def hosts
+				hosts = {}
+				
+				environments.each do |environment|
+					evaluator = environment.evaluator
+					
+					if environment.implements?(Falcon::Environment::Application)
+						Console.info(self) {"Redirecting #{self.url} to #{evaluator.authority}"}
+						hosts[evaluator.authority] = evaluator
+					end
+				end
+				
+				return hosts
+			end
+			
+			# Load the {Middleware::Redirect} application with the specified hosts.
+			def middleware
+				Middleware::Redirect.new(Middleware::NotFound, hosts, redirect_endpoint)
+			end
+		end
+	end
+end

data/lib/falcon/environment/self_signed_tls.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require 'localhost/authority'
+require_relative 'tls'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment that exposes a self-signed TLS certificate using the `localhost` gem.
+		module SelfSignedTLS
+			# The default session identifier for the session cache.
+			# @returns [String]
+			def ssl_session_id
+				"falcon"
+			end
+			
+			# The SSL context to use for incoming connections.
+			# @returns [OpenSSL::SSL::SSLContext]
+			def ssl_context
+				contexts = Localhost::Authority.fetch(authority)
+				
+				contexts.server_context.tap do |context|
+					context.alpn_select_cb = lambda do |protocols|
+						if protocols.include? "h2"
+							return "h2"
+						elsif protocols.include? "http/1.1"
+							return "http/1.1"
+						elsif protocols.include? "http/1.0"
+							return "http/1.0"
+						else
+							return nil
+						end
+					end
+					
+					context.session_id_context = ssl_session_id
+				end
+			end
+		end
+		
+		LEGACY_ENVIRONMENTS[:self_signed_tls] = SelfSignedTLS
+	end
+end

data/lib/falcon/environment/server.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require 'async/service/generic'
+require 'async/http/endpoint'
+
+require_relative '../service/server'
+require_relative '../server'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a web application that uses a Falcon server.
+		module Server
+			# The service class to use for the proxy.
+			# @returns [Class]
+			def service_class
+				Service::Server
+			end
+			
+			# The server authority. Defaults to the server name.
+			# @returns [String]
+			def authority
+				self.name
+			end
+			
+			# Options to use when creating the container.
+			def container_options
+				{restart: true}
+			end
+			
+			# The host that this server will receive connections for.
+			def url
+				"http://[::]:9292"
+			end
+			
+			def timeout
+				nil
+			end
+			
+			# The upstream endpoint that will handle incoming requests.
+			# @returns [Async::HTTP::Endpoint]
+			def endpoint
+				::Async::HTTP::Endpoint.parse(url).with(
+					reuse_address: true,
+					timeout: timeout,
+				)
+			end
+			
+			def verbose
+				false
+			end
+			
+			def cache
+				false
+			end
+			
+			def client_endpoint
+				::Async::HTTP::Endpoint.parse(url)
+			end
+			
+			# Any scripts to preload before starting the server.
+			def preload
+				[]
+			end
+		end
+	end
+end

data/lib/falcon/environment/supervisor.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require_relative '../service/supervisor'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a supervisor which can monitor multiple applications.
+		module Supervisor
+			# The name of the supervisor
+			# @returns [String]
+			def name
+				"supervisor"
+			end
+			
+			# The IPC path to use for communication with the supervisor.
+			# @returns [String]
+			def ipc_path
+				::File.expand_path("supervisor.ipc", root)
+			end
+			
+			# The endpoint the supervisor will bind to.
+			# @returns [Async::IO::Endpoint]
+			def endpoint
+				Async::IO::Endpoint.unix(ipc_path)
+			end
+			
+			# The service class to use for the supervisor.
+			# @returns [Class]
+			def service_class
+				::Falcon::Service::Supervisor
+			end
+		end
+		
+		LEGACY_ENVIRONMENTS[:supervisor] = Supervisor
+	end
+end

data/lib/falcon/environment/tls.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require_relative '../tls'
+require_relative '../environment'
+
+module Falcon
+	module Environment
+		# Provides an environment that exposes a TLS context for hosting a secure web application.
+		module TLS
+			# The default session identifier for the session cache.
+			# @returns [String]
+			def ssl_session_id
+				"falcon"
+			end
+			
+			# The supported ciphers.
+			# @returns [Array(String)]
+			def ssl_ciphers
+				Falcon::TLS::SERVER_CIPHERS
+			end
+			
+			# The public certificate path.
+			# @returns [String]
+			def ssl_certificate_path
+				File.expand_path("ssl/certificate.pem", root)
+			end
+			
+			# The list of certificates loaded from that path.
+			# @returns [Array(OpenSSL::X509::Certificate)]
+			def ssl_certificates
+				OpenSSL::X509::Certificate.load_file(ssl_certificate_path)
+			end
+			
+			# The main certificate.
+			# @returns [OpenSSL::X509::Certificate]
+			def ssl_certificate
+				ssl_certificates[0]
+			end
+			
+			# The certificate chain.
+			# @returns [Array(OpenSSL::X509::Certificate)]
+			def ssl_certificate_chain
+				ssl_certificates[1..-1]
+			end
+			
+			# The private key path.
+			# @returns [String]
+			def ssl_private_key_path
+				File.expand_path("ssl/private.key", root)
+			end
+			
+			# The private key.
+			# @returns [OpenSSL::PKey::RSA]
+			def ssl_private_key
+				OpenSSL::PKey::RSA.new(File.read(ssl_private_key_path))
+			end
+			
+			# The SSL context to use for incoming connections.
+			# @returns [OpenSSL::SSL::SSLContext]
+			def ssl_context
+				OpenSSL::SSL::SSLContext.new.tap do |context|
+					context.add_certificate(ssl_certificate, ssl_private_key, ssl_certificate_chain)
+					
+					context.session_cache_mode = OpenSSL::SSL::SSLContext::SESSION_CACHE_CLIENT
+					context.session_id_context = ssl_session_id
+					
+					context.alpn_select_cb = lambda do |protocols|
+						if protocols.include? "h2"
+							return "h2"
+						elsif protocols.include? "http/1.1"
+							return "http/1.1"
+						elsif protocols.include? "http/1.0"
+							return "http/1.0"
+						else
+							return nil
+						end
+					end
+					
+					# TODO Ruby 2.4 requires using ssl_version.
+					context.ssl_version = :TLSv1_2_server
+					
+					context.set_params(
+						ciphers: ssl_ciphers,
+						verify_mode: OpenSSL::SSL::VERIFY_NONE,
+					)
+					
+					context.setup
+				end
+			end
+		end
+		
+		LEGACY_ENVIRONMENTS[:tls] = TLS
+	end
+end

data/lib/falcon/{environments.rb → environment.rb}

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
-
-require 'build/environment'
+# Copyright, 2019-2024, by Samuel Williams.
 
 module Falcon
 	# Pre-defined environments for hosting web applications.
 	#
 	# See {Configuration::Loader#load} for more details.
-	module Environments
+	module Environment
+		LEGACY_ENVIRONMENTS = {}
 	end
 end

data/lib/falcon/service/server.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020, by Michael Adams.
+
+require 'async/service/generic'
+require 'async/http/endpoint'
+
+require_relative '../server'
+
+module Falcon
+	module Service
+		class Server < Async::Service::Generic
+			def initialize(...)
+				super
+				
+				@bound_endpoint = nil
+			end
+			
+			# Preload any resources specified by the environment.
+			def preload!
+				root = @evaluator.root
+				
+				if scripts = @evaluator.preload
+					scripts = Array(scripts)
+					
+					scripts.each do |path|
+						Console.logger.info(self) {"Preloading #{path}..."}
+						full_path = File.expand_path(path, root)
+						load(full_path)
+					end
+				end
+			end
+			
+			# Prepare the bound endpoint for the server.
+			def start
+				@endpoint = @evaluator.endpoint
+				
+				Sync do
+					@bound_endpoint = @endpoint.bound
+				end
+				
+				preload!
+				
+				Console.logger.info(self) {"Starting #{self.name} on #{@endpoint}"}
+				
+				super
+			end
+			
+			# Setup the container with the application instance.
+			# @parameter container [Async::Container::Generic]
+			def setup(container)
+				container_options = @evaluator.container_options
+				
+				container.run(name: self.name, **container_options) do |instance|
+					evaluator = @environment.evaluator
+					
+					Async do |task|
+						server = Falcon::Server.new(evaluator.middleware, @bound_endpoint, protocol: @endpoint.protocol, scheme: @endpoint.scheme)
+						
+						server.run
+						
+						instance.ready!
+						
+						task.children.each(&:wait)
+					end
+				end
+			end
+			
+			# Close the bound endpoint.
+			def stop(...)
+				if @bound_endpoint
+					@bound_endpoint.close
+					@bound_endpoint = nil
+				end
+				
+				@endpoint = nil
+				
+				super
+			end
+		end
+	end
+end

data/lib/falcon/service/supervisor.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require 'process/metrics'
 require 'json'
 
 require 'async/io/endpoint'
 require 'async/io/shared_endpoint'
+require 'async/service/generic'
 
 module Falcon
 	module Service
 		# Implements a host supervisor which can restart the host services and provide various metrics about the running processes.
-		class Supervisor < Generic
+		class Supervisor < Async::Service::Generic
 			# Initialize the supervisor using the given environment.
 			# @parameter environment [Build::Environment]
-			def initialize(environment)
+			def initialize(...)
 				super
 				
 				@bound_endpoint = nil