fantail 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1f870f878fe0737149ef9b28549ceeba613a51fc39c70a243a84667713b73d4
-  data.tar.gz: 114fd5d72a6f53af337967440fdabd26c8f726a0654edaf80835a2b96faa4666
+  metadata.gz: e47d5decebc437bc838df2937ec0947a28f1b0f37f84035a744880ef95cbc77c
+  data.tar.gz: 860980fe620dc80a4c48635aa6f39e8e328b44509a093222db417f982bc735bf
 SHA512:
-  metadata.gz: 734e0a70510bfdd3ee9e9bf602d0ecb557f8202cde970c7b4aeb4e4900f23ff7fc6bc8f2a3c8a675b1366bb3d99ad6772618b6043ca737edf50ef37e7482e3e4
-  data.tar.gz: 9e5cff59c2dd10739f677a102c12ef83cb3e007b175be6158e239e59abdf7ffe0b3460258149862564ebf6c09575467aaa92b2168581cdcba2cdf28bc77ba942
+  metadata.gz: e881c4c6ad57a8a455e1e71ae894528f5401eaefae8594f74230d8d97c068fbc5dee0b05fa873d661d02f59d90435535b33d6abb0171ab482aa54f7fb12de7ca
+  data.tar.gz: 1d26ab270de4ca7b585dec05d44e7b09f300865392a4c981038062cc43735d2b5f0db1e10e20ec29d511fd57f9da8c27ba55f124a8234d4c8876018aa0150779

data/lib/fantail/backend.rb

@@ -10,20 +10,23 @@ module Fantail
 		# @parameter endpoint [Endpoint] The endpoint served by this backend.
 		# @parameter client [Interface(:call, :close)] The HTTP client for the endpoint.
 		# @parameter exchange_limit [Integer] The maximum number of outstanding response exchanges.
+		# @parameter permit_limit [Integer] The maximum number of concurrent processing permits.
 		# @yields {|backend| ...} Invoked when the backend can accept another request.
-		def initialize(endpoint, client, exchange_limit:, &available)
+		def initialize(endpoint, client, exchange_limit:, permit_limit: 1, &available)
 			raise ArgumentError, "Exchange limit must be positive!" unless exchange_limit.positive?
+			raise ArgumentError, "Permit limit must be positive!" unless permit_limit.positive?
 			
 			@endpoint = endpoint
 			@client = client
 			@exchange_limit = exchange_limit
+			@permit_limit = permit_limit
 			@available = available
 			
 			@guard = Thread::Mutex.new
 			@active = true
-			@processing = false
+			@processing = 0
+			@processing_by_queue = Hash.new(0)
 			@exchanges = 0
-			@queued = false
 			@closed = false
 		end
 		
@@ -45,12 +48,11 @@ module Fantail
 		
 		# Reserve the processing slot and one response exchange.
 		# @returns [Boolean] Whether the backend was successfully reserved.
-		def reserve
+		def reserve(queue_name = :default)
 			@guard.synchronize do
-				@queued = false
-				
-				if @active && !@processing && @exchanges < @exchange_limit
-					@processing = true
+				if @active && @processing < @permit_limit && @exchanges < @exchange_limit
+					@processing += 1
+					@processing_by_queue[queue_name] += 1
 					@exchanges += 1
 					return true
 				end
@@ -67,20 +69,18 @@ module Fantail
 		end
 		
 		# Release the request-processing slot after response headers arrive.
-		def processed
+		def processed(queue_name = :default)
 			@guard.synchronize do
-				raise RuntimeError, "Backend is not processing a request!" unless @processing
-				@processing = false
+				release_processing(queue_name)
 			end
 			
 			notify_available
 		end
 		
 		# Release both reservations when a request fails before response headers.
-		def failed
+		def failed(queue_name = :default)
 			close = @guard.synchronize do
-				raise RuntimeError, "Backend is not processing a request!" unless @processing
-				@processing = false
+				release_processing(queue_name)
 				@exchanges -= 1
 				should_close?
 			end
@@ -123,26 +123,40 @@ module Fantail
 		
 		# @returns [Boolean] Whether a request is waiting for response headers.
 		def processing?
+			@guard.synchronize{@processing.positive?}
+		end
+		
+		# @returns [Integer] The number of active processing permits.
+		def processing
 			@guard.synchronize{@processing}
 		end
 		
