conjur-api 4.14.0 → 4.15.0

data/lib/conjur/build_from_response.rb

@@ -19,7 +19,18 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # @api private
+  # This module is included by classes that can be built from JSON responses.
   module BuildFromResponse
+    # @api private
+    #
+    # Build a Conjur asset from a REST response.
+    #
+    # @param [RestCliet::Response] response the response to build the object from
+    # @param [Hash] credentials options as {Conjur::API#credentials} used to perform requests in methods on
+    #   the created asset.
+    #
+    # @return [Object] an object of this type
     def build_from_response(response, credentials)
       new(response.headers[:location], credentials).tap do |obj|
         obj.attributes = JSON.parse(response.body)

data/lib/conjur/cast.rb

@@ -21,7 +21,11 @@
 module Conjur
   module Cast
     protected
-    
+
+    # Convert a value to a role or resource identifier.
+    #
+    # @param [String, Array, #roleid, #resourceid] obj the value to cast
+    # @param [Symbol] kind must be either `:roleid` or `:resourceid`
     def cast(obj, kind)
       case kind
       when :roleid, :resourceid

data/lib/conjur/core-api.rb

@@ -21,6 +21,11 @@
 module Conjur
   class API
     class << self
+      # @api private
+      #
+      # Host for the core service.  We don't really use this anymore.
+      #
+      # @return [String] the core asset host
       def core_asset_host
         ::Conjur::Core::API.host
       end
@@ -30,14 +35,29 @@ module Conjur
   module Core
     class API < Conjur::API
       class << self
+        # @api private
+        # @deprecated
+        # The host for the Conjur directory service
+        # @return [String] the host.
         def host
           Conjur.configuration.core_url
         end
-        
+
+        # Returns the account as determined by the conjur server.
+        #
+        # You should generally provide the account with {Conjur::Configuration#account}, but this method
+        # can determine it by asking the server.
+        #
+        # You do not need any credentials to call this method.
         def conjur_account
           info['account'] or raise "No account field in #{info.inspect}"
         end
-        
+
+        # @api private
+        #
+        # Used to fetch an `info` hash from the server.
+        #
+        # @return [Hash] a hash containing an `'account'` field that specifies the current Conjur account.
         def info
           @info ||= JSON.parse RestClient::Resource.new(Conjur::Core::API.host)['info'].get
         end

data/lib/conjur/deputy.rb

@@ -19,6 +19,14 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # A Deputy is an actor, typically representing a service.  It is given a login and
+  # an api key, just like {Conjur::Host}s and {Conjur::User}s, and can perform various
+  # actions.
+  #
+  # You should not create instances of this class directly.  Instead, you can get a {Conjur::Deputy}
+  # instance with {Conjur::API#deputy} or {Conjur::API#create_deputy}.
+  #
+  # The deputies api is stable, but is primarily used internally.
   class Deputy < RestClient::Resource
     include Exists
     include HasId
@@ -26,11 +34,20 @@ module Conjur
     include HasAttributes
     include ActsAsUser
     include ActsAsResource
-    
+
+    # Login for the deputy.  Of the form "deputy/<deputy-id>".
+    #
+    # @return [String] the login.
     def login
       [ self.class.name.split('::')[-1].downcase, id ].join('/')
     end
-    
+
+    # API Key that can be used to login as the deputy.
+    #
+    # This is only available if the {Conjur::Deputy} was returned
+    # by {Conjur::API#create_deputy}.
+    #
+    # @return [String] the api key.
     def api_key
       self.attributes['api_key']
     end

data/lib/conjur/env.rb

@@ -21,18 +21,33 @@
 module Conjur
   extend self
 
+  # @deprecated
+  # @api private
+  # This method delegates to {Conjur::Configuration#service_base_port}
+  #
+  # @return [Integer] the service base port
   def service_base_port
     Conjur.configuration.service_base_port
   end
-  
+
+  # This method delegates to {Conjur::Configuration#account}
+  #
+  # @return [String] the value of `Conjur.configuration.account`
   def account
     Conjur.configuration.account
   end
