grafana 0.8.2 → 0.8.5

data/lib/grafana/client.rb

@@ -107,7 +107,6 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'open_timeout\' must be an Integer, given \'%s\'', @open_timeout.class.to_s)) unless( @open_timeout.is_a?(Integer) )
 
       protocoll = ssl == true ? 'https' : 'http'
-      raise ArgumentError.new(format('wrong \'protocoll\'. only \'http\' or \'https\' allowed, given \'%s\'', protocoll)) if( %w[http https].include?(protocoll.downcase) == false )
 
       @url      = format( '%s://%s:%d%s', protocoll, host, port, url_path )
     end

data/lib/grafana/dashboard.rb

@@ -7,14 +7,17 @@ module Grafana
 
 
     # Get dashboard
-    # GET /api/dashboards/db/:slug
+    #
+    # @example
+    #    dashboard('dashboard for many foo')
+    #
+    # @return [String]
+    #
     def dashboard( name )
 
       raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
       raise ArgumentError.new('missing name') if( name.size.zero? )
 
-#       raise ArgumentError.new('name must be an String') unless( name.is_a?(String) )
-
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
 
       @logger.debug( "Attempting to get dashboard (GET /api/dashboards/db/#{name})" ) if @debug
@@ -23,38 +26,70 @@ module Grafana
     end
 
     # Create / Update dashboard
