Class: Puppet::Module

Inherits:
Object show all
Includes:
Util::Logging
Defined in:
lib/puppet/module.rb

Overview

Support for modules

API:

  • public

Defined Under Namespace

Classes: Error, IncompatibleModule, IncompatiblePlatform, InvalidFilePattern, InvalidName, MissingMetadata, MissingModule, UnsupportedPlatform

Constant Summary collapse

FILETYPES =

API:

  • public

{
  "manifests" => "manifests",
  "files" => "files",
  "templates" => "templates",
  "plugins" => "lib",
  "pluginfacts" => "facts.d",
}

Constants included from Util::Logging

Util::Logging::FILE_AND_LINE, Util::Logging::FILE_NO_LINE, Util::Logging::MM, Util::Logging::NO_FILE_LINE

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Logging

#clear_deprecation_warnings, #debug, #deprecation_warning, #format_exception, #get_deprecation_offender, #log_and_raise, #log_deprecations_to_file, #log_exception, #puppet_deprecation_warning, #send_log, setup_facter_logging!, #warn_once

Constructor Details

#initialize(name, path, environment) ⇒ Module

Returns a new instance of Module.

API:

  • public



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/puppet/module.rb', line 61

def initialize(name, path, environment)
  @name = name
  @path = path
  @environment = environment

  assert_validity

  load_metadata if has_metadata?

  @absolute_path_to_manifests = Puppet::FileSystem::PathPattern.absolute(manifests)
end

Instance Attribute Details

#author ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def author
  @author
end

#dependencies ⇒ Object

API:

  • public



58
59
60
 
# File 'lib/puppet/module.rb', line 58

def dependencies
  @dependencies
end

#description ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def description
  @description
end

#environment ⇒ Object

API:

  • public



55
56
57
 
# File 'lib/puppet/module.rb', line 55

def environment
  @environment
end

#forge_name ⇒ Object

API:

  • public



58
59
60
 
# File 'lib/puppet/module.rb', line 58

def forge_name
  @forge_name
end

#license ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def license
  @license
end

#metadata ⇒ Object (readonly)

API:

  • public



55
56
57
 
# File 'lib/puppet/module.rb', line 55

def metadata
  @metadata
end

#name ⇒ Object (readonly)

API:

  • public



55
56
57
 
# File 'lib/puppet/module.rb', line 55

def name
  @name
end

#path ⇒ Object (readonly)

API:

  • public



55
56
57
 
# File 'lib/puppet/module.rb', line 55

def path
  @path
end

#project_page ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def project_page
  @project_page
end

#source ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def source
  @source
end

#summary ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def summary
  @summary
end

#version ⇒ Object

API:

  • public



59
60
61
 
# File 'lib/puppet/module.rb', line 59

def version
  @version
end

Class Method Details

.find(modname, environment = nil) ⇒ Object

Find and return the module that path belongs to. If path is absolute, or if there is no module whose name is the first component of path, return nil

API:

  • public



29
30
31
32
33
34
 
# File 'lib/puppet/module.rb', line 29

def self.find(modname, environment = nil)
  return nil unless modname
  # Unless a specific environment is given, use the current environment
  env = environment ? Puppet.lookup(:environments).get!(environment) : Puppet.lookup(:current_environment)
  env.module(modname)
end

.is_module_directory?(name, path) ⇒ Boolean

Returns:

API:

  • public



36
37
38
39
40
41
 
# File 'lib/puppet/module.rb', line 36

def self.is_module_directory?(name, path)
  # it must be a directory
  fullpath = File.join(path, name)
  return false unless Puppet::FileSystem.directory?(fullpath)
  return is_module_directory_name?(name)
end

.is_module_directory_name?(name) ⇒ Boolean

Returns:

API:

  • public



43
44
45
46
47
 
# File 'lib/puppet/module.rb', line 43

def self.is_module_directory_name?(name)
  # it must match an installed module name according to forge validator
  return true if name =~ /^[a-z][a-z0-9_]*$/
  return false
