wreq 1.0.0

data/lib/wreq_ruby/emulation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Wreq
+  # Device emulation enumeration backed by Rust.
+  #
+  # Variants are exposed as constants under this class.
+  # Each constant is an instance of {Wreq::EmulationDevice}.
+  #
+  # @example Using predefined constants
+  #   device = Wreq::EmulationDevice::Chrome117
+  #   device.class #=> Wreq::EmulationDevice
+  class EmulationDevice
+    # Constants are set by the native extension at initialization.
+    # These stubs are for documentation only.
+    unless const_defined?(:Chrome100)
+      Chrome100 = nil
+      Chrome101 = nil
+      Chrome104 = nil
+      Chrome105 = nil
+      Chrome106 = nil
+      Chrome107 = nil
+      Chrome108 = nil
+      Chrome109 = nil
+      Chrome110 = nil
+      Chrome114 = nil
+      Chrome116 = nil
+      Chrome117 = nil
+      Chrome118 = nil
+      Chrome119 = nil
+      Chrome120 = nil
+      Chrome123 = nil
+      Chrome124 = nil
+      Chrome126 = nil
+      Chrome127 = nil
+      Chrome128 = nil
+      Chrome129 = nil
+      Chrome130 = nil
+      Chrome131 = nil
+      Chrome132 = nil
+      Chrome133 = nil
+      Chrome134 = nil
+      Chrome135 = nil
+      Chrome136 = nil
+      Chrome137 = nil
+      Chrome138 = nil
+      Chrome139 = nil
+      Chrome140 = nil
+      Chrome141 = nil
+      Chrome142 = nil
+      Chrome143 = nil
+      Chrome144 = nil
+      Chrome145 = nil
+      Edge101 = nil
+      Edge122 = nil
+      Edge127 = nil
+      Edge131 = nil
+      Edge134 = nil
+      Edge135 = nil
+      Edge136 = nil
+      Edge137 = nil
+      Edge138 = nil
+      Edge139 = nil
+      Edge140 = nil
+      Edge141 = nil
+      Edge142 = nil
+      Edge143 = nil
+      Edge144 = nil
+      Edge145 = nil
+      Firefox109 = nil
+      Firefox117 = nil
+      Firefox128 = nil
+      Firefox133 = nil
+      Firefox135 = nil
+      FirefoxPrivate135 = nil
+      FirefoxAndroid135 = nil
+      Firefox136 = nil
+      FirefoxPrivate136 = nil
+      Firefox139 = nil
+      Firefox142 = nil
+      Firefox143 = nil
+      Firefox144 = nil
+      Firefox145 = nil
+      Firefox146 = nil
+      Firefox147 = nil
+      SafariIos17_2 = nil
+      SafariIos17_4_1 = nil
+      SafariIos16_5 = nil
+      Safari15_3 = nil
+      Safari15_5 = nil
+      Safari15_6_1 = nil
+      Safari16 = nil
+      Safari16_5 = nil
+      Safari17_0 = nil
+      Safari17_2_1 = nil
+      Safari17_4_1 = nil
+      Safari17_5 = nil
+      Safari17_6 = nil
+      Safari18 = nil
+      SafariIPad18 = nil
+      Safari18_2 = nil
+      Safari18_3 = nil
+      Safari18_3_1 = nil
+      SafariIos18_1_1 = nil
+      Safari18_5 = nil
+      Safari26 = nil
+      Safari26_1 = nil
+      Safari26_2 = nil
+      SafariIos26 = nil
+      SafariIos26_2 = nil
+      SafariIPad26 = nil
+      SafariIpad26_2 = nil
+      OkHttp3_9 = nil
+      OkHttp3_11 = nil
+      OkHttp3_13 = nil
+      OkHttp3_14 = nil
+      OkHttp4_9 = nil
+      OkHttp4_10 = nil
+      OkHttp4_12 = nil
+      OkHttp5 = nil
+      Opera116 = nil
+      Opera117 = nil
+      Opera118 = nil
+      Opera119 = nil
+    end
+
+    unless method_defined?(:to_s)
+      # Returns a string representation of the emulation device.
+      # @return [String] Emulation device as string
+      def to_s
+      end
+    end
+  end
+
+  # Operating system emulation enumeration backed by Rust.
+  #
+  # Variants are exposed as constants under this class.
+  # Each constant is an instance of {Wreq::EmulationOS}.
+  #
+  # @example Using predefined constants
+  #   os = Wreq::EmulationOS::Windows
+  #   os.class #=> Wreq::EmulationOS
+  class EmulationOS
+    # Constants are set by the native extension at initialization.
+    # These stubs are for documentation only.
+    unless const_defined?(:Windows)
+      Windows = nil
+      MacOS = nil
+      Linux = nil
+      Android = nil
+      IOS = nil
+    end
+
+    unless method_defined?(:to_s)
+      # Returns a string representation of the emulation OS.
+      # @return [String] Emulation OS as string
+      def to_s
+      end
+    end
+  end
+
+  # Emulation option wrapper.
+  #
+  # This class wraps device and OS emulation options and provides
+  # a unified interface for browser environment simulation.
+  # The actual implementation is provided by Rust for performance.
+  #
+  # @example Create an emulation option
+  #   emu = Wreq::Emulation.new(device: Wreq::EmulationDevice::Chrome117, os: Wreq::EmulationOS::Windows)
+  #
+  # @param device [Wreq::EmulationDevice] Device profile (optional)
+  # @param os [Wreq::EmulationOS] Operating system profile (optional)
+  # @param skip_http2 [Boolean] Whether to skip HTTP/2 (optional)
+  # @param skip_headers [Boolean] Whether to skip default headers (optional)
+  class Emulation
+    # Native fields and methods are set by the extension.
+    # This stub is for documentation only.
+    unless method_defined?(:new)
+      # @param device [Wreq::EmulationDevice] Device profile (optional)
+      # @param os [Wreq::EmulationOS] Operating system profile (optional)
+      # @param skip_http2 [Boolean] Whether to skip HTTP/2 (optional)
+      # @param skip_headers [Boolean] Whether to skip default headers (optional)
+      def self.new(device: nil, os: nil, skip_http2: false, skip_headers: false)
+      end
+    end
+  end
+end

