wavefront-sdk 4.0.0 → 5.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 578159c0ff0dac09b94caa4dac4e37f03436cb3e2b4cdda54886ce91b9ce4c9b
-  data.tar.gz: 93eac0630e97d53e3b26d222fd09df61f8cd7966c62e39520dbf27525982cb1b
+  metadata.gz: 5e623522f872c4204c1e723ee5a399c513251933e64445f6f5b65ff66d2fbffc
+  data.tar.gz: 6f55f44177169c24d4c0aa89490464097a6fe2278e24a1e3b83e5f7520757dfd
 SHA512:
-  metadata.gz: e3f09ae6d818b0acc7e81e2e4da585c10a59efba18a4ab373679783d62b5a5ccc300e14435b7cbe8a0f2d64adec361e080c55f089732ffbb6c171f619524440e
-  data.tar.gz: d558a6d0eafe0d09120317113758ee70807cae035a7e9677a22cf643e537103ff66d671e7e6a031151cd03572f6b62a78e9aa92a86a2fb052f0cb31ba92c4f17
+  metadata.gz: 58bb998cc92b36c369497631f766af8844a692fbd10508962ee7bd30f4fbe65d222bc512d06b63feb19ca94cdcc4e8429b8c61f6227e4ff1041cd6ffff141758
+  data.tar.gz: 198dfadd7561b5c3772211716d23f9653ace3bbf472e41d12fa8b64d744ed16567bb11796ef3aff252054bc0945200ea71e454b5989824656c178e74503b4675

data/.rubocop.yml

@@ -1,7 +1,18 @@
 ---
 
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.4
+  NewCops: enable
 
 Metrics/ClassLength:
   Max: 150
+
+# Is nothing sacred?
+Layout/LineLength:
+  Max: 80
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  Enabled: false

