falcon-limiter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f3dddcc61c0937bb6126b7a27298982a6159438479753b717fff59491ab9048
+  data.tar.gz: 6430a166f1ffb09e7dbdc6b0e4897abdcfc82c4b299af550aebe3a0ace1deba5
+SHA512:
+  metadata.gz: 4313993a4aa621ed7be5449759e8e874224c1d7ad88f1708e54f8fc2b070064b8ec43cce7b43775d98295c90eb46bd273592bd592331d20cb0d3f7990cef0a4a
+  data.tar.gz: a4b12e91879182a082573553293615843d07f08c8aa67d4f9a2aa13af1121dda6b13cff654887e7da585d21eb10f1d7a6c06d009818e03fbcb2f6a363b9b6a87

data/examples/basic_limiting.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "../lib/falcon/limiter"
+
+# Create a semaphore with a limit of 3 concurrent resources
+semaphore = Falcon::Limiter::Semaphore.new(3)
+
+puts "Available resources: #{semaphore.available_count}"
+puts "Acquired resources: #{semaphore.acquired_count}"
+
+# Simulate acquiring and releasing resources
+tasks = []
+
+10.times do |i|
+	tasks << Thread.new do
+		puts "Task #{i}: Waiting for resource..."
+		
+		# Acquire a resource token
+		token = semaphore.acquire
+		
+		puts "Task #{i}: Acquired resource (#{semaphore.available_count} remaining)"
+		
+		# Simulate work
+		sleep(rand * 2)
+		
+		# Release the resource
+		token.release
+		
+		puts "Task #{i}: Released resource (#{semaphore.available_count} available)"
+	end
+end
+
+# Wait for all tasks to complete
+tasks.each(&:join)
+
+puts "Final state - Available: #{semaphore.available_count}, Acquired: #{semaphore.acquired_count}"

data/examples/environment_usage.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "../lib/falcon/limiter"
+
+# Example service module that includes the limiter environment
+module MyService
+	include Falcon::Limiter::Environment
+	
+	# Customize limiter configuration by overriding methods
+	def limiter_maximum_long_tasks
+		8  # Override default of 4
+	end
+	
+	def limiter_maximum_accepts
+		3  # Override default of 1
+	end
+	
+	def limiter_start_delay
+		0.8 # Override default of 0.1
+	end
+	
+	# Mock middleware method
+	def middleware
+		proc {|_env| [200, {}, ["Base middleware"]]}
+	end
+	
+	# Mock endpoint method
+	def endpoint
+		Object.new.tap do |endpoint|
+			endpoint.define_singleton_method(:to_s) {"MockEndpoint"}
+		end
+	end
+end
+
+# Demonstrate the environment with proper async-service pattern
+require "async/service"
+environment = Async::Service::Environment.build(MyService)
+service = environment.evaluator
+
+puts "=== Falcon Limiter Environment Demo ==="
+puts
+puts "Configuration:"
+options = service.limiter_semaphore_options
+puts "  Max Long Tasks: #{options[:maximum_long_tasks]}"
+puts "  Max Accepts: #{options[:maximum_accepts]}"
+puts "  Start Delay: #{options[:start_delay]}s"
+puts
+
+puts "Semaphore:"
+semaphore = service.limiter_semaphore
+puts "  Limiter Semaphore: #{semaphore.available_count}/#{semaphore.limit} available"
+puts "  Limited: #{semaphore.limited?}"
+puts "  Waiting: #{semaphore.waiting_count}"
+puts
+
+puts "Middleware Integration:"
+base_middleware = service.middleware
+wrapped_middleware = service.limiter_middleware(base_middleware)
+puts "  Base middleware: #{base_middleware.class}"
+puts "  Wrapped middleware: #{wrapped_middleware.class}"
+puts
+
+puts "Endpoint Integration:"
+endpoint = service.endpoint
+puts "  Final Endpoint: #{endpoint.class}"
+
+# Check if it's actually wrapped (only if it's a Wrapper)
+if endpoint.respond_to?(:semaphore)
+	puts "  Semaphore: #{endpoint.semaphore.class}"
+	puts "  Same semaphore instance: #{endpoint.semaphore == service.limiter_semaphore}"
+else
+	puts "  Note: Endpoint is not wrapped (likely mock object)"
+end

