vpndetection 1.0.0

data/lib/vpndetection/client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'typhoeus'
+
+module VPNDetection
+  DEFAULT_BASE_URL = 'https://api.vpndetection.io'
+  DEFAULT_CACHE_MAX_SIZE = 10_000
+  DEFAULT_CACHE_TTL = 3600
+  DEFAULT_CONCURRENCY = 8
+  DEFAULT_RETRIES = 2
+  DEFAULT_TIMEOUT = 10
+
+  # A client for the VPNDetection API.
+  #
+  # The cache is per instance, so an answer is never shared between two clients
+  # holding different API keys and therefore entitled to different fields.
+  class Client
+    # The licensed dataset downloads, for keys that carry the `db.download` scope.
+    attr_reader :database
+
+    # @param api_key [String, nil] omit it entirely to use the free tier, which
+    #   answers `ip` and `is_vpn` and allows 1000 requests per day per source
+    #   address.
+    # @param cache [Boolean] pass false to disable caching.
+    # @param cache_ttl [Numeric] how long an answer stays fresh, in seconds.
+    # @param concurrency [Integer] in-flight requests during a batch.
+    # @param retries [Integer] extra attempts for a transient failure.
+    # @param transport [Transport, nil] override the HTTP layer, mostly for tests.
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, cache: true,
+                   cache_max_size: DEFAULT_CACHE_MAX_SIZE, cache_ttl: DEFAULT_CACHE_TTL,
+                   concurrency: DEFAULT_CONCURRENCY, retries: DEFAULT_RETRIES,
+                   timeout: DEFAULT_TIMEOUT, transport: nil)
+      @transport = transport || Transport.new(
+        Transport::Config.new(api_key: api_key, base_url: base_url, timeout: timeout),
+      )
+      @cache = cache ? Cache.new(max_size: cache_max_size, ttl: cache_ttl) : nil
+      @concurrency = concurrency
+      @retries = retries
+      @database = Database.new(@transport, retries: retries)
+    end
+
+    # Whether an address is private, loopback, link-local, documentation,
+    # multicast or otherwise not routable, including the IPv6 equivalents and
+    # the 6to4 and Teredo ranges.
+    #
+    # These are the addresses {#lookup} answers locally. Exposed here so the
+    # check is reachable from the client you already hold; the same predicate is
+    # also on the module itself, for code with no client to hand.
+    def bogon?(ip)
+      Bogon.bogon?(ip)
+    end
+
+    # Classify one address.
+    #
+    # A bogon is answered locally and never reaches the network. Everything else
+    # is served, then cached for this instance.
+    def lookup(ip, retries: nil)
+      return Bogon.result(ip) if Bogon.bogon?(ip)
+
+      hit = @cache&.get(ip)
+      return hit unless hit.nil?
+
+      result = Retries.with_retries(retries || @retries) do
+        Transport.lookup_result(@transport.lookup_request(ip).run)
+      end
+      @cache&.set(ip, result)
+      result
+    end
+
+    # Classify many addresses in parallel.
+    #
+    # Keyed by address rather than positional, so duplicates in the input
+    # collapse to a single request and the caller never has to line two lists
+    # up. An address that fails carries its error as its value, so one bad entry
+    # cannot lose the rest of the answers.
+    #
+    # @return [Hash{String => Result, Error}] in the order the addresses were given
+    def lookup_batch(ips, concurrency: nil, retries: nil)
+      addresses = ips.to_a.uniq
+      answers = {}
+      pending = []
+
+      addresses.each do |ip|
+        hit = Bogon.bogon?(ip) ? Bogon.result(ip) : @cache&.get(ip)
+        hit.nil? ? pending << ip : answers[ip] = hit
+      end
+      unless pending.empty?
+        run_batch(pending, answers, concurrency || @concurrency, retries || @retries)
+      end
+
+      # Reinstated in input order: a hydra settles in completion order, and a
+      # caller iterating the hash should see what they passed in.
+      addresses.to_h { |ip| [ip, answers[ip]] }
+    end
+
+    private
+
+    # One hydra per call, sized for THIS call. Reusing an instance-level hydra
+    # would silently cap a per-call concurrency at the client's setting, and
+    # would not be safe to drive from two threads either.
+    def run_batch(pending, answers, concurrency, retries)
+      hydra = Typhoeus::Hydra.new(max_concurrency: concurrency)
+      attempts = Hash.new(0)
+
+      enqueue = lambda do |ip|
+        request = @transport.lookup_request(ip)
+        request.on_complete do |response|
+          outcome = settle(ip, response, attempts, retries, enqueue)
+          answers[ip] = outcome unless outcome.nil?
+        end
+        hydra.queue(request)
+      end
+
+      pending.each { |ip| enqueue.call(ip) }
+      hydra.run
+    end
+
+    def settle(ip, response, attempts, retries, enqueue)
+      result = Transport.lookup_result(response)
+      @cache&.set(ip, result)
+      result
+    rescue Error => e
+      return e unless e.retryable? && attempts[ip] < retries
+
+      attempts[ip] += 1
+      # Sleeping here stalls the whole hydra, which is what a server-supplied
+      # delay asks for: it is telling every request to this host to back off.
+      sleep(Retries.delay_for(e, attempts[ip]))
+      enqueue.call(ip)
+      nil
+    end
+  end
+end

