Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions lib/falcon/listener.rb
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,37 @@
# Released under the MIT License.
# Copyright, 2026, by Samuel Williams.

require "io/endpoint/bound_endpoint"

module Falcon
# Describes a bound listener for a Falcon server.
class Listener
# A bound endpoint whose sockets are shared by the workers of a service.
class Endpoint < ::IO::Endpoint::BoundEndpoint
# Bind the endpoint using the given wrapper. Once a socket stops listening, see {Listener#shutdown}, its accept loop waits to be stopped, as it does while no connections arrive.
# @parameter wrapper [::IO::Endpoint::Wrapper] The wrapper to use for binding.
# @yields {|socket| ...} If a block is given, yields each bound socket.
# @parameter socket [Socket] A bound socket.
# @returns [Array(Socket)] An array of bound sockets.
def bind(wrapper = self.wrapper, &block)
return super unless block_given?

super do |server|
yield server
rescue Errno::EINVAL
raise if listening?(server)

sleep
end
end

private

def listening?(server)
server.to_io.getsockopt(::Socket::SOL_SOCKET, ::Socket::SO_ACCEPTCONN).bool
end
end

# Initialize a bound listener.
# @parameter name [String] The logical listener name.
# @parameter scheme [String] The application protocol scheme.
Expand Down Expand Up @@ -35,6 +63,19 @@ def initialize(name:, scheme:, protocols:, endpoint:)
# @attribute [Array(Addrinfo)] The bound addresses.
attr_reader :addresses

# Stop listening on the bound TCP sockets, in every process that shares them. New connections are refused, and established connections are unaffected.
#
# Closing the endpoint is not enough when forked workers hold their own descriptors for its sockets. Only Linux stops a socket listening when it is shut down, and only for TCP: a UNIX socket refuses connections but stays readable, so its accept loops would spin. Other sockets keep listening until every descriptor is closed.
def shutdown
return unless RUBY_PLATFORM.include?("linux")

@endpoint.sockets.each do |socket|
io = socket.to_io

io.shutdown(::Socket::SHUT_RD) if io.local_address.ip?
end
end

# Close the bound endpoint.
def close
@endpoint.close
Expand Down
9 changes: 7 additions & 2 deletions lib/falcon/service/server.rb
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ def initialize(...)
super

@listener = nil
@multiprocess = false
end

# Build a listener from a configured and bound endpoint.
Expand All @@ -41,7 +42,7 @@ def bind_endpoint
@endpoint = @evaluator.endpoint

Sync do
bound_endpoint = @endpoint.bound
bound_endpoint = Listener::Endpoint.bound(@endpoint)
@listener = make_listener(@evaluator, @endpoint, bound_endpoint)
end

Expand All @@ -66,6 +67,8 @@ def with_listener(evaluator)
# Setup the service into the specified container.
# @parameter container [Async::Container] The container to configure.
def setup(container)
@multiprocess = container.class.multiprocess?

container_options = @evaluator.container_options
health_check_timeout = container_options[:health_check_timeout]

Expand Down Expand Up @@ -132,9 +135,11 @@ def run(instance, evaluator, listener = @listener)
"#{evaluator.name} (#{server.statistics_string} L=#{load})"
end

# Close the bound endpoint.
# Stop listening, and close the bound endpoint. New connections are refused while the workers finish the requests they have already accepted.
def stop(...)
if @listener
# Closing the listener is enough, unless workers in other processes hold their own descriptors for it:
@listener.shutdown if @multiprocess
@listener.close
@listener = nil
end
Expand Down
1 change: 1 addition & 0 deletions releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased

- Refuse new connections as soon as a server stops, while it finishes the requests in flight. Forked and hybrid workers hold their own descriptors for the listening socket, so it kept listening until the last worker exited: connections that arrived in the meantime were queued, and then reset. `Falcon::Service::Server#stop` now shuts the socket down with `Falcon::Listener#shutdown`. This applies to TCP sockets on Linux. UNIX sockets, and other platforms, behave as before.
- Document that `falcon virtual` evaluates every `falcon.rb` in the proxy and redirect processes, so every user who owns a `falcon.rb` must be trusted to the same extent as the user running `falcon virtual`, and that an unprivileged `falcon virtual` requires every `falcon.rb` to be owned by that same user.

## v0.57.0
Expand Down
40 changes: 40 additions & 0 deletions test/falcon/listener.rb
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@
# Copyright, 2026, by Samuel Williams.

require "falcon/listener"
require "io/endpoint/host_endpoint"
require "io/endpoint/unix_endpoint"
require "tmpdir"

describe Falcon::Listener do
def make_listener(*addresses, name: "hello", scheme: "http", protocols: ["http/1.1", "http/1.0"])
Expand Down Expand Up @@ -45,4 +48,41 @@ def close

expect(listener.endpoint.closed).to be == true
end

it "stops listening on a socket that another descriptor keeps open" do
skip "Only Linux can shut down a listening socket!" unless RUBY_PLATFORM.include?("linux")

endpoint = subject::Endpoint.bound(IO::Endpoint.tcp("127.0.0.1", 0))
listener = subject.new(name: "hello", scheme: "http", protocols: ["http/1.1"], endpoint: endpoint)
address = listener.addresses.first

# A forked worker holds its own descriptor for the socket, as these duplicates do:
inherited = endpoint.bind

listener.shutdown
listener.close

expect do
Socket.tcp(address.ip_address, address.ip_port).close
end.to raise_exception(Errno::ECONNREFUSED)
ensure
inherited&.each(&:close)
endpoint&.close
end

it "leaves a UNIX socket listening" do
Dir.mktmpdir do |directory|
path = File.join(directory, "falcon.ipc")
endpoint = subject::Endpoint.bound(IO::Endpoint.unix(path))
listener = subject.new(name: "hello", scheme: "http", protocols: ["http/1.1"], endpoint: endpoint)