+		# @returns [Integer] The number of active permits for the given queue affinity.
+		def processing_for(queue_name)
+			@guard.synchronize{@processing_by_queue[queue_name]}
+		end
+		
+		# @returns [Boolean] Whether another request can be admitted.
+		def available?
+			@guard.synchronize{@active && @processing < @permit_limit && @exchanges < @exchange_limit}
+		end
+		
 		protected
 		
 		def notify_available
-			notify = @guard.synchronize do
-				if @active && !@processing && @exchanges < @exchange_limit && !@queued
-					@queued = true
-					true
-				else
-					false
-				end
-			end
-			
-			@available.call(self) if notify
+			@available.call(self) if available?
 		end
 		
 		def should_close?
-			!@active && !@processing && @exchanges.zero? && !@closed
+			!@active && @processing.zero? && @exchanges.zero? && !@closed
+		end
+		
+		def release_processing(queue_name)
+			raise RuntimeError, "Backend is not processing a request!" unless @processing.positive?
+			raise RuntimeError, "Backend is not processing queue #{queue_name.inspect}!" unless @processing_by_queue[queue_name].positive?
+			
+			@processing -= 1
+			@processing_by_queue[queue_name] -= 1
 		end
 		
 		def close_client

data/lib/fantail/balance.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Fantail
+	# Built-in backend selection policies.
+	module Balance
+		# Prefer the backend with the fewest active requests.
+		class Spread
+			# Select the least-active backend, using its name for deterministic ties.
+			# @parameter backends [Array(Backend)] Eligible backends with available permits.
+			# @parameter queue [Queue] The request queue being scheduled.
+			# @parameter request [Protocol::HTTP::Request] The pending request.
+			# @returns [Backend | Nil] The preferred backend.
+			def select(backends, queue:, request:)
+				backends.min_by{|backend| [backend.processing, backend.name]}
+			end
+		end
+		
+		# Prefer a backend which is already processing the same class of work.
+		class Pack
+			# @parameter affinity [Symbol | Nil] The queue affinity to pack, or the current queue by default.
+			def initialize(affinity: nil)
+				@affinity = affinity
+			end
+			
+			# Select the backend with the most active work for the affinity.
+			# @parameter backends [Array(Backend)] Eligible backends with available permits.
+			# @parameter queue [Queue] The request queue being scheduled.
+			# @parameter request [Protocol::HTTP::Request] The pending request.
+			# @returns [Backend | Nil] The preferred backend.
+			def select(backends, queue:, request:)
+				affinity = @affinity || queue.name
+				backends.min_by do |backend|
+					[-backend.processing_for(affinity), backend.processing, backend.name]
+				end
+			end
+		end
+		
+		# Resolve a built-in policy name or validate an application policy object.
+		# @parameter policy [Symbol | #select] The policy name or object.
+		# @parameter options [Hash] Options for a built-in policy.
+		# @returns [#select] The resolved balance policy.
+		def self.coerce(policy, **options)
+			case policy
+			when :spread
+				Spread.new(**options)
+			when :pack
+				Pack.new(**options)
+			else
+				unless policy.respond_to?(:select)
+					raise ArgumentError, "Balance policy must respond to #select!"
+				end
+				
+				policy
+			end
+		end
+	end
+end

