ruby-jss 1.6.0b1 → 2.0.0a10

data/lib/jss/configuration.rb

@@ -1,319 +0,0 @@
-### Copyright 2020 Pixar
-
-###
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###
-###    You may obtain a copy of the Apache License at
-###
-###        http://www.apache.org/licenses/LICENSE-2.0
-###
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-###
-###
-
-###
-module JSS
-
-
-  #####################################
-  ### Module Variables
-  #####################################
-
-  #####################################
-  ### Module Methods
-  #####################################
-
-  #####################################
-  ### Classes
-  #####################################
-
-  ###
-  ### A class for working with pre-defined settings & preferences for the JSS Gem
-  ###
-  ### This is a singleton class, only one instance can exist at a time.
-  ###
-  ### When the JSS module loads, that instance is created and stored in the constant {JSS::CONFIG},
-  ### which can then be used in applications to avoid always having to pass in server names, API user names
-  ### and so on.
-  ###
-  ### When the JSS::Configuration instance is created, the {GLOBAL_CONF} file (/etc/jss_gem.conf) is examined if it exists, and
-  ### the items in it are loaded into the attributes.
-  ###
-  ### Then the user-specific {USER_CONF} file (~/.jss_gem.conf) is examined if it exists, and any attributes defined there will
-  ### override those values from the {GLOBAL_CONF}.
-  ###
-  ### The file format is one attribute per line, thus:
-  ###   attr_name: value
-  ###
-  ### Lines that don't start with a known attribute name followed by a colon are ignored. If an attribute is defined
-  ### more than once, the last one wins.
-  ###
-  ### The known attributes are:
-  ### - api_server_name [String] the hostname of the JSS API server
-  ### - api_server_port [Integer] the port number for the API connection
-  ### - api_ssl_version [String] the SSL version (from the open_ssl module) to use for the connection.
-  ### - api_verify_cert [Boolean] if SSL is used, should the SSL certificate be verified (usually false for a self-signed cert)
-  ### - api_username [String] the JSS username for connecting to the API
-  ### - api_timeout_open [Integer] the number of seconds for the open-connection timeout
-  ### - api_timeout [Integer] the number of seconds for the response timeout
-  ###
-  ### The {APIConnection#connect} method will first use any values given as method arguments. For any not given, it will
-  ### look at the Preferences instance for any values there, and if still none, will use default values or raise an exception.
-  ###
-  ### At any point, the attributes can read or changed using standard Ruby getter/setter methods matching the name of the attribute,
-  ### e.g.
-  ###   JSS::CONFIG.api_server_name  # => 'myjss.mycompany.com'
-  ###   JSS::CONFIG.api_server_name = 'otherjss.mycompany.com'  # sets the api_server_name to a new value
-  ###
-  ###
-  ### The current settings may be saved to the GLOBAL_CONF file, the USER_CONF file, or an arbitrary file using {#save}.
-  ### The argument to {#save} should be either :user, :global, or a String or Pathname file path.
-  ### NOTE: This overwrites any existing file.
-  ###
-  ### To re-load the settings use {#reload}. This clears the current settings, and re-reads both the global and user files.
-  ### If a pathname is provided, e.g.
-  ###   JSS::CONFIG.reload '/path/to/other/file'
-  ### the current settings are cleared and reloaded from that other file.
-  ###
-  ### To view the current settings, use {#print}.
-  ###
-  ### @note Passwords are not saved in prefs files. Your application will have to acquire them using the :prompt or :stdin options to
-  ###   {APIConnection#connect}, or by custom means.
-  ###
-  class Configuration
-    include Singleton
-
-    #####################################
-    ### Class Constants
-    #####################################
-
-    ### The filename for storing the config, globally or user-level.
-    ### The first matching file is used - the array provides
-    ### backward compatibility with earlier versions.
-    ### Saving will always happen to the first filename
-    CONF_FILES = [ "ruby-jss.conf", "jss_gem.conf"]
-
-    ### The Pathname to the machine-wide preferences plist
-    GLOBAL_CONFS =  CONF_FILES.map{|cf| Pathname.new "/etc/#{cf}"}
-
-    ### The Pathname to the user-specific preferences plist
-    USER_CONFS =  CONF_FILES.map{|cf| ENV["HOME"] ? Pathname.new("~/.#{cf}").expand_path : nil }.compact
-
-    ### The attribute keys we maintain, and the type they should be stored as
-    CONF_KEYS = {
-      :api_server_name => :to_s,
-      :api_server_port => :to_i,
-      :api_ssl_version => :to_s,
-      :api_verify_cert => :jss_to_bool,
-      :api_username => :to_s,
-      :api_timeout_open => :to_i,
-      :api_timeout => :to_i,
-      :db_server_name => :to_s,
-      :db_server_port => :to_i,
-      :db_server_socket => :to_s,
-      :db_username => :to_s,
-      :db_name => :to_s,
-      :db_connect_timeout => :to_i,
-      :db_read_timeout => :to_i,
-      :db_write_timeout => :to_i
-    }
-
-    #####################################
-    ### Class Variables
-    #####################################
-
-    #####################################
-    ### Class Methods
-    #####################################
-
-    #####################################
-    ### Attributes
-    #####################################
-
-    # automatically create accessors for all the CONF_KEYS
-    CONF_KEYS.keys.each {|k| attr_accessor k}
-
-
-    #####################################
-    ### Constructor
-    #####################################
-
-    ###
-    ### Initialize!
-    ###
-    def initialize
-
-      read_global
-      read_user
-
-    end
-
-    #####################################
-    ### Public Instance Methods
-    #####################################
-
-    ###
-    ### Clear all values
-    ###
-    ### @return [void]
-    ###
-    def clear_all
-      CONF_KEYS.keys.each {|k| self.send "#{k}=".to_sym, nil}
-    end
-
-    ###
-    ### (Re)read the global prefs, if it exists.
-    ###
-    ### @return [void]
-    ###
-    def read_global
-      GLOBAL_CONFS.each { |gcf|
-        if gcf.file? and gcf.readable?
-          read gcf
-          return
-        end
-      }
-    end
-
-    ###
-    ### (Re)read the user prefs, if it exists.
-    ###
-    ### @return [void]
-    ###
-    def read_user
-      USER_CONFS.each { |ucf|
-        if ucf.file? and ucf.readable?
-          read ucf
-          return
-        end
-      }
-    end
-
-
-    ###
-    ### Clear the settings and reload the prefs files, or another file if provided
-    ###
-    ### @param file[String,Pathname] a non-standard prefs file to load
-    ###
-    ### @return [void]
-    ###
-    def reload(file = nil)
-      clear_all
-      if file
-        read file
-        return true
-      end
-      read_global
-      read_user
-      return true
-    end
-
-
-    ###
-    ### Save the prefs into a file
-    ###
-    ### @param file[Symbol,String,Pathname] either :user, :global, or an arbitrary file to save.
-    ###
-    ### @return [void]
-    ###
-    def save(file)
-      path = case file
-        when :global then GLOBAL_CONFS.first
-        when :user then USER_CONFS.first
-        else Pathname.new(file)
-      end
-
-      raise JSS::MissingDataError, "No HOME environment variable, can't write to user conf file." if path.nil?
-
-      # file already exists? read it in and update the values.
-      if path.readable?
-        data = path.read
-
-        # go thru the known attributes/keys
-        CONF_KEYS.keys.sort.each do |k|
-
-          # if the key exists, update it.
-          if data =~ /^#{k}:/
-            data.sub!(/^#{k}:.*$/, "#{k}: #{self.send k}")
-
-          # if not, add it to the end unless it's nil
-          else
-            data += "\n#{k}: #{self.send k}" unless self.send(k).nil?
-          end # if data =~ /^#{k}:/
-        end #each do |k|
-
-      else # not readable, make a new file
-        data = ""
-        CONF_KEYS.keys.sort.each do |k|
-          data << "#{k}: #{self.send k}\n" unless self.send(k).nil?
-        end
-      end # if path readable
-
-      # make sure we end with a newline, the save it.
-      data << "\n" unless data.end_with?("\n")
-      path.jss_save data
-    end # read file
-
-
-    ###
-    ### Print out the current settings to stdout
-    ###
-    ### @return [void]
-    ###
-    def print
-      CONF_KEYS.keys.sort.each{|k| puts "#{k}: #{self.send k}"}
-    end
-
-    #####################################
-    ### Private Instance Methods
-    #####################################
-    private
-
-    ###
-    ### Read in any prefs file
-    ###
-    ### @param file[String,Pathname] the file to read
-    ###
-    ### @return [void]
-    ###
-    def read(file)
-
-      Pathname.new(file).read.each_line do |line|
-          # skip blank lines and those starting with #
-          next if line =~ /^\s*(#|$)/
-
-          line.strip =~ /^(\w+?):\s*(\S.*)$/
-          next unless $1
-          attr = $1.to_sym
-          setter = "#{attr}=".to_sym
-          value = $2.strip
-
-          if CONF_KEYS.keys.include? attr
-            if value
-              # convert the value to the correct class
-              value = value.send(CONF_KEYS[attr])
-            end
-            self.send(setter, value)
-          end  # if
-        end # do line
-
-    end # read file
-
-  end # class Preferences
-
-  # The single instance of Configuration
-  CONFIG = JSS::Configuration.instance
-
-end # module

data/lib/jss/exceptions.rb

@@ -1,115 +0,0 @@
-### Copyright 2020 Pixar
-
-###
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###
-###    You may obtain a copy of the Apache License at
-###
-###        http://www.apache.org/licenses/LICENSE-2.0
-###
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-###
-###
-
-###
-module JSS
-
-  ### Exceptions
-  #####################################
-
-  ### MissingDataError - raise this error when we
-  ### are missing args, or other simliar stuff.
-  ###
-  class MissingDataError < RuntimeError; end
-
-  ### InvalidDataError - raise this error when
-  ### a data item isn't what we expected.
-  ###
-  class InvalidDataError < RuntimeError; end
-
-  ### InvalidConnectionError - raise this error when we
-  ### don't have a usable connection to a network service, or
-  ### don't have proper authentication/authorization.
-  ###
-  class InvalidConnectionError < RuntimeError; end
-
-  ### NoSuchItemError - raise this error when
-  ### a desired item doesn't exist.
-  ###
-  class NoSuchItemError < RuntimeError; end
-
-  ### AlreadyExistsError - raise this error when
-  ### trying to create something that already exists.
-  ###
-  class AlreadyExistsError < RuntimeError; end
-
-  ### AmbiguousError - raise this error when a search
-  ### term that should find one object finds more.
-  ###
-  class AmbiguousError < RuntimeError; end
-
-  ### FileServiceError - raise this error when
-  ### there's a problem accessing file service on a
-  ### distribution point.
-  ###
-  class FileServiceError < RuntimeError; end
-
-  ### UnmanagedError - raise this when we
-  ### try to do something managerial to
-  ### an unmanaged object
-  ###
-  class UnmanagedError < RuntimeError; end
-
-  ### UnsupportedError - raise this when we
-  ### try to do something not yet supported
-  ###
-  class UnsupportedError < RuntimeError; end
-
-  ### TimeoutError - raise this when we
-  ### try to do and it times out
-  ###
-  class TimeoutError < RuntimeError; end
-
-  ### AuthenticationError - raise this when
-  ### a name/pw are wrong
-  ###
-  class AuthenticationError < RuntimeError; end
-
-  ###
-  class AuthorizationError < RuntimeError ; end
-
-  ### ConflictError - raise this when
-  ### attempts to PUT or PUSH to the API
-  ### result in a 409 Conflict http error.
-  ### See {JSS::APIConnection#raise_conflict_error}
-  ###
-  class ConflictError < RuntimeError; end
-
-  ### BadRequestError - raise this when
-  ### attempts to PUT or PUSH or DELETE to the API
-  ### result in a 400 Bad Request http error.
-  ### See {JSS::APIConnection.raise_bad_request_error}
-  ###
-  class BadRequestError < RuntimeError; end
-
-  ### APIRequestError - raise this when
-  ### attempts API actions generate an error not dealt with
-  ### by ConflictError or BadRequestError
-  ### result in a 400 Bad Request http error.
-  ### See {JSS::APIConnection.raise_api_error}
-  ###
-  class APIRequestError < RuntimeError; end
-
-end # module JSS

data/lib/jss/ruby_extensions/array.rb

@@ -1,52 +0,0 @@
-# Copyright 2020 Pixar
-
-#
-#    Licensed under the Apache License, Version 2.0 (the "Apache License")
-#    with the following modification; you may not use this file except in
-#    compliance with the Apache License and the following modification to it:
-#    Section 6. Trademarks. is deleted and replaced with:
-#
-#    6. Trademarks. This License does not grant permission to use the trade
-#       names, trademarks, service marks, or product names of the Licensor
-#       and its affiliates, except as required to comply with Section 4(c) of
-#       the License and to reproduce the content of the NOTICE file.
-#
-#    You may obtain a copy of the Apache License at
-#
-#        http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the Apache License with the above modification is
-#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-#    KIND, either express or implied. See the Apache License for the specific
-#    language governing permissions and limitations under the Apache License.
-#
-#
-
-#
-class Array
-
-  # A case-insensitive version of #include? for Arrays of Strings.
-  #
-  # @param somestring [String] the String to search for
-  #
-  # @return [Boolean] Does the Array contain the String, ignoring case?
-  #
-  def jss_ci_include_string?(somestring)
-    any? { |s| s.to_s.casecmp(somestring).zero? }
-  end
-
-  # Fetch a string from an Array of Strings case-insensitively,
-  # e.g. my_array.jss_ci_fetch_string('ThRashEer') will return 'thrasher'
-  # or nil if no match
-  #
-  # @param somestring [String] the String to search for
-  #
-  # @return [String, nil] The matching string as it exists in the Array, nil if it doesn't exist
-  #
-  def jss_ci_fetch_string(somestring)
-    idx = index { |s| s.to_s.casecmp(somestring).zero? }
-    idx ? self[idx] : nil
-  end
-
-end # class

data/lib/jss/ruby_extensions/hash.rb

@@ -1,140 +0,0 @@
-# Copyright 2020 Pixar
-
-#
-#    Licensed under the Apache License, Version 2.0 (the "Apache License")
-#    with the following modification; you may not use this file except in
-#    compliance with the Apache License and the following modification to it:
-#    Section 6. Trademarks. is deleted and replaced with:
-#
-#    6. Trademarks. This License does not grant permission to use the trade
-#       names, trademarks, service marks, or product names of the Licensor
-#       and its affiliates, except as required to comply with Section 4(c) of
-#       the License and to reproduce the content of the NOTICE file.
-#
-#    You may obtain a copy of the Apache License at
-#
-#        http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the Apache License with the above modification is
-#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-#    KIND, either express or implied. See the Apache License for the specific
-#    language governing permissions and limitations under the Apache License.
-#
-#
-
-#
-class Hash
-
-  #
-  # Convert Hash values to nil.
-  #
-  # With no block, values equalling the String, or any member of the Array, given
-  # will be converted to nil. Equality is evaluated with == and Array#include?
-  #
-  # With a block, if the result of the block evaluates to true, the value is converted to nil.
-  #
-  # Subhashes are ignored unless recurse is true.
-  #
-  # @param to_nils[String,Array] Hash values equal to (==) these become nil. Defaults to empty string
-  #
-  # @param recurse[Boolean] should sub-Hashes be nillified?
-  #
-  # @yield [value] Hash values for which the block returns true will become nil.
-  #
-  # @return [Hash] the hash with the desired values converted to nil
-  #
-  # @example
-  #   hash = {:foo => '', :bar => {:baz => '' }}
-  #   hash.jss_nillify!  # {:foo => nil, :bar => {:baz => '' }}
-  #
-  #   hash = {:foo => '', :bar => {:baz => '' }}
-  #   hash.jss_nillify! '', :recurse  # {:foo => nil, :bar => {:baz => nil }}
-  #
-  #   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
-  #   hash.jss_nillify! ['', 123], :recurse # {:foo => nil, :bar => {:baz => nil, :bim => "123" }}
-  #
-  #   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
-  #   hash.jss_nillify!(:anything, :recurse){|v| v.to_i == 123 }  # {:foo => nil, :bar => {:baz => '', :bim => nil }}
-  #
-  def jss_nillify!(to_nils = '', recurse = false, &block)
-    nillify_these = [] << to_nils
-    nillify_these.flatten!
-
-    each_pair do |k, v|
-      if v.class == Hash
-        v.jss_nillify!(to_nils, recurse, &block)
-        next
-      end
-      do_it =
-        if block_given?
-          yield v
-        else
-          nillify_these.include? v
-        end
-      self[k] = nil if do_it
-    end # each pair
-  end # def nillify
-
-  # Since a lot of JSON data from the API comes as deeply-nested structures
-  # of Hashes and Arrays, it can be a pain to reference some of the deeper
-  # data inside, and it isn't worth coding them out into instance attributes.
-  #
-  # For example see the 'hardware' subset of a JSS::Computer's API data,
-  # which is stored as a Hash in the {JSS::Computer.hardware} attribute.
-  #
-  # To refer to the percent-full value of one of the machine's drives, you need
-  # to use e.g. this:
-  #
-  #   computer_instance.hardware[:storage].first[:partition][:percentage_full]
-  #
-  # It would be nice to use method-like chains to access that data,
-  # similar to what OpenStruct provides.
-  #
-  # But, there are two problems with just storing #hardware as an OpenStruct:
-  # 1) we'd lose some important Hash methods, like #keys and #values, breaking
-  # backward compatibility. 2) OpenStructs only work on the Hash itself, not
-  # its contents.
-  #
-  # So to get the best of both worlds, we use the RecursiveOpenStruct gem
-  #
-  #   https://github.com/aetherknight/recursive-open-struct
-  #
-  # which subclasses OpenStruct to be recursive.
-  #
-  # And, instead of replacing the Hash, we'll add a RecursiveOpenStruct version
-  # of itself to itself as an attribute.
-  #
-  # Now, we can access the same data using this:
-  #
-  #   computer_instance.hardware.jss_ros.storage.first.partition.percentage_full
-  #
-  # CAVEAT: Treat these as read-only.
-  #
-  # While the Hashes themselves may be mutable, their use in ruby-jss Classes
-  # should usually be considered read-only - neither the Hash, nor the
-  # RecursiveOpenStruct  object created by this method should be changed.
-  # Changes to the Hash or the RecursiveOpenStruct are NOT synced between them,
-  # and ruby-jss won't know to send such changes back to the API when #update
-  # is called.
-  #
-  # This should be fine for the intended uses. Data like Computer#hardware
-  # isn't sent back to the JSS via Computer#update, since it must come
-  # from a 'recon' anyway.
-  #
-  # Data that is sent back to the JSS will have setter methods defined in the
-  # class or a mixin module (e.g. the Locatable module).
-  #
-  # Since the data is functionally read-only, why not use the ImmutableStruct
-  # gem, used elsewhere in ruby-jss?
-  #
-  # Because ImmutableStruct is really for creating fully-fleshed-out read-only
-  # classes, with a known set of attributes rather than just giving us a nicer
-  # way to access Hash data with arbitrary keys.
-  #
-  def jss_recursive_ostruct
-    @jss_ros ||= RecursiveOpenStruct.new(self, recurse_over_arrays: true)
-  end
-  alias jss_ros jss_recursive_ostruct
-
-end # class