Class: Puppet::Module Private

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

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Support for modules

Defined Under Namespace

Classes: Error, FaultyMetadata, IncompatibleModule, IncompatiblePlatform, InvalidFilePattern, InvalidName, MissingMetadata, MissingModule, Plan, Task, UnsupportedPlatform

Constant Summary collapse

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Logging

#clear_deprecation_warnings, #debug, #deprecation_warning, #format_backtrace, #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.



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/puppet/module.rb', line 77

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

  assert_validity
  load_metadata

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

Instance Attribute Details

#author ⇒ Object

Returns the value of attribute author.



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

def author
  @author
end

#dependencies ⇒ Object

Returns the value of attribute dependencies.



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

def dependencies
  @dependencies
end

#description ⇒ Object

Returns the value of attribute description.



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

def description
  @description
end

#environment ⇒ Object

Returns the value of attribute environment.



71
72
73
 
# File 'lib/puppet/module.rb', line 71

def environment
  @environment
end

#forge_name ⇒ Object

Returns the value of attribute forge_name.



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

def forge_name
  @forge_name
end

#license ⇒ Object

Returns the value of attribute license.



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

def license
  @license
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



71
72
73
 
# File 'lib/puppet/module.rb', line 71

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



71
72
73
 
# File 'lib/puppet/module.rb', line 71

def name
  @name
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



71
72
73
 
# File 'lib/puppet/module.rb', line 71

def path
  @path
end

#project_page ⇒ Object

Returns the value of attribute project_page.



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

def project_page
  @project_page
end

#source ⇒ Object

Returns the value of attribute source.



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

def source
  @source
end

#summary ⇒ Object

Returns the value of attribute summary.



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

def summary
  @summary
end

#version ⇒ Object

Returns the value of attribute version.



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

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



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

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:

  • (Boolean) 


44
45
46
47
48
49
50
 
# File 'lib/puppet/module.rb', line 44

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

  is_module_directory_name?(name)
end

.is_module_directory_name?(name) ⇒ Boolean

Returns:

  • (Boolean) 


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

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_]*$/

  false
end

.is_module_namespaced_name?(name) ⇒ Boolean

Returns:

  • (Boolean) 


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

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_]*$/

  false
end

.parse_range(range) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



67
68
69
 
# File 'lib/puppet/module.rb', line 67

def self.parse_range(range)
  SemanticPuppet::VersionRange.parse(range)
end

Instance Method Details

#==(other) ⇒ Object 



451
452
453
454
455
456
 
# File 'lib/puppet/module.rb', line 451

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

#all_manifests ⇒ Object 



289
290
291
292
293
 
# File 'lib/puppet/module.rb', line 289

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

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

#dependencies_as_modules ⇒ Object 



357
358
359
360
361
362
363
364
365
366
 
# File 'lib/puppet/module.rb', line 357

def dependencies_as_modules
  dependent_modules = []
  dependencies and dependencies.each do |dep|
    _, 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:

  • (Boolean) 


342
343
344
 
# File 'lib/puppet/module.rb', line 342

def has_external_facts?
  File.directory?(plugin_fact_directory)
end

#has_hiera_conf? ⇒ Boolean

Returns:

  • (Boolean) 


310
311
312
 
# File 'lib/puppet/module.rb', line 310

def has_hiera_conf?
  hiera_conf_file.nil? ? false : Puppet::FileSystem.exist?(hiera_conf_file)
end

#has_metadata? ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
105
106
107
 
# File 'lib/puppet/module.rb', line 102

def has_metadata?
  load_metadata
  @metadata.is_a?(Hash) && !@metadata.empty?
rescue Puppet::Module::MissingMetadata
  false
end

#has_translations?(locale) ⇒ Boolean

Returns true if the module has translation files for the given locale.

Parameters:

  • locale (String) —

    the two-letter language code to check for translations

Returns:

  • (Boolean) —

    true if the module has a directory for the locale, false false otherwise



338
339
340
 
# File 'lib/puppet/module.rb', line 338

def has_translations?(locale)
  Puppet::FileSystem.exist?(File.join(locale_directory, locale))
end

#hiera_conf_file ⇒ Object 



303
304
305
306
307
308
 
# File 'lib/puppet/module.rb', line 303

def hiera_conf_file
  unless defined?(@hiera_conf_file)
    @hiera_conf_file = path.nil? ? nil : File.join(path, Puppet::Pops::Lookup::HieraConfig::CONFIG_FILE_NAME)
  end
  @hiera_conf_file
end

#license_file ⇒ Object 



213
214
215
216
217
218
219
 
# File 'lib/puppet/module.rb', line 213

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 



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/puppet/module.rb', line 243

def load_metadata
  return if instance_variable_defined?(:@metadata)

  @metadata = data = read_metadata
  return if data.empty?

  @forge_name = data['name'].tr('-', '/') if data['name']

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

    if attr == :dependencies
      unless value.is_a?(Array)
        raise MissingMetadata, "The value for the key dependencies in the file metadata.json of the module #{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

#locale_directory ⇒ String

Returns:

  • (String) 


328
329
330
 
# File 'lib/puppet/module.rb', line 328

def locale_directory
  subpath("locales")
end

#match_manifests(rest) ⇒ Object

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



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/puppet/module.rb', line 273

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 



295
296
297
298
299
300
301
 
# File 'lib/puppet/module.rb', line 295

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 



314
315
316
 
# File 'lib/puppet/module.rb', line 314

def modulepath
  File.dirname(path) if path
end

#plan_file(name) ⇒ Object

This is a re-implementation of the Filetypes singular type method (e.g. ‘manifest(’my/manifest.pp’)‘. We don’t implement the full filetype “API” for plans.



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/puppet/module.rb', line 197

def plan_file(name)
  # If 'file' is nil then they're asking for the base path.
  # This is used for things like fileserving.
  if name
    full_path = File.join(plans_directory, name)
  else
    full_path = plans_directory
  end

  if Puppet::FileSystem.exist?(full_path)
    full_path
  else
    nil
  end
end

#plans ⇒ Object 



184
185
186
187
188
189
190
191
192
 
# File 'lib/puppet/module.rb', line 184

def plans
  return @plans if instance_variable_defined?(:@plans)

  if Puppet::FileSystem.exist?(plans_directory)
    @plans = Puppet::Module::Plan.plans_in_module(self)
  else
    @plans = []
  end
end

#plans_directory ⇒ Object 



180
181
182
 
# File 'lib/puppet/module.rb', line 180

def plans_directory
  subpath("plans")
end

#plugin_directory ⇒ Object

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



319
320
321
 
# File 'lib/puppet/module.rb', line 319

def plugin_directory
  subpath("lib")
end

#plugin_fact_directory ⇒ Object 



323
324
325
 
# File 'lib/puppet/module.rb', line 323

def plugin_fact_directory
  subpath("facts.d")
end

#puppetversion ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



89
90
91
 
# File 'lib/puppet/module.rb', line 89

def puppetversion
  nil
end

#puppetversion=(something) ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



94
95
 
# File 'lib/puppet/module.rb', line 94

def puppetversion=(something)
end

#read_metadata ⇒ Object 



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/puppet/module.rb', line 221

def read_metadata
  md_file = metadata_file
  return {} if md_file.nil?

  content = File.read(md_file, :encoding => 'utf-8')
  content.empty? ? {} : Puppet::Util::Json.load(content)
rescue Errno::ENOENT
  {}
rescue Puppet::Util::Json::ParseError => e
  # TRANSLATORS 'metadata.json' is a specific file name and should not be translated.
  msg = _("%{name} has an invalid and unparsable metadata.json file. The parse error: %{error}") % { name: name, error: e.message }
  case Puppet[:strict]
  when :off
    Puppet.debug(msg)
  when :warning
    Puppet.warning(msg)
  when :error
    raise FaultyMetadata, msg
  end
  {}
end

#required_by ⇒ Object 



368
369
370
 
# File 'lib/puppet/module.rb', line 368

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

#supports(name, version = nil) ⇒ Object 



346
347
348
349
 
# File 'lib/puppet/module.rb', line 346

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

#task_file(name) ⇒ Object

This is a re-implementation of the Filetypes singular type method (e.g. ‘manifest(’my/manifest.pp’)‘. We don’t implement the full filetype “API” for tasks since tasks don’t map 1:1 onto files.



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/puppet/module.rb', line 164

def task_file(name)
  # If 'file' is nil then they're asking for the base path.
  # This is used for things like fileserving.
  if name
    full_path = File.join(tasks_directory, name)
  else
    full_path = tasks_directory
  end

  if Puppet::FileSystem.exist?(full_path)
    full_path
  else
    nil
  end
end

#tasks ⇒ Object 



151
152
153
154
155
156
157
158
159
 
# File 'lib/puppet/module.rb', line 151

def tasks
  return @tasks if instance_variable_defined?(:@tasks)

  if Puppet::FileSystem.exist?(tasks_directory)
    @tasks = Puppet::Module::Task.tasks_in_module(self)
  else
    @tasks = []
  end
end

#tasks_directory ⇒ Object 



147
148
149
 
# File 'lib/puppet/module.rb', line 147

def tasks_directory
  subpath("tasks")
end

#to_s ⇒ Object 



351
352
353
354
355
 
# File 'lib/puppet/module.rb', line 351

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'
    }
  }
]



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/puppet/module.rb', line 398

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 => forge_name,
        :version => 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

    next unless version_string

    begin
      required_version_semver_range = self.class.parse_range(version_string)
      actual_version_semver = SemanticPuppet::Version.parse(dep_mod.version)
    rescue ArgumentError
      error_details[:reason] = :non_semantic_version
      unmet_dependencies << error_details
      next
    end

    next if required_version_semver_range.include? actual_version_semver

    error_details[:reason] = :version_mismatch
    unmet_dependencies << error_details
    next
  end

  unmet_dependencies
end

#validate_puppet_version ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



98
99
100
 
# File 'lib/puppet/module.rb', line 98

def validate_puppet_version
  nil
end