idr_client 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f20475104672ed1c698969b86285488f338c00f1
-  data.tar.gz: 319f90522a9faf84c0943625e5c377957e5b5d04
+  metadata.gz: ab0992f262a2a01f0f4bfd7c712900c1ffb4408f
+  data.tar.gz: 8ec5f04a3a7c132985e1d8d46eaa60c4fd64b8e7
 SHA512:
-  metadata.gz: 433ad64347ae2b4eb1065d595933e1ecf7e0a4142bb1f1ec0d19e737b38f9b99105a5022abb820788eabf13670bb89a5f3a620381ba0a003898c578f1b842c2b
-  data.tar.gz: fbe1fd2885a18f881dae520d186a44e72c26328261e965087bee19c06bd06e38d4a42d70647c64519db044ed6314e71c69d08a03856763210fa7f449d520c12d
+  metadata.gz: 583b0c19fb5256f8f3b8c5886ef23679815bdbb6fc9f14982968ee47bc6aaec3fe6a8f8223fa232e1659fce855c54a0fba0c1fec3419821bcadbe2c0b7d7f300
+  data.tar.gz: c2eff14423272b0432d582d461cdea0085cff59836bca791ee7c55fe91b6e237f4b5ea8f31c91adc80bc57dc72c29978fc0e9ed5c8813e0d77838feaccc1b5b9

data/lib/idr_client.rb

@@ -5,19 +5,53 @@ require 'soar_idm/soar_idm'
 
 module SoarSc
 
+  ##
+  # SOAR Idr Client
+  # Simplifies communication with Hetzner identity registries.
+  # @example Get roles
+  #   idr_client = SoarSc::IdrClient.new
+  #   idr_client.roles_uri = SoarSc::Providers::ServiceRegistry::find_first_service_uri('idr-staff-get-roles')
+  #   subject_identifier = 'charles.mulder@example.org'
+  #   roles = idr_client.get_roles(subject_identifier)
+  # @example Get all attributes
+  #   idr_client = SoarSc::IdrClient.new
+  #   idr_client.attributes_uri = SoarSc::Providers::ServiceRegistry::find_first_service_uri('idr-staff-get-attributes')
+  #   subject_identifier = 'charles.mulder@example.org'
+  #   attributes = idr_client.get_attributes(subject_identifier)
+  # @example Get attributes filtered by role
+  #   idr_client = SoarSc::IdrClient.new
+  #   idr_client.roles_uri = SoarSc::Providers::ServiceRegistry::find_first_service_uri('idr-staff-get-roles')
+  #   idr_client.attributes_uri = SoarSc::Providers::ServiceRegistry::find_first_service_uri('idr-staff-get-attributes')
+  #   subject_identifier = 'charles.mulder@example.org'
+  #   role = 'technical'
+  #   attributes = idr_client.get_attributes(subject_identifier, role)
   class IdrClient < SoarIdm::IdmApi
 
     class MissingRequiredAttributeError < StandardError; end
     class CommunicationError < StandardError; end
     class UnsupportedResponseError < StandardError; end
 
-    attr_accessor :roles_uri
-    attr_accessor :attributes_uri
+    # @!attribute [w] roles_uri
+    attr_writer :roles_uri
 
+    # @!attribute [w] attributes_uri
+    attr_writer :attributes_uri
+
+    ##
+    # Creates an instance of IdrClient
+    # @param http optional [Object] 
+    # @return [Object] instance of IdrClient
     def initialize(http=Net::HTTP)
       @http = http
     end
 
+    ##
+    # Get roles 
+    # @param subject_identifier [String]
+    # @raise MissingRequiredAttributeError when missing subject_identifier param
+    # @raise UnsupportedResponseError when remote response is not json
+    # @raise CommunicationError when network error
+    # @return [Array] list of roles
     def get_roles(subject_identifier)
       begin
         super(subject_identifier)
@@ -30,6 +64,14 @@ module SoarSc
       end
     end
 
+    ##
+    # Get attributes optionally filtered by role
+    # @param subject_identifier [String]
+    # @param role optional [String]
+    # @raise MissingRequiredAttributeError
+    # @raise UnsupportedResponseError
+    # @raise CommunicationError
+    # @return [Hash] dictionary of roles and attributes, optionally filtered by role
     def get_attributes(subject_identifier, role = nil)
       begin
         super(subject_identifier, role)
@@ -42,11 +84,19 @@ module SoarSc
       end
     end
 
+    ##
+    # Set remote uri used by get_attributes method
+    # @param attributes_uri [String]
+    # @return [Nil]
     def attributes_uri=(attributes_uri)
       raise URI::InvalidURIError if not valid_url?(attributes_uri)
       @attributes_uri = URI.parse(attributes_uri)
     end
 
+    ##
+    # Set remote uri used by get_roles method
+    # @param roles_uri [String]
+    # @return [Nil]
     def roles_uri=(roles_uri)
       raise URI::InvalidURIError if not valid_url?(roles_uri)
       @roles_uri = URI.parse(roles_uri)
@@ -54,27 +104,45 @@ module SoarSc
 
     private 
 
+    ##
+    # @param entity_identifier [String]
+    # @return [Array]
     def calculate_identities(entity_identifier)
       [entity_identifier]
     end
 
+    ##
+    # @param identity [String]
+    # @return [Hash] attributes keyed by role
     def calculate_all_attributes(identity)
       response = ask_idr(identity, nil, @attributes_uri)
       response['data']['attributes']
     end
 
+    ##
+    # @param identity [String]
+    # @return [Array] list of roles
     def calculate_roles(identity)
       raise MissingRequiredAttributeError, 'Missing required roles_uri' if @roles_uri.nil?
       response = ask_idr(identity, nil, @roles_uri)
       response['data']['roles']
     end
 
-    def calculate_attributes(identity, role)
+    ##
+    # @param identity [String]
+    # @param role optional [String] 
+    # @return [Hash] dictionairy of attributes
+    def calculate_attributes(identity, role = nil)
       raise MissingRequiredAttributeError, 'Missing required @attributes_uri attribute' if @attributes_uri.nil?
       response = ask_idr(identity, role, @attributes_uri)
       response['data']['attributes'][role]
     end 
 
+    ##
+    # @param identifier [String]
+    # @param role optional [String]
+    # @param url [URI::HTTP, URI::HTTPS] 
+    # @return [Hash] parsed json response
     def ask_idr(identifier, role = nil, url)
       response = @http.start(url.host, url.port) do |http|
         params = build_params(identifier, role)
@@ -83,12 +151,19 @@ module SoarSc
       JSON.parse(response.body)
     end
 
+    ##
+    # @param identifier [String]
+    # @param role optional [String]
+    # @return [String] url query parameters
     def build_params(identifier, role = nil)
       params = "?identifier=#{identifier}"
       params += "&role=#{role}" if not role.nil?
       params
     end
 
+    ##
+    # @param uri [String] 
+    # @return [Boolean]
     def valid_url?(uri)
       result = uri =~ /\A#{URI::regexp(['http', 'https'])}\z/
       not result.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idr_client
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Charles Mulder
@@ -70,3 +70,4 @@ signing_key:
 specification_version: 4
 summary: Identity registry client
 test_files: []
+has_rdoc: