lean_pool 0.1.0

data/README.md

@@ -0,0 +1,324 @@
+# LeanPool
+
+[![Gem Version](https://badge.fury.io/rb/lean_pool.svg)](https://badge.fury.io/rb/lean_pool)
+[![Build Status](https://github.com/half-blood-labs/lean_pool/workflows/CI/badge.svg)](https://github.com/half-blood-labs/lean_pool/actions)
+[![Downloads](https://img.shields.io/gem/dt/lean_pool.svg)](https://rubygems.org/gems/lean_pool)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-red.svg)](https://www.ruby-lang.org/)
+
+A lightweight, process-free resource pool for Ruby using `concurrent-ruby`. Inspired by Elixir's `nimble_pool`, LeanPool provides efficient resource management without per-resource processes, making it perfect for managing sockets, HTTP connections, ports, and other resources.
+
+**Author:** [Junaid Farooq](mailto:fjunaid252@gmail.com) | **Repository:** [half-blood-labs/lean_pool](https://github.com/half-blood-labs/lean_pool)
+
+## Features
+
+- 🚀 **Zero Overhead**: Direct resource access without data copying between processes
+- 🔒 **Thread-Safe**: Built on `concurrent-ruby` for reliable thread safety
+- ⚡ **Efficient**: Lazy initialization and smart resource reuse
+- 🎯 **Simple API**: Clean, Ruby-idiomatic interface
+- 🔧 **Flexible**: Works with any resource type (sockets, connections, ports, etc.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lean_pool'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install lean_pool
+```
+
+## Usage
+
+### Basic Example
+
+```ruby
+require 'lean_pool'
+
+# Create a pool of Redis connections
+pool = LeanPool::Pool.new(size: 5) do
+  Redis.new(host: "localhost", port: 6379)
+end
+
+# Use the pool
+pool.checkout do |redis|
+  redis.get("my_key")
+  redis.set("my_key", "value")
+end
+```
+
+### HTTP Connection Pool
+
+LeanPool includes a built-in HTTP connection pool for easy HTTP/HTTPS requests:
+
+```ruby
+require 'lean_pool'
+
+# Create an HTTP pool
+http_pool = LeanPool::HTTPPool.new("api.example.com", 443, size: 10, use_ssl: true)
+
+# Perform GET requests
+response = http_pool.get("/users")
+puts response[:status]  # => 200
+puts response[:body]
+puts response[:headers]
+
+# Perform POST requests with JSON
+response = http_pool.post(
+  "/users",
+  body: '{"name":"John","email":"john@example.com"}',
+  headers: { "Content-Type" => "application/json" }
+)
+
+# With custom timeout
+response = http_pool.get("/slow-endpoint", timeout: 30.0)
+
+# Check pool statistics
+stats = http_pool.stats
+# => { size: 10, available: 8, in_use: 2, total: 10 }
+
+# Shutdown when done
+http_pool.shutdown
+```
+
+### Custom HTTP Pool Implementation
+
+You can also create your own HTTP pool wrapper:
+
+```ruby
+require 'lean_pool'
+require 'net/http'
+
+class CustomHTTPPool
+  def self.new_pool(host, port, size: 10)
+    LeanPool::Pool.new(
+      size: size,
+      timeout: 5.0,
+      lazy: true,
+      pool_state: { host: host, port: port }
+    ) do |state|
+      Net::HTTP.new(state[:host], state[:port])
+    end
+  end
+
+  def self.get(pool, path, opts = {})
+    pool.checkout(timeout: opts[:timeout] || 5.0) do |http|
+      http.start unless http.started?
+      response = http.get(path)
+      
+      if response.code == "200"
+        { status: response.code.to_i, body: response.body, headers: response.to_hash }
+      else
+        { remove: true }
+      end
+    end
+  end
+end
+
+# Usage
+pool = CustomHTTPPool.new_pool("api.example.com", 443)
+result = CustomHTTPPool.get(pool, "/users")
+puts result[:body]
+```
+
+### With Custom State
+
+```ruby
+pool = LeanPool::Pool.new(
+  size: 10,
+  pool_state: { database: "production", timeout: 30 }
+) do |state|
+  DatabaseConnection.new(
+    database: state[:database],
+    timeout: state[:timeout]
+  )
+end
+
+pool.checkout do |db|
+  db.query("SELECT * FROM users")
+end
+```
+
+### Pool Statistics
+
+```ruby
+pool = LeanPool::Pool.new(size: 5) { Redis.new }
+
+stats = pool.stats
+# => { size: 5, available: 3, in_use: 2, total: 5 }
+```
+
+### Shutdown and Reload
+
+```ruby
+# Gracefully shutdown the pool
+pool.shutdown do |resource|
+  resource.close if resource.respond_to?(:close)
+end
+
+# Reload the pool (useful after forking)
+pool.reload do |resource|
+  resource.quit if resource.respond_to?(:quit)
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  pool.checkout(timeout: 2.0) do |resource|
+    resource.perform_operation
+  end
+rescue LeanPool::TimeoutError => e
+  puts "Pool is busy, try again later"
+rescue LeanPool::ShutdownError => e
+  puts "Pool is shutdown"
+rescue LeanPool::ResourceError => e
+  puts "Failed to create resource: #{e.message}"
+end
+```
+
+## Comparison with Other Pooling Solutions
+
+| Feature | LeanPool | connection_pool | pond |
+|---------|----------|-----------------|------|
+| Process-free | ✅ | ❌ | ❌ |
+| Direct resource access | ✅ | ❌ | ❌ |
+| Zero data copying | ✅ | ❌ | ❌ |
+| Thread-safe | ✅ | ✅ | ✅ |
+| Lazy initialization | ✅ | ✅ | ✅ |
+| Built on concurrent-ruby | ✅ | ❌ | ❌ |
+
+## When to Use LeanPool
+
+**Use LeanPool when:**
+- You need direct access to resources (sockets, ports, HTTP connections)
+- You want to avoid data copying between processes
+- You're managing resources that don't need per-resource processes
+- You need high-performance resource pooling
+
+**Don't use LeanPool when:**
+- You're managing processes (use process-based pools instead)
+- You need multiplexing (HTTP/2, etc.)
+- Resources require per-resource process isolation
+
+## Requirements
+
+- Ruby >= 3.0.0
+- concurrent-ruby >= 1.3.0
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+$ bundle install
+$ bundle exec rspec
+```
+
+### Running Tests Locally
+
+**Quick test run:**
+```bash
+$ bundle exec rspec
+```
+
+**With documentation format:**
+```bash
+$ bundle exec rspec --format documentation
+```
+
+**Run specific test files:**
+```bash
+$ bundle exec rspec spec/lean_pool/pool_spec.rb
+$ bundle exec rspec spec/lean_pool/http_pool_spec.rb
+$ bundle exec rspec spec/lean_pool/errors_spec.rb
+```
+
+**Simulate CI locally:**
+```bash
+$ ./.github/workflows/test-local.sh
+```
+
+This script will:
+- Check Ruby version
+- Install dependencies
+- Validate syntax of all Ruby files
+- Run RuboCop linting
+- Run the full test suite
+- Display test summary
+
+**Using Rake:**
+```bash
+$ bundle exec rake        # Runs tests + linting
+$ bundle exec rake spec  # Runs only tests
+```
+
+## Testing
+
+The project includes comprehensive test coverage with over 198 test cases covering:
+
+- Pool initialization and configuration
+- Resource checkout and lifecycle management
+- Thread safety and concurrent operations
+- Timeout handling and error recovery
+- HTTP connection pooling
+- Integration scenarios and real-world use cases
+- Edge cases and boundary conditions
+
+Run the full test suite:
+
+```bash
+$ bundle exec rspec
+```
+
+## Project Status
+
+- ✅ **CI/CD**: Automated testing with GitHub Actions (testing on Ruby 3.0, 3.1, 3.2, 3.3)
+- ✅ **Test Coverage**: Comprehensive test suite with 198+ test cases
+- ✅ **Documentation**: Complete YARD documentation for all modules
+- ✅ **Thread Safety**: Built on concurrent-ruby for reliable concurrency
+- ✅ **Production Ready**: Suitable for production use
+- ✅ **Code Quality**: RuboCop linting and syntax validation
+
+## CI/CD Status
+
+The project uses GitHub Actions for continuous integration:
+
+- **Test Matrix**: Tests run on Ruby 3.0, 3.1, 3.2, and 3.3
+- **Linting**: RuboCop code quality checks
+- **Syntax Validation**: Automatic Ruby syntax checking
+- **Status Badge**: [![Build Status](https://github.com/half-blood-labs/lean_pool/workflows/CI/badge.svg)](https://github.com/half-blood-labs/lean_pool/actions)
+
+View the latest CI runs: [GitHub Actions](https://github.com/half-blood-labs/lean_pool/actions)
+
+**Note**: After publishing the gem to RubyGems, the badges will automatically update to show download counts and build status.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/half-blood-labs/lean_pool.
+
+## Author
+
+**Junaid Farooq**
+
+- Email: fjunaid252@gmail.com
+- GitHub: [@half-blood-labs](https://github.com/half-blood-labs)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Inspiration
+
+This gem is inspired by [nimble_pool](https://github.com/dashbitco/nimble_pool) from the Elixir ecosystem, adapted for Ruby's concurrency model using `concurrent-ruby`.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/lean_pool"
+
+# Example 1: Basic resource pool
+puts "=== Example 1: Basic Resource Pool ==="
+pool = LeanPool::Pool.new(size: 3) do
+  { id: rand(1000), created_at: Time.now }
+end
+
+3.times do |i|
+  result = pool.checkout do |resource|
+    puts "Using resource #{i + 1}: #{resource[:id]}"
+    resource[:id] * 2
+  end
+  puts "Result: #{result}"
+end
+
+puts "\nPool stats: #{pool.stats}"
+
+# Example 2: HTTP Pool
+puts "\n=== Example 2: HTTP Pool ==="
+begin
+  http_pool = LeanPool::HTTPPool.new("httpbin.org", 80, size: 5)
+  
+  response = http_pool.get("/get")
+  puts "Status: #{response[:status]}"
+  puts "Response size: #{response[:body]&.length || 0} bytes"
+  
+  puts "\nHTTP Pool stats: #{http_pool.stats}"
+  
+  http_pool.shutdown
+rescue => e
+  puts "HTTP example failed (network may be unavailable): #{e.message}"
+end
+
+# Example 3: Custom resource with state
+puts "\n=== Example 3: Custom Resource with State ==="
+class SimpleCounter
+  def initialize(initial_value = 0)
+    @value = initial_value
+  end
+
+  def increment
+    @value += 1
+  end
+
+  def value
+    @value
+  end
+end
+
+counter_pool = LeanPool::Pool.new(
+  size: 2,
+  pool_state: { start: 10 }
+) do |state|
+  SimpleCounter.new(state[:start])
+end
+
+results = []
+2.times do
+  result = counter_pool.checkout do |counter|
+    counter.increment
+    counter.value
+  end
+  results << result
+end
+
+puts "Counter results: #{results}"
+puts "Counter pool stats: #{counter_pool.stats}"
+
+puts "\n=== All examples completed! ==="

data/lean_pool.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/lean_pool/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "lean_pool"
+  spec.version       = LeanPool::VERSION
+  spec.authors       = ["Junaid Farooq"]
+  spec.email         = ["fjunaid252@gmail.com"]
+
+  spec.summary       = "A lightweight, process-free resource pool for Ruby using concurrent-ruby"
+  spec.description   = <<~DESC
+    LeanPool is a tiny, efficient resource pool implementation for Ruby that provides
+    direct resource access without per-resource processes. Inspired by Elixir's nimble_pool,
+    it's perfect for managing sockets, HTTP connections, ports, and other resources that
+    need efficient pooling with minimal overhead.
+  DESC
+  spec.homepage      = "https://github.com/half-blood-labs/lean_pool"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/half-blood-labs/lean_pool"
+  spec.metadata["changelog_uri"] = "https://github.com/half-blood-labs/lean_pool/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "concurrent-ruby", "~> 1.3"
+end

data/lib/lean_pool/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module LeanPool
+  # Base error class for all LeanPool errors.
+  #
+  # All LeanPool-specific errors inherit from this class, allowing you to
+  # catch all LeanPool errors with a single rescue clause.
+  #
+  # @example Catching all LeanPool errors
+  #   begin
+  #     pool.checkout { |r| r.operation }
+  #   rescue LeanPool::Error => e
+  #     puts "LeanPool error: #{e.message}"
+  #   end
+  #
+  # @since 0.1.0
+  class Error < StandardError; end
+
+  # Raised when a pool checkout operation times out.
+  #
+  # This error is raised when attempting to checkout a resource from a pool
+  # that is at capacity and no resources become available within the specified
+  # timeout period.
+  #
+  # @example Handling timeout errors
+  #   begin
+  #     pool.checkout(timeout: 1.0) { |r| r.operation }
+  #   rescue LeanPool::TimeoutError => e
+  #     puts "Pool is busy, try again later"
+  #   end
+  #
+  # @since 0.1.0
+  class TimeoutError < Error; end
+
+  # Raised when attempting to use a pool that has been shutdown.
+  #
+  # This error is raised when attempting to checkout a resource from a pool
+  # that has been shut down. Once a pool is shutdown, it cannot be used for
+  # new operations unless it is reloaded.
+  #
+  # @example Handling shutdown errors
+  #   begin
+  #     pool.checkout { |r| r.operation }
+  #   rescue LeanPool::ShutdownError => e
+  #     puts "Pool has been shutdown"
+  #   end
+  #
+  # @see Pool#shutdown
+  # @see Pool#reload
+  # @since 0.1.0
+  class ShutdownError < Error; end
+
+  # Raised when resource initialization fails.
+  #
+  # This error is raised when the resource initializer block raises an exception
+  # during resource creation. The original error is preserved and can be accessed
+  # via the `cause` attribute.
+  #
+  # @example Handling resource errors
+  #   begin
+  #     pool.checkout { |r| r.operation }
+  #   rescue LeanPool::ResourceError => e
+  #     puts "Failed to create resource: #{e.message}"
+  #     puts "Original error: #{e.cause}"
+  #   end
+  #
+  # @since 0.1.0
+  class ResourceError < Error; end
+end