couchbase 3.7.0 → 3.8.0

data/lib/couchbase/management/user_manager.rb

@@ -15,274 +15,443 @@
 #  limitations under the License.
 
 require "couchbase/errors"
+require "couchbase/options"
 
 require "time"
 
 module Couchbase
   module Management
+    module Options
+      module User
+        # Options for {UserManager#get_user}
+        class GetUser < ::Couchbase::Options::Base
+          # @return [:local, :external] Name of the user's domain. Defaults to +:local+
+          attr_accessor :domain
+
+          # Creates an instance of options for {UserManager#get_user}
+          # @param [:local, :external] domain the name of the user's domain. Defaults to +:local+
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetUser] self
+          def initialize(domain: :local,
+                         timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super(timeout: timeout, retry_strategy: retry_strategy, parent_span: parent_span)
+            @domain = domain
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = GetUser.new.freeze
+        end
+
+        # Options for {UserManager#get_all_users}
+        class GetAllUsers < ::Couchbase::Options::Base
+          # @return [:local, :external] Name of the user's domain. Defaults to +:local+
+          attr_accessor :domain
+
+          # Creates an instance of options for {UserManager#get_all_users}
+          # @param [:local, :external] the name of the user's domain. Defaults to +:local+
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetAllUsers] self
+          def initialize(domain: :local,
+                         timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super(timeout: timeout, retry_strategy: retry_strategy, parent_span: parent_span)
+            @domain = domain
+            yield self if block_given?
+          end
+        end
+
+        # Options for {UserManager#upsert_user}
+        class UpsertUser < ::Couchbase::Options::Base
+          # @return [:local, :external] Name of the user's domain. Defaults to +:local+
+          attr_accessor :domain
+
+          # Creates an instance of options for {UserManager#upsert_user}
+          # @param [:local, :external] domain the name of the user's domain. Defaults to +:local+
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [UpsertUser] self
+          def initialize(domain: :local,
+                         timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super(timeout: timeout, retry_strategy: retry_strategy, parent_span: parent_span)
+            @domain = domain
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = UpsertUser.new.freeze
+        end
+
+        # Options for {UserManager#drop_user}
+        class DropUser < ::Couchbase::Options::Base
+          # @return [:local, :external] Name of the user's domain. Defaults to +:local+
+          attr_accessor :domain
+
+          # Creates an instance of options for {UserManager#drop_user}
+          # @param [:local, :external] domain the name of the user's domain. Defaults to +:local+
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [DropUser] self
+          def initialize(domain: :local,
+                         timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super(timeout: timeout, retry_strategy: retry_strategy, parent_span: parent_span)
+            @domain = domain
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = DropUser.new.freeze
+        end
+
+        # Options for {UserManager#change_password}
+        class ChangePassword < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#change_password}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [ChangePassword] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = ChangePassword.new.freeze
+        end
+
+        # Options for {UserManager#get_roles}
+        class GetRoles < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#get_roles}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetRoles] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = GetRoles.new.freeze
+        end
+
+        # Options for {UserManager#get_group}
+        class GetGroup < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#get_group}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetGroup] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = GetGroup.new.freeze
+        end
+
+        # Options for {UserManager#get_all_groups}
+        class GetAllGroups < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#get_all_groups}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [GetAllGroups] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = GetAllGroups.new.freeze
+        end
+
+        # Options for {UserManager#upsert_group}
+        class UpsertGroup < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#upsert_group}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [UpsertGroup] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = UpsertGroup.new.freeze
+        end
+
+        # Options for {UserManager#drop_group}
+        class DropGroup < ::Couchbase::Options::Base
+          # Creates an instance of options for {UserManager#drop_group}
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [DropGroup] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          # @api private
+          DEFAULT = DropGroup.new.freeze
+        end
+      end
+    end
+
     class UserManager
       alias inspect to_s
 
       # @param [Couchbase::Backend] backend
-      def initialize(backend)
+      # @param [Couchbase::Observability::Wrapper] observability wrapper
+      #
+      # @api private
+      def initialize(backend, observability)
         @backend = backend
+        @observability = observability
       end
 
       # Get a user
       #
       # @param [String] username ID of the user
-      # @param [GetUserOptions] options
+      # @param [Options::User::GetUser] options
       #
       # @return [UserAndMetadata]
       #
       # @raise [ArgumentError]
       # @raise [Error::UserNotFound]
-      def get_user(username, options = GetUserOptions.new)
-        resp = @backend.user_get(options.domain, username, options.timeout)
-        extract_user(resp)
+      def get_user(username, options = Options::User::GetUser::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_GET_USER, options.parent_span, self, :management) do |obs_handler|
+          resp = @backend.user_get(options.domain, username, options.timeout, obs_handler)
+          extract_user(resp)
+        end
       end
 
       # Gets all users
       #
+      # @param [Options::User::GetAllUsers] options
+      #
       # @return [Array<UserAndMetadata>]
-      def get_all_users(options = GetAllUsersOptions.new)
-        resp = @backend.user_get_all(options.domain, options.timeout)
-        resp.map { |entry| extract_user(entry) }
+      def get_all_users(options = Options::User::GetAllUsers::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_GET_ALL_USERS, options.parent_span, self, :management) do |obs_handler|
+          resp = @backend.user_get_all(options.domain, options.timeout, obs_handler)
+          resp.map { |entry| extract_user(entry) }
+        end
       end
 
       # Creates or updates a user
       #
       # @param [User] user the new version of the user
-      # @param [UpsertUserOptions] options
+      # @param [Options::User::UpsertUser] options
       #
       # @raise [ArgumentError]
-      def upsert_user(user, options = UpsertUserOptions.new)
-        @backend.user_upsert(
-          options.domain,
-          {
-            username: user.username,
-            display_name: user.display_name,
-            groups: user.groups,
-            password: user.password,
-            roles: user.roles.map do |role|
-                     {
-                       name: role.name,
-                       bucket: role.bucket,
-                       scope: role.scope,
-                       collection: role.collection,
-                     }
-                   end,
-          }, options.timeout
-        )
+      def upsert_user(user, options = Options::User::UpsertUser::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_UPSERT_USER, options.parent_span, self, :management) do |obs_handler|
+          @backend.user_upsert(
+            options.domain,
+            {
+              username: user.username,
+              display_name: user.display_name,
+              groups: user.groups,
+              password: user.password,
+              roles: user.roles.map do |role|
+                {
+                  name: role.name,
+                  bucket: role.bucket,
+                  scope: role.scope,
+                  collection: role.collection,
+                }
+              end,
+            },
+            options.timeout,
+            obs_handler,
+          )
+        end
       end
 
       # Removes a user
       #
       # @param [String] username ID of the user
-      # @param [DropUserOptions] options
-      def drop_user(username, options = DropUserOptions.new)
-        @backend.user_drop(options.domain, username, options.timeout)
+      # @param [Options::User::DropUser] options
+      def drop_user(username, options = Options::User::DropUser::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_DROP_USER, options.parent_span, self, :management) do |obs_handler|
+          @backend.user_drop(options.domain, username, options.timeout, obs_handler)
+        end
       end
 
       # Gets all roles supported by the server
       #
-      # @param [GetRolesOptions] options
+      # @param [Options::User::GetRoles] options
       #
       # @return [Array<RoleAndDescription>]
-      def get_roles(options = GetRolesOptions.new)
-        resp = @backend.role_get_all(options.timeout)
-        resp.map do |r|
-          RoleAndDescription.new do |role|
-            role.name = r[:name]
-            role.display_name = r[:display_name]
-            role.description = r[:description]
-            role.bucket = r[:bucket]
-            role.scope = r[:scope]
-            role.collection = r[:collection]
+      def get_roles(options = Options::User::GetRoles::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_GET_ROLES, options.parent_span, self, :management) do |obs_handler|
+          resp = @backend.role_get_all(options.timeout, obs_handler)
+          resp.map do |r|
+            RoleAndDescription.new do |role|
+              role.name = r[:name]
+              role.display_name = r[:display_name]
+              role.description = r[:description]
+              role.bucket = r[:bucket]
+              role.scope = r[:scope]
+              role.collection = r[:collection]
+            end
           end
         end
       end
 
       # Changes the password of the currently authenticated user
       #
-      # @param [ChangePasswordOptions] options
+      # @param [Options::User::ChangePassword] options
       #
       # @raise [ArgumentError]
-      def change_password(new_password, options = ChangePasswordOptions.new)
-        @backend.change_password(new_password, options.timeout)
+      def change_password(new_password, options = Options::User::ChangePassword::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_CHANGE_PASSWORD, options.parent_span, self, :management) do |obs_handler|
+          @backend.change_password(new_password, options.timeout, obs_handler)
+        end
       end
 
       # Gets a group
       #
       # @param [String] group_name name of the group to get
+      # @param [Options::User::GetGroup] options
       #
       # @return [Group]
       #
       # @raise [ArgumentError]
       # @raise [Error::GroupNotFound]
-      def get_group(group_name, options = GetGroupOptions.new)
-        resp = @backend.group_get(group_name, options.timeout)
-        extract_group(resp)
+      def get_group(group_name, options = Options::User::GetGroup::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_GET_GROUP, options.parent_span, self, :management) do |obs_handler|
+          resp = @backend.group_get(group_name, options.timeout, obs_handler)
+          extract_group(resp)
+        end
       end
 
       # Gets all groups
       #
-      # @param [GetAllGroupsOptions] options
+      # @param [Options::User::GetAllGroups] options
       #
       # @return [Array<Group>]
-      def get_all_groups(options = GetAllGroupsOptions.new)
-        resp = @backend.group_get_all(options.timeout)
-        resp.map { |entry| extract_group(entry) }
+      def get_all_groups(options = Options::User::GetAllGroups::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_GET_ALL_GROUPS, options.parent_span, self, :management) do |obs_handler|
+          resp = @backend.group_get_all(options.timeout, obs_handler)
+          resp.map { |entry| extract_group(entry) }
+        end
       end
 
       # Creates or updates a group
       #
       # @param [Group] group the new version of the group
-      # @param [UpsertGroupOptions] options
+      # @param [Options::User::UpsertGroup] options
       #
       # @raise [ArgumentError]
       # @raise [Error::GroupNotFound]
-      def upsert_group(group, options = UpsertGroupOptions.new)
-        @backend.group_upsert({
-          name: group.name,
-          description: group.description,
-          ldap_group_reference: group.ldap_group_reference,
-          roles: group.roles.map do |role|
-                   {
-                     name: role.name,
-                     bucket: role.bucket,
-                     scope: role.scope,
-                     collection: role.collection,
-                   }
-                 end,
-        }, options.timeout)
+      def upsert_group(group, options = Options::User::UpsertGroup::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_UPSERT_GROUP, options.parent_span, self, :management) do |obs_handler|
+          @backend.group_upsert({
+            name: group.name,
+            description: group.description,
+            ldap_group_reference: group.ldap_group_reference,
+            roles: group.roles.map do |role|
+              {
+                name: role.name,
+                bucket: role.bucket,
+                scope: role.scope,
+                collection: role.collection,
+              }
+            end,
+          }, options.timeout, obs_handler)
+        end
       end
 
       # Removes a group
       #
       # @param [String] group_name name of the group
-      # @param [DropGroupOptions] options
+      # @param [Options::User::DropGroup] options
       #
       # @raise [Error::GroupNotFound]
-      def drop_group(group_name, options = DropGroupOptions.new)
-        @backend.group_drop(group_name, options.timeout)
-      end
-
-      class GetUserOptions
-        # @return [:local, :external] Name of the user's domain. Defaults to +:local+
-        attr_accessor :domain
-
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [GetUserOptions] self
-        def initialize
-          @domain = :local
-          yield self if block_given?
-        end
-      end
-
-      class GetAllUsersOptions
-        # @return [:local, :external] Name of the user's domain. Defaults to +:local+
-        attr_accessor :domain
-
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [GetAllUsersOptions] self
-        def initialize
-          @domain = :local
-          yield self if block_given?
-        end
-      end
-
-      class UpsertUserOptions
-        # @return [:local, :external] Name of the user's domain. Defaults to +:local+
-        attr_accessor :domain
-
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [UpsertUserOptions] self
-        def initialize
-          @domain = :local
-          yield self if block_given?
+      def drop_group(group_name, options = Options::User::DropGroup::DEFAULT)
+        @observability.record_operation(Observability::OP_UM_DROP_GROUP, options.parent_span, self, :management) do |obs_handler|
+          @backend.group_drop(group_name, options.timeout, obs_handler)
         end
       end
 
-      class DropUserOptions
-        # @return [:local, :external] Name of the user's domain. Defaults to +:local+
-        attr_accessor :domain
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::GetUser} instead
+      GetUserOptions = ::Couchbase::Management::Options::User::GetUser
 
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::GetAllUsers} instead
+      GetAllUsersOptions = ::Couchbase::Management::Options::User::GetAllUsers
 
-        # @yieldparam [DropUserOptions] self
-        def initialize
-          @domain = :local
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::UpsertUser} instead
+      UpsertUserOptions = ::Couchbase::Management::Options::User::UpsertUser
 