data/lib/fantail/configuration.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "queue"
+
+module Fantail
+	# Immutable request queue and admission configuration.
+	class Configuration
+		# Builds configurations using the application DSL.
+		class Builder
+			# @parameter root [String] The root for relative configuration files.
+			def initialize(root = Dir.pwd)
+				@root = File.expand_path(root)
+				@queues = {}
+				@default_queue_name = nil
+				@pending_limit = nil
+				@permit_limit = 1
+			end
+			
+			# @attribute [String] The root for relative configuration files.
+			attr :root
+			
+			# Evaluate a trusted configuration file using this builder.
+			# @parameter path [String] The relative or absolute configuration path.
+			def load_file(path)
+				realpath = File.realpath(File.expand_path(path, @root))
+				root = @root
+				@root = File.dirname(realpath)
+				instance_eval(File.read(realpath), realpath)
+			ensure
+				@root = root if root
+			end
+			
+			# Define a named request queue. Matchers are evaluated in definition order.
+			# @parameter name [Symbol | String] The stable queue name.
+			# @yields {|queue| ...} The queue builder, or evaluates the block as its DSL.
+			# @returns [Queue] The configured queue.
+			def queue(name, &block)
+				name = name.to_sym
+				raise ArgumentError, "Queue #{name.inspect} is already defined!" if @queues.key?(name)
+				
+				builder = Queue::Builder.new(name)
+				if block
+					if block.arity.zero?
+						builder.instance_eval(&block)
+					else
+						block.call(builder)
+					end
+				end
+				
+				@queues[name] = builder.build
+			end
+			
+			# Select the fallback queue for unmatched requests.
+			# @parameter name [Symbol | String] A defined queue name.
+			def default_queue(name)
+				@default_queue_name = name.to_sym
+			end
+			
+			# Set the global pending request limit.
+			# @parameter value [Integer] The maximum number of pending requests.
+			def pending_limit(value)
+				value = Integer(value)
+				raise ArgumentError, "Pending limit must not be negative!" if value.negative?
+				@pending_limit = value
+			end
+			
+			# Set the number of processing permits provided by each worker.
+			# @parameter value [Integer] The number of permits per worker.
+			def permit_limit(value)
+				value = Integer(value)
+				raise ArgumentError, "Permit limit must be positive!" unless value.positive?
+				@permit_limit = value
+			end
+			
+			# Validate and build the immutable configuration.
+			# @returns [Configuration] The configured request queues.
+			def build
+				raise ArgumentError, "At least one queue must be defined!" if @queues.empty?
+				default_queue_name = @default_queue_name || @queues.keys.first
+				raise ArgumentError, "Default queue #{default_queue_name.inspect} is not defined!" unless @queues.key?(default_queue_name)
+				
+				Configuration.new(
+					queues: @queues.dup.freeze,
+					default_queue_name: default_queue_name,
+					pending_limit: @pending_limit,
+					permit_limit: @permit_limit,
+				).freeze
+			end
+		end
+		
+		# Build a configuration using a scoped builder.
+		# @parameter root [String] The root for relative configuration files.
+		# @yields {|builder| ...} The configuration builder.
+		# @returns [Configuration] The immutable configuration.
+		def self.build(root: Dir.pwd, &block)
+			builder = Builder.new(root)
+			
+			if block
+				if block.arity.zero?
+					builder.instance_eval(&block)
+				else
+					block.call(builder)
+				end
+			end
+			
+			builder.build
+		end
+		
+		# @returns [Configuration] A single-queue, single-permit configuration.
+		def self.default
+			@default ||= build do
+				queue(:default)
+				default_queue(:default)
+			end
+		end
+		
+		# Load and build trusted application configuration files.
+		# @parameter paths [String | Array(String)] The configuration files to load.
+		# @returns [Configuration] The immutable configuration.
+		def self.load(paths)
+			builder = Builder.new
+			Array(paths).each{|path| builder.load_file(path)}
+			builder.build
+		end
+		
+		# @parameter queues [Hash(Symbol, Queue)] The configured queues.
+		# @parameter default_queue_name [Symbol] The fallback queue name.
+		# @parameter pending_limit [Integer | Nil] The global pending request limit.
+		# @parameter permit_limit [Integer] The processing permits per worker.
+		def initialize(queues:, default_queue_name:, pending_limit:, permit_limit:)
+			@queues = queues
+			@default_queue_name = default_queue_name
+			@pending_limit = pending_limit
+			@permit_limit = permit_limit
+		end
+		
+		attr :queues
+		attr :default_queue_name
+		attr :pending_limit
+		attr :permit_limit
+		
+		# Classify a request using matchers in definition order.
+		# @returns [Queue] The matching or default queue.
+		def classify(request)
+			@queues.each_value do |queue|
+				return queue if queue.match?(request)
+			end
+			
+			@queues.fetch(@default_queue_name)
+		end
+	end
+end

data/lib/fantail/proxy.rb

@@ -7,34 +7,41 @@ require "protocol/http/request"
 require "protocol/http/response"
 
 require_relative "response_body"
+require_relative "scheduler"
 
 module Fantail
-	# Routes HTTP requests through the registry's global admission queue.
+	# Routes HTTP requests through the configured admission queues.
 	class Proxy
 		# Initialize an HTTP proxy.
 		# @parameter registry [Registry] The backend registry.
