falcon-limiter 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61d3807604e041bf6affc784d16a9dc6003016e0f716081f2fb85efd26f17f12
-  data.tar.gz: 9b1ca7661095b7f609b5cd027975e52bbd9b87951d09d2c6b947c16503fa9396
+  metadata.gz: 19aed9c67b7fe7b68716eb8b4db0ffaa0424733a2e3e18abda65e367293fda17
+  data.tar.gz: 1eabdea4a1110e92a86a5d30bc1dba115cc10f7d33fb8ef545d3f5f6806eaac0
 SHA512:
-  metadata.gz: d09553c8da363d761041e05850e6e38a6f562eb00108ea6944f6724e4546fc114332367c73ee1e87ff5445ed4fbc0a8d3519fbf2a42a0bc7806ff8088e73af5d
-  data.tar.gz: c46e60261492d8f0da23738dffe8fbdf20844e999acf766ee3e93cf3f3a2b351e8a9fd804249dc12284b987b35f843644d977db8536156be15e082c3277bbcff
+  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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon-limiter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Josh Teeter
@@ -59,9 +59,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- examples/load/config.ru
-- examples/load/falcon.rb
-- examples/load/readme.md
+- 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/load/config.ru

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require "console"
-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(delay: 0.1)
-		sleep(10)
-	when "/cpu"
-		Console.info(self, "Starting \"CPU intensive\" task...")
-		sleep(10)
-	else
-		Console.info(self, "Unknown path: #{path}")
-		return [404, {"content-type" => "text/plain"}, ["Not Found"]]
-	end
-	
-	Console.info(self, "Request completed");
-	
-	[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

data/examples/load/readme.md

@@ -1,87 +0,0 @@
-# Load Example
-
-This example provides pseudo "io"-bound and "cpu"-bound endpoints for testing Falcon Limiter.
-
-## Usage
-
-First, start the server:
-
-```bash
-$ bundle exec ./falcon.rb
-  0.0s     info: Falcon::Command::Host [oid=0x448] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | Falcon Host v0.52.3 taking flight!
-               | - Configuration: ././falcon.rb
-               | - To terminate: Ctrl-C or kill 8064
-               | - To reload: kill -HUP 8064
- 0.08s     info: Async::Container::Notify::Console [oid=0x510] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | {status: "Initializing controller..."}
- 0.08s     info: Falcon::Service::Server [oid=0x520] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | Starting hello.localhost on #<Async::HTTP::Endpoint http://localhost:9292ps/ {wrapper: #<Falcon::Limiter::Wrapper:0x0000000104efe0e8 @limiter=#<Async::Limiter::Queued:0x00000001086ffcd0 @timing=Async::Limiter::Timing::None, @parent=nil, @tags=nil, @mutex=#<Thread::Mutex:0x0000000104efe188>, @queue=#<Async::PriorityQueue:0x00000001086ffd20 @items=[true], @closed=false, @parent=nil, @waiting=#<IO::Event::PriorityHeap:0x0000000104efe4a8 @contents=[]>, @sequence=0, @mutex=#<Thread::Mutex:0x0000000104efe3e0>>>>}>
- 0.08s     info: Async::Service::Controller [oid=0x528] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | Controller starting...
- 0.08s     info: Async::Container::Notify::Console [oid=0x510] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | {ready: true, size: 1}
- 0.08s     info: Async::Service::Controller [oid=0x528] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
-               | Controller started...
-```
-
-Note that the server is starting with a wrapper `Falcon::Limiter::Wrapper` which provides connection limiting, and with only a single worker (for the sake of making testing predictable).
-
-## "CPU"-bound Work
-
-Make several requests to the `/cpu` path:
-
-```bash
-# Start multiple requests in background
-$ curl http://localhost:9292/cpu &
-$ curl http://localhost:9292/cpu &
-$ curl http://localhost:9292/cpu &
-
-$ curl -v http://localhost:9292/cpu
-```
-
-You will note that these will be sequential as the connection limiter is limited to 1 connection at a time.
-
-## "IO"-bound Work
-
-Make several requests to the `/io` path:
-
-```bash
-# These will run concurrently (up to the long task limit)
-$ curl http://localhost:9292/io &
-$ curl http://localhost:9292/io &
-$ curl http://localhost:9292/io &
-$ curl http://localhost:9292/io &
-
-$ curl -v http://localhost:9292/io
-```
-
-You will note that these will be concurrent, as the connection limiter is released once `LongTask.current.start` is invoked.
-
-Also note that in order to prevent persistent connections from overloading the limiter, once a connection handles an "IO"-bound request, it will be marked as non-persistent (`connection: close`). This prevents us from having several "IO"-bound requests and a "CPU"-bound request from exceeding the limit on "CPU"-bound requests, by preventing a connection that was handling an "IO"-bound request from submitting a "CPU"-bound request (or otherwise hanging while waiting on the connection limiter).
-
-## Mixed Workload Testing
-
-In addition, if you perform a "CPU"-bound request after starting several "IO"-bound requests, a single "CPU"-bound request will be allowed, but until it completes, no further connections will be accepted.
-
-To see the limiter behavior with mixed workloads:
-
-```bash
-# Start several I/O requests
-$ curl http://localhost:9292/io &
-$ curl http://localhost:9292/io &
-$ curl http://localhost:9292/io &
-
-# Then try a CPU request (should be queued until I/O requests complete)
-$ curl http://localhost:9292/cpu
-```
-
-## Configuration
-
-The example is configured with:
-- **Connection limit**: 1 (only 1 connection accepted at a time).
-- **Long task limit**: 4 (up to 4 concurrent I/O operations).
-- **Start delay**: 0.1 seconds (delay before releasing connection token).
-- **Workers**: 1 (single process for predictable behavior).
-
-You can modify these values in `falcon.rb` by overriding the environment methods.