internetdata 1.0.0

data/lib/internetdata/configuration.rb

@@ -0,0 +1,315 @@
+=begin
+#InternetData API
+
+#The InternetData API. Please see https://docs.internetdata.io/api for more details. 
+
+The version of the OpenAPI document: 2026.09.04
+Contact: dev@internetdata.io
+Generated by: https://openapi-generator.tech
+Generator version: 7.25.0
+
+=end
+
+module InternetData
+  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 = 'internetdata.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
+      {
+        'ApiKeyAuth' =>
+          {
+            type: 'api_key',
+            in: 'query',
+            key: 'apikey',
+            value: api_key_with_prefix('apikey')
+          },
+        'BearerAuth' =>
+          {
+            type: 'bearer',
+            in: 'header',
+            key: 'Authorization',
+            value: "Bearer #{access_token_with_refresh}"
+          },
+      }
+    end
+
+    # Returns an array of Server setting
+    def server_settings
+      [
+        {
+          url: "https://internetdata.io",
+          description: "No description provided",
+        }
+      ]
+    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/internetdata/database_api.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module InternetData
+  # The licensed database downloads, reached as `client.database`.
+  #
+  # Not to be confused with {Database}, which is one entry in a {#list}, nor with
+  # the generated {DatabaseV2Api} underneath, which speaks the wire.
+  class DatabaseApi
+    def initialize(transport, retries:)
+      @transport = transport
+      @api = DatabaseV2Api.new(transport)
+      @retries = retries
+    end
+
+    # The database FAMILIES your organization may see, with its license beside
+    # each one.
+    #
+    # A license is held against the family while a download names one version, so
+    # the ids {#download}, {#download_bytes}, {#download_url}, {#checksums} and
+    # {#metadata} take come from each family's `versions`, not from the family.
+    #
+    # `standing` is the discovery surface for the PUBLISHED catalog only. A
+    # database commissioned for a single customer is ABSENT from this listing for
+    # everyone else, rather than present with a standing of `unlicensed`, and the
+    # server decides that per key. So the catalog is not the same for every key,
+    # a listing fetched with one key says nothing about another, and there is no
+    # other source to reconstruct it from.
+    def list
+      call { @api.list_databases.databases }
+    end
+
+    # What is inside one database: schema, sample rows, row count and sizes.
+    #
+    # `updated` and `entries` answer whether today's build is worth fetching, and
+    # `size` is bytes per format, which is what a transfer should be budgeted
+    # against before it starts.
+    def metadata(id)
+      call { @api.database_metadata_v2(id) }
+    end
+
+    # The digests for one published file.
+    #
+    # Returns the whole set rather than one algorithm: which digests a database
+    # 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_v2(id, format).checksums }
+    end
+
+    # Your organization's recent download attempts, newest first, refusals
+    # included.
+    def downloads(limit: nil)
+      call { @api.list_downloads(limit.nil? ? {} : { limit: limit }).downloads }
+    end
+
+    # The time-limited URL for one database file.
+    #
+    # Presigned, so it carries no credential of yours and can be handed to
+    # anything that speaks HTTP. 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 database 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 database, and a refresh that fails does not destroy the copy already
+    # there. Nothing beyond one chunk is ever held in memory, whatever the
+    # database 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 database file and hand back its bytes.
+    #
+    # **This holds the entire file in memory**, and the catalog spans seven orders
+    # of magnitude: `bogon_asn_v1` is a few hundred bytes while the largest
+    # published database is over 5 GiB. Reach for it at the small end, where the
+    # bytes go straight into a parser, and use {#download} for anything you have
+    # not measured with {#metadata}.
+    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 database. The declared-length
+      # check 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_v2(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