-		def initialize(registry)
-			@registry = registry
+		# @parameter configuration [Configuration] Request classification and scheduling policy.
+		def initialize(registry, configuration: Configuration.default)
+			@scheduler = Scheduler.new(registry, configuration)
 		end
 		
+		attr :scheduler
+		
 		# Route a request to the next available backend.
 		# @parameter request [Protocol::HTTP::Request] The downstream request.
 		# @returns [Protocol::HTTP::Response] The upstream or generated response.
 		def call(request)
-			unless backend = @registry.acquire
+			unless backend_reservation = @scheduler.acquire(request)
 				return Protocol::HTTP::Response[503, {"content-type" => "text/plain"}, ["No backends available.\n"]]
 			end
 			
+			return backend_reservation.response if backend_reservation.is_a?(Scheduler::Rejection)
+			
 			reservation = :processing
+			backend = backend_reservation.backend
 			upstream_request = build_request(request)
 			response = backend.call(upstream_request)
-			backend.processed
+			backend_reservation.processed
 			reservation = :exchange
 			
 			if body = response.body
-				response.body = ResponseBody.new(body){backend.release}
+				response.body = ResponseBody.new(body){backend_reservation.release}
 			else
-				backend.release
+				backend_reservation.release
 			end
 			reservation = nil
 			
@@ -42,9 +49,9 @@ module Fantail
 		rescue => error
 			case reservation
 			when :processing
-				backend.failed
+				backend_reservation.failed
 			when :exchange
-				backend.release
+				backend_reservation.release
 			end
 			
 			return Protocol::HTTP::Response[502, {"content-type" => "text/plain"}, ["Bad Gateway: #{error.class}\n"]]

