falcon-limiter 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f3dddcc61c0937bb6126b7a27298982a6159438479753b717fff59491ab9048
-  data.tar.gz: 6430a166f1ffb09e7dbdc6b0e4897abdcfc82c4b299af550aebe3a0ace1deba5
+  metadata.gz: 19aed9c67b7fe7b68716eb8b4db0ffaa0424733a2e3e18abda65e367293fda17
+  data.tar.gz: 1eabdea4a1110e92a86a5d30bc1dba115cc10f7d33fb8ef545d3f5f6806eaac0
 SHA512:
-  metadata.gz: 4313993a4aa621ed7be5449759e8e874224c1d7ad88f1708e54f8fc2b070064b8ec43cce7b43775d98295c90eb46bd273592bd592331d20cb0d3f7990cef0a4a
-  data.tar.gz: a4b12e91879182a082573553293615843d07f08c8aa67d4f9a2aa13af1121dda6b13cff654887e7da585d21eb10f1d7a6c06d009818e03fbcb2f6a363b9b6a87
+  metadata.gz: be434c0ba702339891fbf77bf78ce76610e5b833abf304ac7c65913aceac28a04a0ac4560d75e29c5866d8fa13598482b62aa949d9bef6d326eb62b2ccfcd1f7
+  data.tar.gz: 51344952a67ae841d4f3284fe084178ba6af764e482c7f16d730c5d22a3ffc64560af6010602c416427c8f42706e822b3228073ee84714f7508c07b787f2da18

data/context/getting-started.md

