sumologic-query 1.3.5 → 1.4.0

data/lib/sumologic/configuration.rb

@@ -4,7 +4,8 @@ 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, :max_workers, :request_delay
+                  :poll_backoff_factor, :max_messages_per_request, :max_workers, :request_delay,
+                  :connect_timeout, :read_timeout, :max_retries, :retry_base_delay, :retry_max_delay
 
     API_VERSION = 'v1'
 
@@ -20,9 +21,16 @@ module Sumologic
       @poll_backoff_factor = 1.5 # increase interval by 50% each time
 
       # Timeouts and limits
-      @timeout = 300 # seconds (5 minutes)
+      @timeout = 300 # seconds (5 minutes) - overall operation timeout
+      @connect_timeout = ENV.fetch('SUMO_CONNECT_TIMEOUT', '10').to_i # seconds
+      @read_timeout = ENV.fetch('SUMO_READ_TIMEOUT', '60').to_i # seconds
       @max_messages_per_request = 10_000
 
+      # Retry configuration
+      @max_retries = ENV.fetch('SUMO_MAX_RETRIES', '3').to_i
+      @retry_base_delay = ENV.fetch('SUMO_RETRY_BASE_DELAY', '1.0').to_f # seconds
+      @retry_max_delay = ENV.fetch('SUMO_RETRY_MAX_DELAY', '30.0').to_f # seconds
+
       # Rate limiting (default: 5 workers, 250ms delay)
       @max_workers = ENV.fetch('SUMO_MAX_WORKERS', '5').to_i
       @request_delay = ENV.fetch('SUMO_REQUEST_DELAY', '0.25').to_f
@@ -32,6 +40,11 @@ module Sumologic
       @base_url ||= build_base_url
     end
 
+    # Base URL for v2 API endpoints (Content Library, etc.)
+    def base_url_v2
+      @base_url_v2 ||= build_base_url('v2')
+    end
+
     def validate!
       raise AuthenticationError, 'SUMO_ACCESS_ID not set' unless @access_id
       raise AuthenticationError, 'SUMO_ACCESS_KEY not set' unless @access_key
@@ -39,20 +52,21 @@ module Sumologic
 
     private
 
-    def build_base_url
+    def build_base_url(version = API_VERSION)
       case @deployment
       when /^http/
-        @deployment # Full URL provided
+        # Full URL provided - replace version if present
+        @deployment.sub(%r{/api/v\d+}, "/api/#{version}")
       when 'us1'
-        "https://api.sumologic.com/api/#{API_VERSION}"
+        "https://api.sumologic.com/api/#{version}"
       when 'us2'
-        "https://api.us2.sumologic.com/api/#{API_VERSION}"
+        "https://api.us2.sumologic.com/api/#{version}"
       when 'eu'
-        "https://api.eu.sumologic.com/api/#{API_VERSION}"
+        "https://api.eu.sumologic.com/api/#{version}"
       when 'au'
-        "https://api.au.sumologic.com/api/#{API_VERSION}"
+        "https://api.au.sumologic.com/api/#{version}"
       else
-        "https://api.#{@deployment}.sumologic.com/api/#{API_VERSION}"
+        "https://api.#{@deployment}.sumologic.com/api/#{version}"
       end
     end
   end

data/lib/sumologic/http/client.rb

@@ -11,8 +11,30 @@ module Sumologic
     # Orchestrates HTTP communication with Sumo Logic API
     # Delegates to specialized components for request building,
     # response handling, connection pooling, and cookie management
+    #
+    # Features automatic retry with exponential backoff for:
+    # - Rate limit errors (429)
+    # - Server errors (5xx)
+    # - Connection errors
     class Client
-      def initialize(base_url:, authenticator:)
+      # Errors that are safe to retry
+      RETRYABLE_EXCEPTIONS = [
+        Errno::ECONNRESET,
+        Errno::EPIPE,
+        Errno::ETIMEDOUT,
+        Errno::ECONNREFUSED,
+        EOFError,
+        Net::HTTPBadResponse,
+        Net::OpenTimeout,
+        Net::ReadTimeout
+      ].freeze
+
+      def initialize(base_url:, authenticator:, config: nil)
+        @config = config
+        @max_retries = config&.max_retries || 3
+        @retry_base_delay = config&.retry_base_delay || 1.0
+        @retry_max_delay = config&.retry_max_delay || 30.0
+
         @cookie_jar = CookieJar.new
         @request_builder = RequestBuilder.new(
           base_url: base_url,
@@ -20,25 +42,47 @@ module Sumologic
           cookie_jar: @cookie_jar
         )
         @response_handler = ResponseHandler.new
