redfish_client 0.6.0 → 0.6.1

data/lib/redfish_client/connector.rb

@@ -1,262 +0,0 @@
-# frozen_string_literal: true
-
-require "base64"
-require "excon"
-require "json"
-
-require "redfish_client/nil_hash"
-require "redfish_client/response"
-
-module RedfishClient
-  # Connector serves as a low-level wrapper around HTTP calls that are used
-  # to retrieve data from the service API. It abstracts away implementation
-  # details such as sending the proper headers in request, which do not
-  # change between resource fetches.
-  #
-  # Library users should treat this class as an implementation detail and
-  # use higer-level {RedfishClient::Resource} instead.
-  class Connector
-    # AuthError is raised if the credentials are invalid.
-    class AuthError < StandardError; end
-
-    # Default headers, as required by Redfish spec
-    # https://redfish.dmtf.org/schemas/DSP0266_1.4.0.html#request-headers
-    DEFAULT_HEADERS = {
-      "Accept" => "application/json",
-      "OData-Version" => "4.0",
-    }.freeze
-
-    # Basic and token authentication header names
-    BASIC_AUTH_HEADER = "Authorization"
-    TOKEN_AUTH_HEADER = "X-Auth-Token"
-    LOCATION_HEADER   = "Location"
-
-    # Create new connector.
-    #
-    # By default, connector performs no caching. If caching is desired,
-    # Hash should be used as a cache implementation.
-    #
-    # It is also possible to pass in custom caching class. Instances of that
-    # class should respond to the following four methods:
-    #
-    #  1. `[](key)`         - Used to access cached content and should return
-    #                         `nil` if the key has no associated value.
-    #  2. `[]=(key, value)` - Cache `value` under the `key`
-    #  3. `clear`           - Clear the complete cache.
-    #  4. `delete(key)`     - Invalidate cache entry associated with `key`.
-    #
-    # @param url [String] base url of the Redfish service
-    # @param verify [Boolean] verify SSL certificate of the service
-    # @param use_session [Boolean] Use a session for authentication
-    # @param cache [Object] cache backend
-    def initialize(url, verify: true, cache: nil, use_session: true)
-      @url = url
-      @headers = DEFAULT_HEADERS.dup
-      middlewares = Excon.defaults[:middlewares] +
-        [Excon::Middleware::RedirectFollower]
-      @connection = Excon.new(@url,
-                              ssl_verify_peer: verify,
-                              middlewares: middlewares)
-      @cache = cache || NilHash.new
-      @use_session = use_session
-    end
-
-    # Add HTTP headers to the requests made by the connector.
-    #
-    # @param headers [Hash<String, String>] headers to be added
-    def add_headers(headers)
-      @headers.merge!(headers)
-    end
-
-    # Remove HTTP headers from requests made by the connector.
-    #
-    # Headers that are not currently set are silently ignored and no error is
-    # raised.
-    #
-    # @param headers [List<String>] headers to remove
-    def remove_headers(headers)
-      headers.each { |h| @headers.delete(h) }
-    end
-
-    # Issue requests to the service.
-    #
-    # @param mathod [Symbol] HTTP method (:get, :post, :patch or :delete)
-    # @param path [String] path to the resource, relative to the base
-    # @param data [Hash] data to be sent over the socket
-    # @return [Response] response object
-    def request(method, path, data = nil)
-      return @cache[path] if method == :get && @cache[path]
-
-      do_request(method, path, data).tap do |r|
-        @cache[path] = r if method == :get && r.status == 200
-      end
-    end
-
-    # Issue GET request to service.
-    #
-    # This method will first try to return cached response if available. If
-    # cache does not contain entry for this request, data will be fetched from
-    # remote and then cached, but only if the response has an OK (200) status.
-    #
-    # @param path [String] path to the resource, relative to the base url
-    # @return [Response] response object
-    def get(path)
-      request(:get, path)
-    end
-
-    # Issue POST requests to the service.
-    #
-    # @param path [String] path to the resource, relative to the base
-    # @param data [Hash] data to be sent over the socket, JSON encoded
-    # @return [Response] response object
-    def post(path, data = nil)
-      request(:post, path, data)
-    end
-
-    # Issue PATCH requests to the service.
-    #
-    # @param path [String] path to the resource, relative to the base
-    # @param data [Hash] data to be sent over the socket
-    # @return [Response] response object
-    def patch(path, data = nil)
-      request(:patch, path, data)
-    end
-
-    # Issue DELETE requests to the service.
-    #
-    # @param path [String] path to the resource, relative to the base
-    # @return [Response] response object
-    def delete(path)
-      request(:delete, path)
-    end
-
-    # Clear the cached responses.
-    #
-    # If path is passed as a parameter, only one cache entry gets invalidated,
-    # else complete cache gets invalidated.
-    #
-    # Next GET request will repopulate the cache.
-    #
-    # @param path [String] path to invalidate
-    def reset(path = nil)
-      path.nil? ? @cache.clear : @cache.delete(path)
-    end
-
-    # Set authentication-related variables.
-    #
-    # Last parameter controls the kind of login connector will perform. If
-    # session_path is `nil`, basic authentication will be used, otherwise
-    # connector will use session-based authentication.
-    #
-    # Note that actual login is done lazily. If you need to check for
-    # credential validity, call #{login} method.
-    #
-    # @param username [String] API username
-    # @param password [String] API password
-    # @param auth_test_path [String] API path to test credential's validity
-    # @param session_path [String, nil] API session path
-    def set_auth_info(username, password, auth_test_path, session_path = nil)
-      @username = username
-      @password = password
-      @auth_test_path = auth_test_path
-      @session_path = @use_session ? session_path : nil
-    end
-
-    # Authenticate against the service.
-    #
-    # Calling this method will try to authenticate against API using
-    # credentials provided by #{set_auth_info} call.
-    # If authentication fails, # {AuthError} will be raised.
-    #
-    # @raise [AuthError] if credentials are invalid
-    def login
-      @session_path ? session_login : basic_login
-    end
-
-    # Sign out of the service.
-    def logout
-      # We bypass request here because we do not want any retries on 401
-      # when doing logout.
-      if @session_oid
-        params = prepare_request_params(:delete, @session_oid)
-        @connection.request(params)
-        @session_oid = nil
-      end
-      remove_headers([BASIC_AUTH_HEADER, TOKEN_AUTH_HEADER])
-    end
-
-    private
-
-    def do_request(method, path, data)
-      params = prepare_request_params(method, path, data)
-      r = @connection.request(params)
-      if r.status == 401
-        login
-        r = @connection.request(params)
-      end
-      Response.new(r.status, downcase_headers(r.data[:headers]), r.data[:body])
-    end
-
-    def downcase_headers(headers)
-      headers.each_with_object({}) { |(k, v), obj| obj[k.downcase] = v }
-    end
-
-    def prepare_request_params(method, path, data = nil)
-      params = { method: method, path: path }
-      if data
-        params[:body] = data.to_json
-        params[:headers] = @headers.merge("Content-Type" => "application/json")
-      else
-        params[:headers] = @headers
-      end
-      params
-    end
-
-    def session_login
-      # We bypass request here because we do not want any retries on 401
-      # when doing login.
-      params = prepare_request_params(:post, @session_path,
-                                      "UserName" => @username,
-                                      "Password" => @password)
-      r = @connection.request(params)
-      raise_invalid_auth_error unless r.status == 201
-
-      body    = JSON.parse(r.data[:body])
-      headers = r.data[:headers]
-
-      add_headers(TOKEN_AUTH_HEADER => headers[TOKEN_AUTH_HEADER])
-      save_session_oid!(body, headers)
-    end
-
-    def save_session_oid!(body, headers)
-      @session_oid = body["@odata.id"] if body.key?("@odata.id")
-      return if @session_oid
-
-      return unless headers.key?(LOCATION_HEADER)
-
-      location = URI.parse(headers[LOCATION_HEADER])
-      @session_oid = [location.path, location.query].compact.join("?")
-    end
-
-    def basic_login
-      payload = Base64.encode64("#{@username}:#{@password}").strip
-      add_headers(BASIC_AUTH_HEADER => "Basic #{payload}")
-      return if auth_valid?
-
-      remove_headers([BASIC_AUTH_HEADER])
-      raise_invalid_auth_error
-    end
-
-    def raise_invalid_auth_error
-      raise AuthError, "Invalid credentials"
-    end
-
-    def auth_valid?
-      # We bypass request here because we do not want any retries on 401
-      # when checking authentication headers.
-      reset(@auth_test_path) # Do not want to see cached response
-      params = prepare_request_params(:get, @auth_test_path)
-      @connection.request(params).status == 200
-    end
-  end
-end

