RubyGems - datacentred - Versions diffs - 0.1.1pre → 1.1.1 - Mend

datacentred 0.1.1pre → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

checksums.yaml +4 -4
data/.codeclimate.yml +11 -0
data/.coveralls.yml +1 -0
data/.gitignore +9 -0
data/.rubocop.yml +2 -0
data/.yardopts +1 -0
data/CODE_OF_CONDUCT.md +46 -0
data/Gemfile.lock +39 -2
data/LICENSE +21 -0
data/README.md +160 -2
data/circle.yml +0 -2
data/datacentred.gemspec +17 -14
data/docs/Datacentred.html +537 -0
data/docs/Datacentred/Errors.html +260 -0
data/docs/Datacentred/Errors/Error.html +139 -0
data/docs/Datacentred/Errors/NotFound.html +145 -0
data/docs/Datacentred/Errors/Unauthorized.html +149 -0
data/docs/Datacentred/Errors/UnprocessableEntity.html +145 -0
data/docs/Datacentred/Model.html +128 -0
data/docs/Datacentred/Model/Base.html +255 -0
data/docs/Datacentred/Model/Project.html +1729 -0
data/docs/Datacentred/Model/Role.html +1830 -0
data/docs/Datacentred/Model/Usage.html +510 -0
data/docs/Datacentred/Model/User.html +832 -0
data/docs/Datacentred/Model/Version.html +451 -0
data/docs/Datacentred/Project.html +142 -0
data/docs/Datacentred/Request.html +128 -0
data/docs/Datacentred/Request/Base.html +675 -0
data/docs/Datacentred/Request/Projects.html +1286 -0
data/docs/Datacentred/Request/Roles.html +1286 -0
data/docs/Datacentred/Request/Usage.html +315 -0
data/docs/Datacentred/Request/Users.html +841 -0
data/docs/Datacentred/Request/Versions.html +258 -0
data/docs/Datacentred/Response.html +410 -0
data/docs/Datacentred/Role.html +142 -0
data/docs/Datacentred/Usage.html +142 -0
data/docs/Datacentred/User.html +142 -0
data/docs/Datacentred/Version.html +142 -0
data/docs/_index.html +349 -0
data/docs/class_list.html +51 -0
data/docs/css/common.css +1 -0
data/docs/css/full_list.css +58 -0
data/docs/css/style.css +492 -0
data/docs/file.README.html +231 -0
data/docs/file_list.html +56 -0
data/docs/frames.html +17 -0
data/docs/index.html +231 -0
data/docs/js/app.js +248 -0
data/docs/js/full_list.js +216 -0
data/docs/js/jquery.js +4 -0
data/docs/method_list.html +643 -0
data/docs/top-level-namespace.html +110 -0
data/lib/datacentred.rb +65 -12
data/lib/datacentred/error.rb +37 -15
data/lib/datacentred/model/base.rb +21 -0
data/lib/datacentred/model/project.rb +90 -31
data/lib/datacentred/model/role.rb +89 -31
data/lib/datacentred/model/usage.rb +16 -9
data/lib/datacentred/model/user.rb +54 -22
data/lib/datacentred/model/version.rb +17 -8
data/lib/datacentred/request/base.rb +68 -31
data/lib/datacentred/request/projects.rb +92 -24
data/lib/datacentred/request/roles.rb +92 -24
data/lib/datacentred/request/usage.rb +10 -1
data/lib/datacentred/request/users.rb +58 -15
data/lib/datacentred/request/versions.rb +13 -1
data/lib/datacentred/response.rb +6 -2
data/test/integration/authorization_test.rb +30 -0
data/test/integration/projects_test.rb +11 -11
data/test/integration/roles_test.rb +17 -17
data/test/integration/usage_test.rb +8 -8
data/test/integration/users_test.rb +23 -19
data/test/integration/versions_test.rb +1 -2
data/test/test_helper.rb +8 -5
data/test/vcr_cassettes/not_authorized.yml +57 -0
data/test/vcr_cassettes/unexpected_error.yml +56 -0
metadata +115 -9