-        @connection_pool = ConnectionPool.new(base_url: base_url, max_connections: 10)
+        @connection_pool = ConnectionPool.new(
+          base_url: base_url,
+          max_connections: 10,
+          read_timeout: config&.read_timeout,
+          connect_timeout: config&.connect_timeout
+        )
       end
 
-      # Execute HTTP request with error handling
+      # Execute HTTP request with automatic retry for transient errors
       # Uses connection pool for thread-safe parallel execution
       def request(method:, path:, body: nil, query_params: nil)
         uri = @request_builder.build_uri(path, query_params)
-        request = @request_builder.build_request(method, uri, body)
+        attempt = 0
 
-        DebugLogger.log_request(method, uri, body, request.to_hash)
+        loop do
+          attempt += 1
+          request = @request_builder.build_request(method, uri, body)
 
-        response = execute_request(uri, request)
+          DebugLogger.log_request(method, uri, body, request.to_hash)
 
-        DebugLogger.log_response(response)
+          begin
+            response = execute_request(uri, request)
+            DebugLogger.log_response(response)
 
-        @response_handler.handle(response)
-      rescue Errno::ECONNRESET, Errno::EPIPE, EOFError, Net::HTTPBadResponse => e
-        # Connection error - raise for retry at higher level
-        raise Error, "Connection error: #{e.message}"
+            # Check if response is retryable before handling
+            if @response_handler.retryable?(response) && attempt <= @max_retries
+              delay = calculate_retry_delay(attempt, response)
+              log_retry(attempt, delay, "HTTP #{response.code}")
+              sleep(delay)
+              next
+            end
+
+            return @response_handler.handle(response)
+          rescue *RETRYABLE_EXCEPTIONS => e
+            raise Error, "Connection error: #{e.message}" if attempt > @max_retries
+
+            delay = calculate_retry_delay(attempt)
+            log_retry(attempt, delay, e.class.name)
+            sleep(delay)
+          end
+        end
       end
 
       # Close all connections in the pool
@@ -58,6 +102,27 @@ module Sumologic
 
         response
       end
+
+      def calculate_retry_delay(attempt, response = nil)
+        # Use Retry-After header if available (for rate limits)
+        if response
+          info = @response_handler.extract_rate_limit_info(response)
+          return info[:retry_after] if info[:retry_after]&.positive?
+        end
+
+        # Exponential backoff with jitter
+        base_delay = @retry_base_delay * (2**(attempt - 1))
+        jitter = rand * 0.5 * base_delay # Add up to 50% jitter
+        delay = base_delay + jitter
+
+        [delay, @retry_max_delay].min
+      end
+
+      def log_retry(attempt, delay, reason)
+        return unless ENV['SUMO_DEBUG'] || $DEBUG
+
+        warn "[Sumologic::Http::Client] Retry #{attempt}/#{@max_retries} after #{delay.round(2)}s (#{reason})"
+      end
     end
   end
 end

data/lib/sumologic/http/connection_pool.rb

@@ -7,12 +7,14 @@ module Sumologic
     # Thread-safe connection pool for HTTP clients
     # Allows multiple threads to have their own connections
     class ConnectionPool
-      READ_TIMEOUT = 60
-      OPEN_TIMEOUT = 10
+      DEFAULT_READ_TIMEOUT = 60
+      DEFAULT_OPEN_TIMEOUT = 10
 
-      def initialize(base_url:, max_connections: 10)
+      def initialize(base_url:, max_connections: 10, read_timeout: nil, connect_timeout: nil)
         @base_url = base_url
         @max_connections = max_connections
+        @read_timeout = read_timeout || DEFAULT_READ_TIMEOUT
+        @connect_timeout = connect_timeout || DEFAULT_OPEN_TIMEOUT
         @pool = []
         @mutex = Mutex.new
       end
