falcon 0.36.3 → 0.37.0

data/lib/falcon/service/generic.rb

@@ -22,7 +22,13 @@
 
 module Falcon
 	module Service
+		# Captures the stateful behaviour of a specific service.
+		# Specifies the interfaces required by derived classes.
+		#
+		# Designed to be invoked within an {Async::Controller::Container}.
 		class Generic
+			# Convert the given environment into a service if possible.
+			# @parameter environment [Build::Environment] The environment to use to construct the service.
 			def self.wrap(environment)
 				evaluator = environment.evaluator
 				service = evaluator.service || self
@@ -30,29 +36,41 @@ module Falcon
 				return service.new(environment)
 			end
 			
+			# Initialize the service from the given environment.
+			# @parameter environment [Build::Environment]
 			def initialize(environment)
 				@environment = environment
 				@evaluator = @environment.evaluator
 			end
 			
+			# Whether the service environment contains the specified keys.
+			# This is used for matching environment configuration to service behaviour.
 			def include?(keys)
 				keys.all?{|key| @environment.include?(key)}
 			end
 			
+			# The name of the service.
+			# e.g. `myapp.com`.
 			def name
 				@evaluator.name
 			end
 			
+			# The logger to use for this service.
+			# @returns [Console::Logger]
 			def logger
 				return Async.logger # .with(name: name)
 			end
 			
+			# Start the service.
 			def start
 			end
 			
+			# Setup the service into the specified container.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 			end
 			
+			# Stop the service.
 			def stop
 			end
 		end

data/lib/falcon/service/proxy.rb

@@ -32,26 +32,32 @@ module Falcon
 				"#{self.class} for #{self.authority}"
 			end
 			
+			# The host that this proxy will receive connections for.
 			def authority
 				@evaluator.authority
 			end
 			
+			# The upstream endpoint that this proxy will connect to.
 			def endpoint
 				@evaluator.endpoint
 			end
 			
+			# The {OpenSSL::SSL::SSLContext} that will be used for incoming connections.
 			def ssl_context
 				@evaluator.ssl_context
 			end
 			
+			# The root
 			def root
 				@evaluator.root
 			end
 			
+			# The protocol this proxy will use to talk to the upstream host.
 			def protocol
 				endpoint.protocol
 			end
 			
+			# The scheme this proxy will use to talk to the upstream host.
 			def scheme
 				endpoint.scheme
 			end

data/lib/falcon/service/supervisor.rb

@@ -28,33 +28,41 @@ require 'async/io/shared_endpoint'
 
 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
+			# Initialize the supervisor using the given environment.
+			# @parameter environment [Build::Environment]
 			def initialize(environment)
 				super
 				
 				@bound_endpoint = nil
 			end
 			
+			# The endpoint which the supervisor will bind to.
+			# Typically a unix pipe in the same directory as the host.
 			def endpoint
 				@evaluator.endpoint
 			end
 			
+			# Restart the process group that the supervisor belongs to.
 			def do_restart(message)
 				# Tell the parent of this process group to spin up a new process group/container.
 				# Wait for that to start accepting new connections.
 				# Stop accepting connections.
 				# Wait for existing connnections to drain.
 				# Terminate this process group.
-				
 				signal = message[:signal] || :INT
 				
 				Process.kill(signal, Process.ppid)
 			end
 			
+			# Capture process metrics relating to the process group that the supervisor belongs to.
 			def do_metrics(message)
 				Process::Metrics::General.capture(pid: Process.ppid, ppid: Process.ppid)
 			end
 			
+			# Handle an incoming request.
+			# @parameter message [Hash] The decoded message.
 			def handle(message)
 				case message[:please]
 				when 'restart'
@@ -64,6 +72,7 @@ module Falcon
 				end
 			end
 			
+			# Bind the supervisor to the specified endpoint.
 			def start
 				Async.logger.info(self) {"Binding to #{self.endpoint}..."}
 				
@@ -74,6 +83,8 @@ module Falcon
 				super
 			end
 			
+			# Start the supervisor process which accepts connections from the bound endpoint and processes JSON formatted messages.
+			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				container.run(name: self.name, restart: true, count: 1) do |instance|
 					Async do
@@ -93,6 +104,7 @@ module Falcon
 				super
 			end
 			
+			# Release the bound endpoint.
 			def stop
 				@bound_endpoint&.close
 				@bound_endpoint = nil

data/lib/falcon/services.rb