-  
+
+  # This method delegates to {Conjur::Configuration#env}
+  # @return [String] the value of `Conjur.configuration.env`
   def env
     Conjur.configuration.env
   end
-  
+
+  # @api private
+  # @deprecated
+  # This method delegates to {Conjur::Configuration#stack}
+  #
+  # @return [String] the value of `Conjur.configuration.stack`
   def stack
     Conjur.configuration.stack
   end

data/lib/conjur/escape.rb

@@ -19,21 +19,56 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+
+  # Provides helpers for escaping url components.
+  #
+  # The helpers are added as both class and isntance methods.
   module Escape
     module ClassMethods
+      # URL escape the entire string.  This is essentially the same as calling `CGI.escape str`.
+      #
+      # @example
+      #   fully_escape 'foo/bar@baz'
+      #   # => "foo%2Fbar%40baz"
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
       def fully_escape(str)
         require 'cgi'
         CGI.escape(str.to_s)
       end
-      
+
+      # Escape a URI path component.
+      #
+      # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
+      # @see Conjur::Escape::ClassMethods#path_or_query_escape
       def path_escape(str)
         path_or_query_escape str
       end
 
+      # Escape a URI query value.
+      #
+      # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
+      # @see Conjur::Escape::ClassMethods#path_or_query_escape
       def query_escape(str)
         path_or_query_escape str
       end
-      
+
+      # Escape a path or query value.
+      #
+      # This method is *similar* to `URI.escape`, but it has several important differences:
+      #   * If a falsey value is given, the string `"false"` is returned.
+      #   * If the value given responds to `#id`, the value returned by `str.id` is escaped instead.
+      #   * The value is escaped without modifying `':'` or `'/'`.
+      #
+      # @param [String, FalseClass, NilClass, #id] str the value to escape
+      # @return [String] the value escaped as described
       def path_or_query_escape(str)
         return "false" unless str
         str = str.id if str.respond_to?(:id)
@@ -43,19 +78,45 @@ module Conjur
         URI.escape(str.to_s, Regexp.new("[^#{pattern}]"))
       end
     end
-    
+
+    # @api private
+    # :nodoc:
     def self.included(base)
       base.extend ClassMethods
     end
-    
+
+    # URL escape the entire string.  This is essentially the same as calling `CGI.escape str`.
+    #
+    # @example
+    #   fully_escape 'foo/bar@baz'
+    #   # => "foo%2Fbar%40baz"
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#fully_escape
     def fully_escape(str)
       self.class.fully_escape str
     end
 
+    # Escape a URI path component.
+    #
+    # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#path_or_query_escape
     def path_escape(str)
       self.class.path_escape str
     end
 
+
+    # Escape a URI query value.
+    #
+    # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#path_or_query_escape
     def query_escape(str)
       self.class.query_escape str
     end

data/lib/conjur/event_source.rb

@@ -1,7 +1,13 @@
 module Conjur
+  # @api private
   # An EventSource instance is used to parse a stream in the format given by
   # the Server Sent Events standard: http://www.whatwg.org/specs/web-apps/current-work/#server-sent-events
+  #
+  # This class is used internally by the audit methods in follow mode.
+  #
   class EventSource
+    # @api private
+    # Representation of a SSE event
     class Event < Struct.new(:data, :name, :id);
     end
 
@@ -20,6 +26,8 @@ module Conjur
     attr_accessor :json
     alias json? json
 
+    # @api private
+    # Create an EventSource
     def initialize
       @json   = true
       @on     = {}
@@ -27,9 +35,11 @@ module Conjur
       @buffer = ""
     end
 
-    # Feed a chunk of data to the EventSource and dispatch any fully receieved
+    # @api private
+    # Feed a chunk of data to the EventSource and dispatch any fully received
     # events.  
     # @param [String] chunk the data to parse
+    # @return [void]
     def feed chunk
       @buffer << chunk
 