data/lib/vpndetection/configuration.rb

@@ -0,0 +1,326 @@
+=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
+
+module VPNDetection
+  class Configuration
+    # Defines url scheme
+    attr_accessor :scheme
+
+    # Defines url host
+    attr_accessor :host
+
+    # Defines url base path
+    attr_accessor :base_path
+
+    # Define server configuration index
+    attr_accessor :server_index
+
+    # Define server operation configuration index
+    attr_accessor :server_operation_index
+
+    # Default server variables
+    attr_accessor :server_variables
+
+    # Default server operation variables
+    attr_accessor :server_operation_variables
+
+    # Defines API keys used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: parameter value (API key)
+    #
+    # @example parameter name is "api_key", API key is "xxx" (e.g. "api_key=xxx" in query string)
+    #   config.api_key['api_key'] = 'xxx'
+    attr_accessor :api_key
+
+    # Defines API key prefixes used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: API key prefix
+    #
+    # @example parameter name is "Authorization", API key prefix is "Token" (e.g. "Authorization: Token xxx" in headers)
+    #   config.api_key_prefix['api_key'] = 'Token'
+    attr_accessor :api_key_prefix
+
+    # Defines the username used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :username
+
+    # Defines the password used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :password
+
+    # Defines the access token (Bearer) used with OAuth2.
+    attr_accessor :access_token
+
+    # Defines a Proc used to fetch or refresh access tokens (Bearer) used with OAuth2.
+    # Overrides the access_token if set
+    # @return [Proc]
+    attr_accessor :access_token_getter
+
+    # Set this to return data as binary instead of downloading a temp file. When enabled (set to true)
+    # HTTP responses with return type `File` will be returned as a stream of binary data.
+    # Default to false.
+    attr_accessor :return_binary_data
+
+    # Set this to enable/disable debugging. When enabled (set to true), HTTP request/response
+    # details will be logged with `logger.debug` (see the `logger` attribute).
+    # Default to false.
+    #
+    # @return [true, false]
+    attr_accessor :debugging
+
+    # Set this to ignore operation servers for the API client. This is useful when you need to
+    # send requests to a different server than the one specified in the OpenAPI document.
+    # Will default to the base url defined in the spec but can be overridden by setting
+    # `scheme`, `host`, `base_path` directly.
+    # Default to false.
+    # @return [true, false]
+    attr_accessor :ignore_operation_servers
+
+    # Defines the logger used for debugging.
+    # Default to `Rails.logger` (when in Rails) or logging to STDOUT.
+    #
+    # @return [#debug]
+    attr_accessor :logger
+
+    # Defines the temporary folder to store downloaded files
+    # (for API endpoints that have file response).
+    # Default to use `Tempfile`.
+    #
+    # @return [String]
+    attr_accessor :temp_folder_path
+
+    # The time limit for HTTP request in seconds.
+    # Default to 0 (never times out).
+    attr_accessor :timeout
+
+    # Set this to false to skip client side validation in the operation.
+    # Default to true.
+    # @return [true, false]
+    attr_accessor :client_side_validation
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL certificate when calling API from https server.
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL host name
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl_host
+
+    ### TLS/SSL setting
+    # Set this to customize the certificate file to verify the peer.
+    #
+    # @return [String] the path to the certificate file
+    #
+    # @see The `cainfo` option of Typhoeus, `--cert` option of libcurl. Related source code:
+    # https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/easy_factory.rb#L145
+    attr_accessor :ssl_ca_cert
+
+    ### TLS/SSL setting
+    # Client certificate file (for client certificate)
+    attr_accessor :cert_file
+
+    ### TLS/SSL setting
+    # Client private key file (for client certificate)
+    attr_accessor :key_file
+
+    # Set this to customize parameters encoding of array parameter with multi collectionFormat.
+    # Default to nil.
+    #
+    # @see The params_encoding option of Ethon. Related source code:
+    # https://github.com/typhoeus/ethon/blob/master/lib/ethon/easy/queryable.rb#L96
+    attr_accessor :params_encoding
+
+
+    attr_accessor :inject_format
+
+    attr_accessor :force_ending_format
+
+    def initialize
+      @scheme = 'https'
+      @host = 'api.vpndetection.io'
+      @base_path = ''
+      @server_index = nil
+      @server_operation_index = {}
+      @server_variables = {}
+      @server_operation_variables = {}
+      @api_key = {}
+      @api_key_prefix = {}
+      @client_side_validation = true
+      @verify_ssl = true
+      @verify_ssl_host = true
+      @cert_file = nil
+      @key_file = nil
+      @timeout = 0
+      @params_encoding = nil
+      @debugging = false
+      @ignore_operation_servers = false
+      @inject_format = false
+      @force_ending_format = false
+      @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+
+      yield(self) if block_given?
+    end
+
+    # The default Configuration object.
+    def self.default
+      @@default ||= Configuration.new
+    end
+
+    def configure
+      yield(self) if block_given?
+    end
+
+    def scheme=(scheme)
+      # remove :// from scheme
+      @scheme = scheme.sub(/:\/\//, '')
+    end
+
+    def host=(host)
+      # remove http(s):// and anything after a slash
+      @host = host.sub(/https?:\/\//, '').split('/').first
+    end
+
+    def base_path=(base_path)
+      # Add leading and trailing slashes to base_path
+      @base_path = "/#{base_path}".gsub(/\/+/, '/')
+      @base_path = '' if @base_path == '/'
+    end
+
+    # Returns base URL for specified operation based on server settings
+    def base_url(operation = nil)
+      return "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') if ignore_operation_servers
+      if operation_server_settings.key?(operation) then
+        index = server_operation_index.fetch(operation, server_index)
+        server_url(index.nil? ? 0 : index, server_operation_variables.fetch(operation, server_variables), operation_server_settings[operation])
+      else
+        server_index.nil? ? "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') : server_url(server_index, server_variables, nil)
+      end
+    end
+
+    # Gets API key (with prefix if set).
+    # @param [String] param_name the parameter name of API key auth
+    def api_key_with_prefix(param_name, param_alias = nil)
+      key = @api_key[param_name]
+      key = @api_key.fetch(param_alias, key) unless param_alias.nil?
+      if @api_key_prefix[param_name]
+        "#{@api_key_prefix[param_name]} #{key}"
+      else
+        key
+      end
+    end
+
+    # Gets access_token using access_token_getter or uses the static access_token
+    def access_token_with_refresh
+      return access_token if access_token_getter.nil?
+      access_token_getter.call
+    end
+
+    # Gets Basic Auth token string
+    def basic_auth_token
+      'Basic ' + ["#{username}:#{password}"].pack('m').delete("\r\n")
+    end
+
+    # Returns Auth Settings hash for api client.
+    def auth_settings
+      {
+        'bearerAuth' =>
+          {
+            type: 'bearer',
+            in: 'header',
+            key: 'Authorization',
+            value: "Bearer #{access_token_with_refresh}"
+          },
+        'apiKeyHeader' =>
+          {
+            type: 'api_key',
+            in: 'header',
+            key: 'X-Api-Key',
+            value: api_key_with_prefix('X-Api-Key')
+          },
+        'apiKeyQuery' =>
+          {
+            type: 'api_key',
+            in: 'query',
+            key: 'apikey',
+            value: api_key_with_prefix('apikey')
+          },
+      }
+    end
+
+    # Returns an array of Server setting
+    def server_settings
+      [
+        {
+          url: "https://api.vpndetection.io",
+          description: "Production",
+        },
+        {
+          url: "https://api-staging.vpndetection.io",
+          description: "Staging",
+        }
+      ]
+    end
+
+    def operation_server_settings
+      {
+      }
+    end
+
+    # Returns URL based on server settings
+    #
+    # @param index array index of the server settings
+    # @param variables hash of variable and the corresponding value
+    def server_url(index, variables = {}, servers = nil)
+      servers = server_settings if servers == nil
+
+      # check array index out of bound
+      if (index.nil? || index < 0 || index >= servers.size)
+        fail ArgumentError, "Invalid index #{index} when selecting the server. Must not be nil and must be less than #{servers.size}"
+      end
+
+      server = servers[index]
+      url = server[:url]
+
+      return url unless server.key? :variables
+
+      # go through variable and assign a value
+      server[:variables].each do |name, variable|
+        if variables.key?(name)
+          if (!server[:variables][name].key?(:enum_values) || server[:variables][name][:enum_values].include?(variables[name]))
+            url.gsub! "{" + name.to_s + "}", variables[name]
+          else
+            fail ArgumentError, "The variable `#{name}` in the server URL has invalid value #{variables[name]}. Must be #{server[:variables][name][:enum_values]}."
+          end
+        else
+          # use default value
+          url.gsub! "{" + name.to_s + "}", server[:variables][name][:default_value]
+        end
+      end
+
+      url
+    end
+
+
+  end
+end

data/lib/vpndetection/database.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  # The licensed dataset downloads, reached as `client.database`.
+  #
+  # Access is granted by contract rather than self-serve, so every method here
+  # needs a key carrying the `db.download` scope.
+  class Database
+    def initialize(transport, retries:)
+      @transport = transport
+      @api = DatabaseApi.new(transport)
+      @retries = retries
+    end
+
+    # The dataset FAMILIES your organization is licensed to download.
+    #
+    # A license is held against the family, while a download names one version,
+    # so the ids {#download}, {#download_bytes}, {#download_url} and {#checksums}
+    # take come from each family's `versions`, not from the family itself.
+    def list
+      call { @api.list_databases.datasets }
+    end
+
+    # What is inside one dataset: schema, samples, row count and sizes.
+    def metadata(id)
+      call { @api.database_metadata(id) }
+    end
+
+    # The digests for one dataset file.
+    #
+    # Returns the whole set rather than one algorithm: which digests a dataset
+    # publishes is the API's choice, not ours, and the response nests them one
+    # level down under `checksums`.
+    def checksums(id, format)
+      call { @api.database_checksum(id, format).checksums }
+    end
+
+    # Your organization's recent download attempts, newest first.
+    def downloads(limit: nil)
+      call { @api.list_downloads(limit.nil? ? {} : { limit: limit }).downloads }
+    end
+
+    # The time-limited URL for one dataset file.
+    #
+    # The URL is returned rather than the bytes so the caller decides how to
+    # transfer a file that routinely runs to gigabytes; the link authorizes the
+    # START of a transfer, so one already running is not interrupted when it
+    # lapses.
+    def download_url(id, format)
+      call { redirect_location(id, format) }
+    end
+
+    # Download one dataset file to `path`, and return the bytes written.
+    #
+    # The bytes land in a neighboring `.part` file that is renamed on completion,
+    # so a transfer that dies half way leaves no truncated file that reads as a
+    # whole dataset, and a refresh that fails does not destroy the copy already
+    # there. Nothing beyond one chunk is ever held in memory, whatever the
+    # dataset weighs.
+    def download(id, format, path)
+      partial = "#{path}.part"
+      begin
+        url = download_url(id, format)
+        written = Retries.with_retries(@retries) do
+          # Reopened per attempt, so a retry restarts the file rather than
+          # appending a second copy of the body to a half-written one.
+          File.open(partial, 'wb') { |file| stream(url) { |chunk| file.write(chunk) } }
+        end
+        File.rename(partial, path)
+      rescue StandardError
+        File.delete(partial) if File.exist?(partial)
+        raise
+      end
+      written
+    end
+
+    # Download one dataset file and hand back its bytes.
+    #
+    # **This holds the entire file in memory**, and the catalog spans five orders
+    # of magnitude: `cdn_ip_v1` is 10 KB while `resproxy_ip_90d_v1` is 1.79 GB.
+    # Reach for it at the small end, where the bytes go straight into a parser,
+    # and use {#download} for anything you have not measured.
+    def download_bytes(id, format)
+      url = download_url(id, format)
+      Retries.with_retries(@retries) do
+        bytes = String.new(encoding: Encoding::BINARY)
+        stream(url) { |chunk| bytes << chunk }
+        bytes
+      end
+    end
+
+    private
+
+    # Runs one transfer of a presigned link, handing each chunk to the block, and
+    # returns the bytes that reached it.
+    #
+    # Typhoeus only streams when a request carries an `on_body` callback: with
+    # one set, Ethon's write callback passes the chunk on INSTEAD of appending it
+    # to `response.body`, so the ceiling on a transfer of any size is one chunk.
+    # The callback must therefore never answer `:unyielded`, which is the value
+    # that means "nobody took this" and puts the chunk back in the buffer.
+    def stream(url)
+      written = 0
+      served = nil
+      request = @transport.storage_request(url)
+      request.on_headers { |response| served = response.code }
+      request.on_body do |chunk, _response|
+        # An error page has no bounded size, so a refusal is aborted here rather
+        # than read and then classified.
+        next :abort unless served == 200
+
+        yield chunk
+        written += chunk.bytesize
+      end
+
+      settle(request.run, written)
+    end
+
+    def settle(response, written)
+      status = response.code.to_i
+      # No status at all means the transfer never reached HTTP: DNS, connect,
+      # TLS or a timeout, and curl's own reason is the only thing that says
+      # which. It is also what a :partial_file arrives as once a status IS in
+      # hand, which is where a transfer that died mid-flight fails rather than
+      # leaving a short file that reads as a whole dataset. The declared-length
+      # check the other bindings hand-roll is curl's job here.
+      raise Error.from_transport(response) if status.zero?
+
+      unless status == 200
+        raise Error.from_status(status, response.headers, nil,
+                                message: "object storage refused the download link with status #{status}")
+      end
+      raise Error.from_transport(response) unless response.success?
+
+      written
+    end
+
+    # The 302 is this operation's SUCCESS case, but the generated client treats
+    # every non-2xx as a failure, so it arrives as an ApiError carrying the
+    # Location header.
+    def redirect_location(id, format)
+      @api.download_database(id, format)
+      raise Error.new(:server_error, 'expected a redirect to object storage')
+    rescue ApiError => e
+      raise unless e.code == 302
+
+      location = e.response_headers && e.response_headers['Location']
+      raise Error.new(:server_error, 'the redirect carried no Location header', status: 302) if location.nil?
+
+      location.is_a?(Array) ? location.last : location
+    end
+
+    def call(&block)
+      Retries.with_retries(@retries) do
+        block.call
+      rescue ApiError => e
+        raise error_for(e)
+      end
+    end
+
+    def error_for(api_error)
+      return Error.new(:network, api_error.message) if api_error.code.to_i.zero?
+
+      Error.from_status(api_error.code, api_error.response_headers, api_error.response_body)
+    end
+  end
+end