grafana 0.8.2 → 1.0.0

data/lib/grafana/folder.rb

@@ -0,0 +1,198 @@
+module Grafana
+
+  # http://docs.grafana.org/http_api/folder/#folder-api
+  #
+  module Folder
+
+    # Get all folders
+    # GET /api/folders
+    # Returns all folders that the authenticated user has permission to view.
+    #
+    # @example
+    #    folders
+    #
+    # @return [Hash]
+    #
+    def folders
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      endpoint = '/api/folders'
+      @logger.debug("Getting all folders (GET #{endpoint})") if @debug
+      get(endpoint)
+    end
+
+    # Get folder by uid
+    # GET /api/folders/:uid
+    #
+    # Will return the folder given the folder uid.
+    #
+    # Get folder by id
+    # GET /api/folders/:id
+    #
+    # Will return the folder identified by id.
+    def folder( folder_uid )
+
+      raise ArgumentError.new(format('wrong type. user \'folder_uid\' must be an String (for an Folder Uid) or an Integer (for an Folder Id), given \'%s\'', folder_uid.class.to_s)) \
+          if( folder_uid.is_a?(String) && folder_uid.is_a?(Integer) )
+      raise ArgumentError.new('missing \'folder_uid\'') if( folder_uid.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      if(folder_uid.is_a?(Integer))
+
+        f  = folders
+        f  = JSON.parse(f) if(f.is_a?(String))
+
+        status = f.dig('status')
+        return f if( status != 200 )
+
+        f = f.dig('message').detect {|x| x['id'] == folder_uid }
+
+        return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.nil? )
+
+        folder_uid = f.dig('uid') unless(f.nil?)
+
+        return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.is_a?(Integer) )
+      end
+
+      return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters, but it is %s characters long', folder_uid.length) } \
+          if( folder_uid.is_a?(String) && folder_uid.length > 40 )
+      return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_uid) } if( folder_uid.nil? )
+
+      endpoint = format( '/api/folders/%s', folder_uid )
+
+      @logger.debug("Getting folder by Id #{folder_uid} (GET #{endpoint})") if @debug
+      get(endpoint)
+    end
+
+    # Create folder
+    # POST /api/folders
+    #
+    # Creates a new folder.
+    # JSON Body schema:
+    #
+    #   uid   - Optional unique identifier.
+    #   title - The title of the folder.
+    def create_folder( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      title = validate( params, required: false, var: 'title', type: String )
+      uid   = validate( params, required: true , var: 'uid'  , type: String )
+
+      return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters. \'%s\' given', uid.length) } if( uid.length > 40 )
+
+      data = {
+        uid: uid,
+        title: title
+      }
+      data.reject!{ |_, y| y.nil? }
+
+      payload = data.deep_string_keys
+
+      endpoint = '/api/folders'
+
+      @logger.debug("create folder#{title} (GET #{endpoint})") if  @debug
+      logger.debug(payload.to_json) if(@debug)
+
+      post( endpoint, payload.to_json )
+    end
+
+    # Update folder
+    # PUT /api/folders/:uid
+    #
+    # schould be fail, when the version are not incremented
+    # overwrite helps
+    #
+    # Updates an existing folder identified by uid.
+    # JSON Body schema:
+    #
+    #   - uid - Provide another unique identifier than stored to change the unique identifier.
+    #   - title - The title of the folder.
+    #   - version - Provide the current version to be able to update the folder. Not needed if overwrite=true.
+    #   - overwrite - Set to true if you want to overwrite existing folder with newer version.
+    def update_folder( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      uid       = validate( params, required: true , var: 'uid'      , type: String )
+      title     = validate( params, required: true , var: 'title'    , type: String )
+      new_uid   = validate( params, required: false, var: 'new_uid'  , type: String )
+      version   = validate( params, required: false, var: 'version'  , type: Integer )
+      overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || false
+
+      existing_folder = folder( uid )
+      return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', uid) } if( existing_folder.dig('status') != 200 )
+
+      unless( new_uid.nil? )
+        existing_folder = folder( new_uid )
+        return { 'status' => 404, 'message' => format( 'Folder \'%s\' found', uid) } if( existing_folder.dig('status') == 200 )
+      end
+
+      payload = {
+        title: title,
+        uid: new_uid,
+        version: version,
+        overwrite: overwrite
+      }
+      payload.reject!{ |_, y| y.nil? }
+
+      @logger.debug("Updating folder with Uid #{uid}") if @debug
+
+      endpoint = format( '/api/folders/%s', uid )
+
+      put( endpoint, payload.to_json )
+    end
+
+
+    # Delete folder
+    # DELETE /api/folders/:uid
+    #
+    # Deletes an existing folder identified by uid together with all dashboards stored in the folder, if any.
+    # This operation cannot be reverted.
+    def delete_folder( folder_uid )
+
+      raise ArgumentError.new(format('wrong type. user \'folder_uid\' must be an String (for an Folder Uid) or an Integer (for an Folder Id), given \'%s\'', folder_uid.class.to_s)) \
+          if( folder_uid.is_a?(String) && folder_uid.is_a?(Integer) )
+      raise ArgumentError.new('missing \'folder_uid\'') if( folder_uid.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      if(folder_uid.is_a?(Integer))
+
+        fldrs  = folders
+
+        fldrs  = JSON.parse(fldrs) if(fldrs.is_a?(String))
+        status = fldrs.dig('status')
+
+        return fldrs if( status != 200 )
+
+        fldrs.dig('message').each do |d|
+          folder_uid = d.dig('uid').to_s
+        end
+      end
+
+      return { 'status' => 404, 'message' => format( 'No User \'%s\' found', folder_uid) } if( folder_uid.nil? )
+
+      endpoint = format( '/api/folders/%s', folder_uid )
+
+      @logger.debug("deleting folder by uid #{folder_uid} (GET #{endpoint})") if @debug
+      delete(endpoint)
+    end
+
+
+  end
+end
+

data/lib/grafana/folder_and_dashboard_search.rb

@@ -0,0 +1,57 @@
+module Grafana
+
+  # http://docs.grafana.org/http_api/folder_dashboard_search/#folder-dashboard-search-api
+  #
+  module FolderSearch
+
+    # Search folders and dashboards
+    # GET /api/search/
+    #
+    # Query parameters:
+    #
+    #  - query - Search Query
+    #  - tag - List of tags to search for
+    #  - type - Type to search for, dash-folder or dash-db
+    #  - dashboardIds - List of dashboard id's to search for
+    #  - folderIds - List of folder id's to search in for dashboards
+    #  - starred - Flag indicating if only starred Dashboards should be returned
+    #  - limit - Limit the number of returned results
+    def folder_and_dashboard_search(params)
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'team has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      query         = validate( params, required: false, var: 'query'       , type: String )
+      tag           = validate( params, required: false, var: 'tag '        , type: String )
+      type          = validate( params, required: false, var: 'type'        , type: String )
+      dashboard_id  = validate( params, required: false, var: 'dashboardIds', type: Integer )
+      folder_id     = validate( params, required: false, var: 'folderIds'   , type: Integer )
+      starred       = validate( params, required: false, var: 'starred'     , type: Boolean )
+      limit         = validate( params, required: false, var: 'limit'       , type: Integer )
+
+      unless(type.nil?)
+        valid_types   = ['dash-folder', 'dash-db']
+        downcased = Set.new valid_types.map(&:downcase)
+        return { 'status' => 404, 'message' => format( 'wrong type. Must be one of %s, given \'%s\'', valid_types.join(', '), type ) } unless( downcased.include?( type.downcase ) )
+      end
+
+      api     = []
+      api << format( 'query=%s', CGI.escape( query ) ) unless( query.nil? )
+      api << format( 'tags=%s', tag ) unless( tag.nil? )
+      api << format( 'type=%s', type ) unless( type.nil? )
+      api << format( 'dashboardId=%s', dashboard_id ) unless( dashboard_id.nil? )
+      api << format( 'folderId=%s', folder_id ) unless( folder_id.nil? )
+      api << format( 'starred=%s', starred ) unless( starred.nil? )
+      api << format( 'limit=%s', limit ) unless( limit.nil? )
+
+      api = api.join( '&' )
+
+      endpoint = format('/api/search?%s', api)
+      get(endpoint)
+    end
+
+  end
+end
+

data/lib/grafana/folder_permissions.rb

@@ -0,0 +1,155 @@
+module Grafana
+
+  # http://docs.grafana.org/http_api/folder_permissions/#folder-permissions-api
+  #
+  # This API can be used to update/get the permissions for a folder.
+  #
+  # Permissions with folderId=-1 are the default permissions for users with the Viewer and Editor roles.
+  # Permissions can be set for a user, a team or a role (Viewer or Editor).
+  # Permissions cannot be set for Admins - they always have access to everything.
+  #
+  # The permission levels for the permission field:
+  #
+  # 1 = View
+  # 2 = Edit
+  # 4 = Admin
+  #
+  module FolderPermissions
+
+    # Get permissions for a folder
+    # GET /api/folders/:uid/permissions
+    #
+    # Gets all existing permissions for the folder with the given uid.
+    def folder_permissions( folder_id )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      f = folder( folder_id )
+
+      status = f.dig('status')
+      return f if( status != 200 )
+
+      endpoint = format('/api/folders/%s/permissions', f.dig('uid') )
+
+      @logger.debug("Getting all folders (GET #{endpoint})") if @debug
+      get(endpoint)
+    end
+
+
+    # Update permissions for a folder
+    # POST /api/folders/:uid/permissions
+    #
+    # Updates permissions for a folder.
+    # This operation will remove existing permissions if they're not included in the request.
+    #
+    # JSON body schema:
+    #
+    # items - The permission items to add/update. Items that are omitted from the list will be removed.
+    #
+    def update_folder_permissions( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      folder      = validate( params, required: true, var: 'folder'     , type: String )
+      permissions = validate( params, required: true, var: 'permissions', type: Hash )
+
+      return { 'status' => 404, 'message' => 'no permissions given' } if( permissions.size.zero? )
+
+      f_folder = folder(folder)
+      return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder) } if( f_folder.dig('status') != 200 )
+
+      folder_uid = f_folder.dig('uid')
+
+      valid_roles = %w[View Edit Admin]
+#       valid_keys  = %w[role permission teamId userId]
+
+      c_team = permissions.dig('team')
+      c_user = permissions.dig('user')
+      team   = []
+      user   = []
+
+      unless(c_team.nil?)
+        check_keys = []
+
+        c_team.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_team = team(k)
+          team_id = f_team.dig('id')
+
+          next unless(( f_team.dig('status') == 200) && !check_keys.include?(team_id) && r == true )
+
+          check_keys << team_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          team << {
+            teamId: team_id,
+            permission: role_id
+          }
+        end
+      end
+
+      unless(c_user.nil?)
+        check_keys = []
+
+        c_user.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_user = user(k)
+          user_id = f_user.dig('id')
+
+          next unless(( f_user.dig('status') == 200) && !check_keys.include?(user_id) && r == true )
+
+          check_keys << user_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          user << {
+            userId: user_id,
+            permission: role_id
+          }
+        end
+      end
+
+      payload = {
+        items: team + user
+      }
+      payload.reject!{ |_, y| y.nil? }
+
+      endpoint = format( '/api/folders/%s/permissions', folder_uid )
+
+      post(endpoint, payload.to_json)
+    end
+
+
+#    private
+#    def validate_hash( value, valid_params )
+#
+#      downcased = Set.new valid_params.map(&:downcase)
+#
+#      unless( downcased.include?( value.downcase ) )
+#        return {
+#          'status' => 404,
+#          'message' => format( 'wrong permissions. Must be one of %s, given \'%s\'', valid_params.join(', '), value )
+#        }
+#      end
+#      true
+#    end
+
+  end
+end
+

data/lib/grafana/login.rb

@@ -67,58 +67,59 @@ module Grafana
               accept: 'application/json',
               cookies: response_cookies
             }
+            @username = username
+            @password = password
           end
 
         rescue SocketError
-          if( retried < max_retries )
-            retried += 1
-            logger.debug( format( 'cannot login, socket error (retry %d / %d)', retried, max_retries ) ) if @debug
-            sleep( sleep_between_retries )
-            retry
-          else
-            raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url )
-          end
+          raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url ) unless( retried < max_retries )
+
+          retried += 1
+          logger.debug( format( 'cannot login, socket error (retry %d / %d)', retried, max_retries ) ) if @debug
+          sleep( sleep_between_retries )
+          retry
 
         rescue RestClient::Unauthorized
           logger.debug( request_data.to_json ) if @debug
           raise format( 'Not authorized to connect \'%s\' - wrong username or password?', @url )
 
         rescue RestClient::BadGateway
-          if( retried < max_retries )
-            retried += 1
-            logger.debug( format( 'cannot login, connection refused (retry %d / %d)', retried, max_retries ) ) if @debug
-            sleep( sleep_between_retries )
-            retry
-          else
-            raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url )
-          end
+          raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url ) unless( retried < max_retries )
+
+          retried += 1
+          logger.debug( format( 'cannot login, connection refused (retry %d / %d)', retried, max_retries ) ) if @debug
+          sleep( sleep_between_retries )
+          retry
 
         rescue Errno::ECONNREFUSED