data/examples/falcon_environment.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "../lib/falcon/limiter"
+
+service "limiter-example.localhost" do
+	include Falcon::Limiter::Environment
+	
+	# Configure concurrency limits by overriding methods
+	def limiter_max_long_tasks = 4
+	def limiter_max_accepts = 2
+	def limiter_start_delay = 0.5
+	
+	scheme "http"
+	url "http://localhost:9292"
+	
+	rack_app do
+		run lambda {|env|
+			request = env["protocol.http.request"]
+			
+			case env["PATH_INFO"]
+			when "/fast"
+				# Fast response - no need for long task
+				[200, { "Content-Type" => "text/plain" }, ["Fast response"]]
+				
+			when "/slow"
+				# Slow response - use long task management
+				Falcon::Limiter::LongTask.current&.start
+				
+				# Simulate I/O operation (database query, API call, etc.)
+				sleep(2)
+				
+				Falcon::Limiter::LongTask.current&.stop
+				
+				[200, { "Content-Type" => "text/plain" }, ["Slow response completed"]]
+				
+			when "/stats"
+				# Show limiter statistics
+				stats = if respond_to?(:statistics)
+					statistics
+				else
+					{ message: "Statistics not available" }
+				end
+				
+				[200, { "Content-Type" => "application/json" }, [stats.to_json]]
+				
+			else
+				[404, { "Content-Type" => "text/plain" }, ["Not found"]]
+			end
+		}
+	end
+end

data/examples/limiter/README.md

@@ -0,0 +1,95 @@
+# Falcon Limiter Examples
+
+This directory contains examples demonstrating the Falcon::Limiter functionality for managing concurrent workloads.
+
+## Overview
+
+The Falcon::Limiter system helps distinguish between I/O bound and CPU bound workloads:
+
+- **I/O bound work**: Long tasks that benefit from releasing connection tokens to improve concurrency
+- **CPU bound work**: Tasks that should keep connection tokens to prevent GVL contention
+
+## Examples
+
+### 1. Falcon Environment (`falcon.rb`)
+
+Uses `Falcon::Environment::Limiter` for turn-key setup:
+
+```bash
+falcon-host ./falcon.rb
+```
+
+**Endpoints:**
+- `/fast` - Quick response without long task
+- `/slow` - I/O bound task using long task management  
+- `/cpu` - CPU bound task without long task
+- `/stats` - Show limiter statistics
+
+### 2. Rack Application (`config.ru`)
+
+Basic Rack app with manual limiter middleware:
+
+```bash
+falcon serve -c config.ru
+```
+
+**Endpoints:**
+- `/long-io` - Long I/O operation with long task
+- `/short` - Short operation (long task delay avoids overhead)
+- `/token-info` - Shows connection token information
+- `/` - Simple hello response
+
+## Key Concepts
+
+### Long Task Management
+
+```ruby
+# For I/O bound operations
+request.long_task&.start
+external_api_call()  # Long I/O operation
+request.long_task&.stop  # Optional - auto cleanup on response end
+```
+
+### Connection Token Release
+
+Long tasks automatically:
+1. Extract and release connection tokens during I/O operations
+2. Acquire long task tokens from a separate semaphore
+3. Allow more connections to be accepted while I/O is pending
+4. Clean up automatically when response finishes
+
+### Configuration
+
+```ruby
+# Environment-based
+ENV["FALCON_LIMITER_MAX_LONG_TASKS"] = "8"
+ENV["FALCON_LIMITER_MAX_ACCEPTS"] = "2"
+
+# Or programmatic
+Falcon::Limiter.configure do |config|
+  config.max_long_tasks = 8
+  config.max_accepts = 2
+  config.start_delay = 0.6
+end
+```
+
+## Testing Load Scenarios
+
+Test with multiple concurrent requests:
+
+```bash
+# Test slow endpoint concurrency
+curl -s "http://localhost:9292/slow" &
+curl -s "http://localhost:9292/slow" &
+curl -s "http://localhost:9292/slow" &
+
+# Should still be responsive for fast requests
+curl -s "http://localhost:9292/fast"
+```
+
+## Benefits
+
+1. **Better Concurrency**: I/O operations don't block connection acceptance
+2. **Graceful Degradation**: System remains responsive under high load  
+3. **Resource Management**: Prevents GVL contention for CPU work
+4. **Automatic Cleanup**: Long tasks clean up automatically on response completion

