proxmox-api 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbf823b601fbcb8595b19af7580881ef311ce140d1e5d971a9451a3a50c7249a
-  data.tar.gz: 246a3d239a3ffa4966022e2f28c95addcf9787b6b1fd236b2c163a54dd2b837b
+  metadata.gz: f471fb9bb0268e38e3b45da32b2572d29a53d9805e4702e47a6a0c784351f971
+  data.tar.gz: 0364feb0db15bea88f86358ca5299e6c16a70f56a045024db1c63957defa26ec
 SHA512:
-  metadata.gz: 42b320222e6b040bd9d06fa103f61bb177f63b6d9d8c2c034d5ca243387c9526b5cdb0cae56229cabbe2e45f15722c729e8240e880f47c2f4c3da4d67f2789a1
-  data.tar.gz: 2617997f456c221ab6fabfd933c3b3c4b51944a51a43a2204403e23265a59ccef0dbb6b09c3e99b09317f8b3c5d8a05622b48cf17a063f735a16f4fb2a2bd317
+  metadata.gz: 4172c20fc513e1772ab19d0acdd94d2393601ac5a6ad4067a24e30ac52698208580d2a011ee2047d0d41edf93a081aeaf2ae988fbaf4f78b2da94a72c1c16d29
+  data.tar.gz: 95d4895f5e6323b6f0ab9fb79b3bc64e36ed8a735b3d3f9f80fb244db5559f0d744ba587ca047de6290b5dc6408d62124f3754f9357fa4bc4c85ac93613ffd54

data/lib/proxmox_api.rb

@@ -3,13 +3,21 @@
 require 'rest_client'
 require 'json'
 
+# This class is wrapper for Proxmox PVE APIv2.
+# See README for usage examples.
+#
+# @author Eugene Lapeko
 class ProxmoxAPI
-  AUTH_PARAMS  = %i[username realm password otp path privs].freeze
+  AUTH_PARAMS = %i[username realm password otp].freeze
+  RESOURCE_OPTIONS = %i[headers].freeze
   REST_METHODS = %i[get post put delete].freeze
-  SSL_OPTIONS  = %i[ssl_client_cert ssl_client_key ssl_ca_file verify_ssl].freeze
 
+  # This class is used to collect api path before request
   class ApiPath
+    # @param [ProxmoxAPI] api ProxmoxAPI object to call when request is executed
     def initialize(api)
+      raise ArgumentError, 'Not an instance of ProxmoxAPI' unless api.is_a? ProxmoxAPI
+
       @api = api
       @path = []
     end
@@ -24,7 +32,7 @@ class ProxmoxAPI
     end
 
     def method_missing(method, *args)
-      return @api.__send__(:submit, method, to_s, *args) if REST_METHODS.include?(method)
+      return @api.__send__(:submit, method, to_s, *args) if REST_METHODS.any? { |rm| /^#{rm}!?$/.match? method }
 
       @path << method.to_s
       self
@@ -35,12 +43,46 @@ class ProxmoxAPI
     end
   end
 
+  # This exception is raised when Proxmox API returns error code
+  #
+  # @!attribute [r] response
+  #   @return [RestClient::Response] answer from Proxmox server
+  class ApiException < RuntimeError
+    attr_reader :response
+
+    def initialize(response, description)
+      @response = response
+
+      super description
+    end
+  end
+
+  # Constructor method for ProxmoxAPI
+  #
+  # @param [String] cluster hostname/ip of cluster to control
+  # @param [Hash] options cluster connection parameters
+  #
+  # @option options [String] :username - username to be used for connection
+  # @option options [String] :password - password to be used for connection
+  # @option options [String] :realm - auth realm, can be given in :username ('user@realm')
+  # @option options [String] :token - token to be used instead of username, password, and realm
+  # @option options [String] :secret - secret to be used with token
+  # @option options [String] :otp - one-time password for two-factor auth
+  #
+  # @option options [Boolean] :verify_ssl - verify server certificate
+  #
+  # You can also pass here all ssl options supported by rest-client gem
+  # @see https://github.com/rest-client/rest-client
   def initialize(cluster, options)
+    if options.key?(:token) && options.key?(:secret)
+      options[:headers] = { Authorization: "PVEAPIToken=#{options[:token]}=#{options[:secret]}" }
+    end
+
     @connection = RestClient::Resource.new(
       "https://#{cluster}:#{options[:port] || 8006}/api2/json/",
-      options.select { |k, _v| SSL_OPTIONS.include? k }
+      options.select { |k, _v| connection_options.include?(k.to_s) }
     )
-    @auth_ticket = create_auth_ticket(options.select { |k, _v| AUTH_PARAMS.include? k })
+    @auth_ticket = options.key?(:token) ? {} : create_auth_ticket(options.select { |k, _v| AUTH_PARAMS.include? k })
   end
 
   def [](index)
@@ -55,11 +97,23 @@ class ProxmoxAPI
     true
   end
 
+  # The list of options to be passed to RestClient object
+  def self.connection_options
+    RestClient::Request::SSLOptionList.unshift('verify_ssl') + RESOURCE_OPTIONS
+  end
+
   private
 
+  def raise_on_failure(response, message = 'Proxmox API request failed')
+    return unless response.code.to_i >= 400
+
+    raise ApiException.new(response, message)
+  end
+
   def create_auth_ticket(options)
     @connection['access/ticket'].post options do |response, _request, _result, &_block|
-      # TODO: raise unless response.code == 200
+      raise_on_failure(response, 'Proxmox authentication failure')
+
       data = JSON.parse(response.body, symbolize_names: true)[:data]
       {
         cookies: { PVEAuthCookie: data[:ticket] },
@@ -80,8 +134,14 @@ class ProxmoxAPI
   end
 
   def submit(method, url, data = {})
+    if /!$/.match? method
+      method = method.to_s.tr('!', '').to_sym
+      skip_raise = true
+    end
+
     @connection[url].__send__(method, *prepare_options(method, data)) do |response|
-      # TODO: raise unless response.code == 200
+      raise_on_failure(response) unless skip_raise
+
       JSON.parse(response.body, symbolize_names: true)[:data]
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proxmox-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Eugene Lapeko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-27 00:00:00.000000000 Z
+date: 2022-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -38,7 +38,49 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
-description: A library to manage Proxmox VE cluster using APIv2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Proxmox VE REST API wrapper
 email: eugene@lapeko.info
 executables: []
 extensions: []
@@ -50,7 +92,8 @@ files:
 homepage: https://github.com/L-Eugene/proxmox-api
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -59,15 +102,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
-summary: A library to manage Proxmox VE cluster
+summary: Proxmox VE REST API wrapper
 test_files: []