fiber_job 0.1.0

data/lib/fiber_job/cron_parser.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FiberJob
+  # Simple cron parser - supports basic patterns
+  # Format: [second] minute hour day month weekday
+  # Examples: "*/30 * * * * *" (every 30 sec), "0 2 * * *" (daily 2am)
+  class CronParser
+    def self.next_run(cron_expression, from_time = Time.now)
+      fields = cron_expression.split
+
+      if fields.length == 6
+        # 6-field format: second minute hour day month weekday
+        second, minute, hour, day, month, weekday = fields
+        current = from_time + 1 # Start from next second
+        current = Time.new(current.year, current.month, current.day, current.hour, current.min, current.sec)
+        increment = 1
+        max_iterations = 86_400 # 24 hours in seconds
+      elsif fields.length == 5
+        # 5-field format: minute hour day month weekday
+        minute, hour, day, month, weekday = fields
+        second = nil
+        current = from_time + 60 # Start from next minute
+        current = Time.new(current.year, current.month, current.day, current.hour, current.min, 0)
+        increment = 60
+        max_iterations = 1440 # 24 hours in minutes
+      else
+        raise "Invalid cron expression: #{cron_expression}. Must have 5 or 6 fields."
+      end
+
+      # Simple implementation - find next matching time
+      max_iterations.times do
+        if matches?(current, second, minute, hour, day, month, weekday)
+          return current
+        end
+        current += increment
+      end
+
+      raise "No matching time found for cron expression: #{cron_expression}"
+    end
+
+    private
+
+    def self.matches?(time, second, minute, hour, day, month, weekday)
+      (second.nil? || match_field?(time.sec, second)) &&
+        match_field?(time.min, minute) &&
+        match_field?(time.hour, hour) &&
+        match_field?(time.day, day) &&
+        match_field?(time.month, month) &&
+        match_field?(time.wday, weekday)
+    end
+
+    def self.match_field?(value, pattern)
+      return true if pattern == '*'
+
+      if pattern.start_with?('*/')
+        # Handle */5 pattern
+        interval = pattern[2..-1].to_i
+        return (value % interval) == 0
+      end
+
+      # Handle exact match
+      return value == pattern.to_i
+    end
+  end
+end

