aspera-cli 4.28.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 (242) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +217 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +122 -26
  10. data/SECURITY.md +84 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1895 -632
  14. data/docs/test-mcp-with-ai.md +8 -8
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +7 -4
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +29 -22
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +95 -67
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +370 -0
  41. data/lib/aspera/ascp/log_locations.rb +163 -0
  42. data/lib/aspera/ascp/management.rb +16 -8
  43. data/lib/aspera/ascp/session_errors.rb +217 -0
  44. data/lib/aspera/assert.rb +4 -0
  45. data/lib/aspera/cli/ascp_actions.rb +12 -19
  46. data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
  47. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  48. data/lib/aspera/cli/bootstrapper.rb +38 -33
  49. data/lib/aspera/cli/command_line.rb +63 -8
  50. data/lib/aspera/cli/command_registry.rb +9 -1
  51. data/lib/aspera/cli/command_spec.rb +47 -7
  52. data/lib/aspera/cli/completion/ascli.bash +19 -5
  53. data/lib/aspera/cli/completion/ascli.fish +13 -2
  54. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  55. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  56. data/lib/aspera/cli/completion_actions.rb +303 -69
  57. data/lib/aspera/cli/context.rb +9 -4
  58. data/lib/aspera/cli/deprecation.rb +5 -2
  59. data/lib/aspera/cli/error.rb +6 -0
  60. data/lib/aspera/cli/extended_value.rb +66 -31
  61. data/lib/aspera/cli/formatter.rb +43 -30
  62. data/lib/aspera/cli/gem_checker.rb +9 -6
  63. data/lib/aspera/cli/hints.rb +22 -10
  64. data/lib/aspera/cli/http.rb +38 -10
  65. data/lib/aspera/cli/info.rb +12 -7
  66. data/lib/aspera/cli/mailer.rb +6 -3
  67. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  68. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  69. data/lib/aspera/cli/mcp/tool.rb +20 -17
  70. data/lib/aspera/cli/option_declarator.rb +10 -4
  71. data/lib/aspera/cli/option_registry.rb +6 -3
  72. data/lib/aspera/cli/option_types.rb +17 -2
  73. data/lib/aspera/cli/option_value.rb +77 -18
  74. data/lib/aspera/cli/options.schema.yaml +641 -80
  75. data/lib/aspera/cli/parser.rb +71 -35
  76. data/lib/aspera/cli/plugins/alee.rb +7 -4
  77. data/lib/aspera/cli/plugins/aoc.rb +248 -37
  78. data/lib/aspera/cli/plugins/ats.rb +10 -9
  79. data/lib/aspera/cli/plugins/base.rb +50 -18
  80. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  81. data/lib/aspera/cli/plugins/config.rb +210 -104
  82. data/lib/aspera/cli/plugins/console.rb +6 -3
  83. data/lib/aspera/cli/plugins/cos.rb +8 -4
  84. data/lib/aspera/cli/plugins/factory.rb +21 -7
  85. data/lib/aspera/cli/plugins/faspex5.rb +31 -26
  86. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  87. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  88. data/lib/aspera/cli/plugins/mcp.rb +42 -22
  89. data/lib/aspera/cli/plugins/node.rb +39 -38
  90. data/lib/aspera/cli/plugins/oauth.rb +23 -6
  91. data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
  92. data/lib/aspera/cli/plugins/preview.rb +72 -45
  93. data/lib/aspera/cli/plugins/server.rb +66 -14
  94. data/lib/aspera/cli/plugins/shares.rb +87 -18
  95. data/lib/aspera/cli/plugins/transferd.rb +228 -0
  96. data/lib/aspera/cli/poll.rb +236 -0
  97. data/lib/aspera/cli/preset_actions.rb +144 -30
  98. data/lib/aspera/cli/preset_manager.rb +113 -35
  99. data/lib/aspera/cli/prompt.rb +157 -9
  100. data/lib/aspera/cli/result.rb +12 -8
  101. data/lib/aspera/cli/runner.rb +89 -48
  102. data/lib/aspera/cli/secret_finder.rb +4 -1
  103. data/lib/aspera/cli/security.rb +89 -9
  104. data/lib/aspera/cli/special_values.rb +4 -1
  105. data/lib/aspera/cli/sync_actions.rb +15 -10
  106. data/lib/aspera/cli/table_fitter.rb +3 -0
  107. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  108. data/lib/aspera/cli/transfer_actions.rb +11 -8
  109. data/lib/aspera/cli/transfer_agent.rb +43 -20
  110. data/lib/aspera/cli/transfer_progress.rb +14 -45
  111. data/lib/aspera/cli/vault_actions.rb +45 -0
  112. data/lib/aspera/cli/vault_manager.rb +188 -42
  113. data/lib/aspera/cli/version.rb +4 -1
  114. data/lib/aspera/cli/web_secret.rb +12 -10
  115. data/lib/aspera/cli/wizard.rb +42 -39
  116. data/lib/aspera/command_line_builder.rb +9 -5
  117. data/lib/aspera/command_line_converter.rb +4 -1
  118. data/lib/aspera/coverage.rb +103 -33
  119. data/lib/aspera/data_repository.rb +4 -1
  120. data/lib/aspera/dot_container.rb +4 -1
  121. data/lib/aspera/environment.rb +23 -12
  122. data/lib/aspera/exec_spec.rb +3 -0
  123. data/lib/aspera/faspex_gw.rb +13 -9
  124. data/lib/aspera/faspex_postproc.rb +15 -12
  125. data/lib/aspera/formatter_interface.rb +4 -1
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +20 -5
  129. data/lib/aspera/inflate.rb +43 -0
  130. data/lib/aspera/json_rpc/client.rb +6 -5
  131. data/lib/aspera/json_rpc/version.rb +3 -0
  132. data/lib/aspera/line_logger.rb +4 -1
  133. data/lib/aspera/link_header.rb +4 -1
  134. data/lib/aspera/log.rb +18 -5
  135. data/lib/aspera/markdown.rb +5 -2
  136. data/lib/aspera/mime.rb +3 -0
  137. data/lib/aspera/nagios.rb +6 -4
  138. data/lib/aspera/node_emulator.rb +15 -13
  139. data/lib/aspera/oauth/client/base.rb +124 -73
  140. data/lib/aspera/oauth/client/boot.rb +7 -4
  141. data/lib/aspera/oauth/client/factory.rb +41 -18
  142. data/lib/aspera/oauth/client/generic.rb +5 -1
  143. data/lib/aspera/oauth/client/json_credentials.rb +7 -3
  144. data/lib/aspera/oauth/client/jwt.rb +6 -3
  145. data/lib/aspera/oauth/client/shares_web.rb +94 -0
  146. data/lib/aspera/oauth/client/url_json.rb +7 -3
  147. data/lib/aspera/oauth/client/web.rb +40 -13
  148. data/lib/aspera/oauth/server/pkce.rb +6 -5
  149. data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +16 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +17 -2
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +3 -0
  165. data/lib/aspera/rest/aspera_errors.rb +4 -1
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +45 -34
  168. data/lib/aspera/rest/error_analyzer.rb +5 -2
  169. data/lib/aspera/rest/list.rb +8 -4
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +8 -5
  172. data/lib/aspera/rest.rb +9 -6
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  175. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  176. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  177. data/lib/aspera/schema/async_tables.yaml +11 -10
  178. data/lib/aspera/schema/documentation.rb +8 -2
  179. data/lib/aspera/schema/reader.rb +7 -0
  180. data/lib/aspera/schema/registry.rb +44 -28
  181. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  182. data/lib/aspera/schema/validator.rb +4 -1
  183. data/lib/aspera/sealed_hash.rb +150 -0
  184. data/lib/aspera/secret/hider.rb +213 -0
  185. data/lib/aspera/secret/reference.rb +150 -0
  186. data/lib/aspera/secret/resolver.rb +212 -0
  187. data/lib/aspera/secret/store/base.rb +153 -0
  188. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  189. data/lib/aspera/secret/store/factory.rb +103 -0
  190. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  191. data/lib/aspera/secret/store/keeper.rb +141 -0
  192. data/lib/aspera/secret/store/macos_security.rb +284 -0
  193. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  194. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  195. data/lib/aspera/secret/store/one_password_cli.rb +112 -0
  196. data/lib/aspera/secret/store/secret_service.rb +125 -0
  197. data/lib/aspera/secret/strength.rb +119 -0
  198. data/lib/aspera/servlet_helpers.rb +5 -2
  199. data/lib/aspera/ssh.rb +10 -7
  200. data/lib/aspera/ssl.rb +5 -2
  201. data/lib/aspera/string_ext.rb +3 -0
  202. data/lib/aspera/sync/args.schema.yaml +3 -0
  203. data/lib/aspera/sync/conf.schema.yaml +9 -4
  204. data/lib/aspera/sync/database.rb +3 -0
  205. data/lib/aspera/sync/operations.rb +17 -15
  206. data/lib/aspera/temp_file_manager.rb +8 -4
  207. data/lib/aspera/timer_limiter.rb +3 -0
  208. data/lib/aspera/transfer/error.rb +4 -1
  209. data/lib/aspera/transfer/faux_file.rb +4 -1
  210. data/lib/aspera/transfer/parameters.rb +17 -14
  211. data/lib/aspera/transfer/result.rb +23 -0
  212. data/lib/aspera/transfer/resumer.rb +6 -4
  213. data/lib/aspera/transfer/spec.rb +9 -22
  214. data/lib/aspera/units/decimal.rb +67 -0
  215. data/lib/aspera/units/duration.rb +109 -0
  216. data/lib/aspera/uri_reader.rb +64 -9
  217. data/lib/aspera/web_auth/index.html.erb +6 -2
  218. data/lib/aspera/web_auth/paste.rb +109 -0
  219. data/lib/aspera/web_auth/receiver.rb +50 -0
  220. data/lib/aspera/web_auth/relay.rb +76 -0
  221. data/lib/aspera/web_auth/reply.html.erb +150 -0
  222. data/lib/aspera/web_auth/server.rb +47 -10
  223. data/lib/aspera/web_page.rb +7 -2
  224. data/lib/aspera/web_server_simple.rb +6 -3
  225. data/lib/aspera/yaml.rb +5 -1
  226. data/llms-install.md +88 -0
  227. data/llms.txt +87 -0
  228. data/skills/ascli/SKILL.md +94 -0
  229. data.tar.gz.sig +0 -0
  230. metadata +77 -20
  231. metadata.gz.sig +0 -0
  232. data/lib/aspera/duration.rb +0 -42
  233. data/lib/aspera/keychain/base.rb +0 -30
  234. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  235. data/lib/aspera/keychain/factory.rb +0 -58
  236. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  237. data/lib/aspera/keychain/macos_security.rb +0 -277
  238. data/lib/aspera/keychain/one_password_api.rb +0 -91
  239. data/lib/aspera/keychain/one_password_base.rb +0 -39
  240. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  241. data/lib/aspera/secret_hider.rb +0 -196
  242. data/lib/aspera/secret_strength.rb +0 -114
