windoo 1.0.1

data/lib/windoo/mixins/api_collection.rb

@@ -0,0 +1,408 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+# main module
+module Windoo
+
+  module Mixins
+
+    # This should be included into The TitleEditor and
+    # Admin classes that represent API collections in their
+    # respective servers.
+    #
+    # It defines core methods for dealing with such collections.
+    module APICollection
+
+      # when this module is included, also extend our Class Methods
+      def self.included(includer)
+        Windoo.verbose_include includer, self
+        includer.extend(ClassMethods)
+      end
+
+      # REQUIRED ITEMS WHEN MIXING IN
+      ###################################
+      ###################################
+      # Classes mixing in this module must define these things:
+
+      # Constant RSRC_PATH
+      ######
+      # The path from which to GET, PUT, or DELETE
+      # lists or instances of this class. e.g 'patches'
+      # or 'softwaretitles'
+
+      # Constant CONTAINER_CLASS
+      ######
+      # Except for softwaretitles, the POST/create path for
+      # all objects is under the path of their container object.
+      #
+      # e.g. to create a patch for a softwaretitle, the path is:
+      #     .../softwaretitles/{id}/patches
+      #
+      # and to create a killapp in a patch, it is:
+      #     .../patches/{id}/killapps
+      #
+      # This constant allows this class to calculate
+      # the POST path from its container's path, and gives
+      # access to other data from the container class.
+
+      # instance method #handle_create_response(post_response, container_id: nil)
+      ######
+      #
+      # This method is called after a new object is created on the server,
+      # and the data from the POST response is passed in.
+      # This method should update the attributes with any new
+      # data from the result, such as modification dates, ids, etc.
+      #
+      # It must return the primary identifier of the new object
+
+      # instance method #handle_update_response(put_response)
+      ######
+      #
+      # This method is called after an object is updated on the server,
+      # and the data from the PUT response is passed in.
+      # This method should update the attributes with any new
+      # data from the result, such as modification dates, etc.
+      #
+      # It must return the primary identifier of the updated object
+
+      ###################################
+      ###################################
+
+      # Class Methods
+      #####################################
+      module ClassMethods
+
+        ####################
+        def self.extended(extender)
+          Windoo.verbose_extend extender, self
+        end
+
+        # Make a new instance on the server.
+        #
+        # The attributes marked as required must be supplied
+        # in the keyword args. Others may be included, or
+        # may be added later. To see the required args, use
+        # the .required_attributes class method
+        #
+        # @param container [Object] All objects other than SoftwareTitles
+        #   are contained within other objects, and created via methods
+        #   within those container objects. They will pass 'self'
+        #
+        # @param init_data [Hasn] The attributes of the new item as keyword
+        #   arguments. Some may be required.
+        #
+        # @return [Object] A new instance of the class, already saved
+        #   to the server.
+        #
+        ####################
+        def create(container: nil, cnx: Windoo.cnx, **init_data)
+          container = Windoo::Validate.container_for_new_object(
+            new_object_class: self,
+            container: container
+          )
+
+          unless (required_attributes & init_data.keys) == required_attributes
+            raise ArgumentError,
+                  "Missing one or more required attributes for #{self}: #{required_attributes.join ', '}"
+          end
+
+          # validate all init values
+          json_attributes.each do |attr_name, attr_def|
+            init_val = init_data[attr_name]
+            if attr_def[:required]
+              Windoo::Validate.not_nil(
+                init_val,
+                msg: "Value for #{attr_name}: must be provided"
+              )
+            end
+
+            init_data[attr_name] = Windoo::Validate.json_attr init_val, attr_def: attr_def, attr_name: attr_name
+          end
+          # add the container if applicable
+          init_data[:from_container] = container if container
+
+          # Let other steps in the process know we are being called from #create
+          init_data[:creating] = true
+
+          # Create our instance
+          obj = new(**init_data)
+
+          # create it on the server
+          obj.create_on_server cnx: cnx
+
+          # return it
+          obj
+        end
+
+        # Instantiate from the API directly.
+        # @return [Object]
+        #
+        ####################
+        def fetch(primary_ident, cnx: Windoo.cnx)
+          if primary_ident.is_a? Hash
+            raise 'All API objects other than SoftwareTitle are fetched only by their id number'
+          end
+
+          init_data = cnx.get("#{self::RSRC_PATH}/#{primary_ident}")
+          init_data[:cnx] = cnx
+          init_data[:fetching] = true
+          new(**init_data)
+        end
+
+        # This is used by container classes to instantiate the objects they contain
+        # e.g. when when instantiating a Patch, it needs to instantiate
+        # killApps, components, and capabilites. it will do so with this method
+        #
+        ####################
+        def instantiate_from_container(container:, **init_data)
+          container = Windoo::Validate.container_for_new_object(
+            new_object_class: self,
+            container: container
+          )
+          init_data[:from_container] = container
+          init_data[:cnx] = container.cnx
+          new(**init_data)
+        end
+
+        ####
+        def delete(primary_ident, cnx: Windoo.cnx)
+          if primary_ident.is_a? Hash
+            raise ArgumentError, 'All API objects other than SoftwareTitle are deleted only by their id number'
+          end
+
+          cnx.delete("#{self::RSRC_PATH}/#{primary_ident}")
+        rescue Windoo::NoSuchItemError
+          # wasn't there to begin with
+          nil
+        end
+
+      end # module ClassMethods
+
+      # Constructor
+      ######################
+      def initialize(**init_data)
+        fetching = init_data.delete :fetching
+        @cnx = init_data.delete :cnx
+
+        @container ||= init_data.delete :from_container
+
+        # we save 'creating' in an inst. var so we know to create
+        # rather than update later on when we #save
+        @creating = true if init_data[:creating]
+
+        unless fetching || @container || @creating
+          raise Windoo::UnsupportedError, "#{self.class} can only be instantiated using .fetch or .create, not .new"
+        end
+
+        super
+      end
+
+      # Public Instance Methods
+      ####################
+
+      # @return [APICollection] The object that contains this object, or nil
+      #   if nothing contains this object
+      # def container
+      #   return @container if defined? @container
+
+      #   @container =
+      #     if defined? self.class::CONTAINER_CLASS
+      #       container_id_key = self.class::CONTAINER_CLASS.primary_id_key
+      #       container_id = send container_id_key
+      #       self.class::CONTAINER_CLASS.fetch container_id
+      #     end
+      # end
+
+      # @return [nil, Integer] our primary identifier value, regardless of its
+      #   attribute name. Before creation, this is nil. After deletion, this is -1
+      #
+      ####################
+      def primary_id
+        send self.class.primary_id_key
+      end
+
+      # @return [Boolean] Is this object the same as another, based on their
+      #   primary_id
+      ####################
+      def ==(other)
+        return false unless self.class == other.class
+
+        primary_id == other.primary_id
+      end
+
+      # @return [Integer] our primary identifier value before we were deleted.
+      #   Before deletion, this is nil
+      #
+      ####################
+      def deleted_id
+        @deleted_id
+      end
+
+      # @return [Integer] our primary identifier value before we were deleted.
+      #   Before deletion, this is nil
+      #
+      ####################
+      def deleted_id
+        @deleted_id
+      end
+
+      # @return [Windoo::APICollection] If this object is contained within another,
+      #   then here is the object that contains it
+      ####################
+      def container
+        @container
+      end
+
+      # @return [Windoo::Connection] The server connection for this object
+      ####################
+      def cnx
+        @cnx
+      end
+
+      # @return [Windoo::SoftwareTitle] The SoftwareTitle object that ultimately
+      #   contains this object
+      ####################
+      def softwareTitle
+        return self if is_a? Windoo::SoftwareTitle
+
+        return container if container.is_a? Windoo::SoftwareTitle
+
+        container.softwareTitle
+      end
+
+      # Delete this object
+      #
+      # @return [Integer] The id of the object that was deleted
+      #
+      #############
+      def delete
+        self.class.delete primary_id, cnx: cnx
+        @deleted_id = primary_id
+        instance_variable_set "@#{self.class.primary_id_key}", -1
+        @deleted_id
+      end
+
+      # create a new object on the server from this instance
+      #
+      # @param container_id [Integer, nil] the id of the object that will
+      #   contain the one we are creating. If nil, then we are creating
+      #   a SoftwareTitle.
+      #
+      # @return [Integer] The id of the newly created object
+      #
+      ####################
+      def create_on_server(cnx: Windoo.cnx)
+        unless @creating
+          raise Windoo::UnsupportedError,
+                "Do not call 'create_on_server' directly - use the .create class method."
+        end
+
+        @cnx = cnx
+        rsrc = creation_rsrc
+        resp = cnx.post rsrc, to_json
+
+        update_title_modify_time(resp)
+
+        # the container method woull only return nil for
+        # SoftwareTitle objects
+        container_id = container&.primary_id
+
+        new_id = handle_create_response(resp, container_id: container_id)
+
+        # no longer creating, future saves are updates
+        remove_instance_variable :@creating
+
+        new_id
+      end
+
+      # Update a single attribute on the server with the current value.
+      #
+      # @param attr_name [Symbol] The key from Class.json_attributes for the value
+      #   we want to update
+      #
+      # @param alt_value [Object] A value to send that isn't the actual data for the attribute.
+      #   If provided, the attr_name need not appear as a key in .json_attributes, but
+      #   that name and this value will be sent to the API. See CriteriaManager#update_criterion
+      #   for an example
+      #
+      #
+      # @return [Integer] the id of the updated item.
+      ####################
+      def update_on_server(attr_name, new_value)
+        # This may be nil if given an alt name for an alt value
+        attr_def = self.class.json_attributes[attr_name]
+
+        if attr_def&.dig attr_name, :do_not_send
+          raise Windoo::UnsupportedError, "The value for #{attr_name} cannot be updated directly."
+        end
+
+        # convert the value, if needed, to API format
+        value_to_send =
+          if attr_def&.dig attr_name, :to_api
+            Windoo::Converters.send attr_def[:to_api], new_value.dup
+          else
+            new_value
+          end
+
+        json_to_put = { attr_name => value_to_send }.to_json
+
+        # should use our @cnx...
+        resp = cnx.put "#{self.class::RSRC_PATH}/#{primary_id}", json_to_put
+        update_title_modify_time(resp)
+        handle_update_response(resp)
+      end
+
+      # Remove the cnx  object from
+      # the instance_variables used to create
+      # pretty-print (pp) output.
+      #
+      # @return [Array] the desired instance_variables
+      ####################
+      def pretty_print_instance_variables
+        vars = instance_variables.sort
+        vars.delete :@cnx
+        vars.delete :@container
+        vars
+      end
+
+      # Private Instance Methods
+      ####################
+      private
+
+      # update the timestamp on the title that contains this object
+      ####################
+      def update_title_modify_time(resp)
+        if is_a? Windoo::SoftwareTitle
+          @lastModified = Time.parse(resp[:lastModified])
+        else
+          softwareTitle.update_modification_time
+        end
+      end
+
+      # figure out the resource path to use for POSTing this thing to the server
+      #
+      # @param container_id [Integer, nil] the id of the object that will
+      #   contain the one we are creating. If nil, then we are creating
+      #   a SoftwareTitle.
+      #
+      # @return [String] The resource path for POSTing to the server
+      #
+      ####################
+      def creation_rsrc
+        # if no container id was given, the only thing we can create is
+        # a SoftwareTitle.  Everything else is created via its container.
+        return Windoo::SoftwareTitle::RSRC_PATH unless @container
+
+        "#{self.class::CONTAINER_CLASS::RSRC_PATH}/#{@container.primary_id}/#{self.class::RSRC_PATH}"
+      end
+
+    end # module APICollection
+
+  end # module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/constants.rb

