aspera-cli 4.28.0 → 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 (237) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +143 -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 +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1633 -609
  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 +20 -20
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +71 -65
  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 +16 -8
  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 +12 -19
  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 -33
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +6 -1
  50. data/lib/aspera/cli/command_spec.rb +34 -7
  51. data/lib/aspera/cli/completion/ascli.bash +19 -5
  52. data/lib/aspera/cli/completion/ascli.fish +13 -2
  53. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  54. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  55. data/lib/aspera/cli/completion_actions.rb +303 -69
  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 +3 -0
  59. data/lib/aspera/cli/extended_value.rb +61 -27
  60. data/lib/aspera/cli/formatter.rb +29 -22
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -10
  63. data/lib/aspera/cli/http.rb +12 -9
  64. data/lib/aspera/cli/info.rb +12 -7
  65. data/lib/aspera/cli/mailer.rb +6 -3
  66. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  67. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  68. data/lib/aspera/cli/mcp/tool.rb +15 -14
  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 +65 -12
  73. data/lib/aspera/cli/options.schema.yaml +487 -63
  74. data/lib/aspera/cli/parser.rb +56 -32
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +244 -35
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +17 -12
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +198 -103
  81. data/lib/aspera/cli/plugins/console.rb +6 -3
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +21 -7
  84. data/lib/aspera/cli/plugins/faspex5.rb +28 -25
  85. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  86. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +28 -22
  88. data/lib/aspera/cli/plugins/node.rb +31 -30
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +63 -11
  93. data/lib/aspera/cli/plugins/shares.rb +86 -16
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +144 -30
  96. data/lib/aspera/cli/preset_manager.rb +52 -18
  97. data/lib/aspera/cli/prompt.rb +4 -1
  98. data/lib/aspera/cli/result.rb +12 -8
  99. data/lib/aspera/cli/runner.rb +69 -46
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +79 -9
  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 +3 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +29 -20
  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 +188 -42
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.rb +12 -10
  113. data/lib/aspera/cli/wizard.rb +42 -39
  114. data/lib/aspera/command_line_builder.rb +9 -5
  115. data/lib/aspera/command_line_converter.rb +4 -1
  116. data/lib/aspera/coverage.rb +103 -33
  117. data/lib/aspera/data_repository.rb +4 -1
  118. data/lib/aspera/dot_container.rb +4 -1
  119. data/lib/aspera/duration.rb +5 -2
  120. data/lib/aspera/environment.rb +21 -12
  121. data/lib/aspera/exec_spec.rb +3 -0
  122. data/lib/aspera/faspex_gw.rb +13 -9
  123. data/lib/aspera/faspex_postproc.rb +15 -12
  124. data/lib/aspera/formatter_interface.rb +4 -1
  125. data/lib/aspera/graphql.rb +5 -1
  126. data/lib/aspera/hash_ext.rb +3 -0
  127. data/lib/aspera/id_generator.rb +4 -2
  128. data/lib/aspera/json_rpc/client.rb +6 -5
  129. data/lib/aspera/json_rpc/version.rb +3 -0
  130. data/lib/aspera/line_logger.rb +4 -1
  131. data/lib/aspera/link_header.rb +4 -1
  132. data/lib/aspera/log.rb +18 -5
  133. data/lib/aspera/markdown.rb +5 -2
  134. data/lib/aspera/mime.rb +3 -0
  135. data/lib/aspera/nagios.rb +6 -4
  136. data/lib/aspera/node_emulator.rb +15 -13
  137. data/lib/aspera/oauth/client/base.rb +91 -70
  138. data/lib/aspera/oauth/client/boot.rb +7 -4
  139. data/lib/aspera/oauth/client/factory.rb +6 -3
  140. data/lib/aspera/oauth/client/generic.rb +5 -1
  141. data/lib/aspera/oauth/client/json_credentials.rb +4 -1
  142. data/lib/aspera/oauth/client/jwt.rb +6 -3
  143. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  144. data/lib/aspera/oauth/client/url_json.rb +4 -1
  145. data/lib/aspera/oauth/client/web.rb +39 -12
  146. data/lib/aspera/oauth/server/pkce.rb +6 -5
  147. data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
  148. data/lib/aspera/persistency_action_once.rb +5 -3
  149. data/lib/aspera/persistency_folder.rb +6 -3
  150. data/lib/aspera/preview/file_types.rb +6 -3
  151. data/lib/aspera/preview/generator.rb +9 -5
  152. data/lib/aspera/preview/options.schema.yaml +3 -3
  153. data/lib/aspera/preview/terminal.rb +8 -4
  154. data/lib/aspera/preview/utils.rb +6 -4
  155. data/lib/aspera/products/connect.rb +5 -2
  156. data/lib/aspera/products/desktop.rb +4 -1
  157. data/lib/aspera/products/other.rb +4 -2
  158. data/lib/aspera/products/transferd.rb +6 -2
  159. data/lib/aspera/products/transferd_service.rb +610 -0
  160. data/lib/aspera/proxy_auto_config.js +2 -2
  161. data/lib/aspera/proxy_auto_config.rb +5 -2
  162. data/lib/aspera/rainbow.rb +3 -0
  163. data/lib/aspera/rest/aspera_errors.rb +4 -1
  164. data/lib/aspera/rest/call_error.rb +3 -0
  165. data/lib/aspera/rest/client.rb +22 -29
  166. data/lib/aspera/rest/error_analyzer.rb +5 -2
  167. data/lib/aspera/rest/list.rb +8 -4
  168. data/lib/aspera/rest/parameters.rb +3 -0
  169. data/lib/aspera/rest/util.rb +8 -5
  170. data/lib/aspera/rest.rb +9 -6
  171. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  172. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  173. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  174. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  175. data/lib/aspera/schema/async_tables.yaml +11 -10
  176. data/lib/aspera/schema/documentation.rb +8 -2
  177. data/lib/aspera/schema/reader.rb +7 -0
  178. data/lib/aspera/schema/registry.rb +43 -28
  179. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  180. data/lib/aspera/schema/validator.rb +4 -1
  181. data/lib/aspera/sealed_hash.rb +166 -0
  182. data/lib/aspera/secret/hider.rb +201 -0
  183. data/lib/aspera/secret/reference.rb +150 -0
  184. data/lib/aspera/secret/resolver.rb +212 -0
  185. data/lib/aspera/secret/store/base.rb +153 -0
  186. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  187. data/lib/aspera/secret/store/factory.rb +103 -0
  188. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  189. data/lib/aspera/secret/store/keeper.rb +141 -0
  190. data/lib/aspera/secret/store/macos_security.rb +284 -0
  191. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  192. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  193. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  194. data/lib/aspera/secret/store/secret_service.rb +125 -0
  195. data/lib/aspera/secret/strength.rb +119 -0
  196. data/lib/aspera/servlet_helpers.rb +5 -2
  197. data/lib/aspera/ssh.rb +10 -7
  198. data/lib/aspera/ssl.rb +5 -2
  199. data/lib/aspera/string_ext.rb +3 -0
  200. data/lib/aspera/sync/args.schema.yaml +3 -0
  201. data/lib/aspera/sync/conf.schema.yaml +9 -4
  202. data/lib/aspera/sync/database.rb +3 -0
  203. data/lib/aspera/sync/operations.rb +16 -14
  204. data/lib/aspera/temp_file_manager.rb +8 -4
  205. data/lib/aspera/timer_limiter.rb +3 -0
  206. data/lib/aspera/transfer/error.rb +4 -1
  207. data/lib/aspera/transfer/faux_file.rb +4 -1
  208. data/lib/aspera/transfer/parameters.rb +17 -14
  209. data/lib/aspera/transfer/result.rb +3 -0
  210. data/lib/aspera/transfer/resumer.rb +6 -4
  211. data/lib/aspera/transfer/spec.rb +9 -22
  212. data/lib/aspera/transfer/units.rb +75 -0
  213. data/lib/aspera/uri_reader.rb +57 -7
  214. data/lib/aspera/web_auth/index.html.erb +6 -2
  215. data/lib/aspera/web_auth/paste.rb +109 -0
  216. data/lib/aspera/web_auth/receiver.rb +50 -0
  217. data/lib/aspera/web_auth/relay.rb +76 -0
  218. data/lib/aspera/web_auth/reply.html.erb +150 -0
  219. data/lib/aspera/web_auth/server.rb +47 -10
  220. data/lib/aspera/web_page.rb +7 -2
  221. data/lib/aspera/web_server_simple.rb +6 -3
  222. data/lib/aspera/yaml.rb +5 -1
  223. data/llms.txt +81 -0
  224. data/skills/ascli/SKILL.md +88 -0
  225. data.tar.gz.sig +0 -0
  226. metadata +72 -19
  227. metadata.gz.sig +0 -0
  228. data/lib/aspera/keychain/base.rb +0 -30
  229. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  230. data/lib/aspera/keychain/factory.rb +0 -58
  231. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  232. data/lib/aspera/keychain/macos_security.rb +0 -277
  233. data/lib/aspera/keychain/one_password_api.rb +0 -91
  234. data/lib/aspera/keychain/one_password_base.rb +0 -39
  235. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  236. data/lib/aspera/secret_hider.rb +0 -196
  237. data/lib/aspera/secret_strength.rb +0 -114