-          if( retried < max_retries )
-            retried += 1
-            logger.debug( format( 'cannot login, connection refused (retry %d / %d)', retried, max_retries ) ) if @debug
-            sleep( sleep_between_retries )
-            retry
-          else
-            raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url )
-          end
+          raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url ) unless( retried < max_retries )
+
+          retried += 1
+          logger.debug( format( 'cannot login, connection refused (retry %d / %d)', retried, max_retries ) ) if @debug
+          sleep( sleep_between_retries )
+          retry
 
         rescue Errno::EHOSTUNREACH
-          if( retried < max_retries )
-            retried += 1
-            logger.debug( format( 'cannot login, host unreachable (retry %d / %d)', retried, max_retries ) ) if @debug
-            sleep( sleep_between_retries )
-            retry
-          else
-            raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url )
-          end
+          raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url ) unless( retried < max_retries )
+
+          retried += 1
+          logger.debug( format( 'cannot login, host unreachable (retry %d / %d)', retried, max_retries ) ) if @debug
+          sleep( sleep_between_retries )
+          retry
+
+        rescue => error
+          raise format( 'Maximum retries (%d) against \'%s/login\' reached. Giving up ...', max_retries, @url ) unless( retried < max_retries )
+
+          retried += 1
+          logger.error( error )
+          logger.debug( format( 'cannot login (retry %d / %d)', retried, max_retries ) ) if @debug
+          sleep( sleep_between_retries )
+          retry
         end
 
         logger.debug('User session initiated') if @debug
-
         return true
       end
-
       false
     end
 
@@ -130,10 +131,15 @@ module Grafana
     # @return [Hash]
     #
     def ping_session
-      endpoint = '/api/login/ping'
       logger.debug( "Pinging current session (GET #{endpoint})" ) if @debug
+      endpoint = '/api/login/ping'
       get( endpoint )
     end
+
+
+    def headers
+      @headers
+    end
   end
 
 end