lean_pool 0.1.0

data/lib/lean_pool/http_pool.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "pool"
+
+module LeanPool
+  # HTTP connection pool implementation using Net::HTTP.
+  #
+  # HTTPPool provides a convenient wrapper around {Pool} for managing HTTP/1
+  # connections. It automatically handles connection lifecycle, request/response
+  # processing, and connection reuse.
+  #
+  # This is an example implementation demonstrating how to use LeanPool for
+  # HTTP connections. For production use with more advanced features (HTTP/2,
+  # connection keep-alive optimization, etc.), consider using libraries like
+  # HTTP.rb or Faraday with connection pooling.
+  #
+  # Features:
+  # - Automatic connection management and reuse
+  # - Support for both HTTP and HTTPS (SSL)
+  # - GET and POST request methods
+  # - Custom headers and timeouts
+  # - Automatic connection removal on errors
+  #
+  # @example Basic HTTP requests
+  #   pool = LeanPool::HTTPPool.new("api.example.com", 443, size: 10, use_ssl: true)
+  #   
+  #   response = pool.get("/users")
+  #   puts response[:status]  # => 200
+  #   puts response[:body]
+  #   puts response[:headers]
+  #
+  # @example POST request with JSON
+  #   pool = LeanPool::HTTPPool.new("api.example.com", 443, use_ssl: true)
+  #   
+  #   response = pool.post(
+  #     "/users",
+  #     body: '{"name":"John"}',
+  #     headers: { "Content-Type" => "application/json" }
+  #   )
+  #
+  # @example With custom timeout
+  #   pool = LeanPool::HTTPPool.new("api.example.com", 80, timeout: 10.0)
+  #   response = pool.get("/slow-endpoint", timeout: 15.0)
+  #
+  # @note Uses Ruby's standard Net::HTTP library. Connections are reused when
+  #   possible but removed automatically if errors occur.
+  #
+  # @since 0.1.0
+  class HTTPPool
+    # Initialize a new HTTP connection pool.
+    #
+    # Creates a new pool for managing HTTP connections to the specified host and port.
+    # Connections are created lazily on-demand and reused when possible.
+    #
+    # @param host [String] The hostname or IP address to connect to
+    # @param port [Integer] The port number to connect to
+    # @param size [Integer] Maximum number of connections in the pool (default: 10)
+    # @param timeout [Float] Default timeout in seconds for operations (default: 5.0)
+    # @param use_ssl [Boolean] Whether to use SSL/TLS for connections (default: false)
+    #
+    # @example
+    #   pool = LeanPool::HTTPPool.new("api.example.com", 443, size: 10, use_ssl: true)
+    def initialize(host, port, size: 10, timeout: 5.0, use_ssl: false)
+      @host = host
+      @port = port
+      @use_ssl = use_ssl
+
+      @pool = Pool.new(
+        size: size,
+        timeout: timeout,
+        pool_state: { host: host, port: port, use_ssl: use_ssl }
+      ) do |state|
+        http = Net::HTTP.new(state[:host], state[:port])
+        http.use_ssl = state[:use_ssl] if state[:use_ssl]
+        http
+      end
+    end
+
+    # Perform a GET HTTP request.
+    #
+    # Retrieves a connection from the pool, performs a GET request to the specified
+    # path, and returns the response. The connection is automatically returned to
+    # the pool unless an error occurs, in which case it's removed.
+    #
+    # @param path [String] The request path (e.g., "/users" or "/api/v1/data")
+    # @param headers [Hash] Optional HTTP headers to include in the request
+    # @param timeout [Float, nil] Optional timeout override in seconds. If nil, uses
+    #   the pool's default timeout.
+    # @return [Hash] Response hash with the following keys:
+    #   - `:status` [Integer] HTTP status code (e.g., 200, 404, 500)
+    #   - `:body` [String] Response body
+    #   - `:headers` [Hash] Response headers
+    # @return [Hash] If an error occurs, returns a hash with `:error` and `:remove` keys
+    #
+    # @example Basic GET request
+    #   response = pool.get("/users")
+    #   puts response[:status]  # => 200
+    #   puts response[:body]
+    #
+    # @example With custom headers
+    #   response = pool.get(
+    #     "/api/data",
+    #     headers: { "Authorization" => "Bearer token", "Accept" => "application/json" }
+    #   )
+    #
+    # @example With custom timeout
+    #   response = pool.get("/slow-endpoint", timeout: 30.0)
+    def get(path, headers: {}, timeout: nil)
+      @pool.checkout(timeout: timeout) do |http|
+        http.start unless http.started?
+
+        request = Net::HTTP::Get.new(path)
+        headers.each { |k, v| request[k] = v }
+
+        response = http.request(request)
+
+        {
+          status: response.code.to_i,
+          body: response.body,
+          headers: response.to_hash
+        }
+      end
+    rescue => e
+      # Remove connection if it's broken
+      { error: e.message, remove: true }
+    end
+
+    # Perform a POST HTTP request.
+    #
+    # Retrieves a connection from the pool, performs a POST request to the specified
+    # path with the given body, and returns the response. The connection is automatically
+    # returned to the pool unless an error occurs, in which case it's removed.
+    #
+    # @param path [String] The request path (e.g., "/users" or "/api/v1/create")
+    # @param body [String] The request body to send (default: empty string)
+    # @param headers [Hash] Optional HTTP headers to include in the request
+    # @param timeout [Float, nil] Optional timeout override in seconds. If nil, uses
+    #   the pool's default timeout.
+    # @return [Hash] Response hash with the following keys:
+    #   - `:status` [Integer] HTTP status code (e.g., 200, 201, 400, 500)
+    #   - `:body` [String] Response body
+    #   - `:headers` [Hash] Response headers
+    # @return [Hash] If an error occurs, returns a hash with `:error` and `:remove` keys
+    #
+    # @example Basic POST request
+    #   response = pool.post("/users", body: '{"name":"John"}')
+    #
+    # @example POST with JSON
+    #   response = pool.post(
+    #     "/api/users",
+    #     body: '{"name":"John","email":"john@example.com"}',
+    #     headers: { "Content-Type" => "application/json" }
+    #   )
+    #
+    # @example POST with form data
+    #   response = pool.post(
+    #     "/submit",
+    #     body: "name=John&email=john@example.com",
+    #     headers: { "Content-Type" => "application/x-www-form-urlencoded" }
+    #   )
+    def post(path, body: "", headers: {}, timeout: nil)
+      @pool.checkout(timeout: timeout) do |http|
+        http.start unless http.started?
+
+        request = Net::HTTP::Post.new(path)
+        headers.each { |k, v| request[k] = v }
+        request.body = body
+
+        response = http.request(request)
+
+        {
+          status: response.code.to_i,
+          body: response.body,
+          headers: response.to_hash
+        }
+      end
+    rescue => e
+      { error: e.message, remove: true }
+    end
+
+    # Get HTTP pool statistics.
+    #
+    # Returns statistics about the underlying connection pool, including size,
+    # available connections, in-use connections, and total connections.
+    #
+    # @return [Hash] Pool statistics hash with `:size`, `:available`, `:in_use`, and `:total` keys
+    # @see Pool#stats
+    def stats
+      @pool.stats
+    end
+
+    # Shutdown the HTTP pool gracefully.
+    #
+    # Closes all HTTP connections in the pool and prevents new requests. All
+    # connections are properly finished before being removed from the pool.
+    #
+    # @return [void]
+    # @see Pool#shutdown
+    def shutdown
+      @pool.shutdown do |http|
+        http.finish if http.started?
+      end
+    end
+  end
+end

