aspera-cli 4.29.0 → 4.29.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +2 -1
  3. data/CHANGELOG.md +76 -2
  4. data/README.md +20 -1
  5. data/SECURITY.md +14 -0
  6. data/docs/README.md +277 -38
  7. data/lib/aspera/api/node.rb +9 -2
  8. data/lib/aspera/ascp/installation.rb +26 -4
  9. data/lib/aspera/ascp/log_analyzer/lines.rb +2 -2
  10. data/lib/aspera/ascp/log_analyzer.rb +19 -3
  11. data/lib/aspera/ascp/log_locations.rb +163 -0
  12. data/lib/aspera/cli/ascp_logs_actions.rb +12 -0
  13. data/lib/aspera/cli/bootstrapper.rb +1 -0
  14. data/lib/aspera/cli/command_line.rb +39 -2
  15. data/lib/aspera/cli/command_registry.rb +3 -0
  16. data/lib/aspera/cli/command_spec.rb +13 -0
  17. data/lib/aspera/cli/error.rb +3 -0
  18. data/lib/aspera/cli/extended_value.rb +5 -4
  19. data/lib/aspera/cli/formatter.rb +14 -8
  20. data/lib/aspera/cli/http.rb +26 -1
  21. data/lib/aspera/cli/info.rb +1 -1
  22. data/lib/aspera/cli/mcp/tool.rb +5 -3
  23. data/lib/aspera/cli/option_value.rb +14 -8
  24. data/lib/aspera/cli/options.schema.yaml +156 -19
  25. data/lib/aspera/cli/parser.rb +15 -3
  26. data/lib/aspera/cli/plugins/aoc.rb +4 -2
  27. data/lib/aspera/cli/plugins/ats.rb +1 -1
  28. data/lib/aspera/cli/plugins/base.rb +33 -6
  29. data/lib/aspera/cli/plugins/config.rb +12 -1
  30. data/lib/aspera/cli/plugins/faspex5.rb +3 -1
  31. data/lib/aspera/cli/plugins/mcp.rb +14 -0
  32. data/lib/aspera/cli/plugins/node.rb +8 -8
  33. data/lib/aspera/cli/plugins/oauth.rb +18 -5
  34. data/lib/aspera/cli/plugins/orchestrator.rb +28 -24
  35. data/lib/aspera/cli/plugins/preview.rb +3 -1
  36. data/lib/aspera/cli/plugins/server.rb +3 -3
  37. data/lib/aspera/cli/plugins/shares.rb +1 -2
  38. data/lib/aspera/cli/plugins/transferd.rb +7 -2
  39. data/lib/aspera/cli/poll.rb +236 -0
  40. data/lib/aspera/cli/preset_manager.rb +63 -19
  41. data/lib/aspera/cli/prompt.rb +153 -8
  42. data/lib/aspera/cli/runner.rb +25 -7
  43. data/lib/aspera/cli/security.rb +10 -0
  44. data/lib/aspera/cli/sync_actions.rb +2 -0
  45. data/lib/aspera/cli/transfer_agent.rb +14 -0
  46. data/lib/aspera/cli/transfer_progress.rb +6 -5
  47. data/lib/aspera/cli/version.rb +1 -1
  48. data/lib/aspera/environment.rb +3 -1
  49. data/lib/aspera/id_generator.rb +16 -3
  50. data/lib/aspera/inflate.rb +43 -0
  51. data/lib/aspera/oauth/client/base.rb +38 -8
  52. data/lib/aspera/oauth/client/factory.rb +35 -15
  53. data/lib/aspera/oauth/client/json_credentials.rb +3 -2
  54. data/lib/aspera/oauth/client/shares_web.rb +13 -4
  55. data/lib/aspera/oauth/client/url_json.rb +3 -2
  56. data/lib/aspera/oauth/client/web.rb +2 -2
  57. data/lib/aspera/orchestrator_workflow_checker.rb +10 -1
  58. data/lib/aspera/preview/terminal.rb +8 -2
  59. data/lib/aspera/products/desktop.rb +13 -1
  60. data/lib/aspera/rest/client.rb +23 -5
  61. data/lib/aspera/schema/registry.rb +1 -0
  62. data/lib/aspera/sealed_hash.rb +2 -18
  63. data/lib/aspera/secret/hider.rb +13 -1
  64. data/lib/aspera/secret/store/one_password_cli.rb +13 -11
  65. data/lib/aspera/sync/operations.rb +4 -4
  66. data/lib/aspera/transfer/result.rb +20 -0
  67. data/lib/aspera/transfer/spec.rb +2 -2
  68. data/lib/aspera/{transfer/units.rb → units/decimal.rb} +4 -12
  69. data/lib/aspera/units/duration.rb +109 -0
  70. data/lib/aspera/uri_reader.rb +11 -6
  71. data/lib/aspera/web_auth/reply.html.erb +1 -1
  72. data/llms-install.md +88 -0
  73. data/llms.txt +6 -0
  74. data/skills/ascli/SKILL.md +6 -0
  75. data.tar.gz.sig +0 -0
  76. metadata +7 -3
  77. metadata.gz.sig +0 -0
  78. data/lib/aspera/duration.rb +0 -45
@@ -27,9 +27,13 @@ module Aspera
27
27
  class PresetManager