data/examples/limiter/config.ru

@@ -0,0 +1,50 @@
+#!/usr/bin/env falcon --verbose serve -c
+# frozen_string_literal: true
+
+require "falcon/limiter"
+
+# Configure limiter globally
+Falcon::Limiter.configure do |config|
+	config.max_long_tasks = 4
+	config.max_accepts = 2
+	config.start_delay = 0.1
+end
+
+# Basic Rack app demonstrating limiter usage
+run lambda {|env|
+	request = env["protocol.http.request"]
+	path = env["PATH_INFO"]
+	
+	case path
+	when "/long-io"
+		# Start long task for I/O bound work
+		request.long_task&.start
+		
+		# Simulate database query or external API call
+		sleep(1.5)
+		
+		[200, { "content-type" => "text/plain" }, ["Long I/O operation completed at #{Time.now}"]]
+		
+	when "/short"
+		# Short operation - long task overhead avoided by delay
+		sleep(0.05)
+		[200, { "content-type" => "text/plain" }, ["Short operation at #{Time.now}"]]
+		
+	when "/token-info"
+		# Show connection token information
+		token_info = "No connection token"
+		
+		if request.respond_to?(:connection)
+			io = request.connection.stream.io
+			if io.respond_to?(:token)
+				token = io.token
+				token_info = "Token: #{token.inspect}, Released: #{token.released?}"
+			end
+		end
+		
+		[200, { "content-type" => "text/plain" }, [token_info]]
+		
+	else
+		[200, { "content-type" => "text/plain" }, ["Hello from Falcon Limiter!"]]
+	end
+}

data/examples/limiter/falcon.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "falcon/limiter"
+
+service "limiter-example.localhost" do
+	include Falcon::Environment::Limiter
+	
+	# Configure limiter settings
+	limiter_configuration.max_long_tasks = 4
+	limiter_configuration.max_accepts = 2
+	limiter_configuration.start_delay = 0.1 # Shorter delay for demo
+	
+	scheme "http"
+	url "http://localhost:9292"
+	
+	rack_app do
+		run lambda {|env|
+			# Access HTTP request directly
+			request = env["protocol.http.request"]
+			path = env["PATH_INFO"]
+			
+			case path
+			when "/fast"
+				# Fast request - no long task needed
+				[200, { "content-type" => "text/plain" }, ["Fast response: #{Time.now}"]]
+				
+			when "/slow"
+				# Slow I/O bound request - use long task
+				request.long_task&.start
+				
+				# Simulate I/O operation
+				sleep(2.0)
+				
+				# Optional manual stop (auto-cleanup on response end)
+				request.long_task&.stop
+				
+				[200, { "content-type" => "text/plain" }, ["Slow response: #{Time.now}"]]
+				
+			when "/cpu"
+				# CPU bound request - don't use long task to prevent GVL contention
+				# Simulate CPU work
+				result = (1..1_000_000).sum
+				
+				[200, { "content-type" => "text/plain" }, ["CPU result: #{result}"]]
+				
+			when "/stats"
+				# Show limiter statistics
+				stats = statistics
+				[200, { "content-type" => "application/json" }, [stats.to_json]]
+				
+			else
+				[404, { "content-type" => "text/plain" }, ["Not found"]]
+			end
+		}
+	end
+end

data/examples/load/config.ru

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "falcon/limiter/long_task"
+
+run do |env|
+	path = env["PATH_INFO"]
+	
+	case path
+	when "/io"
+		Console.info(self, "Starting \"I/O intensive\" task...")
+		Falcon::Limiter::LongTask.current.start
+		sleep(10)
+	when "/cpu"
+		Console.info(self, "Starting \"CPU intensive\" task...")
+		sleep(10)
+	end
+	
+	[200, {"content-type" => "text/plain"}, ["Hello from Falcon Limiter!"]]
+end

