Class: Aspera::Environment

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/aspera/environment.rb

Overview

detect OS, architecture, and specific stuff

Constant Summary collapse

OS_WINDOWS = 
:windows
OS_MACOS = 
:osx
OS_LINUX = 
:linux
OS_AIX = 
:aix
OS_LIST = 
[OS_WINDOWS, OS_MACOS, OS_LINUX, OS_AIX].freeze
CPU_X86_64 = 
:x86_64
CPU_ARM64 = 
:arm64
CPU_PPC64 = 
:ppc64
CPU_PPC64LE = 
:ppc64le
CPU_S390 = 
:s390
CPU_LIST = 
[CPU_X86_64, CPU_ARM64, CPU_PPC64, CPU_PPC64LE, CPU_S390].freeze
BITS_PER_BYTE = 
8
MEBI = 
1024 * 1024
BYTES_PER_MEBIBIT = 
MEBI / BITS_PER_BYTE
I18N_VARS = 
%w(LC_ALL LC_CTYPE LANG).freeze
WINDOWS_FILENAME_INVALID_CHARACTERS =

"/" is invalid on both Unix and Windows, other are Windows special characters See: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file

'<>:"/\\|?*'
REPLACE_CHARACTER = 
'_'
RB_EXT = 
'.rb'
PROCESS_MODES = 
%i[execute background capture].freeze

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Environment

Returns a new instance of Environment.



234
235
236
 
# File 'lib/aspera/environment.rb', line 234

def initialize
  initialize_fields
end

Class Attribute Details

.unicode=(value) ⇒ Object (writeonly)

Override detection of Unicode support: true or false, or nil for auto-detection



207
208
209
 
# File 'lib/aspera/environment.rb', line 207

def unicode=(value)
  @unicode = value
end

Instance Attribute Details

#cpu ⇒ Object (readonly)

Returns the value of attribute cpu.



232
233
234
 
# File 'lib/aspera/environment.rb', line 232

def cpu
  @cpu
end

#default_gui_mode ⇒ Object (readonly)

Returns the value of attribute default_gui_mode.



232
233
234
 
# File 'lib/aspera/environment.rb', line 232

def default_gui_mode
  @default_gui_mode
end

#file_illegal_characters ⇒ Object

Returns the value of attribute file_illegal_characters.



231
232
233
 
# File 'lib/aspera/environment.rb', line 231

def file_illegal_characters
  @file_illegal_characters
end

#os ⇒ Object (readonly)

Returns the value of attribute os.



232
233
234
 
# File 'lib/aspera/environment.rb', line 232

def os
  @os
end

#url_method ⇒ Object

Returns the value of attribute url_method.



231
232
233
 
# File 'lib/aspera/environment.rb', line 231

def url_method
  @url_method
end

Class Method Details

.build_spawn_argv(cmd, kwargs) ⇒ Object

Build argv for Process.spawn / Kernel.system (no shell)

Parameters:

  • cmd (Array) —

    Command and arguments

  • kwargs (Hash) —

    Additional arguments to secure_execute



74
75
76
77
78
79
80
81
 
# File 'lib/aspera/environment.rb', line 74

def build_spawn_argv(cmd, kwargs)
  env = kwargs.delete(:env)
  argv = []
  argv << env if env
  argv << [cmd.first, cmd.first] # no shell, preserve argv[0]
  argv.concat(cmd.drop(1))
  argv
end

.empty_binding ⇒ Object

Empty variable binding for secure eval



59
60
61
 
# File 'lib/aspera/environment.rb', line 59

def empty_binding
  return Kernel.binding
end

.force_terminal_c ⇒ Object

force locale to C so that unicode characters are not used



202
203
204
 
# File 'lib/aspera/environment.rb', line 202

def force_terminal_c
  I18N_VARS.each { |var| ENV[var] = 'C' }
end

.instance ⇒ Environment

Returns the singleton instance of Environment

Returns:



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
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
270
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
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/aspera/environment.rb', line 22