data/lib/redfish_client/event_listener.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "uri"
-
-module RedfishClient
-  # EventListener class can be used to stream events from Redfish service. It
-  # is a thin wrapper around SSE listener that does the dirty work of
-  # splitting each event into its EventRecords and reporting them as separate
-  # events.
-  class EventListener
-    # Create new EventListener instance.
-    #
-    # @param sse_client [ServerSentEvents::Client] SSE client
-    def initialize(sse_client)
-      @sse_client = sse_client
-    end
-
-    # Stream events from redfish service.
-    #
-    # Events that this method yields are actually EventRecords, extracted from
-    # the actual Redfish Event.
-    def listen
-      @sse_client.listen do |event|
-        split_event_into_records(event).each { |r| yield(r) }
-      end
-    end
-
-    private
-
-    def split_event_into_records(event)
-      JSON.parse(event.data).fetch("Events", [])
-    end
-  end
-end

data/lib/redfish_client/nil_hash.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module RedfishClient
-  # NilHash imitates the built-in Hash class without storing anything
-  # permanently.
-  #
-  # Main use of this class is as a non-caching connector backend.
-  class NilHash
-    # Access hash member.
-    #
-    # Since this implementation does not store any data, return value is
-    # always nil.
-    #
-    # @param _key not used
-    # @return [nil]
-    def [](_key)
-      nil
-    end
-
-    # Set hash member.
-    #
-    # This is just a pass-through method, since it always simply returns the
-    # value without actually storing it.
-    #
-    # @param _key not used
-    # @param value [Object] any value
-    # @return [Object] value
-    def []=(_key, value)
-      value
-    end
-
-    # Clear the contents of the cache.
-    #
-    # Since hash is not storing anything, this is a no-op.
-    def clear; end
-
-    # Delete entry from hash.
-    #
-    # Since hash is not storing anything, this is a no-op.
-    #
-    # @param _key not used
-    def delete(_key) end
-  end
-end