data/examples/load/falcon.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "falcon/limiter/environment"
+require "falcon/environment/rack"
+
+service "hello.localhost" do
+	include Falcon::Environment::Rack
+	include Falcon::Limiter::Environment
+	
+	endpoint do
+		Async::HTTP::Endpoint.parse("http://localhost:9292").with(wrapper: limiter_wrapper)
+	end
+	
+	count {1}
+end

data/lib/falcon/limiter/environment.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Josh Teeter.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "middleware"
+require_relative "semaphore"
+require_relative "wrapper"
+
+module Falcon
+	module Limiter
+		# A flat environment module for falcon-limiter services.
+		#
+		# Provides simple, declarative configuration for concurrency limiting.
+		# Override these methods in your service to customize behavior.
+		module Environment
+			# Maximum number of concurrent long tasks (default: 4).
+			# If this is nil or non-positive, long task support will be disabled.
+			# @returns [Integer] The maximum number of concurrent long tasks.
+			def limiter_maximum_long_tasks
+				4
+			end
+			
+			# @returns [Integer] The maximum number of concurrent connection accepts.
+			def limiter_maximum_connections
+				1
+			end
+			
+			# @returns [Float] The delay before starting long task in seconds.
+			def limiter_start_delay
+				0.1
+			end
+			
+			# @returns [Async::Limiter::Queued] The limiter for coordinating long tasks and connection accepts.
+			def connection_limiter
+				# Create priority queue and pre-populate with tokens:
+				queue = Async::PriorityQueue.new
+				limiter_maximum_connections.times{queue.push(true)}
+				
+				Async::Limiter::Queued.new(queue)
+			end
+			
+			# @returns [Class] The middleware class to use for long task support.
+			def limiter_middleware_class
+				Middleware
+			end
+			
+			# @returns [Protocol::HTTP::Middleware] The middleware with long task support, if enabled.
+			def limiter_middleware(middleware)
+				# Create middleware with long task support if enabled:
+				if limiter_maximum_long_tasks&.positive?
+					limiter_middleware_class.new(
+						middleware, 
+						connection_limiter: connection_limiter,
+						maximum_long_tasks: limiter_maximum_long_tasks,
+						start_delay: limiter_start_delay
+					)
+				else
+					middleware
+				end
+			end
+			
+			# @returns [Protocol::HTTP::Middleware] The middleware with long task support, if enabled.
+			def middleware
+				limiter_middleware(super)
+			end
+			
+			def limiter_wrapper
+				Wrapper.new(connection_limiter)
+			end
+			
+			# @returns [IO::Endpoint::Wrapper] The endpoint with connection limiting.
+			def endpoint
+				super.with(wrapper: limiter_wrapper)
+			end
+		end
+	end
+end