@@ -0,0 +1,354 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ # cspell:ignore asperascp asws getname lastlog lsass pcap tokengen trapd userdata winuser wtmp
7
+ require_relative '../assert'
8
+ require_relative '../log'
9
+ require_relative 'log_analyzer/log_file'
10
+ require_relative 'log_analyzer/records'
11
+ require 'resolv'
12
+ require 'set'
13
+ require 'stringio'
14
+ require 'time'
15
+ require 'zlib'
16
+
17
+ module Aspera
18
+ module Ascp
19
+ # Analysis of ascp transfer logs: sessions, statistics and diagnostics.
20
+ # Results are tables: Hash (one object) or Array of Hash (list of objects).
21
+ class LogAnalyzer
22
+ # Oldest ascp version for which the analysis is designed
23
+ MIN_VERSION = '4.0'
24
+ # Path that designates the standard input
25
+ STDIN_PATH = '-'
26
+ # First two bytes of a gzip file
27
+ GZIP_MAGIC = "\x1F\x8B".b.freeze
28
+ # Files analyzed when scanning a folder
29
+ INCLUDED_FILES = /transfer|messages|log/i
30
+ # Files not analyzed when scanning a folder (path relative to folder)
31
+ EXCLUDED_FILES = %r{async|ssl_|\.dat|\.xml|\.html|graph|winuser|manager|asperascp\.20|background|asws|node|plugin|opt/aspera/var|\.exe|trapd|rtf|lsass|lastlog|wtmp|
32
+ process|stats|production|mongrel|console|ntp\.|prepost|aspx|aspshell|tokengen|userdata|http|asconfigurator|ascmd|\.jpg|\.png|ui\.|connect|ssh|
33
+ stderr|stdout|central|sync|\.zip|\.msi|\.tgz|\.tbz|\.tar|\.rar|\.bz2?|\.pcap|analysis\.txt|\.7z}ix
34
+ # Folders not scanned
35
+ EXCLUDED_FOLDERS = /\$|recycle/i
36
+ # Statistics summed over log files
37
+ SUMMED_STATS = %i[total_sessions success failed cancelled http_fallback smart_reset win_clock retries] + LogFile::FINDINGS.keys
38
+ # Severities of diagnostics, most severe first
39
+ SEVERITIES = %w[error warning info].freeze
40
+ # Maximum values of log files
41
+ MAXIMA = {max_total: 'max_throughput', max_out: 'max_send', max_in: 'max_receive', max_sess: 'max_sessions'}.freeze
42
+
43
+ # Default diagnostic thresholds
44
+ DEFAULT_THRESHOLDS = {
45
+ efficiency: 90.0,
46
+ control_loss_percent: 5.0,
47
+ control_loss_sent: 10,
48
+ retry_window: 3600,
49
+ last_error_window: 60,
50
+ rate_decline_ratio: 0.7,
51
+ rate_decline_min_samples: 10,
52
+ rate_decline_delay: 20,
53
+ rate_decline_end_fraction: 0.1,
54
+ license_expiry_days: 30,
55
+ small_files_min_count: 100,
56
+ small_files_max_mean: 1_000_000,
57
+ small_mtu_max: 1400
58
+ }.freeze
59
+
60
+ # @return [Array<LogFile>] analyzed log files
61
+ attr_reader :log_files, :thresholds
62
+
63
+ # @param period [Integer] Snapshot period in seconds
64
+ # @param zero_bytes [Boolean] Include sessions without transferred bytes
65
+ # @param mtu [Integer, nil] MTU to use when not found in logs
66
+ # @param resolve [Boolean] Resolve peer addresses to host names
67
+ # @param thresholds [Hash] Diagnostic thresholds
68
+ # @param timezone [String, nil] Time zone of the log lines: `UTC` or `+HH:MM`. Time zone of the analyst if nil.
69
+ def initialize(period: 60, zero_bytes: false, mtu: nil, resolve: false, thresholds: {}, timezone: nil)
70
+ self.class.check_timezone(timezone)
71
+ @timezone = timezone
72
+ thresholds = thresholds.transform_keys(&:to_sym)
73
+ unknown = thresholds.keys - DEFAULT_THRESHOLDS.keys
74
+ Aspera.assert(unknown.empty?, type: ArgumentError) { "Unknown threshold: #{unknown.join(', ')}" }
75
+ @thresholds = DEFAULT_THRESHOLDS.merge(thresholds)
76
+ @options = {period: period, zero_bytes: zero_bytes, mtu: mtu, thresholds: @thresholds, timezone: timezone}
77
+ @resolve = resolve
78
+ @log_files = []
79
+ end
80
+
81
+ class << self
82
+ # @param timezone [String, nil] Time zone of the log lines: `UTC` or `+HH:MM`
83
+ # @raise [ParameterError] if the time zone is not valid
84
+ def check_timezone(timezone)
85
+ return if timezone.nil?
86
+ Time.at(0, in: timezone)
87
+ rescue ArgumentError
88
+ raise ParameterError, "Invalid time zone: #{timezone.inspect}, expected `UTC` or `+HH:MM`"
89
+ end
90
+
91
+ # @param path [String] log file, `-` (standard input), or folder
92
+ # @return [Array<String>] the log file, or the log files in the folder (recursively)
93
+ def log_paths(path)
94
+ return [path] unless File.directory?(path)
95
+ without_links(scan_folder(path, path, []))
96
+ end
97
+
98
+ # Read the lines of a log file: plain, or compressed with gzip (detected with its first bytes)
99
+ # @param path [String] Log file, or `-` for the standard input
100
+ # @param encoding [Encoding] Encoding of lines
101
+ # @yieldparam line [String]
102
+ def read_lines(path, encoding, &block)
103
+ io = path == STDIN_PATH ? StringIO.new($stdin.binmode.read) : File.open(path, 'rb')
104
+ gzip = io.read(2) == GZIP_MAGIC
105
+ io.rewind
106
+ io = Zlib::GzipReader.new(io, external_encoding: encoding) if gzip
107
+ io.set_encoding(encoding) unless gzip
108
+ io.each_line(&block)
109
+ ensure
110
+ io&.close
111
+ end
112
+
113
+ # Load the log files of a path
114
+ # In a folder, a file that is not an ascp log is ignored. A file given explicitly must be an ascp log.
115
+ # @param path [String] log file, `-` (standard input), or folder
116
+ # @yieldparam file [String] log file
117
+ # @yieldreturn [#ascp?] the loaded log
118
+ # @return [Array] the loaded logs that are ascp logs
119
+ def load_logs(path)
120
+ explicit = !File.directory?(path)
121
+ log_paths(path).filter_map do |file|
122
+ log = yield(file)
123
+ next log if log.ascp?
124
+ Aspera.assert(!explicit, type: ParameterError) { "Not an ascp log: #{file}" }
125
+ Log.log.debug { "Ignored, not an ascp log: #{file}" }
126
+ nil
127
+ rescue Zlib::Error, Errno::EPIPE => e
128
+ # JRuby raises Errno::EPIPE (instead of Zlib::Error) on truncated gzip input
129
+ raise ParameterError, "Cannot read #{file}: #{e.message}" if explicit
130
+ Log.log.warn("Ignored, cannot read #{file}: #{e.message}")
131
+ nil
132
+ end
133
+ end
134
+
135
+ private
136
+
137
+ # `ascp` creates `<name>.log` as a hard link to the current rotated file `<name>.<n>.log`: keep only one of them.
138
+ # @return [Array<String>] files, without those that are the same file as a previous one
139
+ def without_links(files)
140
+ seen = Set.new
141
+ files.select do |file|
142
+ stat = File.stat(file)
143
+ # No inode number on some platforms
144
+ stat.ino.zero? || seen.add?([stat.dev, stat.ino])
145
+ end
146
+ end
147
+
148
+ # @return [Array<String>] files, with the log files of folder added
149
+ def scan_folder(root, folder, files)
150
+ Dir.children(folder).sort.each do |name|
151
+ next if name.start_with?('.')
152
+ path = File.join(folder, name)
153
+ if File.directory?(path)
154
+ scan_folder(root, path, files) unless name.match?(EXCLUDED_FOLDERS)
155
+ elsif name.match?(INCLUDED_FILES) && !path.delete_prefix(root).match?(EXCLUDED_FILES)
156
+ files.push(path)
157
+ end
158
+ end
159
+ files
160
+ end
161
+ end
162
+
163
+ # Analyze a log file, or the log files in a folder (recursively)
164
+ # @param path [String] file, `-` (standard input) or folder
165
+ # @return [self]
166
+ def add(path)
167
+ @log_files.concat(self.class.load_logs(path) { |file| LogFile.new(file, **@options).analyze })
168
+ self
169
+ end
170
+
171
+ # @return [Hash] statistics over all log files
172
+ def summary
173
+ stats = Hash.new(0)
174
+ errors = Hash.new(0)
175
+ categories = Hash.new(0)
176
+ result = {}
177
+ @log_files.each do |log|
178
+ SUMMED_STATS.each { |key| stats[key] += log.stats[key] }
179
+ stats[:stuck_nack_loss] = [stats[:stuck_nack_loss], log.stats[:stuck_nack_loss]].max
180
+ log.stats[:errors].each { |error, count| errors[error] += count }
181
+ log.stats[:error_categories].each { |category, count| categories[category] += count }
182
+ MAXIMA.each do |key, name|
183
+ next if log.stats[key] <= result.fetch(name, 0)
184
+ result[name] = log.stats[key]
185
+ result["#{name}_time"] = iso(log.stats[:"#{key}_time"])
186
+ end
187
+ end
188
+ first = @log_files.filter_map(&:first_time).min
189
+ last = @log_files.filter_map(&:last_time).max
190
+ {
191
+ 'files' => @log_files.size,
192
+ 'first_log' => iso(first),
193
+ 'last_log' => iso(last),
194
+ 'sessions' => stats[:total_sessions],
195
+ 'success' => stats[:success],
196
+ 'failed' => stats[:failed],
197
+ 'cancelled' => stats[:cancelled],
198
+ 'success_rate' => ((100.0 * (stats[:total_sessions] - stats[:failed]) / stats[:total_sessions]).round(2) if stats[:total_sessions].positive?),
199
+ 'http_fallback' => stats[:http_fallback],
200
+ 'retries' => stats[:retries],
201
+ 'multi_session' => @log_files.sum { |log| log.multi_sessions.size },
202
+ 'errors' => errors.sort_by { |_, count| -count }.to_h,
203
+ 'error_categories' => categories.sort_by { |_, count| -count }.to_h,
204
+ 'diagnostics' => SEVERITIES.to_h { |severity| [severity, 0] }.merge(diagnostics.map { |row| row['severity'] }.tally).reject { |_, count| count.zero? }
205
+ }.merge(result).merge(
206
+ 'findings' => LogFile.findings(stats),
207
+ 'warnings' => warnings
208
+ ).compact
209
+ end
210
+
211
+ # @return [Array<String>] warnings about log files
212
+ def warnings
213
+ @log_files.flat_map do |log|
214
+ log.old_versions.map { |version| "#{log.path}: ascp #{version} is older than #{MIN_VERSION}, analysis may be inaccurate" }
215
+ end
216
+ end
217
+
218
+ # @return [Array<Hash>] one row per session, with the other side if its log is also analyzed
219
+ def sessions
220
+ rows = @log_files.flat_map(&:session_reports)
221
+ join_sides(rows)
222
+ single_file(rows)
223
+ end
224
+
225
+ # @return [Array<Hash>] one row per diagnostic of sessions: id, severity, message, recommendation (if the diagnostic has one)
226
+ def diagnostics
227
+ single_file(@log_files.flat_map(&:diagnostics))
228
+ end
229
+
230
+ # @return [Array<Hash>] one row per multi-session transfer
231
+ def multi_sessions
232
+ single_file(@log_files.flat_map(&:multi_sessions))
233
+ end
234
+
235
+ # @return [Array<Hash>] one row per snapshot period: aggregate rates
236
+ def snapshots
237
+ single_file(@log_files.flat_map(&:snapshots))
238
+ end
239
+
240
+ # @return [Array<Hash>] one row per session in each snapshot period
241
+ def snapshot_sessions
242
+ single_file(@log_files.flat_map(&:snapshot_sessions))
243
+ end
244
+
245
+ # @return [Array<Hash>] sessions and errors by peer address, most failures first
246
+ def peers
247
+ rows = {}
248
+ each_session do |_, s|
249
+ peer = s[:peer] or next
250
+ row = (rows[peer] ||= {'peer' => peer, 'users' => Set.new, 'sessions' => 0, 'success' => 0, 'failed' => 0, 'cancelled' => 0, 'errors' => Hash.new(0)})
251
+ row['users'].add(s[:user]) if s[:user]
252
+ row['sessions'] += 1
253
+ case s[:status]
254
+ when 'success' then row['success'] += 1
255
+ when 'failed'
256
+ row[s[:error].to_s.match?(/cancelled/i) ? 'cancelled' : 'failed'] += 1
257
+ row['errors'][s[:error]] += 1 if s[:error]
258
+ end
259
+ end
260
+ rows.values.sort_by { |row| -row['failed'] }.map do |row|
261
+ row.merge('users' => row['users'].to_a, 'errors' => row['errors'].to_h).merge(hostname(row['peer']))
262
+ end
263
+ end
264
+
265
+ # @return [Array<Hash>] one row per transferred file
266
+ def transfers
267
+ result = []
268
+ each_session do |log, s|
269
+ s.files.each do |name, file|
270
+ result.push({
271
+ 'file' => log.path,
272
+ 'session' => s[:uuid],
273
+ 'pid' => s.pid,
274
+ 'user' => s[:user],
275
+ 'peer' => s[:peer],
276
+ 'destination' => s[:dest],
277
+ 'start' => iso(s[:start]),
278
+ 'stop' => iso(s[:stop]),
279
+ 'path' => name,
280
+ 'direction' => file[:op] == 'recv' ? 'receive' : file[:op],
281
+ 'size' => file[:size],
282
+ 'status' => file[:status],
283
+ 'error' => file[:error]
284
+ }.compact)
285
+ end
286
+ end
287
+ single_file(result)
288
+ end
289
+
290
+ # @return [Array<Hash>] licenses of local and peer systems
291
+ def licenses
292
+ @log_files.each_with_object({}) do |log, all|
293
+ log.licenses.each { |key, license| all[key] = license.merge(file: log.path) }
294
+ end.map do |(number, address), license|
295
+ {'license' => number, 'address' => address, 'product' => license[:product], 'account' => license[:account], 'os' => license[:os], 'file' => license[:file]}.compact
296
+ end
297
+ end
298
+
299
+ # @return [Array<Hash>] by peer: number of sessions with loss due to overdriving of network (shallow queues) or storage
300
+ def overdrives
301
+ counts = Hash.new(0)
302
+ each_session do |_, s|
303
+ cause = s.overdrive
304
+ counts[[s[:peer], cause]] += 1 if cause
305
+ end
306
+ counts.sort_by { |_, count| -count }.map do |(peer, cause), count|
307
+ {'peer' => peer, 'cause' => cause.to_s, 'occurrences' => count}.merge(hostname(peer))
308
+ end
309
+ end
310
+
311
+ private
312
+
313
+ def iso(time)
314
+ Time.at(time).getlocal(@timezone).iso8601 if time
315
+ end
316
+
317
+ def each_session
318
+ @log_files.each { |log| log.sessions.each { |s| yield(log, s) } }
319
+ end
320
+
321
+ # Same session in the logs of sender and receiver: add the other side to each row
322
+ # @param rows [Array<Hash>] sessions
323
+ def join_sides(rows)
324
+ rows.group_by { |row| row['session'] }.each do |uuid, same|
325
+ next if uuid.nil? || same.size != 2 || same.map { |row| row['direction'] }.uniq.size != 2
326
+ same.each_with_index do |row, index|
327
+ other = same[1 - index]
328
+ row['peer_side'] = other.slice('file', 'pid', 'role', 'status', 'error').compact
329
+ row['peer_diagnostics'] = other['diagnostics'] if other['diagnostics']&.any?
330
+ end
331
+ end
332
+ end
333
+
334
+ # Remove column `file` when only one file is analyzed
335
+ def single_file(rows)
336
+ return rows if @log_files.size > 1
337
+ rows.each { |row| row.delete('file') }
338
+ end
339
+
340
+ # @return [Hash] host name of address, if resolution is enabled and successful
341
+ def hostname(address)
342
+ return {} unless @resolve && address
343
+ @hostnames ||= {}
344
+ @hostnames[address] ||= Resolv::DNS.open do |dns|
345
+ dns.timeouts = 5
346
+ dns.getname(address).to_s
347
+ rescue Resolv::ResolvError, ArgumentError
348
+ ''
349
+ end
350
+ @hostnames[address].empty? ? {} : {'hostname' => @hostnames[address]}
351
+ end
352
+ end
353
+ end
354
+ end
@@ -1,15 +1,17 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'aspera/assert'
4
- require 'aspera/log'
5
- require 'aspera/string_ext'
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ require_relative '../assert'
7
+ require_relative '../log'
8
+ require_relative '../string_ext'
6
9
 