28
28
  # Reserved keys in the YAML config file
29
29
  module Key
30
+ # Section of the config file itself (holds its version)
30
31
  CONFIG = 'config'
32
+ # Key of the version of the config file, in section CONFIG
31
33
  VERSION = 'version'
34
+ # Section that maps a plugin name to its default preset name
32
35
  DEFAULTS = 'default'
36
+ # Name of the global default preset, when none is declared
33
37
  GLOBAL = 'global_common_defaults'
34
38
  # Prefix for comment/meta keys ignored during preset parsing (e.g. _comment)
35
39
  META_PREFIX = '_'
@@ -37,15 +41,18 @@ module Aspera
37
41
  COMMENT = "#{META_PREFIX}comment".freeze
38
42
  end
39
43
 
44
+ # Preset name given on command line to designate the global default preset
40
45
  GLOBAL_DEFAULT_KEYWORD = 'GLOBAL'
46
+ # Plugin name under which the global default preset is declared in section DEFAULTS
41
47
  CONF_GLOBAL_SYM = :config
42
48
  # Separator for dot-notation digging into presets
43
49
  PRESET_DIG_SEPARATOR = '.'
44
50
 
45
51
  private_constant :PRESET_DIG_SEPARATOR
46
52
 
47
- # @param config_file [String] absolute path to the YAML config file
48
- # @param use_plugin_defaults [Boolean] if false, skip default preset lookup
53
+ # Load the config file (created in memory if it does not exist).
54
+ # @param config_file [String] Absolute path to the YAML config file
55
+ # @param use_plugin_defaults [Boolean] `false`: plugin default presets are not applied (see #plugin_default_name)
49
56
  def initialize(config_file:, use_plugin_defaults: true)
50
57
  @config_file = config_file
51
58
  @use_plugin_defaults = use_plugin_defaults
@@ -61,15 +68,19 @@ module Aspera
61
68
  # File I/O
62
69
  # ------------------------------------------------------------------
63
70
 
64
- # @return [String] SHA256 of current in-memory presets
71
+ # Checksum of the presets in memory, compared to the one of the file to save only when changed.
72
+ # @return [String] SHA256 hex digest of the in-memory presets
65
73
  def checksum
66
74
  Digest::SHA256.hexdigest(JSON.generate(@config_presets))
67
75
  end
68
76
 
69
77
  # Read and validate the YAML config file.
70
- # Sets @config_presets and @checksum_on_disk.
78
+ # Sets @config_presets and @checksum_on_disk, and declares the secrets found in presets to the secret hider.
71
79
  # A file that cannot be read (YAML error, duplicate keys, access) is left untouched: it shall be fixed.
72
80
  # A file with an unexpected structure is renamed for manual conversion, and a new one is created next time.
81
+ # @return [void]
82
+ # @raise [Psych::SyntaxError] YAML syntax error in config file
83
+ # @raise [Cli::Error] Config file cannot be read, or has an unexpected structure
73
84
  def read_config_file
74
85
  Log.log.debug { "config file is: #{@config_file}".red }
75
86
  if File.exist?(@config_file)
@@ -123,7 +134,10 @@ module Aspera
123
134
  # Preset read/write helpers
124
135
  # ------------------------------------------------------------------
125
136
 
126
- # @return [String, nil] name of the default preset for a plugin, or nil
137
+ # Name of the default preset declared for a plugin in the `default` section.
138
+ # @param plugin_name_sym [Symbol] Plugin name (e.g. `:aoc`), or CONF_GLOBAL_SYM for the global default
139
+ # @return [String, nil] Name of the default preset, or `nil` if none, or if plugin defaults are disabled
140
+ # @raise [Cli::Error] The default preset is declared but does not exist, or is not a Hash
127
141
  def plugin_default_name(plugin_name_sym)
128
142
  Aspera.assert(!@config_presets.nil?, 'config_presets shall be defined')
129
143
  return unless @use_plugin_defaults
@@ -146,8 +160,11 @@ module Aspera
146
160
 
147
161
  # Resolve and return a deep-cloned, extended copy of a named preset.
148
162
  # Supports dot-notation (e.g. "outer.inner").
149
- # @param config_name [String]
150
- # @param include_path [Array] guard against include loops
163
+ # Meta keys (prefix `_`) are removed, extended values are evaluated, and a secret read alone is declared to the secret hider.
164
+ # @param config_name [String] Preset name, optionally followed by dot-separated sub keys
165
+ # @param include_path [Array<String>] Names already being resolved, to detect include loops
166
+ # @return [Hash, String, Object] Copy of the preset, or of the selected sub value
167
+ # @raise [Cli::Error] Unknown preset or sub key, or include loop
151
168
  def by_name(config_name, include_path = [])
152
169
  Aspera.assert(!include_path.include?(config_name), type: Cli::Error) { 'loop in include' }
153
170
  include_path = include_path.clone
@@ -173,6 +190,11 @@ module Aspera
173
190
  # Set a single key in a preset hash (creates the preset if absent).
174
191
  # If param_name contains dots, it is treated as a dot-path and deep-merged into the preset.
175
192
  # If param_value is nil, the key is deleted instead.
193
+ # Numeric secrets are converted to String (see .stringify_secrets).
194
+ # @param preset [String] Name of preset
195
+ # @param param_name [String, Symbol] Key name, or dot-path of the key in the preset
196
+ # @param param_value [Object, nil] Value to set, or `nil` to delete the key
197
+ # @return [nil]
176
198
  def set_key(preset, param_name, param_value)
177
199
  Aspera.assert_type(param_name, String, Symbol) { 'parameter' }
178
200
  param_name = param_name.to_s
@@ -216,6 +238,7 @@ module Aspera
216
238
  nil
217
239
  end
218
240
 
241
+ # Name of the global default preset: declared in `default` under `config`, else `global_common_defaults`.
219
242
  # @param create [Boolean] `true`: declare and create the global default preset if needed (to write in it)
220
243
  # @return [String] name of the global default preset
221
244
  def global_default_preset(create: true)
@@ -231,33 +254,46 @@ module Aspera
231
254
  result
232
255
  end
233
256
 
257
+ # @param preset_name [String] Name of preset
234
258
  # @return [Boolean] true if `preset_name` is declared as the global default preset (does not create it)
235
259
  def global_preset?(preset_name)
236
260
  defaults = @config_presets[Key::DEFAULTS]
237
261
  defaults.is_a?(Hash) && defaults[CONF_GLOBAL_SYM.to_s].eql?(preset_name)
238
262
  end
239
263
 
240
- # Set param in the global defaults preset
264
+ # Set a parameter in the global default preset (created if needed).
265
+ # @param key [String, Symbol] Key name, or dot-path of the key
266
+ # @param value [Object, nil] Value to set, or `nil` to delete the key
267
+ # @return [nil]
241
268
  def set_global_default(key, value)
242
269
  set_key(global_default_preset, key, value)
243
270
  end
244
271
 
245
- # Create / overwrite a preset and optionally set it as plugin default.
246
- def defaults_set(plugin_name, preset_name, preset_values, option_default, option_override)
272
+ # Create or overwrite a preset, and optionally set it as default for the plugin (used by the wizard).
273
+ # @param plugin_name_sym [Symbol] Plugin name (e.g. `:aoc`)
274
+ # @param preset_name [String] Name of preset to create
275
+ # @param preset_values [Hash] Content of preset
276
+ # @param option_default [Boolean] `true`: set the preset as default for the plugin
277
+ # @param option_override [Boolean] `true`: replace an existing preset or plugin default
278
+ # @return [Hash] preset_values
279
+ # @raise [Cli::Error] The preset, or the plugin default, already exists, and option_override is `false`
280
+ def defaults_set(plugin_name_sym, preset_name, preset_values, option_default, option_override)
247
281
  @config_presets[Key::DEFAULTS] ||= {}
248
- raise Cli::Error, "A default configuration already exists for plugin '#{plugin_name}' (use wizard key override=yes or default=no)" \
249
- if !option_override && option_default && @config_presets[Key::DEFAULTS].key?(plugin_name)
282
+ raise Cli::Error, "A default configuration already exists for plugin '#{plugin_name_sym}' (use wizard key override=yes or default=no)" \
283
+ if !option_override && option_default && @config_presets[Key::DEFAULTS].key?(plugin_name_sym.to_s)
250
284
  raise Cli::Error, "Preset already exists: #{preset_name} (use wizard key override=yes or provide alternate preset name)" \
251
285
  if !option_override && @config_presets.key?(preset_name)
252
286
  if option_default
253
- Log.log.info("Setting config preset as default for #{plugin_name}")
254
- @config_presets[Key::DEFAULTS][plugin_name.to_s] = preset_name
287
+ Log.log.info("Setting config preset as default for #{plugin_name_sym}")
288
+ @config_presets[Key::DEFAULTS][plugin_name_sym.to_s] = preset_name
255
289
  end
256
290
  @config_presets[preset_name] = preset_values
257
291
  end
258
292
 
259
- # Find the first preset whose url+username match
260
- # @return [Hash, nil]
293
+ # Find the first preset whose url and username match (URLs compared without trailing `/` and default port 443).
294
+ # @param url [String] URL of server
295
+ # @param username [String] User name
296
+ # @return [Hash, nil] Copy of the preset, or `nil` if none matches
261
297
  def lookup_preset(url:, username:)
262
298
  url = canonical_url(url)
263
299
  Log.log.debug { "Lookup preset for #{username}@#{url}" }
@@ -274,11 +310,14 @@ module Aspera
274
310
  # ------------------------------------------------------------------
275
311
 
276
312
  class << self
313
+ # Deep copy of a value (containers included).
314
+ # @param val [Object] Value to copy
315
+ # @return [Object] Copy of val
277
316
  def deep_clone(val)
278
317
  Marshal.load(Marshal.dump(val))
279
318
  end
280
319
 
281
- # Recursively merge src into dst in place (dst wins on scalar conflicts).
320
+ # Recursively merge src into dst in place (src wins on scalar conflicts).
282
321
  # @param dst [Hash] destination (modified in place)
283
322
  # @param src [Hash] source
284
323
  # @return [Hash] dst
@@ -310,12 +349,16 @@ module Aspera
310
349
 
311
350
  private
312
351
 