@@ -83,8 +85,8 @@ module Sumologic
       def create_connection(uri)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
-        http.read_timeout = READ_TIMEOUT
-        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = @read_timeout
+        http.open_timeout = @connect_timeout
         http.keep_alive_timeout = 30
 
         # SSL configuration

data/lib/sumologic/http/response_handler.rb

@@ -15,14 +15,34 @@ module Sumologic
           handle_authentication_error(response)
         when 429
           handle_rate_limit_error(response)
+        when 500..599
+          handle_server_error(response)
         else
           handle_generic_error(response)
         end
       end
 
+      # Check if response indicates a retryable error
+      def retryable?(response)
+        code = response.code.to_i
+        code == 429 || code.between?(500, 599)
+      end
+
+      # Extract rate limit info from response headers
+      def extract_rate_limit_info(response)
+        {
+          retry_after: parse_retry_after(response),
+          limit: response['X-RateLimit-Limit']&.to_i,
+          remaining: response['X-RateLimit-Remaining']&.to_i,
+          reset_at: parse_reset_time(response)
+        }
+      end
+
       private
 
       def parse_success(response)
+        return {} if response.body.nil? || response.body.empty?
+
         JSON.parse(response.body)
       end
 
@@ -31,12 +51,56 @@ module Sumologic
       end
 
       def handle_rate_limit_error(response)
-        raise Error, "Rate limit exceeded: #{response.body}"
+        info = extract_rate_limit_info(response)
+        message = 'Rate limit exceeded'
+        message += " (retry after #{info[:retry_after]}s)" if info[:retry_after]
+
+        raise RateLimitError.new(
+          message,
+          retry_after: info[:retry_after],
+          limit: info[:limit],
+          remaining: info[:remaining],
+          reset_at: info[:reset_at]
+        )
+      end
+
+      def handle_server_error(response)
+        raise Error, "Server error HTTP #{response.code}: #{response.body}"
       end
 
       def handle_generic_error(response)
         raise Error, "HTTP #{response.code}: #{response.body}"
       end
+
+      def parse_retry_after(response)
+        # Try Retry-After header first (standard HTTP)
+        retry_after = response['Retry-After']
+        return retry_after.to_i if retry_after&.match?(/^\d+$/)
+
+        # Try X-RateLimit-Reset (common alternative)
+        reset = response['X-RateLimit-Reset']
+        return nil unless reset
+
+        # Reset can be seconds or Unix timestamp
+        reset_val = reset.to_i
+        if reset_val > 1_000_000_000 # Likely a Unix timestamp
+          [reset_val - Time.now.to_i, 1].max
+        else
+          reset_val
+        end
+      end
+
+      def parse_reset_time(response)
+        reset = response['X-RateLimit-Reset']
+        return nil unless reset
+
+        reset_val = reset.to_i
+        if reset_val > 1_000_000_000 # Unix timestamp
+          Time.at(reset_val)
+        else
+          Time.now + reset_val
+        end
+      end
     end
   end
 end

