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
@@ -0,0 +1,228 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative 'base'
7
+ require_relative '../info'
8
+ require_relative '../special_values'
9
+ require_relative '../../ascp/installation'
10
+ require_relative '../../products/transferd_service'
11
+ require_relative '../../schema/documentation'
12
+ require_relative '../../log'
13
+ require_relative '../../assert'
14
+
15
+ module Aspera
16
+ module Cli
17
+ module Plugins
18
+ # Install the Transfer Daemon (`transferd`), run it as a system service, and query a running daemon
19
+ class Transferd < Base
20
+ application_name 'Transfer Daemon'
21
+
22
+ class << self
23
+ # Seam for the client commands: object that gives `info(params)`, `transfer_status(id, params)` and `transfer_cancel(id, params)`,
24
+ # with `params` a Hash with `url`, and optional `api_key`, `ca_file`.
25
+ # `nil` (default): `Agent::Transferd`, loaded on first use, because it requires the optional gem `grpc`.
26
+ # @return [#info, #transfer_status, #transfer_cancel, nil]
27
+ attr_accessor :daemon_client
28
+ end
29
+
30
+ command :install, description: 'Install the transfer daemon',
31
+ arguments: [{name: :version, mandatory: false, default: nil}]
32
+ command :list, description: 'List available SDK locations'
33
+ command :service, description: 'Manage the transfer daemon as a system service'
34
+ commands_under :service do
35
+ service_config_arg = {name: :config, type: Hash, mandatory: false, default: {}, schema: Schema::Registry::TRANSFERD_SERVICE_CONFIG}
36
+ command(
37
+ :spec, description: 'Show the transfer daemon configuration schema',
38
+ action: lambda do |**|
39
+ builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader('transferd')).build
40
+ Result::ObjectList.new(builder.rows, fields: builder.columns)
41
+ end
42
+ )
43
+ command(
44
+ :install, description: 'Install the SDK if needed, then configure and start the service',
45
+ arguments: [service_config_arg],
46
+ action: ->(config:, **) { transferd_service_install(config) }
47
+ )
48
+ command(
49
+ :configure, description: 'Configure the transfer daemon service',
50
+ arguments: [service_config_arg],
51
+ action: lambda do |config:, **|
52
+ transferd_service do |host, sdk_folder, dry_run|
53
+ steps = Products::TransferdService.configure(config, sdk_folder, host: host, dry_run: dry_run)
54
+ Products::TransferdService.check_version(sdk_folder, host: host)
55
+ transferd_service_steps(steps)
56
+ end
57
+ end
58
+ )
59
+ command(
60
+ :status, description: 'Show the state of the service (the API key is not shown)',
61
+ arguments: [service_config_arg],
62
+ action: lambda do |config:, **|
63
+ transferd_service { |host, sdk_folder, _dry_run| Result::SingleObject.new(Products::TransferdService.status(config, sdk_folder, host: host)) }
64
+ end
65
+ )
66
+ command(
67
+ :uninstall, description: 'Stop and remove the service (service.purge: also remove configuration and logs)',
68
+ arguments: [service_config_arg],
69
+ action: lambda do |config:, **|
70
+ transferd_service do |host, _sdk_folder, dry_run|
71
+ purge = Products::TransferdService.service_options(config)['purge'].eql?(true)
72
+ transferd_service_steps(Products::TransferdService.uninstall(config, host: host, dry_run: dry_run, purge: purge))
73
+ end
74
+ end
75
+ )
76
+ command(
77
+ :use, description: 'Use an installed version of the SDK (SDK folder named current), and restart the service',
78
+ arguments: [{name: :version}, service_config_arg],
79
+ action: lambda do |version:, config:, **|
80
+ transferd_service do |host, sdk_folder, dry_run|
81
+ transferd_service_steps(Products::TransferdService.use(config, sdk_folder, version, host: host, dry_run: dry_run))
82
+ end
83
+ end
84
+ )
85
+ command(
86
+ :versions, description: 'List the installed versions of the SDK (SDK folder named current)',
87
+ action: lambda do |**|
88
+ sdk_folder = options.get_option(:sdk_folder, mandatory: true)
89
+ Result::ObjectList.new(Products::TransferdService.versions(sdk_folder), fields: %w[version folder current])
90
+ end
91
+ )
92
+ end
93
+ command :info, description: 'Show information on a running daemon',
94
+ action: ->(**) { Result::SingleObject.new(daemon_client.info(daemon_params)) }
95
+ command :transfers, description: 'Query the transfers of a running daemon'
96
+ commands_under :transfers do
97
+ command(
98
+ :show, description: 'Show the status of a transfer (the daemon keeps it for some time after its end)',
99
+ arguments: [{name: :transfer_id}],
100
+ action: ->(transfer_id:, **) { Result::SingleObject.new(daemon_client.transfer_status(transfer_id, daemon_params)) }
101
+ )
102
+ command(
103
+ :cancel, description: 'Stop a transfer',
104
+ arguments: [{name: :transfer_id}],
105
+ action: lambda do |transfer_id:, **|
106
+ daemon_client.transfer_cancel(transfer_id, daemon_params)
107
+ Result::Status.new("Transfer #{transfer_id} stopped")
108
+ end
109
+ )
110
+ end
111
+
112
+ option :url, description: 'Client commands: endpoint of the running daemon, e.g. 127.0.0.1:55002'
113
+ option :api_key, description: 'Client commands: API key of the daemon, if its authentication is enabled'
114
+ option :ca_file, description: 'Client commands: certificate authority (PEM file) of the daemon, if its TLS is enabled'
115
+
116
+ # Install the transfer SDK (ascp + transferd) from a URL or using the default source.
117
+ # Version defaults to `Info::SDK_VERSION`; pass `LATEST` as argument to install the latest available version.
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).
121
+ # Also called by the deprecated command `config ascp install`.
122
+ # @param version [String, nil] version to install; nil means use the default SDK version
123
+ # @return [Result::Status] installation result message
124
+ def action_install(version: nil, **)
125
+ asked_version = version.nil? ? Info::SDK_VERSION : version
126
+ asked_version = nil if asked_version.eql?(SpecialValues::LATEST)
127
+ installation = Ascp::Installation.instance
128
+ url = sdk_url_option
129
+ if url.nil?
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']
135
+ end
136
+ name, ver, folder = installation.install_sdk(url: url, version: asked_version)
137
+ return Result::Status.new("Installed #{name} version #{ver} in #{folder}")
138
+ end
139
+
140
+ # @return [Result::ObjectList] The SDK locations
141
+ def action_list(**)
142
+ sdk_list = Ascp::Installation.instance.sdk_locations
143
+ Result::ObjectList.new(sdk_list, fields: sdk_list.first.keys - ['url'])
144
+ end
145
+
146
+ private
147
+
148
+ # @return [#info, #transfer_status, #transfer_cancel] The client of the daemon
149
+ # @raise [Cli::Error] if the optional gem `grpc` is missing
150
+ def daemon_client
151
+ injected = self.class.daemon_client
152
+ return injected unless injected.nil?
153
+ begin
154
+ require_relative '../../agent/transferd'
155
+ rescue LoadError => e
156
+ raise Cli::Error, "Commands that query a running daemon require the gem grpc (#{e.message}). Install it with: gem install grpc"
157
+ end
158
+ Agent::Transferd
159
+ end
160
+
161
+ # Parameters of the connection to the daemon: option `url` is mandatory, `api_key` and `ca_file` are optional.
162
+ # Options `url`, `api_key` and `ca_file` have priority, else the same keys of option `transfer` are used, if its agent is `transferd`.
163
+ # @return [Hash]
164
+ def daemon_params
165
+ from_transfer = transfer_agent_params
166
+ params = %w[url api_key ca_file].to_h { |key| [key, options.get_option(key.to_sym) || from_transfer[key]] }.compact
167
+ Aspera.assert(params.key?('url'), type: Cli::BadArgument) do
168
+ "Missing option #{Parser.option_name_to_line(:url)} (or #{Parser.option_name_to_line(:transfer)} with agent transferd and key url)"
169
+ end
170
+ return params
171
+ end
172
+
173
+ # @return [Hash] Keys `url`, `api_key`, `ca_file` of option `transfer`, only if its agent is `transferd`, else empty
174
+ def transfer_agent_params
175
+ transfer_options = transfer.transfer_options
176
+ return {} unless transfer_options['agent'].to_s.eql?('transferd')
177
+ return transfer_options.slice('url', 'api_key', 'ca_file')
178
+ end
179
+
180
+ # @return [String, nil] Value of option `sdk_url`, or nil to select the archive from the SDK locations (`DEF`)
181
+ def sdk_url_option
182
+ sdk_url = options.get_option(:sdk_url, mandatory: true)
183
+ return sdk_url.eql?(SpecialValues::DEF) ? nil : sdk_url
184
+ end
185
+
186
+ # Common processing of the commands of `transferd service` that act on the system.
187
+ # Refuses to run if the system is not supported or the user is not root, unless `--dry-run=yes`.
188
+ # @yieldparam host [Products::TransferdService::Host] Access to the system
189
+ # @yieldparam sdk_folder [String] Option `sdk_folder`, or link `current` of the layout
190
+ # @yieldparam dry_run [Boolean] Option `dry_run`
191
+ def transferd_service
192
+ host = Products::TransferdService::Host.new
193
+ dry_run = options.get_option(:dry_run)
194
+ Products::TransferdService.assert_supported(host, dry_run: dry_run)
195
+ sdk_folder = options.get_option(:sdk_folder, mandatory: true)
196
+ Aspera.assert(!Ascp::Installation.product_selector?(sdk_folder), type: Cli::BadArgument) { 'The service requires a SDK folder, not a product' }
197
+ yield(host, sdk_folder, dry_run)
198
+ end
199
+
200
+ # @param steps [Array<String>] Actions done, or to do with `--dry-run=yes`
201
+ # @return [Result] The list of actions, or a message if there is nothing to do
202
+ def transferd_service_steps(steps)
203
+ steps.empty? ? Result::Status.new('Nothing to do') : Result::ValueList.new(steps, name: 'action')
204
+ end
205
+
206
+ # Implementation of `transferd service install`
207
+ # With the layout (SDK folder named `current`), the SDK is installed in a folder of the version, next to the link.
208
+ # @param config [Hash] `CONFIG`
209
+ def transferd_service_install(config)
210
+ transferd_service do |host, sdk_folder, dry_run|
211
+ version = Products::TransferdService.service_options(config)['version'] || Info::SDK_VERSION
212
+ sdk_url = sdk_url_option
213
+ installation = Ascp::Installation.instance
214
+ install_sdk =
215
+ if Products::TransferdService.layout?(sdk_folder)
216
+ ->(folder) { installation.install_sdk(url: sdk_url, version: version, folder: folder) }
217
+ else
218
+ -> { installation.install_sdk(url: sdk_url, version: version) }
219
+ end
220
+ steps = Products::TransferdService.install(config, sdk_folder, host: host, dry_run: dry_run, install_sdk: install_sdk, version: version)
221
+ Products::TransferdService.check_version(sdk_folder, host: host)
222
+ transferd_service_steps(steps)
223
+ end
224
+ end
225
+ end
226
+ end
227
+ end
228
+ end
@@ -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