+    #
+    # @param [Hash] params
+    # @option params [Hash] dashboard
+    # @option params [Boolean] overwrite (true)
+    #
+    # @example
+    #    params = {
+    #      dashboard: {
+    #        id: null,
+    #        title: 'Production Overview',
+    #        tags: [ 'templated' ],
+    #        timezone": 'browser',
+    #        rows: [
+    #          {
+    #          }
+    #        ],
+    #        'schemaVersion': 6,
+    #        'version': 0
+    #      },
+    #      overwrite: false
+    #    }
+    #    create_dashboard( params )
+    #
+    # @return [Hash]
+    #
     # POST /api/dashboards/db
     def create_dashboard( 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(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? )
+
+      dashboard = validate( params, required: true, var: 'dashboard', type: Hash )
+      overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || true
 
-      title     = params.dig(:title)
-      dashboard = params.dig(:dashboard)
+      dashboard = regenerate_template_ids( dashboard )
 
-      # raise ArgumentError.new('missing title') if( title.nil? )
-      raise ArgumentError.new('missing dashboard') if( dashboard.nil? )
-      raise ArgumentError.new(format('wrong type. dashboard must be an Hash, given %s', dashboard.class.to_s ) ) unless( dashboard.is_a?(Hash) )
+      db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
+      title = db.dig('dashboard','title')
 
       endpoint = '/api/dashboards/db'
-      # title     = slug(title)
 
-      # dashboard = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
-      dashboard = regenerate_template_ids( dashboard )
-
-      if( title.nil? )
-        db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
-        title = db.dig('dashboard','title')
-      end
+      payload = {
+        dashboard: db.dig('dashboard'),
+        overwrite: overwrite
+      }
+      payload.reject!{ |_k, v| v.nil? }
 
       @logger.debug("Creating dashboard: #{title} (POST /api/dashboards/db)") if @debug
 
-      post( endpoint, dashboard )
+      post( endpoint, payload.to_json )
     end
 
     # Delete dashboard
-    # DELETE /api/dashboards/db/:slug
+    #
+    # @example
+    #    delete_dashboard('dashboard for many foo')
+    #
+    # @return [Hash]
+    #
     def delete_dashboard( name )
 
+      raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
+      raise ArgumentError.new('missing name') if( name.size.zero? )
+
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
 
       @logger.debug("Deleting dashboard #{slug(name)} (DELETE #{endpoint})") if @debug
@@ -63,7 +98,12 @@ module Grafana
     end
 
     # Gets the home dashboard
-    # GET /api/dashboards/home
+    #
+    # @example
+    #    home_dashboard
+    #
+    # @return [Hash]
+    #
     def home_dashboard
 
       endpoint = '/api/dashboards/home'
@@ -74,7 +114,12 @@ module Grafana
     end
 
     # Tags for Dashboard
-    # GET /api/dashboards/tags
+    #
+    # @example
+    #    dashboard_tags
+    #
+    # @return [Hash]
+    #
     def dashboard_tags
 
       endpoint = '/api/dashboards/tags'
@@ -85,29 +130,30 @@ module Grafana
     end
 
     # Search Dashboards
-    # GET /api/search/
     #
-    #    searchDashboards( { :tags   => host } )
-    #    searchDashboards( { :tags   => [ host, 'tag1' ] } )
-    #    searchDashboards( { :tags   => [ 'tag2' ] } )
-    #    searchDashboards( { :query  => title } )
-    #    searchDashboards( { :starred => true } )
-    def search_dashboards( params = {} )
+    # @example
+    #    searchDashboards( tags: host )
+    #    searchDashboards( tags: [ host, 'tag1' ] )
+    #    searchDashboards( tags: [ 'tag2' ] )
+    #    searchDashboards( query: title )
+    #    searchDashboards( starred: true )
+    #
+    # @return [Hash]
+    #
+    def search_dashboards( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
 
-      query   = params.dig(:query)
-      starred = params.dig(:starred)
-      tags    = params.dig(:tags)
-      api     = []
+      query   = validate( params, required: false, var: 'query', type: String )
+      starred = validate( params, required: false, var: 'starred', type: Boolean )
+      tags    = validate( params, required: false, var: 'tags' )
 
+      api     = []
       api << format( 'query=%s', CGI.escape( query ) ) unless  query.nil?
       api << format( 'starred=%s', starred ? 'true' : 'false' ) unless( starred.nil? )
 
       unless( tags.nil? )
-
         tags = tags.join( '&tag=' ) if( tags.is_a?( Array ) )
-
         api << format( 'tag=%s', tags )
       end
 
@@ -120,7 +166,13 @@ module Grafana
       get( endpoint )
     end
 
-
+    # import Dashboards from directory
+    #
+    # @example
+    #    import_dashboards_from_directory( '/tmp/dashboards' )
+    #
+    # @return [Hash]
+    #
     def import_dashboards_from_directory( directory )
 
       raise ArgumentError.new('directory must be an String') unless( directory.is_a?(String) )
@@ -135,10 +187,9 @@ module Grafana
 
         dashboard = File.read( f )
         dashboard = JSON.parse( dashboard )
-        title     = dashboard.dig('dashboard','title') || f
 
         result[f.to_s] ||= {}
-        result[f.to_s] = create_dashboard( title: title, dashboard: dashboard )
+        result[f.to_s] = create_dashboard( dashboard: dashboard )
       end
 
       result

data/lib/grafana/datasource.rb

@@ -20,12 +20,7 @@ module Grafana
 
       datasources = get( endpoint )
 
-      if  datasources.nil? || datasources.dig('status').to_i != 200
-        return {
-          'status' => 404,
-          'message' => 'No Datasources found'
-        }
-      end
+      return { 'status' => 404, 'message' => 'No Datasources found' } if( datasources.nil? || datasources == false || datasources.dig('status').to_i != 200 )
 
       datasources = datasources.dig('message')
 
@@ -39,6 +34,8 @@ module Grafana
 
     # Get a single datasources by Id or Name
     #
+    # @param [Mixed] datasource_id Datasource Name (String) or Datasource Id (Integer)
+    #
     # @example
     #    datasource( 1 )
     #    datasource( 'foo' )
@@ -55,12 +52,7 @@ module Grafana
         datasource_id = data.keys.first if( data )
       end
 
-      if( datasource_id.nil? )
-        return {
-          'status' => 404,
-          'message' => format( 'No Datasource \'%s\' found', datasource_id)
-        }
-      end
+      return { 'status' => 404, 'message' => format( 'No Datasource \'%s\' found', datasource_id) } if( datasource_id.nil? )
 
       raise format('DataSource Id can not be 0') if( datasource_id.zero? )
 
@@ -82,14 +74,29 @@ module Grafana
     # merge an current existing datasource configuration with the new values
     #
     # @param [Hash] params
-    # @option params [Hash] data
-    # @option params [Mixed] datasource Datasource Name (String) or Datasource Id (Integer)
+    # @option params [Mixed] name Name or Id of the current existing Datasource (required)
+    # @option params [Mixed] organisation Name or Id of an existing Organisation
+    # @option params [String] type Datasource Type - (required) (grafana graphite cloudwatch elasticsearch prometheus influxdb mysql opentsdb postgres)
+    # @option params [String] new_name  New Datasource Name
+    # @option params [String] database  Datasource Database
+    # @option params [String] access (proxy) Acess Type
+    # @option params [Boolean] default (false)
+    # @option params [String] user
+    # @option params [String] password
+    # @option params [String] url Datasource URL
+    # @option params [Hash] json_data
+    # @option params [String] basic_user
+    # @option params [String] basic_password
     #
     # @example
-    #    update_datasource(
-    #      datasource: 'graphite',
-    #      data: { url: 'http://localhost:2003' }
-    #    )
+    #    params = {
+    #      name: 'graphite',
+    #      new_name: 'influx',
+    #      organisation: 'Main Org.',
+    #      type: 'influxdb',
+    #      url: 'http://localhost:8090'
+    #    }
+    #    update_datasource( params )
     #
     # @return [Hash]
     #
@@ -98,22 +105,70 @@ module Grafana
       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? )
 
-      data       = validate( params, required: true, var: 'data', type: Hash )
-      datasource = validate( params, required: true, var: 'datasource' )
+      name = validate( params, required: true, var: 'name' )
+      organisation  = validate( params, required: false, var: 'organisation' )
+      type          = validate( params, required: false, var: 'type', type: String )
+      new_name      = validate( params, required: false, var: 'new_name', type: String )
+      database    = validate( params, required: false, var: 'database', type: String )
+      access      = validate( params, required: false, var: 'access', type: String ) || 'proxy'
+      default     = validate( params, required: false, var: 'default', type: Boolean ) || false
+      user        = validate( params, required: false, var: 'user', type: String )
+      password    = validate( params, required: false, var: 'password', type: String )
+      url         = validate( params, required: false, var: 'url', type: String )
+      json_data   = validate( params, required: false, var: 'json_data', type: Hash )
+      ba_user     = validate( params, required: false, var: 'basic_user', type: String )
+      ba_password = validate( params, required: false, var: 'basic_password', type: String )
+      basic_auth  = false
+      basic_auth  = true unless( ba_user.nil? && ba_password.nil? )
+      org_id      = nil
+
+      raise ArgumentError.new(format('wrong type. user \'name\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', name.class.to_s)) if( name.is_a?(String) && name.is_a?(Integer) )
 
-      raise ArgumentError.new(format('wrong type. user \'datasource\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', datasource.class.to_s)) if( datasource.is_a?(String) && datasource.is_a?(Integer) )
+      if( organisation )
+        raise ArgumentError.new(format('wrong type. user \'organisation\' must be an String (for an Organisation name) or an Integer (for an Organisation Id), given \'%s\'', organisation.class.to_s)) if( organisation.is_a?(String) && organisation.is_a?(Integer) )
+        org    = organization( organisation )
+        org_id = org.dig('id')
 
-      existing_ds = datasource(datasource)
+        return { 'status' => 404, 'message' => format('Organization \'%s\' not found', organization) } if( org.nil? || org.dig('status').to_i != 200 )
+      end
 
+      existing_ds = datasource(name)
       existing_ds.reject! { |x| x == 'status' }
       existing_ds = existing_ds.deep_string_keys
-
       datasource_id = existing_ds.dig('id')
 
+      return { 'status' => 404, 'message' => format('No Datasource \'%s\' found', name) } if( datasource_id.nil? )
+
+      raise format('Data Source Id can not be 0') if( datasource_id.zero? )
+
+      unless( type.nil? )
+        valid_types = %w[grafana graphite cloudwatch elasticsearch prometheus influxdb mysql opentsdb postgres]
+        raise ArgumentError.new(format('wrong datasource type. only %s allowed, given \%s\'', valid_types.join(', '), type)) if( valid_types.include?(type.downcase) == false )
+      end
+
+      data = {
+        id: datasource_id,
+        orgId: org_id,
+        name: new_name,
+        type: type,
+        access: access,
+        url: url,
+        password: password,
+        user: user,
+        database: database,
+        basicAuth: basic_auth,
+        basicAuthUser: ba_user,
+        basicAuthPassword: ba_user,
+        isDefault: default,
+        jsonData: json_data
+      }
+      data.reject!{ |_k, v| v.nil? }
+
       payload = data.deep_string_keys
       payload = existing_ds.merge(payload).deep_symbolize_keys
 
       endpoint = format('/api/datasources/%d', datasource_id )
+
       @logger.debug("Updating data source Id #{datasource_id} (GET #{endpoint})") if  @debug
       logger.debug(payload.to_json) if(@debug)
 
@@ -128,7 +183,6 @@ module Grafana
     # @option params [String] database  Datasource Database - (required)
     # @option params [String] access (proxy) Acess Type - (required) (proxy or direct)
     # @option params [Boolean] default (false)
-    # @option params [String] user
     # @option params [String] password
     # @option params [String] url Datasource URL - (required)
     # @option params [Hash] json_data
@@ -182,7 +236,6 @@ module Grafana
       database    = validate( params, required: true, var: 'database', type: String )
       access      = validate( params, required: false, var: 'access', type: String ) || 'proxy'
       default     = validate( params, required: false, var: 'default', type: Boolean ) || false
-      user        = validate( params, required: false, var: 'user', type: String )
       password    = validate( params, required: false, var: 'password', type: String )
       url         = validate( params, required: true, var: 'url', type: String )
       json_data   = validate( params, required: false, var: 'json_data', type: Hash )
@@ -241,12 +294,7 @@ module Grafana
         datasource_id = data.keys.first if( data )
       end
 
-      if( datasource_id.nil? )
-        return {
-          'status' => 404,
-          'message' => format( 'No Datasource \'%s\' found', datasource_id)
-        }
-      end
+      return { 'status' => 404, 'message' => format( 'No Datasource \'%s\' found', datasource_id) } if( datasource_id.nil? )
 
       raise format('Data Source Id can not be 0') if( datasource_id.zero? )
 

data/lib/grafana/network.rb

@@ -64,9 +64,15 @@ module Grafana
               response_code = response.code.to_i
               raise RestClient::BadRequest
             else
-              logger.error( response.code )
-              logger.error( response.body )
-              response.return! # (request, result)
+#               logger.error( response.code )
+#               logger.error( response.body )
+
+              body = JSON.parse(response.body) if(response_body.is_a?(String))
+              return {
+                'status' => response_code,
+                'message' => body.dig('message')
+              }
+              # response.return! # (request, result)
             end
           end
 
@@ -129,6 +135,12 @@ module Grafana
           'status' => 401,
           'message' => format('Not authorized to connect \'%s/%s\' - wrong username or password?', @url, endpoint)
         }