-      class ChangePasswordOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::DropUser} instead
+      DropUserOptions = ::Couchbase::Management::Options::User::DropUser
 
-        # @yieldparam [ChangePasswordOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::ChangePassword} instead
+      ChangePasswordOptions = ::Couchbase::Management::Options::User::ChangePassword
 
-      class GetRolesOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::GetRoles} instead
+      GetRolesOptions = ::Couchbase::Management::Options::User::GetRoles
 
-        # @yieldparam [GetRolesOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
-
-      class GetGroupOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::GetGroup} instead
+      GetGroupOptions = ::Couchbase::Management::Options::User::GetGroup
 
-        # @yieldparam [GetGroupOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::GetAllGroups} instead
+      GetAllGroupsOptions = ::Couchbase::Management::Options::User::GetAllGroups
 
-      class GetAllGroupsOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::UpsertGroup} instead
+      UpsertGroupOptions = ::Couchbase::Management::Options::User::UpsertGroup
 
-        # @yieldparam [GetAllGroupsOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
-
-      class UpsertGroupOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [UpsertGroupOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
-
-      class DropGroupOptions
-        # @return [Integer] the time in milliseconds allowed for the operation to complete
-        attr_accessor :timeout
-
-        # @yieldparam [DropGroupOptions] self
-        def initialize
-          yield self if block_given?
-        end
-      end
+      # @api private
+      # @deprecated Use {Couchbase::Management::Options::User::DropGroup} instead
+      DropGroupOptions = ::Couchbase::Management::Options::User::DropGroup
 
       private