Class: Conjur::Annotations

Inherits:
Object
  • Object
show all
Includes:
Escape, Enumerable
Defined in:
lib/conjur/annotations.rb

Overview

Conjur allows Resource instances to be annotated with arbitrary key-value data. This data is generally for "user consumption", and it is not governed by any particular schema or constraints. Your applications can define their own schema for annotations they use. If you do so, we recommend prefixing your annotations, for example, 'myapp:Name', in order to avoid conflict with annotations used, for example, by the Conjur UI.

An Annotations instance acts like a Hash: you can fetch an annotation with #[] and update with #[]=, #each it, and #merge! to do bulk updates.

Instance Method Summary collapse

Methods included from Escape

#fully_escape, #path_escape, #query_escape

Constructor Details

#initialize(resource) ⇒ Annotations

Create an Annotations instance for the given Resource.

Note that you will generally use the Resource#annotations method to get the Annotations for a Resource.

Parameters:



44
45
46
 
# File 'lib/conjur/annotations.rb', line 44

def initialize resource
  @resource = resource
end

Instance Method Details

#[](name) ⇒ Object

Get the value of the annotation with the given name a String or Symbol.

Parameters:

  • name (String, Symbol) —

    the annotation name, indifferent to whether it's



51
52
53
 
# File 'lib/conjur/annotations.rb', line 51

def [] name
  annotations_hash[name.to_sym]
end

#[]=(name, value) ⇒ String

Set an annotation value. This will perform an api call to set the annotation on the server.

Parameters:

  • name (String, Symbol) —

    the annotation name

  • value (String) —

    the annotation value

Returns:

  • (String) —

    the new annotation value



62
63
64
65
 
# File 'lib/conjur/annotations.rb', line 62

def []= name, value
  update_annotation name.to_sym, value
  value
end

#each(&blk) ⇒ Conjur::Annotations

Enumerate all annotations, yielding key,value pairs.

Returns:



69
70
71
72
 
# File 'lib/conjur/annotations.rb', line 69

def each &blk
  annotations_hash.each &blk
  self
end

#inspect ⇒ String

Return an informative representation of the annotations, including the resource to which they're attached. Suitable for debugging.

Returns:

  • (String) 


151
152
153
 
# File 'lib/conjur/annotations.rb', line 151

def inspect
  "<Annotations for #{@resource.resourceid}: #{to_s}>"
end

#keys ⇒ Array<String, Symbol> Also known as: names

Return the annotation names.

This has exactly the same behavior as Hash#keys, in that the returned keys are immutable, and modifications to the array have no effect.

Returns:

  • (Array<String, Symbol>) —

    the annotation names



107
108
109
 
# File 'lib/conjur/annotations.rb', line 107

def keys
  annotations_hash.keys
end

#merge!(hash) ⇒ Conjur::Annotations

Note:

this is currently no more efficient than setting each annotation with #[]=.

Set annotations from key,value pairs in hash.

Parameters:

  • hash (Hash, #each)

Returns:



124
125
126
127
128
129
 
# File 'lib/conjur/annotations.rb', line 124

def merge! hash
  hash.each do |k, v|
    self[k] = v unless self[k] == v
  end
  self
end

#to_a ⇒ Object 



112
113
114
 
# File 'lib/conjur/annotations.rb', line 112

def to_a
  to_h.to_a
end

#to_h ⇒ Hash

Return a proper hash containing a copy of the annotations. Note that updates to this hash have no effect on the actual annotations.

Returns:

  • (Hash) 


135
136
137
 
# File 'lib/conjur/annotations.rb', line 135

def to_h
  annotations_hash.dup
end

#to_s ⇒ String

Return the annotations hash as a string. This method simply delegates to Hash#to_s.

Returns:

  • (String) 


143
144
145
 
# File 'lib/conjur/annotations.rb', line 143

def to_s
  annotations_hash.to_s
end

#values ⇒ Array<String>

Return a copy of the annotation values

Examples:

Changing values has no effectannotations_hash

resource.annotations.values ["Some Value"]
resource.annotations.values.each do |v|
  v << "HI"
end
resource.annotations.values # => ["Some Value"]

 # Notice that this is different from ordinary Hash behavior
 h = {"Some Key" => "Some Value"}
 h.values.each do |v|
    v << "HI"
 end
 h.values # "Some ValueHI"

Show the values of a resources annotations

resource.annotations # => {'Name' => 'The Best Resource EVAR',
                     #  'Story' => 'The Coolest!' }
resource.annotations.values # => ['The Best Resource EVAR', 'The Coolest!']

Returns:

  • (Array<String>) —

    the annotation values



96
97
98
 
# File 'lib/conjur/annotations.rb', line 96

def values
  annotations_hash.values.map(&:dup)
end