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
@@ -173,7 +173,7 @@ module Aspera
173
173
 
174
174
  command :health, description: 'Check Orchestrator API health'
175
175
  command :info, description: 'Check that Orchestrator responds (ping)', action: ->(**) { Result::SingleObject.new(call_ao('remote_node_ping', accept: Mime::XML, xml_opts: {'ForceArray' => false})) }
176
- command :processes, description: 'Show Orchestrator background process status', action: ->(**) { processes_result(call_ao('processes_status', accept: Mime::XML, xml_opts: PROCESSES_XML_OPTS)) }
176
+ command :processes, read_only: true, description: 'Show Orchestrator background process status', action: ->(**) { processes_result(call_ao('processes_status', accept: Mime::XML, xml_opts: PROCESSES_XML_OPTS)) }
177
177
  command :control, description: 'Start, stop or kill the engine, the monitor or workers of Orchestrator, and show the process status',
178
178
  arguments: [
179
179
  {name: :process, type: Symbol, allowed: PROCESS_TYPES},
@@ -217,7 +217,7 @@ module Aspera
217
217
  end
218
218
 
219
219
  commands_under :monitors do
220
- command :snapshot, description: 'Show status of monitors, of all types or of one type',
220
+ command :snapshot, read_only: true, description: 'Show status of monitors, of all types or of one type',
221
221
  arguments: [{name: :type, type: Symbol, mandatory: false, allowed: MONITOR_SNAPSHOT_TYPES}],
222
222
  action: ->(type: nil, **) { Result::SingleObject.new(call_ao(type.nil? ? 'monitor_snapshot' : "monitor_snapshot/#{type}")['monitor']) }
223
223
  command :list, description: 'List monitors of a type: remote node monitors give the names of remote nodes',
@@ -245,14 +245,14 @@ module Aspera
245
245
  end
246
246
 
247
247
  commands_under :queues do
248
- command :stats, description: 'Statistics of the execution queue of the engine',
248
+ command :stats, read_only: true, description: 'Statistics of the execution queue of the engine',
249
249
  action: ->(**) { Result::SingleObject.new(call_ao("execution_queue_stats/#{ANY_ID}")) }
250
250
  command :list, description: 'List managed queues',
251
251
  action: ->(**) { Result::ObjectList.new(call_ao('queues_list').dig('Queues', 'queue') || []) }
252
- command :items, description: 'List items of a queue',
252
+ command :items, read_only: true, description: 'List items of a queue',
253
253
  arguments: [{name: :queue}],
254
254
  action: ->(queue:, **) { Result::ObjectList.new(call_ao("queued_items/#{URI.encode_uri_component(queue)}")['queued_items'] || []) }
255
- command :lookup, description: 'Find queued items, with option query: by item id, by item or by description (optionally in a queue)',
255
+ command :lookup, read_only: true, description: 'Find queued items, with option query: by item id, by item or by description (optionally in a queue)',
256
256
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/lookup_queued_item'),
257
257
  action: ->(**) { Result::ObjectList.new(call_ao('lookup_queued_item')['queued_items'] || []) }
258
258
  command :add, description: 'Add an item to a queue (priority, weight, description and tags with option query)',
@@ -294,7 +294,7 @@ module Aspera
294
294
  end
295
295
 
296
296
  commands_under :journal do
297
- command :files, description: 'List files recorded in a journal book (filters with option query)',
297
+ command :files, read_only: true, description: 'List files recorded in a journal book (filters with option query)',
298
298
  arguments: [{name: :book}],
299
299
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/journal_files/{id}')
300
300
  end
@@ -331,10 +331,10 @@ module Aspera
331
331
  command :status, description: 'Show running status of a workflow',
332
332
  arguments: [{name: :workflow_id, type: :identifier}],
333
333
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao(workflow_id.eql?(SpecialValues::ALL) ? 'workflows_status' : "workflows_status/#{workflow_id}")['workflows']['workflow']) }
334
- command :inputs, description: 'Show input specification of a workflow',
334
+ command :inputs, read_only: true, description: 'Show input specification of a workflow',
335
335
  arguments: [{name: :workflow_id, type: :identifier}],
336
336
  action: ->(workflow_id:, **) { Result::SingleObject.new(call_ao("workflow_inputs_spec/#{workflow_id}")['workflow_inputs_spec']) }
