vpndetection 1.0.0

data/lib/vpndetection/models/vpn_detail.rb

@@ -0,0 +1,179 @@
+=begin
+#VPNDetection API
+
+#The VPNDetection API: classify any IP address, and download the datasets behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
+
+The version of the OpenAPI document: 2026.09.04
+Contact: support@vpndetection.io
+Generated by: https://openapi-generator.tech
+Generator version: 7.25.0
+
+=end
+
+require 'date'
+require 'time'
+
+module VPNDetection
+  # What is known about the VPN attribution. Every key is present when the object is populated, empty values included; the object is `{}` when `is_vpn` is false. `confidence` and `method` are max only, so on a lower plan they are absent from a populated object rather than empty. 
+  class VpnDetail < ApiModelBase
+    # The VPN provider, or an empty string for an unattributed range.
+    attr_accessor :provider
+
+    # The most recent date this address was observed as VPN infrastructure.
+    attr_accessor :last_seen
+
+    # How strongly the attribution is supported. Max only.
+    attr_accessor :confidence
+
+    # How the address was attributed to the provider. Max only.
+    attr_accessor :method
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'provider' => :'provider',
+        :'last_seen' => :'last_seen',
+        :'confidence' => :'confidence',
+        :'method' => :'method'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'provider' => :'String',
+        :'last_seen' => :'Date',
+        :'confidence' => :'String',
+        :'method' => :'String'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `VPNDetection::VpnDetail` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `VPNDetection::VpnDetail`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'provider')
+        self.provider = attributes[:'provider']
+      end
+
+      if attributes.key?(:'last_seen')
+        self.last_seen = attributes[:'last_seen']
+      end
+
+      if attributes.key?(:'confidence')
+        self.confidence = attributes[:'confidence']
+      end
+
+      if attributes.key?(:'method')
+        self.method = attributes[:'method']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      true
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          provider == o.provider &&
+          last_seen == o.last_seen &&
+          confidence == o.confidence &&
+          method == o.method
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [provider, last_seen, confidence, method].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/vpndetection/result.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  # What a lookup answers.
+  #
+  # An **absent** member is one your plan does not include. It never means "we
+  # could not check", so `nil` and `false` are genuinely different answers: `nil`
+  # is "not in your plan", `false` is "checked, and no".
+  #
+  # Ruby makes that easy to lose, because `nil` and `false` are both falsy. Read
+  # the field itself (`is_hosting`) when the difference matters, ask
+  # {#included?} when you need to know whether your plan carries it at all, and
+  # use the predicate (`hosting?`) when you only care whether the address is
+  # flagged. A predicate always answers `true` or `false`, never `nil`.
+  #
+  # A detail object that is present but empty (`{}`) means the flag above it is
+  # false. A populated one always carries every one of its keys. Details are the
+  # wire hashes with their original string keys, so `result.vpn['provider']`.
+  class Result
+    FLAGS = %w[
+      is_vpn is_hosting is_relay is_tor is_cdn is_resproxy is_dcproxy is_mobproxy
+    ].freeze
+
+    DETAILS = %w[vpn hosting relay tor cdn resproxy dcproxy mobproxy].freeze
+
+    # The response exactly as it came off the wire, with its original names.
+    # Frozen, because the cache hands this same object to every later caller of
+    # the address.
+    attr_reader :raw
+
+    def initialize(raw, bogon: false)
+      @raw = deep_freeze(raw)
+      @bogon = bogon
+      freeze
+    end
+
+    # The address that was looked up, normalized.
+    def ip
+      @raw['ip']
+    end
+
+    # Set when this answer was computed locally rather than served. Always
+    # `true` or `false`.
+    def bogon?
+      @bogon
+    end
+
+    # Whether your plan includes a member at all, told apart from a member your
+    # plan includes that answered false.
+    #
+    #   result.included?(:is_hosting)   # => false, not in your plan
+    #   result.is_hosting               # => nil
+    def included?(field)
+      @raw.key?(field.to_s)
+    end
+
+    # Whether the address is VPN infrastructure. Every plan includes this.
+    def is_vpn
+      @raw['is_vpn']
+    end
+
+    # `is_vpn` with an absent member read as false.
+    def vpn?
+      @raw['is_vpn'] == true
+    end
+
+    # Whether the address belongs to a hosting or cloud provider, or nil when
+    # your plan does not include it. Starter and above.
+    def is_hosting
+      @raw['is_hosting']
+    end
+
+    # `is_hosting` with an absent member read as false.
+    def hosting?
+      @raw['is_hosting'] == true
+    end
+
+    # Whether the address is a privacy relay egress, or nil when your plan does
+    # not include it. Starter and above.
+    def is_relay
+      @raw['is_relay']
+    end
+
+    # `is_relay` with an absent member read as false.
+    def relay?
+      @raw['is_relay'] == true
+    end
+
+    # Whether the address is a Tor node, or nil when your plan does not include
+    # it. Starter and above.
+    def is_tor
+      @raw['is_tor']
+    end
+
+    # `is_tor` with an absent member read as false.
+    def tor?
+      @raw['is_tor'] == true
+    end
+
+    # Whether the address belongs to a CDN, or nil when your plan does not
+    # include it. Starter and above.
+    def is_cdn
+      @raw['is_cdn']
+    end
+
+    # `is_cdn` with an absent member read as false.
+    def cdn?
+      @raw['is_cdn'] == true
+    end
+
+    # Whether the address was seen in a residential proxy pool, or nil when your
+    # plan does not include it. Max only.
+    def is_resproxy
+      @raw['is_resproxy']
+    end
+
+    # `is_resproxy` with an absent member read as false.
+    def resproxy?
+      @raw['is_resproxy'] == true
+    end
+
+    # Whether the address was seen in a datacenter proxy pool, or nil when your
+    # plan does not include it. Max only.
+    def is_dcproxy
+      @raw['is_dcproxy']
+    end
+
+    # `is_dcproxy` with an absent member read as false.
+    def dcproxy?
+      @raw['is_dcproxy'] == true
+    end
+
+    # Whether the address was seen in a mobile proxy pool, or nil when your plan
+    # does not include it. Max only.
+    def is_mobproxy
+      @raw['is_mobproxy']
+    end
+
+    # `is_mobproxy` with an absent member read as false.
+    def mobproxy?
+      @raw['is_mobproxy'] == true
+    end
+
+    # Detail for `is_vpn`: provider, last_seen, and on max confidence and method.
+    def vpn
+      @raw['vpn']
+    end
+
+    # Detail for `is_hosting`. Scale and above.
+    def hosting
+      @raw['hosting']
+    end
+
+    # Detail for `is_relay`. Scale and above.
+    def relay
+      @raw['relay']
+    end
+
+    # Detail for `is_tor`. Scale and above.
+    def tor
+      @raw['tor']
+    end
+
+    # Detail for `is_cdn`. Scale and above.
+    def cdn
+      @raw['cdn']
+    end
+
+    # Detail for `is_resproxy`. Max only.
+    def resproxy
+      @raw['resproxy']
+    end
+
+    # Detail for `is_dcproxy`. Max only.
+    def dcproxy
+      @raw['dcproxy']
+    end
+
+    # Detail for `is_mobproxy`. Max only.
+    def mobproxy
+      @raw['mobproxy']
+    end
+
+    def to_h
+      @raw
+    end
+
+    def ==(other)
+      other.is_a?(Result) && other.raw == @raw && other.bogon? == @bogon
+    end
+    alias eql? ==
+
+    def hash
+      [@raw, @bogon].hash
+    end
+
+    def inspect
+      "#<#{self.class} ip=#{ip.inspect} is_vpn=#{is_vpn.inspect} bogon=#{@bogon}>"
+    end
+
+    private
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each { |_, v| deep_freeze(v) }.freeze
+      when Array then value.each { |v| deep_freeze(v) }.freeze
+      else value.freeze
+      end
+    end
+  end
+end