313
- # Normalize a URL for comparison
352
+ # Normalize a URL for comparison: no trailing `/`, no default HTTPS port.
353
+ # @param url [String] URL
354
+ # @return [String] Normalized URL
314
355
  def canonical_url(url)
315
356
  url.chomp('/').sub(%r{^(https://[^/]+):443$}, '\1')
316
357
  end
317
358
 
318
- # Structural validation + compatibility fixes on @config_presets
359
+ # Structural validation and compatibility fixes on @config_presets, stamped with the current version.
360
+ # @return [void]
361
+ # @raise [Cli::Error, StandardError] Unexpected structure
319
362
  def validate_config_presets!
320
363
  Log.dump(:available_presets, @config_presets, level: :trace1)
321
364
  Aspera.assert_type(@config_presets, Hash) { 'config file YAML' }
@@ -333,6 +376,7 @@ module Aspera
333
376
 
334
377
  # Migrates deprecated vault options in presets to the new format (stores and default)
335
378
  # and saves a backup of the original config file.
379
+ # @return [void]
336
380
  def migrate_vault_configs!
337
381
  migrated = false
338
382
  @config_presets.each_value do |preset|
@@ -4,7 +4,12 @@
4
4
  # SPDX-License-Identifier: Apache-2.0
5
5
 
6
6
  require_relative '../assert'
7
+ require_relative '../environment'
8
+ require_relative '../rainbow'
7
9
  require 'io/console'
10
+ require 'unicode/display_width'
11
+
12
+ using Rainbow
8
13
 
9
14
  module Aspera
10
15
  module Cli
@@ -14,15 +19,23 @@ module Aspera
14
19
 
15
20
  # Prompt user for console input
16
21
  # The prompt is displayed on `stderr`, like for sensitive input, so that `stdout` contains only results.
17
- # @param prompt [String] prompt string to display
18
- # @param sensitive [Boolean] whether to hide typed input
22
+ # @param prompt [String] prompt string to display
23
+ # @param sensitive [Boolean] whether to hide typed input
24
+ # @param validate [Proc, nil] Called with the input: raises `ParameterError` (with the reason) if the input is not valid. Its result is not used.
25
+ # On a terminal, hidden input shows whether it is valid, and if not, the error is displayed and the input is asked again.
19
26
  # @return [String] user input stripped of trailing newline
20
- def prompt_user_input(prompt, sensitive: false)
21
- return $stdin.getpass("#{prompt}> ") if sensitive && $stdin.tty?
22
- $stderr.print("#{prompt}> ")
23
- line = $stdin.gets
24
- Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
25
- line.chomp
27
+ def prompt_user_input(prompt, sensitive: false, validate: nil)
28
+ loop do
29
+ line = read_input(prompt, sensitive, validate)
30
+ begin
31
+ validate&.call(line)
32
+ return line
33
+ rescue ParameterError => e
34
+ # not a terminal: nobody to ask again
35
+ raise unless $stdin.tty?
36
+ $stderr.puts("#{e.message}. Try again, or Ctrl-C to stop.".red) # rubocop:disable Style/StderrPuts
37
+ end
38
+ end
26
39
  end
27
40
 
28
41
  # Prompt user for input in a list of symbols
@@ -36,6 +49,138 @@ module Aspera
36
49
  $stderr.puts("No such #{prompt}: #{input}, select one of: #{sym_list.join(', ')}") # rubocop:disable Style/StderrPuts
37
50
  end
38
51
  end
52
+
53
+ private
54
+
55
+ # Characters that erase the last one
56
+ ERASE_CHARS = ["\u007f", "\b"].freeze
57
+
58
+ # Mark of an input checked with `validate`, if valid (`true`) or not: Unicode character, ASCII equivalent, color
59
+ CHECK_MARKS = {
60
+ true => {unicode: '✓', ascii: 'valid', color: :green},
61
+ false => {unicode: '✗', ascii: 'invalid', color: :red}
62
+ }.freeze
63
+
64
+ # Mark shown instead of a hidden input
65
+ Mark = Data.define(:text, :color) do
66
+ # @return [String] Text to display, colored if `color` is set (and colors are enabled)
67
+ def to_s = color.nil? ? text : text.color(color)
68
+
69
+ # @return [String] Characters that erase the mark, by its width on the terminal
70
+ def erase = "\b \b" * Unicode::DisplayWidth.of(text)
71
+ end
72
+ private_constant :ERASE_CHARS, :CHECK_MARKS, :Mark
73
+
74
+ # @param prompt [String] prompt string to display
75
+ # @param sensitive [Boolean] whether to hide typed input
76
+ # @param validate [Proc, nil] Checks the input, for the mark of hidden input
77
+ # @return [String] user input stripped of trailing newline
78
+ def read_input(prompt, sensitive, validate)
79
+ $stderr.print("#{prompt}> ")
80
+ if sensitive && $stdin.tty?
81
+ line = Environment.instance.hidden_silent ? silent_input : masked_input(validate)
82
+ return line unless line.nil?
83
+ end
84
+ read_line
85
+ end
86
+
87
+ # @return [String] Line read from standard input, without trailing newline
88
+ def read_line
89
+ line = $stdin.gets
90
+ Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
91
+ line.chomp
92
+ end
93
+
94
+ # Read a line from the terminal without echoing it, and without any feedback (option `ui.hidden_silent`)
95
+ # @return [String, nil] user input, or `nil` if the terminal cannot disable echo (input not read)
96
+ def silent_input
97
+ line = $stdin.noecho(&:gets)
98
+ $stderr.print("\n")
99
+ Aspera.assert_type(line, String) { 'Unexpected end of standard input' }
100
+ line.chomp
101
+ rescue Errno::ENODEV, Errno::ENOTTY
102
+ nil
103
+ end
104
+
105
+ # Read a line from the terminal without echoing it, but show a mark instead, without revealing the length of the input:
106
+ # a key while the input is empty (waiting for input), then an ellipsis (the paste worked),
107
+ # or, if the input is checked (`validate`), a check mark if it is valid, else a cross.
108
+ # `terminal_supports_unicode?` checks `stdout`, but the mark is on `stderr`: use the locale only.
109
+ # @param validate [Proc, nil] Checks the input
110
+ # @return [String, nil] user input, or `nil` if the terminal has no raw mode (input not read)
111
+ def masked_input(validate)
112
+ unicode = Environment.unicode_environment?
113
+ line = +''
114
+ mark_of = ->(text) { input_mark(text, validate, unicode) }
115
+ shown = mark_of.call(line)
116
+ $stderr.print(shown)
117
+ begin
118
+ $stdin.raw { |tty| read_masked(tty, line, shown, &mark_of) }
119
+ rescue Errno::ENODEV, Errno::ENOTTY
120
+ # e.g. a pseudo terminal without raw mode: erase the mark, the caller reads a line (echoed)
121
+ $stderr.print(shown.erase)
122
+ return
123
+ end
124
+ line
125
+ end
126
+
127
+ # @param line [String] Input
128
+ # @param validate [Proc, nil] Checks the input
129
+ # @param unicode [Boolean] `true` if Unicode is supported
130
+ # @return [Mark] Mark of the input
131
+ def input_mark(line, validate, unicode)
132
+ return Mark.new(Environment.char('🔑', unicode: unicode), nil) if line.empty?
133
+ return Mark.new(Environment.char('…', unicode: unicode), nil) if validate.nil?
134
+ check = CHECK_MARKS[valid?(line, validate)]
135
+ Mark.new(check[unicode ? :unicode : :ascii], check[:color])
136
+ end
137
+
138
+ # @return [Boolean] `true` if `validate` accepts the input
139
+ def valid?(line, validate)
140
+ validate.call(line)
141
+ true
142
+ rescue ParameterError
143
+ false
144
+ end
145
+
146
+ # Read characters until end of line, and update the mark when the input changes
147
+ # @param tty [IO] Terminal in raw mode
148
+ # @param line [String] Input, filled
149
+ # @param shown [Mark] Mark displayed
150
+ # @yieldparam text [String] Input
151
+ # @yieldreturn [Mark] Mark of the input
152
+ # @return [nil]
153
+ def read_masked(tty, line, shown)
154
+ loop do
155
+ before = line.dup
156
+ char = tty.getc
157
+ case char
158
+ when nil, "\r", "\n" then break
159
+ when "\u0003" then raise Interrupt
160
+ # end of input: Ctrl-D (Unix), Ctrl-Z (Windows)
161
+ when "\u0004", "\u001a"
162
+ break unless line.empty?
163
+ raise Aspera::Error, 'Unexpected end of standard input'
164
+ when *ERASE_CHARS then line.chop!
165
+ # Ctrl-W: erase the last word (and spaces after it), like the terminal does
166
+ when "\u0017" then line.sub!(/\S*\s*\z/, '')
167
+ # Ctrl-U: erase all, e.g. to paste again
168
+ when "\u0015" then line.clear
169
+ else
170
+ # ignore other control characters (and escape sequences start)
171
+ line << char unless char.ord < 32
172
+ end
173
+ next if line.eql?(before)
174
+ mark = yield(line)
175
+ next if mark.eql?(shown)
176
+ $stderr.print(shown.erase, mark)
177
+ shown = mark
178
+ end
179
+ nil
180
+ ensure
181
+ # raw mode: no output processing, a line feed alone does not go back to the first column
182
+ $stderr.print("\r\n")
183
+ end
39
184
  end
40
185
  end
41
186
  end
@@ -22,7 +22,7 @@ require_relative 'info'
22
22
  require_relative 'hints'
23
23
  require_relative 'result'
24
24
  require_relative '../transfer/result'
25
- require_relative '../duration'
25
+ require_relative '../units/duration'
26
26
  require_relative '../secret/hider'
27
27
  require_relative '../log'
28
28
  require_relative '../assert'
@@ -52,6 +52,9 @@ module Aspera
52
52
  raise transfer_result.exception
53
53
  when Transfer::Result::Success
54
54
  return Result::Nothing.new
55
+ when Transfer::Result::DryRun
56
+ # Secrets are hidden by the formatter, as in any result
57
+ return Result::SingleObject.new(transfer_result.transfer_spec)
55
58
  else
56
59
  raise "Unexpected transfer result type: #{transfer_result.class}"
57
60
  end
@@ -83,6 +86,8 @@ module Aspera
83
86
  item[STATUS_FIELD] = 'success'
84
87
  when Transfer::Result::Async
85
88
  item[STATUS_FIELD] = "async:#{tr.job_id}"
89
+ when Transfer::Result::DryRun
90
+ item[STATUS_FIELD] = 'dry_run'
86
91
  else
87
92
  item[STATUS_FIELD] = tr.to_s
88
93
  end
@@ -96,8 +101,8 @@ module Aspera
96
101
  # @param argv [Array<String>] command line arguments
97
102
  # @return [nil]
98
103
  def initialize(argv)
104
+ # Dumped (trace2) with secrets hidden by `CommandLine`
99
105
  @argv = argv
100
- Log.dump(:argv, @argv, level: :trace2)
101
106
  @option_help = false
102
107
  @option_show_config = false
103
108
  @context = Context.new
@@ -184,6 +189,7 @@ module Aspera
184
189
  rescue Cli::MissingArgument => e; exception_info = {e: e, t: 'Missing', exit: ExitCode::USAGE}
185
190
  rescue Cli::BadIdentifier, EntityNotFound => e; exception_info = {e: e, t: 'Identifier', exit: ExitCode::NOT_FOUND}
186
191
  rescue Cli::SchemaRequest => e; exception_info = {e: e, t: 'Schema', exit: ExitCode::SUCCESS}
192
+ rescue Cli::PollConditionNotMet => e; exception_info = {e: e, t: 'Poll', exit: ExitCode::ERROR}
187
193
  rescue Cli::Error => e; exception_info = {e: e, t: 'Tool', usage: true, exit: ExitCode::ERROR}
188
194
  rescue Transfer::Error => e; exception_info = {e: e, t: 'Transfer', exit: ExitCode::TRANSFER}
189
195
  rescue Rest::CallError => e; exception_info = {e: e, t: 'Rest', exit: ExitCode.for_call_error(e)}
@@ -195,6 +201,7 @@ module Aspera
195
201
  unless exception_info.nil?
196
202
  Log.log.warn(exception_info[:e].message) if Log.instance.logger_type.eql?(:syslog) && exception_info[:security]
197
203
  Log.log.error { "#{exception_info[:t]}: #{exception_info[:e].message}" } unless exception_info[:e].is_a?(Cli::SchemaRequest)
204
+ Log.log.info { "Location: #{plugin_location(exception_info[:e])}" } if exception_info[:debug] && plugin_location(exception_info[:e])
198
205
  Log.log.debug { (['Backtrace:'] + exception_info[:e].backtrace).join("\n") } if exception_info[:debug]
199
206
  @context.formatter.display_message(:error, 'Use option -h to get help.') if exception_info[:usage]
200
207
  Hints.hint_for(exception_info[:e], @context.formatter)
@@ -204,8 +211,9 @@ module Aspera
204
211
  end
205
212
  end
206
213
  # 2- processing of unprocessed arguments (skip when help was displayed: sub-commands are not consumed)
214
+ # With `show_config`, the command is not executed: its arguments are not consumed, but unknown options are reported
207
215
  unless @option_help
208
- @context.options&.final_errors(after_error: !exception_info.nil?)&.each do |msg|
216
+ @context.options&.final_errors(after_error: !exception_info.nil? || @option_show_config)&.each do |msg|
209
217
  Log.log.error { "Argument: #{msg}" }
210
218
  exception_info = {e: Exception.new(msg), t: 'UnusedArg', exit: ExitCode::USAGE} if exception_info.nil?
211
219
  end
@@ -241,7 +249,7 @@ module Aspera
241
249
  Result::Text.new(usage_text(plugin: plugin))
242
250
  end
243
251
 
244
- # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `web_auth`, `command`
252
+ # `on_set` callback of the `ui` option (dot-notation sub-properties): `mode`, `web_auth`, `hidden_silent`, `command`
245
253
  # A plain value is the `mode`. Values are validated against schema `UiOptions`.
246
254
  # @param value [Hash] sub-properties to set
247
255
  def option_ui=(value)
@@ -259,9 +267,11 @@ module Aspera
259
267
  when :web_auth
260
268
  Aspera.assert_values(v.to_s, %w[port paste], type: BadArgument) { 'ui.web_auth' }
261
269
  Environment.instance.web_auth = v.to_sym
270
+ when :hidden_silent
271
+ Environment.instance.hidden_silent = BoolValue.true?(Parser.get_from_list(v.to_s, 'ui hidden_silent', BoolValue::ALL))
262
272
  when :command
263
273
  Environment.instance.browser_command = v.nil? || v.empty? ? nil : v.map(&:to_s)
264
- else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, web_auth, command)' }
274
+ else Aspera.error_unexpected_value(k, type: BadArgument) { 'ui sub-option (mode, web_auth, hidden_silent, command)' }
265
275
  end
266
276
  end
267
277
  end
@@ -295,7 +305,7 @@ module Aspera
295
305
  case v
296
306
  when nil, false then nil
297
307
  when Numeric then v
298
- else Duration.to_unit(v, 's')
308
+ else Units::Duration.new(v).to_unit('s')
299
309
  end
300
310
  else Aspera.error_unexpected_value(k, type: BadArgument) { 'temp sub-option (folder, clean, expiry)' }
301
311
  end
@@ -306,6 +316,14 @@ module Aspera
306
316
 
307
317
  private
308
318
 
319
+ # Location of an unexpected error in the code of a plugin (built-in or from option `plugin_folder`)
320
+ # @param error [Exception] Error
321
+ # @return [String, nil] First line of the backtrace in a plugin folder, e.g. `<FOLDER>/my_plugin.rb:12:in 'action_list'`, `nil` if none
322
+ def plugin_location(error)
323
+ folders = Plugins::Factory.instance.lookup_folders.map { |folder| File.join(folder, '') }
324
+ error.backtrace&.find { |line| folders.any? { |folder| line.start_with?(folder) } }
325
+ end
326
+
309
327
  # Build the usage/help text.
310
328
  #
311
329
  # - No plugin: global options + list of top-level plugins
@@ -527,7 +545,7 @@ module Aspera
527
545
  @context.options.declare(:show_config, description: 'Display parameters used for the provided action', allowed: Type::NONE) { @option_show_config = true }
528
546
  @context.options.declare(:version, description: 'Display version', allowed: Type::NONE, short: 'v') { @context.formatter.display_message(:data, Cli::VERSION); ::Process.exit(0) } # rubocop:disable Style/Semicolon
529
547
  @context.options.declare(
530
- :ui, description: 'User interface (dot-notation: mode, web_auth, command)',
548
+ :ui, description: 'User interface (dot-notation: mode, web_auth, hidden_silent, command)',
531
549
  allowed: [Hash, String], shorthand: 'mode', schema: Schema::Registry::UI_OPTIONS,
532
550
  on_set: method(:option_ui=)
533
551
  )
@@ -22,10 +22,12 @@ module Aspera
22
22
  # Security levels, from least to most restrictive
23
23
  LEVELS = %i[low medium high].freeze
24
24
  # Extended-value handlers restricted by security level, with the levels that allow them
25
+ # `zlib`: a small value can decompress to gigabytes (decompression bomb), a limit on its size would not limit the number of values
25
26
  EXTENDED_VALUE_LEVELS = {
26
27
  ruby: %i[low],
27
28
  uri: %i[low],
28
29
  env: %i[low],
30
+ zlib: %i[low],
29
31
  file: %i[low medium]
30
32
  }.freeze
31
33
  # Levels that allow processing a secret (e.g. by an extended value): the result could reveal it, as only declared values are hidden
@@ -158,6 +160,14 @@ module Aspera
158
160
  end
159
161
  end
160
162
 
163
+ # Read a local file chosen by the caller, e.g. `@file:`, or a command that reads a file to display something about it.
164
+ # Not for a file that a command sends (e.g. upload, import of a workflow): not restricted, as transfers.
165
+ # @param path [String] Path of a file to read
166
+ # Other arguments are those of `File.read`, e.g. `binmode: true` for bytes
167
+ # @return [String] Content of the file
168
+ # @raise [BadArgument] If reading the file is refused at current level
169
+ def read_file(path, ...) = File.read(readable_path(path), ...)
170
+
161
171
  # Writing a file where the client chooses (e.g. downloaded file) could replace a file that is used later (e.g. plugin, shell startup file).
162
172
  # At level `medium` and `high`, files can be written only in `writable_paths` (none by default): the real path of the folder is checked,
163
173
  # so that neither `..` nor a symbolic link leads outside of them.
@@ -171,6 +171,8 @@ module Aspera
171
171
  # @param sync_info [Hash] extra sync configuration (may be empty)
172
172
  # @param block [Proc, nil] block to generate transfer spec; receives (direction, local_dir, remote_dir)
173
173
  def run_sync_transfer(direction, path:, sync_info: {}, &block)
174
+ # Not a transfer of `TransferAgent`: the sync session is started directly
175
+ transfer.assert_no_dry_run
174
176
  Sync::Operations.start(async_info_from_args(path: path, sync_info: sync_info, direction: direction), transfer.user_transfer_spec, &block)
175
177
  Result::Success.new
176
178
  end
@@ -267,6 +267,8 @@ module Aspera
267
267
  transfer_spec['content_protection_password'] = @context.options.prompt_user_input('content protection password', sensitive: true) if transfer_spec['content_protection'].eql?('decrypt') && !transfer_spec.key?('content_protection_password')
268
268
  # Secrets of transfer spec (e.g. `token` from the application) are hidden wherever they appear (logs, results)
269
269
  Secret::Hider.instance.add_secrets_in(transfer_spec)
270
+ # Option `dry_run`: no transfer, the final transfer spec is the result
271
+ return Transfer::Result.dry_run(transfer_spec) if dry_run?
270
272
  # Renews the bearer token of the transfer: only possible with OAuth
271
273
  token_regenerator = -> { oauth_api.oauth.renewed_authorization } if oauth_api&.auth_params&.fetch(:type, nil).eql?(:oauth2)
272
274
  # create transfer agent
@@ -320,6 +322,18 @@ module Aspera
320
322
  return result
321
323
  end
322
324
 
325
+ # @return [Boolean] `true` if option `dry_run` is set: transfers are not started (see `start`)
326
+ def dry_run?
327
+ @context.options.get_option(:dry_run)
328
+ end
329
+
330
+ # For a command that changes something before its transfer (e.g. creates a package), or that does not transfer with `start`:
331
+ # fail before any change with option `dry_run`
332
+ # @raise [Cli::BadArgument] if option `dry_run` is set
333
+ def assert_no_dry_run
334
+ Aspera.assert(!dry_run?, type: Cli::BadArgument) { 'Option dry_run is not supported by this command' }
335
+ end
336
+
323
337
  # shut down if agent requires it
324
338
  def shutdown
325
339
  @agent.shutdown if @agent.respond_to?(:shutdown)
@@ -5,7 +5,8 @@
5
5
 
6
6
  require_relative '../log'
7
7
  require_relative '../assert'
8
- require_relative '../transfer/units'
8
+ require_relative '../units/decimal'
9
+ require_relative '../units/duration'
9
10
  require 'monitor'
10
11
  require 'ruby-progressbar'
11
12
 
@@ -229,12 +230,12 @@ module Aspera
229
230
  unless @sessions.empty?
230
231
  bytes_per_second = rate
231
232
  # Fixed width, so that bar does not change size
232
- rate_text = Transfer::Units.format_rate(bytes_per_second).rjust(11)
233
+ rate_text = Units::Decimal.format_rate(bytes_per_second).rjust(11)
233
234
  if total.nil?
234
- fields.push(Transfer::Units.format_bytes(current).rjust(8), rate_text)
235
+ fields.push(Units::Decimal.format_bytes(current).rjust(8), rate_text)
235
236
  else
236
237
  eta = bytes_per_second&.positive? ? (total - current) / bytes_per_second : nil
237
- fields.push('%j%%', rate_text, "ETA: #{Transfer::Units.format_duration(eta)}")
238
+ fields.push('%j%%', rate_text, "ETA: #{eta.nil? ? '--:--:--' : Units::Duration.new(eta).to_hms}")
238
239
  end
239
240
  end
240
241
  update_format(title_text(final: false), fields)
@@ -255,7 +256,7 @@ module Aspera
255
256
  update_bar(total, current)
256
257
  fields.push('%B', '%j%%')
257
258
  end
258
- fields.push(Transfer::Units.format_bytes(current), Transfer::Units.format_rate(average_rate)) unless @sessions.empty?
259
+ fields.push(Units::Decimal.format_bytes(current), Units::Decimal.format_rate(average_rate)) unless @sessions.empty?
259
260
  # Last status (e.g. `running`) is no more relevant
260
261
  @title = success ? nil : 'failed'
261
262
  # Final line may be shorter (no bar)
@@ -7,6 +7,6 @@ module Aspera
7
7
  module Cli
8
8
  # For beta add extension : .beta1
9
9
  # For dev version add extension : .pre
10
- VERSION = '4.29.0'
10
+ VERSION = '4.29.1'
11
11
  end
12
12
  end
@@ -292,7 +292,8 @@ module Aspera
292
292
  # browser_command: [Array<String>, nil] command (and arguments) that opens a URL (URL is appended), instead of
293
293
  # the system default
294
294
  # web_auth: :port or :paste, how the result of a web login is received: local port, or URL pasted by the user
295
- attr_accessor :url_method, :browser_command, :web_auth, :file_illegal_characters
295
+ # hidden_silent: if true, hidden input shows no mark of its state
296
+ attr_accessor :url_method, :browser_command, :web_auth, :hidden_silent, :file_illegal_characters
296
297
  attr_reader :os, :cpu, :default_gui_mode
297
298
 
298
299
  def initialize
@@ -338,6 +339,7 @@ module Aspera
338
339
  @url_method = @default_gui_mode
339
340
  @browser_command = nil
340
341
  @web_auth = :port
342
+ @hidden_silent = false
341
343
  @file_illegal_characters = REPLACE_CHARACTER + WINDOWS_FILENAME_INVALID_CHARACTERS
342
344
  nil
343
345
  end
@@ -17,12 +17,25 @@ module Aspera
17
17
  def from_list(*ids)
18
18
  safe_char = Environment.instance.safe_filename_character
19
19
  # compact: remove nils
20
- id = ids.flatten.compact.map do |i|
21
- i.is_a?(String) && i.start_with?('http://', 'https://') ? URI.parse(i).host : i.to_s
22
- end.join(safe_char)
20
+ id = ids.flatten.compact.map { |i| host_or_text(i) }.join(safe_char)
23
21
  # keep dot for extension only (nicer)
24
22
  return Environment.instance.sanitized_filename(id.gsub('.', safe_char)).downcase
25
23
  end
24
+
25
+ private
26
+
27
+ # A valid HTTP(S) URL with a host: its host name.
28
+ # Any other value is kept as text, e.g. an OAuth scope of several URLs separated by spaces, or an invalid URL.
29
+ # @param value [Object] one object ID
30
+ # @return [String] the host name, or the value as text
31
+ def host_or_text(value)
32
+ return value.to_s unless value.is_a?(String)
33
+ # A plain identifier also parses (as URI::Generic, without host): check the class (URI::HTTPS is a URI::HTTP) and the host
34
+ uri = URI.parse(value)
35
+ uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? ? uri.host : value
36
+ rescue URI::InvalidURIError
37
+ value
38
+ end
26
39
  end
27
40
  end
28
41
  end