337
- command :details, description: 'Show detailed running status of a workflow (period with option query: `start_date`, `end_date`)',
337
+ command :details, read_only: true, description: 'Show detailed running status of a workflow (period with option query: `start_date`, `end_date`)',
338
338
  arguments: [{name: :workflow_id, type: :identifier}],
339
339
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/workflow_details/{id}'),
340
340
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("workflow_details/#{workflow_id}")['workflows']['workflow']['statuses']) }
@@ -366,7 +366,7 @@ module Aspera
366
366
  {name: :workflow_id, type: :identifier},
367
367
  {name: :export, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.OrchestratorWorkflowExport'}
368
368
  ]
369
- command :workorders, description: 'List work orders of a workflow (filters with option query)',
369
+ command :workorders, read_only: true, description: 'List work orders of a workflow (filters with option query)',
370
370
  arguments: [{name: :workflow_id, type: :identifier}],
371
371
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_orders_list/{id}'),
372
372
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("work_orders_list/#{workflow_id}")['work_orders']) }
@@ -386,20 +386,20 @@ module Aspera
386
386
  end
387
387
  end
388
388
  end
389
- command :outputs, description: 'Show output specification of a workflow',
389
+ command :outputs, read_only: true, description: 'Show output specification of a workflow',
390
390
  arguments: [{name: :workflow_id, type: :identifier}],
391
391
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("workflow_outputs_spec/#{workflow_id}")['workflow_outputs_spec']['output']) }
392
- command :parents, description: 'List published workflows that use a sub-workflow',
392
+ command :parents, read_only: true, description: 'List published workflows that use a sub-workflow',
393
393
  arguments: [{name: :workflow_id, type: :identifier}],
394
394
  action: ->(workflow_id:, **) { Result::ValueList.new(call_ao("list_by_subworkflow/#{workflow_id}")['parent_workflows'] || [], name: 'workflow') }
395
- command :steps, description: 'List steps of a type (plugin class, e.g. CustomRuby) in published workflows, with their work orders',
395
+ command :steps, read_only: true, description: 'List steps of a type (plugin class, e.g. CustomRuby) in published workflows, with their work orders',
396
396
  arguments: [{name: :step_type}],
397
397
  action: ->(step_type:, **) { Result::ObjectList.new(call_ao("retrieve_steps/#{ANY_ID}", query: {type: step_type})) }
398
398
  command :test_step, description: 'Launch the test cases of workflow steps: returns the id of the test run (`synchronous`, `step`, `case` with option query)',
399
399
  arguments: [{name: :workflow_id, type: :identifier}],
400
400
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/test_step/{id}'),
401
401
  action: ->(workflow_id:, **) { Result::SingleObject.new(call_ao("test_step/#{workflow_id}")) }
402
- command :test_status, description: 'Show the status of a test run launched by `test_step`',
402
+ command :test_status, read_only: true, description: 'Show the status of a test run launched by `test_step`',
403
403
  arguments: [{name: :test_run_id}],
404
404
  action: ->(test_run_id:, **) { Result::SingleObject.new(call_ao("test_step_status/#{test_run_id}")) }
405
405
  end
@@ -408,7 +408,7 @@ module Aspera
408
408
  command :status, description: 'Show status of a work order',
409
409
  arguments: [{name: :workorder_id, type: :identifier}],
410
410
  action: ->(workorder_id:, **) { Result::SingleObject.new(call_ao("work_order_status/#{workorder_id}")['work_order']) }
411
- command :worksteps, description: 'List work steps of a work order (not the steps of its sub-workflows)',
411
+ command :worksteps, read_only: true, description: 'List work steps of a work order (not the steps of its sub-workflows)',
412
412
  arguments: [{name: :workorder_id, type: :identifier}]
413
413
  command :cancel, description: 'Cancel a work order (option query: `force`)',
414
414
  arguments: [{name: :workorder_id, type: :identifier}],
@@ -417,14 +417,14 @@ module Aspera
417
417
  command :reset, description: 'Reset a work order',
418
418
  arguments: [{name: :workorder_id, type: :identifier}],
419
419
  action: ->(workorder_id:, **) { Result::SingleObject.new(call_ao("work_order_reset/#{workorder_id}")['work_order']) }