data/lib/fantail/queue.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "balance"
+
+module Fantail
+	# Immutable policy for one class of requests.
+	class Queue
+		# Builds a queue policy using the configuration DSL.
+		class Builder
+			# @parameter name [Symbol | String] The stable queue name.
+			def initialize(name)
+				@name = name
+				@matcher = nil
+				@eligibility = nil
+				@admission = nil
+				@balance_policy = Balance::Spread.new
+				@depth_limit = nil
+				@wait_limit = nil
+				@shed_status = 429
+				@shed_headers = {}
+			end
+			
+			# Set the request classifier for this queue.
+			# @yields {|request| ...} Whether a request belongs to this queue.
+			def match(&block)
+				raise ArgumentError, "A matcher block is required!" unless block
+				@matcher = block
+			end
+			
+			# Restrict the backends which may serve this queue.
+			# @yields {|backend, request| ...} Whether the backend is eligible.
+			def eligible(&block)
+				raise ArgumentError, "An eligibility block is required!" unless block
+				@eligibility = block
+			end
+			
+			# Set an application admission policy.
+			# @parameter policy [#admit? | #call | Nil] The admission policy object.
+			# @yields {|request, queue:, pending:| ...} Whether the request can wait.
+			def admit(policy = nil, &block)
+				@admission = policy || block
+				raise ArgumentError, "An admission policy is required!" unless @admission
+			end
+			
+			# Set the soft backend balance policy.
+			# @parameter policy [Symbol | #select] A built-in name or application policy.
+			# @parameter options [Hash] Options for a built-in policy.
+			def balance(policy, **options)
+				@balance_policy = Balance.coerce(policy, **options)
+			end
+			
+			# Set the maximum number of requests waiting in this queue.
+			# @parameter value [Integer] The maximum queue depth.
+			def depth_limit(value)
+				value = Integer(value)
+				raise ArgumentError, "Depth limit must not be negative!" if value.negative?
+				@depth_limit = value
+			end
+			
+			# Set the maximum time a request may wait for a permit.
+			# @parameter value [Numeric] The maximum wait in seconds.
+			def wait_limit(value)
+				value = Float(value)
+				raise ArgumentError, "Wait limit must be positive!" unless value.positive?
+				@wait_limit = value
+			end
+			
+			# Configure the response used when admission is rejected.
+			# @parameter status [Integer] The HTTP response status.
+			# @parameter retry_after [Numeric | String | Nil] An optional Retry-After value.
+			# @parameter headers [Hash] Additional response headers.
+			def shed(status: 429, retry_after: nil, headers: {})
+				@shed_status = Integer(status)
+				@shed_headers = headers.transform_keys(&:to_s)
+				@shed_headers["retry-after"] = retry_after.to_s if retry_after
+			end
+			
+			# Build the immutable queue policy.
+			# @returns [Queue] The configured queue.
+			def build
+				Queue.new(
+					@name,
+					matcher: @matcher,
+					eligibility: @eligibility,
+					admission: @admission,
+					balance_policy: @balance_policy,
+					depth_limit: @depth_limit,
+					wait_limit: @wait_limit,
+					shed_status: @shed_status,
+					shed_headers: @shed_headers.dup.freeze,
+				).freeze
+			end
+		end
+		
+		# @parameter name [Symbol | String] The stable queue name.
+		# @parameter matcher [Proc | Nil] The request classifier.
+		# @parameter eligibility [Proc | Nil] The backend eligibility policy.
+		# @parameter admission [#admit? | #call | Nil] The queue admission policy.
+		# @parameter balance_policy [#select] The backend balance policy.
+		# @parameter depth_limit [Integer | Nil] The maximum queue depth.
+		# @parameter wait_limit [Float | Nil] The maximum queue wait.
+		# @parameter shed_status [Integer] The rejection response status.
+		# @parameter shed_headers [Hash] The rejection response headers.
+		def initialize(name, matcher:, eligibility:, admission:, balance_policy:, depth_limit:, wait_limit:, shed_status:, shed_headers:)
+			@name = name.to_sym
+			@matcher = matcher
+			@eligibility = eligibility
+			@admission = admission
+			@balance_policy = balance_policy
+			@depth_limit = depth_limit
+			@wait_limit = wait_limit
+			@shed_status = shed_status
+			@shed_headers = shed_headers
+		end
+		
+		attr :name
+		attr :balance_policy
+		attr :depth_limit
+		attr :wait_limit
+		attr :shed_status
+		attr :shed_headers
+		
+		# @parameter request [Protocol::HTTP::Request] The request to classify.
+		# @returns [Boolean | Nil] Whether the request matches this queue.
+		def match?(request)
+			@matcher&.call(request)
+		end
+		
+		# @returns [Boolean] Whether a backend may serve the request.
+		def eligible?(backend, request)
+			!@eligibility || @eligibility.call(backend, request)
+		end
+		
+		# @returns [Boolean] Whether a request may enter the pending queue.
+		def admit?(request, pending:)
+			return true unless @admission
+			
+			if @admission.respond_to?(:admit?)
+				@admission.admit?(request, queue: self, pending: pending)
+			else
+				@admission.call(request, queue: self, pending: pending)
+			end
+		end
+	end
+end

data/lib/fantail/registry.rb

@@ -4,26 +4,25 @@
 # Copyright, 2026, by Samuel Williams.
 
 require "async/bus/controller"
-require "async/queue"
 
 require_relative "endpoint"
 require_relative "backend"
 
 module Fantail
-	# Maintains live backends and a global queue of available processing slots.
+	# Maintains live backends and notifies the scheduler when capacity changes.
 	class Registry < Async::Bus::Controller
-		WAKE = Object.new.freeze
-		
 		# Initialize an endpoint registry.
 		# @parameter exchange_limit [Integer] The maximum outstanding responses per backend.
-		# @parameter backend_factory [Proc | Nil] An optional backend construction strategy.
-		def initialize(exchange_limit: 8, backend_factory: nil)
+		# @parameter permit_limit [Integer] The maximum active processing permits per backend.
+		# @parameter backend_factory [#call(endpoint, exchange_limit, permit_limit, available) | Nil] An optional backend construction strategy.
+		def initialize(exchange_limit: 8, permit_limit: 1, backend_factory: nil)
 			@exchange_limit = exchange_limit
+			@permit_limit = permit_limit
 			@backend_factory = backend_factory || self.method(:make_backend)
 			
 			@guard = Thread::Mutex.new
 			@backends = {}
-			@available = Async::Queue.new
+			@available = nil
 			@closed = false
 		end
 		
@@ -62,7 +61,7 @@ module Fantail
 					next if current&.endpoint == endpoint
 					
 					retired << current if current