@@ -1,12 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/cli/plugins/basic_auth'
4
- require 'aspera/cli/special_values'
5
- require 'aspera/nagios'
6
- require 'aspera/log'
7
- require 'aspera/assert'
8
- require 'aspera/transfer/spec'
9
- require 'aspera/schema/registry'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'basic_auth'
7
+ require_relative '../special_values'
8
+ require_relative '../../nagios'
9
+ require_relative '../../log'
10
+ require_relative '../../assert'
11
+ require_relative '../../transfer/spec'
12
+ require_relative '../../schema/registry'
10
13
  require 'xmlsimple'
11
14
 
12
15
  module Aspera
@@ -18,33 +21,52 @@ module Aspera
18
21
  TEST_ENDPOINT = 'api/remote_node_ping'
19
22
  # Raw Markdown of the workflow authoring documents
20
23
  DOC_BASE_URL = 'https://raw.githubusercontent.com/laurent-martin/aspera-orchestrator-plugins-doc/main/docs'
21
- # Documents of command `workflows development`: name => file
22
- DOC_FILES = {
23
- authoring: 'workflow-authoring-guide.md',
24
- templates: 'action-template-reference.md',
25
- manual: 'Orchestrator_Plugin_Manual.md'
24
+ # Short link to the development guide: tried first, so that the location of the document can change
25
+ DOC_GUIDE_LINK = 'https://ibm.biz/aspera-orchestrator-book'
26
+ # Documents of command `workflows development`: name => URLs, tried in order
27
+ DOC_URLS = {
28
+ guide: [DOC_GUIDE_LINK, "#{DOC_BASE_URL}/orchestrator-development-guide.md"].freeze,
29
+ templates: ["#{DOC_BASE_URL}/action-template-reference.md"].freeze,
30
+ manual: ["#{DOC_BASE_URL}/Orchestrator_Plugin_Manual.md"].freeze
26
31
  }.freeze
27
- # Value of argument `section` of command `workflows development` for the table of contents
28
- DOC_TOC = 'toc'
32
+ # Description of the documents of command `workflows development`
33
+ DOC_DESCRIPTIONS = {
34
+ guide: 'Aspera Orchestrator Development Guide: concepts, designer, workflow files, recipes, plugins and portlets (large: use `toc` and `section`)',
35
+ templates: 'Action Template Reference: template attributes, inputs and outputs of each action plugin',
36
+ manual: 'Orchestrator Plugin Manual: functional description and setup of each plugin (large: use `toc` and `section`)'
37
+ }.freeze
38
+ # An unknown short link ends on a HTML page, but the documents are Markdown (they may start with a comment)
39
+ HTML_PAGE = /\A\s*<(!doctype|html)/i
29
40
  # Default maximum level of headings in the table of contents: guide sections, one entry per plugin
30
41
  DOC_TOC_LEVELS = {
31
- authoring: 3,
42
+ guide: 3,
32
43
  templates: 2,
33
44
  manual: 3
34
45
  }.freeze
35
- # Sections of a plugin specification, listed by command `plugins spec`
46
+ # Sections of a plugin specification, listed by command `plugins spec show`
36
47
  SPEC_SECTIONS = %i[attributes inputs outputs].freeze
37
- # Fields of the list of plugins of command `plugins spec`
38
- SPEC_LIST_FIELDS = %w[name category version display_name].freeze
48
+ # Fields of the list of plugins of command `plugins spec toc`
49
+ SPEC_LIST_FIELDS = %w[name category version display_name manual_anchor].freeze
39
50
  # Text value that is a YAML document (Ruby objects serialized by Orchestrator)
40
51
  YAML_DUMP = /\A---\s/
41
52
  # Types of monitors of `list_monitors` (`monitor_type`) and of `monitor_snapshot` (path)
42
53
  MONITOR_TYPES = %i[workflow workorder folder node script].freeze
43
54
  MONITOR_SNAPSHOT_TYPES = %i[workflows workorders folders nodes scripts].freeze
55
+ # Processes and commands of `control_process`
56
+ PROCESS_TYPES = %i[engine monitor worker].freeze
57
+ PROCESS_COMMANDS = %i[start stop kill].freeze
58
+ # XML options for the status of processes (`processes_status` and `control_process`)
59
+ PROCESSES_XML_OPTS = {'ForceArray' => %w[node process]}.freeze
60
+ # Moves of `reorder_queued_item` and `bulk_reorder_queue`
61
+ QUEUE_MOVES = %i[up down first last].freeze
62
+ # `ManagedResource` of Orchestrator repeats key `id` in each resource
63
+ RESOURCE_JSON_OPTS = {allow_duplicate_key: true}.freeze
44
64
  # Id segment of the path, for endpoints routed only as `api/<endpoint>/<id>` that do not use it
45
65
  ANY_ID = '0'
46
- private_constant :STANDARD_PATH, :TEST_ENDPOINT, :DOC_BASE_URL, :DOC_FILES, :DOC_TOC, :DOC_TOC_LEVELS, :SPEC_SECTIONS, :SPEC_LIST_FIELDS, :YAML_DUMP,
47
- :MONITOR_TYPES, :MONITOR_SNAPSHOT_TYPES, :ANY_ID
66
+ # Login of the current user, for `list_tasks`
67
+ SELF_USER = 'self'
68
+ private_constant :STANDARD_PATH, :TEST_ENDPOINT, :DOC_BASE_URL, :DOC_GUIDE_LINK, :DOC_URLS, :DOC_DESCRIPTIONS, :HTML_PAGE, :DOC_TOC_LEVELS, :SPEC_SECTIONS, :SPEC_LIST_FIELDS, :YAML_DUMP,
69
+ :MONITOR_TYPES, :MONITOR_SNAPSHOT_TYPES, :PROCESS_TYPES, :PROCESS_COMMANDS, :PROCESSES_XML_OPTS, :QUEUE_MOVES, :RESOURCE_JSON_OPTS, :ANY_ID, :SELF_USER
48
70
 
49
71
  class << self
50
72
  # @return [Hash,NilClass]
@@ -88,7 +110,7 @@ module Aspera
88
110
  }