listener.shutdown

expect do
UNIXSocket.new(path).close
end.not.to raise_exception
ensure
endpoint&.close
end
end
end
81 changes: 81 additions & 0 deletions test/falcon/listener/endpoint.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# frozen_string_literal: true

# Released under the MIT License.
# Copyright, 2026, by Samuel Williams.

require "falcon/listener"
require "io/endpoint/host_endpoint"
require "sus/fixtures/async/scheduler_context"

describe Falcon::Listener::Endpoint do
include Sus::Fixtures::Async::SchedulerContext

let(:endpoint) {subject.bound(IO::Endpoint.tcp("127.0.0.1", 0))}
let(:listener) {Falcon::Listener.new(name: "hello", scheme: "http", protocols: ["http/1.1"], endpoint: endpoint)}
let(:address) {listener.addresses.first}

after do
endpoint.close
end

it "duplicates the bound sockets" do
sockets = endpoint.bind

expect(sockets.size).to be == 1
expect(sockets.first.local_address.ip_port).to be == address.ip_port
expect(sockets.first.fileno).not.to be == endpoint.sockets.first.fileno
ensure
sockets&.each(&:close)
end

it "accepts connections" do
accepted = Async::Queue.new

accepting = Async do |task|
endpoint.accept do |peer|
accepted.enqueue(peer.read)
end

task.children.each(&:wait)
end

Socket.tcp(address.ip_address, address.ip_port) do |socket|
socket.write("Hello World")
end

expect(accepted.dequeue).to be == "Hello World"
ensure
accepting&.stop
end

it "waits to be stopped once the listener has shut down" do
skip "Only Linux can shut down a listening socket!" unless RUBY_PLATFORM.include?("linux")

accepting = Async do |task|
endpoint.bind do |server|
listener.shutdown
server.accept
end

task.children.each(&:wait)
end

expect(accepting).to be(:running?)
ensure
accepting&.stop
end

it "raises an error from a socket that is still listening" do
accepting = Async do |task|
endpoint.bind do
# Fail once the parent task is waiting, so that the failure is reported to it:
sleep(0.001)
raise Errno::EINVAL
end

task.children.each(&:wait)
end

expect{accepting.wait}.to raise_exception(Errno::EINVAL)
end
end
108 changes: 108 additions & 0 deletions test/falcon/service/server.rb
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,76 @@
require "falcon/environment/server"
require "falcon/environment/rackup"
require "sus/fixtures/async/scheduler_context"
require "async/container"
require "async/http/client"
require "async/service/environment"

AStoppingServer = Sus::Shared("a stopping server") do
let(:arrived) {IO.pipe}
let(:proceed) {IO.pipe}

# Reports each request to `/slow`, and then holds it until the test lets it proceed.
let(:application) do
arrived_output = arrived.last
proceed_input = proceed.first

Module.new do
define_method(:middleware) do
Protocol::HTTP::Middleware.for do |request|
if request.path == "/slow"
arrived_output.write(".")
proceed_input.read(1)
end

Protocol::HTTP::Response[200, {}, ["Hello World"]]
end
end
end
end

let(:environment) do
Async::Service::Environment.new(Falcon::Environment::Server).with(
application,
name: "hello",
root: __dir__,
url: "http://127.0.0.1:0",
container_options: container_options,
)
end

after do
[*arrived, *proceed].each(&:close)
end

it "refuses new connections and finishes the requests in flight" do
container = container_class.new

server.start
address = server.with_listener(environment.evaluator){|listener| listener.addresses.first}
server.setup(container)
container.wait_until_ready

client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse("http://#{address.ip_address}:#{address.ip_port}"))
request = Async{client.get("/slow").read}
arrived.first.read(1)

server.stop

# Only Linux can shut down a listening socket:
if RUBY_PLATFORM.include?("linux")
expect do
Socket.tcp(address.ip_address, address.ip_port).close
end.to raise_exception(Errno::ECONNREFUSED)
end

proceed.last.write(".")
expect(request.wait).to be == "Hello World"
ensure
client&.close
server.stop
container&.stop
end
end

describe Falcon::Service::Server do
include Sus::Fixtures::Async::SchedulerContext
Expand All @@ -33,6 +103,7 @@

server.with_listener(environment.evaluator) do |listener|
expect(listener).to be_a(Falcon::Listener)
expect(listener.endpoint).to be_a(Falcon::Listener::Endpoint)
expect(listener).to have_attributes(
name: be == "hello",
scheme: be == "http",
Expand Down Expand Up @@ -154,4 +225,41 @@ def server.run
end.wait
end.to raise_exception(IOError, message: be == "application failure")
end

with "a forked container", if: Process.respond_to?(:fork) do
let(:container_class) {Async::Container::Forked}
let(:container_options) {{restart: false, count: 2}}

it_behaves_like AStoppingServer
end

it "doesn't shut down the listener when its workers are threads" do
container = Class.new(Async::Container::Threaded) do
def run(...)
self
end
end.new

server.start
address, shared = server.with_listener(environment.evaluator) do |listener|
# These duplicates keep the sockets open, so they go on listening unless they are shut down:
[listener.addresses.first, listener.endpoint.bind]
end
server.setup(container)

server.stop

expect do
Socket.tcp(address.ip_address, address.ip_port).close
end.not.to raise_exception
ensure
shared&.each(&:close)
end

with "a hybrid container", if: Process.respond_to?(:fork) do
let(:container_class) {Async::Container::Hybrid}
let(:container_options) {{restart: false, forks: 1, threads: 2}}

it_behaves_like AStoppingServer
end
end