@@ -38,7 +48,10 @@ module Conjur
       end
     end
 
-    # Adds a listener for :name:
+    # Add a block to be called when events with an `'event'` field of `name` are received.
+    #
+    # @param [String, Symbol] name the name to listen for
+    # @yieldparam [Conjur::EventSource::Event] the event
     def on name, &block
       (@on[name.to_sym] ||= []) << block
     end

data/lib/conjur/graph.rb

@@ -19,15 +19,30 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+
+  # A Graph represents a directed graph of roles.
+  #
+  # An instance of this class is returned by {Conjur::API#role_graph}.
+  #
+  # @example Graphs act like arrays of edges
+  #   graph.each do |edge|
+  #     puts "#{edge.parent} -> #{edge.child}"
+  #   end
+  #   # role1 -> role2
+  #   # role2 -> role3
+  #
   class Graph
 
     include Enumerable
 
-    # @!attribute r edges
-    #   @return [Array<Conjur::Graph::Edge>] the edges of this graph
+    # Returns an array containing the directed edges of the graph.
+    #
+    # @return [Array<Conjur::Graph::Edge>] the edges of this graph
     attr_reader :edges
 
     # @api private
+    #
+    # @param val [String, Hash, Array, Graph] Data from which to initialize the instance
     def initialize val
       @edges = case val
         when String then JSON.parse(val)['graph']
@@ -41,8 +56,9 @@ module Conjur
     end
 
     # Enumerates the edges of this graph.
-    # @yieldparam [Conjur::Graph::Edge] each edge of the graph
-    # @return edge [Conjur::Graph] this graph
+    #
+    # @yieldparam [Conjur::Graph::Edge] edge each edge of the graph
+    # @return [Conjur::Graph] this graph
     def each_edge
       return enum_for(__method__) unless block_given?
       edges.each{|e| yield e}
@@ -52,28 +68,59 @@ module Conjur
     alias each each_edge
 
     # Enumerates the vertices (roles) of this graph
-    # @yieldparam vertex [Conjur::Role] each vertex in this graph
+    # @yieldparam  [Conjur::Role] vertex each vertex in this graph
     # @return [Conjur::Graph] this graph
     def each_vertex
       return enum_for(__method__) unless block_given?
       vertices.each{|v| yield v}
     end
 
-
+    # Serialize the graph as JSON
+    # @param [Boolean] short when true, the graph is serialized as an array of arrays instead of an array of hashes.
+    # @return [String] the JSON serialized graph.
+    # @see #as_json
+    #
     def to_json short =  false
       as_json(short).to_json
     end
 
+    # Convert the graph to a JSON serializable data structure.  The value returned by this method can have two
+    # forms:  An array of arrays when `short` is `true`, or hash like
+    # `{ 'graph' => [ {'parent' => 'roleid', 'child' => 'roleid'} ]}` otherwise.
+    #
+    # @example Graph formats
+    #   graph = api.role_graph 'conjur:group:pubkeys-1.0/key-managers'
+    #
+    #   # Short format
+    #   graph.as_json true
+    #   #  => [
+    #   #  ["conjur:group:pubkeys-1.0/key-managers", "conjur:group:pubkeys-1.0/admin"],
+    #   #  ["conjur:group:pubkeys-1.0/admin", "conjur:user:admin"]
+    #   # ]
+    #
+    #   # Default format (you can omit the false parameter in this case)
+    #   graph.as_json false
+    #   # => {
+    #   #  "graph" => [
+    #   #    {"parent"=>"conjur:group:pubkeys-1.0/key-managers", "child"=>"conjur:group:pubkeys-1.0/admin"},
+    #   #    {"parent"=>"conjur:group:pubkeys-1.0/admin", "child"=>"conjur:user:admin"}
+    #   #  ]
+    #   #}
+    #
+    # @param [Boolean] short whether to use short of default format
+    # @return [Hash, Array] JSON serializable representation of the graph
     def as_json short = false
       edges = self.edges.map{|e| e.as_json(short)}
       short ? edges : {'graph' => edges}
     end
 