data/lib/falcon/limiter/long_task.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Marc-André Cournoyer.
+# Copyright, 2025, by Francisco Mejia.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/task"
+require_relative "semaphore"
+
+Fiber.attr_accessor :falcon_limiter_long_task
+
+module Falcon
+	module Limiter
+		# Manages long-running tasks by releasing connection tokens during I/O operations to prevent contention and maintain server responsiveness.
+		#
+		# A long task is any long (1+ sec) operation that isn't CPU-bound (usually long I/O). Starting a long task lets the server accept one more (potentially CPU-bound) request. This allows us to handle many concurrent I/O bound requests, without adding contention (which impacts latency).
+		class LongTask
+			# The priority to use when stopping a long task to re-acquire the connection token.
+			STOP_PRIORITY = 1000
+			
+			# @returns [LongTask] The current long task.
+			def self.current
+				Fiber.current.falcon_limiter_long_task
+			end
+			
+			# Assign the current long task.
+			def self.current=(long_task)
+				Fiber.current.falcon_limiter_long_task = long_task
+			end
+			
+			# Execute the block with the current long task.
+			def with
+				previous = self.class.current
+				self.class.current = self
+				yield
+			ensure
+				self.class.current = previous
+			end
+			
+			# Create a long task for the given request.
+			# Extracts connection token from the request if available for proper token management.
+			# @parameter limiter [Async::Limiter] The limiter instance for managing concurrent long tasks.
+			# @parameter request [Object] The HTTP request object to extract connection information from.
+			# @parameter options [Hash] Additional options passed to the constructor.
+			# @returns [LongTask] A new long task instance ready for use.
+			def self.for(request, limiter, **options)
+				# Get connection token from request if possible:
+				connection_token = request&.connection&.stream&.io&.token rescue nil
+				
+				return new(request, limiter, connection_token, **options)
+			end
+			
+			# Initialize a new long task with the specified configuration.
+			# @parameter limiter [Async::Limiter] The limiter instance for controlling concurrency.
+			# @parameter connection_token [Async::Limiter::Token, nil] Optional connection token to manage.
+			# @parameter start_delay [Float] Delay in seconds before starting the long task (default: 0.1).
+			def initialize(request, limiter, connection_token = nil, start_delay: 0.1)
+				@request = request
+				@limiter = limiter
+				@connection_token = connection_token
+				@start_delay = start_delay
+				
+				@token = Async::Limiter::Token.new(@limiter)
+				@delayed_start_task = nil
+			end
+			
+			# Check if the long task has been started.
+			# @returns [Boolean] True if the long task token has been acquired, false otherwise.
+			def started?
+				@token.acquired? || @delayed_start_task
+			end
+			
+			# Start the long task, optionally with a delay to avoid overhead for short operations
+			def start(delay: @start_delay)
+				# If already started, nothing to do:
+				if started?
+					if block_given?
+						return yield self
+					else
+						return self
+					end
+				end
+				
+				if delay == true
+					delay = @start_delay
+				elsif delay == false
+					delay = nil
+				end
+				
+				def acquired?
+					@token.acquired?
+				end
+				
+				# Otherwise, start the long task:
+				if delay&.positive?
+					# Wait specified delay before starting the long task:
+					@delayed_start_task = Async do
+						sleep(delay)
+						self.acquire
+					rescue Async::Stop
+						# Gracefully exit on stop.
+					ensure
+						@delayed_start_task = nil
+					end
+				else
+					# Start the long task immediately:
+					self.acquire
+				end
+				
+				return self unless block_given?
+				
+				begin
+					yield self
+				ensure
+					self.stop
+				end
+			end
+			
+			# Stop the long task and restore connection token
+			def stop(force: false, **options)
+				if delayed_start_task = @delayed_start_task
+					@delayed_start_task = nil
+					delayed_start_task.stop
+				end
+				
+				# Re-acquire the connection token with high priority than inbound requests:
+				options[:priority] ||= STOP_PRIORITY
+				
+				# Release the long task token:
+				release(force, **options)
+			end
+			
+			private
+			
+			# This acquires the long task token and releases the connection token if it exists.
+			# This marks the beginning of a long task.
+			# @parameter options [Hash] The options to pass to the long task token acquisition.
+			def acquire(**options)
+				return if @token.acquired?
+				
+				# Wait if we've reached our limit of ongoing long tasks.
+				if @token.acquire(**options)
+					# Release the socket accept token.
+					@connection_token&.release
+					
+					# Mark connection as non-persistent since we released the token.
+					make_non_persistent!
+				end
+			end
+			
+			# This releases the long task token and re-acquires the connection token if it exists.
+			# This marks the end of a long task.
+			# @parameter force [Boolean] Whether to force the release of the long task token without re-acquiring the connection token.
+			# @parameter options [Hash] The options to pass to the connection token re-acquisition.
+			def release(force = false, **options)
+				return if @token.released?
+				
+				@token.release
+				
+				return if force
+				
+				# Re-acquire the connection token to prevent overloading the connection limiter:
+				@connection_token&.acquire(**options)
+			end
+			
+			def make_non_persistent!
+				# Keeping the connection alive here is problematic because if the next request is slow,
+				# it will "block the server" since we have relinquished the token already.
+				@request&.connection&.persistent = false
+			rescue NoMethodError
+				# Connection may not support persistent flag
+			end
+		end
+	end
+end

data/lib/falcon/limiter/middleware.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Josh Teeter.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http/middleware"
+require_relative "long_task"
+require_relative "semaphore"
+
+module Falcon
+	module Limiter
+		# Protocol::HTTP middleware that provides long task management for requests.
+		# This allows applications to manage I/O vs CPU bound workloads effectively.
+		class Middleware < Protocol::HTTP::Middleware
+			# Initialize the middleware with limiting configuration.
+			# @parameter delegate [Object] The next middleware in the chain to call.
+			# @parameter connection_limiter [Async::Limiter] Connection limiter instance for managing accepts.
+			# @parameter maximum_long_tasks [Integer] Maximum number of concurrent long tasks (default: 4).
+			# @parameter start_delay [Float] Delay in seconds before starting long tasks (default: 0.1).
+			def initialize(delegate, connection_limiter:, maximum_long_tasks: 4, start_delay: 0.1)
+				super(delegate)
+				
+				@maximum_long_tasks = maximum_long_tasks
+				@start_delay = start_delay
+				@connection_limiter = connection_limiter
+				@long_task_limiter = Semaphore.new(maximum_long_tasks)
+			end
+			
+			attr_reader :maximum_long_tasks, :start_delay, :long_task_limiter, :connection_limiter
+			
+			# Process an HTTP request with long task management support.
+			# Creates a long task context that applications can use to manage I/O operations.
+			# @parameter request [Object] The HTTP request to process.
+			# @returns [Object] The HTTP response from the downstream middleware.
+			def call(request)
+				# Create LongTask instance for this request if enabled
+				long_task = LongTask.for(request, @long_task_limiter, start_delay: @start_delay)
+				
+				# Use scoped context for clean access
+				long_task.with do
+					response = super(request)
+					
+					if long_task.started?
+						Protocol::HTTP::Body::Completable.wrap(response) do
+							long_task.stop(force: true)
+						end
+					end
+					
+					response
+				end
+			end
+			
+			# Get semaphore statistics
+			def statistics
+				{
+					long_task_limiter: @long_task_limiter.statistics,
+					connection_limiter: @connection_limiter.statistics
+				}
+			end
+		end
+	end
+end

data/lib/falcon/limiter/semaphore.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Josh Teeter.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/limiter"
+require "async/limiter/token"
+require "async/priority_queue"
+
+module Falcon
+	module Limiter
+		# Simple wrapper around Async::Limiter::Queued that provides the interface
+		# expected by Falcon while leveraging async-limiter's implementation.
+		module Semaphore
+			# Create a new limiter with the specified capacity.
+			# @parameter limit [Integer] The maximum number of concurrent operations allowed (default: 1).
+			# @returns [Async::Limiter::Queued] A new limiter instance with pre-allocated tokens.
+			def self.new(limit = 1)
+				# Create priority queue and pre-populate with tokens
+				queue = Async::PriorityQueue.new
+				limit.times{queue.push(true)}
+				
+				return Async::Limiter::Queued.new(queue)
+			end
+		end
+	end
+end

data/lib/falcon/limiter/socket.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Falcon
+	module Limiter
+		# A transparent socket wrapper that automatically manages token release.
+		# Behaves exactly like the wrapped socket but releases the limiter token on close.
+		class Socket < BasicObject
+			# Initialize the socket wrapper with delegation and token management.
+			# @parameter delegate [Object] The socket object to wrap and delegate to.
+			# @parameter token [Async::Limiter::Token] The limiter token to release when socket closes.
+			def initialize(delegate, token)
+				@delegate = delegate
+				@token = token
+			end
+			
+			# Provide access to the token for manual management if needed.
+			attr_reader :token
+			
+			# Override close to release the token.
+			def close
+				@delegate.close
+			ensure
+				if token = @token
+					@token = nil
+					token.release
+				end
+			end
+			
+			# Transparent delegation to the wrapped delegate.
+			def method_missing(...)
+				@delegate.public_send(...)
+			end
+			
+			# Check if this wrapper or the delegate responds to a method.
+			# @parameter method [Symbol] The method name to check.
+			# @parameter include_private [Boolean] Whether to include private methods (default: false).
+			# @returns [Boolean] True if either wrapper or delegate responds to the method.
+			def respond_to?(method, include_private = false)
+				# Check our own methods first (token, close, inspect, to_s, etc.)
+				case method.to_sym
+				when :token
+					true
+				else
+					# Check delegate for other methods
+					@delegate.respond_to?(method, include_private)
+				end
+			end
+			
+			# Support for method_missing delegation by checking delegate's methods.
+			# @parameter method [Symbol] The method name to check.
+			# @parameter include_private [Boolean] Whether to include private methods (default: false).
+			# @returns [Boolean] True if the delegate responds to the method.
+			def respond_to_missing?(method, include_private = false)
+				@delegate.respond_to?(method, include_private) || super
+			end
+			
+			# Forward common inspection methods
+			def inspect
+				"#<#{self.class}(#{@delegate.class}) #{@delegate.inspect}>"
+			end
+			
+			# String representation of the wrapped socket.
+			# @returns [String] The string representation of the delegate socket.
+			def to_s
+				@delegate.to_s
+			end
+		end
+	end
+end

data/lib/falcon/limiter/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Falcon
+	module Limiter
+		VERSION = "0.1.0"
+	end
+end

data/lib/falcon/limiter/wrapper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "io/endpoint/wrapper"
+require "async/limiter/token"
+require_relative "socket"
+
+module Falcon
+	module Limiter
+		# An endpoint wrapper that limits concurrent connections using a semaphore.
+		# This provides backpressure by limiting how many connections can be accepted simultaneously.
+		class Wrapper < IO::Endpoint::Wrapper
+			# Initialize the wrapper with a connection limiter.
+			# @parameter limiter [Async::Limiter] The limiter instance for controlling concurrent connections.
+			def initialize(limiter)
+				super()
+				@limiter = limiter
+			end
+			
+			attr_reader :limiter
+			
+			# Wait for an inbound connection to be ready to be accepted.
+			def wait_for_inbound_connection(server)
+				loop do
+					# Wait until there is a connection ready to be accepted:
+					server.wait_readable
+					
+					# Acquire the limiter:
+					if token = Async::Limiter::Token.acquire(@limiter)
+						return token
+					end
+				end
+			end
+			
+			# Once the server is readable and we've acquired the token, we can accept the connection (if it's still there).
+			def socket_accept_nonblock(server, token)
+				socket = server.accept_nonblock
+			rescue IO::WaitReadable
+				nil
+			ensure
+				token.release unless socket
+			end
+			
+			def wrap_socket(socket, token)
+				Socket.new(socket, token)
+			end
+			
+			# Accept a connection from the server, limited by the per-worker (thread or process) semaphore.
+			def socket_accept(server)
+				socket = nil
+				address = nil
+				token = nil
+				
+				loop do
+					next unless token = wait_for_inbound_connection(server)
+					
+					# In principle, there is a connection ready to be accepted:
+					socket, address = socket_accept_nonblock(server, token)
+					
+					break if socket
+				end
+				
+				# Wrap socket with transparent token management
+				return wrap_socket(socket, token), address
+			end
+		end
+	end
+end

data/lib/falcon/limiter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "limiter/semaphore"
+require_relative "limiter/socket"
+require_relative "limiter/wrapper"
+require_relative "limiter/long_task"
+require_relative "limiter/middleware"
+require_relative "limiter/environment"
+
+# @namespace
+module Falcon
+	# @namespace
+	module Limiter
+	end
+end

data/license.md

