From 18df0106803f3b47beca4363dce2a792a23263d5 Mon Sep 17 00:00:00 2001 From: Jake Frautschi Date: Thu, 19 Nov 2026 21:06:07 -0800 Subject: [PATCH] Refuse new connections as soon as a server stops. A forked or hybrid worker holds its own descriptor for the listening socket, so closing the parent's copy in `Service::Server#stop` left the socket listening until the last worker exited. Connections that arrived while the workers drained were queued by the kernel and then reset. When the workers are in other processes, `#stop` now shuts the socket down before closing it. For a TCP socket on Linux that applies to every process that shares it, so new connections are refused at once and requests in flight still finish. UNIX sockets, and other platforms, behave as before. So do threaded containers, where closing the only descriptor already stops the socket listening. A worker's accept loop sees the shutdown as `EINVAL`, so the bound endpoint now waits to be stopped instead of failing the task. Fixes #369. Co-Authored-By: Claude Fable 5.2 --- lib/falcon/listener.rb | 41 ++++++++++++ lib/falcon/service/server.rb | 9 ++- releases.md | 1 + test/falcon/listener.rb | 40 ++++++++++++ test/falcon/listener/endpoint.rb | 81 +++++++++++++++++++++++ test/falcon/service/server.rb | 108 +++++++++++++++++++++++++++++++ 6 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 test/falcon/listener/endpoint.rb diff --git a/lib/falcon/listener.rb b/lib/falcon/listener.rb index 12dfdc8..f9c49ef 100644 --- a/lib/falcon/listener.rb +++ b/lib/falcon/listener.rb @@ -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. @@ -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 diff --git a/lib/falcon/service/server.rb b/lib/falcon/service/server.rb index f9179c5..4d14f67 100644 --- a/lib/falcon/service/server.rb +++ b/lib/falcon/service/server.rb @@ -20,6 +20,7 @@ def initialize(...) super @listener = nil + @multiprocess = false end # Build a listener from a configured and bound endpoint. @@ -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 @@ -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] @@ -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 diff --git a/releases.md b/releases.md index 781b430..fc74397 100644 --- a/releases.md +++ b/releases.md @@ -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 diff --git a/test/falcon/listener.rb b/test/falcon/listener.rb index 13bfdf5..af06230 100644 --- a/test/falcon/listener.rb +++ b/test/falcon/listener.rb @@ -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"]) @@ -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 diff --git a/test/falcon/listener/endpoint.rb b/test/falcon/listener/endpoint.rb new file mode 100644 index 0000000..951d669 --- /dev/null +++ b/test/falcon/listener/endpoint.rb @@ -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 diff --git a/test/falcon/service/server.rb b/test/falcon/service/server.rb index 18d72f2..e6d7948 100644 --- a/test/falcon/service/server.rb +++ b/test/falcon/service/server.rb @@ -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 @@ -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", @@ -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