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