@@ -0,0 +1,24 @@
+# MIT License
+
+Copyright, 2025, by Marc-André Cournoyer.  
+Copyright, 2025, by Francisco Mejia.  
+Copyright, 2025, by Josh Teeter.  
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,160 @@
+# Falcon Limiter
+
+Advanced concurrency control and resource limiting for Falcon web server, built on top of [async-limiter](https://github.com/socketry/async-limiter).
+
+[![Development Status](https://github.com/socketry/falcon-limiter/workflows/Test/badge.svg)](https://github.com/socketry/falcon-limiter/actions?workflow=Test)
+
+## Features
+
+This gem provides sophisticated concurrency management for Falcon applications by:
+
+  - **Connection Limiting**: Control the number of concurrent connections to prevent server overload
+  - **Long Task Management**: Handle I/O vs CPU bound workloads effectively by releasing resources during long operations
+  - **Priority-based Resource Allocation**: Higher priority tasks get preferential access to limited resources
+  - **Automatic Resource Cleanup**: Ensures proper resource release even when exceptions occur
+  - **Built-in Statistics**: Monitor resource utilization and contention
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem 'falcon-limiter'
+```
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/falcon-limiter/) for more details.
+
+### Basic Falcon Environment Integration
+
+``` ruby
+#!/usr/bin/env falcon-host
+
+require "falcon-limiter"
+
+service "myapp.localhost" do
+  include Falcon::Environment::Limiter
+  
+  # Configure concurrency limits
+  limiter_configuration.max_long_tasks = 8
+  limiter_configuration.max_accepts = 2
+  
+  scheme "http"
+  url "http://localhost:9292"
+  
+  rack_app do
+    run lambda { |env|
+      # Start long task for I/O bound work
+      Falcon::Limiter::LongTask.current&.start
+      
+      # Long I/O operation (database query, external API call, etc.)
+      external_api_call
+      
+      # Optional manual stop (auto-cleanup on response end)
+      Falcon::Limiter::LongTask.current&.stop
+      
+      [200, {}, ["OK"]]
+    }
+  end
+end
+```
+
+### Manual Middleware Setup
+
+``` ruby
+require "falcon-limiter"
+require "protocol/http/middleware"
+
+# Configure middleware stack
+middleware = Protocol::HTTP::Middleware.build do
+  use Falcon::Limiter::Middleware, 
+      max_long_tasks: 4,
+      max_accepts: 2
+  use Protocol::Rack::Adapter
+  run rack_app
+end
+```
+
+### Direct Semaphore Usage
+
+``` ruby
+require "falcon-limiter"
+
+# Create a semaphore for database connections
+db_semaphore = Falcon::Limiter::Semaphore.new(5)
+
+# Acquire a connection
+token = db_semaphore.acquire
+
+begin
+  # Use database connection
+  database_operation
+ensure
+  # Release the connection
+  token.release
+end
+```
+
+## Configuration
+
+Configure limits using environment variables or programmatically:
+
+``` bash
+export FALCON_LIMITER_MAX_LONG_TASKS=8
+export FALCON_LIMITER_MAX_ACCEPTS=2
+export FALCON_LIMITER_START_DELAY=0.6
+```
+
+Or in code:
+
+``` ruby
+Falcon::Limiter.configure do |config|
+  config.max_long_tasks = 8
+  config.max_accepts = 2
+  config.start_delay = 0.6
+end
+```
+
+## Architecture
+
+Falcon Limiter is built on top of [async-limiter](https://github.com/socketry/async-limiter), providing:
+
+  - **Thread-safe resource management** using priority queues
+  - **Integration with Falcon's HTTP pipeline** through Protocol::HTTP::Middleware
+  - **Automatic connection token management** for optimal resource utilization
+  - **Priority-based task scheduling** to prevent resource starvation
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec sus` to run the tests.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
+
+### v0.1.0
+
+## See Also
+
+  - [falcon](https://github.com/socketry/falcon) - A fast, asynchronous, rack-compatible web server.
+  - [async-limiter](https://github.com/socketry/async-limiter) - Execution rate limiting for Async.
+  - [async](https://github.com/socketry/async) - A concurrency framework for Ruby.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.1.0

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: falcon-limiter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josh Teeter
+- Samuel Williams
+- Francisco Mejia
+- Marc-André Cournoyer
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-limiter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- examples/basic_limiting.rb
+- examples/environment_usage.rb
+- examples/falcon_environment.rb
+- examples/limiter/README.md
+- examples/limiter/config.ru
+- examples/limiter/falcon.rb
+- examples/load/config.ru
+- examples/load/falcon.rb
+- lib/falcon/limiter.rb
+- lib/falcon/limiter/environment.rb
+- lib/falcon/limiter/long_task.rb
+- lib/falcon/limiter/middleware.rb
+- lib/falcon/limiter/semaphore.rb
+- lib/falcon/limiter/socket.rb
+- lib/falcon/limiter/version.rb
+- lib/falcon/limiter/wrapper.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/falcon-limiter
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/falcon-limiter/
+  source_code_uri: https://github.com/socketry/falcon-limiter.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Advanced concurrency control and resource limiting for Falcon web server.
+test_files: []

metadata.gz.sig

@@ -0,0 +1,3 @@
+^Ù/�Sg�	Pلz�ɺ��G���oĺ��{N�m}|0���<�O�
+��˾G�ϙDL��O����
++�T���Q:��7X��qrYnB���