-    # @param [String, NilClass] name to assign to the graph. Usually this can be omitted unless you
-    # are writing multiple graphs to a single file.  Must be in the ID format specified by
-    # http://www.graphviz.org/content/dot-language
+    # Returns a string formatted for use by the {http://www.graphviz.org/ graphviz dot} tool.
+    #
+    # @param [String, NilClass] name An identifier to assign to the graph. This can be omitted unless you
+    #   are writing multiple graphs to a single file.  This must be in the ID format specified by
+    #   http://www.graphviz.org/content/dot-language.
     #
-    # @return [String] the dot format (used by graphvis, among others) representation of this graph.
+    # @return [String] the dot format (used by graphviz, among others) representation of this graph.
     def to_dot name = nil
       dot = "digraph #{name || ''} {"
       vertices.each do |v|
@@ -84,7 +131,9 @@ module Conjur
       end
       dot << "\n}"
     end
-    
+
+    # Return the vertices (roles) of the graph as an array.
+    # @return [Array<Conjur::Role>] the vertices/roles
     def vertices
       @vertices ||= edges.inject([]) {|a, pair| a.concat pair.to_a }.uniq
     end
@@ -148,41 +197,83 @@ module Conjur
       "#{parent_id} -> #{child_id}"
     end
 
-    # an edge consisting of a parent & child, both of which are Conjur::Role instances
+    # Represents a directed Edge between a parent role and a child role.
+    #
+    # In this context, the parent role is a *member of* the child role.  For example,
+    # the `admin` role is a parent of every role, either directly or indirectly, because
+    # it is added as a member to all roles it creates.
     class Edge
+
+      # Return the parent of this edge. The {#parent} role *is a member of* the {#child} role.
+      # @return [Conjur::Role] the parent role
       attr_reader :parent
+
+      # Return the child of this edge.  The {#parent} role *is a member of* the {#child} role.
+      # @return [Conjur::Role] the child role
       attr_reader :child
 
+      # Create a directed edge with a parent and child
+      #
+      # @param [Conjur::Role] parent the parent or source of this edge
+      # @param  [Conjur::Role] child the child or destination of this edge
       def initialize parent, child
         @parent = parent
         @child = child
       end
 
+      # Serialize this edge as JSON.
+      #
+      # @see #as_json
+      # @param [Boolean] short when true, serialize the edge as an Array instead of a Hash
+      # @return [String] the JSON serialized edge
       def to_json short = false
         as_json(short).to_json
       end
 
+      # Return a value suitable for JSON serialization.
+      #
+      # The `short` parameter determines whether to return a `["parent", "child"]` Array
+      # or a Hash like `{"parent" => "parent-role", "child" => "child-role"}`.
+      #
+      # @param [Boolean] short return an Array when true, otherwise return a Hash.
+      # @return [Array, Hash] value suitable for JSON serialization
       def as_json short = false
         short ? to_a : to_h
       end
 
+      # Return this edge as a Hash like {"parent" => "...", "child" => "..."}.
+      #
+      # Note that the keys in the hash are strings.
+      #
+      # @return [Hash] a Hash representing this edge
       def to_h
         # return string keys to make testing less brittle
         {'parent' => @parent, 'child' => @child}
       end
 
+      # Return this edge as an Array like ["parent", "child"]
+      #
+      # @return [Array<String>] the edge as an Array
       def to_a
         [@parent, @child]
       end
 
+      # @api private
+      # :nodoc:
       def to_s
         "<Edge #{parent.id} --> #{child.id}>"
       end
 
+      # Support using edges as hash keys
+      # @api private
+      # :nodoc:
       def hash
         @hash ||= to_a.map(&:to_s).hash
       end
 
+      # Support using edges as hash keys and equality testing
+      # @api private
+      # :nodoc:
       def == other
         other.kind_of?(self.class) and other.parent == parent and other.child == child
       end