underpass 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51f76547b39510c69d96638663caf0078df8c28d410b3ca2941f775da5b16297
-  data.tar.gz: c929b78a88ef2e7fd52f4e329729128e37d283a33781c832df71afdec7c84d6b
+  metadata.gz: 7e5920d16962c26dd7711747653a0ce891250e870d2a675f51402354306a3e93
+  data.tar.gz: 1770e8e1e320916d9a53673df975ec1a7293d0d1064bdb0d68c2ab50cd168aeb
 SHA512:
-  metadata.gz: 9404c1959b9696c10fbf58fa633a7dc23e4bd173a0fe6f59735833e5b180f297a0285852fac32942dcbefac00b771e8240a4ac4f381922d2d86d8aa405756e50
-  data.tar.gz: c9687c1a6aaf9d99a06a44d017cb422831713027cfdc2b239b569fb160864e2ca3a01fe7ead7357d86d151a76af062d071f2ff636b261ffafca886bdf9b3110e
+  metadata.gz: f67e73666224ec23cf123b2803438a4b893359039da09fd9209506dea49b2b8685b04a8287955bc2c811224d786a9ca17be7ebcd22fc64242000147d10fe0ae8
+  data.tar.gz: dcbf032eae5a06497068f36861073dfa846d889c4bbab7681db81127a878824a70edb43dffb022bcae188afb8a40b2bea7deae6d3be9fc4cd429246fdf2e8fc4

data/README.md

@@ -34,25 +34,26 @@ WKT
 bbox = RGeo::Geographic.spherical_factory.parse_wkt(wkt)
 
 # Query using raw Overpass QL
-query = 'way["heritage:operator"="lmi"]["ref:ro:lmi"="MM-II-m-B-04508"];'
+query = 'way["heritage:operator"="lmi"]["heritage"="2"];'
 features = Underpass::QL::Query.perform(bbox, query)
 
 # Each result is a Feature with geometry and OSM tags
 features.each do |f|
   puts f.geometry.as_text     # => "POLYGON ((...)"
-  puts f.properties[:name]    # => "Some Heritage Building"
-  puts f.id                   # => 123456
+  puts f.properties[:name]    # => "Biserica Romano-Catolică"
+  puts f.id                   # => 186213580
   puts f.type                 # => "way"
 end
 ```
 
-See [more usage examples](usage-examples.md).
+See [more usage examples](docs/usage-examples.md).
 
-For comprehensive examples with real data covering all return types and functionality, see the [usage-examples.md](usage-examples.md) file which includes examples for:
+For comprehensive examples with real data covering all return types and functionality, see the [usage-examples.md](docs/usage-examples.md) file which includes examples for:
 - Node queries (Point geometries) - restaurants, cafes, etc.
 - Way queries (LineString/Polygon geometries) - roads, buildings, parks
 - Relation queries (MultiPolygon/MultiLineString geometries) - lakes, bus routes
 - Area queries using `perform_in_area`
+- Raw queries using `perform_raw` with inline bounding boxes
 - Around queries for proximity search
 - Builder DSL for constructing queries
 - Post-query filtering
@@ -90,9 +91,9 @@ query = Underpass::QL::Builder.new
 
 # Multiple tag filters
 query = Underpass::QL::Builder.new
-          .way('heritage:operator': 'lmi', 'ref:ro:lmi': 'MM-II-m-B-04508')
+          .way('heritage:operator': 'lmi', heritage: '2')
           .to_ql
-# => 'way["heritage:operator"="lmi"]["ref:ro:lmi"="MM-II-m-B-04508"];'
+# => 'way["heritage:operator"="lmi"]["heritage"="2"];'
 
 # nwr (node/way/relation) shorthand
 query = Underpass::QL::Builder.new
@@ -105,6 +106,27 @@ builder = Underpass::QL::Builder.new.way(building: 'yes')
 features = Underpass::QL::Query.perform(bbox, builder)
 ```
 
