vagrant_cloud 2.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e324926c5c32c84fd0c0506035b0dadc552e4f6c
-  data.tar.gz: 493f832cc1c117c5634dd674ec0a95100003b552
+SHA256:
+  metadata.gz: 00b96df31d811857d6e1322587604bc91195401913872e3340fa89eb8c0816fd
+  data.tar.gz: 52da865c61e7d50b5777a2a9ea2cc3bd6d7c22c1a3e2a34bc2bfdd537515b0da
 SHA512:
-  metadata.gz: 435e8819762b21c375438e577a2a315afc356936212eb7a87e80eb6eb8c019827b0dcbf7044f4fd1f5ceff42c3245b5947ed5c8a74146db4b913d9f195d6fbfc
-  data.tar.gz: 76e35098ecf224f7df999d235be1f0687e062916c163efd87b9264d473bf95b950e54704ca8e3072988e1c2282dc7f6ce9c8279305095c78a911376e080e3b3f
+  metadata.gz: 9e6a2b72a501bc694992e9de0b789cba4c38fb8c6f176cd4c2e5ca4bd0fb387db5d2b23ada2307b7c63d6590b4ad3b1a8c8f98c74fbcd4f95ffd9c49cb028604
+  data.tar.gz: a0e90c8f8adad13d0dccd154cf50407065048a8e773df01c50482bdf79787d744e91d5b2e1a6f431c20c7d37656d894aa82c3fdf3e4f7501da5882bd029dff42

data/README.md

