latitude-api 0.2.0

data/lib/latitude/api/objects.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    # Shared, read-only value objects that appear as nested attributes across
+    # many resources (project/team/currency/limits/stats/billing/tag/user/role).
+    module Objects
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] code
+      #   @return [String]
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] currency_id
+      #   @return [String]
+      class Currency < APIObject
+        attribute :id, :string, read_only: true
+        attribute :code, :string, read_only: true
+        attribute :name, :string, read_only: true
+        attribute :currency_id, :string, read_only: true
+      end
+
+      # @!attribute [r] bare_metal
+      #   @return [Integer]
+      # @!attribute [r] bare_metal_gpu
+      #   @return [Integer]
+      # @!attribute [r] virtual_machine
+      #   @return [Integer]
+      # @!attribute [r] virtual_machine_gpu
+      #   @return [Integer]
+      # @!attribute [r] elastic_ip
+      #   @return [Integer]
+      # @!attribute [r] virtual_network
+      #   @return [Integer]
+      # @!attribute [r] database
+      #   @return [String]
+      # @!attribute [r] filesystem
+      #   @return [String]
+      # @!attribute [r] block_storage
+      #   @return [String]
+      class Limits < APIObject
+        attribute :bare_metal, :integer, read_only: true
+        attribute :bare_metal_gpu, :integer, read_only: true
+        attribute :virtual_machine, :integer, read_only: true
+        attribute :virtual_machine_gpu, :integer, read_only: true
+        attribute :elastic_ip, :integer, read_only: true
+        attribute :virtual_network, :integer, read_only: true
+        attribute :database, :string, read_only: true
+        attribute :filesystem, :string, read_only: true
+        attribute :block_storage, :string, read_only: true
+      end
+
+      # @!attribute [r] databases
+      #   @return [Integer]
+      # @!attribute [r] ip_addresses
+      #   @return [Integer]
+      # @!attribute [r] prefixes
+      #   @return [Integer]
+      # @!attribute [r] servers
+      #   @return [Integer]
+      # @!attribute [r] storages
+      #   @return [Integer]
+      # @!attribute [r] virtual_machines
+      #   @return [Integer]
+      # @!attribute [r] vlans
+      #   @return [Integer]
+      class Stats < APIObject
+        attribute :databases, :integer, read_only: true
+        attribute :ip_addresses, :integer, read_only: true
+        attribute :prefixes, :integer, read_only: true
+        attribute :servers, :integer, read_only: true
+        attribute :storages, :integer, read_only: true
+        attribute :virtual_machines, :integer, read_only: true
+        attribute :vlans, :integer, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] customer_billing_id
+      #   @return [String]
+      # @!attribute [r] subscription_id
+      #   @return [String]
+      # @!attribute [r] type
+      #   @return [String]
+      # @!attribute [r] method
+      #   @return [String]
+      class Billing < APIObject
+        attribute :id, :string, read_only: true
+        attribute :customer_billing_id, :string, read_only: true
+        attribute :subscription_id, :string, read_only: true
+        attribute :type, :string, read_only: true
+        attribute :method, :string, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] created_at
+      #   @return [Time]
+      # @!attribute [r] updated_at
+      #   @return [Time]
+      class Role < APIObject
+        attribute :id, :string, read_only: true
+        attribute :name, :string, read_only: true
+        attribute :created_at, :time, read_only: true
+        attribute :updated_at, :time, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] description
+      #   @return [String]
+      # @!attribute [r] color
+      #   @return [String]
+      class Tag < APIObject
+        attribute :id, :string, read_only: true
+        attribute :name, :string, read_only: true
+        attribute :description, :string, read_only: true
+        attribute :color, :string, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] slug
+      #   @return [String]
+      # @!attribute [r] description
+      #   @return [String]
+      # @!attribute [r] address
+      #   @return [String]
+      # @!attribute [r] currency
+      #   @return [Latitude::API::Objects::Currency]
+      # @!attribute [r] status
+      #   @return [String]
+      # @!attribute [r] feature_flags
+      #   @return [Array]
+      # @!attribute [r] limits
+      #   @return [Latitude::API::Objects::Limits]
+      class Team < APIObject
+        attribute :id, :string, read_only: true
+        attribute :name, :string, read_only: true
+        attribute :slug, :string, read_only: true
+        attribute :description, :string, read_only: true
+        attribute :address, :string, read_only: true
+        attribute :currency, Objects::Currency, read_only: true
+        attribute :status, :string, read_only: true
+        attribute :feature_flags, :array, read_only: true
+        attribute :limits, Objects::Limits, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] slug
+      #   @return [String]
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] description
+      #   @return [String]
+      # @!attribute [r] provisioning_type
+      #   @return [String]
+      # @!attribute [r] billing_type
+      #   @return [String]
+      # @!attribute [r] billing_method
+      #   @return [String]
+      # @!attribute [r] bandwidth_alert
+      #   @return [Boolean]
+      # @!attribute [r] environment
+      #   @return [String]
+      # @!attribute [r] billing
+      #   @return [Latitude::API::Objects::Billing]
+      # @!attribute [r] stats
+      #   @return [Latitude::API::Objects::Stats]
+      class Project < APIObject
+        attribute :id, :string, read_only: true
+        attribute :slug, :string, read_only: true
+        attribute :name, :string, read_only: true
+        attribute :description, :string, read_only: true
+        attribute :provisioning_type, :string, read_only: true
+        attribute :billing_type, :string, read_only: true
+        attribute :billing_method, :string, read_only: true
+        attribute :bandwidth_alert, :boolean, read_only: true
+        attribute :environment, :string, read_only: true
+        attribute :billing, Objects::Billing, read_only: true
+        attribute :stats, Objects::Stats, read_only: true
+      end
+
+      # @!attribute [r] id
+      #   @return [String]
+      # @!attribute [r] email
+      #   @return [String]
+      # @!attribute [r] first_name
+      #   @return [String]
+      # @!attribute [r] last_name
+      #   @return [String]
+      # @!attribute [r] created_at
+      #   @return [Time]
+      # @!attribute [r] updated_at
+      #   @return [Time]
+      # @!attribute [r] role
+      #   @return [Latitude::API::Objects::Role]
+      class User < APIObject
+        attribute :id, :string, read_only: true
+        attribute :email, :string, read_only: true
+        attribute :first_name, :string, read_only: true
+        attribute :last_name, :string, read_only: true
+        attribute :created_at, :time, read_only: true
+        attribute :updated_at, :time, read_only: true
+        attribute :role, Objects::Role, read_only: true
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/action.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Action
+        def action(name, path:, type: nil, method: :post, attributes: {}, accepts: nil, returns: :raw)
+          action_method = method.to_sym
+          action_path   = path
+          action_type   = type
+          action_attrs  = attributes
+          accepts_keys  = accepts ? Array(accepts).map(&:to_sym) : nil
+          returns_mode  = returns
+
+          define_singleton_method(name) do |id, params = {}, opts = {}|
+            params = params.dup
+            path_params = extract_path_params(params, path_param_keys)
+            if accepts_keys
+              unknown = params.keys.map(&:to_sym) - accepts_keys
+              raise ArgumentError, "unknown action params: #{unknown.join(', ')}" unless unknown.empty?
+            end
+            body_attrs = action_attrs.merge(params)
+            body = if action_type
+                     JSONAPI.encode(type: action_type, attributes: body_attrs)
+                   elsif !body_attrs.empty?
+                     JSON.generate(body_attrs)
+                   end
+            url = "#{instance_url(id, path_params: path_params)}/#{action_path}"
+            parsed = execute_request(method: action_method, path: url, body: body, opts: opts)
+            returns_mode == :instance ? construct_from(parsed, opts: opts, path_params: path_params) : parsed
+          end
+
+          define_method(name) do |params = {}, opts = {}|
+            merged = @path_params.merge(params || {})
+            self.class.public_send(name, id, merged, opts)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/create.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Create
+        def create(params = {}, opts = {})
+          params = params.dup
+          path_params = extract_path_params(params, path_param_keys)
+          body = JSONAPI.encode(type: resource_type, attributes: params)
+          parsed = execute_request(
+            method: :post,
+            path: class_url(path_params: path_params),
+            body: body,
+            opts: opts,
+          )
+          construct_from(parsed, opts: opts, path_params: path_params)
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/delete.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Delete
+        def delete(id, params = {}, opts = {})
+          params = params.dup
+          path_params = extract_path_params(params, path_param_keys)
+          query = RequestParams.encode(params)
+          execute_request(
+            method: :delete,
+            path: instance_url(id, path_params: path_params),
+            query: query,
+            opts: opts,
+          )
+          true
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/list.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module List
+        def list(params = {}, opts = {})
+          params = deep_dup_hash(params)
+          path_params = params.delete(:_path_params) || extract_path_params(params, path_param_keys)
+          query = build_query(params)
+          parsed = execute_request(
+            method: :get,
+            path: class_url(path_params: path_params),
+            query: query,
+            opts: opts,
+          )
+          ListObject.new(
+            resource_class: self,
+            parsed: parsed,
+            request_params: params,
+            request_opts: opts,
+            path_params: path_params,
+          )
+        end
+
+        def all(params = {}, opts = {})
+          list(params, opts).auto_paging_each.to_a
+        end
+
+        private
+
+        def build_query(params)
+          params = params.dup
+          sort = params.delete(:sort) || params.delete("sort")
+          encoded = RequestParams.encode(params)
+          encoded_sort = RequestParams.encode_sort(sort)
+          [encoded, encoded_sort && !encoded_sort.empty? ? "sort=#{URI.encode_www_form_component(encoded_sort)}" : nil]
+            .reject { |s| s.nil? || s.empty? }
+            .join("&")
+        end
+
+        def deep_dup_hash(hash)
+          hash.each_with_object({}) do |(k, v), out|
+            out[k] = case v
+                     when Hash  then deep_dup_hash(v)
+                     when Array then v.dup
+                     else v
+                     end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/nested.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Nested
+        def nested_resource(name, class_name:)
+          parent_key = path_param_keys_for_parent
+          define_singleton_method(name) do |id|
+            klass = Object.const_get(class_name)
+            NestedAccessor.new(klass: klass, path_params: { parent_key => id })
+          end
+
+          define_method(name) do
+            klass = Object.const_get(class_name)
+            NestedAccessor.new(klass: klass, path_params: { parent_key => @id })
+          end
+        end
+
+        def path_param_keys_for_parent
+          "#{resource_type.sub(/s\z/, '')}_id".to_sym
+        end
+      end
+
+      class NestedAccessor
+        def initialize(klass:, path_params:)
+          @klass = klass
+          @path_params = path_params
+        end
+
+        def list(params = {}, opts = {})
+          @klass.list(params.merge(@path_params), opts, path_params: @path_params)
+        end
+
+        def retrieve(id, params = {}, opts = {})
+          @klass.retrieve(id, params.merge(@path_params), opts)
+        end
+
+        def create(params = {}, opts = {})
+          @klass.create(params.merge(@path_params), opts)
+        end
+
+        def update(id, params = {}, opts = {})
+          @klass.update(id, params.merge(@path_params), opts)
+        end
+
+        def delete(id, params = {}, opts = {})
+          @klass.delete(id, params.merge(@path_params), opts)
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/retrieve.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Retrieve
+        def retrieve(id, params = {}, opts = {})
+          params = params.dup
+          path_params = extract_path_params(params, path_param_keys)
+          query = RequestParams.encode(params)
+          parsed = execute_request(
+            method: :get,
+            path: instance_url(id, path_params: path_params),
+            query: query,
+            opts: opts,
+          )
+          construct_from(parsed, opts: opts, path_params: path_params)
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/operations/update.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Operations
+      module Update
+        def update(id, params = {}, opts = {})
+          params = params.dup
+          path_params = extract_path_params(params, path_param_keys)
+          body = JSONAPI.encode(type: resource_type, id: id, attributes: params)
+          parsed = execute_request(
+            method: :patch,
+            path: instance_url(id, path_params: path_params),
+            body: body,
+            opts: opts,
+          )
+          construct_from(parsed, opts: opts, path_params: path_params)
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/request_executor.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Latitude
+  module API
+    class RequestExecutor
+      RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+      RETRIABLE_EXCEPTIONS = [
+        EOFError,
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        Errno::EPIPE,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        OpenSSL::SSL::SSLError,
+        SocketError,
+      ].freeze
+
+      def initialize(config)
+        @config = config
+      end
+
+      def execute(method:, path:, query: nil, body: nil, headers: {}, idempotency_key: nil, extra_headers: {})
+        @config.validate_api_key!
+
+        url = build_url(path, query)
+        request_headers = build_headers(method, headers, idempotency_key, extra_headers)
+        options = build_httparty_options(request_headers, body)
+
+        attempts = 0
+        max_retries = @config.max_network_retries
+
+        loop do
+          attempts += 1
+          started = Time.now
+          response = nil
+          begin
+            response = HTTParty.send(method.to_sym, url.to_s, options)
+          rescue *RETRIABLE_EXCEPTIONS => e
+            log_exception(e, method, path, attempts)
+            raise ConnectionError.new("Network error talking to #{url}: #{e.message}", cause: e) if attempts > max_retries
+
+            sleep(backoff_delay(attempts, nil))
+            next
+          end
+
+          duration = ((Time.now - started) * 1000).round
+          log_response(method, path, response, duration)
+
+          if retriable_status?(response.code) && attempts <= max_retries
+            sleep(backoff_delay(attempts, response))
+            next
+          end
+
+          return handle_response(response, method: method, path: path)
+        end
+      end
+
+      private
+
+      def build_url(path, query)
+        base = URI.parse(@config.api_base)
+        resolved = path.start_with?("http://", "https://") ? URI.parse(path) : URI.join("#{base}/", path.sub(%r{^/}, ""))
+        if query && !query.empty?
+          resolved.query = [resolved.query, query].compact.reject(&:empty?).join("&")
+        end
+        resolved
+      end
+
+      def build_headers(method, headers, idempotency_key, extra_headers)
+        h = {}
+        h["Authorization"]  = "Bearer #{@config.api_key}"
+        h["Accept"]         = JSONAPI::MEDIA_TYPE
+        h["Content-Type"]   = "application/json" if %i[post put patch].include?(method.to_sym)
+        h["User-Agent"]     = user_agent
+        h["API-Version"]    = @config.api_version if @config.api_version
+        h["Idempotency-Key"] = idempotency_key if idempotency_key
+
+        (headers || {}).each { |k, v| h[k.to_s] = v.to_s }
+        (extra_headers || {}).each { |k, v| h[k.to_s] = v.to_s }
+        h
+      end
+
+      def build_httparty_options(headers, body)
+        options = {
+          headers: headers,
+          open_timeout: @config.open_timeout,
+          read_timeout: @config.read_timeout,
+          follow_redirects: false,
+          format: :plain,
+        }
+        options[:write_timeout] = @config.write_timeout if @config.write_timeout
+        options[:verify] = @config.verify_ssl_certs
+        options[:ca_path] = @config.ca_bundle_path if @config.ca_bundle_path
+        options[:body] = body if body
+
+        if @config.proxy
+          proxy_uri = URI.parse(@config.proxy)
+          options[:http_proxyaddr] = proxy_uri.host
+          options[:http_proxyport] = proxy_uri.port
+          options[:http_proxyuser] = proxy_uri.user if proxy_uri.user
+          options[:http_proxypass] = proxy_uri.password if proxy_uri.password
+        end
+        options
+      end
+
+      def handle_response(response, method:, path:)
+        status  = response.code
+        body    = response.body
+        headers = normalize_headers(response.headers)
+        request_id = headers["x-request-id"] || headers["request-id"]
+
+        if status.between?(200, 299)
+          return nil if body.nil? || body.empty? || status == 204
+
+          return JSONAPI.parse(body)
+        end
+
+        parsed = begin
+          JSONAPI.parse(body)
+        rescue StandardError
+          nil
+        end
+        klass = Latitude::API.error_class_for_status(status)
+        raise klass.new(
+          nil,
+          http_status: status,
+          http_headers: headers,
+          http_body: body,
+          json_body: parsed,
+          request_id: request_id,
+        )
+      end
+
+      def normalize_headers(headers)
+        return {} if headers.nil?
+
+        result = {}
+        headers.each { |k, v| result[k.to_s.downcase] = v.is_a?(Array) ? v.first : v }
+        result
+      end
+
+      def retriable_status?(status)
+        RETRIABLE_STATUSES.include?(status.to_i)
+      end
+
+      def backoff_delay(attempt, response)
+        if response && response.code.to_i == 429
+          retry_after = extract_retry_after(response)
+          return retry_after.to_f if retry_after
+        end
+        base  = @config.initial_network_retry_delay
+        max   = @config.max_network_retry_delay
+        delay = base * (2**(attempt - 1))
+        jitter = delay * (rand * 0.5)
+        [max, delay + jitter].min
+      end
+
+      def extract_retry_after(response)
+        headers = normalize_headers(response.headers)
+        header = headers["retry-after"]
+        return Integer(header) if header && header.to_s.match?(/\A\d+\z/)
+
+        body = response.body
+        return nil if body.nil? || body.empty?
+
+        parsed = begin
+          JSONAPI.parse(body)
+        rescue StandardError
+          nil
+        end
+        errors = parsed.is_a?(Hash) ? Array(parsed["errors"]) : []
+        errors.each do |e|
+          meta = e["meta"] || {}
+          return Integer(meta["retry_after"]) if meta["retry_after"]
+        end
+        nil
+      end
+
+      def user_agent
+        parts = ["Latitude/v1 RubyBindings/#{VERSION}"]
+        parts << "(#{RUBY_ENGINE} #{RUBY_VERSION}; #{RUBY_PLATFORM})"
+        if (info = @config.app_info)
+          app = +"#{info[:name]}"
+          app << "/#{info[:version]}" if info[:version]
+          app << " (#{info[:url]})" if info[:url]
+          parts << app
+        end
+        parts.join(" ")
+      end
+
+      def log_response(method, path, response, duration_ms)
+        logger = @config.logger
+        return unless logger
+
+        logger.info("latitude-api #{method.to_s.upcase} #{path} status=#{response.code} dur=#{duration_ms}ms")
+        return unless logger.debug?
+
+        parsed = begin
+          JSON.parse(response.body.to_s)
+        rescue StandardError
+          response.body
+        end
+        redacted = Util.redact(parsed, @config.sensitive_fields)
+        logger.debug("latitude-api response: #{redacted.inspect[0..4096]}")
+      end
+
+      def log_exception(exception, method, path, attempt)
+        logger = @config.logger
+        return unless logger
+
+        logger.warn("latitude-api #{method.to_s.upcase} #{path} attempt=#{attempt} error=#{exception.class}: #{exception.message}")
+      end
+    end
+  end
+end