data/lib/fiber_job/job.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module FiberJob
+  # Base class for all background jobs in the FiberJob system.
+  # Provides interface for job execution, retry logic, and scheduling capabilities.
+  #
+  # All job classes should inherit from this class and implement the {#perform} method
+  # to define their specific behavior.
+  #
+  # @example Basic job definition
+  #   class EmailJob < FiberJob::Job
+  #     def perform(user_id, message)
+  #       user = User.find(user_id)
+  #       UserMailer.notification(user, message).deliver_now
+  #     end
+  #   end
+  #
+  # @example Job with custom configuration
+  #   class ComplexJob < FiberJob::Job
+  #     def initialize
+  #       super
+  #       @queue = :high_priority
+  #       @max_retries = 5
+  #       @timeout = 600  # 10 minutes
+  #     end
+  #
+  #     def perform(data)
+  #       # Complex processing logic
+  #     end
+  #
+  #     def retry_delay(attempt)
+  #       attempt * 60  # Linear backoff: 1min, 2min, 3min...
+  #     end
+  #   end
+  class Job
+    # @!attribute [rw] queue
+    #   @return [Symbol] The queue name where this job will be processed
+    # @!attribute [rw] retry_count
+    #   @return [Integer] Current number of retry attempts
+    # @!attribute [rw] max_retries
+    #   @return [Integer] Maximum number of retry attempts before giving up
+    # @!attribute [rw] priority
+    #   @return [Integer] Job priority (higher numbers = higher priority)
+    # @!attribute [rw] timeout
+    #   @return [Integer] Maximum execution time in seconds before timeout
+    attr_accessor :queue, :retry_count, :max_retries, :priority, :timeout
+
+    # Initializes a new job instance with default configuration.
+    # Sets reasonable defaults for queue, retries, and timeout values.
+    #
+    # @return [void]
+    def initialize
+      @queue = :default
+      @retry_count = 0
+      @max_retries = 3
+      @priority = 0
+      @timeout = 300 # 5 minutes
+    end
+
+    # Executes the job with the provided arguments.
+    # This method must be implemented by all job subclasses.
+    #
+    # @param args [Array] Arguments passed to the job
+    # @raise [NotImplementedError] When called on the base Job class
+    # @return [void]
+    # @abstract Subclasses must implement this method
+    #
+    # @example Implementation in subclass
+    #   def perform(user_id, message)
+    #     user = User.find(user_id)
+    #     # Process the job...
+    #   end
+    def perform(*args)
+      raise NotImplementedError, 'Subclasses must implement perform'
+    end
+
+    # Calculates the delay before retrying a failed job.
+    # Uses exponential backoff with random jitter by default.
+    #
+    # @param attempt [Integer] The current retry attempt number (0-based)
+    # @return [Integer] Delay in seconds before retry
+    #
+    # @example Custom retry delay
+    #   def retry_delay(attempt)
+    #     [30, 60, 120, 300][attempt] || 300  # Fixed intervals
+    #   end
+    def retry_delay(attempt)
+      # Default exponential backoff: 2^attempt + random jitter
+      (2 ** attempt) + rand(10)
+    end
+
+    # Determines if failed jobs should be retried with priority.
+    # Priority retries are processed before regular jobs in the queue.
+    #
+    # @return [Boolean] Whether to use priority retry queue
+    def priority_retry?
+      true
+    end
+
+    # Returns the queue name for this job class.
+    # Creates a temporary instance to get the configured queue name.
+    #
+    # @return [Symbol] The queue name where jobs of this class will be processed
+    def self.queue
+      new.queue
+    end
+
+    # Enqueues the job for immediate asynchronous execution.
+    #
+    # @param args [Array] Arguments to pass to the job's perform method
+    # @return [String] Job ID for tracking
+    #
+    # @example Enqueue a job
+    #   EmailJob.perform_async(user.id, "Welcome message")
+    def self.perform_async(*args)
+      Client.enqueue(self, *args)
+    end
+
+    # Enqueues the job for execution after a specified delay.
+    #
+    # @param delay [Numeric] Delay in seconds before execution
+    # @param args [Array] Arguments to pass to the job's perform method
+    # @return [String] Job ID for tracking
+    #
+    # @example Enqueue with delay
+    #   EmailJob.perform_in(3600, user.id, "Reminder message")  # 1 hour delay
+    def self.perform_in(delay, *args)
+      Client.enqueue_in(delay, self, *args)
+    end
+
+    # Enqueues the job for execution at a specific time.
+    #
+    # @param time [Time, Integer] Specific time or timestamp for execution
+    # @param args [Array] Arguments to pass to the job's perform method
+    # @return [String] Job ID for tracking
+    #
+    # @example Enqueue at specific time
+    #   EmailJob.perform_at(tomorrow_9am, user.id, "Daily summary")
+    def self.perform_at(time, *args)
+      Client.enqueue_at(time, self, *args)
+    end
+  end
+end