data/HISTORY.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 5.2.1 (2020-09-18)
+* Remove necessity for user to `require 'pathname'`
+
+## 5.2.0 (2020-09-03)
+* Add `:raise_on_no_profile` option to `Wavefront::Credentials` constructor
+  options. If this is true and a specific config stanza is requested but not
+  found, `Wavefront::Exception::MissingConfigProfile` is thrown.
+
+## 5.1.0 (2020-08-15)
+* Add `create_aws_external_id`, `delete_aws_external_id`, and
+  `confirm_aws_external_id` methods to `Wavefront::CloudIntegration`.
+
+## 5.0.1 (2020-07-08)
+* Reinstate `Wavefront::Role#grant` and `Wavefront::Role#revoke`, which were
+  accidentally removed prior to release of 5.0.0.
+
+## 5.0.0 (2020-07-08)
+* Remove `Wavefront::UserGroup#grant` and `Wavefront::UserGroup#revoke` as [the
+ API paths they used have been
+ removed](https://docs.wavefront.com/2020.06.x_release_notes.html#obsolete-and-deprecated-apis).
+ (Breaking change.)
+* Remove `Wavefront::MonitoredCluster` class, as it has been removed from the
+  public API.
+* Deprecate `Wavefront::User` class, as [the user API is now
+  deprecated](https://docs.wavefront.com/2020.06.x_release_notes.html#obsolete-and-deprecated-apis)
+* Add `Wavefront::Role` class, for managing roles.
+* Promote `Wavefront::Spy` class from unstable. It is now an official API.
+
 ## 4.0.0 (2020-02-17)
 * Drop support for Ruby 2.3. (Breaking change.)
 * Add `Wavefront::MonitoredCluster` class.

data/README.md

@@ -100,10 +100,11 @@ when you ask for a list of objects.
 
 You can set an offset and a limit when you list, but setting the
 limit to the magic value `:all` will return all items, without you
-having to deal with pagination.
+having to deal with pagination. When you do that, `offset` is repurposed as
+the number of results fetched with each call to the API.
 
 Calling a method with the limit set to `:lazy` returns a lazy
-enumerable.
+enumerable. Again, `offset` is the chunk size.
 
 ```ruby
 wf = Wavefront::Alert.new(creds.all)

data/lib/wavefront-sdk/account.rb

@@ -44,6 +44,18 @@ module Wavefront
       api.get(id)
     end
 
+    # POST /api/v2/account/{id}/addRoles
+    # Add specific roles to the account (user or service account)
+    # @param id [String] ID of the account
+    # @param role_list [Array[String]] list of roles to add
+    # @return [Wavefront::Response]
+    #
+    def add_roles(id, role_list)
+      wf_account_id?(id)
+      validate_role_list(role_list)
+      api.post([id, 'addRoles'].uri_concat, role_list, 'application/json')
+    end
+
     # POST /api/v2/account/{id}/addUserGroups
     # Adds specific user groups to the account (user or service account)
     # @param id [String] ID of the account
@@ -68,10 +80,22 @@ module Wavefront
       api.get([id, 'businessFunctions'].uri_concat)
     end
 
+    # POST /api/v2/account/{id}/removeRoles
+    # Removes specific roles from the account (user or service account)
+    # @param id [String] ID of the account
+    # @param role_list [Array[String]] list of roles to remove
+    # @return [Wavefront::Response]
+    #
+    def remove_roles(id, role_list)
+      wf_account_id?(id)
+      validate_role_list(role_list)
+      api.post([id, 'removeRoles'].uri_concat, role_list, 'application/json')
+    end
+
     # POST /api/v2/account/{id}/removeUserGroups
     # Removes specific user groups from the account (user or service account)
     # @param id [String] ID of the account
-    # @param group_list [Array[String]] list of groups to add
+    # @param group_list [Array[String]] list of groups to remove
     # @return [Wavefront::Response]
     #
     def remove_user_groups(id, group_list)
@@ -132,7 +156,8 @@ module Wavefront
     end
 
     # POST /api/v2/account/removeingestionpolicies
-    # Removes ingestion policies from multiple accounts
+    # Removes ingestion policies from multiple accounts. The API path says
+    # "policies" but I've made the method name "policy" for consistency.
     # @param policy_id [String] ID of the ingestion policy
     # @param id_list [Array[String]] list of accounts to be put in policy
     # @return [Wavefront::Response]
@@ -140,7 +165,7 @@ module Wavefront
     def remove_ingestion_policy(policy_id, id_list)
       wf_ingestionpolicy_id?(policy_id)
       validate_account_list(id_list)
-      api.post('removeingestionpolicy',
+      api.post('removeingestionpolicies',
                { ingestionPolicyId: policy_id,
                  accounts: id_list },
                'application/json')
@@ -157,6 +182,78 @@ module Wavefront
       api.post('deleteAccounts', id_list, 'application/json')
     end
 
+    # GET /api/v2/account/user
+    # Get all user accounts
+    # @param offset [Int] user account at which the list begins
+    # @param limit [Int] the number of user accounts to return
+    # @return [Wavefront::Response]
+    #
+    def user_list(offset = 0, limit = 100)
+      api.get('user', offset: offset, limit: limit)
+    end
+
+    def user_create(body, send_email = false)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      uri = send_email ? "?sendEmail=#{send_email}" : 'user'
+
+      api.post(uri, body, 'application/json')
+    end
+
+    # POST /api/v2/account/user
+    # Creates or updates a user account
+    # @param id [String] a Wavefront user ID
+    # @param body [Hash] key-value hash of the parameters you wish to change
+    # @param modify [true, false] if true, use {#describe()} to get a hash
+    #   describing the existing object, and modify that with the new body. If
+    #   false, pass the new body straight through.
+    # @return [Wavefront::Response]
+    def user_update(body, modify = true)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      return api.post('user', body, 'application/json') unless modify
+
+      api.post('user',
+               hash_for_update(describe(id).response, body),
+               'application/json')
+    end
+
+    # GET /api/v2/account/user/{id}
+    # Retrieves a user by identifier (email address)
+    # @param id [String] ID of the proxy
+    # @return [Wavefront::Response]
+    #
+    def user_describe(id)
+      wf_user_id?(id)
+      api.get(['user', id].uri_concat)
+    end
+
+    # POST /api/v2/account/user/invite
+    # Invite user accounts with given user groups and permissions.
+    # @param body [Array[Hash]] array of hashes, each hash describing a user.
+    #   See API docs for more details. It is your responsibility to validate
+    #   the data which describes each user.
+    # @return [Wavefront::Response]
+    #
+    def user_invite(body)
+      raise ArgumentError unless body.is_a?(Array)
+      raise ArgumentError unless body.first.is_a?(Hash)
+
+      api.post('user/invite', body, 'application/json')
+    end
+
+    # POST /api/v2/account/validateAccounts
+    # Returns valid accounts (users and service accounts), also invalid
+    # identifiers from the given list
+    # @param id_list [Array[String]] list of user IDs
+    # @return [Wavefront::Response]
+    #
+    def validate_accounts(id_list)
+      raise ArgumentError unless id_list.is_a?(Array)
+
+      api.post('validateAccounts', id_list, 'application/json')
+    end
+
     private
 
     # @param id [String] ID of the user
@@ -198,5 +295,9 @@ module Wavefront
       wf_permission?(permission)
       api.post(['revoke', permission].uri_concat, id_list, 'application/json')
     end
+
+    def update_keys
+      %i[identifier groups userGroups roles ingestionPolicyId]
+    end
   end
 end

data/lib/wavefront-sdk/api_mixins/user.rb

@@ -35,6 +35,16 @@ module Wavefront
 
         list.each { |id| wf_account_id?(id) }
       end
+
+      # Validate a list of roles
+      # @param list [Array[String]] list of role IDs
+      # @raise Wavefront::Exception::InvalidRole
+      #
+      def validate_role_list(list)
+        raise ArgumentError unless list.is_a?(Array)
+
+        list.each { |id| wf_role_id?(id) }
+      end
     end
   end
 end

data/lib/wavefront-sdk/cloudintegration.rb

@@ -101,5 +101,32 @@ module Wavefront
       wf_cloudintegration_id?(id)
       api.post([id, 'undelete'].uri_concat)
     end
+
+    # POST /api/v2/cloudintegration/awsExternalIdCreate an external id
+    # @return [Wavefront::Response]
+    #
+    def create_aws_external_id
+      api.post('awsExternalId', nil, 'application/json')
+    end
+
+    # DELETE /api/v2/cloudintegration/awsExternalId/{id}DELETEs an external id
+    # that was created by Wavefront
+    # @param id [String] AWS external ID
+    # @return [Wavefront::Response]
+    #
+    def delete_aws_external_id(external_id)
+      wf_aws_external_id?(external_id)
+      api.delete(['awsExternalId', external_id].uri_concat)
+    end
+
+    # GET /api/v2/cloudintegration/awsExternalId/{id}GETs (confirms) a valid
+    # external id that was created by Wavefront
+    # @param id [String] AWS external ID
+    # @return [Wavefront::Response]
+    #
+    def confirm_aws_external_id(external_id)
+      wf_aws_external_id?(external_id)
+      api.get(['awsExternalId', external_id].uri_concat)
+    end
   end
 end

data/lib/wavefront-sdk/core/exception.rb

@@ -12,6 +12,7 @@ module Wavefront
     class InvalidAlertId < RuntimeError; end
     class InvalidAlertSeverity < RuntimeError; end
     class InvalidApiTokenId < RuntimeError; end
+    class InvalidAwsExternalId < RuntimeError; end
     class InvalidConfigFile < RuntimeError; end
     class InvalidCloudIntegrationId < RuntimeError; end
     class InvalidDashboardId < RuntimeError; end
@@ -38,6 +39,7 @@ module Wavefront
     class InvalidPoint < RuntimeError; end
     class InvalidPrefixLength < RuntimeError; end
     class InvalidProxyId < RuntimeError; end
+    class InvalidRoleId < RuntimeError; end
     class InvalidRelativeTime < RuntimeError; end
     class InvalidSamplingValue < RuntimeError; end
     class InvalidSavedSearchEntity < RuntimeError; end
@@ -53,6 +55,7 @@ module Wavefront
     class InvalidUserGroupId < RuntimeError; end
     class InvalidVersion < RuntimeError; end
     class InvalidWebhookId < RuntimeError; end
+    class MissingConfigProfile < RuntimeError; end
     class NetworkTimeout < RuntimeError; end
     class NotImplemented < RuntimeError; end
     class SocketError < RuntimeError; end

data/lib/wavefront-sdk/credentials.rb

@@ -31,11 +31,16 @@ module Wavefront
     # @param options [Hash] keys may be 'file', which
     #   specifies a config file which will be loaded and parsed. If
     #   no file is supplied, those listed above will be used.;
-    #   and/or 'profile' which select a profile section from 'file'
+    #   and/or 'profile' which select a profile section from 'file'.
+    #   Specify the key :raise_noprofile to have an exception thrown
+    #   if a given profile cannot be found. Otherwise that is ignored and
+    #   options are built from other sources.
     #
     def initialize(options = {})
-      raw = load_from_file(cred_files(options), options[:profile] ||
-                           'default')
+      @raise_noprofile = options[:raise_on_no_profile] || false
+      raw = load_from_file(real_files(cred_files(options)),
+                           options[:profile] || 'default')
+
       populate(env_override(raw))
     end
 
@@ -80,31 +85,45 @@ module Wavefront
       end
     end
 
+    def real_files(files)
+      files.select { |f| f.exist? && f.file? }
+    end
+
     # @param files [Array][Pathname] a list of ini-style config files
     # @param profile [String] a profile name
+    # @param disallow_missing [Bool] whether or not to raise an exception if
+    #   we are given a profile but can't find it.
     # @return [Hash] the given profile from the given list of files.
     #   If multiple files match, the last one will be used
     #
     def load_from_file(files, profile = 'default')
       ret = {}
+      profiles_found = conf_files_found = 0
 
       files.each do |f|
-        next unless f.exist? && f.file?
-
         ret = load_profile(f, profile)
+        conf_files_found += 1
+        profiles_found += 1 unless ret.empty?
         ret[:file] = f
       end
 
+      raise_on_missing_profile(profile, profiles_found, conf_files_found)
       ret
     end
 
-    # Load in an (optionally) given section of an ini-style
-    # configuration file not there, we don't consider that an error.
+    def raise_on_missing_profile(profile, profiles_found, conf_files_found)
+      return true unless @raise_noprofile
+      return true unless profiles_found.zero? && conf_files_found.positive?
+
+      raise Wavefront::Exception::MissingConfigProfile, profile
+    end
+
+    # Load in an (optionally) given section of an ini-style configuration
+    # file. If the section is not there, we don't consider that an error.
     #
     # @param file [Pathname] the file to read
     # @param profile [String] the section in the config to read
-    # @return [Hash] options loaded from file. Each key becomes a
-    #   symbol
+    # @return [Hash] options loaded from file. Each key becomes a symbol
     #
     def load_profile(file, profile = 'default')
       IniFile.load(file)[profile].each_with_object({}) do |(k, v), memo|

data/lib/wavefront-sdk/defs/version.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
-WF_SDK_VERSION = '4.0.0'
+require 'pathname'
+
+WF_SDK_VERSION = '5.2.1'
 WF_SDK_LOCATION = Pathname.new(__dir__).parent.parent.parent

data/lib/wavefront-sdk/distribution.rb

@@ -65,6 +65,7 @@ module Wavefront
       raise Wavefront::Exception::InvalidDistribution
     end
 
+    # rubocop:disable Metrics/AbcSize
     def dist_hash(dist)
       dist.dup.tap do |d|
         d[:interval] = distribution_interval(dist)
@@ -75,6 +76,7 @@ module Wavefront
         d[:opttags] = tags_or_nothing(opts[:tags])
       end
     end
+    # rubocop:enable Metrics/AbcSize
 
     def distribution_timestamp(dist)
       parse_time(dist.fetch(:ts, Time.now))

data/lib/wavefront-sdk/paginator/base.rb

@@ -5,23 +5,29 @@ require_relative '../defs/constants'
 module Wavefront
   module Paginator
     #
-    # Automatically handle pagination. This is an abstract class
-    # made concrete by an extension for each HTTP request type.
+    # Automatically handle pagination. This is an abstract class made concrete
+    # by an extension for each HTTP request type.
     #
-    # This class and its children do slightly unpleasant things with
-    # the HTTP request passed to us by the user, extracting and
-    # changing values in the URI, query string, or POST/PUT body.
-    # The POST class is particularly onerous.
+    # This class and its children do slightly unpleasant things with the HTTP
+    # request passed to us by the user, extracting and changing values in the
+    # URI, query string, or POST/PUT body.  The POST class is particularly
+    # onerous.
     #
-    # Automatic pagination works by letting the user override the
-    # limit and offset values in API calls. Setting the limit to
-    # :all iteratively calls the Wavefront API, returning all
-    # requested objects an a standard Wavefront::Response wrapper;
-    # setting limit to :lazy returns a lazy Enumerable. The number
-    # of objects fetched in each API call, whether eager or lazy
-    # defaults to PAGE_SIZE, but the user can override that value by
-    # using the offset argument in conjunction with limit = :lazy |
-    # :all.
+    # Automatic pagination works by letting the user override the limit and
+    # offset values in API calls.
+    #
+    # * Calling with limit = :all iteratively calls the Wavefront API,
+    # returning all requested objects in a standard Wavefront::Response
+    # wrapper.
+    #
+    # * Calling with limit = :lazy returns a lazy Enumerable.
+    #
+    # The number of objects fetched in each API call, eager or lazy, defaults
+    # to PAGE_SIZE, but the user can override that value by using the offset
+    # argument in conjunction with limit = :lazy | :all.
+    #
+    # So, for example, to fetch all objects in blocks of ten (which could
+    # require a lot of API calls) you would use { limit: :all, offset: 10 }
     #
     class Base
       attr_reader :api_caller, :conn, :method, :args, :page_size,