data/docs/top-level-namespace.html ADDED

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.9
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Datacentred.html" title="Datacentred (module)">Datacentred</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Fri Sep 15 16:27:41 2017 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.9 (ruby-2.3.1).
+</div>
+    </div>
+  </body>
+</html>

data/lib/datacentred.rb CHANGED

@@ -1,41 +1,94 @@
 require 'faraday'
 require 'json'
+require 'recursive-open-struct'
 require 'time'
+# Main Datacentred client module
+#
+# This library acts as a Ruby wrapper for the DataCentred API.
 module Datacentred
-  require_relative 'datacentred/response'
   require_relative 'datacentred/error'
-  require_relative 'datacentred/model/user'
+  require_relative 'datacentred/model/base'
   require_relative 'datacentred/model/project'
   require_relative 'datacentred/model/role'
   require_relative 'datacentred/model/usage'
+  require_relative 'datacentred/model/user'
   require_relative 'datacentred/model/version'
   require_relative 'datacentred/request/base'
   require_relative 'datacentred/request/projects'
-  require_relative 'datacentred/request/users'
   require_relative 'datacentred/request/roles'
   require_relative 'datacentred/request/usage'
+  require_relative 'datacentred/request/users'
   require_relative 'datacentred/request/versions'
+  require_relative 'datacentred/response'
+  # Access key credential for the DataCentred API.
+  #
+  # This value is automatically loaded from the *DATACENTRED_ACCESS* environment variable.
+  #
+  # You can find your API credentials by logging into the dashboard at https://my.datacentred.io
+  #
+  # @return [String] API access key credential
   def self.access_key
     @@access_key ||= ENV['DATACENTRED_ACCESS']
   end
-  def self.access_key=(val)
-    @@access_key = val
+  # Set a new access key value.
+  #
+  # This will override any values loaded from environment variables.
+  #
+  # @param [String] new_access_key New access key value
+  # @return [String] API access key credential
+  def self.access_key=(new_access_key)
+    @@access_key = new_access_key
   end
+  # Secret key credential for the DataCentred API.
+  #
+  # This value is automatically loaded from the *DATACENTRED_SECRET* environment variable.
+  #
+  # You can find your API credentials by logging into the dashboard at https://my.datacentred.io
+  #
+  # @return [String] API secret key credential
   def self.secret_key
     @@secret_key ||= ENV['DATACENTRED_SECRET']
   end
-  def self.secret_key=(val)
-    @@secret_key = val
+  # Set a new secret key value.
+  #
+  # This will override any values loaded from environment variables.
+  #
+  # @param [String] new_secret_key New secret key value
+  #
+  # @return [String] API secret key credential
+  def self.secret_key=(new_secret_key)
+    @@secret_key = new_secret_key
   end
-  User = Model::User
-  Project = Model::Project
-  Role = Model::Role
-  Usage = Model::Usage
-  Version = Model::Version
+  # Shorthand alias for {Model::Project}
+  # @see Model::Project
+  class Project < Model::Project; end
+  # Shorthand alias for {Model::Role}
+  # @see Model::Role
+  class Role < Model::Role; end
+  # Shorthand alias for {Model::Usage}
+  # @see Model::Usage
+  class Usage < Model::Usage; end
+  # Shorthand alias for {Model::User}
+  # @see Model::User
+  class User < Model::User; end
+  # Shorthand alias for {Model::Version}
+  # @see Model::Version
+  class Version < Model::Version; end
+  # Model classes representing RESTful API entities.
+  module Model ; end
+  # Request classes representing RESTful API interactions.
+  module Request
+  end
 end

data/lib/datacentred/error.rb CHANGED

@@ -1,28 +1,50 @@
 module Datacentred
-  class Error < StandardError
+  # Behaviours and exceptions for recoverable errors.
+  module Errors
+    # Test server response and raise appropriate error if an error has been returned.
+    #
+    # @raise [Error] Appropriate error for server response code.
+    # @return [nil] Returns nil on success
     def self.raise_unless_successful(status, body)
       return if status.to_s.start_with? "2" # 2xx
-      err = Datacentred::errors[status]
+      err = errors[status]
       message = body&.fetch("errors")&.first&.fetch("detail")
       if err
-        raise err, message
+        raise err, message || status.to_s
       else