89
111
  end
90
112
 
91
- option :apikey, description: 'API key (exclusive with username/password)'
113
+ option :apikey, description: 'API key of the user (exclusive with password), requires username'
92
114
  option :auth_style, description: 'Authentication style', allowed: %i[basic query token], default: :token
93
115
  option :ret_style, description: 'Method to specify the expected response format ("Accept")', allowed: %i[header query path], default: :query
94
116
  option :result, description: "Specify result value as: 'work_step:parameter'", deprecation: {last: '4.27.2', message: 'use keys `step` and `variable` of argument `execution` of `workflows start`'}
@@ -151,50 +173,157 @@ module Aspera
151
173
 
152
174
  command :health, description: 'Check Orchestrator API health'
153
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})) }
154
- command :processes, description: 'Show Orchestrator background process status', action: ->(**) { Result::ObjectList.new(call_ao('processes_status', accept: Mime::XML, xml_opts: {'ForceArray' => %w[node process]})['node'].flat_map { |n| n['process'] }) }
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
+ command :control, description: 'Start, stop or kill the engine, the monitor or workers of Orchestrator, and show the process status',
178
+ arguments: [
179
+ {name: :process, type: Symbol, allowed: PROCESS_TYPES},
180
+ {name: :operation, type: Symbol, allowed: PROCESS_COMMANDS},
181
+ {name: :worker_ids, mandatory: false}
182
+ ],
183
+ action: ->(process:, operation:, worker_ids: nil, **) { processes_result(call_ao("control_process/#{process}", query: {command: operation, worker_id: worker_ids}.compact, accept: Mime::XML, xml_opts: PROCESSES_XML_OPTS)) }
184
+ command :users, description: 'Manage users'
185
+ command :alerts, description: 'Alerts of the categories the user is subscribed to'
186
+ command :tasks, description: 'Tasks: user inputs waiting for a user'
155
187
  command :monitors, description: 'Monitors of workflows, work orders, folders, remote nodes and scripts'
156
188
  command :queues, description: 'Managed queues'
189
+ command :portlets, description: 'Portlets of the web interface'
157
190
  command :pools, description: 'Resource pools'
158
191
  command :journal, description: 'Journal books'
159
192
  command :workorders, description: 'Manage work orders'