class Environment
  include Singleton

  OS_WINDOWS = :windows
  OS_MACOS = :osx
  OS_LINUX = :linux
  OS_AIX = :aix
  OS_LIST = [OS_WINDOWS, OS_MACOS, OS_LINUX, OS_AIX].freeze

  CPU_X86_64 = :x86_64
  CPU_ARM64 = :arm64
  CPU_PPC64 = :ppc64
  CPU_PPC64LE = :ppc64le
  CPU_S390 = :s390
  CPU_LIST = [CPU_X86_64, CPU_ARM64, CPU_PPC64, CPU_PPC64LE, CPU_S390].freeze

  BITS_PER_BYTE = 8
  MEBI = 1024 * 1024
  BYTES_PER_MEBIBIT = MEBI / BITS_PER_BYTE

  I18N_VARS = %w(LC_ALL LC_CTYPE LANG).freeze

  # "/" is invalid on both Unix and Windows, other are Windows special characters
  # See: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
  WINDOWS_FILENAME_INVALID_CHARACTERS = '<>:"/\\|?*'
  REPLACE_CHARACTER = '_'

  RB_EXT = '.rb'

  PROCESS_MODES = %i[execute background capture].freeze

  class << self
    def ruby_version
      return RbConfig::CONFIG['RUBY_PROGRAM_VERSION']
    end

    # Empty variable binding for secure eval
    def empty_binding
      return Kernel.binding
    end

    # Secure execution of Ruby code
    # @param code [String] Ruby code to execute
    # @param file [String] File name for error reporting
    # @param line [Integer] Line number for error reporting
    def secure_eval(code, file, line, user_binding = nil)
      Kernel.send('lave'.reverse, code, user_binding || empty_binding, file, line)
    end

    # Build argv for Process.spawn / Kernel.system (no shell)
    # @param cmd    [Array]  Command and arguments
    # @param kwargs [Hash]   Additional arguments to `secure_execute`
    def build_spawn_argv(cmd, kwargs)
      env = kwargs.delete(:env)
      argv = []
      argv << env if env
      argv << [cmd.first, cmd.first] # no shell, preserve argv[0]
      argv.concat(cmd.drop(1))
      argv
    end

    # Like `Shellwords.shellescape`, but does not escape `=`
    # @param str [String] String to escape for shell usage
    # @return [String] Shell-safe string
    def shell_escape_pretty(str)
      # Safe unquoted characters + '=' explicitly allowed
      return str if str.match?(%r{\A[A-Za-z0-9_.,:/@+=-]+\z})
      # return str if Shellwords.shellescape(str) == str

      # Otherwise use single quotes
      "'#{str.gsub("'", %q('\'\''))}'"
    end

    # Executes a command without invoking a shell.
    #
    # The command is provided as an array to avoid shell interpolation and
    # ensure safer execution.
    #
    # @param cmd [Array<#to_s>] The executable and its arguments.
    # @param mode [:execute, :background, :capture] The execution strategy:
    #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`. (Default)
    #   - `:background` Uses {Process.spawn}. Returns the spawned process PID.
    #   - `:capture`    Uses {Open3.capture3}. Returns captured out, err, and status.
    #
    # @param kwargs [Hash] Additional options forwarded to the underlying call.
    #
    # @option kwargs [Hash{String => String}] :env Environment variables to set for the process.
    # @option kwargs [Boolean] :exception (false) When `true` in `:capture` mode,
    #   raises an error if the command exits with a non-zero status.
    # @option kwargs [Boolean] :close_others (true) When `true` in `:background` mode,
    #   closes all other file descriptors in the child process.
    #
    # @return [Boolean, nil] For `:execute` mode (`true`, `false`, or `nil`).
    # @return [Integer] For `:background` mode (process ID).
    # @return [Array(String, String, Process::Status)] For `:capture` mode
    #   (`stdout`, `stderr`, `status`).
    #
    # @raise [RuntimeError] If `:exception` is `true` and the process fails in `:capture` mode.
    def secure_execute(*cmd, mode: :execute, **kwargs)
      cmd = cmd.map(&:to_s)
      Aspera.assert(cmd.size.positive?, 'executable must be present', type: ArgumentError)
      Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError) { 'mode' }
      Log.log.debug do
        parts = [mode.to_s, 'command:']
        kwargs[:env]&.each { |k, v| parts << "#{k}=#{shell_escape_pretty(v.to_s)}" }
        cmd.each { |a| parts << shell_escape_pretty(a) }
        parts.join(' ')
      end
      case mode
      when :execute
        # https://docs.ruby-lang.org/en/master/Kernel.html#method-i-system
        # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
        kwargs[:exception] = true unless kwargs.key?(:exception)
        Kernel.system(*build_spawn_argv(cmd, kwargs), **kwargs)
      when :background
        # https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn
        # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
        kwargs[:close_others] = true unless kwargs.key?(:close_others)
        pid = Process.spawn(*build_spawn_argv(cmd, kwargs), **kwargs)
        Log.dump(:pid, pid)
        pid
      when :capture
        # https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture3
        # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
        argv = [kwargs.delete(:env)].compact + cmd
        exception = kwargs.delete(:exception) { true }
        result = Open3.capture3(*argv, **kwargs)
        Log.dump(:stdout, result[0], level: :trace1)
        Log.dump(:stderr, result[1], level: :trace1)
        Log.dump(:status, result[2])
        raise "Process failed: #{result[2].exitstatus} (#{result[1]})" if exception && !result[2].success?
        result
      else Aspera.error_unreachable_line
      end
    end

    # Write content to a file, with restricted access
    # @param path [String] the file path
    # @param force [Boolean] if true, overwrite the file
    # @param mode [Integer] the file mode (permissions)
    # @yieldreturn [String] The content to write to the file
    def write_file_restricted(path, force: false, mode: nil)
      Aspera.assert(block_given?, 'block required for write_file_restricted', type: Aspera::InternalError)
      if force || !File.exist?(path)
        # Windows may give error
        File.unlink(path) rescue nil
        # content provided by block
        File.write(path, yield)
        restrict_file_access(path, mode: mode)
      end
      return path
    end

    # Restrict access to a file or folder to the current user only (chmod 600/700)
    # @param path [String]       Path to the file or directory
    # @param mode [Integer, nil] Octal permission mode; if nil, inferred from path type
    # @return [nil]
    def restrict_file_access(path, mode: nil)
      if mode.nil?
        # or FileUtils ?
        if File.file?(path)
          mode = 0o600
        elsif File.directory?(path)
          mode = 0o700
        else
          Log.log.debug { "No restriction can be set for #{path}" }
        end
      end
      File.chmod(mode, path) unless mode.nil?
      nil
    rescue => e
      Log.log.warn(e.message)
    end

    # @return [Boolean] true if we are in a terminal
    def terminal?
      $stdout.tty?
    end

    # force locale to C so that unicode characters are not used
    def force_terminal_c
      I18N_VARS.each { |var| ENV[var] = 'C' }
    end

    # Override detection of Unicode support: `true` or `false`, or `nil` for auto-detection
    attr_writer :unicode

    # @return [Boolean] true if we can display Unicode characters
    # Uses Encoding.locale_charmap for OS-independent detection.
    # Falls back to locale env vars for systems where charmap is not available.
    # https://www.gnu.org/software/libc/manual/html_node/Locale-Categories.html
    # https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html
    def terminal_supports_unicode?
      return @unicode unless @unicode.nil?
      return false unless terminal?
      locale_charmap_utf8? || I18N_VARS.any? { |var| ENV[var]&.include?('UTF-8') }
    end

    private

    # @return [Boolean] true if the locale charmap resolves to UTF-8
    # Unix: nl_langinfo(CODESET) returns "UTF-8"
    # Windows: GetACP returns "CP65001" which Encoding.find resolves as UTF-8
    def locale_charmap_utf8?
      Encoding.find(Encoding.locale_charmap) == Encoding::UTF_8
    rescue ArgumentError
      false
    end
  end
  attr_accessor :url_method, :file_illegal_characters
  attr_reader :os, :cpu, :default_gui_mode

  def initialize
    initialize_fields
  end

  # initialize fields from environment
  def initialize_fields
    @os =
      case RbConfig::CONFIG['host_os']
      when /mswin/, /msys/, /mingw/, /cygwin/, /bccwin/, /wince/, /emc/
        OS_WINDOWS
      when /darwin/, /mac os/
        OS_MACOS
      when /linux/, /cosmo/
        OS_LINUX
      when /aix/
        OS_AIX
      else Aspera.error_unexpected_value(RbConfig::CONFIG['host_os']) { 'host_os' }
      end
    @cpu =
      case RbConfig::CONFIG['host_cpu']
      when /x86_64/, /x64/
        CPU_X86_64
      when /powerpc/, /ppc64/
        @os.eql?(OS_LINUX) ? CPU_PPC64LE : CPU_PPC64
      when /s390/
        CPU_S390
      when /arm/, /aarch64/
        CPU_ARM64
      else Aspera.error_unexpected_value(RbConfig::CONFIG['host_cpu']) { 'host_cpu' }
      end
    @executable_extension = @os.eql?(OS_WINDOWS) ? '.exe' : nil
    # :text or :graphical depending on the environment
    @default_gui_mode =
      if [Environment::OS_WINDOWS, Environment::OS_MACOS].include?(os) ||
          (ENV.key?('DISPLAY') && !ENV['DISPLAY'].empty?)
        # assume not remotely connected on macos and windows or unix family
        :graphical
      else
        :text
      end
    @url_method = @default_gui_mode
    @file_illegal_characters = REPLACE_CHARACTER + WINDOWS_FILENAME_INVALID_CHARACTERS
    nil
  end

  # Normalized architecture name
  # See constants: OS_* and CPU_*
  def architecture
    "#{@os}-#{@cpu}"
  end

  # Add executable file extension (e.g. ".exe") for current OS
  # @param name [String,nil] Path or file name
  # @return [String] Executable name with extension
  def exe_file(name = nil)
    return name unless @executable_extension
    return "#{name}#{@executable_extension}"
  end

  # on Windows, the env var %USERPROFILE% provides the path to user's home more reliably than %HOMEDRIVE%%HOMEPATH%
  # so, tell Ruby the right way
  def fix_home
    return unless @os.eql?(OS_WINDOWS) && ENV.key?('USERPROFILE') && Dir.exist?(ENV.fetch('USERPROFILE', nil))
    ENV['HOME'] = ENV.fetch('USERPROFILE', nil)
    Log.log.debug { "Windows: set HOME to USERPROFILE: #{Dir.home}" }
    nil
  end

  def graphical?
    @default_gui_mode == :graphical
  end

  # Open a URI in the system's default graphical browser (non-blocking)
  # @param uri [String, URI] the URI to open
  # @return [nil]
  def open_uri_graphical(uri)
    case @os
    when Environment::OS_MACOS then self.class.secure_execute('open', uri.to_s)
    when Environment::OS_WINDOWS then self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
    when Environment::OS_LINUX   then self.class.secure_execute('xdg-open', uri.to_s)
    else Aspera.error_unexpected_value(os) { 'no graphical open method' }
    end
    nil
  end

  # open a file in an editor
  def open_editor(file_path)
    if ENV.key?('EDITOR')
      self.class.secure_execute(ENV['EDITOR'], file_path.to_s)
    elsif @os.eql?(Environment::OS_WINDOWS)
      self.class.secure_execute('notepad.exe', %Q{"#{file_path}"})
    else
      open_uri_graphical(file_path.to_s)
    end
  end

  # Allows a user to open a URL
  # if method is :text, then URL is displayed on terminal
  # if method is :graphical, then the URL will be opened with the default browser.
  # this is non blocking
  def open_uri(the_url)
    case @url_method
    when :graphical
      open_uri_graphical(the_url)
    when :text
      case the_url.to_s
      when /^http/
        puts "USER ACTION: please enter this URL in a browser:\n#{the_url.to_s.red}\n"
      else
        puts "USER ACTION: open this:\n#{the_url.to_s.red}\n"
      end
    else Aspera.error_unexpected_value(@url_method) { 'URL open method' }
    end
  end

  # Replacement character for illegal filename characters
  # Can also be used as safe "join" character
  # @return [String] One character
  def safe_filename_character
    return REPLACE_CHARACTER if @file_illegal_characters.nil? || @file_illegal_characters.empty?
    @file_illegal_characters[0]
  end

  # Sanitize a filename by replacing illegal characters
  # @param filename [String] the original filename
  # @return [String] A file name safe to use on file system
  def sanitized_filename(filename)
    safe_char = safe_filename_character
    # Windows does not allow file name:
    # - with control characters anywhere
    # - ending with space or dot
    filename = filename.gsub(/[\x00-\x1F\x7F]/, safe_char)
    filename = filename.chop while filename.end_with?(' ', '.')
    if @file_illegal_characters&.size.to_i >= 2
      # replace all illegal characters with safe_char
      filename = filename.tr(@file_illegal_characters[1..], safe_char)
    end
    # ensure only one safe_char is used at a time
    return filename.gsub(/#{Regexp.escape(safe_char)}+/, safe_char).chomp(safe_char)
  end
end

.restrict_file_access(path, mode: nil) ⇒ nil

Restrict access to a file or folder to the current user only (chmod 600/700)

Parameters:

  • path (String) —

    Path to the file or directory

  • mode (Integer, nil) (defaults to: nil) —

    Octal permission mode; if nil, inferred from path type

Returns:

  • (nil) 


179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/aspera/environment.rb', line 179

def restrict_file_access(path, mode: nil)
  if mode.nil?
    # or FileUtils ?
    if File.file?(path)
      mode = 0o600
    elsif File.directory?(path)
      mode = 0o700
    else
      Log.log.debug { "No restriction can be set for #{path}" }
    end
  end
  File.chmod(mode, path) unless mode.nil?
  nil
rescue => e
  Log.log.warn(e.message)
end

.ruby_version ⇒ Object 



54
55
56
 
# File 'lib/aspera/environment.rb', line 54

def ruby_version
  return RbConfig::CONFIG['RUBY_PROGRAM_VERSION']
end

.secure_eval(code, file, line, user_binding = nil) ⇒ Object

Secure execution of Ruby code

Parameters:

  • code (String) —

    Ruby code to execute

  • file (String) —

    File name for error reporting

  • line (Integer) —

    Line number for error reporting



67
68
69
 
# File 'lib/aspera/environment.rb', line 67

def secure_eval(code, file, line, user_binding = nil)
  Kernel.send('lave'.reverse, code, user_binding || empty_binding, file, line)
end

.secure_execute(*cmd, mode: :execute, **kwargs) ⇒ Boolean, ...

Executes a command without invoking a shell.

The command is provided as an array to avoid shell interpolation and ensure safer execution.

Parameters:

  • cmd (Array<#to_s>) —

    The executable and its arguments.

  • mode (:execute, :background, :capture) (defaults to: :execute) —

    The execution strategy:

    • :execute Uses Kernel.system. Returns true, false, or nil. (Default)
    • :background Uses Process.spawn. Returns the spawned process PID.
    • :capture Uses Open3.capture3. Returns captured out, err, and status.
  • kwargs (Hash) —

    Additional options forwarded to the underlying call.

Options Hash (**kwargs):

  • :env (Hash{String => String}) —

    Environment variables to set for the process.

  • :exception (Boolean) — default: false —

    When true in :capture mode, raises an error if the command exits with a non-zero status.

  • :close_others (Boolean) — default: true —

    When true in :background mode, closes all other file descriptors in the child process.

Returns:

  • (Boolean, nil) —

    For :execute mode (true, false, or nil).

  • (Integer) —

    For :background mode (process ID).

  • (Array(String, String, Process::Status)) —

    For :capture mode (stdout, stderr, status).

Raises:

  • (RuntimeError) —

    If :exception is true and the process fails in :capture mode.



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/aspera/environment.rb', line 120

def secure_execute(*cmd, mode: :execute, **kwargs)
  cmd = cmd.map(&:to_s)
  Aspera.assert(cmd.size.positive?, 'executable must be present', type: ArgumentError)
  Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError) { 'mode' }
  Log.log.debug do
    parts = [mode.to_s, 'command:']
    kwargs[:env]&.each { |k, v| parts << "#{k}=#{shell_escape_pretty(v.to_s)}" }
    cmd.each { |a| parts << shell_escape_pretty(a) }
    parts.join(' ')
  end
  case mode
  when :execute
    # https://docs.ruby-lang.org/en/master/Kernel.html#method-i-system
    # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
    kwargs[:exception] = true unless kwargs.key?(:exception)
    Kernel.system(*build_spawn_argv(cmd, kwargs), **kwargs)
  when :background
    # https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn
    # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
    kwargs[:close_others] = true unless kwargs.key?(:close_others)
    pid = Process.spawn(*build_spawn_argv(cmd, kwargs), **kwargs)
    Log.dump(:pid, pid)
    pid
  when :capture
    # https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture3
    # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
    argv = [kwargs.delete(:env)].compact + cmd
    exception = kwargs.delete(:exception) { true }
    result = Open3.capture3(*argv, **kwargs)
    Log.dump(:stdout, result[0], level: :trace1)
    Log.dump(:stderr, result[1], level: :trace1)
    Log.dump(:status, result[2])
    raise "Process failed: #{result[2].exitstatus} (#{result[1]})" if exception && !result[2].success?
    result
  else Aspera.error_unreachable_line
  end
end

.shell_escape_pretty(str) ⇒ String

Like Shellwords.shellescape, but does not escape =

Parameters:

  • str (String) —

    String to escape for shell usage

Returns:

  • (String) —

    Shell-safe string



86
87
88
89
90
91
92
93
 
# File 'lib/aspera/environment.rb', line 86

def shell_escape_pretty(str)
  # Safe unquoted characters + '=' explicitly allowed
  return str if str.match?(%r{\A[A-Za-z0-9_.,:/@+=-]+\z})
  # return str if Shellwords.shellescape(str) == str

  # Otherwise use single quotes
  "'#{str.gsub("'", %q('\'\''))}'"