@@ -1,43 +1,149 @@
-vagrant_cloud
-=============
+# vagrant_cloud
+
 Ruby client for the [Vagrant Cloud API](https://www.vagrantup.com/docs/vagrant-cloud/api.html).
 
-[![Build Status](https://img.shields.io/travis/hashicorp/vagrant_cloud/master.svg)](https://travis-ci.org/hashicorp/vagrant_cloud)
 [![Gem Version](https://img.shields.io/gem/v/vagrant_cloud.svg)](https://rubygems.org/gems/vagrant_cloud)
 
+This library provides the functionality to create, modify, and delete boxes, versions,
+and providers on Vagrant Cloud.
+
+## Usage
+
+The Vagrant Cloud library provides two methods for interacting with the Vagrant Cloud API. The
+first is direct interaction using a `VagrantCloud::Client` instance. The second is a basic
+model based approach using a `VagrantCloud::Account` instance.
 
-This client allows to create, modify and delete *boxes*, *versions* and *providers*.
-The main entry point is an object referencing your *account*.
+### Direct Client
+
+The `VagrantCloud::Client` class contains all the underlying functionality which with
+`vagrant_cloud` library uses for communicating with Vagrant Cloud. It can be used directly
+for quickly and easily sending requests to Vagrant Cloud. The `VagrantCloud::Client`
+class will automatically handle any configured authentication, request parameter
+structuring, and response validation. All API related methods in the `VagrantCloud::Client`
+class will return `Hash` results.
+
+Example usage (display box details):
 
-Usage
------
-Example usage:
 ```ruby
-account = VagrantCloud::Account.new('<username>', '<access_token>')
-box = account.ensure_box('my_box')
-version = box.ensure_version('0.0.1')
-provider = version.ensure_provider('virtualbox', 'http://example.com/foo.box')
+require "vagrant_cloud"
 
-version.release
-puts provider.download_url
+client = VagrantCloud::Client.new(access_token: "MY_TOKEN")
+box = client.box_get(username: "hashicorp", name: "bionic64")
+
+puts "Box: #{box[:tag]} Description: #{box[:description]}"
+```
+
+Example usage (creating box and releasing a new version):
+
+```ruby
+require "vagrant_cloud"
+require "net/http"
+
+# Create a new client
+client = VagrantCloud::Client.new(access_token: "MY_TOKEN")
+
+# Create a new box
+client.box_create(
+  username: "hashicorp",
+  name: "test-bionic64",
+  short_description: "Test Box",
+  long_description: "Testing box for an example",
+  is_private: false
+)
+
+# Create a new version
+client.box_version_create(
+  username: "hashicorp",
+  name: "test-bionic64",
+  version: "1.0.0",
+  description: "Version 1.0.0 release"
+)
+
+# Create a new provider
+client.box_version_provider_create(
+  username: "hashicorp",
+  name: "test-bionic64",
+  version: "1.0.0",
+  provider: "virtualbox"
+)
+
+# Request box upload URL
+upload_url = client.box_version_provider_upload(
+  username: "hashicorp",
+  name: "test-bionic64",
+  version: "1.0.0",
+  provider: "virtualbox"
+)
+
+# Upload box asset
+uri = URI.parse(upload_url[:upload_path])
+request = Net::HTTP::Post.new(uri)
+box = File.open(BOX_PATH, "rb")
+request.set_form([["file", box]], "multipart/form-data")
+response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme.eql?("https")) do |http|
+  http.request(request)
+end
+
+# Release the version
+client.box_version_release(
+  username: "hashicorp",
+  name: "test-bionic64",
+  version: "1.0.0"
+)
+```
+
+### Simple Models
+
+The `VagrantCloud::Account` class is the entry point for using simple models to
+interact with Vagrant Cloud.
+
+Example usage (display box details):
+
+```ruby
+require "vagrant_cloud"
+
+account = VagrantCloud::Account.new(access_token: "MY_TOKEN")
+org = account.organization(name: "hashicorp")
+box = org.boxes.select { |b| b.name == "bionic64" }
+
+puts "Box: #{box[:tag]} Description: #{box[:description]}"
 ```
 
-__NOTE:__ As of version 2.0.0, the CLI has been deprecated in favor of the `vagrant cloud`
-command. More information about how to use the `vagrant cloud` command can be found
-on the [Vagrant documentation](https://www.vagrantup.com/docs/cli/cloud.html).
-
-Example CLI usage:
-Create a version and provider within an existing Box, upload a file to be hosted by Vagrant Cloud, and release the version
-```sh
-vagrant_cloud create_version --username $USERNAME --token $VAGRANT_CLOUD_TOKEN --box $BOX_NAME --version $BOX_VERSION
-vagrant_cloud create_provider --username $USERNAME --token $VAGRANT_CLOUD_TOKEN --box $BOX_NAME --version $BOX_VERSION
-vagrant_cloud upload_file --username $USERNAME --token $VAGRANT_CLOUD_TOKEN --box $BOX_NAME --version $BOX_VERSION --provider_file_path $PACKAGE_PATH
-vagrant_cloud release_version --username $USERNAME --token $VAGRANT_CLOUD_TOKEN --box $BOX_NAME --version $BOX_VERSION
+Example usage (creating box and releasing a new version):
+
+```ruby
+require "vagrant_cloud"
+
+# Load our account
+account = VagrantCloud::Account.new(access_token: "MY_TOKEN")
+
+# Load organization
+org = account.organization(name: "hashicorp")
+
+# Create a new box
+box = org.add_box("test-bionic64")
+box.description = "Testing box for an example"
+box.short_description = "Test Box"
+
+# Create a new version
+version = box.add_version("1.0.0")
+version.description = "Version 1.0.0 release"
+
+# Create a new provider
+provider = version.add_provider("virtualbox")
+
+# Save the box, version, and provider
+box.save
+
+# Upload box asset
+provider.upload(path: BOX_PATH)
+
+# Release the version
+version.release
 ```
-If you installed vagrant_cloud with bundler, then you may have to invoke using `bundle exec vagrant_cloud`
 
-Development & Contributing
---------------------------
+## Development & Contributing
+
 Pull requests are very welcome!
 
 Install dependencies:
@@ -50,18 +156,18 @@ Run the tests:
 bundle exec rspec
 ```
 
-Check the code syntax:
-```
-bundle exec rubocop
-```
+## Releasing
 
 Release a new version:
 
-1. Bump the version in `vagrant_cloud.gemspec`, merge to master.
-2. Push a new tag to master.
-3. Release to RubyGems with `bundle exec rake release`.
+1. Update the version in the `version.txt` file
+1. Commit the change to master
+1. Create a new version tag in git: `git tag vX.X.X`
+1. Push the new tag and master to GitHub `git push origin main --tags`
+
+The new release will be automatically built and published.
+
+## History
 
-History
--------
-This gem has been developed and maintained by [Cargo Media](https://www.cargomedia.ch) since April 2014.
-HashiCorp became the official maintainer in October 2017.
+- This gem was developed and maintained by [Cargo Media](https://www.cargomedia.ch) from April 2014 until October 2017.
+- The `vagrant_cloud` CLI tool included in this RubyGem has been deprecated and removed. See `vagrant cloud` for a replacement.

data/lib/vagrant_cloud.rb

@@ -1,11 +1,21 @@
-require 'json'
-require 'rest_client'
+require "excon"
+require "log4r"
+require "json"
+require "securerandom"
+require "set"
+require 'singleton'
+require "thread"
 
-require 'vagrant_cloud/errors'
-
-require 'vagrant_cloud/account'
-require 'vagrant_cloud/box'
-require 'vagrant_cloud/version'
-require 'vagrant_cloud/provider'
-require 'vagrant_cloud/search'
-require 'vagrant_cloud/client'
+module VagrantCloud
+  autoload :Account, "vagrant_cloud/account"
+  autoload :Box, "vagrant_cloud/box"
+  autoload :Client, "vagrant_cloud/client"
+  autoload :Data, "vagrant_cloud/data"
+  autoload :Error, "vagrant_cloud/error"
+  autoload :Instrumentor, "vagrant_cloud/instrumentor"
+  autoload :Logger, "vagrant_cloud/logger"
+  autoload :Organization, "vagrant_cloud/organization"
+  autoload :Response, "vagrant_cloud/response"
+  autoload :Search, "vagrant_cloud/search"
+  autoload :VERSION, "vagrant_cloud/version"
+end

data/lib/vagrant_cloud/account.rb

@@ -1,190 +1,112 @@
 module VagrantCloud
+  # VagrantCloud account
   class Account
-    attr_accessor :username
-    attr_accessor :access_token
-
-    # @param [String] username
-    # @param [String] access_token
-    def initialize(username, access_token, custom_server = nil)
-      @username = username
-      @access_token = access_token
-      @client = Client.new(access_token, custom_server)
-    end
-
-    #---------------------------
-    # Authentication API Helpers
-    #---------------------------
-
-    # @param [String] password
-    # @param [String] description
-    # @param [String] 2FA code
-    # @return [Hash] response body
-    def create_token(password, description = nil, code = nil)
-      token_data_params = {
-        token: { description: description },
-        user:  { login: @username, password: password },
-        two_factor: code
-      }.delete_if { |_, v| v.nil? }
-
-      token_response = @client.request('post', '/authenticate', token_data_params)
-      token_response
-    end
-
-    # @param [String] token
-    def delete_token(access_token = nil)
-      token_response = @client.request('delete', '/authenticate', nil, access_token)
-      token_response
-    end
-
-    # Validates a token on the account or a one-off validation token request.
-    # Will return nil if token is valid, otherwise will return Hash of response
-    # from Vagrant Cloud
+    # @return [Client]
+    attr_reader :client
+    # @return [String] username of this account
+    attr_reader :username
+    # @return [Instrumentor::Collection] Instrumentor in use
+    attr_reader :instrumentor
+
+    # Create a new Account instance
     #
-    # @param [String] access_token
-    # @return [Hash] response body
-    def validate_token(access_token = nil)
-      token_response = @client.request('get', '/authenticate', nil, access_token)
-      token_response
+    # @param [String] access_token Authentication token
+    # @param [Client] client Client to use for account
+    # @param [String] custom_server Custom server URL for client
+    # @param [Integer] retry_count Number of retries on idempotent requests
+    # @param [Integer] retry_interval Number of seconds to wait between requests
+    # @param [Instrumentor::Core] instrumentor Instrumentor to use
+    # @return [Account]
+    def initialize(access_token: nil, client: nil, custom_server: nil, retry_count: nil, retry_interval: nil, instrumentor: nil)
+      raise ArgumentError, "Account accepts `access_token` or `client` but not both" if
+        client && access_token
+      raise TypeError, "Expected `#{Client.name}` but received `#{client.class.name}`" if
+        client && !client.is_a?(Client)
+
+      if client
+        @client = client
+      else
+        @client = Client.new(
+          access_token: access_token,
+          url_base: custom_server,
+          retry_count: retry_count,
+          retry_interval: retry_interval,
+          instrumentor: instrumentor
+        )
+      end
+      setup!
     end
 
-    # @param [String] delivery_method
-    # @param [String] password
-    # @return [Hash] response body
-    def request_2fa_code(delivery_method, password)
-      twofa_code_params = {
-        two_factor: { delivery_method: delivery_method },
-        user: { login: @username, password: password }
-      }
-
-      code_response = @client.request('post', '/two-factor/request-code', twofa_code_params)
-      code_response
+    # @return [Search]
+    def searcher
+      Search.new(account: self)
     end
 
     #---------------------------
-    # Organization API Helpers
+    # Authentication API Helpers
     #---------------------------
 
-    # @param [String] - organization
-    # @return [Hash]
-    def read_organization(org = nil)
-      if org
-        name = org
-      else
-        name = @username
-      end
-
-      @client.request('get', "/user/#{name}")
-    end
-
-    #--------------------
-    # Old Box API Helpers
-    #--------------------
-
-    # @param [String] name
-    # @param [Hash] data
-    # @return [Box]
-    def get_box(name, data = nil)
-      Box.new(self, name, data)
+    # Create a new access token
+    # @param [String] password Remote password
+    # @param [String] description Description of token
+    # @param [String] code 2FA code
+    # @return [Response::CreateToken]
+    def create_token(password:, description: Data::Nil, code: Data::Nil)
+      r = client.authentication_token_create(username: username,
+        password: password, description: description, code: code)
+
+      Response::CreateToken.new(
+        token: r[:token],
+        token_hash: r[:token_hash],
+        created_at: r[:created_at],
+        description: r[:description]
+      )
     end
 
-    # @param [String] name
-    # @param [Hash] args
-    # @return [Box]
-    def create_box(name, *args)
-      params = box_params(*args)
-      params[:name] = name
-
-      data = @client.request('post', '/boxes', box: params)
-      get_box(name, data)
+    # Delete the current token
+    #
+    # @return [self]
+    def delete_token
+      client.authentication_token_delete
+      self
     end
 
-    # @param [String] name
-    # @param [Hash] args
-    # @return [Box]
-    def ensure_box(name, *args)
-      params = box_params(*args)
-
-      begin
-        box = get_box(name)
-        box.data
-      rescue RestClient::ResourceNotFound
-        box = create_box(name, params)
-        # If we've just created the box, we're done.
-        return box
-      end
-
-      # Select elements from params that don't match what we have in the box
-      # data. These are changed parameters and should be updated.
-      update_params = params.select do |k, v|
-        box.data[box.param_name(k)] != v
-      end
-
-      # Update the box with any params that had changed.
-      box.update(update_params) unless update_params.empty?
-
-      box
+    # Validate the current token
+    #
+    # @return [self]
+    def validate_token
+      client.request(path: "authenticate")
+      self
     end
 
-    #--------------------
-    # Old Box API Helpers
-    #--------------------
-
-    # REMOVED IN FAVOR OF CLIENT CLASS, but still exists to support any old clients
+    # Request a 2FA code is sent
     #
-    # @param [String] method
-    # @param [String] path
-    # @param [Hash] params
-    # @return [Hash]
-    def request(method, path, params = {})
-      headers = {}
-
-      headers['Authorization'] = "Bearer #{access_token}" if access_token
-
-      result = RestClient::Request.execute(
-        method: method,
-        url: url_base + path,
-        payload: params,
-        headers: headers,
-        ssl_version: 'TLSv1'
-      )
-      result = JSON.parse(result)
-      errors = result['errors']
-      raise "Vagrant Cloud returned error: #{errors}" if errors
-
-      result
+    # @param [String] delivery_method Delivery method of 2FA
+    # @param [String] password Account password
+    # @return [Response]
+    def request_2fa_code(delivery_method:, password:)
+      r = client.authentication_request_2fa_code(username: username,
+        password: password, delivery_method: delivery_method)
+      Response::Request2FA.new(destination: r.dig(:two_factor, :obfuscated_destination))
     end
 
-    private
-
-    # @return [String]
-    def url_base
-      'https://vagrantcloud.com/api/v1'
+    # Fetch the requested organization
+    #
+    # @param [String] name Organization name
+    # @return [Organization]
+    def organization(name: nil)
+      org_name = name || username
+      r = client.organization_get(name: org_name)
+      Organization.load(account: self, **r)
     end
 
-    # @param [Array] args
-    # @return [Hash]
-    def box_params(*args)
-      # Prepares a hash based on the *args array passed in.
-      # Acceptable parameters are those documented by Hashicorp for the v1 API
-      # at https://vagrantcloud.com/docs
+    protected
 
-      # This dance is to simulate what we could have accomplished with **args
-      # in Ruby 2.0+
-      # This will silently discard any options that are not passed in as a
-      # hash.
-      # Find and remove the first hash we find in *args. Set params to an
-      # empty hash if we weren't passed one.
-      params = args.select { |v| v.is_a?(Hash) }.first
-      if params.nil?
-        params = {}
-      else
-        args.delete_if { |v| v == params }
+    def setup!
+      if client.access_token
+        r = client.request(path: "authenticate")
+        @username = r.dig(:user, :username)
       end
-
-      # Default boxes to public can be overridden by providing :is_private
-      params[:is_private] = false unless params.key?(:is_private)
-
-      params
     end
   end
 end