data/lib/wreq_ruby/error.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+unless defined?(Wreq)
+  module Wreq
+    # System-level and runtime errors
+
+    # Memory allocation failed.
+    class MemoryError < StandardError; end
+
+    # Network connection errors
+
+    # Connection to the server failed.
+    #
+    # Raised when the client cannot establish a connection to the server.
+    #
+    # @example
+    #   begin
+    #     client.get("http://localhost:9999")
+    #   rescue Wreq::ConnectionError => e
+    #     puts "Connection failed: #{e.message}"
+    #     retry_with_backoff
+    #   end
+    class ConnectionError < StandardError; end
+
+    # Proxy Connection to the server failed.
+    #
+    # Raised when the client cannot establish a connection to the proxy server.
+    # @example
+    #   begin
+    #     client.get("http://example.com", proxy: "http://invalid-proxy:8080")
+    #   rescue Wreq::ProxyConnectionError => e
+    #     puts "Proxy connection failed: #{e.message}"
+    #     retry_with_different_proxy
+    #   end
+    class ProxyConnectionError < StandardError; end
+
+    # Connection was reset by the server.
+    #
+    # Raised when the server closes the connection unexpectedly.
+    #
+    # @example
+    #   rescue Wreq::ConnectionResetError => e
+    #     puts "Connection reset: #{e.message}"
+    #   end
+    class ConnectionResetError < StandardError; end
+
+    # TLS/SSL error occurred.
+    #
+    # Raised when there's an error with TLS/SSL, such as certificate
+    # verification failure or protocol mismatch.
+    #
+    # @example
+    #   begin
+    #     client.get("https://self-signed.badssl.com")
+    #   rescue Wreq::TlsError => e
+    #     puts "TLS error: #{e.message}"
+    #   end
+    unless const_defined?(:TlsError)
+      class TlsError < StandardError; end
+    end
+
+    # HTTP protocol and request/response errors
+
+    # Request failed.
+    #
+    # Generic error for request failures that don't fit other categories.
+    #
+    # @example
+    #   rescue Wreq::RequestError => e
+    #     puts "Request failed: #{e.message}"
+    #   end
+    class RequestError < StandardError; end
+
+    # HTTP status code indicates an error.
+    #
+    # Raised when the server returns an error status code (4xx or 5xx).
+    #
+    # @example
+    #   begin
+    #     response = client.get("https://httpbin.io/status/404")
+    #   rescue Wreq::StatusError => e
+    #     puts "HTTP error: #{e.message}"
+    #     # e.response contains the full response
+    #   end
+    class StatusError < StandardError; end
+
+    # Redirect handling failed.
+    #
+    # Raised when too many redirects occur or redirect logic fails.
+    #
+    # @example
+    #   begin
+    #     client = Wreq::Client.new(max_redirects: 3)
+    #     client.get("https://httpbin.io/redirect/10")
+    #   rescue Wreq::RedirectError => e
+    #     puts "Too many redirects: #{e.message}"
+    #   end
+    class RedirectError < StandardError; end
+
+    # Request timed out.
+    #
+    # Raised when the request exceeds the configured timeout.
+    #
+    # @example
+    #   begin
+    #     client = Wreq::Client.new(timeout: 5)
+    #     client.get("https://httpbin.io/delay/10")
+    #   rescue Wreq::TimeoutError => e
+    #     puts "Request timed out: #{e.message}"
+    #     retry_with_longer_timeout
+    #   end
+    class TimeoutError < StandardError; end
+
+    # Data processing and encoding errors
+
+    # Response body processing failed.
+    #
+    # Raised when there's an error reading or processing the response body.
+    #
+    # @example
+    #   rescue Wreq::BodyError => e
+    #     puts "Body error: #{e.message}"
+    #   end
+    class BodyError < StandardError; end
+
+    # Decoding response failed.
+    #
+    # Raised when response content cannot be decoded (e.g., invalid UTF-8,
+    # malformed JSON, corrupted compression).
+    #
+    # @example
+    #   begin
+    #     response = client.get("https://example.com/invalid-utf8")
+    #     response.text  # May raise DecodingError
+    #   rescue Wreq::DecodingError => e
+    #     puts "Decoding error: #{e.message}"
+    #     # Fall back to binary data
+    #     data = response.body
+    #   end
+    class DecodingError < StandardError; end
+
+    # Configuration and builder errors
+
+    # Client configuration is invalid.
+    #
+    # Raised when the client is configured with invalid options.
+    #
+    # @example
+    #   begin
+    #     client = Wreq::Client.new(
+    #       proxy: "invalid://proxy",
+    #       timeout: -1
+    #     )
+    #   rescue Wreq::BuilderError => e
+    #     puts "Invalid configuration: #{e.message}"
+    #   end
+    class BuilderError < StandardError; end
+  end
+end

