cloudstack_client 1.5.12 → 2.0.0

data/test/connection_test.rb

@@ -0,0 +1,364 @@
+require "test_helper"
+
+describe CloudstackClient::Connection do
+  let(:connection) do
+    CloudstackClient::Connection.new(
+      TestHelpers::TEST_URL,
+      TestHelpers::TEST_KEY,
+      TestHelpers::TEST_SECRET,
+      quiet: true
+    )
+  end
+
+  describe "input validation" do
+    it "raises when the API URL is missing" do
+      _(proc { CloudstackClient::Connection.new(nil, "k", "s") })
+        .must_raise CloudstackClient::InputError
+    end
+
+    it "raises when the API key is missing" do
+      _(proc { CloudstackClient::Connection.new("http://url", nil, "s") })
+        .must_raise CloudstackClient::InputError
+    end
+
+    it "raises when the secret key is missing" do
+      _(proc { CloudstackClient::Connection.new("http://url", "k", nil) })
+        .must_raise CloudstackClient::InputError
+    end
+
+    it "raises when the async poll interval is below 1 second" do
+      error = _(proc {
+        CloudstackClient::Connection.new("http://url", "k", "s", async_poll_interval: 0.5)
+      }).must_raise CloudstackClient::InputError
+      _(error.message).must_match(/POLL INTERVAL/)
+    end
+
+    it "raises when the async timeout is below 60 seconds" do
+      error = _(proc {
+        CloudstackClient::Connection.new("http://url", "k", "s", async_timeout: 30)
+      }).must_raise CloudstackClient::InputError
+      _(error.message).must_match(/ASYNC TIMEOUT/)
+    end
+
+    it "raises when request retries is below 1" do
+      error = _(proc {
+        CloudstackClient::Connection.new("http://url", "k", "s", request_retries: 0)
+      }).must_raise CloudstackClient::InputError
+      _(error.message).must_match(/REQUEST RETRIES/)
+    end
+
+    it "applies the documented defaults" do
+      _(connection.read_timeout).must_equal CloudstackClient::Connection::DEF_REQ_TIMEOUT
+      _(connection.async_timeout).must_equal CloudstackClient::Connection::DEF_ASYNC_TIMEOUT
+      _(connection.async_poll_interval).must_equal CloudstackClient::Connection::DEF_POLL_INTERVAL
+      _(connection.request_retries).must_equal CloudstackClient::Connection::DEF_REQUEST_RETRIES
+      _(connection.verify_ssl).must_equal true
+      _(connection).wont_respond_to :secret_key=
+    end
+
+    it "allows SSL verification to be disabled explicitly" do
+      configured = CloudstackClient::Connection.new(
+        TestHelpers::TEST_URL,
+        TestHelpers::TEST_KEY,
+        TestHelpers::TEST_SECRET,
+        verify_ssl: false,
+        ca_file: "/tmp/cloudstack-ca.pem"
+      )
+
+      _(configured.verify_ssl).must_equal false
+      _(configured.ca_file).must_equal "/tmp/cloudstack-ca.pem"
+    end
+  end
+
+  describe "request signing" do
+    # Golden value: HMAC-SHA1 of the downcased payload, Base64 encoded and then
+    # URL escaped. Pinned so a change to the signing algorithm fails loudly.
+    it "signs the downcased payload with HMAC-SHA1" do
+      expected = CGI.escape(
+        Base64.encode64(
+          OpenSSL::HMAC.digest("sha1", TestHelpers::TEST_SECRET, "apikey=test-key&command=listzones")
+        ).chomp
+      )
+
+      _(connection.send(:create_signature, "apiKey=test-key&command=listZones"))
+        .must_equal expected
+    end
+
+    it "is case insensitive, because the payload is downcased before signing" do
+      _(connection.send(:create_signature, "command=listZones"))
+        .must_equal connection.send(:create_signature, "COMMAND=LISTZONES")
+    end
+
+    it "sends the signature and apiKey with the request" do
+      stub_list("listZones", "zone", [{ "id" => "1" }])
+      connection.send_request("command" => "listZones")
+
+      params = last_request_params
+      _(params["apiKey"].first).must_equal TestHelpers::TEST_KEY
+      _(params["response"].first).must_equal "json"
+      _(params["signature"].first).wont_be_nil
+    end
+  end
+
+  describe "parameter serialization" do
+    it "sorts parameters, since the signature depends on their order" do
+      _(connection.send(:params_to_data, "z" => "1", "a" => "2", "m" => "3"))
+        .must_equal "a=2&m=3&z=1"
+    end
+
+    it "serializes an Array of Hashes as an indexed map" do
+      data = connection.send(:params_to_data,
+        "tags" => [{ "key" => "role", "value" => "web" }])
+
+      _(data).must_equal "tags[0].key=role&tags[0].value=web"
+    end
+
+    it "serializes a Hash as an indexed key/value map" do
+      data = connection.send(:params_to_data, "details" => { "cpu" => "2" })
+
+      _(data).must_equal "details[0].key=cpu&details[0].value=2"
+    end
+
+    it "escapes spaces as %20 rather than +" do
+      _(connection.send(:escape, "my machine")).must_equal "my%20machine"
+    end
+
+    it "leaves asterisks unescaped" do
+      _(connection.send(:escape, "*")).must_equal "*"
+    end
+
+    it "escapes reserved characters" do
+      _(connection.send(:escape, "a&b=c")).must_equal "a%26b%3Dc"
+    end
+  end
+
+  describe "response unwrapping" do
+    it "returns the collection from a count plus collection response" do
+      stub_list("listZones", "zone", [{ "id" => "1" }, { "id" => "2" }])
+
+      _(connection.send_request("command" => "listZones"))
+        .must_equal [{ "id" => "1" }, { "id" => "2" }]
+    end
+
+    it "keeps the count when include_count is requested" do
+      stub_list("listZones", "zone", [{ "id" => "1" }])
+
+      result = connection.send_request({ "command" => "listZones" }, include_count: true)
+      _(result["count"]).must_equal 1
+      _(result["zone"]).must_equal [{ "id" => "1" }]
+    end
+
+    it "returns an empty Array for a zero count response" do
+      stub_command("listZones", { "listzonesresponse" => { "count" => 0 } })
+
+      _(connection.send_request("command" => "listZones")).must_equal []
+    end
+
+    it "unwraps a single nested Hash" do
+      stub_command("createUser", { "createuserresponse" => { "user" => { "id" => "42" } } })
+
+      _(connection.send_request("command" => "createUser")).must_equal("id" => "42")
+    end
+
+    it "returns a scalar-valued body unchanged" do
+      stub_command("someCommand", { "somecommandresponse" => { "jobid" => "job-9" } })
+
+      _(connection.send_request("command" => "someCommand")).must_equal("jobid" => "job-9")
+    end
+
+    it "returns an empty body as an empty Array" do
+      stub_command("listZones", { "listzonesresponse" => {} })
+
+      _(connection.send_request("command" => "listZones")).must_equal []
+    end
+  end
+
+  describe "symbolized keys" do
+    let(:connection) do
+      CloudstackClient::Connection.new(
+        TestHelpers::TEST_URL, TestHelpers::TEST_KEY, TestHelpers::TEST_SECRET,
+        quiet: true, symbolize_keys: true
+      )
+    end
+
+    it "returns Symbol keys throughout the response" do
+      stub_list("listZones", "zone", [{ "id" => "1", "name" => "zone1" }])
+
+      _(connection.send_request("command" => "listZones"))
+        .must_equal [{ id: "1", name: "zone1" }]
+    end
+
+    it "still strips the count key when it is symbolized" do
+      stub_list("listZones", "zone", [{ "id" => "1" }])
+      result = connection.send_request("command" => "listZones")
+
+      _(result).must_equal [{ id: "1" }]
+    end
+  end
+
+  describe "error handling" do
+    it "raises ApiError with the errortext for a non-200 response" do
+      stub_command("listZones",
+        { "listzonesresponse" => { "errortext" => "Unable to execute" } },
+        status: 431)
+
+      error = _(proc { connection.send_request("command" => "listZones") })
+        .must_raise CloudstackClient::ApiError
+      _(error.message).must_match(/431/)
+      _(error.message).must_match(/Unable to execute/)
+    end
+
+    it "raises ParseError when the body is not JSON" do
+      stub_request(:get, ApiStubs::ANY_REQUEST).to_return(status: 200, body: "<html>oops</html>")
+
+      error = _(proc { connection.send_request("command" => "listZones") })
+        .must_raise CloudstackClient::ParseError
+      _(error.message).must_match(/not readable/)
+    end
+
+    it "raises ConnectionError when the endpoint is unreachable" do
+      stub_request(:get, ApiStubs::ANY_REQUEST).to_raise(Errno::ECONNREFUSED)
+
+      error = _(proc { connection.send_request("command" => "listZones") })
+        .must_raise CloudstackClient::ConnectionError
+      _(error.message).must_match(/is not reachable/)
+    end
+  end
+
+  describe "retries" do
+    it "makes exactly one attempt with the default retry setting" do
+      stub_request(:get, ApiStubs::ANY_REQUEST).to_raise(Errno::ECONNREFUSED)
+
+      error = _(proc { connection.send_request("command" => "listZones") })
+        .must_raise CloudstackClient::ConnectionError
+      _(error.message).must_match(/after 1 attempt/)
+      assert_requested(:get, ApiStubs::ANY_REQUEST, times: 1)
+    end
+
+    it "retries up to request_retries attempts before giving up" do
+      connection = CloudstackClient::Connection.new(
+        TestHelpers::TEST_URL, TestHelpers::TEST_KEY, TestHelpers::TEST_SECRET,
+        quiet: true, request_retries: 3
+      )
+      stub_request(:get, ApiStubs::ANY_REQUEST).to_raise(Errno::ECONNREFUSED)
+
+      error = connection.stub(:sleep, nil) do
+        _(proc { connection.send_request("command" => "listZones") })
+          .must_raise CloudstackClient::ConnectionError
+      end
+
+      _(error.message).must_match(/after 3 attempts/)
+      assert_requested(:get, ApiStubs::ANY_REQUEST, times: 3)
+    end
+
+    it "returns the result when a retry succeeds" do
+      connection = CloudstackClient::Connection.new(
+        TestHelpers::TEST_URL, TestHelpers::TEST_KEY, TestHelpers::TEST_SECRET,
+        quiet: true, request_retries: 3
+      )
+      stub_request(:get, ApiStubs::ANY_REQUEST)
+        .to_raise(Errno::ECONNREFUSED)
+        .then.to_return(
+          status: 200,
+          body: JSON.generate("listzonesresponse" => { "count" => 1, "zone" => [{ "id" => "1" }] })
+        )
+
+      result = connection.stub(:sleep, nil) do
+        connection.send_request("command" => "listZones")
+      end
+
+      _(result).must_equal [{ "id" => "1" }]
+    end
+  end
+
+  describe "asynchronous requests" do
+    it "returns the jobresult once the job succeeds" do
+      stub_async("deployVirtualMachine",
+        polls: [job_success("virtualmachine" => { "id" => "vm-1" })])
+
+      result = connection.stub(:sleep, nil) do
+        connection.send_async_request("command" => "deployVirtualMachine")
+      end
+
+      _(result).must_equal("virtualmachine" => { "id" => "vm-1" })
+    end
+
+    it "polls until the job leaves the pending state" do
+      stub_async("deployVirtualMachine",
+        polls: [job_pending, job_pending, job_success("id" => "vm-1")])
+
+      result = connection.stub(:sleep, nil) do
+        connection.send_async_request("command" => "deployVirtualMachine")
+      end
+
+      _(result).must_equal("id" => "vm-1")
+    end
+
+    it "raises JobError when the job fails" do
+      stub_async("deployVirtualMachine",
+        polls: [job_failure("Insufficient capacity")])
+
+      error = connection.stub(:sleep, nil) do
+        _(proc { connection.send_async_request("command" => "deployVirtualMachine") })
+          .must_raise CloudstackClient::JobError
+      end
+
+      _(error.message).must_match(/Insufficient capacity/)
+      _(error.message).must_match(/530/)
+    end
+
+    it "raises JobError when a failed job has no error text" do
+      stub_async(
+        "deployVirtualMachine",
+        polls: [{ "jobstatus" => 2, "jobresultcode" => 530 }]
+      )
+
+      error = connection.stub(:sleep, nil) do
+        _(proc { connection.send_async_request("command" => "deployVirtualMachine") })
+          .must_raise CloudstackClient::JobError
+      end
+
+      _(error.message).must_match(/Unknown error/)
+    end
+
+    it "raises TimeoutError when the job never completes" do
+      stub_async("deployVirtualMachine", polls: [job_pending])
+
+      error = connection.stub(:sleep, nil) do
+        _(proc { connection.send_async_request("command" => "deployVirtualMachine") })
+          .must_raise CloudstackClient::TimeoutError
+      end
+
+      _(error.message).must_match(/timed out/)
+    end
+
+    it "rejects per-request async options that are out of range" do
+      _(proc {
+        connection.send_async_request({ "command" => "x" }, async_timeout: 5)
+      }).must_raise CloudstackClient::InputError
+    end
+  end
+
+  describe "the host option" do
+    it "sets the Host header when a host is given" do
+      connection = CloudstackClient::Connection.new(
+        TestHelpers::TEST_URL, TestHelpers::TEST_KEY, TestHelpers::TEST_SECRET,
+        quiet: true, host: "cloudstack.internal"
+      )
+      stub_list("listZones", "zone", [{ "id" => "1" }])
+
+      connection.send_request("command" => "listZones")
+
+      assert_requested(:get, ApiStubs::ANY_REQUEST,
+        headers: { "Host" => "cloudstack.internal" }, times: 1)
+    end
+
+    it "omits the Host header when no host is given" do
+      stub_list("listZones", "zone", [{ "id" => "1" }])
+      connection.send_request("command" => "listZones")
+
+      signature = WebMock::RequestRegistry.instance.requested_signatures.hash.keys.last
+      _(signature.headers.to_h.keys.map(&:downcase)).wont_include "host"
+    end
+  end
+end

