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 



115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/kamal/utils.rb', line 115

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 



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

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.



80
81
82
83
84
 
# File 'lib/kamal/utils.rb', line 80

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



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

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



55
56
57
 
# File 'lib/kamal/utils.rb', line 55

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

#join_commands(commands) ⇒ Object 



111
112
113
 
# File 'lib/kamal/utils.rb', line 111

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

#older_version?(version, other_version) ⇒ Boolean

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/kamal/utils.rb', line 127

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, escape: true) ⇒ Object

Returns a list of shell-dashed option arguments. If the value is true, it's treated like a value-less option. A Sensitive value stays Sensitive: the rendered option keeps the real value for execution and a redacted form for anything kamal prints - same contract as argumentize's sensitive: kwarg, but decided per value by the caller.



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/kamal/utils.rb', line 27

def optionize(args, with: nil, escape: true)
  options = if with
    flatten_args(args).collect do |(key, value)|
      if value == true
        "--#{key}"
      else
        rendered = "--#{key}#{with}#{escape ? escape_shell_value(value) : value}"
        value.is_a?(Kamal::Utils::Sensitive) ? sensitive(rendered, redaction: "--#{key}#{with}#{value.redaction}") : rendered
      end
    end
  else
    flatten_args(args).collect do |(key, value)|
      rendered = value == true ? nil : escape ? escape_shell_value(value) : value
      rendered = sensitive(rendered, redaction: value.redaction) if value.is_a?(Kamal::Utils::Sensitive)
      [ "--#{key}", rendered ]
    end
  end

  options.flatten.compact
end

#redacted(value) ⇒ Object 



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

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

#seconds_duration(value) ⇒ Object

kamal-proxy takes durations as Go duration strings; deploy.yml takes plain seconds. Zero is a real value (it disables the timeout), so only nil drops out.



50
51
52
 
# File 'lib/kamal/utils.rb', line 50

def seconds_duration(value)
  "#{value}s" if value
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"



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

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

#stable_sort!(elements, &block) ⇒ Object 



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

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