falcon 0.36.4 → 0.36.5

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.4"
+	VERSION = "0.36.5"
 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,6 +24,8 @@ 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)
 				

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.36.4
+  version: 0.36.5
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-25 00:00:00.000000000 Z
+date: 2020-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -248,21 +248,7 @@ 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:
@@ -271,47 +257,9 @@ executables:
 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
@@ -329,22 +277,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,18 +303,12 @@ 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: []
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -372,7 +316,7 @@ 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:
   - - ">="
@@ -380,7 +324,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A fast, asynchronous, rack-compatible web server.
 test_files: []

data/.editorconfig

@@ -1,5 +0,0 @@
-root = true
-
-[*]
-indent_style = tab
-indent_size = 2

data/.github/FUNDING.yml

@@ -1,3 +0,0 @@
-# These are supported funding model platforms
-custom: https://github.com/socketry/community/#funding
-github: ioquatix

data/.github/workflows/development.yml

@@ -1,60 +0,0 @@
-name: Development
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ${{matrix.os}}-latest
-    continue-on-error: ${{matrix.experimental}}
-    
-    strategy:
-      matrix:
-        experimental: [false]
-        
-        os:
-          - ubuntu
-          - macos
-        
-        ruby:
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        include:
-          # - experimental: true
-          #   os: ubuntu
-          #   ruby: truffleruby
-          # - experimental: true
-          #   os: ubuntu
-          #   ruby: jruby
-          - experimental: true
-            os: ubuntu
-            ruby: head
-          - experimental: true
-            os: ubuntu
-            ruby: 2.7
-            env: BUNDLE_GEMFILE=gems/rack1.gemfile
-          - experimental: true
-            os: ubuntu
-            ruby: 2.7
-            env: BUNDLE_GEMFILE=gems/rack3.gemfile
-          - experimental: true
-            os: ubuntu
-            ruby: 2.6
-            env: COVERAGE=PartialSummary,Coveralls
-    
-    steps:
-    - uses: actions/checkout@v1
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    
-    - name: Installing packages (ubuntu)
-      if: matrix.os == 'ubuntu'
-      run: sudo apt-get install apache2-utils
-    
-    - name: Install dependencies
-      run: ${{matrix.env}} bundle install
-    
-    - name: Run tests
-      run: ${{matrix.env}} bundle exec rspec