@@ -0,0 +1,43 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # When using included modules to define constants,
+  # the constants have to be defined at the level where they will be
+  # referenced, or else they
+  # aren't available to other broken-out-and-included sub modules
+  #
+  # See https://cultivatehq.com/posts/ruby-constant-resolution/ for
+  # an explanation
+
+  # The minimum Ruby version needed for windoo
+  MINIMUM_RUBY_VERSION = '2.6.3'
+
+  # These are handy for testing values without making new arrays, strings, etc every time.
+  TRUE_FALSE = [true, false].freeze
+
+  # Empty strings are used in various places
+  BLANK = ''
+
+  module Mixins
+
+    # Constants useful throughout Windoo
+    # This should be included into the Jamf module
+    #####################################
+    module Constants
+
+      # when this module is included, also extend our Class Methods
+      def self.included(includer)
+        Windoo.load_msg "--> #{includer} is including Windoo::Constants"
+      end
+
+    end # module constants
+
+  end #  module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/default_connection.rb

@@ -0,0 +1,75 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  module Mixins
+
+    # Module methods and aliases for dealing with the default connection
+    # This is extended into the API module
+    ######################
+    module DefaultConnection
+
+      # When this module is extended into a class
+      def self.extended(extender)
+        Windoo.verbose_extend extender, self
+      end
+
+      # The current default Windoo::Connection instance.
+      #
+      # @return [Windoo::Connection]
+      #
+      def default_connection
+        @default_connection ||= Windoo::Connection.new name: :default
+      end
+      alias cnx default_connection
+
+      # Create a new Connection object and use it as the default for all
+      # future API calls. This will replace the existing default connection with
+      # a totally new one
+      #
+      # @param (See Windoo::Connection#initialize)
+      #
+      # @return [String] the to_s output of the new connection
+      #
+      def connect(url = nil, **params)
+        params[:name] ||= :default
+        @default_connection = Windoo::Connection.new url, **params
+        @default_connection.to_s
+      end
+      alias login connect
+
+      # Use the given Windoo::Connection object as the default connection, replacing
+      # the one that currently exists.
+      #
+      # @param connection [Windoo::Connection] The default Connection to use for future
+      #   API calls
+      #
+      # @return [APIConnection] The connection now being used.
+      #
+      def cnx=(connection)
+        unless connection.is_a? Windoo::Connection
+          raise 'Title Editor connections must be instances of Windoo::Connection'
+        end
+
+        @default_connection = connection
+      end
+
+      # Disconnect the default connection
+      #
+      def disconnect
+        @default_connection.disconnect if @default_connection&.connected?
+      end
+      alias logout disconnect
+
+    end # module DefaultConnection
+
+  end #   module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/immutable.rb