data/lib/sumologic/metadata/app.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+
+module Sumologic
+  module Metadata
+    # Handles app catalog operations
+    # Uses GET /v1/apps endpoint
+    # Note: This lists the app catalog (available apps), not installed apps
+    class App
+      include Loggable
+
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # List available apps from the Sumo Logic app catalog
+      #
+      # @return [Array<Hash>] Array of app data
+      def list
+        data = @http.request(
+          method: :get,
+          path: '/apps'
+        )
+
+        apps = data['apps'] || []
+        log_info "Fetched #{apps.size} apps from catalog"
+        apps
+      rescue StandardError => e
+        raise Error, "Failed to list apps: #{e.message}"
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/content.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+
+module Sumologic
+  module Metadata
+    # Handles content library operations
+    # Uses v2 content API endpoints for path lookup and export
+    class Content
+      include Loggable
+
+      EXPORT_POLL_INTERVAL = 2 # seconds
+      EXPORT_MAX_WAIT = 120 # seconds
+
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # Get a content item by its library path
+      # Returns item ID, type, name, and parent folder
+      #
+      # @param path [String] Content library path (e.g., '/Library/Users/me/My Search')
+      # @return [Hash] Content item data
+      def get_by_path(path)
+        data = @http.request(
+          method: :get,
+          path: '/content/path',
+          query_params: { path: path }
+        )
+
+        log_info "Retrieved content at path: #{path}"
+        data
+      rescue StandardError => e
+        raise Error, "Failed to get content at path '#{path}': #{e.message}"
+      end
+
+      # Export a content item as JSON
+      # Handles the async job lifecycle: start → poll → fetch result
+      #
+      # @param content_id [String] The content item ID to export
+      # @return [Hash] Exported content data
+      def export(content_id)
+        # Start export job
+        job = @http.request(
+          method: :post,
+          path: "/content/#{content_id}/export"
+        )
+        job_id = job['id']
+        log_info "Started export job #{job_id} for content #{content_id}"
+
+        # Poll until complete
+        poll_export_status(content_id, job_id)
+
+        # Fetch result
+        result = @http.request(
+          method: :get,
+          path: "/content/#{content_id}/export/#{job_id}/result"
+        )
+
+        log_info "Export complete for content #{content_id}"
+        result
+      rescue StandardError => e
+        raise Error, "Failed to export content #{content_id}: #{e.message}"
+      end
+
+      private
+
+      def poll_export_status(content_id, job_id)
+        start_time = Time.now
+
+        loop do
+          elapsed = Time.now - start_time
+          raise TimeoutError, "Export job timed out after #{EXPORT_MAX_WAIT}s" if elapsed > EXPORT_MAX_WAIT
+
+          status = @http.request(
+            method: :get,
+            path: "/content/#{content_id}/export/#{job_id}/status"
+          )
+
+          state = status['status']
+          log_info "Export status: #{state}"
+
+          case state
+          when 'Success'
+            return
+          when 'Failed'
+            raise Error, "Export job failed: #{status['error']&.dig('message') || 'unknown error'}"
+          end
+
+          sleep EXPORT_POLL_INTERVAL
+        end
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/dashboard.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+require_relative 'models'
+
+module Sumologic
+  module Metadata
+    # Handles dashboard operations via v2 API
+    # Uses GET /v2/dashboards endpoints
+    class Dashboard
+      include Loggable
+
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # List all dashboards
+      # Returns array of dashboard objects
+      #
+      # @param limit [Integer] Maximum number of dashboards to return (default: 100)
+      # @return [Array<Hash>] Array of dashboard data
+      def list(limit: 100)
+        dashboards = []
+        token = nil
+
+        loop do
+          query_params = { limit: [limit - dashboards.size, 100].min }
+          query_params[:token] = token if token
+
+          data = @http.request(
+            method: :get,
+            path: '/dashboards',
+            query_params: query_params
+          )
+
+          batch = data['dashboards'] || []
+          dashboards.concat(batch)
+
+          log_info "Fetched #{batch.size} dashboards (total: #{dashboards.size})"
+
+          # Check for pagination
+          token = data['next']
+          break if token.nil? || dashboards.size >= limit
+        end
+
+        dashboards.take(limit)
+      rescue StandardError => e
+        raise Error, "Failed to list dashboards: #{e.message}"
+      end
+
+      # Get a specific dashboard by ID
+      # Returns full dashboard details including panels
+      #
+      # @param dashboard_id [String] The dashboard ID
+      # @return [Hash] Dashboard data
+      def get(dashboard_id)
+        data = @http.request(
+          method: :get,
+          path: "/dashboards/#{dashboard_id}"
+        )
+
+        log_info "Retrieved dashboard: #{data['title']} (#{dashboard_id})"
+        data
+      rescue StandardError => e
+        raise Error, "Failed to get dashboard #{dashboard_id}: #{e.message}"
+      end
+
+      # Search dashboards by title or description
+      # Returns matching dashboards
+      #
+      # @param query [String] Search query
+      # @param limit [Integer] Maximum results (default: 100)
+      # @return [Array<Hash>] Matching dashboards
+      def search(query:, limit: 100)
+        # Use list and filter client-side
+        dashboards = list(limit: limit * 2)
+        query_lower = query.downcase
+
+        filtered = dashboards.select do |d|
+          title_match = d['title']&.downcase&.include?(query_lower)
+          desc_match = d['description']&.downcase&.include?(query_lower)
+          title_match || desc_match
+        end
+
+        filtered.take(limit)
+      end
+
+      # List dashboards in a specific folder
+      #
+      # @param folder_id [String] Folder ID to search in
+      # @param limit [Integer] Maximum results
+      # @return [Array<Hash>] Dashboards in folder
+      def list_by_folder(folder_id:, limit: 100)
+        dashboards = list(limit: limit * 2)
+
+        filtered = dashboards.select do |d|
+          d['folderId'] == folder_id
+        end
+
+        filtered.take(limit)
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/field.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+
+module Sumologic
+  module Metadata
+    # Handles field operations
+    # Uses GET /v1/fields and GET /v1/fields/builtin endpoints
+    class Field
+      include Loggable
+
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # List custom fields
+      #
+      # @return [Array<Hash>] Array of custom field data
+      def list
+        data = @http.request(
+          method: :get,
+          path: '/fields'
+        )
+
+        fields = data['data'] || []
+        log_info "Fetched #{fields.size} custom fields"
+        fields
+      rescue StandardError => e
+        raise Error, "Failed to list fields: #{e.message}"
+      end
+
+      # List built-in fields
+      #
+      # @return [Array<Hash>] Array of built-in field data
+      def list_builtin
+        data = @http.request(
+          method: :get,
+          path: '/fields/builtin'
+        )
+
+        fields = data['data'] || []
+        log_info "Fetched #{fields.size} built-in fields"
+        fields
+      rescue StandardError => e
+        raise Error, "Failed to list built-in fields: #{e.message}"
+      end
+    end
+  end
+end

