aspera-cli 4.27.5 → 4.29.0

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 (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  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 +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  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 +8 -5
  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 +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  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 +354 -0
  41. data/lib/aspera/ascp/management.rb +102 -48
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +16 -37
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  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 +11 -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 +4 -1
  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 +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -1,3 +1,4 @@
1
+ # cspell:ignore cksum parentrid peerxfer SSDB SSSTATE xferres
1
2
  # Schema for the SQLite tables inside the Async snap database (snap.db).
2
3
  # Sources:
3
4
  # include/async/session/Sqlite3_SSDB.h (SYNC_SQLITE3_META_SCHEMA, SYNC_SQLITE3_COUNTERS_SCHEMA, SYNC_SQLITE3_SCHEMA_1_0)
@@ -14,19 +15,19 @@ properties:
14
15
  description: One row per session, written at start and updated at stop.
15
16
  type: object
16
17
  properties:
17
- dbversion:
18
+ dbversion: # cspell:disable-line
18
19
  description: Database schema version.
19
20
  type: string
20
- pairname:
21
+ pairname: # cspell:disable-line
21
22
  description: Sync session name.
22
23
  type: string
23
- ldir:
24
+ ldir: # cspell:disable-line
24
25
  description: Local directory path.
25
26
  type: string
26
- rhost:
27
+ rhost: # cspell:disable-line
27
28
  description: Remote host.
28
29
  type: string
29
- rdir:
30
+ rdir: # cspell:disable-line
30
31
  description: Remote directory path.
31
32
  type: string
32
33
  direction:
@@ -68,7 +69,7 @@ properties:
68
69
  sync_point:
69
70
  description: Synchronization point sequence number.
70
71
  type: integer
71
- max_recid:
72
+ max_recid: # cspell:disable-line
72
73
  description: Highest record ID allocated in the snapshot table.
73
74
  type: integer
74
75
  sync_uuid:
@@ -308,7 +309,7 @@ properties:
308
309
  f_cont_timestamp:
309
310
  description: Filesystem content — internal timestamp.
310
311
  type: integer
311
- pcr_reqno:
312
+ pcr_reqno: # cspell:disable-line
312
313
  description: Peer content request sequence number.
313
314
  type: integer
314
315
  pp_cont_size:
@@ -323,7 +324,7 @@ properties:
323
324
  pp_cont_timestamp:
324
325
  description: Peer pending content — internal timestamp.
325
326
  type: integer
326
- tobe_deleted:
327
+ tobe_deleted: # cspell:disable-line
327
328
  description: Set to 1 when the record is flagged for deletion (garbage collection pending).
328
329
  type: integer
329
330
  scn_not_visited:
@@ -338,10 +339,10 @@ properties:
338
339
  candidate_in_prog:
339
340
  description: Set to 1 when this record is currently in the candidate transfer list.
340
341
  type: integer
341
- meta_lastreq_no:
342
+ meta_lastreq_no: # cspell:disable-line
342
343
  description: Sequence number of the last metadata request sent.
343
344
  type: integer
344
- meta_lastresp_no:
345
+ meta_lastresp_no: # cspell:disable-line
345
346
  description: Sequence number of the last metadata response received.
346
347
  type: integer
347
348
  commit_version:
@@ -1,11 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/agent/factory'
4
- require 'aspera/markdown'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
5
 
6
6
  module Aspera
7
7
  module Schema
8
- # Generate documentation from Schema, for Transfer Spec, or async Conf spec
8
+ # Generate documentation from a JSON Schema: in terminal and in manual.
9
+ # Information from `x-` extensions is provided by the caller (`annotate`).
9
10
  class Documentation
10
11
  # Map JSON Schema type names to user-friendly display names
11
12
  JSON_TYPE_TO_DOC = {
@@ -16,19 +17,21 @@ module Aspera
16
17
  'array' => 'Array',
17
18
  'object' => 'Hash'
18
19
  }.freeze
19
- # @param formatter [Cli::Formatter] Formatter instance with methods: markdown_text, tick, check_row
20
- # @param schema [Reader]
21
- # @param include_option [Boolean] `true`: include CLI options (switches, env vars) in descriptions
22
- # @param agent_columns [Boolean] `true`: add separate columns for each transfer agent compatibility
20
+ COLUMNS = %w[name type description].freeze
21
+ # @param formatter [FormatterInterface] Formatter with methods: markdown_text, special_format
22
+ # @param schema [Reader]
23
23
  # @param code_highlight [Boolean] `true`: format name and type as code
24
- def initialize(formatter, schema, include_option: false, agent_columns: false, code_highlight: false)
24
+ # @param annotate [Proc, nil] Called with the schema of a property (`Hash`) and the formatter.
25
+ # Returns lines added to the description (`Array<String>`), or `nil` to hide the property.
26
+ # @param extra_columns [Hash{String => Proc}] Columns inserted before the description: name => Proc
27
+ # called with the schema of a property (`Hash`) and the formatter, returns the value of the cell.
28
+ def initialize(formatter, schema, code_highlight: false, annotate: nil, extra_columns: {})
25
29
  @formatter = formatter
26
30
  @schema = schema
27
- @include_option = include_option
28
- @agent_columns = agent_columns
29
31
  @code_highlight = code_highlight
30
- @columns = %w[name type description]
31
- @columns.insert(-2, *Agent::Factory::ALL.values.map { |i| i[:short].to_s }.sort) if @agent_columns
32
+ @annotate = annotate
33
+ @extra_columns = extra_columns
34
+ @columns = COLUMNS.dup.insert(-2, *extra_columns.keys).freeze
32
35
  # Sections: each entry is {header: row_or_nil, rows: []}
33
36
  # A flat schema produces a single section with no header.
34
37
  @sections = [{header: nil, rows: []}]
@@ -36,7 +39,7 @@ module Aspera
36
39
 
37
40
  def rows
38
41
  @sections.flat_map do |section|
39
- sorted = section[:rows].sort_by { |i| i['name'] }
42
+ sorted = section[:rows].sort_by { |i| i['name'].delete('`') }
40
43
  section[:header] ? [section[:header]] + sorted : sorted
41
44
  end
42
45
  end
@@ -50,7 +53,7 @@ module Aspera
50
53
  [@columns] + rows.map { |row| @columns.map { |field| row[field] } }
51
54
  end
52
55
 
53
- # Generate a documentation table from a JSON schema for transfer specifications
56
+ # Generate a documentation table from a JSON schema
54
57
  #
55
58
  # Recursively processes a JSON schema to create a formatted table for manual documentation.
56
59
  # Handles nested objects, arrays, and extracts metadata (descriptions, types, enums, deprecations).
@@ -60,88 +63,63 @@ module Aspera
60
63
  def build(schema = nil)
61
64
  code = @code_highlight ? ->(c) { "`#{c}`" } : ->(c) { c }
62
65
  schema ||= @schema
63
- render_title = ->(title) { title.gsub(Markdown::FORMATS) { @formatter.markdown_text(Regexp.last_match) } }
64
66
  on_variant = ->(variant_reader, discriminant_property, discriminant_value) do
65
67
  title = variant_reader.current['title'] || variant_reader.current['description']
66
68
  header =
67
69
  if discriminant_property && discriminant_value
68
- desc = render_title.call("`#{discriminant_value}`")
69
- desc += ": #{render_title.call(title)}" if title
70
- @formatter.check_row({
71
- 'name' => render_title.call("**#{discriminant_property}**"),
70
+ desc = @formatter.markdown_text("`#{discriminant_value}`")
71
+ desc += ": #{@formatter.markdown_text(title)}" if title
72
+ {
73
+ 'name' => @formatter.markdown_text("**#{discriminant_property}**"),
72
74
  'type' => code.call(JSON_TYPE_TO_DOC['string']),
73
75
  'description' => desc
74
- })
76
+ }
75
77
  elsif title
76
- @formatter.check_row({'name' => "**#{render_title.call(title)}**", 'type' => '&nbsp;', 'description' => '&nbsp;'})
78
+ {'name' => @formatter.markdown_text("**#{title}**")}
77
79
  end
78
80
  @sections.push({header: header, rows: []})
79
81
  end
80
- schema.each_property(on_variant: on_variant) do |property_schema, _name, property_full_name|
82
+ schema.each_property(on_variant: on_variant) do |property_schema, _name, property_full_name, required|
81
83
  node = property_schema.current
82
- # Manual table
83
- item_type =
84
- if node['type'].is_a?(Array)
85
- node['type'].map { |t| JSON_TYPE_TO_DOC.fetch(t, t) }.join(', ')
86
- elsif node['type'].eql?('array') && node.dig('items', 'type').is_a?(String)
87
- "#{JSON_TYPE_TO_DOC.fetch(node['type'], node['type'])}[#{JSON_TYPE_TO_DOC.fetch(node.dig('items', 'type'), node.dig('items', 'type'))}]"
88
- else
89
- JSON_TYPE_TO_DOC.fetch(node['type'], node['type'])
90
- end
91
- item = {
92
- 'name' => code.call(property_full_name),
93
- 'type' => code.call(item_type),
94
- 'description' => []
95
- }
84
+ annotations = @annotate ? @annotate.call(node, @formatter) : []
85
+ next if annotations.nil?
86
+ item = {'name' => code.call(property_full_name)}
87
+ item_type = type_text(node)
88
+ item_type = "Enum[#{item_type}]" if node.key?('enum') && !item_type.nil?
89
+ item['type'] = code.call(item_type) unless item_type.nil?
90
+ @extra_columns.each { |column, value| item[column] = value.call(node, @formatter) }
91
+ description = []
92
+ description.push("DEPRECATED: #{node['x-deprecation']}") if node.key?('x-deprecation')
96
93
  # Render Markdown formatting and split lines
97
- item['description'] =
98
- node['description']
99
- .gsub(Markdown::FORMATS) { @formatter.markdown_text(Regexp.last_match) }
100
- .split("\n") if node.key?('description')
101
- item['description'].unshift("DEPRECATED: #{node['x-deprecation']}") if node.key?('x-deprecation')
102
- # Add flags for supported agents in doc
103
- agents = []
104
- Agent::Factory::ALL.each_key do |sym|
105
- agents.push(sym) if node['x-agents'].nil? || node['x-agents'].include?(sym.to_s)
106
- end
107
- Aspera.assert(agents.include?(:direct)) { "#{property_full_name}: x-cli-option requires agent direct (or nil)" } if node['x-cli-option']
108
- if @agent_columns
109
- Agent::Factory::ALL.each do |sym, names|
110
- item[names[:short].to_s] = @formatter.tick(agents.include?(sym))
111
- end
112
- else
113
- item['description'].push("(#{agents.map { |i| Agent::Factory::ALL[i][:short].to_s.upcase }.sort.join(', ')})") unless agents.length.eql?(Agent::Factory::ALL.length)
114
- end
115
- # Only keep lines that are usable in supported agents
116
- next if agents.empty?
117
- item['description'].push("Allowed values: #{node['enum'].map { |v| value_text(v) }.join(', ')}.") if node.key?('enum')
118
- item['description'].push("Default: #{value_text(node['default'])}.") if node.key?('default')
119
- item['description'].push("Example: #{value_text(node['example'])}.") if node.key?('example')
120
- if @include_option
121
- envvar_prefix = ''
122
- cli_option =
123
- if node.key?('x-cli-envvar')
124
- envvar_prefix = 'env:'
125
- node['x-cli-envvar']
126
- elsif node['x-cli-switch']
127
- false_part = node.key?('x-cli-false') ? " / #{node['x-cli-false']}" : ''
128
- "#{node['x-cli-option']}#{false_part}"
129
- elsif node['x-cli-option']
130
- arg_type = node.key?('enum') ? '{enum}' : "{#{[node['type']].flatten.join('|')}}"
131
- conversion_tag = node.key?('x-cli-convert') ? 'conversion' : nil
132
- sep = node['x-cli-option'].start_with?('--') ? '=' : ' '
133
- "#{node['x-cli-option']}#{sep}#{"(#{conversion_tag})" if conversion_tag}#{arg_type}"
134
- end
135
- short = node.key?('x-cli-short') ? "(#{node['x-cli-short']})" : nil
136
- item['description'].push("(#{'special:' if node['x-cli-special']}#{envvar_prefix}#{@formatter.markdown_text("`#{cli_option}`")})#{short}") if cli_option
137
- end
138
- @sections.last[:rows].push(@formatter.check_row(item))
94
+ description.concat(@formatter.markdown_text(node['description']).split("\n")) if node.key?('description')
95
+ description.push('Required.') if required
96
+ description.push("Allowed values: #{node['enum'].map { |v| value_text(v) }.join(', ')}.") if node.key?('enum')
97
+ description.push("Default: #{value_text(node['default'])}.") if node.key?('default')
98
+ # OpenAPI 3.1: `examples` array (3.0: `example`)
99
+ example = node.key?('examples') ? Array(node['examples']).first : node['example']
100
+ description.push("Example: #{value_text(example)}.") unless example.nil?
101
+ description.concat(annotations)
102
+ item['description'] = description unless description.empty?
103
+ @sections.last[:rows].push(item)
139
104
  end
140
105
  self
141
106
  end
142
107
 
143
108
  private
144
109
 
110
+ # @param node [Hash] Schema of a property
111
+ # @return [String, nil] Readable type, from `type`, or else from the types of `oneOf` alternatives, `nil` if none
112
+ def type_text(node)
113
+ if node['type'].nil?
114
+ types = Array(node['oneOf']).filter_map { |variant| type_text(variant) }.uniq
115
+ return types.empty? ? nil : types.join(', ')
116
+ end
117
+ return node['type'].map { |t| JSON_TYPE_TO_DOC.fetch(t, t) }.join(', ') if node['type'].is_a?(Array)
118
+ result = JSON_TYPE_TO_DOC.fetch(node['type'], node['type'])
119
+ result = "#{result}[#{type_text(node['items'])}]" if node['type'].eql?('array') && node.dig('items', 'type').is_a?(String)
120
+ result
121
+ end
122
+
145
123
  # Format a schema value (enum, default, example) as code
146
124
  # @param value [Object] value from schema, `nil` for JSON `null`
147
125
  # @return [String]
@@ -1,10 +1,19 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../assert'
7
+
3
8
  module Aspera
4
9
  # base class for plugins modules
5
10
  module Schema
6
11
  # JSON schema reader
7
12
  class Reader
13
+ # Keys of a schema node that provide properties
14
+ PROPERTY_SOURCES = %w[properties allOf oneOf].freeze
15
+ private_constant :PROPERTY_SOURCES
16
+
8
17
  attr_reader :current
9
18
 
10
19
  class << self
@@ -72,14 +81,17 @@ module Aspera
72
81
  # Recursively traverse schema properties with a block.
73
82
  # If the current node has `oneOf`, each variant is traversed in turn and
74
83
  # `on_variant` is called (if given) before each variant's properties.
75
- # @param prefix [String] Prefix for property names (e.g., 'parent.child.')
76
- # @param on_variant [Proc, nil] Called with the variant Reader before its properties
77
- # @yield [property_schema, name, full_name] Yields property info to block
84
+ # @param prefix [String] Prefix for property names (e.g., 'parent.child.')
85
+ # @param on_variant [Proc, nil] Called with the variant Reader before its properties
86
+ # @param parent_required [Array<String>] Names required by the enclosing `oneOf` or `allOf` node
87
+ # @yield [property_schema, name, full_name, required] Yields property info to block
78
88
  # @yieldparam property_schema [Reader] Schema reader for this property
79
89
  # @yieldparam name [String] Property name
80
90
  # @yieldparam full_name [String] Full property name with prefix
91
+ # @yieldparam required [Boolean] `true` if listed in `required` of its object, or of the `oneOf` or `allOf` node that includes it
81
92
  # @return [nil]
82
- def each_property(prefix = '', on_variant: nil, &block)
93
+ def each_property(prefix = '', on_variant: nil, parent_required: [], &block)
94
+ required_names = parent_required + Array(@current['required'])
83
95
  if @current.key?('oneOf')
84
96
  # Build reverse map: $ref -> discriminant value, from discriminator.mapping if present
85
97
  discriminant_by_ref = {}
@@ -94,16 +106,24 @@ module Aspera
94
106
  variant_reader = ref ? resolve_ref(ref) : Reader.new(@root, variant_node)
95
107
  discriminant_value = ref ? discriminant_by_ref[ref] : nil
96
108
  on_variant&.call(variant_reader, discriminant_property, discriminant_value)
97
- variant_reader.each_property(prefix, on_variant: on_variant, &block)
109
+ variant_reader.each_property(prefix, on_variant: on_variant, parent_required: required_names, &block)
98
110
  end
99
111
  return
100
112
  end
101
113
  if @current.key?('allOf')
102
- # Merge all branches: each branch contributes its properties (no variants)
103
- @current['allOf'].each do |branch_node|
104
- ref = branch_node['$ref']
105
- branch_reader = ref ? resolve_ref(ref) : Reader.new(@root, branch_node)
106
- branch_reader.each_property(prefix, on_variant: on_variant, &block)
114
+ # Merge all branches: each branch contributes its properties (no variants).
115
+ # A property is listed once, with its first declaration: a later one may be empty,
116
+ # only to allow the property under `additionalProperties: false`.
117
+ # A property is required if any branch requires it.
118
+ branches = @current['allOf'].map { |branch_node| branch_reader(branch_node) }
119
+ required_names += branches.flat_map { |branch| Array(branch.current['required']) }
120
+ listed = Set.new
121
+ branches.each do |branch|
122
+ # A branch may only constrain properties of other branches, e.g. with `required`
123
+ next unless PROPERTY_SOURCES.any? { |key| branch.current.key?(key) }
124
+ branch.each_property(prefix, on_variant: on_variant, parent_required: required_names) do |property_schema, name, full_name, required|
125
+ yield(property_schema, name, full_name, required) if listed.add?(full_name)
126
+ end
107
127
  end
108
128
  return
109
129
  end
@@ -114,7 +134,7 @@ module Aspera
114
134
  node = property_schema.current
115
135
 
116
136
  # Yield current property to block
117
- yield(property_schema, name, property_full_name)
137
+ yield(property_schema, name, property_full_name, required_names.include?(name))
118
138
 
119
139
  # Recursively process nested structures (`type` is a list for a nullable value, e.g. `[array, 'null']`)
120
140
  types = Array(node['type'])
@@ -140,6 +160,7 @@ module Aspera
140
160
  # description [String] human description (may contain Markdown **bold** / `code`)
141
161
  # default [Object] (optional) default value as native Ruby type
142
162
  # enum [Array] (optional) list of allowed string values
163
+ # complete [String] (optional) kind of value proposed by shell completion (`x-cli-complete`), e.g. `file`
143
164
  #
144
165
  # @return [Array<Hash>]
145
166
  def to_rows
@@ -150,9 +171,22 @@ module Aspera
150
171
 
151
172
  private
152
173
 
174
+ # @param node [Hash] Branch of `allOf` or `oneOf`
175
+ # @return [Reader] Reader on the branch, with `$ref` resolved
176
+ def branch_reader(node)
177
+ node['$ref'] ? resolve_ref(node['$ref']) : Reader.new(@root, node)
178
+ end
179
+
153
180
  # Recursively collect rows from a schema node, passing each property's own
154
181
  # parent `required` array so that only direct-parent membership is checked.
182
+ # Branches of `allOf` are merged: a property is listed once, with its first declaration.
155
183
  def collect_rows(rows, reader, prefix)
184
+ reader.current['allOf']&.each do |branch_node|
185
+ branch_rows = []
186
+ collect_rows(branch_rows, branch_reader(branch_node), prefix)
187
+ listed = rows.to_set { |row| row['name'] }
188
+ rows.concat(branch_rows.reject { |row| listed.include?(row['name']) })
189
+ end
156
190
  return unless reader.current.key?('properties')
157
191
  parent_required = Set.new(Array(reader.current['required']))
158
192
  props_reader = reader.dig('properties')
@@ -176,6 +210,7 @@ module Aspera
176
210
  }
177
211
  row['default'] = node['default'] if node.key?('default')
178
212
  row['enum'] = node['enum'] if node.key?('enum')
213
+ row['complete'] = node['x-cli-complete'] if node.key?('x-cli-complete')
179
214
  rows << row
180
215
  # Recurse into nested object or array-of-objects (`type` is a list for a nullable value)
181
216
  types = Array(node['type'])
@@ -1,8 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../assert'
7
+ require_relative '../yaml'
8
+ require_relative 'reader'
3
9
  require 'singleton'
4
- require 'aspera/yaml'
5
- require 'aspera/schema/reader'
6
10
 
7
11
  module Aspera
8
12
  # base class for plugins modules
@@ -62,16 +66,18 @@ module Aspera
62
66
  aoc: 'aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml',
63
67
  automation: 'aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml',
64
68
  faspex: 'aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml',
65
- faspio: 'aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml',
69
+ faspio: 'aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml',
66
70
  console: 'aspera/schema/IBM Aspera Console-enhanced.yaml',
67
71
  node: 'aspera/schema/IBM Aspera Node API-4.4.6.yaml',
68
72
  shares: 'aspera/schema/IBM_Aspera_Shares.yaml',
69
- orchestrator: 'aspera/schema/IBM Aspera Orchestrator API-v1.yaml',
70
- async_tables: 'aspera/schema/async_tables.yaml'
71
- }
73
+ orchestrator: 'aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml',
74
+ async_tables: 'aspera/schema/async_tables.yaml',
75
+ ascp_log: 'aspera/ascp/log.schema.yaml',
76
+ transferd: 'aspera/schema/transferd-config.schema.json'
77
+ }.freeze
72
78
 