data/lib/wreq_ruby/header.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+unless defined?(Wreq)
+  module Wreq
+    # HTTP headers collection.
+    #
+    # Provides efficient access to HTTP headers with case-insensitive lookups.
+    # Headers are created by the native extension and cannot be directly instantiated.
+    #
+    # All header names are case-insensitive. Multiple values for the same header
+    # are supported through the `get_all` method.
+    #
+    # @example Accessing response headers
+    #   response = Wreq.get("https://example.com")
+    #   headers = response.headers
+    #   content_type = headers["Content-Type"]
+    #   content_type = headers.get("content-type")  # Same, case-insensitive
+    #
+    # @example Getting all values for a header
+    #   accept_values = headers.get_all("Accept")
+    #   # => ["application/json", "text/html"]
+    #
+    # @example Modifying headers
+    #   headers.set("X-Custom-Header", "value")
+    #   headers["Authorization"] = "Bearer token"
+    #   headers.append("Accept", "application/xml")
+    #
+    # @example Iterating headers
+    #   headers.each do |name, value|
+    #     puts "#{name}: #{value}"
+    #   end
+    #
+    # @example Converting to hash
+    #   hash = headers.to_h
+    #   hash["content-type"]  # => "text/html"
+    class Headers
+      # Create a new empty Headers collection.
+      #
+      # @return [Wreq::Headers] New headers instance
+      # @example
+      #   headers = Wreq::Headers.new
+      #   headers.set("Content-Type", "application/json")
+      def self.new
+      end
+
+      # Get a header value by name (case-insensitive).
+      #
+      # Returns the first value if multiple values exist for the same header.
+      #
+      # @param name [String] Header name (case-insensitive)
+      # @return [String, nil] Header value, or nil if not found
+      # @example
+      #   headers.get("Content-Type")       # => "application/json"
+      #   headers.get("content-type")       # => "application/json" (same)
+      #   headers.get("X-Nonexistent")      # => nil
+      def get(name)
+      end
+
+      # Get all values for a header name (case-insensitive).
+      #
+      # Useful when a header can have multiple values (e.g., Accept, Set-Cookie).
+      #
+      # @param name [String] Header name (case-insensitive)
+      # @return [Array<String>] All values for this header (empty array if not found)
+      # @example
+      #   headers.get_all("Accept")
+      #   # => ["application/json", "text/html", "application/xml"]
+      #   headers.get_all("X-Nonexistent")  # => []
+      def get_all(name)
+      end
+
+      # Set a header value, replacing any existing values.
+      #
+      # @param name [String] Header name
+      # @param value [String] Header value
+      # @return [void]
+      # @raise [Wreq::BuilderError] if name or value contains invalid characters
+      # @example
+      #   headers.set("Content-Type", "application/json")
+      #   headers.set("X-Custom-Header", "my-value")
+      def set(name, value)
+      end
+
+      # Append a header value without replacing existing values.
+      #
+      # Adds a new value for the header, preserving any existing values.
+      # Useful for headers that can have multiple values.
+      #
+      # @param name [String] Header name
+      # @param value [String] Header value to append
+      # @return [void]
+      # @raise [Wreq::BuilderError] if name or value contains invalid characters
+      # @example
+      #   headers.set("Accept", "application/json")
+      #   headers.append("Accept", "text/html")
+      #   headers.get_all("Accept")  # => ["application/json", "text/html"]
+      def append(name, value)
+      end
+
+      # Remove all values for a header name.
+      #
+      # @param name [String] Header name (case-insensitive)
+      # @return [String, nil] The removed value (first one if multiple), or nil
+      # @example
+      #   headers.remove("Authorization")  # => "Bearer token"
+      #   headers.remove("X-Nonexistent")  # => nil
+      def remove(name)
+      end
+
+      # Check if a header exists (case-insensitive).
+      #
+      # @param name [String] Header name
+      # @return [Boolean] true if the header exists
+      # @example
+      #   headers.contains?("Content-Type")  # => true
+      #   headers.contains?("X-Missing")     # => false
+      def contains?(name)
+      end
+
+      # Check if a header key exists (alias for {#contains?}).
+      #
+      # @param name [String] Header name
+      # @return [Boolean] true if the header exists
+      # @example
+      #   headers.key?("Accept")  # => true
+      def key?(name)
+      end
+
+      # Get the number of headers.
+      #
+      # @return [Integer] Total number of unique header names
+      # @example
+      #   headers.length  # => 12
+      def length
+      end
+
+      # Check if there are no headers.
+      #
+      # @return [Boolean] true if no headers exist
+      # @example
+      #   headers.empty?  # => false
+      def empty?
+      end
+
+      # Remove all headers.
+      #
+      # @return [void]
+      # @example
+      #   headers.clear
+      #   headers.empty?  # => true
+      def clear
+      end
+
+      # Get all header names.
+      #
+      # @return [Array<String>] Array of header names (lowercase)
+      # @example
+      #   headers.keys
+      #   # => ["content-type", "accept", "user-agent", "authorization"]
+      def keys
+      end
+
+      # Get all header values.
+      #
+      # Returns one value per header (the first if multiple values exist).
+      #
+      # @return [Array<String>] Array of header values
+      # @example
+      #   headers.values
+      #   # => ["application/json", "text/html", "Mozilla/5.0", "Bearer token"]
+      def values
+      end
+
+      # Iterate over headers.
+      #
+      # Yields each header name and value pair. If a header has multiple values,
+      # only the first is yielded.
+      #
+      # @yieldparam name [String] Header name (lowercase)
+      # @yieldparam value [String] Header value
+      # @return [Enumerator, self] Returns enumerator if no block given, self otherwise
+      # @example With block
+      #   headers.each do |name, value|
+      #     puts "#{name}: #{value}"
+      #   end
+      # @example Without block
+      #   enum = headers.each
+      #   enum.to_a  # => [["content-type", "text/html"], ...]
+      def each
+      end
+
+      # Convert headers to a string representation.
+      def to_s
+      end
+    end
+  end
+end