+### Bounding Box Queries with Builder DSL
+
+The Builder DSL is designed to work with `Query.perform`. Define a bounding box
+as an RGeo geometry, build your query with the DSL, and pass both to `perform`:
+
+```ruby
+# Define a bounding box
+wkt = 'POLYGON ((26.08 44.42, 26.12 44.42, 26.12 44.45, 26.08 44.45, 26.08 44.42))'
+bbox = RGeo::Geographic.spherical_factory.parse_wkt(wkt)
+
+# Build the query
+builder = Underpass::QL::Builder.new.node(amenity: 'cafe')
+
+# Execute — the bounding box constrains results spatially
+cafes = Underpass::QL::Query.perform(bbox, builder)
+```
+
+Note: The Builder DSL generates the Overpass QL query body (e.g. `node["amenity"="cafe"];`),
+while the bounding box is applied as a separate spatial constraint by `Query.perform`.
+You can inspect the generated query with `builder.to_ql`.
+
 ## Proximity Queries (Around)
 
 Find elements within a radius (in meters) of a point:
@@ -158,6 +180,21 @@ builder = Underpass::QL::Builder.new.node(amenity: 'restaurant')
 features = Underpass::QL::Query.perform_in_area('Romania', builder)
 ```
 
+## Raw Queries (Inline Bounding Box)
+
+When your query already contains its own bounding box (or other spatial filters)
+inline, use `perform_raw` to skip the global bounding box:
+
+```ruby
+query = 'node["name"="Peak"]["natural"="peak"](47.0,25.0,47.1,25.1);'
+features = Underpass::QL::Query.perform_raw(query)
+```
+
+The query body is wrapped in the standard Overpass request template (output format,
+timeout, recurse) but no global bounding box is added. This is useful when you
+construct queries with element-level bounding boxes or other spatial constraints
+that don't fit the `perform` / `perform_in_area` patterns.
+
 ## Relation Support
 
 ### Multipolygon Relations
@@ -334,6 +371,16 @@ Underpass.configure do |c|
 end
 ```
 
+### Custom Max Retries
+
+Change the maximum number of retry attempts for rate limiting and timeout errors (default: 3):
+
+```ruby
+Underpass.configure do |c|
+  c.max_retries = 5
+end
+```
+
 ### Reset Configuration
 
 ```ruby
@@ -344,24 +391,46 @@ Underpass.reset_configuration!
 
 The client automatically retries on transient errors with exponential backoff:
 
-- **HTTP 429** (rate limited) -- retries up to 3 times, then raises `Underpass::RateLimitError`
-- **HTTP 504** (gateway timeout) -- retries up to 3 times, then raises `Underpass::TimeoutError`
+- **HTTP 429** (rate limited) -- retries up to `max_retries` times (default: 3), then raises `Underpass::RateLimitError`
+- **HTTP 504** (gateway timeout) -- retries up to `max_retries` times (default: 3), then raises `Underpass::TimeoutError`
 - **Other errors** -- raises `Underpass::ApiError` immediately
 
 All errors inherit from `Underpass::Error`, which inherits from `StandardError`.
 
+### Structured Error Data
+
+Errors include structured data parsed from Overpass API responses:
+
 ```ruby
 begin
   features = Underpass::QL::Query.perform(bbox, query)
+rescue Underpass::TimeoutError => e
+  e.code           # => "timeout"
+  e.error_message  # => "Query timed out in \"query\" at line 3 after 25 seconds."
+  e.details        # => { line: 3, timeout_seconds: 25 }
+  e.http_status    # => 504
+
+  # Convert to hash or JSON for logging/APIs
+  e.to_h           # => { code: "timeout", message: "...", details: {...} }
+  e.to_json        # => JSON string
 rescue Underpass::RateLimitError
   puts "Rate limited by the Overpass API, try again later"
-rescue Underpass::TimeoutError
-  puts "Query timed out, try a smaller bounding box"
 rescue Underpass::ApiError => e