73
79
  # Schemas owned by ascli: values are validated against them (vendor API schemas are validated by the API)
74
- OWNED = %i[spec args conf opts preview async_tables].freeze
80
+ OWNED = %i[spec args conf opts preview async_tables ascp_log transferd].freeze
75
81
 
76
82
  OPTIONS = 'opts'
77
83
  TRANSFER_SPEC = 'spec'
@@ -87,20 +93,35 @@ module Aspera
87
93
  ORCHESTRATOR = 'orchestrator'
88
94
  SHARES = 'shares+/api/v1'
89
95
  ASYNC_TABLES = 'async_tables'
90
- LOG_OPTIONS = "#{OPTIONS}:components.schemas.LogOptions"
91
- DIRECT_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.DirectAgentOptions"
92
- NODE_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.NodeAgentOptions"
93
- NODE_EMULATOR_OPTIONS = "#{OPTIONS}:components.schemas.NodeEmulatorOptions"
94
- HTTPGW_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.HttpgwAgentOptions"
95
- TRANSFERD_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferdAgentOptions"
96
- TRANSFER_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferAgentOptions"
97
- SMTP_OPTIONS = "#{OPTIONS}:components.schemas.SmtpOptions"
98
- HTTP_OPTIONS = "#{OPTIONS}:components.schemas.HttpOptions"
99
- VAULT_OPTIONS = "#{OPTIONS}:components.schemas.VaultOptions"
100
- VAULT_SECRET = "#{OPTIONS}:components.schemas.VaultSecret"
101
- IMAGE_OPTIONS = "#{OPTIONS}:components.schemas.ImageOptions"
102
- OUT_OPTIONS = "#{OPTIONS}:components.schemas.OutOptions"
103
- PACKAGE_FOLDER_OPTIONS = "#{OPTIONS}:components.schemas.PackageFolderOptions"
96
+ ASCP_LOG = 'ascp_log'
97
+ LOG_OPTIONS = "#{OPTIONS}:components.schemas.LogOptions".freeze
98
+ UI_OPTIONS = "#{OPTIONS}:components.schemas.UiOptions".freeze
99
+ SECURITY_OPTIONS = "#{OPTIONS}:components.schemas.SecurityOptions".freeze
100
+ TEMP_OPTIONS = "#{OPTIONS}:components.schemas.TempOptions".freeze
101
+ DIRECT_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.DirectAgentOptions".freeze
102
+ NODE_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.NodeAgentOptions".freeze
103
+ NODE_EMULATOR_OPTIONS = "#{OPTIONS}:components.schemas.NodeEmulatorOptions".freeze
104
+ HTTPGW_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.HttpgwAgentOptions".freeze
105
+ TRANSFERD_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferdAgentOptions".freeze
106
+ TRANSFER_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferAgentOptions".freeze
107
+ SMTP_OPTIONS = "#{OPTIONS}:components.schemas.SmtpOptions".freeze
108
+ SERVICE_OPTIONS = "#{OPTIONS}:components.schemas.ServiceOptions".freeze
109
+ TRANSFERD_SERVICE_CONFIG = "#{OPTIONS}:components.schemas.TransferdServiceConfig".freeze
110
+ HTTP_OPTIONS = "#{OPTIONS}:components.schemas.HttpOptions".freeze
111
+ VAULT_OPTIONS = "#{OPTIONS}:components.schemas.VaultOptions".freeze
112
+ VAULT_SECRET = "#{OPTIONS}:components.schemas.VaultSecret".freeze
113
+ VAULT_STORE = "#{OPTIONS}:components.schemas.VaultStore".freeze
114
+ VAULT_STORES = "#{OPTIONS}:components.schemas.VaultStores".freeze
115
+ DETECT_OPTIONS = "#{OPTIONS}:components.schemas.DetectOptions".freeze
116
+ PRESET_LOOKUP_CRITERIA = "#{OPTIONS}:components.schemas.PresetLookupCriteria".freeze
117
+ WIZARD_OPTIONS = "#{OPTIONS}:components.schemas.WizardOptions".freeze
118
+ IMAGE_OPTIONS = "#{OPTIONS}:components.schemas.ImageOptions".freeze
119
+ ASCP_LOGS_OPTIONS = "#{OPTIONS}:components.schemas.AscpLogsOptions".freeze
120
+ OUT_OPTIONS = "#{OPTIONS}:components.schemas.OutOptions".freeze
121
+ PACKAGE_FOLDER_OPTIONS = "#{OPTIONS}:components.schemas.PackageFolderOptions".freeze
122
+ WEB_SERVER_OPTIONS = "#{OPTIONS}:components.schemas.WebServerOptions".freeze
123
+ GATEWAY_OPTIONS = "#{OPTIONS}:components.schemas.Faspex4GatewayOptions".freeze
124
+ POSTPROC_OPTIONS = "#{OPTIONS}:components.schemas.Faspex4PostProcOptions".freeze
104
125
 