160
- command :workstep, description: 'Manage work steps'
193
+ command :worksteps, description: 'Manage work steps'
194
+
195
+ commands_under :alerts do
196
+ command :list, description: 'List alerts (option query: `category`, `count_only`)',
197
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/alerts/{id}'),
198
+ action: ->(**) { Result.auto(call_ao("alerts/#{ANY_ID}")) }
199
+ end
200
+
201
+ commands_under :tasks do
202
+ command :list, description: 'List tasks waiting for a user (only an administrator can list the tasks of another user)',
203
+ arguments: [{name: :user, mandatory: false, default: SELF_USER}],
204
+ action: ->(user:, **) { Result::ObjectList.new(call_ao("list_tasks/#{URI.encode_uri_component(user)}")['tasks'] || []) }
205
+ command :show, description: 'Show a task: its user inputs and its parameters. Id is a task id, or WO<work order id> with the step name when the work order has several',
206
+ arguments: [
207
+ {name: :task_id},
208
+ {name: :step_name, mandatory: false}
209
+ ],
210
+ action: ->(task_id:, step_name: nil, **) { Result::SingleObject.new(call_ao("task_details/#{task_id}", query: {step_name: step_name, Step_name: step_name}.compact)) }
211
+ command :submit, description: 'Complete a task with values of its user inputs (all required inputs must be given)',
212
+ arguments: [
213
+ {name: :task_id, type: :identifier},
214
+ {name: :inputs, type: Hash, schema: 'orchestrator:components.schemas.TaskUserInputs'}
215
+ ],
216
+ action: ->(task_id:, inputs:, **) { Result::SingleObject.new(call_ao("submit_task/#{task_id}", query: inputs.transform_keys { |name| :"outputs[#{name}]" })) }
217
+ end
161
218
 
162
219
  commands_under :monitors do
163
- 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',
164
221
  arguments: [{name: :type, type: Symbol, mandatory: false, allowed: MONITOR_SNAPSHOT_TYPES}],
165
222
  action: ->(type: nil, **) { Result::SingleObject.new(call_ao(type.nil? ? 'monitor_snapshot' : "monitor_snapshot/#{type}")['monitor']) }
166
223
  command :list, description: 'List monitors of a type: remote node monitors give the names of remote nodes',
167
224
  arguments: [{name: :type, type: Symbol, allowed: MONITOR_TYPES}]
225
+ command :activate, description: 'Activate a monitor',
226
+ arguments: [{name: :type, type: Symbol, allowed: MONITOR_TYPES}, {name: :monitor_id, type: :identifier}],
227
+ action: ->(type:, monitor_id:, **) { Result::SingleObject.new(call_ao("activate_monitor/#{monitor_id}", query: {monitor_type: type})) }
228
+ command :deactivate, description: 'Deactivate a monitor',
229
+ arguments: [{name: :type, type: Symbol, allowed: MONITOR_TYPES}, {name: :monitor_id, type: :identifier}],
230
+ action: ->(type:, monitor_id:, **) { Result::SingleObject.new(call_ao("deactivate_monitor/#{monitor_id}", query: {monitor_type: type})) }
231
+ end
232
+
233
+ commands_under :portlets do
234
+ command :list, description: 'List portlets with their version',
235
+ action: ->(**) { Result::ObjectList.new(call_ao('portlet_version')['Portlet'] || []) }
236
+ command :show, description: 'Show the version of a portlet',
237
+ arguments: [{name: :portlet}],
238
+ action: ->(portlet:, **) { Result::ObjectList.new(call_ao("portlet_version/#{URI.encode_uri_component(portlet)}")['Portlet'] || []) }
239
+ end
240
+
241
+ commands_under :users do
242
+ command :create, description: 'Create a user',
243
+ arguments: [{name: :user, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::ORCHESTRATOR, 'api/create_user/{id}.post')}],
244
+ action: ->(user:, **) { Result::Status.new(call_ao("create_user/#{ANY_ID}", body: user).dig('create_user', 'success').to_s) }
168
245
  end
169
246
 
170
247
  commands_under :queues do
248
+ command :stats, read_only: true, description: 'Statistics of the execution queue of the engine',
249
+ action: ->(**) { Result::SingleObject.new(call_ao("execution_queue_stats/#{ANY_ID}")) }
171
250
  command :list, description: 'List managed queues',
172
251
  action: ->(**) { Result::ObjectList.new(call_ao('queues_list').dig('Queues', 'queue') || []) }
252
+ command :items, read_only: true, description: 'List items of a queue',
253
+ arguments: [{name: :queue}],
254
+ action: ->(queue:, **) { Result::ObjectList.new(call_ao("queued_items/#{URI.encode_uri_component(queue)}")['queued_items'] || []) }
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
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/lookup_queued_item'),
257
+ action: ->(**) { Result::ObjectList.new(call_ao('lookup_queued_item')['queued_items'] || []) }
258
+ command :add, description: 'Add an item to a queue (priority, weight, description and tags with option query)',
259
+ arguments: [{name: :queue}, {name: :item}],
260
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/queue_item/{id}'),
261
+ action: ->(queue:, item:, **) { Result::SingleObject.new(call_ao("queue_item/#{URI.encode_uri_component(queue)}", query: {queued_item: item})) }
262
+ command :move, description: "Move a queued item: #{QUEUE_MOVES.join(', ')}",
263
+ arguments: [{name: :operation, type: Symbol, allowed: QUEUE_MOVES}, {name: :item_id, type: :identifier}],
264
+ action: ->(operation:, item_id:, **) { Result::ObjectList.new(call_ao('reorder_queued_item', query: {operation: operation, queued_item_id: item_id})['queued_items'] || []) }
265
+ command :bulk_move, description: "Move several queued items (comma-separated ids): #{QUEUE_MOVES.join(', ')}",
266
+ arguments: [{name: :operation, type: Symbol, allowed: QUEUE_MOVES}, {name: :item_ids}],
267
+ action: ->(operation:, item_ids:, **) { Result::ObjectList.new(call_ao('bulk_reorder_queue', query: {operation: operation, queued_item_ids: item_ids})['queued_items'].map { |entry| entry['queued_item'] }) }
268
+ # Asks for XML: on success, the JSON response of this endpoint is a plain text that is not valid JSON
269
+ command :delete, description: 'Delete a queued item',
270
+ arguments: [{name: :queue}, {name: :item_id, type: :identifier}],
271
+ action: ->(queue:, item_id:, **) { Result::Status.new(call_ao('delete_queued_item', query: {queue_name: queue, queued_item_id: item_id}, accept: Mime::XML, xml_opts: {'ForceArray' => false}).fetch('Success')) }
173
272
  end
174
273
 
175
274
  commands_under :pools do
176
275
  command :status, description: 'Show resources of a resource pool and their status',
177
276
  arguments: [{name: :pool_name}],