end

.is_module_namespaced_name?(name) ⇒ Boolean

Returns:

API:

  • public



49
50
51
52
53
 
# File 'lib/puppet/module.rb', line 49

def self.is_module_namespaced_name?(name)
  # it must match the full module name according to forge validator
  return true if name =~ /^[a-zA-Z0-9]+[-][a-z][a-z0-9_]*$/   
  return false
end

Instance Method Details

#==(other) ⇒ Object

API:

  • public



324
325
326
327
328
329
 
# File 'lib/puppet/module.rb', line 324

def ==(other)
  self.name == other.name &&
  self.version == other.version &&
  self.path == other.path &&
  self.environment == other.environment
end

#all_manifests ⇒ Object

API:

  • public



189
190
191
192
193
 
# File 'lib/puppet/module.rb', line 189

def all_manifests
  return [] unless Puppet::FileSystem.exist?(manifests)

  Dir.glob(File.join(manifests, '**', '*.pp'))
end

#dependencies_as_modules ⇒ Object

API:

  • public



230
231
232
233
234
235
236
237
238
239
 
# File 'lib/puppet/module.rb', line 230

def dependencies_as_modules
  dependent_modules = []
  dependencies and dependencies.each do |dep|
    author, dep_name = dep["name"].split('/')
    found_module = environment.module(dep_name)
    dependent_modules << found_module if found_module
  end

  dependent_modules
end

#has_external_facts? ⇒ Boolean

Returns:

API:

  • public



215
216
217
 
# File 'lib/puppet/module.rb', line 215

def has_external_facts?
  File.directory?(plugin_fact_directory)
end

#has_metadata? ⇒ Boolean

Returns:

API:

  • public



87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/puppet/module.rb', line 87

def has_metadata?
  return false unless metadata_file

  return false unless Puppet::FileSystem.exist?(metadata_file)

  begin
    metadata =  JSON.parse(File.read(metadata_file))
  rescue JSON::JSONError => e
    Puppet.debug("#{name} has an invalid and unparsable metadata.json file.  The parse error: #{e.message}")
    return false
  end

  return metadata.is_a?(Hash) && !metadata.keys.empty?
end

#license_file ⇒ Object

API:

  • public



140
141
142
143
144
145
 
# File 'lib/puppet/module.rb', line 140

def license_file
  return @license_file if defined?(@license_file)

  return @license_file = nil unless path
  @license_file = File.join(path, "License")
end

#load_metadata ⇒ Object

API:

  • public



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/puppet/module.rb', line 147

def load_metadata
  @metadata = data = JSON.parse(File.read(metadata_file))
  @forge_name = data['name'].gsub('-', '/') if data['name']

  [:source, :author, :version, :license, :dependencies].each do |attr|
    unless value = data[attr.to_s]
      raise MissingMetadata, "No #{attr} module metadata provided for #{self.name}"
    end

    if attr == :dependencies
      unless value.is_a?(Array)
        raise MissingMetadata, "The value for the key dependencies in the file metadata.json of the module #{self.name} must be an array, not: '#{value}'"
      end
      value.each do |dep|
        name = dep['name']
        dep['name'] = name.tr('-', '/') unless name.nil?
        dep['version_requirement'] ||= '>= 0.0.0'
      end
    end

    send(attr.to_s + "=", value)
  end
end

#match_manifests(rest) ⇒ Object

Return the list of manifests matching the given glob pattern, defaulting to ‘init.pp’ for empty modules.

API:

  • public



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/puppet/module.rb', line 173

def match_manifests(rest)
  if rest
    wanted_manifests = wanted_manifests_from(rest)
    searched_manifests = wanted_manifests.glob.reject { |f| FileTest.directory?(f) }
  else
    searched_manifests = []
  end

  # (#4220) Always ensure init.pp in case class is defined there.
  init_manifest = manifest("init.pp")
  if !init_manifest.nil? && !searched_manifests.include?(init_manifest)
    searched_manifests.unshift(init_manifest)
  end
  searched_manifests
