ipscope 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e47cec1a0711d254f804e3ac7db1f3c48fd393783e8d6d9278be4b83de83bf24
+  data.tar.gz: 62d49ea6718b0225ea0cf97aabcec0c01b864997cfd8996d71b0086863cee8fb
+SHA512:
+  metadata.gz: 5610d9f7837486b72df7ce4004d5094a57fe5e361cf063c1c515e6c2d35f541aaa7c33029f981d4617ed6bcb4cd50b67e36fb12bc3293d8b8d470066c0a9699a
+  data.tar.gz: d123e32f1c15b375633e50f7fa59a18ac638d2da72d7f943a40e09c19b744c40c90932e7e7fdddfd1a1f0beecda7ef2954ca7237180473c03b5505f9e92dd592

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Badele LLC (ipscope.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# IPScope Official Ruby Server-Side SDK (`ipscope`)
+
+Zero-dependency, thread-safe, memory-bounded Ruby Server-Side SDK for the **IPScope IP Intelligence Platform**.
+
+Scoped strictly to **IP intelligence operations** (single IP lookup, caller IP lookup, batch lookup, chunked/streaming batch lookup, network CIDR prefix lookup, dataset metadata, geolocation/anonymity feedback submission, and service health status) with zero account, wallet, or billing dependencies.
+
+---
+
+## Key Features
+
+- **Zero External Runtime Dependencies**: Built entirely on Ruby's standard library (`net/http`, `json`, `ipaddr`, `resolv`, `uri`).
+- **Bounded `O(1)` LRU + TTL Cache**: Default `max_entries: 512` (`< 400 KB` memory footprint) using Ruby's ordered `Hash` protected by a `Mutex` and `Process::CLOCK_MONOTONIC`.
+- **Singleflight Request Coalescing**: Concurrent threads looking up the same IP address simultaneously share a single in-flight HTTP request.
+- **Hard `2 MiB` Streaming Response Ceiling & Bounded JSON Depth (`16`)**: Protects Ruby workers (Puma, Sidekiq, Unicorn, Pitchfork) against oversized upstream payloads and deeply nested JSON memory bombs.
+- **Zero-DNS IPv4/IPv6 & CIDR Validation**: Validates and canonicalizes IP addresses and CIDR prefixes locally without triggering DNS queries.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "ipscope"
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "ipscope"
+
+client = IpScope::Client.new(api_key: "ips_live_your_api_key_here")
+
+# 1. Single IPv4 or IPv6 lookup (cached automatically in bounded LRU cache)
+ip_info = client.lookup_ip("8.8.8.8")
+puts "#{ip_info.ip} #{ip_info.geo.country_code} AS#{ip_info.network.asn}"
+puts "VPN: #{ip_info.security.is_vpn} Threat: #{ip_info.security.threat_level}"
+
+# 2. Batch lookup (up to 100 IPs; deduplicates & reuses cached entries automatically)
+batch = client.lookup_batch(["8.8.8.8", "1.1.1.1", "2606:4700:4700::1111"])
+batch.results.each do |record|
+  puts "#{record.ip} -> #{record.network.org}"
+end
+
+# 3. Memory-bounded streaming batch lookup for 10,000+ IPs (constant O(chunk) RAM)
+client.lookup_batch_stream(large_ip_list) do |chunk|
+  chunk.results.each do |record|
+    # Process each record with < 400 KB steady-state memory overhead
+  end
+end
+
+# 4. Network CIDR prefix lookup
+prefix = client.lookup_network("8.8.8.0/24")
+puts "#{prefix.requested_cidr} matches: #{prefix.total_matches}"
+```

data/lib/ipscope/cache.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module IpScope
+  # Thread-safe bounded O(1) LRU + TTL in-memory cache for IP intelligence records.
+  #
+  # Uses Ruby's insertion-ordered Hash (`delete(key)` + `store[key] = entry`,
+  # `store.shift` for O(1) eviction of the least-recently-used key) protected by a `Mutex`.
+  class LruTtlCache
+    def initialize(options = nil)
+      opts = options || CacheOptions.new
+      @enabled = opts.enabled && opts.max_entries.positive? && opts.ttl_seconds.positive?
+      @max_entries = [opts.max_entries, 1].max
+      @ttl_seconds = [opts.ttl_seconds, 0.001].max
+      @mutex = Mutex.new
+      @store = {}
+      @hits = 0
+      @misses = 0
+      @evictions = 0
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    def get(key, now_monotonic = nil)
+      return nil unless @enabled
+
+      now = now_monotonic || monotonic_now
+      @mutex.synchronize do
+        entry = @store[key]
+        unless entry
+          @misses += 1
+          return nil
+        end
+
+        if now >= entry[:expires_at]
+          @store.delete(key)
+          @misses += 1
+          return nil
+        end
+
+        # Promote to most-recently-used tail in O(1)
+        @store.delete(key)
+        @store[key] = entry
+        @hits += 1
+        entry[:value]
+      end
+    end
+
+    def set(key, value, now_monotonic = nil)
+      return unless @enabled
+
+      now = now_monotonic || monotonic_now
+      @mutex.synchronize do
+        if @store.key?(key)
+          @store.delete(key)
+        elsif @store.length >= @max_entries
+          @store.shift
+          @evictions += 1
+        end
+
+        @store[key] = {
+          value: value,
+          expires_at: now + @ttl_seconds
+        }
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @store.clear
+        @hits = 0
+        @misses = 0
+        @evictions = 0
+      end
+    end
+
+    def stats
+      @mutex.synchronize do
+        CacheStats.new(
+          enabled: @enabled,
+          size: @store.length,
+          max_entries: @max_entries,
+          hits: @hits,
+          misses: @misses,
+          evictions: @evictions
+        )
+      end
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/ipscope/client.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module IpScope
+  # Official Server-Side Ruby Client for the IPScope IP Intelligence Platform.
+  #
+  # Scoped strictly to IP intelligence operations (single IP lookup, caller IP lookup,
+  # batch lookup, chunked/streaming batch lookup, CIDR network prefix lookup, dataset metadata,
+  # geolocation/anonymity feedback submission, and service health status).
+  class Client
+    MAX_BATCH_SIZE = Validator::MAX_BATCH_SIZE
+    MAX_RESPONSE_BYTES = HttpTransport::MAX_RESPONSE_BYTES
+
+    def initialize(
+      api_key:,
+      base_url: HttpTransport::DEFAULT_BASE_URL,
+      timeout_seconds: HttpTransport::DEFAULT_TIMEOUT_SECONDS,
+      retry_options: nil,
+      cache_options: nil,
+      user_agent: nil,
+      custom_transport: nil
+    )
+      @transport = HttpTransport.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout_seconds: timeout_seconds,
+        retry_options: retry_options,
+        user_agent: user_agent,
+        custom_transport: custom_transport
+      )
+      @cache = LruTtlCache.new(cache_options)
+      @inflight_mutex = Mutex.new
+      @inflight = {}
+    end
+
+    # Closes persistent keep-alive connections and clears cached state.
+    def close
+      @cache.clear
+      @transport.close
+    end
+
+    # Looks up full IP intelligence for a single IPv4 or IPv6 address (`GET /v1/ip/{ip}`).
+    def lookup_ip(ip, options = nil)
+      lookup_ip_with_meta(ip, options).data
+    end
+
+    # Looks up full IP intelligence for a single IPv4 or IPv6 address along with
+    # rate-limit headers and cache hit metadata. Coalesces concurrent identical lookups
+    # across threads via singleflight.
+    def lookup_ip_with_meta(ip, options = nil)
+      canonical_ip = Validator.validate_ip_address(ip)
+      bypass_cache = options&.bypass_cache || false
+
+      unless bypass_cache
+        cached = @cache.get(canonical_ip)
+        unless cached.nil?
+          return IpScopeResultWithMeta.new(
+            data: cached,
+            rate_limit: @transport.last_rate_limit,
+            from_cache: true
+          )
+        end
+      end
+
+      return fetch_and_cache_single_ip(canonical_ip, bypass_cache, options) if bypass_cache
+
+      execute_singleflight(canonical_ip) do
+        fetch_and_cache_single_ip(canonical_ip, false, options)
+      end
+    end
+
+    # Resolves IP intelligence for the caller's own public IP address (`GET /v1/ip`).
+    def lookup_caller_ip(options = nil)
+      raw = @transport.request_json("GET", "/v1/ip", options: options)
+      record = IpLookupResponse.from_h(raw[:data])
+      @cache.set(record.ip, record) if !(options&.bypass_cache) && !record.ip.empty?
+      record
+    end
+
+    # Performs a batch IP lookup (`POST /v1/ip/batch`) for up to 100 IP addresses.
+    # Automatically deduplicates input IPs, reuses cached entries from the LRU cache,
+    # and backfills newly fetched records into the cache.
+    def lookup_batch(ips, options = nil)
+      unique_ips = Validator.validate_and_deduplicate_batch_ips(ips, MAX_BATCH_SIZE)
+      bypass_cache = options&.bypass_cache || false
+
+      resolved_map = {}
+      missing_ips = []
+
+      if !bypass_cache && @cache.enabled?
+        unique_ips.each do |ip|
+          cached = @cache.get(ip)
+          if cached
+            resolved_map[ip] = cached
+          else
+            missing_ips << ip
+          end
+        end
+      else
+        missing_ips = unique_ips
+      end
+
+      unless missing_ips.empty?
+        raw = @transport.request_json(
+          "POST",
+          "/v1/ip/batch",
+          json_body: { "ips" => missing_ips },
+          options: options
+        )
+        batch_resp = BatchLookupResponse.from_h(raw[:data])
+
+        batch_resp.results.each_with_index do |record, idx|
+          requested_key = missing_ips[idx] || record.ip
+          resolved_map[requested_key] = record
+          resolved_map[record.ip] = record unless record.ip.empty?
+          unless bypass_cache
+            @cache.set(requested_key, record)
+            @cache.set(record.ip, record) if !record.ip.empty? && record.ip != requested_key
+          end
+        end
+      end
+
+      ordered_results = unique_ips.each_with_object([]) do |ip, acc|
+        acc << resolved_map[ip] if resolved_map.key?(ip)
+      end
+
+      BatchLookupResponse.new(
+        count: ordered_results.length,
+        results: ordered_results
+      )
+    end
+
+    # Splits an arbitrarily large list of IP addresses into chunks of up to 100 unique IPs
+    # and merges the results into a single `BatchLookupResponse`.
+    def lookup_batch_chunked(ips, options = nil)
+      merged = []
+      lookup_batch_stream(ips, options) do |chunk_resp|
+        merged.concat(chunk_resp.results)
+      end
+      BatchLookupResponse.new(
+        count: merged.length,
+        results: merged
+      )
+    end
+
+    # Memory-bounded streaming enumerator that yields `BatchLookupResponse` chunks of up to
+    # 100 unique IP addresses at a time with constant `O(chunk)` RAM usage.
+    # Returns an `Enumerator` if no block is given.
+    def lookup_batch_stream(ips, options = nil)
+      return enum_for(:lookup_batch_stream, ips, options) unless block_given?
+
+      unless ips.respond_to?(:each)
+        raise IpScopeValidationError.new("Batch IP stream must be an Enumerable.", field: "ips")
+      end
+
+      chunk = []
+      seen_in_chunk = {}
+      yielded_any = false
+
+      ips.each do |raw_ip|
+        unless raw_ip.is_a?(String)
+          raise IpScopeValidationError.new("Expected String IP address in lookup_batch_stream.", field: "ips")
+        end
+
+        canonical = Validator.validate_ip_address(raw_ip, "ips")
+        next if seen_in_chunk.key?(canonical)
+
+        seen_in_chunk[canonical] = true
+        chunk << canonical
+
+        if chunk.length >= MAX_BATCH_SIZE
+          yielded_any = true
+          yield lookup_batch(chunk, options)
+          chunk = []
+          seen_in_chunk = {}
+        end
+      end
+
+      if !chunk.empty?
+        yield lookup_batch(chunk, options)
+      elsif !yielded_any
+        raise IpScopeValidationError.new("Batch IP stream must contain at least 1 IP address.", field: "ips")
+      end
+    end
+
+    # Looks up BGP/CIDR network prefix intelligence (`GET /v1/network/{address}/{prefixLength}`).
+    def lookup_network(cidr, options = nil)
+      parsed = Validator.validate_cidr_prefix(cidr)
+      encoded_addr = URI.encode_www_form_component(parsed[:address])
+      path = "/v1/network/#{encoded_addr}/#{parsed[:prefix_length]}"
+      raw = @transport.request_json("GET", path, options: options)
+      NetworkPrefixLookupResponse.from_h(raw[:data])
+    end
+
+    # Retrieves active IP intelligence dataset snapshots metadata (`GET /v1/datasets/metadata`).
+    def get_datasets_metadata(options = nil)
+      raw = @transport.request_json("GET", "/v1/datasets/metadata", options: options)
+      DatasetsMetadataResponse.from_h(raw[:data])
+    end
+
+    # Submits an IP geolocation or anonymity correction (`POST /v1/feedback`).
+    def submit_feedback(feedback, options = nil)
+      unless feedback.is_a?(FeedbackSubmissionInput)
+        raise IpScopeValidationError.new("Expected FeedbackSubmissionInput instance.", field: "feedback")
+      end
+
+      trimmed = feedback.ip_or_cidr.strip
+      if trimmed.empty?
+        raise IpScopeValidationError.new("ip_or_cidr must not be empty.", field: "ip_or_cidr")
+      end
+
+      normalized = if trimmed.include?("/")
+                     Validator.validate_cidr_prefix(trimmed)[:canonical_cidr]
+                   else
+                     Validator.validate_ip_address(trimmed, "ip_or_cidr")
+                   end
+
+      payload = feedback.to_h
+      payload["ip_or_cidr"] = normalized
+
+      raw = @transport.request_json("POST", "/v1/feedback", json_body: payload, options: options)
+      FeedbackSubmissionResponse.from_h(raw[:data])
+    end
+
+    # Queries the IPScope API health status (`GET /v1/status`).
+    def get_status(options = nil)
+      raw = @transport.request_json("GET", "/v1/status", options: options)
+      ServiceStatusResponse.from_h(raw[:data])
+    end
+
+    # Returns the most recent rate-limit metadata observed from `x-ratelimit-*` headers.
+    def last_rate_limit
+      @transport.last_rate_limit
+    end
+
+    # Returns current bounded LRU cache statistics.
+    def cache_stats
+      @cache.stats
+    end
+
+    # Clears all entries and resets statistics in the in-memory LRU cache.
+    def clear_cache
+      @cache.clear
+    end
+
+    private
+
+    def fetch_and_cache_single_ip(canonical_ip, bypass_cache, options)
+      encoded = URI.encode_www_form_component(canonical_ip)
+      raw = @transport.request_json("GET", "/v1/ip/#{encoded}", options: options)
+      record = IpLookupResponse.from_h(raw[:data])
+
+      unless bypass_cache
+        @cache.set(canonical_ip, record)
+        @cache.set(record.ip, record) if !record.ip.empty? && record.ip != canonical_ip
+      end
+
+      IpScopeResultWithMeta.new(
+        data: record,
+        rate_limit: raw[:rate_limit],
+        from_cache: false
+      )
+    end
+
+    def execute_singleflight(key)
+      leader = false
+      state = nil
+
+      @inflight_mutex.synchronize do
+        if @inflight.key?(key)
+          state = @inflight[key]
+        else
+          leader = true
+          state = { done: false, result: nil, error: nil, cond: ConditionVariable.new }
+          @inflight[key] = state
+        end
+      end
+
+      if leader
+        begin
+          res = yield
+          @inflight_mutex.synchronize do
+            state[:result] = res
+            state[:done] = true
+            @inflight.delete(key)
+            state[:cond].broadcast
+          end
+          res
+        rescue StandardError => e
+          @inflight_mutex.synchronize do
+            state[:error] = e
+            state[:done] = true
+            @inflight.delete(key)
+            state[:cond].broadcast
+          end
+          raise e
+        end
+      else
+        @inflight_mutex.synchronize do
+          state[:cond].wait(@inflight_mutex) until state[:done]
+        end
+        raise state[:error] if state[:error]
+
+        state[:result]
+      end
+    end
+  end
+
+  # Alias for consistency with other IPScope SDKs (`IpScopeClient`).
+  IpScopeClient = Client
+end

data/lib/ipscope/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module IpScope
+  # Base error class for all exceptions raised by the IPScope Ruby SDK.
+  class IpScopeError < StandardError
+    attr_reader :error_code
+
+    def initialize(message, error_code: "IPSCOPE_ERROR")
+      super(message)
+      @error_code = error_code.to_s.freeze
+    end
+  end
+
+  # Raised when client-side validation fails before sending an HTTP request.
+  class IpScopeValidationError < IpScopeError
+    attr_reader :field
+
+    def initialize(message, field: nil)
+      super(message, error_code: "IPSCOPE_VALIDATION_ERROR")
+      @field = field ? field.to_s.freeze : nil
+    end
+  end
+
+  # Raised when an HTTP request exceeds the configured timeout.
+  class IpScopeTimeoutError < IpScopeError
+    attr_reader :path, :timeout_seconds
+
+    def initialize(path, timeout_seconds)
+      @path = path.to_s.freeze
+      @timeout_seconds = timeout_seconds.to_f
+      super(
+        format('IPScope request to "%s" timed out after %.2fs', @path, @timeout_seconds),
+        error_code: "IPSCOPE_TIMEOUT_ERROR"
+      )
+    end
+  end
+
+  # Raised when the IPScope API returns a non-2xx HTTP status code or network failure.
+  class IpScopeApiError < IpScopeError
+    attr_reader :status, :path, :rate_limit
+
+    def initialize(message, status:, path:, error_code: nil, rate_limit: nil)
+      @status = status.to_i
+      @path = path.to_s.freeze
+      @rate_limit = rate_limit
+      super(message, error_code: error_code || "IPSCOPE_HTTP_#{@status}")
+    end
+  end
+
+  # Raised on HTTP 401 Unauthorized or 403 Forbidden.
+  class IpScopeAuthenticationError < IpScopeApiError
+    def initialize(message, status:, path:, rate_limit: nil)
+      code = status.to_i == 401 ? "IPSCOPE_UNAUTHORIZED" : "IPSCOPE_FORBIDDEN_SCOPE"
+      super(message, status: status, path: path, error_code: code, rate_limit: rate_limit)
+    end
+  end
+
+  # Raised on HTTP 429 Too Many Requests when retries are exhausted or disabled.
+  class IpScopeRateLimitError < IpScopeApiError
+    attr_reader :retry_after_seconds
+
+    def initialize(message, path:, retry_after_seconds: nil, rate_limit: nil)
+      @retry_after_seconds = retry_after_seconds ? retry_after_seconds.to_f : nil
+      super(
+        message,
+        status: 429,
+        path: path,
+        error_code: "IPSCOPE_RATE_LIMITED",
+        rate_limit: rate_limit
+      )
+    end
+  end
+end