data/lib/lean_pool/pool.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module LeanPool
+  # A lightweight, process-free resource pool implementation.
+  #
+  # Pool manages a collection of resources (connections, sockets, file handles, etc.)
+  # without creating per-resource processes. It provides thread-safe access to resources
+  # with automatic lifecycle management, timeout handling, and resource reuse.
+  #
+  # Key features:
+  # - Thread-safe resource access using concurrent-ruby
+  # - Lazy or eager resource initialization
+  # - Automatic resource cleanup and removal
+  # - Configurable timeouts for checkout operations
+  # - Resource state tracking and statistics
+  # - Graceful shutdown and reload capabilities
+  #
+  # The pool maintains a fixed maximum number of resources and automatically manages
+  # their lifecycle. Resources can be marked for removal by returning a hash with
+  # `remove: true` from the checkout block.
+  #
+  # @example Basic Redis connection pool
+  #   pool = LeanPool::Pool.new(size: 5) do
+  #     Redis.new(host: "localhost", port: 6379)
+  #   end
+  #
+  #   pool.checkout do |redis|
+  #     redis.get("key")
+  #     redis.set("key", "value")
+  #   end
+  #
+  # @example Database connection pool with custom state
+  #   pool = LeanPool::Pool.new(
+  #     size: 10,
+  #     timeout: 5.0,
+  #     lazy: true,
+  #     pool_state: { host: "localhost", port: 5432, database: "mydb" }
+  #   ) do |state|
+  #     PG.connect(
+  #       host: state[:host],
+  #       port: state[:port],
+  #       dbname: state[:database]
+  #     )
+  #   end
+  #
+  #   pool.checkout do |conn|
+  #     conn.exec("SELECT * FROM users")
+  #   end
+  #
+  # @example Removing unhealthy resources
+  #   pool.checkout do |resource|
+  #     if resource.healthy?
+  #       resource.perform_operation
+  #     else
+  #       { remove: true }  # Remove unhealthy resource from pool
+  #     end
+  #   end
+  #
+  # @example Getting pool statistics
+  #   stats = pool.stats
+  #   # => { size: 5, available: 3, in_use: 2, total: 5 }
+  #
+  # @example Graceful shutdown
+  #   pool.shutdown do |resource|
+  #     resource.close if resource.respond_to?(:close)
+  #   end
+  #
+  # @thread_safety Thread-safe. All operations use concurrent-ruby primitives
+  #   for safe concurrent access.
+  #
+  # @see https://github.com/ruby-concurrency/concurrent-ruby concurrent-ruby
+  #
+  # @since 0.1.0
+  class Pool
+    # Initialize a new resource pool.
+    #
+    # Creates a new pool with the specified configuration. Resources can be
+    # initialized eagerly (all at once) or lazily (on-demand when needed).
+    #
+    # @param size [Integer] Maximum number of resources in the pool. Must be > 0.
+    # @param timeout [Float] Default timeout in seconds for checkout operations. Must be > 0.
+    # @param lazy [Boolean] If true, resources are created on-demand when checked out.
+    #   If false, all resources are created immediately during initialization.
+    # @param pool_state [Object] Optional state object to pass to the resource initializer.
+    #   This can be any object (Hash, Struct, etc.) that contains configuration needed
+    #   to create resources.
+    # @yield [pool_state] Block that initializes a new resource
+    # @yieldparam pool_state [Object] The pool_state passed during initialization, or nil
+    # @yieldreturn [Object] The initialized resource to be managed by the pool
+    # @raise [ArgumentError] If size <= 0, timeout <= 0, or no block is provided
+    #
+    # @example Basic initialization
+    #   pool = LeanPool::Pool.new(size: 5) { MyResource.new }
+    #
+    # @example With pool state
+    #   pool = LeanPool::Pool.new(
+    #     size: 10,
+    #     pool_state: { host: "localhost", port: 6379 }
+    #   ) do |state|
+    #     Connection.new(state[:host], state[:port])
+    #   end
+    #
+    # @example Eager initialization
+    #   pool = LeanPool::Pool.new(size: 5, lazy: false) { MyResource.new }
+    #   # All 5 resources are created immediately
+    def initialize(size: 5, timeout: 5.0, lazy: true, pool_state: nil, &block)
+      raise ArgumentError, "size must be greater than 0" if size <= 0
+      raise ArgumentError, "timeout must be positive" if timeout <= 0
+      raise ArgumentError, "initializer block required" unless block_given?
+
+      @size = size
+      @timeout = timeout
+      @lazy = lazy
+      @pool_state = pool_state
+      @initializer = block
+      @shutdown = Concurrent::AtomicBoolean.new(false)
+
+      # Thread-safe collections
+      @available = Concurrent::Array.new
+      @in_use = Concurrent::Hash.new
+      @mutex = Concurrent::ReentrantReadWriteLock.new
+
+      # Initialize resources if not lazy
+      initialize_resources unless lazy
+    end
+
+    # Checkout a resource from the pool and execute a block with it.
+    #
+    # Retrieves an available resource from the pool (or creates a new one if the pool
+    # is not full and lazy initialization is enabled), executes the provided block
+    # with the resource, and then returns the resource to the pool (or removes it
+    # if indicated by the block's return value).
+    #
+    # If the pool is full and no resources are available, this method will wait up
+    # to the specified timeout for a resource to become available.
+    #
+    # The resource is automatically returned to the pool after the block executes,
+    # unless the block returns a hash with `remove: true` or `error: true`, in which
+    # case the resource is removed from the pool.
+    #
+    # @param timeout [Float, nil] Optional timeout override in seconds. If nil, uses
+    #   the pool's default timeout.
+    # @yield [resource] Block to execute with the checked out resource
+    # @yieldparam resource [Object] The checked out resource from the pool
+    # @yieldreturn [Object] Return value from the block. If a Hash with `remove: true`
+    #   or `error: true` is returned, the resource will be removed from the pool.
+    # @return [Object] The return value from the block
+    # @raise [TimeoutError] If checkout times out waiting for an available resource
+    # @raise [ShutdownError] If the pool has been shutdown
+    # @raise [ArgumentError] If no block is provided
+    # @raise [ResourceError] If resource creation fails
+    #
+    # @example Basic checkout
+    #   result = pool.checkout do |resource|
+    #     resource.perform_operation
+    #   end
+    #
+    # @example With custom timeout
+    #   pool.checkout(timeout: 2.0) do |resource|
+    #     resource.slow_operation
+    #   end
+    #
+    # @example Removing unhealthy resources
+    #   pool.checkout do |resource|
+    #     if resource.healthy?
+    #       resource.use
+    #     else
+    #       { remove: true }  # Resource will be removed
+    #     end
+    #   end
+    def checkout(timeout: nil, &block)
+      raise ShutdownError, "Pool is shutdown" if @shutdown.true?
+      raise ArgumentError, "block required" unless block_given?
+
+      timeout ||= @timeout
+      deadline = Time.now + timeout
+
+      resource = nil
+      thread_id = Thread.current.object_id
+
+      begin
+        # Try to get an available resource
+        @mutex.with_write_lock do
+          resource = @available.pop
+          
+          # Create new resource if none available and pool not full
+          if resource.nil? && @in_use.size < @size
+            resource = create_resource
+          end
+        end
+
+        # Wait for resource if pool is full
+        while resource.nil? && Time.now < deadline
+          sleep(0.01) # Small sleep to avoid busy waiting
+          
+          @mutex.with_write_lock do
+            resource = @available.pop
+            
+            # Try to create new resource if none available and pool not full
+            if resource.nil? && @in_use.size < @size
+              resource = create_resource
+            end
+          end
+        end
+
+        raise TimeoutError, "Timeout waiting for resource" if resource.nil?
+
+        # Mark resource as in use
+        @mutex.with_write_lock do
+          @in_use[thread_id] = resource
+        end
+
+        # Execute block with resource
+        result = block.call(resource)
+
+        # Check resource state and return to pool or remove
+        checkin_resource(resource, result)
+
+        result
+      rescue => e
+        # Remove resource if error occurred
+        discard_resource(resource) if resource
+        raise
+      ensure
+        # Always remove from in_use
+        @mutex.with_write_lock do
+          @in_use.delete(thread_id)
+        end
+      end
+    end
+
+    # Checkout a resource, raising on error (alias for checkout).
+    #
+    # This is an alias for {#checkout} that provides a more explicit name
+    # for operations that should raise exceptions on errors.
+    #
+    # @param timeout [Float, nil] Optional timeout override in seconds
+    # @yield [resource] Block to execute with the checked out resource
+    # @return [Object] The return value from the block
+    # @raise [TimeoutError] If checkout times out
+    # @raise [ShutdownError] If pool is shutdown
+    # @see #checkout
+    def checkout!(timeout: nil, &block)
+      checkout(timeout: timeout, &block)
+    end
+
+    # Get current pool statistics.
+    #
+    # Returns a hash containing information about the current state of the pool,
+    # including the maximum size, number of available resources, number of resources
+    # currently in use, and total number of resources.
+    #
+    # @return [Hash] Hash with the following keys:
+    #   - `:size` [Integer] Maximum number of resources in the pool
+    #   - `:available` [Integer] Number of resources currently available for checkout
+    #   - `:in_use` [Integer] Number of resources currently checked out
+    #   - `:total` [Integer] Total number of resources (available + in_use)
+    #
+    # @example
+    #   stats = pool.stats
+    #   # => { size: 5, available: 3, in_use: 2, total: 5 }
+    #
+    # @note This method is thread-safe and uses a read lock for minimal contention.
+    def stats
+      @mutex.with_read_lock do
+        {
+          size: @size,
+          available: @available.size,
+          in_use: @in_use.size,
+          total: @available.size + @in_use.size
+        }
+      end
+    end
+
+    # Shutdown the pool gracefully.
+    #
+    # Marks the pool as shutdown, preventing new checkouts, and cleans up all
+    # resources. The method will wait for in-use resources to be returned (up to
+    # the pool's timeout), then force cleanup of any remaining resources.
+    #
+    # After shutdown, all subsequent checkout attempts will raise {ShutdownError}.
+    #
+    # @param cleanup [Proc, nil] Optional block to cleanup each resource. If provided,
+    #   this block will be called for each resource. If not provided, the pool will
+    #   attempt to call common cleanup methods (`close`, `quit`, `disconnect`) if
+    #   they exist on the resource.
+    # @yield [resource] Cleanup block for each resource in the pool
+    # @return [void]
+    #
+    # @example With custom cleanup
+    #   pool.shutdown do |resource|
+    #     resource.close if resource.respond_to?(:close)
+    #     resource.cleanup if resource.respond_to?(:cleanup)
+    #   end
+    #
+    # @example Without cleanup block (uses default cleanup)
+    #   pool.shutdown
+    #
+    # @note Cleanup errors are silently ignored to ensure all resources are processed.
+    def shutdown(&cleanup)
+      @shutdown.make_true
+
+      @mutex.with_write_lock do
+        # Cleanup all available resources
+        while resource = @available.pop
+          cleanup_resource(resource, cleanup)
+        end
+
+        # Wait for in-use resources (with timeout)
+        deadline = Time.now + @timeout
+        while !@in_use.empty? && Time.now < deadline
+          sleep(0.1)
+        end
+
+        # Force cleanup remaining in-use resources
+        @in_use.each_value do |resource|
+          cleanup_resource(resource, cleanup)
+        end
+        @in_use.clear
+      end
+    end
+
+    # Reload the pool by shutting down and reinitializing.
+    #
+    # Shuts down the pool (cleaning up all existing resources), then re-enables
+    # the pool for new checkouts. If the pool was initialized with `lazy: false`,
+    # resources will be recreated immediately. Otherwise, resources will be created
+    # on-demand as before.
+    #
+    # This is useful after forking processes or when you need to reset the pool
+    # state without creating a new pool instance.
+    #
+    # @param cleanup [Proc, nil] Optional block to cleanup resources during shutdown
+    # @yield [resource] Cleanup block for each resource (passed to shutdown)
+    # @return [void]
+    #
+    # @example Reload after fork
+    #   if fork
+    #     pool.reload  # Reinitialize pool in child process
+    #   end
+    #
+    # @see #shutdown
+    def reload(&cleanup)
+      shutdown(&cleanup)
+      @shutdown.make_false
+      initialize_resources unless @lazy
+    end
+
+    private
+
+    # Initialize all resources for eager initialization.
+    #
+    # Creates the maximum number of resources and adds them to the available pool.
+    # This is called during initialization if `lazy: false`.
+    #
+    # @return [void]
+    def initialize_resources
+      @size.times do
+        resource = create_resource
+        @available << resource if resource
+      end
+    end
+
+    # Create a new resource using the initializer block.
+    #
+    # Calls the initializer block with the pool state and returns the created resource.
+    # If resource creation fails, raises a ResourceError with the original error
+    # information.
+    #
+    # @return [Object] The newly created resource
+    # @raise [ResourceError] If resource creation fails
+    def create_resource
+      begin
+        resource = @initializer.call(@pool_state)
+        # Allow nil resources (some use cases may need this)
+        resource
+      rescue => e
+        raise ResourceError, "Failed to create resource: #{e.message}", e.backtrace
+      end
+    end
+
+    # Check in a resource after use.
+    #
+    # Determines whether to return the resource to the pool or remove it based on
+    # the block's return value. If the result is a Hash with `remove: true` or
+    # `error: true`, the resource is discarded. Otherwise, it's returned to the
+    # available pool.
+    #
+    # @param resource [Object] The resource to check in
+    # @param result [Object] The return value from the checkout block
+    # @return [void]
+    def checkin_resource(resource, result)
+      should_remove = if result.is_a?(Hash)
+        result[:remove] == true
+      else
+        false
+      end
+
+      if should_remove
+        discard_resource(resource)
+      else
+        @mutex.with_write_lock do
+          @available << resource
+        end
+      end
+    end
+
+    # Discard a resource from the pool.
+    #
+    # Removes a resource from the pool. By default, this simply allows the resource
+    # to be garbage collected. Override this method in subclasses if you need
+    # explicit cleanup before discarding.
+    #
+    # @param resource [Object] The resource to discard
+    # @return [void]
+    def discard_resource(resource)
+    end
+
+    # Cleanup a resource during shutdown.
+    #
+    # Calls the provided cleanup block if given, otherwise attempts to call common
+    # cleanup methods on the resource (`close`, `quit`, `disconnect`). Errors during
+    # cleanup are silently ignored to ensure all resources are processed.
+    #
+    # @param resource [Object] The resource to cleanup
+    # @param cleanup [Proc, nil] Optional cleanup block
+    # @return [void]
+    def cleanup_resource(resource, cleanup)
+      if cleanup
+        cleanup.call(resource)
+      else
+        resource.close if resource.respond_to?(:close)
+        resource.quit if resource.respond_to?(:quit)
+        resource.disconnect if resource.respond_to?(:disconnect)
+      end
+    rescue => e
+    end
+  end
+end

data/lib/lean_pool/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LeanPool
+  # The current version of LeanPool.
+  #
+  # Follows semantic versioning (MAJOR.MINOR.PATCH):
+  # - MAJOR: Breaking changes
+  # - MINOR: New features, backwards compatible
+  # - PATCH: Bug fixes, backwards compatible
+  #
+  # @return [String] The version string (e.g., "0.1.0")
+  # @since 0.1.0
+  VERSION = "0.1.0"
+end