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).



9
10
11
12
13
14
15
16
17
18
19
20
21
 
# File 'lib/kamal/utils.rb', line 9

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 ]
    elsif value == false
      [ argument, "#{key}=false" ]
    else
      [ argument, key ]
    end
  end
end

#docker_arch ⇒ Object 



95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/kamal/utils.rb', line 95

def docker_arch
  arch = `docker info --format '{{.Architecture}}'`.strip
  case arch
  when /aarch64/
    "arm64"
  when /x86_64/
    "amd64"
  else
    arch
  end
end

#escape_ascii_shell_value(value) ⇒ Object 



66
67
68
69
70
 
# File 'lib/kamal/utils.rb', line 66

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

#escape_shell_value(value) ⇒ Object

Escape a value to make it safe for shell use.



60
61
62
63
64
 
# File 'lib/kamal/utils.rb', line 60

def escape_shell_value(value)
  value.to_s.scan(/[\x00-\x7F]+|[^\x00-\x7F]+/) \
    .map { |part| part.ascii_only? ? escape_ascii_shell_value(part) : part }
    .join
end

#filter_specific_items(filters, items) ⇒ Object

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



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/kamal/utils.rb', line 73

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



35
36
37
 
# File 'lib/kamal/utils.rb', line 35

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

#join_commands(commands) ⇒ Object 



91
92
93
 
# File 'lib/kamal/utils.rb', line 91

def join_commands(commands)
  commands.map(&:strip).join(" ")
end

#older_version?(version, other_version) ⇒ Boolean

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/kamal/utils.rb', line 107

def older_version?(version, other_version)
  Gem::Version.new(version.delete_prefix("v")) < Gem::Version.new(other_version.delete_prefix("v"))
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.



24
25
26
27
28
29
30
31
32
 
# File 'lib/kamal/utils.rb', line 24

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 



46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/kamal/utils.rb', line 46

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”



42
43
44
 
# File 'lib/kamal/utils.rb', line 42

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

#stable_sort!(elements, &block) ⇒ Object 



87
88
89
 
# File 'lib/kamal/utils.rb', line 87

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