data/lib/redfish_client/resource.rb

@@ -1,290 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module RedfishClient
-  # Resource is basic building block of Redfish client and serves as a
-  # container for the data that is retrieved from the Redfish service.
-  #
-  # When we interact with the Redfish service, resource will wrap the data
-  # retrieved from the service API and offer us dot-notation accessors for
-  # values stored.
-  #
-  # Resource will also load any sub-resource on demand when we access it.
-  # For example, if we have a root Redfish resource stored in `root`,
-  # accessing `root.SessionService` will automatically fetch the appropriate
-  # resource from the API.
-  #
-  # In order to reduce the amount of requests being sent to the service,
-  # resource can also utilise caching connector. If we would like to get
-  # fresh values from the service, {#refresh} call will flush the cache and
-  # retrieve fresh data from the remote.
-  class Resource
-    # NoODataId error is raised when operation would need OpenData id of the
-    # resource to accomplish the task a hand.
-    class NoODataId < StandardError; end
-
-    # NoResource error is raised if the service cannot find requested
-    # resource.
-    class NoResource < StandardError; end
-
-    # Timeout error is raised if the async request is not handled in due time.
-    class Timeout < StandardError; end
-
-    # Headers, returned from the service when resource has been constructed.
-    #
-    # @return [Hash] resource headers
-    attr_reader :headers
-
-    # Raw data that has been used to construct resource by either fetching it
-    # from the remote API or by being passed-in as a parameter to constructor.
-    #
-    # @return [Hash] resource raw data
-    attr_reader :raw
-
-    # Create new resource.
-    #
-    # Resource can be created either by passing in OpenData identifier or
-    # supplying the content (hash). In the first case, connector will be used
-    # to fetch the resource data. In the second case, resource only wraps the
-    # passed-in hash and does no fetching.
-    #
-    # @param connector [RedfishClient::Connector] connector that will be used
-    #   to fetch the resources
-    # @param oid [String] OpenData id of the resource
-    # @param raw [Hash] raw content to populate resource with
-    # @raise [NoResource] resource cannot be retrieved from the service
-    def initialize(connector, oid: nil, raw: nil)
-      @connector = connector
-      if oid
-        initialize_from_service(oid)
-      else
-        @raw = raw
-      end
-    end
-
-    # Wait for the potentially async operation to terminate
-    #
-    # Note that this can be safely called on response from non-async
-    # operations where the function will return immediately and without making
-    # any additional requests to the service.
-    #
-    # @param response [RedfishClient::Response] response
-    # @param retries [Integer] number of retries
-    # @param delay [Integer] number of seconds between retries
-    # @return [RedfishClient::Response] final response
-    # @raise [Timeout] if the operation did not terminate in time
-    def wait(response, retries: 10, delay: 1)
-      retries.times do |_i|
-        return response if response.done?
-
-        sleep(delay)
-        response = get(path: response.monitor)
-      end
-      raise Timeout, "Async operation did not terminate in allotted time"
-    end
-
-    # Access resource content.
-    #
-    # This function offers a way of accessing resource data in the same way
-    # that hash exposes its content.
-    #
-    # @param attr [String] key for accessing data
-    # @return associated value or `nil` if attr is missing
-    def [](attr)
-      build_resource(raw[attr])
-    end
-
-    # Safely access nested resource content.
-    #
-    # This function is an equivalent of safe navigation operator that can be
-    # used with arbitrary keys.
-    #
-    # Calling `res.dig("a", "b", "c")` is equivalent to `res.a&.b&.c` and
-    # `res["a"] && res["a"]["b"] && res["a"]["b"]["c"]`.
-    # @params keys [Array<Symbol, String>] sequence of keys to access
-    # @return associated value or `nil` if any key is missing
-    def dig(*keys)
-      keys.reduce(self) { |a, k| a.nil? ? nil : a[k] }
-    end
-
-    # Test if resource contains required key.
-    #
-    # @param name [String, Symbol] key name to test
-    # @return [Boolean] inclusion test result
-    def key?(name)
-      raw.key?(name.to_s)
-    end
-
-    # Convenience access for resource data.
-    #
-    # Calling `resource.Value` is exactly the same as `resource["Value"]`.
-    def method_missing(symbol, *_args, &_block)
-      self[symbol.to_s]
-    end
-
-    def respond_to_missing?(symbol, include_private = false)
-      key?(symbol.to_s) || super
-    end
-
-    # Pretty-print the wrapped content.
-    #
-    # @return [String] JSON-serialized raw data
-    def to_s
-      JSON.pretty_generate(raw)
-    end
-
-    # Issue a requests to the selected endpoint.
-    #
-    # By default, request will be sent to the path, stored in `@odata.id`
-    # field. Source field can be changed by specifying the `field` parameter
-    # when calling this function. Specifying the `path` argument will bypass
-    # the field lookup altogether and issue a request directly to the selected
-    # path.
-    #
-    # If the resource has no lookup field, {NoODataId} error will be raised,
-    # since posting to non-networked resources makes no sense and probably
-    # indicates bug in library consumer.
-    #
-    # @param method [Symbol] HTTP method (:get, :post, :patch or :delete)
-    # @param field [String, Symbol] path lookup field
-    # @param path [String] path to post to
-    # @return [RedfishClient::Response] response
-    # @raise  [NoODataId] resource has no OpenData id
-    def request(method, field, path, payload = nil)
-      @connector.request(method, get_path(field, path), payload)
-    end
-
-    # Issue a GET requests to the selected endpoint.
-    #
-    # By default, GET request will be sent to the path, stored in `@odata.id`
-    # field. Source field can be changed by specifying the `field` parameter
-    # when calling this function. Specifying the `path` argument will bypass
-    # the field lookup altogether and issue a GET request directly to the
-    # selected path.
-    #
-    # If the resource has no lookup field, {NoODataId} error will be raised,
-    # since posting to non-networked resources makes no sense and probably
-    # indicates bug in library consumer.
-    #
-    # @param field [String, Symbol] path lookup field
-    # @param path [String] path to post to
-    # @return [RedfishClient::Response] response
-    # @raise  [NoODataId] resource has no OpenData id
-    def get(field: "@odata.id", path: nil)
-      request(:get, field, path)
-    end
-
-    # Issue a POST requests to the selected endpoint.
-    #
-    # By default, POST request will be sent to the path, stored in `@odata.id`
-    # field. Source field can be changed by specifying the `field` parameter
-    # when calling this function. Specifying the `path` argument will bypass
-    # the field lookup altogether and POST directly to the requested path.
-    #
-    # In order to avoid having to manually serialize data to JSON, this
-    # function call takes Hash as a payload and encodes it before sending it
-    # to the endpoint.
-    #
-    # If the resource has no lookup field, {NoODataId} error will be raised,
-    # since posting to non-networked resources makes no sense and probably
-    # indicates bug in library consumer.
-    #
-    # @param field [String, Symbol] path lookup field
-    # @param path [String] path to post to
-    # @param payload [Hash<String, >] data to send
-    # @return [RedfishClient::Response] response
-    # @raise  [NoODataId] resource has no OpenData id
-    def post(field: "@odata.id", path: nil, payload: nil)
-      request(:post, field, path, payload)
-    end
-
-    # Issue a PATCH requests to the selected endpoint.
-    #
-    # Works exactly the same as the {post} method, but issued a PATCH request
-    # to the server.
-    #
-    # @param field [String, Symbol] path lookup field
-    # @param path [String] path to patch
-    # @param payload [Hash<String, >] data to send
-    # @return [RedfishClient::Response] response
-    # @raise  [NoODataId] resource has no OpenData id
-    def patch(field: "@odata.id", path: nil, payload: nil)
-      request(:patch, field, path, payload)
-    end
-
-    # Issue a DELETE requests to the endpoint of the resource.
-    #
-    # If the resource has no `@odata.id` field, {NoODataId} error will be
-    # raised, since deleting non-networked resources makes no sense and
-    # probably indicates bug in library consumer.
-    #
-    # @return [RedfishClient::Response] response
-    # @raise  [NoODataId] resource has no OpenData id
-    def delete(field: "@odata.id", path: nil, payload: nil)
-      request(:delete, field, path, payload)
-    end
-
-    # Refresh resource content from the API
-    #
-    # Caling this method will ensure that the resource data is in sync with
-    # the Redfis API, invalidating any caches as necessary.
-    def refresh
-      return unless self["@odata.id"]
-
-      # TODO(@tadeboro): raise more sensible exception if resource cannot be
-      # refreshed.
-      @connector.reset(self["@odata.id"])
-      initialize_from_service(self["@odata.id"])
-    end
-
-    private
-
-    def initialize_from_service(oid)
-      url, fragment = oid.split("#", 2)
-      resp = wait(get(path: url))
-      raise NoResource unless [200, 201].include?(resp.status)
-
-      @raw = get_fragment(JSON.parse(resp.body), fragment)
-      @raw["@odata.id"] = oid
-      @headers = resp.headers
-    end
-
-    def get_fragment(data, fragment)
-      # data, /my/0/part -> data["my"][0]["part"]
-      parse_fragment_string(fragment).reduce(data) do |acc, c|
-        acc[acc.is_a?(Array) ? c.to_i : c]
-      end
-    end
-
-    def parse_fragment_string(fragment)
-      # /my/0/part -> ["my", "0", "part"]
-      fragment ? fragment.split("/").reject { |i| i == "" } : []
-    end
-
-    def get_path(field, path)
-      raise NoODataId if path.nil? && !key?(field)
-      path || raw[field]
-    end
-
-    def build_resource(data)
-      return nil if data.nil?
-
-      case data
-      when Hash then build_hash_resource(data)
-      when Array then data.collect { |d| build_resource(d) }
-      else data
-      end
-    end
-
-    def build_hash_resource(data)
-      if data.key?("@odata.id")
-        Resource.new(@connector, oid: data["@odata.id"])
-      else
-        Resource.new(@connector, raw: data)
-      end
-    rescue NoResource
-      nil
-    end
-  end
-end

data/lib/redfish_client/response.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-require "uri"
-
-module RedfishClient
-  # Response struct.
-  #
-  # This struct is returned from the methods that interact with the remote API.
-  class Response
-    attr_reader :status
-    attr_reader :headers
-    attr_reader :body
-
-    def initialize(status, headers, body)
-      @status = status
-      @headers = headers
-      @body = body
-    end
-
-    # Returns wether the request is completed or ongoing. Be aware than completed
-    # doesn't mean completed successfully, and that you still need to check status
-    # for success or failure.
-    # @return [true] if the request was completed
-    def done?
-      status != 202
-    end
-
-    def monitor
-      return nil if done?
-
-      uri = URI.parse(headers["location"])
-      [uri.path, uri.query].compact.join("?")
-    end
-
-    def to_h
-      { "status" => status, "headers" => headers, "body" => body }
-    end
-
-    def to_s
-      "Response[status=#{status}, headers=#{headers}, body='#{body}']"
-    end
-
-    def self.from_hash(data)
-      new(*data.values_at("status", "headers", "body"))
-    end
-  end
-end