7
10
  module Aspera
8
11
  module Ascp
9
12
  # processing of ascp management port events
10
13
  # Reference: `mgmtmess.c`
11
14
  class Management
12
- # cspell:ignore asmgmt faspmgmt
13
15
  # References:
14
16
  # https://www.ibm.com/support/pages/error-code-reference-tables
15
17
  # `asmgmt_err.h` : codes, mnemonics and messages
@@ -98,7 +100,8 @@ module Aspera
98
100
  69 => {r: true, c: 'MAX_ASCP', m: 'Maximum ascp processes on a node exceeded',
99
101
  a: 'Failed to start session maximum transfer sessions exceeded'}
100
102
  }.freeze
101
- # cspell: disable
103
+ # Mnemonic => error, see ERRORS
104
+ ERRORS_BY_MNEMONIC = ERRORS.values.to_h { |error| [error[:c], error] }.freeze
102
105
  # Same as `as_mgmt_cmd_name_str` (`NOTIFICATION` is twice there too)
103
106
  OPERATIONS = %w[
104
107
  NOP
@@ -283,7 +286,7 @@ module Aspera
283
286
  ].freeze
284
287
  # Management port start message
285
288
  PROT_VERSION = '2'
286
- MGT_HEADER = "FASPMGR #{PROT_VERSION}"
289
+ MGT_HEADER = "FASPMGR #{PROT_VERSION}".freeze
287
290
  # empty line is separator to end event information