105
126
  REQ_BODY = '.requestBody.content.application/json.schema'
106
127
  # Suffix appended to a dotted path to signal query-param extraction in reader()
@@ -113,7 +134,7 @@ module Aspera
113
134
 
114
135
  # Read schema from file or from cache.
115
136
  # When name_path ends with QUERY_PARAMS_SUFFIX, the OAS `parameters` array at that path
116
- # is synthesised into an object schema via Reader.from_query_params instead of navigating
137
+ # is synthesized into an object schema via Reader.from_query_params instead of navigating
117
138
  # into the tree.
118
139
  # @param name_path [String] registry key with optional colon-separated dotted path suffix,
119
140
  # e.g. "faspex:paths./packages.get.parameters" or "faspex:paths./packages.post.requestBody..."
@@ -123,8 +144,8 @@ module Aspera
123
144
  sym = name.to_sym
124
145
  Aspera.assert(Registry.known?(sym)) { "schema: #{sym}" }
125
146
  spec_file = File.join(@main_folder, LOCATIONS[sym])
126
- @cache[sym] = Yaml.safe_load(File.read(spec_file)) if spec_file.end_with?('.yaml') && !@cache.key?(sym)
127
- @cache[sym] = JSON.parse(File.read(spec_file)) if spec_file.end_with?('.json') && !@cache.key?(sym)
147
+ # JSON is read with the YAML loader: it accepts the header comment added by `rake tools:openapi`
148
+ @cache[sym] = Yaml.safe_load(File.read(spec_file)) unless @cache.key?(sym)
128
149
  # Query-params path: strip the suffix, navigate to the operation node, extract parameters
129
150
  if path&.end_with?(QUERY_PARAMS_SUFFIX)
130
151
  parent_path = path.delete_suffix(QUERY_PARAMS_SUFFIX)