sumologic-query 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b3c5ddcf5c4b6bc30c0c13cad3068b36a75ee8bd32ba2ce80254cc5c8768d28
-  data.tar.gz: b547d045c8bd2edfee3dbb48d4104f68650d4ee778680d555d9667b790005c84
+  metadata.gz: 94a41b01c95f9975b2caa3fd6e35ed59f3a0a50ea1bef0a382984db8b28a2df1
+  data.tar.gz: 2a2af32a87f880dfbea771d08e1ba0aff16015a14da80742ee90f8bcaa8f653c
 SHA512:
-  metadata.gz: f7b0f7a4de43f7488bc6c5507fb2bf7cfabca37ff1d062ce4860846fe0bf95023edec89da29eca4fe6a25d5773ce42f7b04ccea08dda5a47c9b726e46405422f
-  data.tar.gz: db5cde513357a5a8e128401c14c4b53fb452d6d3ab3804e4a069732aa3e88614dae751bd806cda242d238e0dcdb0adb84e7220fe4c1947c65b79e4d590b9837c
+  metadata.gz: 42e019ecf001cf27fe9c4a6fb09ab3830c94e4d198b150ea9a34854a4cb77c72b0d769b61cce671dc3fb548b2d5bf6f7b8df97fcea08175bde3897f205ff8d24
+  data.tar.gz: 5f83a1f886d1b2d3e995be899b9b093bfb03738b9626ca5a5c7c2c06fecf88da037d017fe894b5c0ad014ec3a9a5bdabc0173eeb748b6e07bb013452e1cfd833

data/CHANGELOG.md

@@ -1,34 +1,15 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented in [GitHub Releases](https://github.com/patrick204nqh/sumologic-query/releases).
 
-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).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2025-11-13
+## Releases
 