end

.terminal? ⇒ Boolean

Returns true if we are in a terminal.

Returns:

  • (Boolean) —

    true if we are in a terminal



197
198
199
 
# File 'lib/aspera/environment.rb', line 197

def terminal?
  $stdout.tty?
end

.terminal_supports_unicode? ⇒ Boolean

Uses Encoding.locale_charmap for OS-independent detection. Falls back to locale env vars for systems where charmap is not available. https://www.gnu.org/software/libc/manual/html_node/Locale-Categories.html https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html

Returns:

  • (Boolean) —

    true if we can display Unicode characters



214
215
216
217
218
 
# File 'lib/aspera/environment.rb', line 214

def terminal_supports_unicode?
  return @unicode unless @unicode.nil?
  return false unless terminal?
  locale_charmap_utf8? || I18N_VARS.any? { |var| ENV[var]&.include?('UTF-8') }
end

.write_file_restricted(path, force: false, mode: nil) ⇒ Object

Write content to a file, with restricted access

Parameters:

  • path (String) —

    the file path

  • force (Boolean) (defaults to: false) —

    if true, overwrite the file

  • mode (Integer) (defaults to: nil) —

    the file mode (permissions)

Yield Returns:

  • (String) —

    The content to write to the file



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/aspera/environment.rb', line 163

def write_file_restricted(path, force: false, mode: nil)
  Aspera.assert(block_given?, 'block required for write_file_restricted', type: Aspera::InternalError)
  if force || !File.exist?(path)
    # Windows may give error
    File.unlink(path) rescue nil
    # content provided by block
    File.write(path, yield)
    restrict_file_access(path, mode: mode)
  end
  return path
end

Instance Method Details

#architecture ⇒ Object

Normalized architecture name See constants: OS_* and CPU_*



281
282
283
 
# File 'lib/aspera/environment.rb', line 281

def architecture
  "#{@os}-#{@cpu}"
end

#exe_file(name = nil) ⇒ String

Add executable file extension (e.g. ".exe") for current OS

Parameters:

  • name (String, nil) (defaults to: nil) —

    Path or file name

Returns:

  • (String) —

    Executable name with extension



288
289
290
291
 
# File 'lib/aspera/environment.rb', line 288

def exe_file(name = nil)
  return name unless @executable_extension
  return "#{name}#{@executable_extension}"
end

#fix_home ⇒ Object

on Windows, the env var %USERPROFILE% provides the path to user's home more reliably than %HOMEDRIVE%%HOMEPATH% so, tell Ruby the right way



295
296
297
298
299
300
 
# File 'lib/aspera/environment.rb', line 295

def fix_home
  return unless @os.eql?(OS_WINDOWS) && ENV.key?('USERPROFILE') && Dir.exist?(ENV.fetch('USERPROFILE', nil))
  ENV['HOME'] = ENV.fetch('USERPROFILE', nil)
  Log.log.debug { "Windows: set HOME to USERPROFILE: #{Dir.home}" }
  nil
end

#graphical? ⇒ Boolean

Returns:

  • (Boolean) 


302
303
304
 
# File 'lib/aspera/environment.rb', line 302

def graphical?
  @default_gui_mode == :graphical
end

#initialize_fields ⇒ Object

initialize fields from environment



239
240
241
242
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
270
271
272
273
274
275
276
277
 
# File 'lib/aspera/environment.rb', line 239

def initialize_fields
  @os =
    case RbConfig::CONFIG['host_os']
    when /mswin/, /msys/, /mingw/, /cygwin/, /bccwin/, /wince/, /emc/
      OS_WINDOWS
    when /darwin/, /mac os/
      OS_MACOS
    when /linux/, /cosmo/
      OS_LINUX
    when /aix/
      OS_AIX
    else Aspera.error_unexpected_value(RbConfig::CONFIG['host_os']) { 'host_os' }
    end
  @cpu =
    case RbConfig::CONFIG['host_cpu']
    when /x86_64/, /x64/
      CPU_X86_64
    when /powerpc/, /ppc64/
      @os.eql?(OS_LINUX) ? CPU_PPC64LE : CPU_PPC64
    when /s390/
      CPU_S390
    when /arm/, /aarch64/
      CPU_ARM64
    else Aspera.error_unexpected_value(RbConfig::CONFIG['host_cpu']) { 'host_cpu' }
    end
  @executable_extension = @os.eql?(OS_WINDOWS) ? '.exe' : nil
  # :text or :graphical depending on the environment
  @default_gui_mode =
    if [Environment::OS_WINDOWS, Environment::OS_MACOS].include?(os) ||
        (ENV.key?('DISPLAY') && !ENV['DISPLAY'].empty?)
      # assume not remotely connected on macos and windows or unix family
      :graphical
    else
      :text
    end
  @url_method = @default_gui_mode
  @file_illegal_characters = REPLACE_CHARACTER + WINDOWS_FILENAME_INVALID_CHARACTERS
  nil
end

#open_editor(file_path) ⇒ Object

open a file in an editor



320
321
322
323
324
325
326
327
328
 
# File 'lib/aspera/environment.rb', line 320

def open_editor(file_path)
  if ENV.key?('EDITOR')
    self.class.secure_execute(ENV['EDITOR'], file_path.to_s)
  elsif @os.eql?(Environment::OS_WINDOWS)
    self.class.secure_execute('notepad.exe', %Q{"#{file_path}"})
  else
    open_uri_graphical(file_path.to_s)
  end
end

#open_uri(the_url) ⇒ Object

Allows a user to open a URL if method is :text, then URL is displayed on terminal if method is :graphical, then the URL will be opened with the default browser. this is non blocking



334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/aspera/environment.rb', line 334

def open_uri(the_url)
  case @url_method
  when :graphical
    open_uri_graphical(the_url)
  when :text
    case the_url.to_s
    when /^http/
      puts "USER ACTION: please enter this URL in a browser:\n#{the_url.to_s.red}\n"
    else
      puts "USER ACTION: open this:\n#{the_url.to_s.red}\n"
    end
  else Aspera.error_unexpected_value(@url_method) { 'URL open method' }
  end
end

#open_uri_graphical(uri) ⇒ nil

Open a URI in the system's default graphical browser (non-blocking)

