Class: Falcon::Server

Inherits:
Async::HTTP::Server
  • Object
show all
Defined in:
lib/falcon/server.rb

Overview

A server listening on a specific endpoint, hosting a specific middleware.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*arguments, utilization_registry: nil, **options) ⇒ Server

Initialize the server and set up statistics tracking.



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/falcon/server.rb', line 58

def initialize(*arguments, utilization_registry: nil, **options)
	super(*arguments, **options)
	
	utilization_registry ||= Async::Utilization::Registry.new
	
	# Get metric references for utilization tracking:
	@connections_total_metric = utilization_registry.metric(:connections_total)
	@connections_active_metric = utilization_registry.metric(:connections_active)
	@requests_total_metric = utilization_registry.metric(:requests_total)
	@requests_active_metric = utilization_registry.metric(:requests_active)
end

Class Method Details

.middleware ⇒ Object

Deprecated.

Use rack_middleware instead.



21
22
23
24
25
 
# File 'lib/falcon/server.rb', line 21

def self.middleware(...)
	warn("`Falcon::Server.middleware` is deprecated, use `.rack_middleware` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
	
	return self.rack_middleware(...)
end

.protocol_middleware(application, verbose: false, cache: true) ⇒ Object

Wrap a protocol application with the standard server middleware.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/falcon/server.rb', line 39

def self.protocol_middleware(application, verbose: false, cache: true)
	::Protocol::HTTP::Middleware.build do
		if verbose
			use Middleware::Verbose
		end
		
		if cache
			use Async::HTTP::Cache::General
		end
		
		use ::Protocol::HTTP::ContentEncoding
		run application
	end
end

.rack_middleware(rack_app, verbose: false, cache: true) ⇒ Object

Wrap a Rack application with the standard server middleware.



31
32
33
 
# File 'lib/falcon/server.rb', line 31

def self.rack_middleware(rack_app, verbose: false, cache: true)
	return self.protocol_middleware(::Protocol::Rack::Adapter.new(rack_app), verbose: verbose, cache: cache)
end

Instance Method Details

#accept ⇒ Object

Accept a new connection and track connection statistics.



71
72
73
74
75
76
 
# File 'lib/falcon/server.rb', line 71

def accept(...)
	@connections_total_metric.increment
	@connections_active_metric.track do
		super
	end
end

#call ⇒ Object

Handle a request and track request statistics.

Uses manual increment/decrement so requests_active stays elevated until the response body is closed (including rack.response_finished). The Body::RequestFinished wrapper runs the decrement after the body closes, so response_finished callbacks are counted as active.



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/falcon/server.rb', line 84

def call(...)
	decrement = false
	
	@requests_total_metric.increment
	@requests_active_metric.increment
	decrement = true
	
	# Roll back `requests_active` unless the full `super` + wrap path completes. Covers
	# `super` raising before `wrap` runs, errors inside `wrap`, and other abnormal exits.
	response = Body::RequestFinished.wrap(super, @requests_active_metric)
	decrement = false
	
	return response
ensure
	if decrement
		@requests_active_metric.decrement
	end
end

#statistics_string ⇒ Object

Generates a human-readable string representing the current statistics.

e.g. C=23/3.42K R=2/3.42K L=0.273

This can be interpreted as:

  • C=23/3.42K - The number of connections currently open and the total number of connections accepted.
  • R=2/3.42K - The number of requests currently being processed and the total number of requests received.
  • L=0.273 - The average scheduler load of the server, where 0.0 is idle and 1.0 is fully loaded.


114
115
116
 
# File 'lib/falcon/server.rb', line 114

def statistics_string
	"C=#{format_count @connections_active_metric.value}/#{format_count @connections_total_metric.value} R=#{format_count @requests_active_metric.value}/#{format_count @requests_total_metric.value}"
end