-### Added
-- Initial release of sumologic-query CLI tool
-- Core `Sumologic::Client` class for Search Job API
-- Command-line interface with query, time range, and output options
-- Automatic job polling with 20-second intervals
-- Automatic pagination for large result sets (10K messages per request)
-- Support for multiple Sumo Logic deployments (us1, us2, eu, au)
-- Environment variable configuration (SUMO_ACCESS_ID, SUMO_ACCESS_KEY, SUMO_DEPLOYMENT)
-- Debug mode for troubleshooting (SUMO_DEBUG)
-- JSON output format with metadata
-- Zero external dependencies (stdlib only)
-- Comprehensive error handling and user-friendly messages
-- MIT license
-- Complete documentation and examples
+- [v1.1.0](https://github.com/patrick204nqh/sumologic-query/releases/tag/v1.1.0) - Latest
+- [v1.0.0](https://github.com/patrick204nqh/sumologic-query/releases/tag/v1.0.0) - Initial release
 
-### Features
-- Query historical logs via Search Job API
-- Time range filtering (ISO 8601 format)
-- Message limiting
-- Timezone support
-- File or stdout output
-- 5-minute default timeout
-- Graceful cleanup of search jobs
+---
 
-[1.0.0]: https://github.com/patrick204nqh/sumologic-query/releases/tag/v1.0.0
+**Note:** Release notes are automatically generated from commit messages and pull requests.
+See [GitHub Releases](https://github.com/patrick204nqh/sumologic-query/releases) for detailed changelogs.

data/bin/sumo-query

@@ -1,110 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Simple CLI wrapper for querying Sumo Logic logs
-# Usage: sumo-query --query "error" --from "2025-11-13T14:00:00" --to "2025-11-13T15:00:00"
-
 require_relative '../lib/sumologic'
-require 'optparse'
-require 'json'
-
-options = {
-  time_zone: 'UTC'
-}
-
-OptionParser.new do |opts|
-  opts.banner = <<~BANNER
-    Sumo Logic Query Tool - Fast, read-only log access
-
-    Usage: sumo-query [options]
-
-    Examples:
-      # Error timeline with 5-minute buckets
-      sumo-query --query 'error | timeslice 5m | count' \\
-        --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00'
-
-      # Search for specific text
-      sumo-query --query '"connection timeout"' \\
-        --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00' \\
-        --limit 100
-
-      # Filter by source category
-      sumo-query --query '_sourceCategory=prod/api error' \\
-        --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00' \\
-        --output results.json
-
-    Options:
-  BANNER
-
-  opts.on('-q', '--query QUERY', 'Search query (required)') { |v| options[:query] = v }
-  opts.on('-f', '--from TIME', 'Start time in ISO 8601 format (required)') { |v| options[:from] = v }
-  opts.on('-t', '--to TIME', 'End time in ISO 8601 format (required)') { |v| options[:to] = v }
-  opts.on('-z', '--time-zone TZ', 'Time zone (default: UTC)') { |v| options[:time_zone] = v }
-  opts.on('-l', '--limit N', Integer, 'Limit number of messages') { |v| options[:limit] = v }
-  opts.on('-o', '--output FILE', 'Output file (default: stdout)') { |v| options[:output] = v }
-  opts.on('-d', '--debug', 'Enable debug output') { $DEBUG = true }
-  opts.on('-h', '--help', 'Show this help') do
-    puts opts
-    exit
-  end
-  opts.on('-v', '--version', 'Show version') do
-    puts "sumologic-query v#{Sumologic::VERSION}"
-    exit
-  end
-end.parse!
-
-# Validate required options
-unless options[:query] && options[:from] && options[:to]
-  warn 'Error: --query, --from, and --to are required'
-  warn 'Run with --help for usage information'
-  exit 1
-end
 
 begin
-  # Create client
-  client = Sumologic::Client.new
-
-  warn "Querying Sumo Logic: #{options[:from]} to #{options[:to]}"
-  warn "Query: #{options[:query]}"
-  warn 'This may take 1-3 minutes depending on data volume...'
-  $stderr.puts
-
-  # Execute search
-  results = client.search(
-    query: options[:query],
-    from_time: options[:from],
-    to_time: options[:to],
-    time_zone: options[:time_zone],
-    limit: options[:limit]
-  )
-
-  # Format output
-  output = {
-    query: options[:query],
-    from: options[:from],
-    to: options[:to],
-    time_zone: options[:time_zone],
-    message_count: results.size,
-    messages: results
-  }
-
-  json_output = JSON.pretty_generate(output)
-
-  # Write to file or stdout
-  if options[:output]
-    File.write(options[:output], json_output)
-    warn "\nResults saved to: #{options[:output]}"
-    warn "Message count: #{results.size}"
-  else
-    puts json_output
-  end
-rescue Sumologic::AuthenticationError => e
-  warn "\nAuthentication Error: #{e.message}"
-  warn "\nPlease set environment variables:"
-  warn "  export SUMO_ACCESS_ID='your_access_id'"
-  warn "  export SUMO_ACCESS_KEY='your_access_key'"
-  warn "  export SUMO_DEPLOYMENT='us2'  # Optional, defaults to us2"
-  exit 1
+  Sumologic::CLI.start(ARGV)
 rescue Sumologic::TimeoutError => e
   warn "\nTimeout Error: #{e.message}"
   warn "\nTry:"
@@ -115,6 +15,10 @@ rescue Sumologic::TimeoutError => e
 rescue Sumologic::Error => e
   warn "\nError: #{e.message}"
   exit 1
+rescue StandardError => e
+  warn "\nUnexpected Error: #{e.message}"
+  warn e.backtrace.first(5).join("\n") if $DEBUG
+  exit 1
 rescue Interrupt
   warn "\nInterrupted by user"
   exit 130

data/lib/sumologic/cli.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'json'
+
+module Sumologic
+  # Thor-based CLI for Sumo Logic query tool
+  class CLI < Thor
+    class_option :debug, type: :boolean, aliases: '-d', desc: 'Enable debug output'
+    class_option :output, type: :string, aliases: '-o', desc: 'Output file (default: stdout)'
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'search', 'Search Sumo Logic logs'
+    long_desc <<~DESC
+      Search Sumo Logic logs using a query string.
+
+      Examples:
+        # Error timeline with 5-minute buckets
+        sumo-query search --query 'error | timeslice 5m | count' \\
+          --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00'
+
+        # Search for specific text
+        sumo-query search --query '"connection timeout"' \\
+          --from '2025-11-13T14:00:00' --to '2025-11-13T15:00:00' \\
+          --limit 100
+    DESC
+    option :query, type: :string, required: true, aliases: '-q', desc: 'Search query'
+    option :from, type: :string, required: true, aliases: '-f', desc: 'Start time (ISO 8601)'
+    option :to, type: :string, required: true, aliases: '-t', desc: 'End time (ISO 8601)'
+    option :time_zone, type: :string, default: 'UTC', aliases: '-z', desc: 'Time zone'
+    option :limit, type: :numeric, aliases: '-l', desc: 'Limit number of messages'
+    def search
+      $DEBUG = true if options[:debug]
+
+      client = create_client
+
+      log_search_info
+      results = execute_search(client)
+      output_search_results(results)
+
+      warn "\nMessage count: #{results.size}"
+    end
+
+    desc 'list-collectors', 'List all Sumo Logic collectors'
+    long_desc <<~DESC
+      List all collectors in your Sumo Logic account.
+
+      Example:
+        sumo-query list-collectors --output collectors.json
+    DESC
+    def list_collectors
+      $DEBUG = true if options[:debug]
+
+      client = create_client
+
+      warn 'Fetching collectors...'
+      collectors = client.list_collectors
+
+      output_json(
+        total: collectors.size,
+        collectors: collectors.map { |c| format_collector(c) }
+      )
+    end
+
+    desc 'list-sources', 'List sources from collectors'
+    long_desc <<~DESC
+      List all sources from all collectors, or sources from a specific collector.
+
+      Examples:
+        # List all sources
+        sumo-query list-sources
+
+        # List sources for specific collector
+        sumo-query list-sources --collector-id 12345
+    DESC
+    option :collector_id, type: :string, desc: 'Collector ID to list sources for'
+    def list_sources
+      $DEBUG = true if options[:debug]
+
+      client = create_client
+
+      if options[:collector_id]
+        list_sources_for_collector(client, options[:collector_id])
+      else
+        list_all_sources(client)
+      end
+    end
+
+    default_task :search
+
+    private
+
+    def create_client
+      Client.new
+    rescue AuthenticationError => e
+      error "Authentication Error: #{e.message}"
+      error "\nPlease set environment variables:"
+      error "  export SUMO_ACCESS_ID='your_access_id'"
+      error "  export SUMO_ACCESS_KEY='your_access_key'"
+      error "  export SUMO_DEPLOYMENT='us2'  # Optional, defaults to us2"
+      exit 1
+    rescue Error => e
+      error "Error: #{e.message}"
+      exit 1
+    end
+
+    def list_sources_for_collector(client, collector_id)
+      warn "Fetching sources for collector: #{collector_id}"
+      sources = client.list_sources(collector_id: collector_id)
+
+      output_json(
+        collector_id: collector_id,
+        total: sources.size,
+        sources: sources.map { |s| format_source(s) }
+      )
+    end
+
+    def list_all_sources(client)
+      warn 'Fetching all sources from all collectors...'
+      warn 'This may take a minute...'
+
+      all_sources = client.list_all_sources
+
+      output_json(
+        total_collectors: all_sources.size,
+        total_sources: all_sources.sum { |c| c['sources'].size },
+        data: all_sources.map do |item|
+          {
+            collector: item['collector'],
+            sources: item['sources'].map { |s| format_source(s) }
+          }
+        end
+      )
+    end
+
+    def format_collector(collector)
+      {
+        id: collector['id'],
+        name: collector['name'],
+        collectorType: collector['collectorType'],
+        alive: collector['alive'],
+        category: collector['category']
+      }
+    end
+
+    def format_source(source)
+      {
+        id: source['id'],
+        name: source['name'],
+        category: source['category'],
+        sourceType: source['sourceType'],
+        alive: source['alive']
+      }
+    end
+
+    def output_json(data)
+      json_output = JSON.pretty_generate(data)
+
+      if options[:output]
+        File.write(options[:output], json_output)
+        warn "\nResults saved to: #{options[:output]}"
+      else
+        puts json_output
+      end
+    end
+
+    def error(message)
+      warn message
+    end
+
+    def log_search_info
+      warn "Querying Sumo Logic: #{options[:from]} to #{options[:to]}"
+      warn "Query: #{options[:query]}"
+      warn 'This may take 1-3 minutes depending on data volume...'
+      $stderr.puts
+    end
+
+    def execute_search(client)
+      client.search(
+        query: options[:query],
+        from_time: options[:from],
+        to_time: options[:to],
+        time_zone: options[:time_zone],
+        limit: options[:limit]
+      )
+    end
+
+    def output_search_results(results)
+      output_json(
+        query: options[:query],
+        from: options[:from],
+        to: options[:to],
+        time_zone: options[:time_zone],
+        message_count: results.size,
+        messages: results
+      )
+    end
+  end
+end

data/lib/sumologic/client.rb

@@ -1,203 +1,59 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'uri'
-require 'base64'
-
 module Sumologic
-  # Lightweight Sumo Logic Search Job API client
-  # Handles historical log queries with automatic polling and pagination
+  # Facade for Sumo Logic API operations
+  # Coordinates HTTP, Search, and Metadata components
   class Client
-    API_VERSION = 'v1'
-    DEFAULT_POLL_INTERVAL = 20 # seconds
-    DEFAULT_TIMEOUT = 300 # seconds (5 minutes)
-    MAX_MESSAGES_PER_REQUEST = 10_000
-
-    attr_reader :access_id, :access_key, :deployment, :base_url
-
-    def initialize(access_id: nil, access_key: nil, deployment: nil)
-      @access_id = access_id || ENV.fetch('SUMO_ACCESS_ID', nil)
-      @access_key = access_key || ENV.fetch('SUMO_ACCESS_KEY', nil)
-      @deployment = deployment || ENV['SUMO_DEPLOYMENT'] || 'us2'
-      @base_url = deployment_url(@deployment)
-
-      validate_credentials!
-    end
-
-    # Main search method
-    # Returns array of messages/records as JSON
+    attr_reader :config
+
+    def initialize(config = nil)
+      @config = config || Configuration.new
+      @config.validate!
+
+      # Initialize HTTP layer
+      authenticator = Http::Authenticator.new(
+        access_id: @config.access_id,
+        access_key: @config.access_key
+      )
+      @http = Http::Client.new(
+        base_url: @config.base_url,
+        authenticator: authenticator
+      )
+
+      # Initialize domain components
+      @search = Search::Job.new(http_client: @http, config: @config)
+      @collector = Metadata::Collector.new(http_client: @http)
+      @source = Metadata::Source.new(http_client: @http, collector_client: @collector)
+    end
+
+    # Search logs with query
+    # Returns array of messages
     def search(query:, from_time:, to_time:, time_zone: 'UTC', limit: nil)
-      job_id = create_job(query, from_time, to_time, time_zone)
-      poll_until_complete(job_id)
-      messages = fetch_all_messages(job_id, limit)
-      delete_job(job_id)
-      messages
-    rescue StandardError => e
-      delete_job(job_id) if job_id
-      raise Error, "Search failed: #{e.message}"
-    end
-
-    private
-
-    def validate_credentials!
-      raise AuthenticationError, 'SUMO_ACCESS_ID not set' unless @access_id
-      raise AuthenticationError, 'SUMO_ACCESS_KEY not set' unless @access_key
-    end
-
-    def deployment_url(deployment)
-      case deployment
-      when /^http/
-        deployment # Full URL provided
-      when 'us1'
-        'https://api.sumologic.com/api/v1'
-      when 'us2'
-        'https://api.us2.sumologic.com/api/v1'
-      when 'eu'
-        'https://api.eu.sumologic.com/api/v1'
-      when 'au'
-        'https://api.au.sumologic.com/api/v1'
-      else
-        "https://api.#{deployment}.sumologic.com/api/v1"
-      end
-    end
-
-    def auth_header
-      encoded = Base64.strict_encode64("#{@access_id}:#{@access_key}")
-      "Basic #{encoded}"
-    end
-
-    def create_job(query, from_time, to_time, time_zone)
-      uri = URI("#{@base_url}/search/jobs")
-      request = Net::HTTP::Post.new(uri)
-      request['Authorization'] = auth_header
-      request['Content-Type'] = 'application/json'
-      request['Accept'] = 'application/json'
-
-      body = {
+      @search.execute(
         query: query,
-        from: from_time,
-        to: to_time,
-        timeZone: time_zone
-      }
-      request.body = body.to_json
-
-      response = http_request(uri, request)
-      data = JSON.parse(response.body)
-
-      raise Error, "Failed to create job: #{data['message']}" unless data['id']
-
-      log_info "Created search job: #{data['id']}"
-      data['id']
+        from_time: from_time,
+        to_time: to_time,
+        time_zone: time_zone,
+        limit: limit
+      )
     end
 
-    def poll_until_complete(job_id, timeout: DEFAULT_TIMEOUT)
-      uri = URI("#{@base_url}/search/jobs/#{job_id}")
-      start_time = Time.now
-      interval = DEFAULT_POLL_INTERVAL
-
-      loop do
-        raise TimeoutError, "Search job timed out after #{timeout} seconds" if Time.now - start_time > timeout
-
-        request = Net::HTTP::Get.new(uri)
-        request['Authorization'] = auth_header
-        request['Accept'] = 'application/json'
-
-        response = http_request(uri, request)
-        data = JSON.parse(response.body)
-
-        state = data['state']
-        log_info "Job state: #{state} (#{data['messageCount']} messages, #{data['recordCount']} records)"
-
-        case state
-        when 'DONE GATHERING RESULTS'
-          return data
-        when 'CANCELLED', 'FORCE PAUSED'
-          raise Error, "Search job #{state.downcase}"
-        end
-
-        sleep interval
-      end
-    end
-
-    def fetch_all_messages(job_id, limit = nil)
-      messages = []
-      offset = 0
-      total_fetched = 0
-
-      loop do
-        batch_limit = if limit
-                        [MAX_MESSAGES_PER_REQUEST, limit - total_fetched].min
-                      else
-                        MAX_MESSAGES_PER_REQUEST
-                      end
-
-        break if batch_limit <= 0
-
-        uri = URI("#{@base_url}/search/jobs/#{job_id}/messages")
-        uri.query = URI.encode_www_form(offset: offset, limit: batch_limit)
-
-        request = Net::HTTP::Get.new(uri)
-        request['Authorization'] = auth_header
-        request['Accept'] = 'application/json'
-
-        response = http_request(uri, request)
-        data = JSON.parse(response.body)
-
-        batch = data['messages'] || []
-        messages.concat(batch)
-        total_fetched += batch.size
-
-        log_info "Fetched #{batch.size} messages (total: #{total_fetched})"
-
-        break if batch.size < batch_limit # No more messages
-        break if limit && total_fetched >= limit
-
-        offset += batch.size
-      end
-
-      messages
-    end
-
-    def delete_job(job_id)
-      return unless job_id
-
-      uri = URI("#{@base_url}/search/jobs/#{job_id}")
-      request = Net::HTTP::Delete.new(uri)
-      request['Authorization'] = auth_header
-
-      http_request(uri, request)
-      log_info "Deleted search job: #{job_id}"
-    rescue StandardError => e
-      log_error "Failed to delete job #{job_id}: #{e.message}"
-    end
-
-    def http_request(uri, request)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      http.read_timeout = 60
-      http.open_timeout = 10
-
-      response = http.request(request)
-
-      case response.code.to_i
-      when 200..299
-        response
-      when 401, 403
-        raise AuthenticationError, "Authentication failed: #{response.body}"
-      when 429
-        raise Error, "Rate limit exceeded: #{response.body}"
-      else
-        raise Error, "HTTP #{response.code}: #{response.body}"
-      end
+    # List all collectors
+    # Returns array of collector objects
+    def list_collectors
+      @collector.list
     end
 
-    def log_info(message)
-      warn "[Sumologic::Client] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+    # List sources for a specific collector
+    # Returns array of source objects
+    def list_sources(collector_id:)
+      @source.list(collector_id: collector_id)
     end
 
-    def log_error(message)
-      warn "[Sumologic::Client ERROR] #{message}"
+    # List all sources from all collectors
+    # Returns array of hashes with collector and sources
+    def list_all_sources
+      @source.list_all
     end
   end
 end

data/lib/sumologic/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sumologic
+  # Centralized configuration for Sumo Logic client
+  class Configuration
+    attr_accessor :access_id, :access_key, :deployment, :timeout, :initial_poll_interval, :max_poll_interval,
+                  :poll_backoff_factor, :max_messages_per_request
+
+    API_VERSION = 'v1'
+
+    def initialize
+      # Authentication
+      @access_id = ENV.fetch('SUMO_ACCESS_ID', nil)
+      @access_key = ENV.fetch('SUMO_ACCESS_KEY', nil)
+      @deployment = ENV['SUMO_DEPLOYMENT'] || 'us2'
+
+      # Search job polling
+      @initial_poll_interval = 5 # seconds - start fast for small queries
+      @max_poll_interval = 20 # seconds - slow down for large queries
+      @poll_backoff_factor = 1.5 # increase interval by 50% each time
+
+      # Timeouts and limits
+      @timeout = 300 # seconds (5 minutes)
+      @max_messages_per_request = 10_000
+    end
+
+    def base_url
+      @base_url ||= build_base_url
+    end
+
+    def validate!
+      raise AuthenticationError, 'SUMO_ACCESS_ID not set' unless @access_id
+      raise AuthenticationError, 'SUMO_ACCESS_KEY not set' unless @access_key
+    end
+
+    private
+
+    def build_base_url
+      case @deployment
+      when /^http/
+        @deployment # Full URL provided
+      when 'us1'
+        "https://api.sumologic.com/api/#{API_VERSION}"
+      when 'us2'
+        "https://api.us2.sumologic.com/api/#{API_VERSION}"
+      when 'eu'
+        "https://api.eu.sumologic.com/api/#{API_VERSION}"
+      when 'au'
+        "https://api.au.sumologic.com/api/#{API_VERSION}"
+      else
+        "https://api.#{@deployment}.sumologic.com/api/#{API_VERSION}"
+      end
+    end
+  end
+end

data/lib/sumologic/http/authenticator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Sumologic
+  module Http
+    # Handles authentication header generation for Sumo Logic API
+    class Authenticator
+      def initialize(access_id:, access_key:)
+        @access_id = access_id
+        @access_key = access_key
+      end
+
+      def auth_header
+        encoded = Base64.strict_encode64("#{@access_id}:#{@access_key}")
+        "Basic #{encoded}"
+      end
+    end
+  end
+end

data/lib/sumologic/http/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Sumologic
+  module Http
+    # Handles HTTP communication with Sumo Logic API
+    # Responsibilities: request execution, error handling, SSL configuration
+    class Client
+      READ_TIMEOUT = 60
+      OPEN_TIMEOUT = 10
+
+      def initialize(base_url:, authenticator:)
+        @base_url = base_url
+        @authenticator = authenticator
+      end
+
+      # Execute HTTP request with error handling
+      def request(method:, path:, body: nil, query_params: nil)
+        uri = build_uri(path, query_params)
+        request = build_request(method, uri, body)
+
+        response = execute_request(uri, request)
+        handle_response(response)
+      end
+
+      private
+
+      def build_uri(path, query_params)
+        uri = URI("#{@base_url}#{path}")
+        uri.query = URI.encode_www_form(query_params) if query_params
+        uri
+      end
+
+      def build_request(method, uri, body)
+        request_class = case method
+                        when :get then Net::HTTP::Get
+                        when :post then Net::HTTP::Post
+                        when :delete then Net::HTTP::Delete
+                        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                        end
+
+        request = request_class.new(uri)
+        request['Authorization'] = @authenticator.auth_header
+        request['Accept'] = 'application/json'
+
+        if body
+          request['Content-Type'] = 'application/json'
+          request.body = body.to_json
+        end
+
+        request
+      end
+
+      def execute_request(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = READ_TIMEOUT
+        http.open_timeout = OPEN_TIMEOUT
+
+        http.request(request)
+      end
+
+      def handle_response(response)
+        case response.code.to_i
+        when 200..299
+          JSON.parse(response.body)
+        when 401, 403
+          raise AuthenticationError, "Authentication failed: #{response.body}"
+        when 429
+          raise Error, "Rate limit exceeded: #{response.body}"
+        else
+          raise Error, "HTTP #{response.code}: #{response.body}"
+        end
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/collector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Sumologic
+  module Metadata
+    # Handles collector metadata operations
+    class Collector
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # List all collectors
+      # Returns array of collector objects
+      def list
+        data = @http.request(
+          method: :get,
+          path: '/collectors'
+        )
+
+        collectors = data['collectors'] || []
+        log_info "Found #{collectors.size} collectors"
+        collectors
+      rescue StandardError => e
+        raise Error, "Failed to list collectors: #{e.message}"
+      end
+
+      private
+
+      def log_info(message)
+        warn "[Sumologic::Metadata::Collector] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/source.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Sumologic
+  module Metadata
+    # Handles source metadata operations
+    class Source
+      def initialize(http_client:, collector_client:)
+        @http = http_client
+        @collector_client = collector_client
+      end
+
+      # List sources for a specific collector
+      # Returns array of source objects with metadata
+      def list(collector_id:)
+        data = @http.request(
+          method: :get,
+          path: "/collectors/#{collector_id}/sources"
+        )
+
+        sources = data['sources'] || []
+        log_info "Found #{sources.size} sources for collector #{collector_id}"
+        sources
+      rescue StandardError => e
+        raise Error, "Failed to list sources for collector #{collector_id}: #{e.message}"
+      end
+
+      # List all sources from all collectors
+      # Returns array of hashes with collector info and their sources
+      def list_all
+        collectors = @collector_client.list
+        result = []
+
+        collectors.each do |collector|
+          next unless collector['alive'] # Skip offline collectors
+
+          collector_id = collector['id']
+          collector_name = collector['name']
+
+          log_info "Fetching sources for collector: #{collector_name} (#{collector_id})"
+
+          sources = list(collector_id: collector_id)
+
+          result << {
+            'collector' => {
+              'id' => collector_id,
+              'name' => collector_name,
+              'collectorType' => collector['collectorType']
+            },
+            'sources' => sources
+          }
+        rescue StandardError => e
+          log_error "Failed to fetch sources for collector #{collector_name}: #{e.message}"
+        end
+
+        log_info "Total: #{result.size} collectors with sources"
+        result
+      rescue StandardError => e
+        raise Error, "Failed to list all sources: #{e.message}"
+      end
+
+      private
+
+      def log_info(message)
+        warn "[Sumologic::Metadata::Source] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+      end
+
+      def log_error(message)
+        warn "[Sumologic::Metadata::Source ERROR] #{message}"
+      end
+    end
+  end
+end

data/lib/sumologic/search/job.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Sumologic
+  module Search
+    # Manages search job lifecycle: create, poll, fetch, delete
+    class Job
+      def initialize(http_client:, config:)
+        @http = http_client
+        @config = config
+        @poller = Poller.new(http_client: http_client, config: config)
+        @paginator = Paginator.new(http_client: http_client, config: config)
+      end
+
+      # Execute a complete search workflow
+      # Returns array of messages
+      def execute(query:, from_time:, to_time:, time_zone: 'UTC', limit: nil)
+        job_id = create(query, from_time, to_time, time_zone)
+        @poller.poll(job_id)
+        messages = @paginator.fetch_all(job_id, limit: limit)
+        delete(job_id)
+        messages
+      rescue StandardError => e
+        delete(job_id) if job_id
+        raise Error, "Search failed: #{e.message}"
+      end
+
+      private
+
+      def create(query, from_time, to_time, time_zone)
+        data = @http.request(
+          method: :post,
+          path: '/search/jobs',
+          body: {
+            query: query,
+            from: from_time,
+            to: to_time,
+            timeZone: time_zone
+          }
+        )
+
+        raise Error, "Failed to create job: #{data['message']}" unless data['id']
+
+        log_info "Created search job: #{data['id']}"
+        data['id']
+      end
+
+      def delete(job_id)
+        return unless job_id
+
+        @http.request(
+          method: :delete,
+          path: "/search/jobs/#{job_id}"
+        )
+        log_info "Deleted search job: #{job_id}"
+      rescue StandardError => e
+        log_error "Failed to delete job #{job_id}: #{e.message}"
+      end
+
+      def log_info(message)
+        warn "[Sumologic::Search::Job] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+      end
+
+      def log_error(message)
+        warn "[Sumologic::Search::Job ERROR] #{message}"
+      end
+    end
+  end
+end

data/lib/sumologic/search/paginator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sumologic
+  module Search
+    # Handles paginated fetching of search job messages
+    class Paginator
+      def initialize(http_client:, config:)
+        @http = http_client
+        @config = config
+      end
+
+      # Fetch all messages for a job with automatic pagination
+      # Returns array of message objects
+      def fetch_all(job_id, limit: nil)
+        messages = []
+        offset = 0
+        total_fetched = 0
+
+        loop do
+          batch_limit = calculate_batch_limit(limit, total_fetched)
+          break if batch_limit <= 0
+
+          batch = fetch_batch(job_id, offset, batch_limit)
+          messages.concat(batch)
+          total_fetched += batch.size
+
+          log_progress(batch.size, total_fetched)
+
+          break if batch.size < batch_limit # No more messages
+          break if limit && total_fetched >= limit
+
+          offset += batch.size
+        end
+
+        messages
+      end
+
+      private
+
+      def calculate_batch_limit(user_limit, total_fetched)
+        if user_limit
+          [@config.max_messages_per_request, user_limit - total_fetched].min
+        else
+          @config.max_messages_per_request
+        end
+      end
+
+      def fetch_batch(job_id, offset, limit)
+        data = @http.request(
+          method: :get,
+          path: "/search/jobs/#{job_id}/messages",
+          query_params: { offset: offset, limit: limit }
+        )
+
+        data['messages'] || []
+      end
+
+      def log_progress(batch_size, total)
+        log_info "Fetched #{batch_size} messages (total: #{total})"
+      end
+
+      def log_info(message)
+        warn "[Sumologic::Search::Paginator] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+      end
+    end
+  end
+end

data/lib/sumologic/search/poller.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Sumologic
+  module Search
+    # Handles adaptive polling of search jobs with exponential backoff
+    class Poller
+      def initialize(http_client:, config:)
+        @http = http_client
+        @config = config
+      end
+
+      # Poll until job completes or times out
+      # Returns final job status data
+      def poll(job_id)
+        start_time = Time.now
+        interval = @config.initial_poll_interval
+        poll_count = 0
+
+        loop do
+          check_timeout!(start_time)
+
+          data = fetch_job_status(job_id)
+          state = data['state']
+
+          log_poll_status(state, data, interval, poll_count)
+
+          case state
+          when 'DONE GATHERING RESULTS'
+            log_completion(start_time, poll_count)
+            return data
+          when 'CANCELLED', 'FORCE PAUSED'
+            raise Error, "Search job #{state.downcase}"
+          end
+
+          sleep interval
+          poll_count += 1
+          interval = calculate_next_interval(interval)
+        end
+      end
+
+      private
+
+      def check_timeout!(start_time)
+        elapsed = Time.now - start_time
+        return unless elapsed > @config.timeout
+
+        raise TimeoutError, "Search job timed out after #{@config.timeout} seconds"
+      end
+
+      def fetch_job_status(job_id)
+        @http.request(
+          method: :get,
+          path: "/search/jobs/#{job_id}"
+        )
+      end
+
+      def calculate_next_interval(current_interval)
+        # Adaptive backoff: gradually increase interval for long-running jobs
+        new_interval = current_interval * @config.poll_backoff_factor
+        [new_interval, @config.max_poll_interval].min
+      end
+
+      def log_poll_status(state, data, interval, count)
+        msg_count = data['messageCount']
+        rec_count = data['recordCount']
+        log_info "Job state: #{state} (#{msg_count} messages, #{rec_count} records) " \
+                 "[interval: #{interval}s, poll: #{count}]"
+      end
+
+      def log_completion(start_time, poll_count)
+        elapsed = Time.now - start_time
+        log_info "Job completed in #{elapsed.round(1)} seconds after #{poll_count + 1} polls"
+      end
+
+      def log_info(message)
+        warn "[Sumologic::Search::Poller] #{message}" if ENV['SUMO_DEBUG'] || $DEBUG
+      end
+    end
+  end
+end

data/lib/sumologic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sumologic
-  VERSION = '1.0.1'
+  VERSION = '1.1.1'
 end

data/lib/sumologic.rb

@@ -1,10 +1,41 @@
 # frozen_string_literal: true
 
 require_relative 'sumologic/version'
-require_relative 'sumologic/client'
 
 module Sumologic
+  # Base error class for all Sumologic errors
   class Error < StandardError; end
-  class TimeoutError < Error; end
+
+  # Authentication-related errors
   class AuthenticationError < Error; end
+
+  # Timeout errors during search job execution
+  class TimeoutError < Error; end
+end
+
+# Load configuration first
+require_relative 'sumologic/configuration'
+
+# Load HTTP layer
+require_relative 'sumologic/http/authenticator'
+require_relative 'sumologic/http/client'
+
+# Load search domain
+require_relative 'sumologic/search/poller'
+require_relative 'sumologic/search/paginator'
+require_relative 'sumologic/search/job'
+
+# Load metadata domain
+require_relative 'sumologic/metadata/collector'
+require_relative 'sumologic/metadata/source'
+
+# Load main client (facade)
+require_relative 'sumologic/client'
+
+# Load CLI (requires thor gem)
+begin
+  require 'thor'
+  require_relative 'sumologic/cli'
+rescue LoadError
+  # Thor not available - CLI won't work but library will
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sumologic-query
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - patrick204nqh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-13 00:00:00.000000000 Z
+date: 2025-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -82,7 +96,16 @@ files:
 - README.md
 - bin/sumo-query
 - lib/sumologic.rb
+- lib/sumologic/cli.rb
 - lib/sumologic/client.rb
+- lib/sumologic/configuration.rb
+- lib/sumologic/http/authenticator.rb
+- lib/sumologic/http/client.rb
+- lib/sumologic/metadata/collector.rb
+- lib/sumologic/metadata/source.rb
+- lib/sumologic/search/job.rb
+- lib/sumologic/search/paginator.rb
+- lib/sumologic/search/poller.rb
 - lib/sumologic/version.rb
 homepage: https://github.com/patrick204nqh/sumologic-query
 licenses: