conjur-api 4.14.0 → 4.15.0

data/lib/conjur/role_grant.rb

@@ -19,8 +19,56 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
-  RoleGrant = Struct.new(:member, :grantor, :admin_option) do
+  # A `RoleGrant` instance represents the membership of a role in some unspecified role.  `RoleGrant`s are returned
+  # by {Conjur::Role#members} and represent members of the role on which the method was invoked.
+  #
+  # @example
+  #   alice.members.map{|grant| grant.member}.include? admin_role # => true
+  #   admin_role.members.map{|grant| grant.member}.include? alice # => true
+  #
+  class RoleGrant
+
+
+    # The member role in the relationship
+    # @return [Conjur::Role] the member
+    attr_reader :member
+
+    # The role that created this grant.
+    #
+    # @return [Conjur::Role] the role that created the grant
+    attr_reader :grantor
+
+    # When true, the role {#member} is allowed to give this grant to other roles
+    #
+    # @return [Boolean] whether the role can grant the role to others
+    attr_reader :admin_option
+
+
+    # @api private
+    #
+    # Create a new RoleGrant instance.
+    #
+    # @param [Conjur::Role] member the member to which the role was granted
+    # @param [Conjur::Role] grantor  the role that created this grant
+    # @param [Boolean] admin_option whether `member` can give the grant to other roles
+    def initialize member, grantor, admin_option
+      @member = member
+      @grantor = grantor
+      @admin_option = admin_option
+    end
+
+    #@!attribute member
+    #   The member thing
+    #   @return [Conjur::Role] a ret?
+
     class << self
+      # @api private
+      #
+      # Create a `RoleGrant` from a JSON respnose
+      #
+      # @param [Hash] json the parsed JSON response
+      # @param [Hash] credentials the credentials used to create APIs for the member and grantor role objects
+      # @return [Conjur::RoleGrant]
       def parse_from_json(json, credentials)
         member = Role.new(Conjur::Authz::API.host, credentials)[Conjur::API.parse_role_id(json['member']).join('/')]
         grantor = Role.new(Conjur::Authz::API.host, credentials)[Conjur::API.parse_role_id(json['grantor']).join('/')]
@@ -28,4 +76,4 @@ module Conjur
       end
     end
   end
-end
+end

data/lib/conjur/secret.rb

@@ -19,9 +19,17 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # @api private
+  #
+  # Secrets are primitive encrypted values upon which {Conjur::Variable}s are built.
+  # You probably want to use {Conjur::Variable} instead.
   class Secret < RestClient::Resource
     include ActsAsAsset
-    
+
+    # @api private
+    # Return the value of the secret
+    #
+    # @return [String] the value stored by this secret
     def value
       self['value'].get.body
     end

data/lib/conjur/standard_methods.rb

@@ -29,7 +29,17 @@ module Conjur
   module StandardMethods
     
     protected
-    
+
+    # @api private
+    #
+    # Create this resource by sending a POST request to its URL.
+    #
+    # @param [String] host the url of the service (for example, https://conjur.host.com/api)
+    # @param [String] type the asset `kind` (for example, 'user', 'group')
+    # @param [String, nil] id the id of the new asset
+    # @param [Hash] options options to pass through to `RestClient::Resource`'s `post` method.
+    # @return [Object] an instance of a class determined by `type`.  For example, if `type` is
+    #   `'user'`, the class will be `Conjur::User`.
     def standard_create(host, type, id = nil, options = nil)
       log do |logger|
         logger << "Creating #{type}"
@@ -43,7 +53,16 @@ module Conjur
       resp = RestClient::Resource.new(host, credentials)[type.to_s.pluralize].post(options)
       "Conjur::#{type.to_s.classify}".constantize.build_from_response(resp, credentials)
     end
-    
+
+    # @api private
+    #
+    # Fetch a list of assets by sending a GET request to the URL for resources of the given `type`.
+    #
+    # @param [String] host the url of the service (for example, https://conjur.host.com/api)
+    # @param [String] type the asset `kind` (for example, 'user', 'group')
+    # @param [Hash] options options to pass through to `RestClient::Resource`'s `post` method.
+    # @return [Array<Object>] an array of instances of the asset class determined by `type`.  For example, if
+    #   `type` is `'group'`, and array of `Conjur::Group` instances will be returned.
     def standard_list(host, type, options)
       JSON.parse(RestClient::Resource.new(host, credentials)[type.to_s.pluralize].get(options)).collect do |item|
         # Note that we don't want to fully_escape the ids below -- methods like #layer, #host, etc don't expect