-					backend = @backend_factory.call(endpoint, @exchange_limit, self.method(:offer))
+					backend = @backend_factory.call(endpoint, @exchange_limit, @permit_limit, self.method(:offer))
 					@backends[endpoint.name] = backend
 					started << backend
 				end
@@ -70,23 +69,19 @@ module Fantail
 			
 			retired.each(&:retire)
 			started.each(&:start)
-			@available.enqueue(WAKE) unless retired.empty?
+			notify_available unless retired.empty?
 			
 			self.size
 		end
 		
-		# Acquire the next backend with processing capacity.
-		# @returns [Backend | Nil] An admitted backend, or nil if no endpoints exist.
-		def acquire
-			loop do
-				return nil if self.empty?
-				
-				candidate = @available.dequeue
-				return nil unless candidate
-				next if candidate.equal?(WAKE)
-				
-				return candidate if candidate.reserve
-			end
+		# @returns [Array(Backend)] A snapshot of active backends.
+		def backends
+			@guard.synchronize{@backends.values.dup}
+		end
+		
+		# Register the central scheduler capacity callback.
+		def on_available(&block)
+			@guard.synchronize{@available = block}
 		end
 		
 		# @returns [Integer] The number of active endpoints.
@@ -120,21 +115,23 @@ module Fantail
 				@backends.values.tap{@backends = {}}
 			end
 			
-			@available.close
 			backends.each(&:retire)
 		end
 		
 		protected
 		
-		def offer(backend)
-			@available.enqueue(backend)
-		rescue Async::Queue::ClosedError
-			# The registry is already shutting down:
+		def offer(_backend)
+			notify_available
+		end
+		
+		def notify_available
+			available = @guard.synchronize{@available}
+			available&.call
 		end
 		
-		def make_backend(endpoint, exchange_limit, available)
+		def make_backend(endpoint, exchange_limit, permit_limit, available)
 			client = endpoint.make_client(exchange_limit: exchange_limit)
-			Backend.new(endpoint, client, exchange_limit: exchange_limit, &available)
+			Backend.new(endpoint, client, exchange_limit: exchange_limit, permit_limit: permit_limit, &available)
 		end
 	end
 end