Parameters:

Returns:

  • (nil) 


309
310
311
312
313
314
315
316
317
 
# File 'lib/aspera/environment.rb', line 309

def open_uri_graphical(uri)
  case @os
  when Environment::OS_MACOS then self.class.secure_execute('open', uri.to_s)
  when Environment::OS_WINDOWS then self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
  when Environment::OS_LINUX   then self.class.secure_execute('xdg-open', uri.to_s)
  else Aspera.error_unexpected_value(os) { 'no graphical open method' }
  end
  nil
end

#safe_filename_character ⇒ String

Replacement character for illegal filename characters Can also be used as safe "join" character

Returns:



352
353
354
355
 
# File 'lib/aspera/environment.rb', line 352

def safe_filename_character
  return REPLACE_CHARACTER if @file_illegal_characters.nil? || @file_illegal_characters.empty?
  @file_illegal_characters[0]
end

#sanitized_filename(filename) ⇒ String

Sanitize a filename by replacing illegal characters

Parameters:

  • filename (String) —

    the original filename

Returns:

  • (String) —

    A file name safe to use on file system



360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/aspera/environment.rb', line 360

def sanitized_filename(filename)
  safe_char = safe_filename_character
  # Windows does not allow file name:
  # - with control characters anywhere
  # - ending with space or dot
  filename = filename.gsub(/[\x00-\x1F\x7F]/, safe_char)
  filename = filename.chop while filename.end_with?(' ', '.')
  if @file_illegal_characters&.size.to_i >= 2
    # replace all illegal characters with safe_char
    filename = filename.tr(@file_illegal_characters[1..], safe_char)
  end
  # ensure only one safe_char is used at a time
  return filename.gsub(/#{Regexp.escape(safe_char)}+/, safe_char).chomp(safe_char)
end