latitude-api 0.2.0

data/lib/latitude/api/attributes.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module Attributes
+      Spec = Struct.new(:name, :type, :read_only, keyword_init: true)
+
+      # Attribute names that collide with core Ruby/internal methods. For these we
+      # still record the spec (so the value is wrapped and documented) but skip the
+      # generated accessor; read them via #[] instead.
+      RESERVED_NAMES = %w[method class send __send__ object_id __id__ hash dup clone
+                          freeze frozen? instance_variable_get instance_variable_set
+                          respond_to? is_a? kind_of? equal? itself].freeze
+
+      module ClassMethods
+        def attribute(name, type = :string, **opts)
+          name = name.to_s
+          read_only = opts.fetch(:read_only, false)
+          attribute_specs[name] = Spec.new(name: name, type: type, read_only: read_only)
+
+          unless RESERVED_NAMES.include?(name)
+            define_method(name) { read_attribute(name) }
+            define_method("#{name}=") { |value| write_attribute(name, value) } unless read_only
+          end
+
+          attribute_specs[name]
+        end
+
+        def attribute_specs
+          @attribute_specs ||= (superclass.respond_to?(:attribute_specs) ? superclass.attribute_specs : {}).dup
+        end
+      end
+
+      module InstanceMethods
+        def attribute_spec(name)
+          self.class.respond_to?(:attribute_specs) ? self.class.attribute_specs[name.to_s] : nil
+        end
+
+        def read_attribute(name)
+          @values[name.to_s]
+        end
+
+        def wrap_attribute(key, value)
+          type = attribute_spec(key)&.type
+
+          if type.is_a?(Array)
+            klass = type.first
+            return Array(value).map { |v| v.is_a?(Hash) ? klass.new(v) : v } if object_class?(klass)
+          elsif object_class?(type)
+            return value.is_a?(Hash) ? type.new(value) : value
+          end
+
+          APIObject.wrap(value)
+        end
+
+        private
+
+        def object_class?(type)
+          type.is_a?(Class) && type <= APIObject
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Latitude
+  class Client
+    RESOURCE_ACCESSORS = {
+      servers:              "Latitude::API::Resources::Server",
+      regions:              "Latitude::API::Resources::Region",
+      roles:                "Latitude::API::Resources::Role",
+      events:               "Latitude::API::Resources::Event",
+      ips:                  "Latitude::API::Resources::IP",
+      plans:                "Latitude::API::Resources::Plan",
+      billing_usage:        "Latitude::API::Resources::BillingUsage",
+      traffic:              "Latitude::API::Resources::Traffic",
+      user_profile:         "Latitude::API::Resources::UserProfile",
+      user_teams:           "Latitude::API::Resources::UserTeam",
+      projects:             "Latitude::API::Resources::Project",
+      ssh_keys:             "Latitude::API::Resources::SSHKey",
+      user_data:            "Latitude::API::Resources::UserData",
+      tags:                 "Latitude::API::Resources::Tag",
+      team:                 "Latitude::API::Resources::Team",
+      api_keys:             "Latitude::API::Resources::APIKey",
+      elastic_ips:          "Latitude::API::Resources::ElasticIP",
+      virtual_networks:     "Latitude::API::Resources::VirtualNetwork",
+      firewalls:            "Latitude::API::Resources::Firewall",
+      vpn_sessions:         "Latitude::API::Resources::VPNSession",
+      storage_filesystems:  "Latitude::API::Resources::Storage::Filesystem",
+      storage_volumes:      "Latitude::API::Resources::Storage::Volume",
+      storage_objects:      "Latitude::API::Resources::Storage::Object",
+      virtual_machines:     "Latitude::API::Resources::VirtualMachine",
+      kubernetes_clusters:  "Latitude::API::Resources::KubernetesCluster",
+    }.freeze
+
+    attr_reader :config
+
+    def initialize(**overrides)
+      @config = Latitude.config.dup_with(**overrides)
+      @accessors = {}
+    end
+
+    def configure
+      yield @config
+      @config
+    end
+
+    def with_config(&blk)
+      Latitude::API::APIResource.with_config(@config, &blk)
+    end
+
+    RESOURCE_ACCESSORS.each do |name, class_name|
+      define_method(name) do
+        @accessors[name] ||= ResourceFacade.new(class_name: class_name, config: @config)
+      end
+    end
+
+    class ResourceFacade
+      def initialize(class_name:, config:)
+        @class_name = class_name
+        @config = config
+      end
+
+      def resource_class
+        @resource_class ||= ::Object.const_get(@class_name)
+      end
+
+      def method_missing(name, *args, **kwargs, &blk)
+        if resource_class.respond_to?(name)
+          Latitude::API::APIResource.with_config(@config) do
+            resource_class.public_send(name, *args, **kwargs, &blk)
+          end
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        resource_class.respond_to?(name) || super
+      end
+    end
+  end
+end