178
- # Orchestrator repeats key `id` in each resource
179
- action: ->(pool_name:, **) { Result::ObjectList.new(call_ao("pool_status/#{ANY_ID}", query: {name: pool_name}, json_opts: {allow_duplicate_key: true})['ManagedResource'] || []) }
277
+ action: ->(pool_name:, **) { Result::ObjectList.new(call_ao("pool_status/#{ANY_ID}", query: {name: pool_name}, json_opts: RESOURCE_JSON_OPTS)['ManagedResource'] || []) }
278
+ command :add_resource, description: 'Add a resource to a resource pool (capacity and tags with option query)',
279
+ arguments: [{name: :pool_name}, {name: :resource_name}],
280
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/add_resource/{id}'),
281
+ action: ->(pool_name:, resource_name:, **) { Result::SingleObject.new(call_ao("add_resource/#{ANY_ID}", query: {pool_name: pool_name, resource_name: resource_name}, json_opts: RESOURCE_JSON_OPTS)['ManagedResource']) }
282
+ command :resource_capacity, description: 'Change the capacity of a resource',
283
+ arguments: [{name: :pool_name}, {name: :resource_name}, {name: :capacity, type: Integer}],
284
+ action: ->(pool_name:, resource_name:, capacity:, **) { Result::SingleObject.new(call_ao("edit_resource_capacity/#{capacity}", query: {pool_name: pool_name, resource_name: resource_name}, json_opts: RESOURCE_JSON_OPTS)['ManagedResource']) }
285
+ command :capacity, description: 'Change the capacity of a resource pool',
286
+ arguments: [{name: :pool_name}, {name: :capacity, type: Integer}],
287
+ action: ->(pool_name:, capacity:, **) { Result::ObjectList.new(call_ao("edit_pool_capacity/#{capacity}", query: {pool_name: pool_name}, json_opts: RESOURCE_JSON_OPTS)['ManagedResource']) }
288
+ command :online, description: 'Take a resource online',
289
+ arguments: [{name: :pool_name}, {name: :resource_name}],
290
+ action: ->(pool_name:, resource_name:, **) { Result::SingleObject.new(call_ao("resource_online/#{ANY_ID}", query: {pool_name: pool_name, resource_name: resource_name})['ManagedResource']) }
291
+ command :offline, description: 'Take a resource offline',
292
+ arguments: [{name: :pool_name}, {name: :resource_name}],
293
+ action: ->(pool_name:, resource_name:, **) { Result::SingleObject.new(call_ao("resource_offline/#{ANY_ID}", query: {pool_name: pool_name, resource_name: resource_name})['ManagedResource']) }
180
294
  end
181
295
 
182
296
  commands_under :journal do
183
- 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)',
184
298
  arguments: [{name: :book}],
185
299
  query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/journal_files/{id}')
186
300
  end
187
301
 
188
302
  commands_under :plugins do
189
- command :list, description: 'Show Orchestrator plugin versions', action: ->(**) { Result::ObjectList.new(call_ao('plugin_version')['Plugin']) }
303
+ command :list, description: 'List plugins with their version', action: ->(**) { Result::ObjectList.new(call_ao('plugin_version')['Plugin']) }
304
+ command :reload, description: 'Reload a plugin (class name), or all enabled plugins',
305
+ arguments: [{name: :plugin, mandatory: false}],
306
+ action: ->(plugin: nil, **) { Result::SingleObject.new(call_ao('reload_plugin', query: {action_type: plugin}.compact)) }
307
+ command :enable, description: 'Enable a plugin (class name), or all plugins. Orchestrator 4.1.6: never for a plugin imported with `import`, it deletes its folder',
308
+ arguments: [{name: :plugin, mandatory: false}],
309
+ action: ->(plugin: nil, **) { Result::SingleObject.new(call_ao("enable_plugin/#{ANY_ID}", query: {action_type: plugin}.compact)) }
310
+ command :import, description: 'Import and enable a plugin from an archive present on the Orchestrator host, readable by aspweb. Orchestrator 4.1.6: its migration files stay in the load folder, and prevent the next start',
311
+ arguments: [{name: :file_path}],
312
+ action: ->(file_path:, **) { Result::SingleObject.new(call_ao("import_plugin/#{ANY_ID}", query: {file: file_path})) }
190
313
  command :reload_set, description: 'Reload a set of plugins',
191
314
  arguments: [{name: :plugin_set, type: Hash, schema: 'opts:components.schemas.OrchestratorReloadPluginSet'}],
192
315
  action: ->(plugin_set:, **) { Result::SingleObject.new(call_ao('reload_plugin_set', body: plugin_set.transform_keys(&:to_sym))) }
193
- command :spec, description: "Show specifications of action plugins, from GitHub (no access to Orchestrator): list of plugins, one plugin, or its #{SPEC_SECTIONS.join(', ')}",
194
- arguments: [
195
- {name: :plugin, mandatory: false},
196
- {name: :section, type: Symbol, mandatory: false, allowed: SPEC_SECTIONS}
197
- ]
316
+ # Specifications of action plugins, read from GitHub (no access to Orchestrator)
317
+ commands_under :spec, description: 'Specifications of action plugins, from GitHub (no access to Orchestrator)' do
318
+ command :toc, description: 'List the plugins: name, category, version, display name, anchor of the section in the Plugin Manual (filter with option select)',
319
+ action: ->(**) { plugin_spec_toc }
320
+ command :show, description: "Show the specification of a plugin, with `manual_anchor` for `workflows development manual section`: whole, or one section (#{SPEC_SECTIONS.join(', ')})",
321
+ arguments: [
322
+ {name: :plugin},
323
+ {name: :section, type: Symbol, mandatory: false, allowed: SPEC_SECTIONS}
324
+ ],
325
+ action: ->(plugin:, section: nil, **) { plugin_spec_show(plugin, section) }
326
+ end
198
327
  end
199
328
 
200
329
  commands_under :workflows do
@@ -202,11 +331,12 @@ module Aspera
202
331
  command :status, description: 'Show running status of a workflow',
203
332
  arguments: [{name: :workflow_id, type: :identifier}],
204
333
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao(workflow_id.eql?(SpecialValues::ALL) ? 'workflows_status' : "workflows_status/#{workflow_id}")['workflows']['workflow']) }
205
- command :inputs, description: 'Show input specification of a workflow',
334
+ command :inputs, read_only: true, description: 'Show input specification of a workflow',
206
335
  arguments: [{name: :workflow_id, type: :identifier}],
207
336
  action: ->(workflow_id:, **) { Result::SingleObject.new(call_ao("workflow_inputs_spec/#{workflow_id}")['workflow_inputs_spec']) }
208
- command :details, description: 'Show detailed running status of a workflow',
337
+ command :details, read_only: true, description: 'Show detailed running status of a workflow (period with option query: `start_date`, `end_date`)',
209
338
  arguments: [{name: :workflow_id, type: :identifier}],
339
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/workflow_details/{id}'),
210
340
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("workflow_details/#{workflow_id}")['workflows']['workflow']['statuses']) }
211
341
  command :start, description: 'Start a workflow: create a work order (sync or async)',
212
342
  arguments: [
@@ -216,11 +346,11 @@ module Aspera
216
346
  ]
217
347
  command :import, description: 'Import a workflow from a file created by `workflows export`, local problems are reported as warnings (see `check_import`)',
218
348
  arguments: [
219
- {name: :file_path},
349
+ {name: :file_path, complete: :file},
220
350
  {name: :import, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.OrchestratorWorkflowImport'}
221
351
  ]
222
352
  command :check_import, description: 'Check a workflow file (no access to Orchestrator): rules that Orchestrator does not check on import, but that make the workflow fail to publish or to run',
223
- arguments: [{name: :file_path}]
353
+ arguments: [{name: :file_path, complete: :file}]
224
354
  command :find_constraints, description: 'List the conflicts and missing plugins of a workflow file present on the Orchestrator host, before `import_with_constraints`',
225
355
  arguments: [
226
356
  {name: :filename},
@@ -236,41 +366,87 @@ module Aspera
236
366
  {name: :workflow_id, type: :identifier},
237
367
  {name: :export, type: Hash, mandatory: false, default: {}, schema: 'opts:components.schemas.OrchestratorWorkflowExport'}
238
368
  ]
239
- command :workorders, description: 'List work orders of a workflow',
369
+ command :workorders, read_only: true, description: 'List work orders of a workflow (filters with option query)',
240
370
  arguments: [{name: :workflow_id, type: :identifier}],
371
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_orders_list/{id}'),
241
372
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("work_orders_list/#{workflow_id}")['work_orders']) }
242
- command :development, description: "Show documentation for workflow development, from GitHub (no access to Orchestrator): whole document, its table of contents (#{DOC_TOC}, headings up to level #{DOC_TOC_LEVELS.map { |d, l| "#{l} (#{d})" }.join(', ')}, or argument level), or one section (anchor)",
243
- arguments: [
244
- {name: :document, type: Symbol, mandatory: false, default: :authoring, allowed: DOC_FILES.keys},
245
- {name: :section, mandatory: false},
246
- {name: :level, type: Integer, mandatory: false}
247
- ]
248
- command :outputs, description: 'Show output specification of a workflow',
373
+ # Documentation for workflow development, read from GitHub (no access to Orchestrator)
374
+ commands_under :development, description: 'Documentation for workflow development, from GitHub (no access to Orchestrator): choose a document' do
375
+ DOC_URLS.each_key do |document|
376
+ command document, description: DOC_DESCRIPTIONS[document]
377
+ commands_under document do
378
+ command :toc, description: "List the sections of the document: level, title, anchor (headings up to level #{DOC_TOC_LEVELS[document]}, or argument level)",
379
+ arguments: [{name: :level, type: Integer, mandatory: false}],
380
+ action: ->(level: nil, **) { development_toc(document, level) }
381
+ command :full, description: 'Display the whole document',
382
+ action: ->(**) { Result::Text.new(development_document(document)) }
383
+ command :section, description: 'Display one section of the document (anchor given by `toc`)',
384
+ arguments: [{name: :name}],
385
+ action: ->(name:, **) { development_section(document, name) }
386
+ end
387
+ end
388
+ end
389
+ command :outputs, read_only: true, description: 'Show output specification of a workflow',
249
390
  arguments: [{name: :workflow_id, type: :identifier}],
250
391
  action: ->(workflow_id:, **) { Result::ObjectList.new(call_ao("workflow_outputs_spec/#{workflow_id}")['workflow_outputs_spec']['output']) }
392
+ command :parents, read_only: true, description: 'List published workflows that use a sub-workflow',
393
+ arguments: [{name: :workflow_id, type: :identifier}],
394
+ action: ->(workflow_id:, **) { Result::ValueList.new(call_ao("list_by_subworkflow/#{workflow_id}")['parent_workflows'] || [], name: 'workflow') }
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
+ arguments: [{name: :step_type}],
397
+ action: ->(step_type:, **) { Result::ObjectList.new(call_ao("retrieve_steps/#{ANY_ID}", query: {type: step_type})) }
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
+ arguments: [{name: :workflow_id, type: :identifier}],
400
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/test_step/{id}'),
401
+ action: ->(workflow_id:, **) { Result::SingleObject.new(call_ao("test_step/#{workflow_id}")) }
402
+ command :test_status, read_only: true, description: 'Show the status of a test run launched by `test_step`',
403
+ arguments: [{name: :test_run_id}],
404
+ action: ->(test_run_id:, **) { Result::SingleObject.new(call_ao("test_step_status/#{test_run_id}")) }
251
405
  end
252
406
 
253
407
  commands_under :workorders do
254
408
  command :status, description: 'Show status of a work order',
255
409
  arguments: [{name: :workorder_id, type: :identifier}],
256
410
  action: ->(workorder_id:, **) { Result::SingleObject.new(call_ao("work_order_status/#{workorder_id}")['work_order']) }
257
- command :cancel, description: 'Cancel a work order',
411
+ command :worksteps, read_only: true, description: 'List work steps of a work order (not the steps of its sub-workflows)',
412
+ arguments: [{name: :workorder_id, type: :identifier}]
413
+ command :cancel, description: 'Cancel a work order (option query: `force`)',
258
414
  arguments: [{name: :workorder_id, type: :identifier}],
415
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_order_cancel/{id}'),
259
416
  action: ->(workorder_id:, **) { Result::SingleObject.new(call_ao("work_order_cancel/#{workorder_id}")['work_order']) }
260
417
  command :reset, description: 'Reset a work order',
261
418
  arguments: [{name: :workorder_id, type: :identifier}],
262
419
  action: ->(workorder_id:, **) { Result::SingleObject.new(call_ao("work_order_reset/#{workorder_id}")['work_order']) }
263
- command :output, description: 'Show output of a work order',
420
+ command :output, read_only: true, description: 'Show output of a work order (filters with option query: `step_name`, `variable_name`)',
264
421
  arguments: [{name: :workorder_id, type: :identifier}],
422
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_order_output/{id}'),
265
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
+ command :delete, description: 'Delete a work order and its dependents',
425
+ arguments: [{name: :workorder_id, type: :identifier}],
426
+ action: ->(workorder_id:, **) { Result::Status.new(call_ao("work_order_destroy/#{workorder_id}").strip) }
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
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_order_stats/{id}'),
429
+ action: ->(**) { statistics_result(call_ao("work_order_stats/#{ANY_ID}")) }
266
430
  end
267
431
 
268
- commands_under :workstep do
432
+ commands_under :worksteps do
269
433
  command :status, description: 'Show status of a work step',
270
434
  arguments: [{name: :workstep_id, type: :identifier}]
271
435
  command :cancel, description: 'Cancel a work step',
272
436
  arguments: [{name: :workstep_id, type: :identifier}],
273
437
  action: ->(workstep_id:, **) { Result::SingleObject.new(call_ao("work_step_cancel/#{workstep_id}")) }
438
+ command :reset, description: 'Restart the work order from a work step (several work steps: comma-separated ids)',
439
+ arguments: [{name: :workstep_id, type: :identifier}],
440
+ action: ->(workstep_id:, **) { Result.auto(call_ao("workstep_reset/#{workstep_id}")) }
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
+ query_schema: Schema::Registry.query_params(Schema::Registry::ORCHESTRATOR, 'api/work_step_stats/{id}'),
443
+ action: ->(**) { statistics_result(call_ao("work_step_stats/#{ANY_ID}")) }
444
+ end
445
+
446
+ # Statistics are a list, or a message in `text/plain` when there is none
447
+ # @param stats [Array<Hash>, String]
448
+ def statistics_result(stats)
449
+ stats.is_a?(String) ? Result::Status.new(stats) : Result::ObjectList.new(stats)
274
450
  end
275
451
 
276
452
  # --- API ---
@@ -284,8 +460,8 @@ module Aspera
284
460
  apikey = options.get_option(:apikey)
285
461
  username = options.get_option(:username)
286
462
  password = options.get_option(:password)
287
- Aspera.assert(apikey.nil? || (username.nil? && password.nil?), type: Cli::BadArgument) { 'apikey and username/password are mutually exclusive' }
288
- Aspera.assert(!apikey.nil? || (!username.nil? && !password.nil?), type: Cli::BadArgument) { 'provide either apikey or username and password' }
463
+ Aspera.assert(apikey.nil? || password.nil?, type: Cli::BadArgument) { 'apikey and password are mutually exclusive' }
464
+ Aspera.assert(!username.nil? && !(apikey.nil? && password.nil?), type: Cli::BadArgument) { 'provide username with either password or apikey' }
289
465
 
290
466
  auth_params =
291
467
  case style
@@ -297,11 +473,7 @@ module Aspera
297
473
  password: password
298
474
  }
299
475
  when :query
300
- if apikey
301
- {type: :url, url_query: {'apikey' => apikey}}
302
- else
303
- {type: :url, url_query: {'login' => username, 'password' => password}}
304
- end
476
+ {type: :url, url_query: {'login' => username}.merge(apikey ? {'api_key' => apikey} : {'password' => password})}
305
477
  when :token
306
478
  {
307
479
  type: :oauth2,
@@ -309,7 +481,7 @@ module Aspera
309
481
  base_url: base_url,
310
482
  path_token: 'api/login',
311
483
  token_field: 'token',
312
- json: apikey ? {apikey: apikey} : {username: username, password: password}
484
+ json: {username: username}.merge(apikey ? {api_key: apikey} : {password: password})
313
485
  }
314
486
  else Aspera.error_unexpected_value(style)
315
487
  end
@@ -331,6 +503,12 @@ module Aspera
331
503
  Result::ObjectList.new(nagios.status_list)
332
504
  end
333
505
 
506
+ # Processes of all nodes
507
+ # @param status [Hash] Response of `processes_status` or `control_process` (XML)
508
+ def processes_result(status)
509
+ Result::ObjectList.new(status['node'].flat_map { |node| node['process'] })
510
+ end
511
+
334
512
  # Monitors of work orders are wrapped in `monitor-workorder`
335
513
  def action_monitors_list(type:, **)
336
514
  monitors = call_ao("list_monitors/#{ANY_ID}", query: {monitor_type: type})
@@ -339,19 +517,27 @@ module Aspera
339
517
 
340
518
  # Files of the packages, and files without package, with the name of their package
341
519
  def action_journal_files(book:, **)
342
- report = call_ao("journal_files/#{book}")
520
+ report = call_ao("journal_files/#{URI.encode_uri_component(book)}")
343
521
  files = Array(report['Packages']).flat_map { |package| Array(package['files']).map { |file| {'package' => package['name']}.merge(file) } }
344
522
  Result::ObjectList.new(files + Array(report['Files']))
345
523
  end
346
524
 
347
525
  # Fields of the work step that Orchestrator returns as YAML dumps of its Ruby objects (`prerequisites`, `work_outputs`...)
348
526
  # are removed: they are not readable, and the inputs and outputs are also given as `inputs` and `outputs`.
349
- def action_workstep_status(workstep_id:, **)
527
+ def action_worksteps_status(workstep_id:, **)
350
528
  status = call_ao("work_step_status/#{workstep_id}")
351
529
  status['work_step']&.reject! { |_name, value| value.is_a?(String) && value.match?(YAML_DUMP) }
352
530
  Result::SingleObject.new(status)
353
531
  end
354
532
 
533
+ # Work steps of a work order, without the fields that are YAML dumps (see `action_worksteps_status`).
534
+ # Empty until the work order has created its steps.
535
+ def action_workorders_worksteps(workorder_id:, **)
536
+ steps = Array(call_ao("work_order_status/#{workorder_id}")['work_steps'])
537
+ steps.each { |step| step.reject! { |_name, value| value.is_a?(String) && value.match?(YAML_DUMP) } }
538
+ Result::ObjectList.new(steps)
539
+ end
540
+
355
541
  # 2.1/2.2 Initiate a workorder (async / synchronous)
356
542
  def action_workflows_list(**)
357
543
  Result::ObjectList.new(
@@ -360,17 +546,28 @@ module Aspera
360
546
  )
361
547
  end
362
548
 
363
- # The document is read from GitHub: does not require access to Orchestrator
549
+ # The documents of `workflows development` are read from GitHub: does not require access to Orchestrator
550
+ # @param document [Symbol] One of DOC_URLS keys
551
+ # @return [String] Markdown
552
+ def development_document(document)
553
+ require_relative '../../uri_reader'
554
+ UriReader.read_first(DOC_URLS[document], what: "document #{document}") do |text|
555
+ Aspera.assert(!HTML_PAGE.match?(text), type: Cli::Error) { 'HTML page instead of Markdown' }
556
+ text
557
+ end
558
+ end
559
+
364
560
  # @param level [Integer, nil] Maximum level of headings of the table of contents (default per document)