288
291
  MGT_FRAME_SEPARATOR = ''
289
292
  # fields description for JSON generation
@@ -307,11 +310,16 @@ module Aspera
307
310
  PATH_ESCAPE = "\e"
308
311
  PATH_ESCAPES = {"\n" => 'n', "\r" => 'r', PATH_ESCAPE => PATH_ESCAPE}.freeze
309
312
 
310
- private_constant :OPERATIONS, :PARAMETERS, :MGT_HEADER, :MGT_FRAME_SEPARATOR, :INTEGER_FIELDS, :BOOLEAN_FIELDS, :BOOLEAN_TRUE, :INTEGER_VALUE,
313
+ private_constant :ERRORS_BY_MNEMONIC, :OPERATIONS, :PARAMETERS, :MGT_HEADER, :MGT_FRAME_SEPARATOR, :INTEGER_FIELDS, :BOOLEAN_FIELDS, :BOOLEAN_TRUE, :INTEGER_VALUE,
311
314
  :PATH_FIELDS, :PATH_ESCAPE, :PATH_ESCAPES
312
- # cspell: enable
313
315
 
314
316
  class << self
317
+ # @param mnemonic [String] mnemonic of error, e.g. `CONNECTION_LOST`
318
+ # @return [Hash, nil] error of management port (see ERRORS), nil if unknown
319
+ def error_by_mnemonic(mnemonic)
320
+ ERRORS_BY_MNEMONIC[mnemonic]
321
+ end
322
+
315
323
  # Translate native event name to snake case
316
324
  def field_native_to_snake(name)
317
325
  case name
@@ -0,0 +1,217 @@
1
+ # frozen_string_literal: true
2
+
3
+ # SPDX-FileCopyrightText: IBM Corp.
4
+ # SPDX-License-Identifier: Apache-2.0
5
+
6
+ # cspell:ignore reuseaddr sourcelist BUFS ERANGE
7
+ require_relative 'management'
8
+
9
+ module Aspera
10
+ module Ascp
11
+ # Error codes of FASP sessions: `errcode` in log lines `Session Start` and `Session Stop` of `ascp`.
12
+ # Not the same numbering as errors of the management port (`Management::ERRORS`): each code maps to one of them.
13
+ # References:
14
+ # `fasp_errno.h` : codes (enum `fasp_errno_e`)
15
+ # `fasp_errno.c` : messages (`fasp_errno2str`)
16
+ # `asmgmt_err.c` : code of management port (`mgmt_fasperr2mgmterr`)
17
+ module SessionErrors
18
+ # Code => name, code of management port (mnemonic in `Management::ERRORS`), category (see CATEGORIES), message
19
+ CODES = {
20
+ 1 => ['bad_version', 'INTERNAL_ERROR', 'configuration', 'Bad version'],
21
+ 2 => ['bad_protocol', 'FASP_PROTO', 'configuration', 'Bad protocol'],
22
+ 3 => ['srcpath_check_failed', 'BAD_PATH', 'path', 'Source path check failed'],
23
+ 4 => ['dstpath_check_failed', 'BAD_PATH', 'path', 'Destination path check failed'],
24
+ 5 => ['incompat_mod_proto_vers', 'FASP_PROTO', 'configuration', 'FASP module protocol versions incompatible'],
25
+ 6 => ['incompat_pipeline_depth', 'INTERNAL_ERROR', 'configuration', 'FASP pipeline depths incompatible'],
26
+ 7 => ['sess_stopped', 'USER_CANCEL', 'aborted', 'Session initiation stopped by application'],
27
+ 8 => ['connect_sock', 'CONNECTION_ERROR', 'udp_setup', 'Unable to connect UDP socket'],
28
+ 9 => ['send_stop', 'CONNECTION_ERROR', 'udp_setup', 'Unable to send STOP message'],
29
+ 10 => ['recv_stop', 'CONNECTION_ERROR', 'udp_setup', 'Unable to recv STOP message'],
30
+ 11 => ['c_noresp', 'CONNECTION_TIMEOUT', 'udp_setup',
31
+ 'Client unable to connect to server (check UDP port and firewall)'],
32
+ 12 => ['s_noresp', 'CONNECTION_TIMEOUT', 'udp_setup',
33
+ 'Server unable to hear from client (check UDP port and firewall)'],
34
+ 13 => ['unconcluded_pmtu_brtt', 'PMTU_BRTT_ERROR', 'udp_setup', 'Unable to conclude a valid pmtu-brtt value'],
35
+ 14 => ['invalid_pmtu_brtt', 'PMTU_BRTT_ERROR', 'udp_setup', 'Unable to receive a valid stop message (pmtu-brtt)'],
36
+ 15 => ['unmatched_tl', 'SOCK_SETUP', 'udp_setup', 'Incompatible timer levels between peers'],
37
+ 16 => ['unconcluded_bw', 'BWMEAS_ERROR', 'udp_setup', 'Unable to conclude a valid bw value'],
38
+ 17 => ['invalid_bw', 'BWMEAS_ERROR', 'udp_setup', 'Unable to receive a valid stop message (bwmeas)'],
39
+ 18 => ['ds_conn_lost', 'CONNECTION_LOST', 'network', 'Connection lost in midst of data session'],
40
+ 19 => ['peer_aborted_sess', 'PEER_ABORTED_SESSION', 'aborted', 'Peer aborted session'],
41
+ 20 => ['ds_proto_magic_mismatch', 'FASP_PROTO', 'network', 'Data session protocol error, magic mismatch'],
42
+ 21 => ['ds_proto_pdutype_invalid', 'FASP_PROTO', 'network', 'Data session protocol error, pdu type invalid'],
43
+ 22 => ['ds_proto_msg_toosmall', 'FASP_PROTO', 'network', 'Data session protocol error, message too small'],
44
+ 23 => ['ds_proto_msg_toobig', 'FASP_PROTO', 'network', 'Data session protocol error, message too big'],
45
+ 24 => ['internal_disk_thread', 'THREAD_SPAWN', 'storage', 'Internal disk thread error'],
46
+ 25 => ['internal_ring', 'INTERNAL_ERROR', 'other', 'Internal ring error'],
47
+ 26 => ['internal_out_of_mem', 'OUT_OF_MEMORY', 'other', 'Internal memory error'],
48
+ 27 => ['sess_other', 'TRANSFER_ERROR', 'other', 'Other Session error'],
49
+ 28 => ['xfer_other', 'SOME_FILE_ERRS', 'files', 'Other Transfer error'],
50
+ 29 => ['sess_internal', 'INTERNAL_ERROR', 'other', 'Session internal error'],
51
+ 30 => ['sess_conn_tmout', 'CONNECTION_TIMEOUT', 'network', 'Session connection timeout'],
52
+ 31 => ['sess_rex_send', 'RCVR_SEND_ERROR', 'network', 'Retransmit request send error'],
53
+ 32 => ['sess_stats_send', 'RCVR_SEND_ERROR', 'network', 'Stats request send error'],
54
+ 33 => ['sess_reception', 'CONNECTION_LOST', 'network', 'Data reception error'],
55
+ 34 => ['xfer_external_abort', 'PEER_ABORTED_SESSION', 'aborted', 'External abort of transfer'],
56
+ 35 => ['xfer_transfer_tmout', 'DATA_TRANSFER_TIMEOUT', 'network', 'Data transfer timeout'],
57
+ 36 => ['sess_transfer_tmout', 'DATA_TRANSFER_TIMEOUT', 'network', 'Session data transfer timeout'],
58
+ 37 => ['xfer_test_internal_abort_err', 'PEER_ABORTED_SESSION', 'other', 'Session internal abort'],
59
+ 38 => ['lic_read', 'LIC_NOLIC', 'license', 'Unable to read license'],
60
+ 39 => ['lic_expired', 'LIC_EXPIRED', 'license', 'License expired'],
61
+ 40 => ['lic_illegal', 'LIC_ILLEGAL', 'license', 'Operation not permitted by license'],
62
+ 41 => ['lic_bw_exceeded', 'LIC_RATE_EXCEEDED', 'license', 'License bandwidth cap exceeded'],
63
+ 42 => ['lic_duplicate', 'LIC_DUP', 'license', 'Duplicate license'],
64
+ 43 => ['sock_addrinfo', 'SOCK_SETUP', 'socket', 'Error getting socket information'],
65
+ 44 => ['sock_set_reuse', 'SOCK_SETUP', 'socket', 'Error setting socket reuseaddr'],
66
+ 45 => ['sock_recvbuf', 'SOCK_SETUP', 'socket', 'Error setting socket recv buffer size'],
67
+ 46 => ['sock_sendbuf', 'SOCK_SETUP', 'socket', 'Error setting socket send buffer size'],
68
+ 47 => ['sock_bind', 'SOCK_SETUP', 'socket', 'Error binding socket to port'],
69
+ 48 => ['sock_create', 'SOCK_SETUP', 'socket', 'Error creating socket'],
70
+ 49 => ['resrc_disk_buf', 'INTERNAL_ERROR', 'storage', 'Out of disk buffers'],
71
+ 50 => ['no_such_file', 'NO_SUCH_FILE', 'storage', 'No such file or directory'],
72
+ 51 => ['no_perms', 'NO_PERMS', 'storage', 'Insufficient permissions'],
73
+ 52 => ['no_space_left', 'NO_SPACE_LEFT', 'storage', 'No space left on disk'],
74
+ 53 => ['not_dir', 'NOT_DIR', 'storage', 'Target must be a directory'],
75
+ 54 => ['is_dir', 'IS_DIR', 'storage', 'Expected regular file'],
76
+ 55 => ['file_table_overflow', 'FILE_TABLE_OVR', 'storage', 'File table overflow'],
77
+ 56 => ['too_many_files', 'TOO_MANY_FILES', 'storage', 'Too many files open'],
78
+ 57 => ['file_too_big', 'FILE_TOO_BIG', 'storage', 'File too big for filesystem'],
79
+ 58 => ['read_only_fs', 'READ_ONLY_FS', 'storage', 'Read only filesystem'],
80
+ 59 => ['disk_read', 'DISK_READ', 'storage', 'Disk read failed'],
81
+ 60 => ['disk_write', 'DISK_WRITE', 'storage', 'Disk write failed'],
82
+ 61 => ['srclist_count_invalid', 'INTERNAL_ERROR', 'path', 'Too many source files specified'],
83
+ 62 => ['srclist_not_specified', 'USAGE', 'path', 'Source file list not specified'],
84
+ 63 => ['srcpath_stat_failed', 'STAT_FAILS', 'path', 'Source path stat failed'],
85
+ 64 => ['dstpath_does_not_preexist', 'NOT_DIR', 'path', 'Destination path must preexist'],
86
+ 65 => ['dstpath_is_not_dir', 'NOT_DIR', 'path', 'Destination path must be a directory'],
87
+ 66 => ['dstpath_dir_create_failed', 'BAD_PATH', 'path', 'Destination directory create failed'],
88
+ 67 => ['untranslated_syserrno', 'INTERNAL_ERROR', 'other', 'Untranslated system errno'],
89
+ 68 => ['user_aborted_sess', 'USER_CANCEL', 'aborted', 'User aborted session'],
90
+ 69 => ['ds_resp_unknown', 'FASP_PROTO', 'other', 'Transfer response unknown'],
91
+ 70 => ['ds_resp_err_other', 'FASP_PROTO', 'other', 'Transfer response other error'],
92
+ 71 => ['ds_resp_err_eexist', 'ALREADY_EXISTS', 'storage', 'File already exists'],
93
+ 72 => ['ds_resp_err_aspx', 'UNAUTHORIZED', 'path', 'File is a .aspx file'],
94
+ 73 => ['mgmt_auth_refused', 'UNAUTHORIZED', 'management', 'Management authorization refused'],
95
+ 74 => ['mgmt_conn_lost', 'CONNECTION_LOST', 'management', 'Management connection lost'],
96
+ 75 => ['mgmt_auth_timeout', 'UNAUTHORIZED', 'management', 'Management authorization timeout'],
97
+ 76 => ['had_file_errors', 'SOME_FILE_ERRS', 'files', 'One or more transfers failed'],
98
+ 77 => ['disallowed_path', 'BAD_PATH', 'path', 'File location is outside \'docroot\' hierarchy'],
99
+ 78 => ['filename_too_long', 'FILEPATH_TOO_LONG', 'path', 'Filename too long'],
100
+ 79 => ['not_regular_file', 'NOT_REGULAR', 'storage', 'Not a regular file'],
101
+ 80 => ['lic_keyinvalid', 'LIC_ILLEGAL', 'license', 'Invalid license key'],
102
+ 81 => ['vlink_init_err', 'VLINK_ERROR', 'configuration', 'virtual link initialization failed'],
103
+ 82 => ['vlink_start_err', 'VLINK_ERROR', 'configuration', 'virtual link failed to start up'],
104
+ 83 => ['file_encryption_err', 'FILE_ENCRYPTION_ERROR', 'storage', 'File encryption error'],
105
+ 84 => ['dstpath_invalid', 'BAD_PATH', 'path', 'Destination path invalid'],
106
+ 85 => ['config_file_not_found', 'BAD_CONFIGURATION', 'configuration', 'Configuration file not found'],
107
+ 86 => ['config_file_invalid', 'BAD_CONFIGURATION', 'configuration', 'Invalid configuration file'],
108
+ 87 => ['file_decryption_pass', 'FILE_DECRYPTION_PASS', 'storage', 'File decryption error, bad passphrase'],
109
+ 88 => ['docroot_invalid', 'BAD_PATH', 'path', 'Destination path create failed, invalid docroot'],
110
+ 89 => ['ssh_auth_failed', 'AUTH', 'authentication', 'SSH authentication failed'],
111
+ 90 => ['user_aborted_xfer', 'USER_CANCEL', 'aborted', 'User aborted transfer'],
112
+ 91 => ['cannot_readlink', 'DISK_READ', 'storage', 'Cannot readlink'],
113
+ 92 => ['cannot_rename_partial', 'CANNOT_RENAME_PARTIAL', 'storage', 'Cannot rename partial file'],
114
+ 93 => ['vlink_stop_err', 'VLINK_ERROR', 'configuration', 'virtual link shutdown failure'],
115
+ 94 => ['mgmt_lic_timeout', 'FASP_PROTO', 'license', 'Management license data timeout'],
116
+ 95 => ['too_many_rms', 'INTERNAL_ERROR', 'configuration', 'Too many rate modules'],
117
+ 96 => ['storage_inaccessible', 'INTERNAL_ERROR', 'storage', 'Storage inaccessible'],
118
+ 97 => ['reading_sourcelist', 'USAGE', 'path', 'Error reading sourcelist from command line'],
119
+ 98 => ['reading_token', 'USAGE', 'authentication', 'Error reading token'],
120
+ 99 => ['allocating_chunked_token', 'USAGE', 'authentication', 'Internal error - failed to allocate space for chunked token'],
121
+ 100 => ['extracting_master_token', 'USAGE', 'authentication', 'Invalid token - failed to extract master'],
122
+ 101 => ['extracting_subchunk_token', 'USAGE', 'authentication',
123
+ 'Invalid token - token only contains subset of file paths submitted'],
124
+ 102 => ['too_many_file_paths', 'USAGE', 'path', 'Too many file paths, increase CMDLINE_MAX_BUFS'],
125
+ 103 => ['reading_file_stdin', 'USAGE', 'path', 'Error reading file list from file/stdin'],
126
+ 104 => ['empty_file_list_from_stdin_or_file', 'USAGE', 'path', 'Empty file list from file/stdin'],
127
+ 105 => ['token_filepath_mismatch', 'USAGE', 'path', 'Token doesn\'t match file-list/file-pair-list'],
128
+ 106 => ['usage', 'USAGE', 'configuration', 'Usage error'],
129
+ 107 => ['conn_insecure', 'INSECURE_CONNECTION', 'authentication', 'Remote host is not who we expected'],
130
+ 108 => ['start_validation', 'START_VALIDATION_FAILED', 'validation', 'Start validation failed'],
131
+ 109 => ['stop_validation', 'STOP_VALIDATION_FAILED', 'validation', 'Stop validation failed'],
132
+ 110 => ['threshold_validation', 'THRESHOLD_VALIDATION_FAILED', 'validation', 'Threshold validation failed'],
133
+ 111 => ['network_down', 'CONNECTION_LOST', 'network', 'Network down'],
134
+ 112 => ['address_not_available', 'CONNECTION_ERROR', 'network', 'Address not available'],
135
+ 113 => ['out_of_range', 'CHUNK_MUST_MATCH_ALIGNMENT', 'configuration', 'Value out of expected range (AS_ERANGE)'],
136
+ 114 => ['invalid_argument', 'USAGE', 'configuration', 'Invalid argument'],
137
+ 115 => ['server_multi_session_not_supported', 'USAGE', 'configuration', 'Server version of multi-session transfer is not supported'],
138
+ 116 => ['client_multi_session_not_supported', 'USAGE', 'configuration', 'Client version of multi-session transfer is not supported'],
139
+ 117 => ['illegal_chars_in_path', 'ILLEGAL_CHARS_IN_PATH', 'path', 'Path contains unsupported characters'],
140
+ 118 => ['inconsistent_source_uri', 'USAGE', 'path', 'All source paths must start with the same URI schema'],
141
+ 119 => ['list_uri_not_allowed', 'USAGE', 'path', 'file-pair-list destination cannot be a URI'],
142
+ 120 => ['persistent_uri_not_allowed', 'USAGE', 'path',
143
+ 'URIs not supported in source or destination management parameters'],
144
+ 121 => ['source_archive_mismatch', 'USAGE', 'path', 'Source and archive paths must start with the same URI schema'],
145
+ 122 => ['server_stdio', 'USAGE', 'path', 'Stdio/stdio-tar schema not supported on server'],
146
+ 123 => ['invalid_docroot_dest_combination', 'USAGE', 'path', 'Destination cannot be URI if docroot defined'],
147
+ 124 => ['token_URI_without_docroot_unsupported', 'USAGE', 'path', 'Token only supported for URIs using docroot'],
148
+ 125 => ['invalid_chunk_size', 'USAGE', 'configuration', 'Invalid chunk size'],
149
+ 126 => ['fasp_session_open', 'CONNECTION_ERROR', 'network', 'FASP session open error'],
150
+ 127 => ['fasp_session_accept', 'CONNECTION_ERROR', 'network', 'FASP session accept error'],
151
+ 128 => ['sess_transfer_error', 'CONNECTION_LOST', 'network', 'FASP session transfer error'],
152
+ 129 => ['upload_inprogress', 'UPLOAD_IN_PROGRESS', 'storage', 'File upload already in progress'],
153
+ 130 => ['validation_session_abort', 'VALIDATION_SESSION_ABORT', 'validation', 'FASP session stopped, validation error(s)'],
154
+ 131 => ['remote_storage_error', 'REMOTE_STORAGE_ERROR', 'storage', 'FASP session remote storage error'],
155
+ 132 => ['lua_session_abort', 'LUA_SCRIPT_ABORTED_SESSION', 'validation', 'Aborted session'],
156
+ 133 => ['auth_setup_incomplete', 'AUTHORIZATION', 'authentication', 'Authorization setup incomplete'],
157
+ 134 => ['ssear_retryable', 'SSEAR_RETRYABLE', 'storage', 'Server-side Encryption At Rest unavailable'],
158
+ 135 => ['ssear_fatal', 'SSEAR_FATAL', 'storage', 'Server-side Encryption At Rest failed'],
159
+ 136 => ['link_loop', 'LINK_LOOP', 'storage', 'Too many levels of symbolic links'],
160
+ 137 => ['cipher_non_compat_fips', 'CIPHER_NON_COMPAT_FIPS', 'configuration', 'Cipher not supported with FIPS mode'],
161
+ 138 => ['peer_requires_fips', 'PEER_REQUIRES_FIPS', 'configuration', 'FIPS support required on client and server'],
162
+ 139 => ['jobqueue_aborted', 'LUA_SCRIPT_ABORTED_SESSION', 'aborted', 'Async job aborted by initiator request'],
163
+ 140 => ['connection_error_http', 'CONNECTION_ERROR_HTTP', 'network', 'Connection lost during http session'],
164
+ 141 => ['min_version_fail', 'MIN_VERSION_CHECK', 'configuration', 'Failed to start due to minimum version check.'],
165
+ 142 => ['max_ascp', 'MAX_ASCP', 'server_limit', 'Failed to start session maximum transfer sessions exceeded'],
166
+ 143 => ['incompatible_resume_option', 'USAGE', 'configuration',
167
+ 'The server configuration is not compatible with the specified resume option']
168
+ }.freeze
169
+ # Category => hint for remediation
170
+ CATEGORIES = {
171
+ 'udp_setup' => 'The UDP session could not be established: check that the FASP UDP port (default 33001) is open in firewalls on both sides.',
172
+ 'network' => 'Network problem during the session: check network stability, packet loss, and UDP session timeouts of firewalls.',
173
+ 'aborted' => 'The session was aborted by the user, the peer or the application.',
174
+ 'license' => 'License problem: check the license, e.g. with `ascp -A`.',
175
+ 'socket' => 'Socket error: check that the UDP port is not used by another process, and the system socket limits.',
176
+ 'storage' => 'Storage error: check free space, permissions and access to the storage.',
177
+ 'path' => 'Path error: check source and destination paths, and docroot and restrictions of the transfer user.',
178
+ 'authentication' => 'Authentication failure: check credentials, SSH keys or token.',
179
+ 'management' => 'The management connection with the application that controls ascp (e.g. Node API) failed.',
180
+ 'files' => 'Some files failed: see the list of transferred files for the error of each file.',
181
+ 'validation' => 'A validation of the transfer (e.g. a script on the server) refused it.',
182
+ 'configuration' => 'Incompatible versions or configuration of peers: check versions and configuration.',
183
+ 'server_limit' => 'The server refused the session: maximum number of concurrent ascp processes reached.'
184
+ }.freeze
185
+ # Category of codes without a specific cause, and of unknown codes
186
+ OTHER = 'other'
187
+
188
+ class << self
189
+ # @param code [Integer] error code
190
+ # @return [String] category of error code, see CATEGORIES
191
+ def category(code)
192
+ CODES.dig(code, 2) || OTHER
193
+ end
194
+
195
+ # @param category [String] category of error
196
+ # @return [String, nil] hint for remediation
197
+ def hint(category)
198
+ CATEGORIES[category]
199
+ end
200
+
201
+ # @param code [Integer] error code
202
+ # @return [Boolean, nil] true if a new attempt may succeed, as for the code of management port, nil if unknown
203
+ def retryable(code)
204
+ management = CODES.dig(code, 1) or return
205
+ Management.error_by_mnemonic(management)&.fetch(:r)
206
+ end
207
+
208
+ # @return [Array<Hash>] information on all error codes
209
+ def list
210
+ CODES.map do |code, (name, management, category, message)|
211
+ {'code' => code, 'name' => name, 'message' => message, 'category' => category, 'management' => management, 'retry' => retryable(code)}
212
+ end
213
+ end
214
+ end
215
+ end
216
+ end
217
+ end