-        raise Datacentred::Error, "Error #{status}: #{message}"
+        raise Error, "Error #{status}: #{message}"
       end
     end
-  end
-  class NotFoundError < StandardError; end
-  class UnprocessableEntity < StandardError; end
-  class Unauthorized < StandardError; end
+    # Datacentred base error
+    class Error < StandardError ; end
+    # Raised when an entity cannot be located using the unique id specified.
+    #
+    # Corresponds to a HTTP 404 error.
+    class NotFound < Error; end
+    # Raised usually when data validations fail on operations that mutate state.
+    #
+    # Corresponds to a HTTP 422 error.
+    class UnprocessableEntity < Error; end
-  private
+    # Raised when credentials are invalid.
+    #
+    # Credentials may be invalid because they're incorrect, or because they correspond to an account
+    # that does not have the correct permissions to access the API.
+    #
+    # Corresponds to a HTTP 403 error.
+    class Unauthorized < Error; end
-  def self.errors
-    {
-      401 => Unauthorized,
-      404 => NotFoundError,
-      422 => UnprocessableEntity
-    }
+    private
+    def self.errors
+      {
+        401 => Datacentred::Errors::Unauthorized,
+        404 => Datacentred::Errors::NotFound,
+        422 => Datacentred::Errors::UnprocessableEntity
+      }
+    end
   end
 end

data/lib/datacentred/model/base.rb ADDED

@@ -0,0 +1,21 @@
+module Datacentred
+  module Model
+    # Base class for all API models.
+    #
+    # Uses Recursive Structs to allow nested property access.
+    class Base < RecursiveOpenStruct
+      # Instantiate a new model object.
+      #
+      # @param [Hash] params Object properties as returned by the API.
+      def initialize(params, _opts=nil)
+        params.delete "links" if params['links']
+        ["created_at", "updated_at", "last_updated_at"].each do |key|
+          params[key] = Time.parse(params[key]) if params[key]
+        end
+        super params, recurse_over_arrays: true
+      end
+    end
+  end
+end

data/lib/datacentred/model/project.rb CHANGED

@@ -1,43 +1,102 @@
 module Datacentred
   module Model
-    class Project < OpenStruct
-      def initialize(params)
-        params.delete("links") if params
-        params["created_at"] = Time.parse params["created_at"]
-        params["updated_at"] = Time.parse params["updated_at"]
-        super(params)
-      end
+    # A project on your DataCentred account.
+    #
+    # Projects (also called "Cloud Projects" or "Tenants") are a way of grouping together users and resources.
+    #
+    # All projects created in your DataCented account are backed by a corresponding project in OpenStack's identity service (Keystone).
+    #
+    # @attr [String] id
+    # @attr [String] name
+    # @attr [Hash] quota_set
+    # @attr_reader [Time] created_at
+    # @attr_reader [Time] updated_at
+    class Project < Base
+      class << self
+        # Create a new project.
+        #
+        # @param [Hash] params Project attributes
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Project] New project.
+        def create(params)
+          new Request::Projects.create params
+        end
-      def self.all
-        Request::Projects.list.map{ |project| new(project) }
-      end
+        # List all available projects.
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Project]] A collection of all projects on this account.
+        def all
+          Request::Projects.list.map{|project| new project }
+        end
-      def self.find(id)
-        new Request::Projects.show(id)
-      end
+        # Find a project by unique ID.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @return [Project] The project, if it exists.
+        def find(id)
+          new Request::Projects.show id
+        end
-      def self.create(params)
-        new Request::Projects.create(params)
-      end
+        # Update a project by unique ID.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @param [Hash] params Project attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the project could not be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Project] The updated project.
+        def update(id, params)
+          new Request::Projects.update id, params
+        end
-      def self.update(id, params)
-        new Request::Projects.update(id, params)
-      end
+        # Permanently remove the specified project.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specified project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the user was destroyed.
+        def destroy(id)
+          Request::Projects.destroy id
+          true
+        end
-      def self.remove(id)
-        Request::Projects.destroy(id)
-      end
-      def self.users(id)
-        Request::Projects.list_users(id).map{ |user| new(user) }
-      end
+        # List all users assigned to this project.
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[User]] A collection of the project's users.
+        def users(id)
+          Request::Projects.list_users(id).map{|user| new user }
+        end
-      def self.add_user(project_id, user_id)
-        Request::Projects.add_user(project_id, user_id)
-      end
+        # Add a new user to this project, giving them access to it via OpenStack.
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the user was added (or is already present).
+        def add_user(project_id:, user_id:)
+          Request::Projects.add_user project_id, user_id
+          true
+        end
-      def self.remove_user(project_id, user_id)
-        Request::Projects.remove_user(project_id, user_id)
+        # Remove user from this project, revoking their access to it on OpenStack.
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms that user was removed (or is already absent).
+        def remove_user(project_id:, user_id:)
+          Request::Projects.remove_user project_id, user_id
+          true
+        end
       end
     end
   end