@@ -0,0 +1,116 @@
+# Getting Started
+
+This guide explains how to get started with `falcon-limiter` for advanced concurrency control and resource limiting in Falcon web applications.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add falcon-limiter
+```
+
+## Core Concepts
+
+`falcon-limiter` has one main concept:
+
+- {ruby Falcon::Limiter::LongTask} represents operations that take significant time but aren't CPU-intensive (like database queries or API calls).
+
+When you start a Long Task, the server:
+
+- Releases the connection token so new requests can be accepted.
+- Continues processing your I/O operation in the background.
+- Prevents too many I/O operations from running simultaneously.
+- Maintains responsiveness for CPU-bound requests.
+
+This means your server can handle many concurrent I/O operations without blocking quick CPU-bound requests.
+
+## Usage
+
+The easiest way to get started is using the {ruby Falcon::Limiter::Environment} module:
+
+```ruby
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+require "falcon/limiter/environment"
+require "falcon/environment/rack"
+
+service "myapp.localhost" do
+	include Falcon::Environment::Rack
+	include Falcon::Limiter::Environment
+	
+	# If you use a custom endpoint, you need to use it with the limiter wrapper:
+	endpoint do
+		Async::HTTP::Endpoint.parse("http://localhost:9292").with(wrapper: limiter_wrapper)
+	end
+end
+```
+
+Then in your Rack application:
+
+```ruby
+# config.ru
+require "falcon/limiter/long_task"
+
+run do |env|
+	path = env["PATH_INFO"]
+	
+	case path
+	when "/io"
+		# For I/O bound work, start a long task to release the connection token:
+		Falcon::Limiter::LongTask.current.start
+		
+		# Long I/O operation (database query, external API call, etc.).
+		sleep(5) # Simulating I/O.
+		
+	when "/cpu"
+		# For CPU bound work, keep the connection token.
+		# This ensures only limited CPU work happens concurrently.
+		sleep(5) # Simulating CPU work.
+	end
+	
+	[200, {"content-type" => "text/plain"}, ["Request completed"]]
+end
+```
+
+### Understanding the Behavior
+
+With the default configuration:
+
+- **Connection limit**: 1 (only 1 connection accepted at a time)
+- **Long task limit**: 10 (up to 10 concurrent I/O operations)
+
+This means:
+
+1. **CPU-bound requests** (`/cpu`) will be processed sequentially - only one at a time
+2. **I/O-bound requests** (`/io`) can run concurrently (up to 10) because they release their connection token
+3. **Mixed workloads** work optimally - I/O requests don't block CPU requests from being accepted
+
+### Configuration
+
+You can customize the limits by overriding the environment methods:
+
+```ruby
+service "myapp.localhost" do
+	include Falcon::Environment::Rack
+	include Falcon::Limiter::Environment
+	
+	# Override default limits
+	def limiter_maximum_connections
+		2  # Allow 2 concurrent connections
+	end
+	
+	def limiter_maximum_long_tasks
+		8  # Allow 8 concurrent I/O operations
+	end
+	
+	def limiter_start_delay
+		0.05  # Reduce delay before starting long tasks
+	end
+	
+	endpoint do
+		Async::HTTP::Endpoint.parse("http://localhost:9292").with(wrapper: limiter_wrapper)
+	end
+end
+```

data/context/index.yaml

@@ -0,0 +1,16 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Advanced concurrency control and resource limiting for Falcon web server.
+metadata:
+  documentation_uri: https://socketry.github.io/falcon-limiter/
+  source_code_uri: https://github.com/socketry/falcon-limiter.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `falcon-limiter` for advanced
+    concurrency control and resource limiting in Falcon web applications.
+- path: long-tasks.md
+  title: Long Tasks
+  description: This guide explains how to use <code class="language-ruby">Falcon::Limiter::LongTask</code>
+    to effectively manage I/O vs CPU bound workloads in your Falcon applications.

data/context/long-tasks.md

@@ -0,0 +1,160 @@
+# Long Tasks
+
+This guide explains how to use {ruby Falcon::Limiter::LongTask} to effectively manage I/O vs CPU bound workloads in your Falcon applications.
+
+## Understanding Long Tasks
+
+A **long task** in `falcon-limiter` is any operation that takes significant time (1+ seconds) and isn't CPU-bound, typically I/O operations like:
+
+- Database queries.
+- External API calls.
+- File system operations.
+- Network requests.
+- Message queue operations.
+
+The key insight is that during I/O operations, your application is waiting rather than consuming CPU resources. Long tasks allow the server to:
+
+1. **Release the connection token** during I/O, allowing other requests to be accepted.
+2. **Maintain responsiveness** by not blocking CPU-bound requests.
+3. **Optimize resource utilization** by running multiple I/O operations concurrently.
+
+## Usage
+
+When using {ruby Falcon::Limiter::Environment}, a long task is automatically created for each request:
+
+```ruby
+# In your Rack application
+run do |env|
+	# Long task is available via Falcon::Limiter::LongTask.current
+	long_task = Falcon::Limiter::LongTask.current
+	
+	if long_task
+		# Start the long task for I/O operations
+		long_task.start
+		
+		# Perform I/O operation
+		database_query
+		
+		# Long task automatically stops when request completes
+	end
+	
+	[200, {}, ["Response"]]
+end
+```
+
+### Custom Delays
+
+A delay is used to avoid starting a long task until we know that it's likely to be slow.
+
+```ruby
+run do |env|
+	path = env["PATH_INFO"]
+	
+	case path
+	when "/io"
+		# Start long task with default delay (0.1 seconds):
+		Falcon::Limiter::LongTask.current.start
+		
+		# Perform I/O operation:
+		external_api_call
+		
+	when "/io-immediate"
+		# Start immediately without delay:
+		Falcon::Limiter::LongTask.current.start(delay: false)
+		
+		# Perform I/O operation:
+		database_query
+		
+	when "/io-custom-delay"
+		# Start with custom delay:
+		Falcon::Limiter::LongTask.current.start(delay: 0.5)
+		
+		# Perform I/O operation:
+		slow_file_operation
+		
+	when "/cpu"
+		# Don't start long task for CPU-bound work:
+		cpu_intensive_calculation
+	end
+	
+	[200, {}, ["Completed"]]
+end
+```
+
+### Block-based Long Tasks
+
+You can use long tasks with blocks for automatic cleanup:
+
+```ruby
+require "net/http"
+
+run do |env|
+	path = env["PATH_INFO"]
+	
+	case path
+	when "/api/weather"
+		# Use block-based long task for automatic cleanup:
+		response = Falcon::Limiter::LongTask.current.start do |long_task|
+			# Make external API call:
+			uri = URI("https://api.openweathermap.org/data/2.5/weather?q=London")
+			Net::HTTP.get_response(uri)
+			# Automatic LongTask#stop when block exits.
+		end
+		
+		# CPU work happens outside the long task:
+		result = JSON.parse(response.body)
+		[200, {"content-type" => "application/json"}, [result.to_json]]
+		
+	when "/api/database"
+		# Multiple I/O operations in one long task:
+		users, enriched_data = Falcon::Limiter::LongTask.current.start do
+			# Database query
+			users = database.query("SELECT * FROM users WHERE active = true")
+			
+			# External service call:
+			uri = URI("https://api.example.com/enrich")
+			enriched_data = Net::HTTP.post_form(uri, {user_ids: users.map(&:id)})
+			
+			[users, enriched_data]
+		end
+		
+		# CPU work happens outside the long task:
+		parsed_data = JSON.parse(enriched_data.body)
+		result = users.zip(parsed_data)
+		[200, {"content-type" => "application/json"}, [result.to_json]]
+	end
+end
+```
+
+The block form ensures the long task is properly stopped even if an exception occurs. They can also be nested.
+
+## Long Task Lifecycle
+
+### 1. Creation
+
+Long tasks are created automatically by {ruby Falcon::Limiter::Middleware} for each request when long task support is enabled.
+
+### 2. Starting
+
+When you call `start()`, the long task:
+
+- Waits for the configured delay (default: 0.1 seconds).
+- Acquires a long task token from the limiter.
+- Releases the connection token, allowing new connections.
+- Marks the connection as non-persistent to prevent token leakage
+
+### 3. Execution
+
+During long task execution:
+
+- The connection token is released, so new requests can be accepted.
+- The long task token prevents too many I/O operations from running concurrently.
+- Your I/O operation runs normally.
+
+### 4. Completion
+
+When the request completes, the long task automatically:
+
+- Releases the long task token.
+- Re-acquires the connection token with high priority.
+- Cleans up resources.

data/lib/falcon/limiter/environment.rb

@@ -15,11 +15,11 @@ module Falcon
 		# 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).
+			# Maximum number of concurrent long tasks (default: 10).
 			# 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
+				10
 			end
 			
 			# @returns [Integer] The maximum number of concurrent connection accepts.
@@ -66,6 +66,7 @@ module Falcon
 				limiter_middleware(super)
 			end
 			
+			# @returns [Falcon::Limiter::Wrapper] The wrapper for the connection limiter.
 			def limiter_wrapper
 				Wrapper.new(connection_limiter)
 			end

data/lib/falcon/limiter/long_task.rb

@@ -65,12 +65,18 @@ module Falcon
 				@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.
+			# Check if the long task has been started, but not necessarily acquired (e.g. if there was a delay).
+			# @returns [Boolean] If the long task has been started.
 			def started?
 				@token.acquired? || @delayed_start_task
 			end
 			
+			# Check if the long task has been acquired.
+			# @returns [Boolean] If the long task token has been acquired.
+			def acquired?
+				@token.acquired?
+			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:
@@ -88,10 +94,6 @@ module Falcon
 					delay = nil
 				end
 				
-				def acquired?
-					@token.acquired?
-				end
-				
 				# Otherwise, start the long task:
 				if delay&.positive?
 					# Wait specified delay before starting the long task:

data/lib/falcon/limiter/middleware.rb

@@ -16,9 +16,9 @@ module Falcon
 			# 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 maximum_long_tasks [Integer] Maximum number of concurrent long tasks (default: 10).
 			# @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)
+			def initialize(delegate, connection_limiter:, maximum_long_tasks: 10, start_delay: 0.1)
 				super(delegate)
 				
 				@maximum_long_tasks = maximum_long_tasks

data/lib/falcon/limiter/socket.rb

@@ -49,17 +49,9 @@ module Falcon
 				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}>"
+				"#<#{Socket} #{@delegate.inspect}>"
 			end
 			
 			# String representation of the wrapped socket.

data/lib/falcon/limiter/version.rb

@@ -5,6 +5,6 @@
 
 module Falcon
 	module Limiter
-		VERSION = "0.1.0"
+		VERSION = "0.1.2"
 	end
 end

data/lib/falcon/limiter/wrapper.rb

@@ -43,6 +43,10 @@ module Falcon
 				token.release unless socket
 			end
 			
+			# Wrap the socket with a transparent token management.
+			# @parameter socket [Object] The socket to wrap.
+			# @parameter token [Async::Limiter::Token] The limiter token to release when socket closes.
+			# @returns [Falcon::Limiter::Socket] The wrapped socket.
 			def wrap_socket(socket, token)
 				Socket.new(socket, token)
 			end

data/readme.md

@@ -8,126 +8,33 @@ Advanced concurrency control and resource limiting for Falcon web server, built
 
 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
+  - **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
+## Usage
 
-Add this line to your application's Gemfile:
+Please see the [project documentation](https://socketry.github.io/falcon-limiter/) for more details.
 
-``` ruby
-gem 'falcon-limiter'
-```
+  - [Getting Started](https://socketry.github.io/falcon-limiter/guides/getting-started/index) - This guide explains how to get started with `falcon-limiter` for advanced concurrency control and resource limiting in Falcon web applications.
 
-## Usage
+  - [Long Tasks](https://socketry.github.io/falcon-limiter/guides/long-tasks/index) - This guide explains how to use <code class="language-ruby">Falcon::Limiter::LongTask</code> to effectively manage I/O vs CPU bound workloads in your Falcon applications.
 
-Please see the [project documentation](https://socketry.github.io/falcon-limiter/) for more details.
+## Releases
+
+Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
 
-### 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.
+### v0.1.0
+
+  - Initial implementation.
+
+## 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.
 
 ## Contributing
 
@@ -146,15 +53,3 @@ In order to protect users of this project, we require all contributors to comply
 ### 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

@@ -1,3 +1,5 @@
 # Releases
 
 ## v0.1.0
+
+  - Initial implementation.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon-limiter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Josh Teeter
@@ -59,14 +59,9 @@ 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
+- context/getting-started.md
+- context/index.yaml
+- context/long-tasks.md
 - lib/falcon/limiter.rb
 - lib/falcon/limiter/environment.rb
 - lib/falcon/limiter/long_task.rb

data/examples/basic_limiting.rb

@@ -1,40 +0,0 @@
-#!/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

@@ -1,77 +0,0 @@
-#!/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

@@ -1,55 +0,0 @@
-#!/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

@@ -1,95 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-#!/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

@@ -1,60 +0,0 @@
-#!/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

@@ -1,19 +0,0 @@
-# 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

@@ -1,19 +0,0 @@
-#!/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