@@ -23,7 +23,19 @@
 require_relative 'service/generic'
 
 module Falcon
+	# Represents one or more services associated with a host.
+	#
+	# The services model allows falcon to manage one more more service associated with a given host. Some examples of services include:
+	#
+	# - Rack applications wrapped by {Service::Application}.
+	# - Host supervisor implemented in {Service::Supervisor}.
+	# - Proxy services wrapped by {Service::Proxy}.
+	#
+	# The list of services is typically generated from the user supplied `falcon.rb` configuration file, which is loaded into an immutable {Configuration} instance, which is mapped into a list of services.
 	class Services
+		# Initialize the services from the given configuration.
+		#
+		# @parameter configuration [Configuration]
 		def initialize(configuration)
 			@named = {}
 			
@@ -34,14 +46,19 @@ module Falcon
 			end
 		end
 		
+		# Enumerate all named services.
 		def each(&block)
 			@named.each_value(&block)
 		end
 		
+		# Add a named service.
+		#
+		# @parameter service [Service]
 		def add(service)
 			@named[service.name] = service
 		end
 		
+		# Start all named services.
 		def start
 			@named.each do |name, service|
 				Async.logger.debug(self) {"Starting #{name}..."}
@@ -49,6 +66,9 @@ module Falcon
 			end
 		end
 		
+		# Setup all named services into the given container.
+		#
+		# @parameter container [Async::Container::Generic]
 		def setup(container)
 			@named.each do |name, service|
 				Async.logger.debug(self) {"Setup #{name} into #{container}..."}
@@ -58,6 +78,7 @@ module Falcon
 			return container
 		end
 		
+		# Stop all named services.
 		def stop
 			failed = false
 			

data/lib/falcon/tls.rb

@@ -24,8 +24,10 @@ require_relative 'extensions/openssl'
 
 module Falcon
 	module TLS
