ipdata 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecd1e1860fb3d422c8aea50274e10528dd45d12c4555de9585e7af64f06de450
-  data.tar.gz: f7ad0dcf1f3fd4a526e5ebe64b901c848f4c5cab432ebe33d0a897f72f9c500d
+  metadata.gz: e7127035fac487a80213a19c0076dd279854a26ed9409ebd33cfd99939472a3e
+  data.tar.gz: 61e8191443dc04b4d4cc5367c110d6afeeb2d1c3e121b2659078793978338d98
 SHA512:
-  metadata.gz: 5c3e379a60cd06fc5a5e38aca4680d2014c6b2324bd2587cb108310c0c1356cfc294bd2082ed1d3278e4b7950e5df1c0ff0d7da89be6f40d2b307e63eebdf0e9
-  data.tar.gz: 18f91231a4c26f1c3ba5f2e86436eff0ca22a2b8078f9749af994ace74de4707c4c95d0416344ed658ca186504bdbb3ebfbdec669466ce00d8c6c1a095ad8377
+  metadata.gz: 7d3b43d466e48c1808adb3faf419ebc2e4dd3a0dd8f0074e2989ab3c74df264630c5fe5d6cf429c84e09ddc577b48e37f05580957c678e5a3ba92a53735d7485
+  data.tar.gz: 26db682141596dd33486a38c392a8e8cf408eb0346593c75cd44c3ccfca843993ac0f740cc089cb987dc9541155d93f76c165a67c898b970779119fc2f1a35f8

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Change Log
+
+## 0.2.0
+
+### Added
+
+- Connection reuse: an `IPData::Client` keeps one persistent HTTPS connection (HTTP/1.1 keep-alive) for its lifetime instead of opening a new TLS connection for every request. Create one client and reuse it. New option `keep_alive_timeout:` (seconds, default 60) for the client-side idle timeout, and new method `Client#close` to finish the connection at shutdown; the client reconnects on demand. A client is safe to share between threads (requests are serialised on its connection) and reconnects in a forked child without closing the parent's socket.
+- `Response#is_satellite` and `Response#is_anycast`: the API sends these top-level booleans only when they are true; the readers return `false` when the key is absent, while `response["is_satellite"]`, `key?` and `to_h` reflect the raw response. Both names can be requested through `fields:` and `select_field:`.
+- `threat.blocklists` entries carry `first_seen`, `last_seen` (`"YYYY-MM-DD"`, UTC) and `days_seen` when the feed reports them; some feeds omit all three.
+
+### Changed
+
+- `timeout:` now also applies to writes (previously only to connecting and reading).
+- `bulk_lookup` (`POST /bulk`) is retried once, on a fresh connection, when a reused connection died before any response byte arrived; `lookup` (`GET`) was already retried once by `Net::HTTP`. Nothing is retried on an HTTP error status.
+- The `User-Agent` header is now `ipdata-ruby/<version> Ruby/<ruby-version> (<platform>)` instead of `ruby-ipdata/...`.
+- Gem metadata: the homepage is now https://ipdata.co; `source_code_uri` keeps pointing at this repository.
+
+### Fixed
+
+- `use_ssl` follows the scheme of `base_url:`, so plain `http://` base URLs work; it used to be always on.
+- `lookup(select_field: "city")` without an IP address requests `/city` instead of `//city`.
+- A `base_url:` with a path prefix (for example `https://example.com/ipdata`) keeps that prefix in front of every request path instead of losing it.
+
+## 0.1.5
+
+Initial release on RubyGems: `lookup` for the caller's own IP or a given IP with `fields:` and `select_field:`, `bulk_lookup` for up to 100 addresses, `Client.eu` for the EU endpoint, an in-memory LRU cache with TTL, typed errors (`AuthenticationError`, `ForbiddenError`, `BadRequestError`) and no runtime dependencies.

data/README.md

@@ -118,9 +118,32 @@ client.lookup("8.8.8.8") # served from cache
 ### Custom Timeout
 
 ```ruby
-client = IPData::Client.new("YOUR_API_KEY", timeout: 10) # 10 seconds
+client = IPData::Client.new("YOUR_API_KEY", timeout: 10) # 10 seconds to connect, read and write
 ```
 
+## Connection reuse
+
+An `IPData::Client` keeps one persistent HTTPS connection (HTTP/1.1 keep-alive) for as long as it lives. Create one client per process (or one per API key or endpoint), keep it, and reuse it for every lookup: each new client pays a fresh TLS handshake. HTTP/2 is not available with Ruby's `Net::HTTP`, so the saving is the TLS handshake, not multiplexing.
+
+A client is safe to share between threads, but it serialises requests on its single connection, so use one client per thread when you need lookups to run in parallel. Create clients after forking (for example in your web server's after-fork hook): a client inherited from the parent process notices the new process id and opens its own connection instead of reusing the parent's socket, which it never closes. Call `close` at shutdown to finish the connection; the client stays usable and reconnects on the next request.
+
+```ruby
+client = IPData::Client.new("YOUR_API_KEY")
+
+client.lookup("8.8.8.8") # opens the connection (TCP + TLS handshake)
+client.lookup("1.1.1.1") # reuses it
+
+at_exit { client.close }
+```
+
+The connection is opened on the first request. An idle connection is kept for `keep_alive_timeout:` seconds (default 60); after that the next request opens a new one. `timeout:` applies to connecting, reading and writing.
+
+```ruby
+client = IPData::Client.new("YOUR_API_KEY", keep_alive_timeout: 30)
+```
+
+If the server has silently dropped an idle connection, `lookup` (a `GET`) is retried once by `Net::HTTP` and `bulk_lookup` (a `POST`) once by the client, in both cases on a fresh connection and only when the failure happened before any response byte arrived. Nothing is retried on an HTTP error status.
+
 ## Response Fields
 
 All responses are wrapped in `IPData::Response` objects that support both dot-notation and hash-style access:
@@ -138,6 +161,8 @@ response.continent_name
 response.latitude
 response.longitude
 response.is_eu
+response.is_satellite # satellite ISP; sent only when true, reads false otherwise
+response.is_anycast   # anycast address; sent only when true, reads false otherwise
 response.postal
 response.calling_code
 response.flag
@@ -182,7 +207,10 @@ response.threat.is_known_attacker
 response.threat.is_known_abuser
 response.threat.is_threat
 response.threat.is_bogon
-response.threat.blocklists
+response.threat.blocklists                  # array of entries: name, site, type and, when the feed reports them:
+response.threat.blocklists.first.first_seen # first day listed, "YYYY-MM-DD" (UTC); absent for some feeds
+response.threat.blocklists.first.last_seen  # last day listed, "YYYY-MM-DD" (UTC); absent for some feeds
+response.threat.blocklists.first.days_seen  # number of days listed (integer); absent for some feeds
 response.threat.scores
 
 # Languages (array)
@@ -198,6 +226,8 @@ response[:country_code]
 response.to_h
 ```
 
+`is_satellite` and `is_anycast` are included in the API response only when they are true. `response.is_satellite` and `response.is_anycast` read `false` when the key is absent, while `response["is_satellite"]`, `response.key?("is_satellite")` and `response.to_h` reflect the raw response (`nil`, `false` and no key). Each `threat.blocklists` entry carries `first_seen` and `last_seen` (calendar dates as `"YYYY-MM-DD"` strings, UTC) and `days_seen` (an integer) when the feed reports them; some feeds, for example ipdata's own vpn feed, omit all three, so read them with `entry["first_seen"]` (`nil` when absent) or check `entry.key?("first_seen")`. The dates are kept as strings; use `Date.iso8601(entry.first_seen)` if you need `Date` objects.
+
 ## Error Handling
 
 ```ruby

data/lib/ipdata/client.rb

@@ -1,12 +1,25 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "json"
 require "uri"
 
 module IPData
   # HTTP client for the ipdata.co API.
   #
+  # A client keeps one persistent HTTPS connection (HTTP/1.1 keep-alive) for
+  # as long as it lives: the connection is opened on the first request and
+  # reused for every later one, so only the first lookup pays the TCP and TLS
+  # handshake. Create one client per process (or per API key or endpoint),
+  # keep it, and call {#close} at shutdown.
+  #
+  # A client is safe to share between threads; requests are serialised on its
+  # single connection, so use one client per thread for parallel lookups.
+  # Create clients after forking: a client inherited from a parent process
+  # notices the new process id and opens its own connection instead of
+  # reusing (or closing) the parent's socket.
+  #
   # @example Basic usage
   #   client = IPData::Client.new("YOUR_API_KEY")
   #   response = client.lookup("8.8.8.8")
@@ -22,17 +35,29 @@ module IPData
     BASE_URL = "https://api.ipdata.co"
     EU_BASE_URL = "https://eu-api.ipdata.co"
 
+    # Failures that mean a reused connection died before the server answered.
+    RETRYABLE_ERRORS = [EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE, OpenSSL::SSL::SSLError].freeze
+    private_constant :RETRYABLE_ERRORS
+
     # @param api_key [String] Your ipdata API key
     # @param cache [IPData::Cache, nil] Optional LRU cache instance
-    # @param timeout [Integer] HTTP timeout in seconds (default: 30)
-    # @param base_url [String, nil] Override the base URL (default: global endpoint)
-    def initialize(api_key, cache: nil, timeout: 30, base_url: nil)
+    # @param timeout [Integer] HTTP open, read and write timeout in seconds (default: 30)
+    # @param base_url [String, nil] Override the base URL (default: global endpoint).
+    #   A path prefix, if the URL has one, is kept in front of every request path
+    # @param keep_alive_timeout [Integer] Seconds an idle connection is kept before
+    #   the next request opens a new one (default: 60)
+    def initialize(api_key, cache: nil, timeout: 30, base_url: nil, keep_alive_timeout: 60)
       raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
 
       @api_key = api_key
       @cache = cache
       @timeout = timeout
+      @keep_alive_timeout = keep_alive_timeout
       @base_uri = URI.parse(base_url || BASE_URL)
+      @base_path = @base_uri.path.chomp("/")
+      @mutex = Mutex.new
+      @connection = nil
+      @connection_pid = nil
     end
 
     # Create a client configured for the EU endpoint.
@@ -51,11 +76,7 @@ module IPData
     # @param select_field [String, nil] A single field to extract (returns raw value)
     # @return [Response, Object] Response object, or raw value if select_field is used
     def lookup(ip = nil, fields: nil, select_field: nil)
-      if select_field
-        path = "/#{ip}/#{select_field}"
-        data = get(path)
-        return data
-      end
+      return get(request_path(ip, select_field)) if select_field
 
       cache_key = build_cache_key(ip, fields)
       if @cache
@@ -63,11 +84,10 @@ module IPData
         return cached if cached
       end
 
-      path = ip ? "/#{ip}" : "/"
       params = {}
       params["fields"] = fields.join(",") if fields && !fields.empty?
 
-      data = get(path, params)
+      data = get(request_path(ip), params)
       response = Response.new(data)
 
       @cache&.set(cache_key, response)
@@ -87,14 +107,24 @@ module IPData
       params = {}
       params["fields"] = fields.join(",") if fields && !fields.empty?
 
-      data = post("/bulk", ips, params)
+      data = post(request_path("bulk"), ips, params)
       data.map { |entry| Response.new(entry) }
     end
 
+    # Close the persistent connection, if one is open.
+    #
+    # The client stays usable: the next request opens a new connection.
+    #
+    # @return [nil]
+    def close
+      @mutex.synchronize { discard_connection }
+      nil
+    end
+
     private
 
     def user_agent
-      @user_agent ||= "ruby-ipdata/#{VERSION} Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+      @user_agent ||= "ipdata-ruby/#{VERSION} Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
     end
 
     def build_cache_key(ip, fields)
@@ -103,6 +133,13 @@ module IPData
       key
     end
 
+    # Path of a request made of +segments+, under the path prefix of the base
+    # URL if it has one. Nil segments are skipped, so a lookup of the caller's
+    # own IP uses "/" and its single-field form "/<field>", not "//<field>".
+    def request_path(*segments)
+      "#{@base_path}/#{segments.compact.join('/')}"
+    end
+
     def build_uri(path, params = {})
       uri = @base_uri.dup
       uri.path = path
@@ -118,7 +155,7 @@ module IPData
       request["Accept"] = "application/json"
       request["User-Agent"] = user_agent
 
-      execute(uri, request)
+      execute(request)
     end
 
     def post(path, body, params = {})
@@ -130,16 +167,11 @@ module IPData
       request["User-Agent"] = user_agent
       request.body = JSON.generate(body)
 
-      execute(uri, request)
+      execute(request)
     end
 
-    def execute(uri, request)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      http.open_timeout = @timeout
-      http.read_timeout = @timeout
-
-      response = http.request(request)
+    def execute(request)
+      response = @mutex.synchronize { perform(request) }
 
       unless response.is_a?(Net::HTTPSuccess)
         raise Error.from_response(response.code.to_i, response.body)
@@ -147,5 +179,61 @@ module IPData
 
       JSON.parse(response.body)
     end
+
+    # Send +request+ on the pooled connection. Must be called with @mutex held.
+    #
+    # The server may drop an idle connection without notice. Net::HTTP retries
+    # idempotent requests (GET) on such a failure itself (max_retries); POST
+    # /bulk is not idempotent, so Net::HTTP leaves it alone and it is retried
+    # here instead: exactly once, on a fresh connection, and only when the
+    # failure happened before any response byte arrived. An HTTP error status
+    # is a response and is never retried.
+    def perform(request)
+      retried = false
+      loop do
+        http = connection
+        responded = false
+        begin
+          return http.request(request) { responded = true }
+        rescue *RETRYABLE_ERRORS
+          discard_connection
+          raise if retried || responded || request.method != "POST"
+
+          retried = true
+        end
+      end
+    end
+
+    # The pooled Net::HTTP, opened on first use. A connection inherited from a
+    # parent process is dropped without finish (the socket is shared with the
+    # parent, so no TLS close_notify may be sent on it) and a new one opened.
+    def connection
+      discard_connection if @connection && @connection_pid != Process.pid
+      @connection ||= connect
+    end
+
+    def connect
+      http = Net::HTTP.new(@base_uri.host, @base_uri.port)
+      http.use_ssl = @base_uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      http.keep_alive_timeout = @keep_alive_timeout
+      http.max_retries = 1
+      http.start
+      @connection_pid = Process.pid
+      http
+    end
+
+    # Forget the pooled connection, finishing it only if this process opened it.
+    def discard_connection
+      http = @connection
+      @connection = nil
+      return unless http && @connection_pid == Process.pid
+
+      http.finish if http.started?
+    rescue IOError, SystemCallError
+      nil
+    end
   end
 end

data/lib/ipdata/response.rb

@@ -14,6 +14,9 @@ module IPData
   #
   # Nested hashes are recursively wrapped as Response objects.
   # Arrays of hashes (e.g. languages, blocklists) are mapped to Response arrays.
+  #
+  # Keys the API sends only when they are true (+is_satellite+, +is_anycast+)
+  # have explicit readers that return false when the key is absent.
   class Response
     def initialize(data)
       @data = data || {}
@@ -24,6 +27,23 @@ module IPData
       wrap(@data[key.to_s])
     end
 
+    # Whether the address belongs to a satellite internet provider.
+    #
+    # The API includes the +is_satellite+ key only when it is true, so this
+    # reads +false+ when the key is absent instead of raising NoMethodError.
+    # The raw hash (+to_h+, +[]+, +key?+) is left untouched.
+    def is_satellite
+      @data.fetch("is_satellite", false)
+    end
+
+    # Whether the address is anycast (announced from several locations at once).
+    #
+    # The API includes the +is_anycast+ key only when it is true, so this
+    # reads +false+ when the key is absent. The raw hash is left untouched.
+    def is_anycast
+      @data.fetch("is_anycast", false)
+    end
+
     # Returns the underlying raw Hash.
     def to_h
       @data

data/lib/ipdata/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IPData
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ipdata
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - IPData
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-23 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby SDK for the ipdata.co API. Look up geolocation, threat
   intelligence, ASN, company, carrier, currency, timezone and language data for any
@@ -19,6 +19,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/ipdata.rb
@@ -27,11 +28,11 @@ files:
 - lib/ipdata/errors.rb
 - lib/ipdata/response.rb
 - lib/ipdata/version.rb
-homepage: https://github.com/ipdata/ruby
+homepage: https://ipdata.co
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/ipdata/ruby
+  homepage_uri: https://ipdata.co
   source_code_uri: https://github.com/ipdata/ruby
   changelog_uri: https://github.com/ipdata/ruby/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/ipdata/ruby/issues