data/lib/fiber_job/logger.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FiberJob
+  # Logger provides structured logging for FiberJob operations.
+  # Wraps the configured logger and provides level-based filtering
+  # and FiberJob-specific formatting.
+  #
+  # The logger respects the configured log level and only outputs
+  # messages at or above the current threshold.
+  #
+  # @example Using the logger
+  #   FiberJob.logger.info("Job processing started")
+  #   FiberJob.logger.error("Job failed: #{error.message}")
+  #   FiberJob.logger.debug("Processing queue: #{queue_name}")
+  #
+  # @see FiberJob::Config
+  class Logger
+    # Log level hierarchy for filtering messages.
+    # Lower numbers indicate more verbose logging.
+    LOG_LEVELS = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      fatal: 4
+    }.freeze
+
+    # Initializes the logger with configuration settings.
+    #
+    # @param config [FiberJob::Config] Configuration object containing log level and logger instance
+    def initialize(config)
+      @config = config
+      @level = LOG_LEVELS[@config.log_level.to_sym] || LOG_LEVELS[:info]
+    end
+
+    # Logs a debug message if debug level is enabled.
+    # Used for detailed diagnostic information.
+    #
+    # @param message [String] The message to log
+    # @return [void]
+    #
+    # @example Debug logging
+    #   FiberJob.logger.debug("Processing job #{job.class.name} with args: #{args.inspect}")
+    def debug(message)
+      log(:debug, message)
+    end
+
+    # Logs an info message if info level is enabled.
+    # Used for general operational messages.
+    #
+    # @param message [String] The message to log
+    # @return [void]
+    #
+    # @example Info logging
+    #   FiberJob.logger.info("Worker started processing queue: #{queue_name}")
+    def info(message)
+      log(:info, message)
+    end
+
+    # Logs a warning message if warn level is enabled.
+    # Used for concerning but non-fatal conditions.
+    #
+    # @param message [String] The message to log
+    # @return [void]
+    #
+    # @example Warning logging
+    #   FiberJob.logger.warn("Queue #{queue_name} is getting full")
+    def warn(message)
+      log(:warn, message)
+    end
+
+    # Logs an error message if error level is enabled.
+    # Used for error conditions and exceptions.
+    #
+    # @param message [String] The message to log
+    # @return [void]
+    #
+    # @example Error logging
+    #   FiberJob.logger.error("Job failed: #{error.class.name} - #{error.message}")
+    def error(message)
+      log(:error, message)
+    end
+
+    # Logs a fatal message if fatal level is enabled.
+    # Used for severe error conditions that may terminate the process.
+    #
+    # @param message [String] The message to log
+    # @return [void]
+    #
+    # @example Fatal logging
+    #   FiberJob.logger.fatal("Unable to connect to Redis, shutting down")
+    def fatal(message)
+      log(:fatal, message)
+    end
+
+    private
+
+    # Internal logging method that checks level and delegates to configured logger.
+    #
+    # @param level [Symbol] The log level
+    # @param message [String] The message to log
+    # @return [void]
+    def log(level, message)
+      return unless should_log?(level)
+
+      @config.logger.send(level, message)
+    end
+
+    # Determines if a message should be logged based on current log level.
+    #
+    # @param level [Symbol] The level to check
+    # @return [Boolean] Whether the message should be logged
+    def should_log?(level)
+      LOG_LEVELS[level] >= @level
+    end
+  end
+end

data/lib/fiber_job/process_manager.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FiberJob
+  # ProcessManager is responsible for managing the lifecycle of workers
+  # and ensuring they run with the correct configuration.
+  class ProcessManager
+    def self.start_worker(queues: nil, concurrency: nil)
+      queues ||= FiberJob.config.queues
+      concurrency ||= FiberJob.config.concurrency
+      worker = Worker.new(queues: queues, concurrency: concurrency)
+
+      trap('INT') { worker.stop }
+      trap('TERM') { worker.stop }
+
+      worker.start
+    end
+  end
+end

