Module: Kamal::Utils

Extended by:
Utils
Included in:
Utils
Defined in:
lib/kamal/utils.rb

Defined Under Namespace

Classes: Sensitive

Constant Summary collapse

DOLLAR_SIGN_WITHOUT_SHELL_EXPANSION_REGEX = 
/\$(?!{[^\}]*\})/

Instance Method Summary collapse

Instance Method Details

#argumentize(argument, attributes, sensitive: false) ⇒ Object

Return a list of escaped shell arguments using the same named argument against the passed attributes (hash or array).



7
8
9
10
11
12
13
14
15
16
17
 
# File 'lib/kamal/utils.rb', line 7

def argumentize(argument, attributes, sensitive: false)
  Array(attributes).flat_map do |key, value|
    if value.present?
      attr = "#{key}=#{escape_shell_value(value)}"
      attr = self.sensitive(attr, redaction: "#{key}=[REDACTED]") if sensitive
      [ argument, attr ]
    else
      [ argument, key ]
    end
  end
end

#escape_shell_value(value) ⇒ Object

Escape a value to make it safe for shell use.



56
57
58
59
60
 
# File 'lib/kamal/utils.rb', line 56

def escape_shell_value(value)
  value.to_s.dump
    .gsub(/`/, '\\\\`')
    .gsub(DOLLAR_SIGN_WITHOUT_SHELL_EXPANSION_REGEX, '\$')
end

#filter_specific_items(filters, items) ⇒ Object

Apply a list of host or role filters, including wildcard matches



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/kamal/utils.rb', line 63

def filter_specific_items(filters, items)
  matches = []

  Array(filters).select do |filter|
    matches += Array(items).select do |item|
      # Only allow * for a wildcard
      # items are roles or hosts
      File.fnmatch(filter, item.to_s, File::FNM_EXTGLOB)
    end
  end

  matches.uniq
end

#flatten_args(args) ⇒ Object

Flattens a one-to-many structure into an array of two-element arrays each containing a key-value pair



31
32
33
 
# File 'lib/kamal/utils.rb', line 31

def flatten_args(args)
  args.flat_map { |key, value| value.try(:map) { |entry| [ key, entry ] } || [ [ key, value ] ] }
end

#optionize(args, with: nil) ⇒ Object

Returns a list of shell-dashed option arguments. If the value is true, it’s treated like a value-less option.



20
21
22
23
24
25
26
27
28
 
# File 'lib/kamal/utils.rb', line 20

def optionize(args, with: nil)
  options = if with
    flatten_args(args).collect { |(key, value)| value == true ? "--#{key}" : "--#{key}#{with}#{escape_shell_value(value)}" }
  else
    flatten_args(args).collect { |(key, value)| [ "--#{key}", value == true ? nil : escape_shell_value(value) ] }
  end

  options.flatten.compact
end

#redacted(value) ⇒ Object 



42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/kamal/utils.rb', line 42

def redacted(value)
  case
  when value.respond_to?(:redaction)
    value.redaction
  when value.respond_to?(:transform_values)
    value.transform_values { |value| redacted value }
  when value.respond_to?(:map)
    value.map { |element| redacted element }
  else
    value
  end
end

#sensitive ⇒ Object

Marks sensitive values for redaction in logs and human-visible output. Pass ‘redaction:` to change the default `“[REDACTED]”` redaction, e.g. `sensitive “#arg=#secret”, redaction: “#arg=xxxx”



38
39
40
 
# File 'lib/kamal/utils.rb', line 38

def sensitive(...)
  Kamal::Utils::Sensitive.new(...)
end

#stable_sort!(elements, &block) ⇒ Object 



77
78
79
 
# File 'lib/kamal/utils.rb', line 77

def stable_sort!(elements, &block)
  elements.sort_by!.with_index { |element, index| [ block.call(element), index ] }
end