420
- command :output, description: 'Show output of a work order (filters with option query: `step_name`, `variable_name`)',
420
+ command :output, read_only: true, description: 'Show output of a work order (filters with option query: `step_name`, `variable_name`)',
421
421
  arguments: [{name: :workorder_id, type: :identifier}],
422
422
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_order_output/{id}'),
423
423
  action: ->(workorder_id:, **) { Result::ObjectList.new(call_ao("work_order_output/#{workorder_id}", accept: Mime::XML, xml_opts: {'ForceArray' => %w[variable], 'SuppressEmpty' => nil})['variable']) }
424
424
  command :delete, description: 'Delete a work order and its dependents',
425
425
  arguments: [{name: :workorder_id, type: :identifier}],
426
426
  action: ->(workorder_id:, **) { Result::Status.new(call_ao("work_order_destroy/#{workorder_id}").strip) }
427
- command :stats, description: 'Statistics of work orders: of the last 30 days, or of one day (filters `workflow_id`, `label`, `date` with option query)',
427
+ command :stats, read_only: true, description: 'Statistics of work orders: of the last 30 days, or of one day (filters `workflow_id`, `label`, `date` with option query)',
428
428
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_order_stats/{id}'),
429
429
  action: ->(**) { statistics_result(call_ao("work_order_stats/#{ANY_ID}")) }
430
430
  end
@@ -438,7 +438,7 @@ module Aspera
438
438
  command :reset, description: 'Restart the work order from a work step (several work steps: comma-separated ids)',
439
439
  arguments: [{name: :workstep_id, type: :identifier}],
440
440
  action: ->(workstep_id:, **) { Result.auto(call_ao("workstep_reset/#{workstep_id}")) }
441
- command :stats, description: 'Statistics of work steps: of the last 30 days, or of one day (filters `workflow_id`, `step_id`, `step_type`, `date` with option query)',
441
+ command :stats, read_only: true, description: 'Statistics of work steps: of the last 30 days, or of one day (filters `workflow_id`, `step_id`, `step_type`, `date` with option query)',
442
442
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_step_stats/{id}'),
443
443
  action: ->(**) { statistics_result(call_ao("work_step_stats/#{ANY_ID}")) }
444
444
  end
@@ -625,9 +625,10 @@ module Aspera
625
625
  # `call_ao('check_workflow', body: [['import_file', content, {filename: file_name}], ['import_file_name', file_name]], content_type: Mime::MULTIPART)`
626
626
  # The response is a Hash, see {OrchestratorWorkflowChecker}.
627
627
  # Templates and inputs of steps are checked with the specifications of plugins (see `plugins spec show`), when they can be read.
628
- # @param file_path [String] Workflow file (`.yml` or `.wkf`)
628
+ # @param file_name [String] Name of the workflow file (`.yml` or `.wkf`)
629
+ # @param content [String] Bytes of the file
629
630
  # @return [Hash] `valid` (Boolean), `file_name`, `issues` (list of Hash: `severity`, `code`, `file`, `path`, `message`)
630
- def check_workflow(file_path)
631
+ def check_workflow(file_name, content)
631
632
  require_relative '../../orchestrator_workflow_checker'
632
633
  specs = nil
633
634
  specs_error = nil
@@ -636,7 +637,7 @@ module Aspera
636
637
  rescue StandardError => e
637
638
  specs_error = e.message
638
639
  end
639
- response = OrchestratorWorkflowChecker.check(file_name: File.basename(file_path), content: File.binread(file_path), specs: specs)
640
+ response = OrchestratorWorkflowChecker.check(file_name: file_name, content: content, specs: specs)
640
641
  unless specs_error.nil?