data/lib/internetdata/errors.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module InternetData
+  # Everything this library raises.
+  #
+  # `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are NOT the
+  # same thing. A rate limit is the API protecting itself and carries
+  # `Retry-After`; retrying works. A spent quota carries no such header and
+  # retrying will not help until the window rolls over or the limit is raised.
+  # The header is the only thing that distinguishes them.
+  class Error < StandardError
+    KINDS = %i[
+      bad_request unauthorized forbidden rate_limited quota_exceeded server_error network
+    ].freeze
+
+    RETRYABLE = %i[rate_limited server_error network].freeze
+
+    # The API's machine-readable result code, when the refusal carried one:
+    # `NOT_LICENSED`, `UNKNOWN_DATASET`, `NOT_AVAILABLE` and so on. Deliberately
+    # not an enum, so a code added later stays readable by a client built today.
+    attr_reader :kind, :status, :rc, :retry_after_seconds
+
+    def initialize(kind, message, status: nil, rc: nil, retry_after_seconds: nil)
+      super(message)
+      @kind = kind
+      @status = status
+      @rc = rc
+      @retry_after_seconds = retry_after_seconds
+    end
+
+    # Whether retrying this exact request could succeed.
+    def retryable?
+      RETRYABLE.include?(@kind)
+    end
+
+    # `message:` stands in for the response body, for a response whose body must
+    # not be read: an object storage error page has no bounded size, so a refusal
+    # from it is classified on the status alone.
+    def self.from_status(status, headers, body, message: nil)
+      rc = rc_of(body)
+      message ||= rc || "request failed with status #{status}"
+      retry_after = parse_retry_after(header(headers, 'retry-after'))
+
+      case status
+      when 429
+        # Present means transient, absent means an allowance is spent. Nothing
+        # else in the response separates the two.
+        if retry_after.nil?
+          new(:quota_exceeded, message, status: status, rc: rc)
+        else
+          new(:rate_limited, message, status: status, rc: rc, retry_after_seconds: retry_after)
+        end
+      when 400 then new(:bad_request, message, status: status, rc: rc)
+      when 401 then new(:unauthorized, message, status: status, rc: rc)
+      when 403 then new(:forbidden, message, status: status, rc: rc)
+      # Every other 4xx is a CLIENT error. Classifying on the RANGE rather than
+      # on an enumerated list is what keeps a 404 from an unknown database id
+      # falling through to the retryable server_error default and being retried
+      # twice before it fails.
+      when 400..499 then new(:bad_request, message, status: status, rc: rc)
+      else new(:server_error, message, status: status, rc: rc)
+      end
+    end
+
+    # A Typhoeus response that never carried an HTTP status: DNS failure,
+    # connection refused, TLS failure, or a timeout.
+    def self.from_transport(response)
+      message = response.return_message || response.return_code&.to_s || 'transport failure'
+      new(:network, message)
+    end
+
+    # Case-insensitive, and works with a plain Hash as well as with the
+    # case-blind header object Typhoeus builds from a live response.
+    def self.header(headers, name)
+      return nil if headers.nil?
+
+      value = headers[name] || headers[name.split('-').map(&:capitalize).join('-')]
+      value = headers.find { |k, _| k.to_s.downcase == name }&.last if value.nil?
+      value.is_a?(Array) ? value.last : value
+    end
+
+    # Every refusal this API writes is a `{"rc": "..."}` envelope. An
+    # intermediary's HTML error page parses as neither JSON nor that, and leaves
+    # the status to speak for itself.
+    def self.rc_of(body)
+      parsed = body.is_a?(String) ? (JSON.parse(body) rescue nil) : body
+      return nil unless parsed.is_a?(Hash)
+
+      parsed['rc'].is_a?(String) && !parsed['rc'].empty? ? parsed['rc'] : nil
+    end
+
+    def self.parse_retry_after(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      seconds = Float(value, exception: false)
+      return seconds if seconds && seconds >= 0
+
+      # The header also permits an HTTP date.
+      when_at = Time.httpdate(value) rescue nil
+      return nil if when_at.nil?
+
+      [0, (when_at - Time.now).ceil].max
+    end
+
+    private_class_method :header, :rc_of, :parse_retry_after
+  end
+end