data/lib/sumologic/metadata/folder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+require_relative 'models'
+
+module Sumologic
+  module Metadata
+    # Handles folder/content library operations
+    # Folders organize dashboards, searches, and other content
+    # NOTE: Content API uses v2, not v1
+    class Folder
+      include Loggable
+
+      # @param http_client [Http::Client] HTTP client configured for v2 API
+      def initialize(http_client:)
+        @http = http_client
+      end
+
+      # Get the personal folder for the current user
+      # Returns folder with children
+      #
+      # @return [Hash] Personal folder data
+      def personal
+        data = @http.request(
+          method: :get,
+          path: '/content/folders/personal'
+        )
+
+        log_info "Retrieved personal folder: #{data['name']}"
+        data
+      rescue StandardError => e
+        raise Error, "Failed to get personal folder: #{e.message}"
+      end
+
+      # Get a specific folder by ID
+      # Returns folder details with children
+      #
+      # @param folder_id [String] The folder ID
+      # @return [Hash] Folder data with children
+      def get(folder_id)
+        data = @http.request(
+          method: :get,
+          path: "/content/folders/#{folder_id}"
+        )
+
+        log_info "Retrieved folder: #{data['name']} (#{folder_id})"
+        data
+      rescue StandardError => e
+        raise Error, "Failed to get folder #{folder_id}: #{e.message}"
+      end
+
+      # List all items in a folder (recursive tree)
+      # Builds a tree structure of all content
+      #
+      # @param folder_id [String] Starting folder ID (nil for personal)
+      # @param max_depth [Integer] Maximum recursion depth (default: 3)
+      # @return [Hash] Folder tree with nested children
+      def tree(folder_id: nil, max_depth: 3)
+        root = folder_id ? get(folder_id) : personal
+        build_tree(root, 0, max_depth)
+      rescue StandardError => e
+        raise Error, "Failed to build folder tree: #{e.message}"
+      end
+
+      private
+
+      def build_tree(folder, depth, max_depth)
+        return folder if depth >= max_depth
+
+        children = folder['children'] || []
+        folder['children'] = children.map do |child|
+          if child['itemType'] == 'Folder'
+            begin
+              child_folder = get(child['id'])
+              build_tree(child_folder, depth + 1, max_depth)
+            rescue StandardError => e
+              log_error "Failed to fetch child folder #{child['id']}: #{e.message}"
+              child
+            end
+          else
+            child
+          end
+        end
+
+        folder
+      end
+    end
+  end
+end