641
642
  response['issues'].push({
642
643
  'severity' => 'warning',
@@ -648,10 +649,11 @@ module Aspera
648
649
  response
649
650
  end
650
651
 
652
+ # The file is read as `@file:`: the issues show parts of its content
651
653
  # @param file_path [String] Workflow file
652
654
  # @return [Result] The issues found, or a status if none
653
655
  def action_workflows_check_import(file_path:, **)
654
- response = check_workflow(file_path)
656
+ response = check_workflow(File.basename(file_path), Security.instance.read_file(file_path, binmode: true))
655
657
  return Result::Status.new('no problem found') if response['issues'].empty?
656
658
  Result::ObjectList.new(response['issues'], fields: %w[severity code file path message])
657
659
  end
@@ -704,15 +706,17 @@ module Aspera
704
706
  end
705
707
 
706
708
  # The file is uploaded as a multipart form
709
+ # It is sent, as a transfer sends files: not restricted by the security level, see `Security#read_file`
707
710
  # @param import [Hash] Options: `folder_id`, `publish`, `link_to_subworkflows`
708
711
  def action_workflows_import(file_path:, import: {}, **)
709
712
  import = import.transform_keys(&:to_s)
710
- check_workflow(file_path)['issues'].each do |issue|
713
+ file_name = File.basename(file_path)
714
+ content = File.binread(file_path)
715
+ check_workflow(file_name, content)['issues'].each do |issue|
711
716
  Log.log.warn { "#{issue['severity']}: #{[issue['file'], issue['path']].compact.join(' ')}: #{issue['message']} (#{issue['code']})" }
712
717
  end
713
- file_name = File.basename(file_path)
714
718
  form = [
715
- ['import_file', File.binread(file_path), {filename: file_name}],
719
+ ['import_file', content, {filename: file_name}],
716
720
  ['import_file_name', file_name]
717
721
  ]
718
722
  form.push(['folder_id', import['folder_id'].to_s]) if import.key?('folder_id')
@@ -225,6 +225,8 @@ module Aspera
225
225
  # @return [Object] transfer result returned by [`Main.result_transfer`](lib/aspera/cli/main.rb)
226
226
  def do_transfer(direction, folder_id, source_filename, destination = '/')
227
227
  Aspera.assert(!(destination.nil? && direction.eql?(Transfer::Spec::DIRECTION_RECEIVE)), 'destination must be set for receive direction')
228
+ # Previews are generated from downloaded files, and uploaded
229
+ transfer.assert_no_dry_run
228
230
  t_spec = @api_node.transfer_spec_gen4(folder_id, direction, {
229
231
  'paths' => [{'source' => source_filename}],
230
232
  'tags' => {Transfer::Spec::TAG_RESERVED => {PREV_GEN_TAG => true}}
@@ -440,7 +442,7 @@ module Aspera
440
442
  command :events, description: 'Process file events and generate previews', setup: :setup_node_api, action: ->(**) { run_event_loop(:events) }
441
443
  command :trevents, description: 'Process transfer events and generate previews', setup: :setup_node_api, action: ->(**) { run_event_loop(:trevents) }
442
444
  command :check, description: 'Check required tools are installed', action: ->(**) { tools_cleanup { Result::Status.new('Tools validated') } }
443
- command :show, description: 'Generate and display preview of a source file',
445
+ command :show, read_only: false, description: 'Generate and display preview of a source file',
444
446
  arguments: [{name: :source_file, description: 'Local file to preview', complete: :file}]
445
447
  command :test, description: 'Test preview generation for a source file',
446
448
  arguments: [
@@ -223,15 +223,15 @@ module Aspera
223
223
  command :cp, description: 'Copy files: source destination pairs, or sources with --to-folder', condition: :ascmd_available?, arguments: PATHS_ARGS
224
224
  command :mkdir, description: 'Create directory', condition: :ascmd_available?, arguments: PATHS_ARGS
225
225
  command(
226
- :df, description: 'Show disk usage', condition: :ascmd_available?,
226
+ :df, read_only: true, description: 'Show disk usage', condition: :ascmd_available?,
227
227
  action: lambda do |**|
228
228
  execute_ascmd(:df, []) do |result|
229
229
  Result::ObjectList.new(result.map(&:stringify_keys))
230
230
  end
231
231
  end
232
232
  )
233
- command :du, description: 'Show file sizes', condition: :ascmd_available?, arguments: PATHS_ARGS
234
- command :md5sum, description: 'Compute MD5 checksums', condition: :ascmd_available?, arguments: PATHS_ARGS
233
+ command :du, read_only: true, description: 'Show file sizes', condition: :ascmd_available?, arguments: PATHS_ARGS
234
+ command :md5sum, read_only: true, description: 'Compute MD5 checksums', condition: :ascmd_available?, arguments: PATHS_ARGS
235
235
  command :info, description: 'Show server system information', condition: :ascmd_available?,
236
236
  action: ->(**) { execute_ascmd(:info, []) { |r| Result::SingleObject.new(r.stringify_keys) } }
237
237
 
@@ -357,8 +357,7 @@ module Aspera
357
357
  # entity_plural captured at class-load time in the closure
358
358
  entity_plural_search = entity_type.eql?(:user) ? 'users' : 'groups'
359
359
  commands_under :search do
360
- command :list,
361
- description: "Search #{entity_type}s across all directories (use --query={q: '...'} to filter)",
360
+ command :list, description: "Search #{entity_type}s across all directories (use --query={q: '...'} to filter)",
362
361
  action: ->(**) { entity_list(api: @api_shares_admin, entity: entity_plural_search, items_key: 'members') }
363
362
  command :show,
364
363
  description: "Get directory #{entity_type} details by URN",
@@ -116,6 +116,8 @@ module Aspera
116
116
  # Install the transfer SDK (ascp + transferd) from a URL or using the default source.
117
117
  # Version defaults to `Info::SDK_VERSION`; pass `LATEST` as argument to install the latest available version.
118
118
  # Nothing is done if this version is already installed in the SDK folder (not checked if option `sdk_url` is set).
119
+ # SDK locations are read once, and only if needed (each read is counted as a download in statistics):
120
+ # not if the given version is already installed, but always for `LATEST` (to know that version).
119
121
  # Also called by the deprecated command `config ascp install`.
120
122
  # @param version [String, nil] version to install; nil means use the default SDK version
121
123
  # @return [Result::Status] installation result message
@@ -125,8 +127,11 @@ module Aspera
125
127
  installation = Ascp::Installation.instance
126
128
  url = sdk_url_option
127
129
  if url.nil?
128
- wanted_version = installation.sdk_location_for_platform(version: asked_version)['version']
129
- return Result::Status.new("Version #{wanted_version} is already installed in #{Products::Transferd.sdk_directory}") if installation.installed_sdk_version.eql?(wanted_version)
130
+ installed_version = installation.installed_sdk_version
131
+ location = installation.sdk_location_for_platform(version: asked_version) unless !installed_version.nil? && installed_version.eql?(asked_version)
132
+ wanted_version = location.nil? ? asked_version : location['version']
133
+ return Result::Status.new("Version #{wanted_version} is already installed in #{Products::Transferd.sdk_directory}") if installed_version.eql?(wanted_version)
134
+ url = location['url']
130
135
  end
131
136
  name, ver, folder = installation.install_sdk(url: url, version: asked_version)
132
137
  return Result::Status.new("Installed #{name} version #{ver} in #{folder}")
@@ -0,0 +1,236 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'error'
7
+ require_relative 'result'
8
+ require_relative 'formatter'
9
+ require_relative '../units/duration'
10
+ require_relative '../assert'
11
+ require 'json'
12
+ require 'stringio'
13
+
14
+ module Aspera
15
+ module Cli
16
+ class Result
17
+ # Result of a read-only command executed with option `poll`: the command is executed when the result is displayed,
18
+ # once or several times, and each result is displayed according to `show`.
19
+ # The command is not executed by `Runner#run_with_result` (MCP server): only by `Runner#run`, which displays the result.
20
+ class Poll < Result
21
+ # Parameters of option `poll`, see schema `PollOptions`
22
+ PARAMETERS = %i[interval max timeout until show errors].freeze
23
+ # Values of parameter `show`
24
+ SHOW_MODES = %i[change each last].freeze
25
+ # Values of parameter `errors`
26
+ ERROR_MODES = %i[fail retry].freeze
27
+ # Default time between runs, in seconds
28
+ DEFAULT_INTERVAL = 5
29
+
30
+ # Standard output that keeps the terminal properties of the real one (`tty?`, `winsize`),
31
+ # so that a result is rendered as on the terminal, and compared with the previous one before it is displayed.
32
+ class Capture < StringIO
33
+ # @param terminal [IO] The real standard output
34
+ def initialize(terminal)
35
+ super(+'')
36
+ @terminal = terminal
37
+ end
38
+
39
+ def tty? = @terminal.tty?
40
+ def isatty = tty?
41
+ def winsize = @terminal.winsize
42
+ end
43
+ private_constant :PARAMETERS, :SHOW_MODES, :ERROR_MODES, :DEFAULT_INTERVAL, :Capture
44
+
45
+ class << self
46
+ # Truth of a JMESPath value: `false`, `null`, empty string, empty list and empty object are false
47
+ # @param value [Object] Value of a JMESPath expression
48
+ # @return [Boolean]
49
+ def truthy?(value)
50
+ return false if value.nil? || value.eql?(false)
51
+ return !value.empty? if value.is_a?(String) || value.is_a?(Array) || value.is_a?(Hash)
52
+ true
53
+ end
54
+
55
+ # Data of a result, as seen by a JMESPath expression of `--out.query`: JSON values (keys and objects like `Time` become strings)
56
+ # @param result [Result] Result of a command
57
+ # @return [Object] JSON view of the data
58
+ def json_view(result)
59
+ data =
60
+ case result
61
+ when Result::Empty then []
62
+ when Result::Special then nil
63
+ else result.data
64
+ end
65
+ # A scalar is used as is: it may be binary (e.g. an image)
66
+ return data.is_a?(Symbol) ? data.to_s : data unless data.is_a?(Hash) || data.is_a?(Array)
67
+ JSON.parse(JSON.generate(data))
68
+ end
69
+ end
70
+
71
+ # Parameters are checked before the first run.
72
+ # @param parameters [Hash] Value of option `poll`, see schema `PollOptions`
73
+ # @param format [Symbol] Output format (`--format`)
74
+ # @raise [Cli::BadArgument] if a parameter is invalid
75
+ def initialize(parameters, format: nil)
76
+ super()
77
+ Aspera.assert_type(parameters, Hash, type: BadArgument) { 'poll' }
78
+ parameters = parameters.transform_keys(&:to_sym)
79
+ unknown = parameters.keys - PARAMETERS
80
+ raise BadArgument, "poll: unknown parameter: #{unknown.join(', ')}, expecting: #{PARAMETERS.join(', ')}" unless unknown.empty?
81
+ # Nagios plugins exit after the first result
82
+ raise BadArgument, 'poll: not with format nagios' if format.eql?(:nagios)
83
+ @interval = seconds(parameters.fetch(:interval, DEFAULT_INTERVAL), :interval)
84
+ @max = parameters[:max]
85
+ Aspera.assert(@max.nil? || (@max.is_a?(Integer) && @max.positive?), type: BadArgument) { "poll.max: expecting a positive integer, not #{@max.inspect}" }
86
+ @timeout = parameters[:timeout].nil? ? nil : seconds(parameters[:timeout], :timeout)
87
+ @until = parameters[:until]
88
+ Aspera.assert_type(@until, String, NilClass, type: BadArgument) { 'poll.until' }
89
+ Formatter.check_jmespath(@until, 'poll.until') unless @until.nil?
90
+ @show = parameters.fetch(:show, SHOW_MODES.first).to_s.to_sym
91
+ Aspera.assert_values(@show, SHOW_MODES, type: BadArgument) { 'poll.show' }
92
+ @errors = parameters.fetch(:errors, ERROR_MODES.first).to_s.to_sym
93
+ Aspera.assert_values(@errors, ERROR_MODES, type: BadArgument) { 'poll.errors' }
94
+ # Set by the dispatcher: executes the command, and returns its result
95
+ @action = nil
96
+ end
97
+
98
+ # @param action [Proc] Executes the command, and returns its result
99
+ attr_writer :action
100
+
101
+ # Execute the command (once or several times), and display results.
102
+ # `Ctrl-C` stops polling: the last result is displayed with `show=last`, then `Interrupt` is raised again.
103
+ # @param formatter [Formatter] Displays each result, with formatting options
104
+ # @raise [Cli::PollConditionNotMet] if `until` is not true after the last run
105
+ # @raise [StandardError] error of a run: with `errors=fail`, or of the last run with `errors=retry`
106
+ # @return [nil]
107
+ def format(formatter)
108
+ Aspera.assert(!@action.nil?) { 'poll: no action' }
109
+ start = clock
110
+ run = 0
111
+ met = false
112
+ previous = nil
113
+ last = nil
114
+ interrupted = false
115
+ # Error of the last run, with `errors=retry`
116
+ error = nil
117
+ begin
118
+ loop do
119
+ run += 1
120
+ error = nil
121
+ begin
122
+ result = @action.call
123
+ rescue StandardError => e
124
+ raise if @errors.eql?(:fail)
125
+ error = e
126
+ status(formatter, "poll: run #{run}#{"/#{@max}" unless @max.nil?} #{timestamp} error: #{e.message}")
127
+ end
128
+ if error.nil?
129
+ Aspera.assert_type(result, Result) { 'result of command' }
130
+ met = self.class.truthy?(evaluate(formatter, result)) unless @until.nil?
131
+ output = render(formatter, result)
132
+ case @show
133
+ when :each then display(formatter, run, output)
134
+ when :change then display(formatter, run, output) unless output.eql?(previous)
135
+ when :last then last = [run, output]
136
+ end
137
+ previous = output
138
+ end
139
+ break if met || (!@max.nil? && run >= @max)
140
+ wait = @interval
141
+ unless @timeout.nil?
142
+ remaining = start + @timeout - clock
143
+ break unless remaining.positive?
144
+ wait = [wait, remaining].min
145
+ end
146
+ pause(wait)
147
+ end
148
+ rescue Interrupt
149
+ interrupted = true
150
+ end
151
+ display(formatter, *last) unless last.nil?
152
+ raise Interrupt if interrupted
153
+ raise error unless error.nil?
154
+ status(formatter, "poll: condition met at run #{run}") if met
155
+ raise PollConditionNotMet, "condition not met after #{run} run#{'s' unless run.eql?(1)}: #{@until}" unless @until.nil? || met
156
+ nil
157
+ end
158
+
159
+ private
160
+
161
+ # @param value [Numeric, String] Duration: number of seconds, or text, e.g. `30s`, `5m`, `1h 30m` (see `Units::Duration`)
162
+ # @param name [Symbol] Parameter name, for errors
163
+ # @return [Integer] Seconds
164
+ def seconds(value, name)
165
+ Aspera.assert_type(value, Numeric, String, type: BadArgument) { "poll.#{name}" }
166
+ value = Units::Duration.new(value).to_unit('s')
167
+ Aspera.assert(!value.negative?, type: BadArgument) { "poll.#{name}: must not be negative" }
168
+ value
169
+ rescue ParameterError => e
170
+ raise BadArgument, "poll.#{name}: #{e.message}"
171
+ end
172
+
173
+ # @param formatter [Formatter] Applies `--select`
174
+ # @param result [Result] Result of a run
175
+ # @return [Object] Value of expression `until` on the result data, after `--select`, before `--fields` and `--out.query`
176
+ def evaluate(formatter, result)
177
+ data = self.class.json_view(result)
178
+ data = formatter.filter_columns_on_select(data) if data.is_a?(Array) && data.all?(Hash)
179
+ JMESPath.search(@until, data)
180
+ rescue JMESPath::Errors::Error => e
181
+ raise BadArgument, "poll.until: JMESPath: #{e.message}"
182
+ end
183
+
184
+ # @param formatter [Formatter] Displays the result
185
+ # @param result [Result] Result of a run
186
+ # @return [String] Display of the result
187
+ def render(formatter, result)
188
+ terminal = $stdout
189
+ $stdout = Capture.new(terminal)
190
+ formatter.display_results(result)
191
+ $stdout.string
192
+ ensure
193
+ $stdout = terminal
194
+ end
195
+
196
+ # Display a status line, and the result, immediately: e.g. for a program that reads the output line by line
197
+ # @param formatter [Formatter] Displays the status line
198
+ # @param run [Integer] Run number
199
+ # @param output [String] Display of the result
200
+ # @return [nil]
201
+ def display(formatter, run, output)
202
+ status(formatter, "poll: run #{run}#{"/#{@max}" unless @max.nil?} #{timestamp}")
203
+ $stdout.write(output)
204
+ $stdout.flush
205
+ nil
206
+ end
207
+
208
+ # @param formatter [Formatter] Displays the status line on `stderr`
209
+ # @param message [String] Status line
210
+ # @return [nil]
211
+ def status(formatter, message)
212
+ formatter.display_message(:error, message)
213
+ $stderr.flush
214
+ nil
215
+ end
216
+
217
+ # @return [String] Current local time, for status lines
218
+ def timestamp
219
+ Time.now.strftime('%Y-%m-%d %H:%M:%S')
220
+ end
221
+
222
+ # @return [Float] Monotonic time, in seconds
223
+ def clock
224
+ ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
225
+ end
226
+
227
+ # @param seconds [Numeric] Time to wait
228
+ # @return [nil]
229
+ def pause(seconds)
230
+ sleep(seconds)
231
+ nil
232
+ end
233
+ end
234
+ end
235
+ end
236
+ end