data/lib/vpndetection/retries.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  # What may be tried again, and how long to wait first.
+  #
+  # Only a 5xx, a transport failure and a 429 that carried `Retry-After` are
+  # worth another attempt. Every other 4xx is a client error and fails on the
+  # first try, so a bad dataset id is not asked for three times.
+  module Retries
+    BACKOFF_SECONDS = 0.25
+
+    module_function
+
+    def with_retries(retries)
+      attempt = 0
+      begin
+        yield
+      rescue Error => e
+        raise unless e.retryable? && attempt < retries
+
+        attempt += 1
+        sleep(delay_for(e, attempt))
+        retry
+      end
+    end
+
+    # A server-supplied delay always wins, including a `Retry-After: 0`, which
+    # is the server saying "immediately" rather than saying nothing.
+    def delay_for(error, attempt)
+      error.retry_after_seconds || BACKOFF_SECONDS * (2**(attempt - 1))
+    end
+  end
+end

data/lib/vpndetection/transport.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'uri'
+
+module VPNDetection
+  # The generated wire client, with the three things it gets wrong for this API
+  # corrected in one place.
+  class Transport < ApiClient
+    # The same path template the generated LookupApi holds. Both are asserted
+    # against each other in the test suite, because the batch builds its own
+    # requests to queue them on a hydra and cannot go through the generated
+    # method, which runs each request as it builds it.
+    LOOKUP_PATH = '/{ip}'
+
+    # The generated Configuration applies EVERY security scheme the spec lists,
+    # so a keyless client would send `Authorization: Bearer `, an empty
+    # `X-Api-Key` and an empty `apikey` query parameter. The API answers 401 to
+    # the first of those, which is not what a keyless caller asked for.
+    class Config < Configuration
+      def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+        super()
+        uri = URI.parse(base_url)
+        self.scheme = uri.scheme
+        self.host = uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+        self.base_path = uri.path
+        self.access_token = api_key
+        self.timeout = timeout
+      end
+
+      def auth_settings
+        return {} if access_token.nil? || access_token.to_s.empty?
+
+        {
+          'bearerAuth' => {
+            type: 'bearer', in: 'header', key: 'Authorization',
+            value: "Bearer #{access_token}"
+          }
+        }
+      end
+    end
+
+    def initialize(config = Config.new)
+      super
+      @default_headers['User-Agent'] = "vpndetection-ruby/#{VERSION}"
+    end
+
+    # `follow_location = opts[:follow_location] || true` in the generated client
+    # is true for every value it can be given, so the database download's 302
+    # would be chased and a multi-gigabyte dataset read into memory. Nothing
+    # this API serves is meant to be followed.
+    def build_request(http_method, path, opts = {})
+      request = super
+      request.options[:followlocation] = false
+      request
+    end
+
+    # A GET for the presigned link the download endpoint hands out.
+    #
+    # Built here rather than through {#build_request} so it carries NO
+    # credential: the presigned URL authorizes itself, and forwarding the API key
+    # would hand it to a host with no business holding it. Redirects ARE followed,
+    # unlike every other request this client makes, because this one IS the far
+    # side of a redirect; the guard exists to stop the API's own 302 pulling a
+    # dataset into memory, not to stop object storage from moving a bucket.
+    #
+    # The whole-request timeout is dropped and only the connect phase is bounded.
+    # Ten seconds is a sane ceiling on a lookup and the wrong one on 1.79 GB.
+    def storage_request(url)
+      options = {
+        method: :get,
+        headers: { 'User-Agent' => @default_headers['User-Agent'] },
+        followlocation: true,
+        maxredirs: 5,
+        connecttimeout: @config.timeout,
+        ssl_verifypeer: @config.verify_ssl,
+        ssl_verifyhost: @config.verify_ssl_host ? 2 : 0,
+      }
+      options[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert
+      Typhoeus::Request.new(url, options)
+    end
+
+    def lookup_request(ip)
+      build_request(
+        :GET, LOOKUP_PATH.sub('{ip}', CGI.escape(ip.to_s)),
+        header_params: { 'Accept' => 'application/json' },
+        auth_names: %w[bearerAuth apiKeyHeader apiKeyQuery],
+      )
+    end
+
+    def self.lookup_result(response)
+      raise Error.from_transport(response) if transport_failure?(response)
+      raise Error.from_status(response.code, response.headers, response.body) unless response.success?
+
+      Result.new(parse_object(response))
+    end
+
+    def self.transport_failure?(response)
+      response.timed_out? || response.code.to_i.zero?
+    end
+
+    def self.parse_object(response)
+      body = JSON.parse(response.body.to_s)
+      return body if body.is_a?(Hash)
+
+      raise Error.new(:server_error, 'the API answered with something other than an object',
+                      status: response.code)
+    rescue JSON::ParserError => e
+      raise Error.new(:server_error, "could not parse the response body: #{e.message}",
+                      status: response.code)
+    end
+
+    private_class_method :transport_failure?, :parse_object
+  end
+end

data/lib/vpndetection/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  VERSION = '1.0.0'
+end

data/lib/vpndetection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'vpndetection/version'
+
+# The wire layer, generated from spec/openapi.yaml by scripts/generate.sh.
+# Models are loaded by glob because the set of them is the generator's to
+# decide; they subclass ApiModelBase and so must follow it.
+require 'vpndetection/api_client'
+require 'vpndetection/api_error'
+require 'vpndetection/api_model_base'
+require 'vpndetection/configuration'
+Dir[File.join(__dir__, 'vpndetection', 'models', '*.rb')].sort.each { |model| require model }
+Dir[File.join(__dir__, 'vpndetection', 'api', '*.rb')].sort.each { |api| require api }
+
+require 'vpndetection/bogons'
+require 'vpndetection/errors'
+require 'vpndetection/result'
+require 'vpndetection/bogon'
+require 'vpndetection/cache'
+require 'vpndetection/retries'
+require 'vpndetection/transport'
+require 'vpndetection/database'
+require 'vpndetection/client'
+
+# The official Ruby client library for the VPNDetection API.
+#
+#   client = VPNDetection::Client.new
+#   client.lookup('45.83.91.1').is_vpn   # => true
+module VPNDetection
+  # Whether an address is a bogon: private, loopback, link-local, documentation,
+  # multicast or otherwise not routable on the public internet, including the
+  # IPv6 equivalents and the 6to4 and Teredo ranges that wrap them.
+  #
+  # These can never be VPN or proxy infrastructure, so a client answers them
+  # itself and they never cost a request. The same predicate is on the client,
+  # which is how the README teaches it.
+  def self.bogon?(ip)
+    Bogon.bogon?(ip)
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: vpndetection
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mslm Dev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lru_redux
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Query the VPNDetection API for anonymity detection including VPNs, residential
+  proxies, Tor nodes, hosting servers, CDNs and relays.
+email:
+- support@vpndetection.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/vpndetection.rb
+- lib/vpndetection/api/database_api.rb
+- lib/vpndetection/api/lookup_api.rb
+- lib/vpndetection/api_client.rb
+- lib/vpndetection/api_error.rb
+- lib/vpndetection/api_model_base.rb
+- lib/vpndetection/bogon.rb
+- lib/vpndetection/bogons.rb
+- lib/vpndetection/cache.rb
+- lib/vpndetection/client.rb
+- lib/vpndetection/configuration.rb
+- lib/vpndetection/database.rb
+- lib/vpndetection/errors.rb
+- lib/vpndetection/models/class_detail.rb
+- lib/vpndetection/models/dataset_checksums.rb
+- lib/vpndetection/models/dataset_checksums_response.rb
+- lib/vpndetection/models/dataset_format_size.rb
+- lib/vpndetection/models/dataset_list.rb
+- lib/vpndetection/models/dataset_metadata.rb
+- lib/vpndetection/models/dataset_metadata_column.rb
+- lib/vpndetection/models/download.rb
+- lib/vpndetection/models/download_list.rb
+- lib/vpndetection/models/error_envelope.rb
+- lib/vpndetection/models/licensed_dataset.rb
+- lib/vpndetection/models/licensed_version.rb
+- lib/vpndetection/models/lookup_error.rb
+- lib/vpndetection/models/lookup_response.rb
+- lib/vpndetection/models/proxy_detail.rb
+- lib/vpndetection/models/vpn_detail.rb
+- lib/vpndetection/result.rb
+- lib/vpndetection/retries.rb
+- lib/vpndetection/transport.rb
+- lib/vpndetection/version.rb
+homepage: https://vpndetection.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://vpndetection.io
+  source_code_uri: https://github.com/vpndetection-io/sdk-ruby
+  bug_tracker_uri: https://github.com/vpndetection-io/sdk-ruby/issues
+  changelog_uri: https://github.com/vpndetection-io/sdk-ruby/releases
+  documentation_uri: https://docs.vpndetection.io
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client library for the VPNDetection API.
+test_files: []