-  puts "API error: #{e.message}"
+  puts "API error (#{e.code}): #{e.error_message}"
 end
 ```
 
+### Error Codes
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| `timeout` | Query exceeded time limit | 504 |
+| `memory` | Query exceeded memory limit | 504 |
+| `rate_limit` | Too many requests | 429 |
+| `syntax` | Query syntax error | 400 |
+| `runtime` | Other runtime errors | varies |
+| `unknown` | Unparseable error | varies |
+
 ## Response Caching
 
 Enable in-memory caching to avoid redundant API calls during development:
@@ -409,7 +478,7 @@ Have a look at the [issue tracker](https://github.com/haiafara/underpass/issues)
 
 ## Comprehensive Examples
 
-For detailed, working examples with real data that cover all return types and functionality of the library, see the [usage-examples.md](usage-examples.md) file. These examples demonstrate:
+For detailed, working examples with real data that cover all return types and functionality of the library, see the [usage-examples.md](docs/usage-examples.md) file. These examples demonstrate:
 
 - **Node queries** (Point geometries) - restaurants, cafes, bus stops
 - **Way queries** (LineString geometries) - primary roads, highways

data/lib/underpass/client.rb

@@ -10,20 +10,18 @@ module Underpass
   # Handles caching of responses and automatic retries with exponential
   # backoff for rate limiting (429) and timeout (504) responses.
   class Client
-    # @return [Integer] default maximum number of retries
-    MAX_RETRIES = 3
-
     # Performs the API request with automatic retries for rate limiting and timeouts.
     #
     # Results are cached when a {Cache} instance is configured via {Underpass.cache}.
     #
     # @param request [QL::Request] the prepared Overpass query request
-    # @param max_retries [Integer] maximum number of retry attempts
+    # @param max_retries [Integer] maximum number of retry attempts (defaults to configured value)
     # @return [Net::HTTPResponse] the API response
     # @raise [RateLimitError] when rate limited after exhausting retries
     # @raise [TimeoutError] when the API times out after exhausting retries
     # @raise [ApiError] when the API returns an unexpected error
-    def self.perform(request, max_retries: MAX_RETRIES)
+    def self.perform(request, max_retries: nil)
+      max_retries = Underpass.configuration.max_retries if max_retries.nil?
       cache_key = Digest::SHA256.hexdigest(request.to_query)
       cached = Underpass.cache&.fetch(cache_key)
       return cached if cached
@@ -54,14 +52,28 @@ module Underpass
     private_class_method :post_request
 
     def self.handle_error(response, retries, max_retries)
-      error_class = { 429 => RateLimitError, 504 => TimeoutError }[response.code.to_i]
-      raise ApiError, "Overpass API returned #{response.code}: #{response.body}" unless error_class
+      status_code = response.code.to_i
+      error_class = { 429 => RateLimitError, 504 => TimeoutError }[status_code] || ApiError
+
+      raise build_error(error_class, response.body, status_code) if error_class == ApiError
 
       retries += 1
-      raise error_class, "#{error_class} after #{max_retries} retries" if retries > max_retries
+      raise build_error(error_class, response.body, status_code) if retries > max_retries
 
       retries
     end
     private_class_method :handle_error
+
+    def self.build_error(error_class, body, status_code)
+      parsed = ErrorParser.parse(body, status_code)
+      error_class.new(
+        parsed[:message],
+        code: parsed[:code],
+        error_message: parsed[:message],
+        details: parsed[:details],
+        http_status: status_code
+      )
+    end
+    private_class_method :build_error
   end
 end

data/lib/underpass/configuration.rb

@@ -7,6 +7,7 @@ module Underpass
   #   Underpass.configure do |config|
   #     config.api_endpoint = 'https://overpass.kumi.systems/api/interpreter'
   #     config.timeout = 30
+  #     config.max_retries = 5
   #   end
   class Configuration
     # @return [String] the Overpass API endpoint URL
@@ -15,9 +16,13 @@ module Underpass
     # @return [Integer] the query timeout in seconds
     attr_accessor :timeout
 
+    # @return [Integer] maximum number of retry attempts for rate limiting and timeouts
+    attr_accessor :max_retries
+
     def initialize
       @api_endpoint = 'https://overpass-api.de/api/interpreter'
       @timeout = 25
+      @max_retries = 3
     end
   end
 end

data/lib/underpass/error_parser.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Underpass
+  # Parses HTML error responses from the Overpass API into structured data.
+  #
+  # The Overpass API returns HTML error pages when queries fail. This class
+  # extracts error information from those responses and returns structured
+  # hashes with code, message, and details.
+  #
+  # @example
+  #   result = ErrorParser.parse("<html>...runtime error: Query timed out...</html>", 504)
+  #   result[:code]    # => "timeout"
+  #   result[:message] # => "Query timed out in \"query\" at line 3 after 25 seconds."
+  #   result[:details] # => { line: 3, timeout_seconds: 25 }
+  class ErrorParser
+    # Known error patterns from Overpass API responses
+    PATTERNS = {
+      timeout: /Query timed out.*?at line (\d+) after (\d+) seconds/i,
+      memory: /Query run out of memory.*?(\d+)\s*MB/i,
+      syntax: /parse error:?\s*(.+)/i,
+      runtime: /runtime error:?\s*(.+)/i
+    }.freeze
+
+    # Parses an error response body and returns structured error data.
+    #
+    # @param response_body [String] the raw response body (usually HTML)
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data with :code, :message, and :details keys
+    def self.parse(response_body, status_code)
+      return rate_limit_result if status_code == 429
+
+      text = extract_error_text(response_body)
+      parse_error_text(text, status_code)
+    end
+
+    # Extracts error text from HTML or returns the body as-is.
+    #
+    # @param body [String] the response body
+    # @return [String] the extracted error text
+    def self.extract_error_text(body)
+      return '' if body.nil? || body.empty?
+
+      # Try to extract text from <strong> tags (common Overpass error format)
+      if (match = body.match(%r{<strong[^>]*>(.*?)</strong>}im))
+        return match[1].gsub(/<[^>]+>/, '').strip
+      end
+
+      # Try to extract from <p> tags
+      if (match = body.match(%r{<p[^>]*>(.*?)</p>}im))
+        return match[1].gsub(/<[^>]+>/, '').strip
+      end
+
+      # Fall back to stripping all HTML tags
+      body.gsub(/<[^>]+>/, ' ').gsub(/\s+/, ' ').strip
+    end
+    private_class_method :extract_error_text
+
+    # Parses the error text against known patterns.
+    #
+    # @param text [String] the extracted error text
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data
+    def self.parse_error_text(text, status_code)
+      parse_timeout(text) ||
+        parse_memory(text) ||
+        parse_syntax(text) ||
+        parse_runtime(text) ||
+        unknown_result(text, status_code)
+    end
+    private_class_method :parse_error_text
+
+    def self.parse_timeout(text)
+      return unless (match = text.match(PATTERNS[:timeout]))
+
+      { code: 'timeout', message: text, details: { line: match[1].to_i, timeout_seconds: match[2].to_i } }
+    end
+    private_class_method :parse_timeout
+
+    def self.parse_memory(text)
+      return unless (match = text.match(PATTERNS[:memory]))
+
+      { code: 'memory', message: text, details: { memory_mb: match[1].to_i } }
+    end
+    private_class_method :parse_memory
+
+    def self.parse_syntax(text)
+      return unless (match = text.match(PATTERNS[:syntax]))
+
+      { code: 'syntax', message: match[1].strip, details: extract_syntax_details(match[1]) }
+    end
+    private_class_method :parse_syntax
+
+    def self.parse_runtime(text)
+      return unless (match = text.match(PATTERNS[:runtime]))
+
+      { code: 'runtime', message: match[1].strip, details: {} }
+    end
+    private_class_method :parse_runtime
+
+    # Extracts line number from syntax error messages if present.
+    #
+    # @param message [String] the error message
+    # @return [Hash] details hash with line number if found
+    def self.extract_syntax_details(message)
+      if (match = message.match(/line\s+(\d+)/i))
+        { line: match[1].to_i }
+      else
+        {}
+      end
+    end
+    private_class_method :extract_syntax_details
+
+    # Returns a rate limit error result.
+    #
+    # @return [Hash] structured error data for rate limiting
+    def self.rate_limit_result
+      {
+        code: 'rate_limit',
+        message: 'Rate limited by the Overpass API',
+        details: {}
+      }
+    end
+    private_class_method :rate_limit_result
+
+    # Returns an unknown error result.
+    #
+    # @param text [String] the error text
+    # @param status_code [Integer] the HTTP status code
+    # @return [Hash] structured error data for unknown errors
+    def self.unknown_result(text, status_code)
+      message = text.empty? ? "HTTP #{status_code} error" : text
+      {
+        code: 'unknown',
+        message: message,
+        details: {}
+      }
+    end
+    private_class_method :unknown_result
+  end
+end

data/lib/underpass/errors.rb

@@ -1,8 +1,69 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Underpass
   # Base error class for all Underpass errors.
-  class Error < StandardError; end
+  #
+  # Provides structured error data parsed from Overpass API responses.
+  #
+  # @example
+  #   begin
+  #     features = Underpass::QL::Query.perform(bbox, query)
+  #   rescue Underpass::Error => e
+  #     e.code           # => "timeout"
+  #     e.error_message  # => "Query timed out..."
+  #     e.details        # => { line: 3, timeout_seconds: 25 }
+  #     e.http_status    # => 504
+  #     e.to_h           # => { code: "timeout", message: "...", details: {...} }
+  #   end
+  class Error < StandardError
+    # @return [String, nil] the error code (e.g., "timeout", "memory", "syntax")
+    attr_reader :code
+
+    # @return [String, nil] the human-readable error message
+    attr_reader :error_message
+
+    # @return [Hash] additional error details (varies by error type)
+    attr_reader :details
+
+    # @return [Integer, nil] the HTTP status code from the API response
+    attr_reader :http_status
+
+    # Creates a new error with optional structured data.
+    #
+    # @param message [String, nil] the error message (used by StandardError)
+    # @param code [String, nil] the error code
+    # @param error_message [String, nil] the detailed error message
+    # @param details [Hash] additional error details
+    # @param http_status [Integer, nil] the HTTP status code
+    def initialize(message = nil, code: nil, error_message: nil, details: {}, http_status: nil)
+      @code = code
+      @error_message = error_message || message
+      @details = details || {}
+      @http_status = http_status
+      super(@error_message || message)
+    end
+
+    # Returns a hash representation of the error.
+    #
+    # @return [Hash] the error as a hash with :code, :message, and :details keys
+    def to_h
+      {
+        code: code,
+        message: error_message,
+        details: details
+      }
+    end
+
+    # Returns a JSON representation of the error.
+    #
+    # @param args [Array] arguments passed to JSON.generate
+    # @return [String] the error as a JSON string
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
 
   # Raised when the Overpass API returns a 429 rate limit response.
   class RateLimitError < Error; end

data/lib/underpass/ql/query.rb

@@ -13,6 +13,10 @@ module Underpass
     #
     # @example Query with a named area
     #   features = Underpass::QL::Query.perform_in_area('Romania', 'node["place"="city"];')
+    #
+    # @example Raw query with inline bounding box
+    #   query = 'node["name"="Peak"]["natural"="peak"](47.0,25.0,47.1,25.1);'
+    #   features = Underpass::QL::Query.perform_raw(query)
     class Query
       # Queries the Overpass API within a bounding box.
       #
@@ -43,6 +47,21 @@ module Underpass
         execute(request, query_string)
       end
 
+      # Executes a pre-built query body that includes its own inline bbox.
+      # Wraps it in the standard Request template for output format and timeout,
+      # without adding a global bounding box.
+      #
+      # @param query_body [String] Overpass QL body with inline bbox
+      #   (e.g. +'node["name"="Peak"]["natural"="peak"](47.0,25.0,47.1,25.1);'+)
+      # @return [Array<Feature>] the matched features
+      # @raise [RateLimitError] when rate limited after exhausting retries
+      # @raise [TimeoutError] when the API times out after exhausting retries
+      # @raise [ApiError] when the API returns an unexpected error
+      def self.perform_raw(query_body)
+        request = Underpass::QL::Request.new(query_body, nil)
+        execute(request, query_body)
+      end
+
       def self.resolve_query(query)
         query.respond_to?(:to_ql) ? query.to_ql : query
       end

data/lib/underpass/version.rb

@@ -13,7 +13,7 @@ module Underpass
   module VERSION
     MAJOR = 0
     MINOR = 9
-    PATCH = 0
+    PATCH = 1
 
     STRING = [MAJOR, MINOR, PATCH].join('.')
   end

data/lib/underpass.rb

@@ -6,6 +6,7 @@ require 'json'
 require 'underpass/cache'
 require 'underpass/configuration'
 require 'underpass/errors'
+require 'underpass/error_parser'
 require 'underpass/client'
 require 'underpass/feature'
 require 'underpass/filter'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: underpass
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Janos Rusiczki
@@ -50,6 +50,7 @@ files:
 - lib/underpass/cache.rb
 - lib/underpass/client.rb
 - lib/underpass/configuration.rb
+- lib/underpass/error_parser.rb
 - lib/underpass/errors.rb
 - lib/underpass/feature.rb
 - lib/underpass/filter.rb