data/lib/fantail/scheduler.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/queue"
+require "protocol/http/response"
+
+require_relative "configuration"
+
+module Fantail
+	# Matches pending requests to concrete backend permits.
+	class Scheduler
+		# A reserved processing permit and response exchange.
+		class Reservation
+			# @parameter backend [Backend] The reserved backend.
+			# @parameter queue_name [Symbol] The queue consuming the permit.
+			def initialize(backend, queue_name)
+				@backend = backend
+				@queue_name = queue_name
+			end
+			
+			attr :backend
+			
+			# Release the processing permit after response headers arrive.
+			def processed
+				@backend.processed(@queue_name)
+			end
+			
+			# Release the processing permit and exchange after an upstream failure.
+			def failed
+				@backend.failed(@queue_name)
+			end
+			
+			# Release the response exchange after its body closes.
+			def release
+				@backend.release
+			end
+		end
+		
+		# A queue admission rejection.
+		class Rejection
+			# @parameter queue [Queue] The queue which rejected admission.
+			def initialize(queue)
+				@queue = queue
+			end
+			
+			# @returns [Protocol::HTTP::Response] The configured shedding response.
+			def response
+				headers = {"content-type" => "text/plain"}.merge(@queue.shed_headers)
+				Protocol::HTTP::Response[@queue.shed_status, headers, ["Request queue is full.\n"]]
+			end
+		end
+		
+		Entry = Struct.new(:request, :queue, :enqueued_at, :result, :pending, :assignment)
+		
+		# @parameter registry [Registry] The available backend registry.
+		# @parameter configuration [Configuration] Request and scheduling policy.
+		def initialize(registry, configuration = Configuration.default)
+			@registry = registry
+			@configuration = configuration
+			@guard = Thread::Mutex.new
+			@pending = configuration.queues.to_h{|name, queue| [name, []]}
+			@pending_count = 0
+			@closed = false
+			
+			@registry.on_available{schedule}
+		end
+		
+		# Admit a request, wait for a matching permit, or return a rejection.
+		def acquire(request)
+			queue = @configuration.classify(request)
+			entry = nil
+			result = @guard.synchronize do
+				if @closed
+					nil
+				elsif reservation = reserve(queue, request)
+					reservation
+				elsif @registry.empty?
+					nil
+				elsif reject?(queue, request)
+					Rejection.new(queue)
+				else
+					entry = Entry.new(request, queue, now, Async::Queue.new, true, nil)
+					@pending.fetch(queue.name) << entry
+					@pending_count += 1
+					schedule_locked
+					entry.assignment
+				end
+			end
+			
+			return result unless entry
+			
+			if assignment = entry.assignment
+				entry = nil
+				return assignment
+			end
+			
+			if wait_limit = queue.wait_limit
+				remaining = wait_limit - (now - entry.enqueued_at)
+				result = entry.result.dequeue(timeout: remaining) if remaining.positive?
+				if result
+					entry = nil
+					return result
+				end
+				
+				result = cancel(entry)
+				entry = nil
+				return result
+			else
+				result = entry.result.dequeue
+				entry = nil
+				return result
+			end
+		ensure
+			if entry && assignment = cancel(entry, rejection: false)
+				# The request was assigned concurrently but its waiting task was
+				# interrupted before receiving the reservation. No upstream request
+				# was started, so release both the permit and response exchange.
+				assignment.failed
+			end
+		end
+		
+		# Try to dispatch pending requests after capacity changes.
+		def schedule
+			@guard.synchronize{schedule_locked unless @closed}
+		end
+		
+		# Stop accepting requests and wake all tasks waiting for a permit.
+		def close
+			entries = @guard.synchronize do
+				return if @closed
+				
+				@closed = true
+				entries = @pending.values.flatten(1)
+				@pending.each_value(&:clear)
+				@pending_count = 0
+				entries.each{|entry| entry.pending = false}
+				entries
+			end
+			
+			entries.each{|entry| entry.result.close}
+		end
+		
+		# @parameter queue_name [Symbol | String | Nil] An optional queue to inspect.
+		# @returns [Integer] The number of requests waiting for a permit.
+		def pending_count(queue_name = nil)
+			@guard.synchronize do
+				if queue_name
+					@pending.fetch(queue_name.to_sym).size
+				else
+					@pending_count
+				end
+			end
+		end
+		
+		protected
+		
+		def now
+			Process.clock_gettime(Process::CLOCK_MONOTONIC)
+		end
+		
+		def reject?(queue, request)
+			return true if @configuration.pending_limit && @pending_count >= @configuration.pending_limit
+			pending = @pending.fetch(queue.name).size
+			return true if queue.depth_limit && pending >= queue.depth_limit
+			return true unless queue.admit?(request, pending: pending)
+			
+			false
+		end
+		
+		def cancel(entry, rejection: true)
+			@guard.synchronize do
+				return entry.assignment unless entry.pending
+				
+				@pending.fetch(entry.queue.name).delete(entry)
+				entry.pending = false
+				@pending_count -= 1
+				Rejection.new(entry.queue) if rejection
+			end
+		end
+		
+		def schedule_locked
+			loop do
+				entries = @pending.each_value.filter_map(&:first).sort_by(&:enqueued_at)
+				matched = false
+				
+				entries.each do |entry|
+					if reservation = reserve(entry.queue, entry.request)
+						@pending.fetch(entry.queue.name).shift
+						@pending_count -= 1
+						entry.pending = false
+						entry.assignment = reservation
+						entry.result.enqueue(reservation)
+						matched = true
+						break
+					end
+				end
+				
+				break unless matched
+			end
+		end
+		
+		def reserve(queue, request)
+			backends = @registry.backends.select do |backend|
+				backend.available? && queue.eligible?(backend, request)
+			end
+			
+			until backends.empty?
+				backend = queue.balance_policy.select(backends, queue: queue, request: request)
+				return nil unless backend
+				raise ArgumentError, "Balance policy selected an ineligible backend!" unless backends.include?(backend)
+				
+				return Reservation.new(backend, queue.name) if backend.reserve(queue.name)
+				backends.delete(backend)
+			end
+			
+			nil
+		end
+	end
+end

data/lib/fantail/server.rb

@@ -8,6 +8,7 @@ require "async/http/server"
 require_relative "registry"
 require_relative "proxy"
 require_relative "control"
+require_relative "configuration"
 
 module Fantail
 	# Runs the HTTP load balancer and endpoint-control server together.