data/lib/latitude/api/configuration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    class Configuration
+      DEFAULT_API_BASE                   = "https://api.latitude.sh"
+      DEFAULT_OPEN_TIMEOUT               = 30
+      DEFAULT_READ_TIMEOUT               = 80
+      DEFAULT_WRITE_TIMEOUT              = 30
+      DEFAULT_MAX_NETWORK_RETRIES        = 0
+      DEFAULT_INITIAL_NETWORK_RETRY_DELAY = 0.5
+      DEFAULT_MAX_NETWORK_RETRY_DELAY    = 5.0
+      DEFAULT_SENSITIVE_FIELDS           = %w[
+        authorization
+        public_key
+        private_key
+        password
+        api_key
+        token
+        kubeconfig
+        credentials
+        ipmi_password
+      ].freeze
+
+      attr_accessor :api_key,
+                    :api_base,
+                    :api_version,
+                    :open_timeout,
+                    :read_timeout,
+                    :write_timeout,
+                    :max_network_retries,
+                    :initial_network_retry_delay,
+                    :max_network_retry_delay,
+                    :proxy,
+                    :verify_ssl_certs,
+                    :ca_bundle_path,
+                    :ca_store,
+                    :logger,
+                    :log_level,
+                    :app_info,
+                    :enable_telemetry,
+                    :sensitive_fields
+
+      def initialize
+        @api_key                     = nil
+        @api_base                    = DEFAULT_API_BASE
+        @api_version                 = nil
+        @open_timeout                = DEFAULT_OPEN_TIMEOUT
+        @read_timeout                = DEFAULT_READ_TIMEOUT
+        @write_timeout               = DEFAULT_WRITE_TIMEOUT
+        @max_network_retries         = DEFAULT_MAX_NETWORK_RETRIES
+        @initial_network_retry_delay = DEFAULT_INITIAL_NETWORK_RETRY_DELAY
+        @max_network_retry_delay     = DEFAULT_MAX_NETWORK_RETRY_DELAY
+        @proxy                       = nil
+        @verify_ssl_certs            = true
+        @ca_bundle_path              = nil
+        @ca_store                    = nil
+        @logger                      = nil
+        @log_level                   = :info
+        @app_info                    = nil
+        @enable_telemetry            = true
+        @sensitive_fields            = DEFAULT_SENSITIVE_FIELDS.dup
+      end
+
+      def dup_with(**overrides)
+        copy = Configuration.new
+        instance_variables.each do |ivar|
+          copy.instance_variable_set(ivar, instance_variable_get(ivar))
+        end
+        overrides.each { |k, v| copy.public_send("#{k}=", v) }
+        copy
+      end
+
+      def api_base_uri
+        URI.parse(@api_base)
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "api_base is not a valid URL: #{@api_base.inspect} (#{e.message})"
+      end
+
+      def validate_api_key!
+        return unless @api_key.nil? || @api_key.to_s.empty?
+
+        raise ConfigurationError,
+              "No API key provided. Set it via Latitude.api_key = '...' or pass api_key: in request options."
+      end
+    end
+  end
+end