data/lib/datacentred/model/role.rb CHANGED

@@ -1,43 +1,101 @@
 module Datacentred
   module Model
-    class Role < OpenStruct
-      def initialize(params)
-        params.delete("links")
-        params["created_at"] = Time.parse params["created_at"]
-        params["updated_at"] = Time.parse params["updated_at"]
-        super(params)
-      end
+    # A role on your DataCentred account.
+    #
+    # Roles allow simple setup of user permissions via the creation of roles, then assigning those roles to users.
+    #
+    # @attr [String] id
+    # @attr [String] name
+    # @attr [Boolean] admin
+    # @attr [[String]] permissions
+    # @attr_reader [Time] created_at
+    # @attr_reader [Time] updated_at
+    class Role < Base
+      class << self
+        # Create a new role.
+        #
+        # @param [Hash] params Role attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Role] New role.
+        def create(params)
+          new Request::Roles.create params
+        end
-      def self.all
-        Request::Roles.list.map{|role| new(role) }
-      end
+        # List all available roles.
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Role]] A collection of all roles on this account.
+        def all
+          Request::Roles.list.map{|role| new role }
+        end
-      def self.find(id)
-        new Request::Roles.show(id)
-      end
+        # Find a role by unique ID.
+        #
+        # @param [String] id The unique identifier for this role.
+        # @raise [Errors::NotFound] Raised if the role couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Role] The role, if it exists.
+        def find(id)
+          new Request::Roles.show id
+        end
-      def self.create(params)
-        new Request::Roles.create(params)
-      end
+        # Update a role by unique ID.
+        #
+        # @param [String] id The unique identifier for this role.
+        # @param [Hash] params Role attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the role doesn't exist.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Role] The updated role.
+        def update(id, params)
+          new Request::Roles.update id, params
+        end
-      def self.update(id, params)
-        new Request::Roles.update(id, params)
-      end
+        # Permanently remove the specified role.
+        #
+        # @param [String] id The unique identifier for this role.
+        # @raise [Errors::NotFound] Raised if the role couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specifed role.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the role was destroyed.
+        def destroy(id)
+          Request::Roles.destroy id
+          true
+        end
-      def self.delete(id)
-        Request::Roles.destroy(id)
-      end
-      def self.users(id)
-        Request::Roles.list_users(id).map{|user| new(user) }
-      end
+        # List all users assigned to this role.
+        #
+        # @param [String] id The unique identifier for this role.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[User]] A collection of the role's users.
+        def users(id)
+          Request::Roles.list_users(id).map{|user| new user }
+        end
-      def self.add_user(role_id, user_id)
-        Request::Roles.add_user(role_id, user_id)
-      end
+        # Add new user to this role, giving them the associated permissions.
+        #
+        # @param [String] role_id The unique identifier for this role.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the role or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms that user was added (or is already present).
+        def add_user(role_id:, user_id:)
+          Request::Roles.add_user role_id, user_id
+          true
+        end
-      def self.remove_user(role_id, user_id)
-        Request::Roles.remove_user(role_id, user_id)
+        # Remove user from this role, revoking the associated permissions.
+        #
+        # @param [String] role_id The unique identifier for this role.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the role or user coundn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms that user was removed (or is already absent).
+        def remove_user(role_id:, user_id:)
+          Request::Roles.remove_user role_id, user_id
+          true
+        end
       end
     end
   end