@@ -16,9 +17,10 @@ module Fantail
 		# @parameter endpoint [Async::HTTP::Endpoint] The downstream HTTP endpoint.
 		# @parameter control_endpoint [IO::Endpoint] The async-bus control endpoint.
 		# @parameter exchange_limit [Integer] The maximum outstanding responses per backend.
-		def initialize(endpoint, control_endpoint, exchange_limit: 8)
-			@registry = Registry.new(exchange_limit: exchange_limit)
-			@proxy = Proxy.new(@registry)
+		# @parameter configuration [Configuration] Request classification and scheduling policy.
+		def initialize(endpoint, control_endpoint, exchange_limit: 8, configuration: Configuration.default)
+			@registry = Registry.new(exchange_limit: exchange_limit, permit_limit: configuration.permit_limit)
+			@proxy = Proxy.new(@registry, configuration: configuration)
 			@http_server = Async::HTTP::Server.new(@proxy, endpoint)
 			@control_server = Control.new(control_endpoint, @registry)
 		end
@@ -26,6 +28,11 @@ module Fantail
 		# @attribute [Registry] The server's endpoint registry.
 		attr :registry
 		
+		# @attribute [Scheduler] The central request scheduler.
+		def scheduler
+			@proxy.scheduler
+		end
+		
 		# Run the HTTP and control servers.
 		# @parameter parent [Interface(:async)] The parent task.
 		# @returns [Async::Task] The server task.
@@ -39,8 +46,9 @@ module Fantail
 			end
 		end
 		
-		# Close the endpoint registry.
+		# Stop pending requests and close the endpoint registry.
 		def close
+			@proxy.scheduler.close
 			@registry.close
 		end
 	end

data/lib/fantail/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2026, by Samuel Williams.
 
 module Fantail
-	VERSION = "0.0.1"
+	VERSION = "0.1.0"
 end

data/lib/fantail.rb

@@ -4,10 +4,14 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "fantail/version"
+require_relative "fantail/balance"
+require_relative "fantail/queue"
+require_relative "fantail/configuration"
 require_relative "fantail/endpoint"
 require_relative "fantail/backend"
 require_relative "fantail/response_body"
 require_relative "fantail/registry"
+require_relative "fantail/scheduler"
 require_relative "fantail/proxy"
 require_relative "fantail/control"
 require_relative "fantail/monitor"

data/readme.md

@@ -4,7 +4,7 @@ Worker-aware HTTP load balancing with a global admission queue.
 
 [![Development Status](https://github.com/socketry/fantail/workflows/Test/badge.svg)](https://github.com/socketry/fantail/actions?workflow=Test)
 
-Fantail routes each request to a worker which is ready to process it. It separates the short-lived request-processing reservation from the potentially longer response exchange, so another request can begin after response headers arrive while the previous response body is still streaming.
+Fantail routes each request to a worker which is ready to process it. Configurable request queues can express worker affinity and load-shedding policy while a central scheduler remains responsible for matching requests to worker permits. Fantail separates the short-lived request-processing reservation from the potentially longer response exchange, so another request can begin after response headers arrive while the previous response body is still streaming.
 
 ## Usage
 
@@ -16,6 +16,10 @@ Please see the [project documentation](https://socketry.github.io/fantail/) for
 
 Please see the [project releases](https://socketry.github.io/fantail/releases/index) for all releases.
 
+### v0.1.0
+
+  - Add configurable request queues, worker affinity policies, central permit scheduling, and load shedding.
+
 ### v0.0.1
 
   - Initial implementation.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.1.0
+
+  - Add configurable request queues, worker affinity policies, central permit scheduling, and load shedding.
+
 ## v0.0.1
 
   - Initial implementation.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fantail
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -72,12 +72,16 @@ extra_rdoc_files: []
 files:
 - lib/fantail.rb
 - lib/fantail/backend.rb
+- lib/fantail/balance.rb
+- lib/fantail/configuration.rb
 - lib/fantail/control.rb
 - lib/fantail/endpoint.rb
 - lib/fantail/monitor.rb
 - lib/fantail/proxy.rb
+- lib/fantail/queue.rb
 - lib/fantail/registry.rb
 - lib/fantail/response_body.rb
+- lib/fantail/scheduler.rb
 - lib/fantail/server.rb
 - lib/fantail/version.rb
 - license.md