@@ -0,0 +1,34 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# main module
+module Windoo
+
+  module Mixins
+
+    # by default, instances of JSONObject subclasses are mutable
+    # as a whole, even if some of their attributes are not.
+    #
+    # To make them immutable, they should extend this module
+    #    Windoo::Mixins::Immutable,
+    # which overrides the mutable? method
+    module Immutable
+
+      def self.extended(extender)
+        Windoo.verbose_extend extender, self
+      end
+
+      # this class is immutable
+      def mutable?
+        false
+      end
+
+    end # module Immutable
+
+  end # module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/loading.rb

@@ -0,0 +1,38 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  module Mixins
+
+    module Loading
+
+      def self.extended(extender)
+        Windoo.verbose_extend extender, self
+      end
+
+      # Use the load_msg method defined for Zeitwerk
+      def load_msg(msg)
+        WindooZeitwerkConfig.load_msg msg
+      end
+
+      # Mention that a module is being included into something
+      def verbose_include(includer, includee)
+        load_msg "--> #{includer} is including #{includee}"
+      end
+
+      # Mention that a module is being extended into something
+      def verbose_extend(extender, extendee)
+        load_msg "--> #{extender} is extending #{extendee}"
+      end
+
+    end # module Loading
+
+  end #   module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/patch/component.rb

@@ -0,0 +1,102 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  module Mixins
+
+    module Patch
+
+      # An module that manages the Component in a
+      # Patch.
+      #
+      # Even though 'components' is plural, and
+      # they come from the server in an Array, at the moment there
+      # can only be one per Paatch.
+      #
+      # This module hides that confusion and allows you to work with
+      # just one
+      #
+      # If there's already an component, you can access it
+      # from the #component getter, and use that to directly
+      # update its values.
+      #
+      module Component
+
+        # Construcor
+        ######################
+        def initialize(**init_data)
+          super
+          @component =
+            if @init_data[:components]&.first
+              Windoo::Component.instantiate_from_container(
+                container: self,
+                **@init_data[:components].first
+              )
+            end
+        end
+
+        # Public Instance Methods
+        ####################################
+
+        # Add a component to this Patch. After its created,
+        # you can add criteria to it.
+        #
+        # NOTE: There can be only one per v. You will
+        # get an error if one already exists.
+        #
+        # @param name [String] The name of the component. Usually
+        #   the same as the name of the Software Title it is
+        #   associated with
+        #
+        # @param version [String] The version of the componen.
+        #   Usually the same as the version of the Patch if it
+        #   associated with
+        #
+        # @return [Integer] The id of the new Extension Attribute
+        #
+        def add_component(name:, version:)
+          if @component
+            raise Windoo::AlreadyExistsError,
+                  'This Patch already has a Component. Either delete it before creating a new one, or update the existing one.'
+          end
+
+          @component = Windoo::Component.create(
+            container: self,
+            cnx: cnx,
+            name: name,
+            version: version
+          )
+
+          @component.componentId
+        end
+
+        # Delete the component from this Patch
+        #
+        # @return [Integer] The id of the deleted Extension Attribute
+        #
+        def delete_component
+          return unless @component
+
+          deleted_id = @component.delete
+          @component = nil
+
+          # patches without a component are not valid
+          # so must be disabled
+          container.disable
+
+          deleted_id
+        end
+
+      end # module ExtensionAttribute
+
+    end # module SoftwareTitle
+
+  end # module Mixins
+
+end # module Windoo