data/lib/wreq_ruby/http.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Wreq
+  # HTTP method enumeration backed by Rust.
+  #
+  # Variants are exposed as constants under this class.
+  # Each constant is an instance of {Wreq::Method}.
+  #
+  # @example Using predefined constants
+  #   method = Wreq::Method::GET
+  #   method.class #=> Wreq::Method
+  #
+  # @example In request context
+  #   Wreq.request(url: "https://api.example.com", method: Wreq::Method::POST)
+  class Method
+    # Constants are set by the native extension at initialization.
+    # These stubs are for documentation only.
+    unless const_defined?(:GET)
+      GET = nil # @return [Wreq::Method] HTTP GET method
+      HEAD = nil # @return [Wreq::Method] HTTP HEAD method
+      POST = nil # @return [Wreq::Method] HTTP POST method
+      PUT = nil # @return [Wreq::Method] HTTP PUT method
+      DELETE = nil # @return [Wreq::Method] HTTP DELETE method
+      OPTIONS = nil # @return [Wreq::Method] HTTP OPTIONS method
+      TRACE = nil # @return [Wreq::Method] HTTP TRACE method
+      PATCH = nil # @return [Wreq::Method] HTTP PATCH method
+    end
+  end
+
+  # HTTP version enumeration backed by Rust.
+  #
+  # @example Using predefined constants
+  #   version = Wreq::Version::HTTP_11
+  #   version.class #=> Wreq::Version
+  class Version
+    # Constants are set by the native extension at initialization.
+    # These stubs are for documentation only.
+    unless const_defined?(:HTTP_11)
+      HTTP_09 = nil # @return [Wreq::Version] HTTP/0.9
+      HTTP_10 = nil # @return [Wreq::Version] HTTP/1.0
+      HTTP_11 = nil # @return [Wreq::Version] HTTP/1.1
+      HTTP_2 = nil # @return [Wreq::Version] HTTP/2
+      HTTP_3 = nil # @return [Wreq::Version] HTTP/3
+    end
+
+    # Returns a string representation of the HTTP version.
+    # @return [String] HTTP version as string
+    unless method_defined?(:to_s)
+      def to_s
+      end
+    end
+  end
+
+  # HTTP status code wrapper.
+  #
+  # This class wraps standard HTTP status codes and provides
+  # convenient methods to check the response category.
+  #
+  # The actual implementation is provided by Rust for performance.
+  #
+  # @example Check if response is successful
+  #   status = response.status
+  #   if status.success?
+  #     puts "Request succeeded with code: #{status.as_int}"
+  #   end
+  #
+  # @example Check different status categories
+  #   status.informational?  # 1xx
+  #   status.success?        # 2xx
+  #   status.redirection?    # 3xx
+  #   status.client_error?   # 4xx
+  #   status.server_error?   # 5xx
+  unless const_defined?(:StatusCode)
+    class StatusCode
+      # Returns the status code as an integer.
+      #
+      # @return [Integer] the numeric HTTP status code (100-599)
+      def as_int
+      end
+
+      # Checks if status code is informational (1xx).
+      #
+      # Informational responses indicate that the request was received
+      # and the process is continuing.
+      #
+      # @return [Boolean] true if status is 100-199
+      def informational?
+      end
+
+      # Checks if status code indicates success (2xx).
+      #
+      # Success responses indicate that the request was successfully
+      # received, understood, and accepted.
+      #
+      # @return [Boolean] true if status is 200-299
+      def success?
+      end
+
+      # Checks if status code indicates redirection (3xx).
+      #
+      # Redirection responses indicate that further action needs to be
+      # taken to complete the request.
+      #
+      # @return [Boolean] true if status is 300-399
+      def redirection?
+      end
+
+      # Checks if status code indicates client error (4xx).
+      #
+      # Client error responses indicate that the request contains bad
+      # syntax or cannot be fulfilled.
+      #
+      # @return [Boolean] true if status is 400-499
+      def client_error?
+      end
+
+      # Checks if status code indicates server error (5xx).
+      #
+      # Server error responses indicate that the server failed to
+      # fulfill a valid request.
+      #
+      # @return [Boolean] true if status is 500-599
+      def server_error?
+      end
+
+      # Returns a string representation of the status code.
+      # @return [String] Status code as string
+      def to_s
+      end
+    end
+  end
+end