+      rescue RestClient::Forbidden
+
+        return {
+          'status' => 403,
+          'message' => format('The operation is forbidden \'%s/%s\'', @url, endpoint)
+        }
 
       rescue RestClient::NotFound
 

data/lib/grafana/organization.rb

@@ -6,9 +6,11 @@ module Grafana
   module Organization
 
     # Get current Organisation
-    # GET /api/org
     #
-    #  -> {"id"=>1, "name"=>"Docker", "address"=>{"address1"=>"", "address2"=>"", "city"=>"", "zipCode"=>"", "state"=>"", "country"=>""}, "status"=>200}
+    # @example
+    #    current_organization
+    #
+    # @return [Hash]
     #
     def current_organization
       endpoint = '/api/org'
@@ -17,25 +19,40 @@ module Grafana
     end
 
     # Update current Organisation
-    # PUT /api/org
     #
+    # @param [Hash] params
+    # @option params [String] name new Organisation Name
+    #
+    # @example
+    #    params = {
+    #       name: 'foo'
+    #    }
+    #    update_current_organization( params )
     #
+    # @return [Hash]
     #
-    def update_current_organization( params = {} )
+    def update_current_organization( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
-      name = params.dig(:name)
-      raise ArgumentError.new('missing name') if( name.nil? )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      name         = validate( params, required: true, var: 'name', type: String )
 
       endpoint = '/api/org'
+      payload = {
+        name: name
+      }
+
       @logger.debug("Updating current organization (PUT #{endpoint})") if @debug
-      put(endpoint, params.to_json)
+      put(endpoint, payload.to_json)
     end
 
     # Get all users within the actual organisation
-    # GET /api/org/users
     #
+    # @example
+    #    current_organization_users
     #
+    # @return [Hash]
     #
     def current_organization_users
       endpoint = '/api/org/users'
@@ -44,46 +61,59 @@ module Grafana
     end
 
     # Add a new user to the actual organisation
-    # POST /api/org/users
     #
+    # @param [Hash] params
+    # @option params [String] login_or_email Login or email
+    # @option params [String] role Name of the Role - only 'Viewer', 'Editor', 'Read Only Editor' or 'Admin' allowed
+    #
+    # @example
+    #    params = {
+    #       login_or_email: 'foo',
+    #       role: 'Editor'
+    #    }
+    #    add_user_to_current_organization( params )
     #
+    # @return [Hash]
     #
-    def add_user_to_current_organization( params = {} )
+    def add_user_to_current_organization( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
-      login_or_email = params.dig(:loginOrEmail)
-      role           = params.dig(:role)
-      raise ArgumentError.new('missing loginOrEmail') if( login_or_email.nil? )
-      raise ArgumentError.new('missing role') if( role.nil? )
-      # Defaults to Viewer, other valid options are Admin and Editor and Read Only Editor
-      # valid_perms = ['Viewer','Editor','Read Only Editor','Admin']
-      raise ArgumentError.new( format( 'wrong role. only \'Admin\', \'Viewer\' or \'Editor\' allowed (\'%s\' giving)',role)) if( %w[Admin Viewer Editor].include?(role) == false )
-
-      org = current_organization_users
-      usr = user_by_name( login_or_email )
-
-      if( org )
-
-        org = org.dig('message')
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-        if( org.select { |x| x.dig('email') == login_or_email }.count >= 1 )
-          return {
-            'status' => 404,
-            'message' => format('User \'%s\' are already in the organisation', login_or_email)
-          }
-        end
-      end
+      login_or_email = validate( params, required: true, var: 'login_or_email', type: String )
+      role           = validate( params, required: true, var: 'role', type: String )
+      valid_roles    = ['Viewer', 'Editor', 'Read Only Editor', 'Admin']
 
-      if( usr.nil? || usr.dig('status').to_i != 200 )
+      # https://stackoverflow.com/questions/9333952/case-insensitive-arrayinclude?answertab=votes#tab-top
+      # Do this once, or each time the array changes
+      downcased = Set.new valid_roles.map(&:downcase)
+      unless( downcased.include?( role.downcase ) )
         return {
           'status' => 404,
-          'message' => format('User \'%s\' not found', login_or_email)
+          'login_or_email' => login_or_email,
+          'role' => role,
+          'message' => format( 'wrong role. Role must be one of %s, given \'%s\'', valid_roles.join(', '), role )
         }
       end
 
+      org = current_organization_users
+      usr = user( login_or_email )
+
+      return { 'status' => 404, 'message' => format('User \'%s\' not found', login_or_email) } if( usr.nil? || usr.dig('status').to_i != 200 )
+
+      if( org.is_a?(Hash) && org.dig('status').to_i == 200 )
+        org = org.dig('message')
+        return { 'status' => 404, 'message' => format('User \'%s\' are already in the organisation', login_or_email) } if( org.select { |x| x.dig('email') == login_or_email || x.dig('login') == login_or_email }.count >= 1 )
+      end
+
       endpoint = '/api/org/users'
+      payload = {
+        loginOrEmail: login_or_email,
+        role: role
+      }
+
       @logger.debug("Adding user to current organization (POST #{endpoint})") if @debug
-      post(endpoint, params.to_json)
+      post(endpoint, payload.to_json)
     end
 
     # Updates the given user