data/lib/fiber_job/queue.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'redis'
+
+module FiberJob
+  # Queue provides Redis-based queue operations for job storage and retrieval.
+  # Handles immediate execution queues, scheduled jobs, priority handling,
+  # and failure tracking using Redis data structures.
+  #
+  # The queue system uses Redis lists for immediate jobs, sorted sets for
+  # scheduled jobs, and separate lists for failed job tracking.
+  #
+  # @example Basic queue operations
+  #   # Push a job to queue
+  #   FiberJob::Queue.push(:default, job_data)
+  #
+  #   # Pop a job from queue
+  #   job = FiberJob::Queue.pop(:default, timeout: 1.0)
+  #
+  #   # Schedule a job for later
+  #   FiberJob::Queue.schedule(:default, job_data, Time.now.to_f + 3600)
+  #
+  # @example Queue statistics
+  #   stats = FiberJob::Queue.stats(:default)
+  #   puts "Queue size: #{stats[:size]}"
+  #   puts "Scheduled jobs: #{stats[:scheduled]}"
+  #
+  # @see FiberJob::Worker
+  class Queue
+    # Returns the shared Redis connection instance.
+    # Creates a new connection if one doesn't exist.
+    #
+    # @return [Redis] The shared Redis connection
+    def self.redis
+      @redis ||= Redis.new(url: FiberJob.config.redis_url)
+    end
+
+    # Creates a new Redis connection for fiber-safe operations.
+    # Used when concurrent operations need separate connections.
+    #
+    # @return [Redis] A new Redis connection instance
+    def self.redis_connection
+      # Create a new Redis connection for fiber-safe operations
+      Redis.new(url: FiberJob.config.redis_url)
+    end
+
+    # Adds a job to the specified queue for immediate processing.
+    # Jobs are added to the left side of the list (LPUSH) and processed
+    # from the right side (BRPOP) implementing FIFO behavior.
+    #
+    # @param queue_name [String, Symbol] Name of the target queue
+    # @param payload [Hash] Job data including class, args, and metadata
+    # @return [Integer] The length of the queue after push
+    #
+    # @example Push a job
+    #   payload = { 'class' => 'EmailJob', 'args' => [123, 'message'] }
+    #   FiberJob::Queue.push(:default, payload)
+    def self.push(queue_name, payload)
+      redis.lpush("queue:#{queue_name}", JSON.dump(payload))
+    end
+
+    # Adds a job to the head of the queue for priority processing.
+    # Priority jobs are processed before regular jobs in the same queue.
+    #
+    # @param queue_name [String, Symbol] Name of the target queue
+    # @param payload [Hash] Job data including class, args, and metadata
+    # @return [Integer] The length of the queue after push
+    #
+    # @example Push priority job
+    #   FiberJob::Queue.push_priority(:default, urgent_job_data)
+    def self.push_priority(queue_name, payload)
+      # Add to the head of the queue for priority execution
+      redis.rpush("queue:#{queue_name}", JSON.dump(payload))
+    end
+
+    # Removes and returns a job from the specified queue.
+    # Blocks for the specified timeout waiting for jobs to become available.
+    #
+    # @param queue_name [String, Symbol] Name of the source queue
+    # @param timeout [Float] Maximum time to wait for a job (default: 0.1)
+    # @param redis_conn [Redis, nil] Optional Redis connection to use
+    # @return [Hash, nil] Job data hash or nil if timeout reached
+    #
+    # @example Pop from queue with timeout
+    #   job = FiberJob::Queue.pop(:default, timeout: 5.0)
+    #   if job
+    #     puts "Processing job: #{job['class']}"
+    #   end
+    def self.pop(queue_name, timeout: 0.1, redis_conn: nil)
+      conn = redis_conn || redis
+      data = conn.brpop("queue:#{queue_name}", timeout: timeout)
+      data ? JSON.parse(data[1]) : nil
+    end
+
+    # Schedules a job for execution at a specific time.
+    # Uses Redis sorted sets with timestamp as score for efficient
+    # time-based retrieval.
+    #
+    # @param queue_name [String, Symbol] Name of the target queue
+    # @param payload [Hash] Job data including class, args, and metadata
+    # @param scheduled_at [Float] Unix timestamp for execution
+    # @return [Boolean] True if job was added to schedule
+    #
+    # @example Schedule a job
+    #   future_time = Time.now.to_f + 3600  # 1 hour from now
+    #   FiberJob::Queue.schedule(:default, job_data, future_time)
+    def self.schedule(queue_name, payload, scheduled_at)
+      redis.zadd("schedule:#{queue_name}", scheduled_at, JSON.dump(payload))
+    end
+
+    # Schedules a job with priority for execution at a specific time.
+    # Priority scheduled jobs are moved to the head of the queue when ready.
+    #
+    # @param queue_name [String, Symbol] Name of the target queue
+    # @param payload [Hash] Job data including class, args, and metadata
+    # @param scheduled_at [Float] Unix timestamp for execution
+    # @return [Boolean] True if job was added to schedule
+    def self.schedule_priority(queue_name, payload, scheduled_at)
+      # Mark as priority retry for head-of-queue execution
+      priority_payload = payload.merge('priority_retry' => true)
+      redis.zadd("schedule:#{queue_name}", scheduled_at, JSON.dump(priority_payload))
+    end
+
+    # Processes scheduled jobs that are ready for execution.
+    # Moves jobs from the scheduled set to the appropriate queue
+    # when their scheduled time has arrived.
+    #
+    # @param queue_name [String, Symbol] Name of the queue to process
+    # @return [void]
+    #
+    # @example Process scheduled jobs
+    #   FiberJob::Queue.scheduled_jobs(:default)  # Called by workers
+    def self.scheduled_jobs(queue_name)
+      now = Time.now.to_f
+      jobs = redis.zrangebyscore("schedule:#{queue_name}", 0, now)
+
+      jobs.each do |job_json|
+        redis.zrem("schedule:#{queue_name}", job_json)
+        job_data = JSON.parse(job_json)
+
+        # Use priority queue for retries
+        if job_data['priority_retry']
+          job_data.delete('priority_retry') # Clean up the flag
+          push_priority(queue_name, job_data)
+        else
+          push(queue_name, job_data)
+        end
+      end
+    end
+
+    # Returns statistics for the specified queue.
+    # Provides insight into queue depth, scheduled jobs, and processing status.
+    #
+    # @param queue_name [String, Symbol] Name of the queue
+    # @return [Hash] Statistics hash with :size, :scheduled, and :processing keys
+    #
+    # @example Get queue statistics
+    #   stats = FiberJob::Queue.stats(:default)
+    #   puts "Pending: #{stats[:size]}, Scheduled: #{stats[:scheduled]}"
+    def self.stats(queue_name)
+      {
+        size: redis.llen("queue:#{queue_name}"),
+        scheduled: redis.zcard("schedule:#{queue_name}"),
+        processing: redis.get("processing:#{queue_name}").to_i
+      }
+    end
+
+    # Stores a failed job with error information for later analysis.
+    # Failed jobs are stored with original job data plus failure metadata.
+    #
+    # @param job_data [Hash] Original job data
+    # @param error [Exception] The error that caused the failure
+    # @return [Integer] Length of failed jobs list after storage
+    #
+    # @example Store failed job
+    #   begin
+    #     job.perform
+    #   rescue => e
+    #     FiberJob::Queue.store_failed_job(job_data, e)
+    #   end
+    def self.store_failed_job(job_data, error)
+      failed_job_data = job_data.merge({
+        'failed_at' => Time.now.to_f,
+        'error' => error.message,
+        'backtrace' => error.backtrace&.first(10)
+      })
+      redis.lpush("failed", JSON.dump(failed_job_data))
+    end
+
+    # Retrieves all failed jobs for inspection and debugging.
+    #
+    # @return [Array<Hash>] Array of failed job data hashes
+    #
+    # @example Get failed jobs
+    #   failed = FiberJob::Queue.failed_jobs
+    #   failed.each { |job| puts "Failed: #{job['class']} - #{job['error']}" }
+    def self.failed_jobs
+      redis.lrange("failed", 0, -1).map { |job_json| JSON.parse(job_json) }
+    end
+  end
+end

data/lib/fiber_job/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FiberJob
+  VERSION = "0.1.0"
+end