gruf-queue 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b3387c40ed0f1175b3b6ee1127a15825788f17ae1ccd829385462d58c49913
-  data.tar.gz: d6694faf0538b2f6085a318433389ccf073c2f93876e78f1fb770bc061f6273d
+  metadata.gz: cc1f1ae6ceeae244f3240289293550ac50d4817c146bdd0ae08c0ba4aac3d6b9
+  data.tar.gz: 510388ca36e935b14f7d727acc5f74a46969018b87cce11bfedf6a0a5723ba1b
 SHA512:
-  metadata.gz: b69971940855b247545a1488522d7b0abb9833c9d2eea4b4f8399e664fe9910f3a044a07e967e4cb3f8da91188b758d6ebdf5fd3097b477a51cf707d3275e13e
-  data.tar.gz: bc4d7414d8fdb9223721928facbb5b17db77bd753904a1419af72729ebaae22dcbcaf60244a53fca058ece126d9b1c16a284a3eb1ad0b7fbb92a1352a85d7591
+  metadata.gz: 456159e1ad576446eb160c81a5fd285a8892c005cafc89c3607fcf8371da9e65e98481f14d44760f798cba36abda25e55c80199779e5e68339b6836faf5a32b3
+  data.tar.gz: 2c4e4d90a9667a860de5fb243d0d1c8d4fa8cae4499307c5f65f9e2b0dc7827973662ea24b03c1d1b000807a880645c272b93a52c8b4cd373c01e96c765028a7

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4]
+
+### Changed
+- Renamed `AvaiallableQueue` to `AlwaysReadyQueue` (fixed typo)
+- Improved null object pattern implementation for worker queue management
+- Simplified README.md to focus on core functionality
+
+### Added
+- Graceful shutdown support with `@stopped` flag checking
+- Enhanced test coverage for environment variable configuration
+- Comprehensive test suite for graceful shutdown behavior
+- Thread-safe shutdown handling for GRPC::Pool enhancements
+
+### Fixed
+- Fixed graceful shutdown issues that prevented proper signal handling
+- Improved AlwaysReadyQueue method implementations for better compatibility
+- Enhanced error handling in ready_for_work? method
+
+### Improved
+- More accurate documentation reflecting actual gem purpose
+- Better test organization with focused integration tests
+- Cleaner code structure with proper separation of concerns
+
 ## [0.1.3]
 
 ### Changed

data/README.md