data/test/data/cloudstack-empty.yml

@@ -0,0 +1,3 @@
+:url: ""
+:api_key: test-key
+:secret_key: test-secret

data/test/data/cloudstack-incomplete.yml

@@ -0,0 +1,5 @@
+---
+:default: test1
+test1:
+  :url: https://cloud.test/client/api
+  :api_key: only-an-api-key-no-secret

data/test/data/cloudstack-malformed.yml

@@ -0,0 +1,5 @@
+---
+:default: test1
+test1:
+  :url: "unterminated
+   :api_key: [1, 2

data/test/data/cloudstack-unsafe.yml

@@ -0,0 +1 @@
+--- !ruby/object:Object {}

data/test/support/api_stubs.rb

@@ -0,0 +1,85 @@
+require "json"
+
+# Helpers for stubbing CloudStack HTTP responses.
+#
+# Every CloudStack request carries a generated `signature` query parameter, so
+# stubs match on the `command` parameter with `hash_including` rather than on a
+# full URL.
+module ApiStubs
+  API_ENDPOINT = "https://cloudstack.test/client/api".freeze
+
+  # WebMock matches a bare URL only against requests with no query string, and
+  # every CloudStack request carries one. Match on the endpoint prefix instead.
+  ANY_REQUEST = %r{\Ahttps://cloudstack\.test/client/api}.freeze
+
+  # Stub a CloudStack command with an already-shaped response body.
+  #
+  #   stub_command("listZones", "listzonesresponse" => { "count" => 1, ... })
+  def stub_command(command, body, status: 200)
+    stub_request(:get, API_ENDPOINT)
+      .with(query: hash_including("command" => command))
+      .to_return(
+        status: status,
+        body: JSON.generate(body),
+        headers: { "Content-Type" => "application/json" }
+      )
+  end
+
+  # Stub a command using CloudStack's usual envelope:
+  # { "<command>response" => { "count" => n, "<entity>" => [...] } }
+  def stub_list(command, entity, items, count: nil, extra: {})
+    inner = { "count" => count || items.size, entity => items }.merge(extra)
+    stub_command(command, { "#{command.downcase}response" => inner })
+  end
+
+  # Stub the initial async command, then the queryAsyncJobResult polls.
+  #
+  # `polls` is an array of jobstatus payloads returned in order.
+  def stub_async(command, job_id: "job-1", polls: [])
+    stub_command(command, { "#{command.downcase}response" => { "jobid" => job_id } })
+
+    responses = polls.map do |poll|
+      {
+        status: 200,
+        body: JSON.generate("queryasyncjobresultresponse" => poll),
+        headers: { "Content-Type" => "application/json" }
+      }
+    end
+
+    stub_request(:get, API_ENDPOINT)
+      .with(query: hash_including("command" => "queryAsyncJobResult"))
+      .to_return(*responses)
+  end
+
+  # A completed async job payload.
+  def job_success(result)
+    { "jobstatus" => 1, "jobresult" => result }
+  end
+
+  # A failed async job payload.
+  def job_failure(errortext, code: 530)
+    {
+      "jobstatus" => 2,
+      "jobresultcode" => code,
+      "jobresult" => { "errortext" => errortext }
+    }
+  end
+
+  # An in-flight async job payload.
+  def job_pending
+    { "jobstatus" => 0 }
+  end
+
+  # Parsed query parameters of the most recent request, for asserting on how
+  # a request was built rather than only on what came back.
+  def last_request_params
+    signature = WebMock::RequestRegistry.instance.requested_signatures.hash.keys.last
+    raise "no request was made" if signature.nil?
+
+    # CGI.parse was removed in Ruby 4.0; only CGI.escape/unescape remain.
+    URI.decode_www_form(signature.uri.query.to_s)
+       .each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(key, value), acc|
+         acc[key] << value
+       end
+  end
+end

data/test/test_helper.rb

@@ -2,4 +2,41 @@ require "cloudstack_client"
 
 require "minitest/spec"
 require "minitest/autorun"
-require "minitest/pride"
+# Minitest 6 extracted Object#stub into the minitest-mock gem.
+require "minitest/mock"
+require "minitest/reporters"
+
+require "webmock/minitest"
+
+# No test may reach the network. An accidental live request should fail loudly
+# rather than turn into a slow or flaky test.
+WebMock.disable_net_connect!(allow_localhost: false)
+
+Minitest::Reporters.use!(
+  ENV["CI"] ? Minitest::Reporters::ProgressReporter.new : Minitest::Reporters::SpecReporter.new
+)
+
+require_relative "support/api_stubs"
+
+module TestHelpers
+  TEST_URL    = "https://cloudstack.test/client/api".freeze
+  TEST_KEY    = "test-key".freeze
+  TEST_SECRET = "test-secret".freeze
+
+  def fixture_path(*parts)
+    File.join(File.expand_path("data", __dir__), *parts)
+  end
+
+  # A client with no dynamically defined API methods: useful when the test
+  # targets Connection behaviour rather than the generated command methods.
+  def bare_client(options = {})
+    CloudstackClient::Client.new(
+      TEST_URL, TEST_KEY, TEST_SECRET, { no_api_methods: true }.merge(options)
+    )
+  end
+end
+
+class Minitest::Spec
+  include TestHelpers
+  include ApiStubs
+end

data/test/utils_test.rb

@@ -0,0 +1,62 @@
+require "test_helper"
+
+describe CloudstackClient::Utils do
+  let(:utils) { Object.new.extend(CloudstackClient::Utils) }
+
+  describe "camel_case_to_underscore" do
+    it "converts a simple camel case command" do
+      _(utils.camel_case_to_underscore("listVirtualMachines"))
+        .must_equal "list_virtual_machines"
+    end
+
+    it "splits a leading acronym from the following word" do
+      _(utils.camel_case_to_underscore("listVPCOfferings"))
+        .must_equal "list_vpc_offerings"
+    end
+
+    it "handles a trailing acronym" do
+      _(utils.camel_case_to_underscore("listOsTypes")).must_equal "list_os_types"
+    end
+
+    it "handles consecutive capitals followed by a word" do
+      _(utils.camel_case_to_underscore("createSSHKeyPair"))
+        .must_equal "create_ssh_key_pair"
+    end
+
+    it "converts hyphens to underscores" do
+      _(utils.camel_case_to_underscore("some-command")).must_equal "some_command"
+    end
+
+    it "leaves an already underscored name unchanged" do
+      _(utils.camel_case_to_underscore("list_apis")).must_equal "list_apis"
+    end
+  end
+
+  describe "underscore_to_camel_case" do
+    it "converts an underscored name" do
+      _(utils.underscore_to_camel_case("list_virtual_machines"))
+        .must_equal "listVirtualMachines"
+    end
+
+    it "returns a name without underscores unchanged" do
+      _(utils.underscore_to_camel_case("listApis")).must_equal "listApis"
+    end
+
+    it "cannot restore acronym casing, because the conversion is lossy" do
+      # Documents a known limitation: "ssh" carries no record of "SSH".
+      # Api resolves underscored names through an index instead of relying
+      # on this method being a true inverse.
+      _(utils.underscore_to_camel_case("create_ssh_key_pair"))
+        .must_equal "createSshKeyPair"
+    end
+  end
+
+  describe "round tripping real command names" do
+    it "round trips names without acronyms" do
+      %w[listVirtualMachines deployVirtualMachine listOsTypes listApis].each do |name|
+        underscored = utils.camel_case_to_underscore(name)
+        _(utils.underscore_to_camel_case(underscored)).must_equal name
+      end
+    end
+  end
+end