data/lib/latitude/api/errors.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Latitude
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ConnectionError < Error
+    attr_reader :cause_error
+
+    def initialize(message = nil, cause: nil)
+      super(message)
+      @cause_error = cause
+    end
+  end
+
+  class APIError < Error
+    class Entry
+      attr_reader :status, :code, :title, :detail, :meta, :raw
+
+      def initialize(raw)
+        @raw    = raw || {}
+        @status = @raw["status"]
+        @code   = @raw["code"]
+        @title  = @raw["title"]
+        @detail = @raw["detail"] || @raw["message"]
+        @meta   = @raw["meta"] || {}
+      end
+
+      def to_s
+        return @detail.to_s if @title.nil? || @title.empty?
+        return @title.to_s if @detail.nil? || @detail.empty?
+
+        "#{@title}: #{@detail}"
+      end
+
+      def to_h
+        @raw.dup
+      end
+    end
+
+    attr_reader :http_status, :http_headers, :http_body, :json_body, :request_id, :entries
+
+    def initialize(message = nil, http_status: nil, http_headers: nil, http_body: nil, json_body: nil, request_id: nil)
+      @http_status  = http_status
+      @http_headers = http_headers || {}
+      @http_body    = http_body
+      @json_body    = json_body
+      @request_id   = request_id
+      @entries      = Array(json_body.is_a?(Hash) ? json_body["errors"] : nil).map { |h| Entry.new(h) }
+      super(message || default_message)
+    end
+
+    alias errors entries
+
+    def code
+      entries.first&.code
+    end
+
+    def title
+      entries.first&.title
+    end
+
+    def detail
+      entries.first&.detail
+    end
+
+    private
+
+    def default_message
+      first = entries.first
+      return first.to_s if first && !first.to_s.empty?
+      return "HTTP #{http_status}" if http_status
+
+      "API error"
+    end
+  end
+
+  class BadRequestError < APIError; end
+  class AuthenticationError < APIError; end
+
+  class PermissionError < APIError
+    READ_ONLY_CODES = %w[
+      READ_ONLY_API_KEY
+      READ_ONLY_KEY
+      read_only_api_key
+      read_only
+    ].freeze
+
+    def read_only_key?
+      entries.any? { |e| READ_ONLY_CODES.include?(e.code.to_s) }
+    end
+
+    def feature_not_enabled?
+      entries.any? { |e| e.code.to_s == "FEATURE_NOT_ENABLED" }
+    end
+  end
+
+  class NotFoundError < APIError; end
+  class ConflictError < APIError; end
+  class UnprocessableEntityError < APIError; end
+
+  class RateLimitError < APIError
+    def retry_after
+      meta_value = entries.map { |e| e.meta["retry_after"] }.compact.first
+      return Integer(meta_value) if meta_value
+
+      header_value = http_headers["retry-after"] || http_headers["Retry-After"]
+      return Integer(header_value) if header_value && header_value.to_s.match?(/\A\d+\z/)
+
+      nil
+    end
+  end
+
+  class ServerError < APIError; end
+
+  module API
+    class << self
+      def error_class_for_status(status)
+        case status
+        when 400 then BadRequestError
+        when 401 then AuthenticationError
+        when 403 then PermissionError
+        when 404 then NotFoundError
+        when 409 then ConflictError
+        when 422 then UnprocessableEntityError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else APIError
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/json_api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    module JSONAPI
+      MEDIA_TYPE = "application/vnd.api+json"
+
+      module_function
+
+      def envelope(type:, attributes: nil, id: nil, relationships: nil)
+        data = { "type" => type.to_s }
+        data["id"] = id.to_s if id
+        data["attributes"] = Util.stringify_keys(attributes) if attributes
+        data["relationships"] = Util.stringify_keys(relationships) if relationships
+        { "data" => data }
+      end
+
+      def encode(type:, attributes: nil, id: nil, relationships: nil)
+        JSON.generate(envelope(type: type, attributes: attributes, id: id, relationships: relationships))
+      end
+
+      def parse(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise APIError.new(
+          "Invalid JSON response from server: #{e.message}",
+          http_body: body,
+        )
+      end
+
+      def extract_errors(parsed)
+        return [] unless parsed.is_a?(Hash)
+
+        Array(parsed["errors"])
+      end
+    end
+  end
+end

data/lib/latitude/api/list_object.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    class ListObject
+      include Enumerable
+
+      attr_reader :data, :meta, :links, :request_params, :resource_class, :request_opts, :path_params
+
+      def initialize(resource_class:, parsed:, request_params: {}, request_opts: {}, path_params: {})
+        @resource_class = resource_class
+        @meta           = parsed.is_a?(Hash) ? (parsed["meta"] || {}) : {}
+        @links          = parsed.is_a?(Hash) ? (parsed["links"] || {}) : {}
+        raw_data        = parsed.is_a?(Hash) ? Array(parsed["data"]) : []
+        @data           = raw_data.map do |row|
+          resource_class.new(row, path_params: path_params, opts: request_opts)
+        end
+        @request_params = request_params || {}
+        @request_opts   = request_opts || {}
+        @path_params    = path_params || {}
+      end
+
+      def each(&blk)
+        @data.each(&blk)
+      end
+
+      def size
+        @data.size
+      end
+
+      alias length size
+
+      def empty?
+        @data.empty?
+      end
+
+      def [](index)
+        @data[index]
+      end
+
+      def first
+        @data.first
+      end
+
+      def last
+        @data.last
+      end
+
+      def to_a
+        @data.dup
+      end
+
+      def page_size
+        value = page_params["size"] || page_params[:size]
+        (value || 20).to_i
+      end
+
+      def page_number
+        value = page_params["number"] || page_params[:number]
+        (value || 1).to_i
+      end
+
+      def has_more?
+        return !!@links["next"] if @links && @links["next"]
+        return page_number < @meta["total_pages"].to_i if @meta && @meta["total_pages"]
+
+        @data.size >= page_size
+      end
+
+      def next_page(opts = {})
+        return empty_page unless has_more?
+
+        params = deep_dup(@request_params)
+        params[:page] ||= {}
+        params[:page][:number] = page_number + 1
+        params[:page][:size]   = page_size
+        fetch(params, opts)
+      end
+
+      def previous_page(opts = {})
+        return empty_page if page_number <= 1
+
+        params = deep_dup(@request_params)
+        params[:page] ||= {}
+        params[:page][:number] = page_number - 1
+        params[:page][:size]   = page_size
+        fetch(params, opts)
+      end
+
+      def auto_paging_each(&blk)
+        page = self
+        loop do
+          page.each(&blk)
+          break unless page.has_more?
+
+          page = page.next_page
+        end
+        self
+      end
+
+      private
+
+      def page_params
+        (@request_params[:page] || @request_params["page"] || {})
+      end
+
+      def fetch(params, opts)
+        merged_opts = @request_opts.merge(opts || {})
+        params = params.merge(_path_params: @path_params)
+        @resource_class.list(params, merged_opts)
+      end
+
+      def empty_page
+        self.class.new(resource_class: @resource_class, parsed: { "data" => [] },
+                       request_params: @request_params, request_opts: @request_opts, path_params: @path_params)
+      end
+
+      def deep_dup(hash)
+        hash.each_with_object({}) do |(k, v), out|
+          out[k] = case v
+                   when Hash then deep_dup(v)
+                   when Array then v.dup
+                   else v
+                   end
+        end
+      end
+    end
+  end
+end