-		# We follow "Intermediate compatibility"
-		# https://wiki.mozilla.org/Security/Server_Side_TLS
+		# The list of supported ciphers.
+		#
+		# We follow "Intermediate compatibility" as oulined here:
+		# <https://wiki.mozilla.org/Security/Server_Side_TLS>
 		SERVER_CIPHERS = [
 			# TLS 1.3:
 			"TLS_AES_128_GCM_SHA256",

data/lib/falcon/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module Falcon
-	VERSION = "0.36.3"
+	VERSION = "0.37.0"
 end

data/lib/rack/handler/falcon.rb

@@ -9,10 +9,14 @@ require 'async/io/host_endpoint'
 
 module Rack
 	module Handler
+		# The falcon adaptor for the `rackup` executable.
 		module Falcon
-			SCHEME = "http".freeze
+			# The default scheme.
+			SCHEME = "http"
 			NAME = :falcon
 			
+			# Generate an endpoint for the given `rackup` options.
+			# @returns [Async::IO::Endpoint]
 			def self.endpoint_for(**options)
 				host = options[:Host] || 'localhost'
 				port = Integer(options[:Port] || 9292)
@@ -20,13 +24,15 @@ module Rack
 				return Async::IO::Endpoint.tcp(host, port)
 			end
 			
+			# Run the specified app using the given options:
+			# @parameter app [Object] The rack middleware.
 			def self.run(app, **options)
 				endpoint = endpoint_for(**options)
 				
 				app = ::Falcon::Adapters::Rack.new(app)
 				app = ::Falcon::Adapters::Rewindable.new(app)
 				
-				server = ::Falcon::Server.new(app, endpoint, Async::HTTP::Protocol::HTTP1, SCHEME)
+				server = ::Falcon::Server.new(app, endpoint, protocol: Async::HTTP::Protocol::HTTP1, scheme: SCHEME)
 				yield server if block_given?
 				
 				Async::Reactor.run do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.36.3
+  version: 0.37.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-21 00:00:00.000000000 Z
+date: 2020-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -25,89 +25,89 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.13'
 - !ruby/object:Gem::Dependency
-  name: async-io
+  name: async-container
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.22'
+        version: 0.16.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.22'
+        version: 0.16.0
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.51.0
+        version: 0.54.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.51.0
+        version: 0.54.0
 - !ruby/object:Gem::Dependency
   name: async-http-cache
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
-  name: async-container
+  name: async-io
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: '1.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: '1.22'
 - !ruby/object:Gem::Dependency
-  name: rack
+  name: build-environment
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.13'
 - !ruby/object:Gem::Dependency
-  name: samovar
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: localhost
   requirement: !ruby/object:Gem::Requirement
@@ -123,91 +123,91 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: build-environment
+  name: process-metrics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
-  name: process-metrics
+  name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: async-rspec
+  name: samovar
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
-  type: :development
+        version: '2.1'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
-  name: async-websocket
+  name: async-process
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: async-process
+  name: async-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
-  name: bake
+  name: async-websocket
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.14.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.14.0
 - !ruby/object:Gem::Dependency
-  name: covered
+  name: bake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -221,7 +221,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: covered
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -248,72 +248,18 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: bake-bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: 
+description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables:
 - falcon
 - falcon-host
 extensions: []
 extra_rdoc_files: []
 files:
-- ".editorconfig"
-- ".github/FUNDING.yml"
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- Gemfile
-- README.md
 - bake/falcon/supervisor.rb
 - bin/falcon
 - bin/falcon-host
-- examples/beer/config.ru
-- examples/beer/falcon.rb
-- examples/benchmark/config.ru
-- examples/benchmark/falcon.rb
-- examples/csv/config.ru
-- examples/google/falcon.rb
-- examples/hello/config.ru
-- examples/hello/falcon.rb
-- examples/hello/preload.rb
-- examples/internet/config.ru
-- examples/memory/allocations.rb
-- examples/memory/config.ru
-- examples/push/client.rb
-- examples/push/config.ru
-- examples/push/index.html
-- examples/push/script.js
-- examples/push/style.css
-- examples/redis/Gemfile
-- examples/redis/config.ru
-- examples/sequel/Gemfile
-- examples/sequel/config.ru
-- examples/sequel/data.sqlite3
-- examples/server/standalone.rb
-- examples/sinatra/Gemfile
-- examples/sinatra/Gemfile.lock
-- examples/sinatra/config.ru
-- examples/trailers/config.ru
-- examples/trailers/falcon.rb
-- falcon.gemspec
-- gems/rack1.gemfile
-- gems/rack3.gemfile
 - lib/falcon.rb
-- lib/falcon/adapters/early_hints.rb
 - lib/falcon/adapters/input.rb
 - lib/falcon/adapters/output.rb
 - lib/falcon/adapters/rack.rb
@@ -329,22 +275,24 @@ files:
 - lib/falcon/command/top.rb
 - lib/falcon/command/virtual.rb
 - lib/falcon/configuration.rb
-- lib/falcon/configuration/application.rb
-- lib/falcon/configuration/lets_encrypt_tls.rb
-- lib/falcon/configuration/proxy.rb
-- lib/falcon/configuration/rack.rb
-- lib/falcon/configuration/self_signed_tls.rb
-- lib/falcon/configuration/supervisor.rb
-- lib/falcon/configuration/tls.rb
 - lib/falcon/controller/host.rb
 - lib/falcon/controller/proxy.rb
 - lib/falcon/controller/redirect.rb
 - lib/falcon/controller/serve.rb
 - lib/falcon/controller/virtual.rb
 - lib/falcon/endpoint.rb
+- lib/falcon/environments.rb
+- lib/falcon/environments/application.rb
+- lib/falcon/environments/lets_encrypt_tls.rb
+- lib/falcon/environments/proxy.rb
+- lib/falcon/environments/rack.rb
+- lib/falcon/environments/self_signed_tls.rb
+- lib/falcon/environments/supervisor.rb
+- lib/falcon/environments/tls.rb
 - lib/falcon/extensions/openssl.rb
 - lib/falcon/middleware/proxy.rb
 - lib/falcon/middleware/redirect.rb
+- lib/falcon/middleware/verbose.rb
 - lib/falcon/proxy_endpoint.rb
 - lib/falcon/server.rb
 - lib/falcon/service/application.rb
@@ -353,34 +301,29 @@ files:
 - lib/falcon/service/supervisor.rb
 - lib/falcon/services.rb
 - lib/falcon/tls.rb
-- lib/falcon/verbose.rb
 - lib/falcon/version.rb
 - lib/rack/handler/falcon.rb
-- logo-square.afdesign
-- logo.afdesign
-- logo.svg
-- server.rb
-- tasks/benchmark.rake
 homepage: https://github.com/socketry/falcon
-licenses: []
+licenses:
+- MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: A fast, asynchronous, rack-compatible web server.
 test_files: []