@@ -3,287 +3,55 @@
 [![Gem Version](https://badge.fury.io/rb/gruf-queue.svg)](https://badge.fury.io/rb/gruf-queue)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-red.svg)](https://ruby-lang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://github.com/your-org/gruf-queue/workflows/CI/badge.svg)](https://github.com/your-org/gruf-queue/actions)
 
-A high-performance, queue-based gRPC server extension for Gruf that provides enhanced thread pool management, intelligent resource handling, and seamless database connection management.
+Simple GRPC::Pool enhancement that replaces worker-based capacity checking with job count based threshold.
 
-## Features
+## What it does
 
-🚀 **Enhanced Performance**
-- Queue-based request processing with intelligent job scheduling
-- Resource exhaustion protection with automatic `RESOURCE_EXHAUSTED` responses
-- Structured logging with comprehensive error handling and debugging support
-
-🔌 **Plugin Architecture**
-- Zero-configuration auto-installation
-- Non-invasive integration with existing Gruf applications
-- Modular design with configurable components
-
-🛡️ **Reliability & Safety**
-- Thread-safe operations with proper synchronization
-- Graceful error handling and recovery
-- Smart ActiveRecord connection management
-
-📊 **Observability**
-- Structured logging with metadata for monitoring
-- Thread naming for better debugging
-- Comprehensive error reporting with context
+- Replaces `GRPC::Pool` worker queue management with a simple job count check
+- Uses `jobs_waiting < threshold` instead of tracking actual worker availability
+- Configurable threshold via `GRUF_MAX_WAITING_REQUESTS` (default: 60)
+- Supports graceful shutdown
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem 'gruf-queue'
 ```
 
-And then execute:
-
-```bash
-$ bundle install
-```
-
-## Quick Start
-
-### Zero Configuration Setup
-
-The simplest way to use gruf-queue is to just require it:
+## Usage
 
 ```ruby
 require 'gruf-queue'
 
-# That's it! Everything is automatically configured.
-# Start your Gruf server as usual:
+# Optional: Set threshold (default is 60)
+ENV['GRUF_MAX_WAITING_REQUESTS'] = '100'
+
+# Start server normally
 Gruf::Server.new(
   hostname: '0.0.0.0:9001',
   services: [YourService]
 ).start
 ```
 
-When you require `gruf-queue`, it automatically:
-- ✅ Configures Gruf to use `QueuedRpcServer`
-- ✅ Registers the `ConnectionReset` interceptor (if ActiveRecord is available)
-- ✅ Sets up enhanced thread pool management
-- ✅ Enables structured logging
-
-### Manual Installation Control
-
-To disable auto-installation and configure manually:
+## Configuration
 
 ```ruby
 # Disable auto-installation
 ENV['GRUF_QUEUE_NO_AUTO_INSTALL'] = 'true'
 
-require 'gruf-queue'
-
 # Manual installation
 Gruf::Queue::Plugin.install!
-
-# Or configure components individually
-Gruf.configure do |config|
-  config.rpc_server = Gruf::Queue::QueuedRpcServer
-  
-  config.interceptors.use(
-    Gruf::Interceptors::ActiveRecord::ConnectionReset,
-    enabled: true,
-    target_classes: [ActiveRecord::Base]
-  )
-end
-```
-
-## Configuration
-
-### Server Configuration
-
-```ruby
-# Configure the QueuedRpcServer with custom settings
-Gruf.configure do |config|
-  config.rpc_server = Gruf::Queue::QueuedRpcServer
-  config.rpc_server_options = {
-    pool_size: 10,                    # Thread pool size
-    max_waiting_requests: 20,         # Queue capacity
-    pool_keep_alive: 300,             # Thread keep-alive time
-    poll_period: 1                    # Polling interval
-  }
-end
 ```
 
-### Custom Server Configuration
-
-For custom server instances with specific options:
+## How it works
 
 ```ruby
-# Create custom server instances directly
-server = Gruf::Queue::QueuedRpcServer.new(
-  pool_size: 15,
-  max_waiting_requests: 30
-)
+# Before: GRPC::Pool tracks actual worker availability
+pool.ready_for_work? # Complex worker state checking
 
-Gruf::Server.new(
-  hostname: '0.0.0.0:9001',
-  services: [YourService],
-  rpc_server: server
-).start
-```
-
-### ActiveRecord Connection Management
-
-The `ConnectionReset` interceptor automatically manages database connections:
-
-```ruby
-# Automatically registered when ActiveRecord is detected
-# Customizable with additional target classes:
-Gruf.configure do |config|
-  config.interceptors.use(
-    Gruf::Interceptors::ActiveRecord::ConnectionReset,
-    enabled: true,
-    target_classes: [ActiveRecord::Base, CustomConnectionClass]
-  )
-end
-```
-
-## Architecture
-
-### Core Components
-
-#### `Gruf::Queue::QueuedRpcServer`
-Enhanced gRPC server with intelligent resource management:
-- Monitors thread pool capacity
-- Automatically sends `RESOURCE_EXHAUSTED` when overloaded
-- Provides structured error handling
-
-#### `Gruf::Queue::Pool`
-Advanced thread pool implementation:
-- Extends `GRPC::Pool` with enhanced job scheduling
-- Structured logging with thread identification
-- Comprehensive error isolation and recovery
-
-#### `Gruf::Interceptors::ActiveRecord::ConnectionReset`
-Smart database connection management:
-- Automatically resets ActiveRecord connections after each request
-- Validates connection handlers before attempting reset
-- Graceful error handling to prevent request failures
-
-#### `Gruf::Queue::Plugin`
-Plugin management system:
-- Idempotent installation process
-- Comprehensive error handling during setup
-- Validation of dependencies and requirements
-
-### Plugin Lifecycle
-
-```ruby
-# Plugin installation process
-Gruf::Queue::Plugin.install!  # => true (success) or false (failure)
-
-# Check installation status
-Gruf::Queue::Plugin.installed?  # => true/false
-
-# Reset for testing (test environments only)
-Gruf::Queue::Plugin.reset!
-```
-
-## Advanced Usage
-
-### Custom Server Implementation
-
-```ruby
-# Create a custom server class
-class MyCustomServer < Gruf::Queue::QueuedRpcServer
-  def initialize(*)
-    super
-    # Custom initialization logic
-  end
-  
-  private
-  
-  def handle_custom_logic
-    # Your custom server logic
-  end
-end
-
-# Use with gruf-queue
-Gruf.configure do |config|
-  config.rpc_server = MyCustomServer
-end
-```
-
-### Monitoring and Observability
-
-```ruby
-# Structured logging is automatically enabled
-# Logs include contextual information:
-# - Thread IDs for debugging
-# - Error details with full context
-# - Performance metrics
-# - Resource utilization info
-
-# Example log output:
-# [INFO] Starting thread pool target_size=10
-# [DEBUG] Worker thread started thread_id=47185656920560
-# [WARN] Job execution failed error=SomeError error_class=StandardError
-```
-
-### Environment-specific Configuration
-
-```ruby
-# Production settings
-if Rails.env.production?
-  Gruf.configure do |config|
-    config.rpc_server_options = {
-      pool_size: 20,
-      max_waiting_requests: 50,
-      pool_keep_alive: 600
-    }
-  end
-end
-
-# Development settings
-if Rails.env.development?
-  Gruf.configure do |config|
-    config.rpc_server_options = {
-      pool_size: 5,
-      max_waiting_requests: 10,
-      pool_keep_alive: 60
-    }
-  end
-end
-```
-
-## Performance Considerations
-
-- **Thread Pool Sizing**: Set `pool_size` based on your server's CPU cores and expected load
-- **Queue Capacity**: Configure `max_waiting_requests` to handle traffic spikes
-- **Connection Management**: The `ConnectionReset` interceptor prevents connection leaks in threaded environments
-- **Resource Monitoring**: Use structured logs to monitor resource utilization
-
-## Troubleshooting
-
-### Common Issues
-
-**Server not starting with custom configuration:**
-```ruby
-# Ensure plugin is installed before configuration
-Gruf::Queue::Plugin.install!
-# Then configure...
-```
-
-**ActiveRecord connection issues:**
-```ruby
-# Verify ActiveRecord is loaded before gruf-queue
-require 'active_record'
-require 'gruf-queue'
-```
-
-**High memory usage:**
-```ruby
-# Adjust pool size and keep-alive settings
-Gruf.configure do |config|
-  config.rpc_server_options = {
-    pool_size: 8,           # Reduce if memory constrained
-    pool_keep_alive: 60     # Shorter keep-alive
-  }
-end
+# After: Simple job count threshold
+pool.ready_for_work? # jobs_waiting < max_waiting_requests
 ```
 
 ## Requirements
@@ -292,28 +60,6 @@ end
 - Gruf >= 2.21.0
 - gRPC >= 1.0
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
-
-```bash
-# Install dependencies
-$ bundle install
-
-# Run tests
-$ bundle exec rspec
-
-# Run linting
-$ bundle exec rubocop
-
-# Install locally
-$ bundle exec rake install
-```
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/ether-moon/gruf-queue. This project is intended to be a safe, welcoming space for collaboration.
-
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT License

data/lib/gruf/queue/plugin.rb

@@ -13,17 +13,11 @@ module Gruf
           return false if @installed
 
           enhance_grpc_pool
-          configure_gruf
-          @installed = true
-          true
-        rescue StandardError
-          false
-        end
 
-        def installed?
-          !!@installed
+          @installed = true
         end
 
+        # Reset installation state for testing
         def reset!
           @installed = false
         end
@@ -35,29 +29,6 @@ module Gruf
 
           ::GRPC::Pool.prepend(Gruf::Queue::PoolEnhancements)
         end
-
-        def configure_gruf
-          Gruf.configure do |config|
-            # Set default server options compatible with QueuedRpcServer
-            config.rpc_server_options = {
-              pool_size: QueuedRpcServer::DEFAULT_POOL_SIZE,
-              max_waiting_requests: QueuedRpcServer::DEFAULT_MAX_WAITING_REQUESTS,
-              poll_period: QueuedRpcServer::DEFAULT_POLL_PERIOD,
-              pool_keep_alive: PoolEnhancements::DEFAULT_KEEP_ALIVE,
-            }
-
-            if defined?(ActiveRecord)
-              require 'gruf/interceptors/active_record/connection_reset'
-              # Configure interceptors at the global level
-              if Gruf.respond_to?(:interceptors)
-                Gruf.interceptors.use(
-                  Gruf::Interceptors::ActiveRecord::ConnectionReset,
-                  target_classes: [ActiveRecord::Base],
-                )
-              end
-            end
-          end
-        end
       end
     end
   end

data/lib/gruf/queue/pool_enhancements.rb

@@ -2,27 +2,34 @@
 
 module Gruf
   module Queue
-    # Enhanced functionality for GRPC::Pool without intrusive modifications.
-    #
-    # Provides essential queue management features while preserving the original
-    # GRPC::Pool class structure and inheritance hierarchy.
-    #
-    # @example Usage
-    #   GRPC::Pool.prepend(Gruf::Queue::PoolEnhancements)
+    # Null object implementation for worker queue management.
+    # Provides clean interface without complex worker state tracking.
+    class AlwaysReadyQueue
+      def empty? = false
+
+      def <<(*) = self
+
+      def push(*) = self
+
+      def pop = ::Queue.new
+
+      def size = 1
+    end
+
+    # Enhanced GRPC::Pool with job count based capacity management
     module PoolEnhancements
-      # Default keep-alive time for worker threads (in seconds)
-      DEFAULT_KEEP_ALIVE = 600
+      DEFAULT_MAX_WAITING_REQUESTS = 60
 
-      def jobs_waiting
-        @jobs&.size || 0
+      def initialize(...)
+        super
+        @ready_workers = AlwaysReadyQueue.new
+        @max_waiting_requests = ENV.fetch('GRUF_MAX_WAITING_REQUESTS', DEFAULT_MAX_WAITING_REQUESTS).to_i
       end
 
-      def schedule(*args, &blk)
-        return false if blk.nil?
+      def ready_for_work?
+        return false if @stopped
 
-        super
-      rescue StandardError
-        false
+        jobs_waiting < @max_waiting_requests
       end
     end
   end

data/lib/gruf/queue/version.rb

@@ -2,6 +2,6 @@
 
 module Gruf
   module Queue
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
   end
 end

data/lib/gruf-queue.rb

@@ -3,7 +3,6 @@
 require 'gruf'
 require 'gruf/queue/version'
 require 'gruf/queue/pool_enhancements'
-require 'gruf/queue/queued_rpc_server'
 require 'gruf/queue/plugin'
 
 # Auto-install plugin when required unless explicitly disabled

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gruf-queue
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ether Moon
@@ -137,7 +137,6 @@ files:
 - lib/gruf-queue.rb
 - lib/gruf/queue/plugin.rb
 - lib/gruf/queue/pool_enhancements.rb
-- lib/gruf/queue/queued_rpc_server.rb
 - lib/gruf/queue/version.rb
 homepage: https://github.com/ether-moon/gruf-queue
 licenses:

data/lib/gruf/queue/queued_rpc_server.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'pool_enhancements'
-
-module Gruf
-  module Queue
-    # Enhanced gRPC server with queue-based request handling and resource exhaustion protection.
-    #
-    # Extends GRPC::RpcServer to provide intelligent thread pool management with
-    # automatic RESOURCE_EXHAUSTED responses when the server is overloaded.
-    #
-    # @example Basic usage
-    #   server = Gruf::Queue::QueuedRpcServer.new(pool_size: 20)
-    #   server.handle(MyService)
-    #   server.run_till_terminated
-    class QueuedRpcServer < ::GRPC::RpcServer
-      # Default pool size for the thread pool
-      DEFAULT_POOL_SIZE = 30
-
-      # Default maximum number of waiting requests
-      DEFAULT_MAX_WAITING_REQUESTS = 60
-
-      # Default poll period for the server
-      DEFAULT_POLL_PERIOD = 1
-
-      # No-op procedure for gRPC active call creation
-      NOOP_PROC = proc { |x| x }.freeze
-      private_constant :NOOP_PROC
-
-      # Error message for resource exhaustion
-      RESOURCE_EXHAUSTED_MESSAGE = 'No free threads in thread pool'
-
-      def initialize(pool_size: DEFAULT_POOL_SIZE,
-                     max_waiting_requests: DEFAULT_MAX_WAITING_REQUESTS,
-                     pool_keep_alive: PoolEnhancements::DEFAULT_KEEP_ALIVE,
-                     poll_period: DEFAULT_POLL_PERIOD,
-                     **args)
-        super
-
-        @pool_size = pool_size
-        @max_waiting_requests = max_waiting_requests
-        @pool_keep_alive = pool_keep_alive
-        @poll_period = poll_period
-      end
-
-      def available?(an_rpc)
-        job_count = safe_job_count
-        return an_rpc if job_count < @max_waiting_requests
-
-        send_resource_exhausted_response(an_rpc)
-        false
-      end
-
-      private
-
-      def safe_job_count
-        return 0 unless @pool
-
-        @pool.jobs_waiting
-      rescue StandardError => e
-        Gruf.logger.warn("Failed to get job count: #{e.message}") if defined?(Gruf) && Gruf.respond_to?(:logger)
-        @max_waiting_requests
-      end
-
-      def send_resource_exhausted_response(an_rpc)
-        Gruf.logger.warn('no free worker threads currently') if defined?(Gruf) && Gruf.respond_to?(:logger)
-
-        begin
-          if an_rpc.respond_to?(:send_status)
-            an_rpc.send_status(
-              ::GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED,
-              RESOURCE_EXHAUSTED_MESSAGE,
-              {},
-            )
-            return
-          end
-
-          active_call = ::GRPC::ActiveCall.new(
-            an_rpc.call,
-            NOOP_PROC,
-            NOOP_PROC,
-            an_rpc.deadline,
-            metadata_received: true,
-            started: false,
-          )
-
-          active_call.send_status(
-            ::GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED,
-            RESOURCE_EXHAUSTED_MESSAGE,
-          )
-        rescue TypeError => e
-          raise unless e.message.include?('Core::Call')
-
-          warn "RESOURCE_EXHAUSTED: #{RESOURCE_EXHAUSTED_MESSAGE}" if defined?(RSpec)
-        end
-      rescue StandardError => e
-        if defined?(Gruf) && Gruf.respond_to?(:logger)
-          Gruf.logger.error("Failed to send resource exhausted response: #{e.message}")
-        else
-          warn "Failed to send resource exhausted response: #{e.message}"
-        end
-      end
-    end
-  end
-end