end

#metadata_file ⇒ Object

API:

  • public



195
196
197
198
199
200
 
# File 'lib/puppet/module.rb', line 195

def metadata_file
  return @metadata_file if defined?(@metadata_file)

  return @metadata_file = nil unless path
  @metadata_file = File.join(path, "metadata.json")
end

#modulepath ⇒ Object

API:

  • public



202
203
204
 
# File 'lib/puppet/module.rb', line 202

def modulepath
  File.dirname(path) if path
end

#plugin_directory ⇒ Object

Find all plugin directories. This is used by the Plugins fileserving mount.

API:

  • public



207
208
209
 
# File 'lib/puppet/module.rb', line 207

def plugin_directory
  subpath("lib")
end

#plugin_fact_directory ⇒ Object

API:

  • public



211
212
213
 
# File 'lib/puppet/module.rb', line 211

def plugin_fact_directory
  subpath("facts.d")
end

#puppetversion ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.

API:

  • public



74
75
76
 
# File 'lib/puppet/module.rb', line 74

def puppetversion
  nil
end

#puppetversion=(something) ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.

API:

  • public



79
80
 
# File 'lib/puppet/module.rb', line 79

def puppetversion=(something)
end

#required_by ⇒ Object

API:

  • public



241
242
243
 
# File 'lib/puppet/module.rb', line 241

def required_by
  environment.module_requirements[self.forge_name] || {}
end

#supports(name, version = nil) ⇒ Object

API:

  • public



219
220
221
222
 
# File 'lib/puppet/module.rb', line 219

def supports(name, version = nil)
  @supports ||= []
  @supports << [name, version]
end

#to_s ⇒ Object

API:

  • public



224
225
226
227
228
 
# File 'lib/puppet/module.rb', line 224

def to_s
  result = "Module #{name}"
  result += "(#{path})" if path
  result
end

#unmet_dependencies ⇒ Object

Identify and mark unmet dependencies. A dependency will be marked unmet for the following reasons:

* not installed and is thus considered missing
* installed and does not meet the version requirements for this module
* installed and doesn't use semantic versioning

Returns a list of hashes representing the details of an unmet dependency.

Example:

[
  {
    :reason => :missing,
    :name   => 'puppetlabs-mysql',
    :version_constraint => 'v0.0.1',
    :mod_details => {
      :installed_version => '0.0.1'
    }
    :parent => {
      :name    => 'puppetlabs-bacula',
      :version => 'v1.0.0'
    }
  }
]

API:

  • public



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/puppet/module.rb', line 271

def unmet_dependencies
  unmet_dependencies = []
  return unmet_dependencies unless dependencies

  dependencies.each do |dependency|
    name = dependency['name']
    version_string = dependency['version_requirement'] || '>= 0.0.0'

    dep_mod = begin
      environment.module_by_forge_name(name)
    rescue
      nil
    end

    error_details = {
      :name => name,
      :version_constraint => version_string.gsub(/^(?=\d)/, "v"),
      :parent => {
        :name => self.forge_name,
        :version => self.version.gsub(/^(?=\d)/, "v")
      },
      :mod_details => {
        :installed_version => dep_mod.nil? ? nil : dep_mod.version
      }
    }

    unless dep_mod
      error_details[:reason] = :missing
      unmet_dependencies << error_details
      next
    end

    if version_string
      begin
        required_version_semver_range = SemVer[version_string]
        actual_version_semver = SemVer.new(dep_mod.version)
      rescue ArgumentError
        error_details[:reason] = :non_semantic_version
        unmet_dependencies << error_details
        next
      end

      unless required_version_semver_range.include? actual_version_semver
        error_details[:reason] = :version_mismatch
        unmet_dependencies << error_details
        next
      end
    end
  end

  unmet_dependencies
end

#validate_puppet_version ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.

API:

  • public



83
84
85
 
# File 'lib/puppet/module.rb', line 83

def validate_puppet_version
  return
end