@@ -55,7 +74,16 @@ module Conjur
         end
       end
     end
-    
+
+    # @api private
+    #
+    # Fetch details of an asset by sending a GET request to its URL.
+    #
+    # @param [String] host the url of the service (for example, https://conjur.host.com/api)
+    # @param [String] type the asset `kind` (for example, 'user', 'group')
+    # @param [String, nil] id the id of the asset to show
+    # @return [Object] an instance of a class determined by `type`.  For example, if `type` is
+    #   `'user'`, the class will be `Conjur::User`.
     def standard_show(host, type, id)
       "Conjur::#{type.to_s.classify}".constantize.new(host, credentials)[ [type.to_s.pluralize, fully_escape(id)].join('/') ]
     end

data/lib/conjur/user.rb

@@ -21,15 +21,67 @@
 module Conjur
   class InvalidToken < Exception
   end
-  
+
+  # This class represents a {http://developer.conjur.net/reference/services/directory/user Conjur User}.
   class User < RestClient::Resource
     include ActsAsAsset
     include ActsAsUser
-    
-    alias login id
 
+    # Using a method instead of an alias here to make the docs look nicer :-/ - jjm
+
+    # This method is simply an alias for {#id}.  It returns the user's *unqualified* id, which is referred to as
+    # `login` here because it can be used to login to Conjur.
+    # @return [String] the login for this user
+    def login; id end
+
+    # Assign new attributes to the user.  Currently, this method only lets you change the
+    # `:uidnumber` attribute.
+    #
+    # If a user with the given `:uidnumber` already exists, this method will raise `RestClient::Forbidden`, with
+    # the response body providing additional details if possible.
+    #
+    # ### Permissions
+    # You must be a member of the user's role to call this method.
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @param [Hash] options attributes to change
+    # @option options [FixNum] :uidnumber the new uidnumber for this user.  This option *must* be present.
+    # @return [void]
+    # @raise [RestClient::Conflict] if the uidnumber is already in use
+    # @raise [ArgumentError] if uidnumber isn't a `Fixnum` or isn't present in `options`
     def update options
+      # Currently the server raises a 400 Bad Request if uidnumber is missing, require it here
+      raise ArgumentError "options[:uidnumber] is required" unless uidnumber = options[:uidnumber]
+      raise ArgumentError, "options[:uidnumber] must be a Fixnum" unless uidnumber.kind_of?(Fixnum)
       self.put(options)
     end
+
+    # Get the user's uidnumber, which is used by LDAP and SSH login, among other things.
+    #
+    # ### Permissions
+    # You must have the `'show'` permission on the user's resource to call this method
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @return [Fixnum] the uidnumber
+    # @raise [RestClient::Forbidden] if you don't have permission to `show` the user.
+    def uidnumber
+      attributes['uidnumber']
+    end
+
+    # Set the user's uidnumber, which is used by LDAP and SSH login.
+    #
+    # ### Permissions
+    # You must be a member of the user's role to call this method.
+    #
+    # @note This feature requires Conjur server version 4.3 or later.
+    #
+    # @param [Fixnum] uidnumber the new uidnumber
+    # @return [void]
+    # @raise [RestClient::Conflict] if the uidnumber is already in use.
+    def uidnumber= uidnumber
+      update uidnumber: uidnumber
+    end
   end
 end

data/spec/lib/role_spec.rb

@@ -190,8 +190,7 @@ describe Conjur::Role, api: :dummy do
       grants = %w(foo bar)
       expect_request(
         method: :get,
-        url: role.url + "/?members",
-        headers: {}
+        url: role.url + "/?members"
       ).and_return grants.to_json
       grants.each do |g|
         expect(Conjur::RoleGrant).to receive(:parse_from_json).with(g, anything).and_return g

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conjur-api
 version: !ruby/object:Gem::Version
-  version: 4.14.0
+  version: 4.15.0
 platform: ruby
 authors:
 - Rafal Rzepecki
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-26 00:00:00.000000000 Z
+date: 2015-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client