365
- def action_workflows_development(document: :authoring, section: nil, level: nil, **)
366
- require 'aspera/markdown'
367
- require 'aspera/uri_reader'
368
- Aspera.assert(level.nil? || section.eql?(DOC_TOC), type: Cli::BadArgument) { "argument level is only for #{DOC_TOC}" }
369
- content = UriReader.read("#{DOC_BASE_URL}/#{DOC_FILES[document]}")
370
- return Result::Text.new(content) if section.nil?
371
- return Result::ObjectList.new(Markdown.toc(content, max_level: level || DOC_TOC_LEVELS[document]), fields: %w[level title anchor]) if section.eql?(DOC_TOC)
372
- text = Markdown.extract_section(content, section)
373
- Aspera.assert(!text.nil?, type: Cli::Error) { "Section not found: #{section}, use #{DOC_TOC} to list anchors" }
561
+ def development_toc(document, level)
562
+ require_relative '../../markdown'
563
+ Result::ObjectList.new(Markdown.toc(development_document(document), max_level: level || DOC_TOC_LEVELS[document]), fields: %w[level title anchor])
564
+ end
565
+
566
+ # @param anchor [String] Anchor of the section, see `toc`
567
+ def development_section(document, anchor)
568
+ require_relative '../../markdown'
569
+ text = Markdown.extract_section(development_document(document), anchor)
570
+ Aspera.assert(!text.nil?, type: Cli::Error) { "Section not found: #{anchor}, use `toc` to list anchors" }
374
571
  Result::Text.new(text)
375
572
  end
376
573
 
@@ -378,22 +575,25 @@ module Aspera
378
575
  # @return [Hash] Class name of plugin => attributes, inputs, outputs
379
576
  def plugin_specs
380
577
  return @plugin_specs if @plugin_specs
381
- require 'aspera/uri_reader'
382
- require 'aspera/yaml'
578
+ require_relative '../../uri_reader'
579
+ require_relative '../../yaml'
383
580
  specs = Yaml.safe_load(UriReader.read(options.get_option(:plugin_specs, mandatory: true)))
384
581
  Aspera.assert_type(specs, Hash, type: Cli::Error) { 'plugin specifications' }
385
582
  @plugin_specs = specs
386
583
  end
387
584
 
388
- # @param plugin [String, nil] Class name of the plugin (case insensitive), or nil to list plugins
585
+ def plugin_spec_toc
586
+ Result::ObjectList.new(plugin_specs.map { |name, spec| {'name' => name}.merge(spec.except(*SPEC_SECTIONS.map(&:to_s), 'notes')) }, fields: SPEC_LIST_FIELDS)
587
+ end
588
+
589
+ # @param plugin [String] Class name of the plugin (case insensitive)
389
590
  # @param section [Symbol, nil] One of SPEC_SECTIONS, or nil for the whole specification
390
- def action_plugins_spec(plugin: nil, section: nil, **)
591
+ def plugin_spec_show(plugin, section)
391
592
  specs = plugin_specs
392
- return Result::ObjectList.new(specs.map { |name, spec| {'name' => name}.merge(spec.except(*SPEC_SECTIONS.map(&:to_s), 'notes')) }, fields: SPEC_LIST_FIELDS) if plugin.nil?
393
593
  name = specs.keys.find { |key| key.casecmp?(plugin) }
394
594
  if name.nil?
395
595
  similar = specs.keys.select { |key| key.downcase.include?(plugin.downcase) }
396
- raise Cli::BadArgument, "Unknown plugin: #{plugin}#{", similar: #{similar.join(', ')}" unless similar.empty?}, use `plugins spec` to list plugins"
596
+ raise Cli::BadArgument, "Unknown plugin: #{plugin}#{", similar: #{similar.join(', ')}" unless similar.empty?}, use `plugins spec toc` to list plugins"
397
597
  end
398
598
  return Result::SingleObject.new({'name' => name}.merge(specs[name])) if section.nil?
399
599
  Result::ObjectList.new(specs[name][section.to_s].map { |key, value| {'name' => key}.merge(value) })
@@ -424,11 +624,12 @@ module Aspera
424
624
  # When it has one (same request as `import_workflow`), replace the body by a call, e.g.
425
625
  # `call_ao('check_workflow', body: [['import_file', content, {filename: file_name}], ['import_file_name', file_name]], content_type: Mime::MULTIPART)`
426
626
  # The response is a Hash, see {OrchestratorWorkflowChecker}.
427
- # Templates and inputs of steps are checked with the specifications of plugins (see `plugins spec`), when they can be read.
428
- # @param file_path [String] Workflow file (`.yml` or `.wkf`)
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_name [String] Name of the workflow file (`.yml` or `.wkf`)
629
+ # @param content [String] Bytes of the file
429
630
  # @return [Hash] `valid` (Boolean), `file_name`, `issues` (list of Hash: `severity`, `code`, `file`, `path`, `message`)
430
- def check_workflow(file_path)
431
- require 'aspera/orchestrator_workflow_checker'
631
+ def check_workflow(file_name, content)
632
+ require_relative '../../orchestrator_workflow_checker'
432
633
  specs = nil
433
634
  specs_error = nil
434
635
  begin
@@ -436,7 +637,7 @@ module Aspera
436
637
  rescue StandardError => e
437
638
  specs_error = e.message
438
639
  end
439
- 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)
440
641
  unless specs_error.nil?
441
642
  response['issues'].push({
442
643
  'severity' => 'warning',
@@ -448,10 +649,11 @@ module Aspera
448
649
  response
449
650
  end
450
651
 
652
+ # The file is read as `@file:`: the issues show parts of its content
451
653
  # @param file_path [String] Workflow file
452
654
  # @return [Result] The issues found, or a status if none
453
655
  def action_workflows_check_import(file_path:, **)
454
- response = check_workflow(file_path)
656
+ response = check_workflow(File.basename(file_path), Security.instance.read_file(file_path, binmode: true))
455
657
  return Result::Status.new('no problem found') if response['issues'].empty?
456
658
  Result::ObjectList.new(response['issues'], fields: %w[severity code file path message])
457
659
  end
@@ -504,15 +706,17 @@ module Aspera
504
706
  end
505
707
 
506
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`
507
710
  # @param import [Hash] Options: `folder_id`, `publish`, `link_to_subworkflows`
508
711
  def action_workflows_import(file_path:, import: {}, **)
509
712
  import = import.transform_keys(&:to_s)
510
- 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|
511
716
  Log.log.warn { "#{issue['severity']}: #{[issue['file'], issue['path']].compact.join(' ')}: #{issue['message']} (#{issue['code']})" }
512
717
  end
513
- file_name = File.basename(file_path)
514
718
  form = [
515
- ['import_file', File.binread(file_path), {filename: file_name}],
719
+ ['import_file', content, {filename: file_name}],
516
720
  ['import_file_name', file_name]
517
721
  ]
518
722
  form.push(['folder_id', import['folder_id'].to_s]) if import.key?('folder_id')