aspera-cli 4.29.0 → 4.29.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +2 -1
- data/CHANGELOG.md +76 -2
- data/README.md +20 -1
- data/SECURITY.md +14 -0
- data/docs/README.md +277 -38
- data/lib/aspera/api/node.rb +9 -2
- data/lib/aspera/ascp/installation.rb +26 -4
- data/lib/aspera/ascp/log_analyzer/lines.rb +2 -2
- data/lib/aspera/ascp/log_analyzer.rb +19 -3
- data/lib/aspera/ascp/log_locations.rb +163 -0
- data/lib/aspera/cli/ascp_logs_actions.rb +12 -0
- data/lib/aspera/cli/bootstrapper.rb +1 -0
- data/lib/aspera/cli/command_line.rb +39 -2
- data/lib/aspera/cli/command_registry.rb +3 -0
- data/lib/aspera/cli/command_spec.rb +13 -0
- data/lib/aspera/cli/error.rb +3 -0
- data/lib/aspera/cli/extended_value.rb +5 -4
- data/lib/aspera/cli/formatter.rb +14 -8
- data/lib/aspera/cli/http.rb +26 -1
- data/lib/aspera/cli/info.rb +1 -1
- data/lib/aspera/cli/mcp/tool.rb +5 -3
- data/lib/aspera/cli/option_value.rb +14 -8
- data/lib/aspera/cli/options.schema.yaml +156 -19
- data/lib/aspera/cli/parser.rb +15 -3
- data/lib/aspera/cli/plugins/aoc.rb +4 -2
- data/lib/aspera/cli/plugins/ats.rb +1 -1
- data/lib/aspera/cli/plugins/base.rb +33 -6
- data/lib/aspera/cli/plugins/config.rb +12 -1
- data/lib/aspera/cli/plugins/faspex5.rb +3 -1
- data/lib/aspera/cli/plugins/mcp.rb +14 -0
- data/lib/aspera/cli/plugins/node.rb +8 -8
- data/lib/aspera/cli/plugins/oauth.rb +18 -5
- data/lib/aspera/cli/plugins/orchestrator.rb +28 -24
- data/lib/aspera/cli/plugins/preview.rb +3 -1
- data/lib/aspera/cli/plugins/server.rb +3 -3
- data/lib/aspera/cli/plugins/shares.rb +1 -2
- data/lib/aspera/cli/plugins/transferd.rb +7 -2
- data/lib/aspera/cli/poll.rb +236 -0
- data/lib/aspera/cli/preset_manager.rb +63 -19
- data/lib/aspera/cli/prompt.rb +153 -8
- data/lib/aspera/cli/runner.rb +25 -7
- data/lib/aspera/cli/security.rb +10 -0
- data/lib/aspera/cli/sync_actions.rb +2 -0
- data/lib/aspera/cli/transfer_agent.rb +14 -0
- data/lib/aspera/cli/transfer_progress.rb +6 -5
- data/lib/aspera/cli/version.rb +1 -1
- data/lib/aspera/environment.rb +3 -1
- data/lib/aspera/id_generator.rb +16 -3
- data/lib/aspera/inflate.rb +43 -0
- data/lib/aspera/oauth/client/base.rb +38 -8
- data/lib/aspera/oauth/client/factory.rb +35 -15
- data/lib/aspera/oauth/client/json_credentials.rb +3 -2
- data/lib/aspera/oauth/client/shares_web.rb +13 -4
- data/lib/aspera/oauth/client/url_json.rb +3 -2
- data/lib/aspera/oauth/client/web.rb +2 -2
- data/lib/aspera/orchestrator_workflow_checker.rb +10 -1
- data/lib/aspera/preview/terminal.rb +8 -2
- data/lib/aspera/products/desktop.rb +13 -1
- data/lib/aspera/rest/client.rb +23 -5
- data/lib/aspera/schema/registry.rb +1 -0
- data/lib/aspera/sealed_hash.rb +2 -18
- data/lib/aspera/secret/hider.rb +13 -1
- data/lib/aspera/secret/store/one_password_cli.rb +13 -11
- data/lib/aspera/sync/operations.rb +4 -4
- data/lib/aspera/transfer/result.rb +20 -0
- data/lib/aspera/transfer/spec.rb +2 -2
- data/lib/aspera/{transfer/units.rb → units/decimal.rb} +4 -12
- data/lib/aspera/units/duration.rb +109 -0
- data/lib/aspera/uri_reader.rb +11 -6
- data/lib/aspera/web_auth/reply.html.erb +1 -1
- data/llms-install.md +88 -0
- data/llms.txt +6 -0
- data/skills/ascli/SKILL.md +6 -0
- data.tar.gz.sig +0 -0
- metadata +7 -3
- metadata.gz.sig +0 -0
- data/lib/aspera/duration.rb +0 -45
|
@@ -119,7 +119,7 @@ module Aspera
|
|
|
119
119
|
# @param log [Boolean] whether to log the value retrieval
|
|
120
120
|
# @return [Object] current value
|
|
121
121
|
def value(log: true)
|
|
122
|
-
Log.log.trace1 { "#{@option} -> (#{@value.class})#{@value}" } if log
|
|
122
|
+
Log.log.trace1 { "#{@option} -> (#{@value.class})#{Secret::Hider.instance.hidden_copy(@value)}" } if log
|
|
123
123
|
@value
|
|
124
124
|
end
|
|
125
125
|
|
|
@@ -152,7 +152,8 @@ module Aspera
|
|
|
152
152
|
new_value = coerce(ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types))
|
|
153
153
|
check_sub_options_security(new_value) if restricted_source?(source)
|
|
154
154
|
new_value = {@shorthand => new_value} if @shorthand && new_value.is_a?(String)
|
|
155
|
-
|
|
155
|
+
declare_secrets(new_value)
|
|
156
|
+
Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{Secret::Hider.instance.hidden_copy(new_value)}" }
|
|
156
157
|
Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
|
|
157
158
|
new_value = @convert.call(new_value) if @convert && new_value.is_a?(Hash)
|
|
158
159
|
if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
|
|
@@ -321,15 +322,20 @@ module Aspera
|
|
|
321
322
|
end
|
|
322
323
|
end
|
|
323
324
|
|
|
324
|
-
#
|
|
325
|
-
# @param
|
|
326
|
-
def
|
|
327
|
-
# Secret values are hidden wherever they appear: logs, results
|
|
325
|
+
# Secret values are hidden wherever they appear: logs, results
|
|
326
|
+
# @param value [Object] value of option
|
|
327
|
+
def declare_secrets(value)
|
|
328
328
|
if @sensitive
|
|
329
|
-
Secret::Hider.instance.add_secret_values(
|
|
329
|
+
Secret::Hider.instance.add_secret_values(value)
|
|
330
330
|
else
|
|
331
|
-
Secret::Hider.instance.add_secrets_in(
|
|
331
|
+
Secret::Hider.instance.add_secrets_in(value)
|
|
332
332
|
end
|
|
333
|
+
end
|
|
334
|
+
|
|
335
|
+
# @param new_value [Object] value to store
|
|
336
|
+
# @param source [Symbol, nil] `OptionSource` of value
|
|
337
|
+
def store(new_value, source)
|
|
338
|
+
declare_secrets(new_value)
|
|
333
339
|
@value = new_value
|
|
334
340
|
@source = source
|
|
335
341
|
@on_set&.call(new_value)
|
|
@@ -73,6 +73,12 @@ components:
|
|
|
73
73
|
- port
|
|
74
74
|
- paste
|
|
75
75
|
default: port
|
|
76
|
+
hidden_silent:
|
|
77
|
+
type: boolean
|
|
78
|
+
description: >-
|
|
79
|
+
Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`.
|
|
80
|
+
By default, a mark shows whether something was typed or pasted, without revealing the length.
|
|
81
|
+
default: false
|
|
76
82
|
command:
|
|
77
83
|
type: array
|
|
78
84
|
x-security: low
|
|
@@ -95,9 +101,9 @@ components:
|
|
|
95
101
|
description: >-
|
|
96
102
|
- `low`: no restriction.
|
|
97
103
|
|
|
98
|
-
- `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:` and `@
|
|
104
|
+
- `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
|
|
99
105
|
|
|
100
|
-
- `high`: `@ruby:`, `@file:`, `@uri:` and `@
|
|
106
|
+
- `high`: `@ruby:`, `@file:`, `@uri:`, `@env:` and `@zlib:` are refused, files are written only in `writable_paths`.
|
|
101
107
|
|
|
102
108
|
Features that execute code, load plugins, or write a file chosen by the client (e.g. `--out.file`) are available only at level `low`.
|
|
103
109
|
enum:
|
|
@@ -585,26 +591,46 @@ components:
|
|
|
585
591
|
|
|
586
592
|
Keys are dispatched at startup to three targets:
|
|
587
593
|
`Rest::Parameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
|
|
588
|
-
`SSL` (`ssl_options`), and `OAuth` (`
|
|
594
|
+
`SSL` (`ssl_options`), and `OAuth` (`token_*`, `jwt_*`).
|
|
589
595
|
Any remaining key is forwarded as a setter to the `Net::HTTP` session
|
|
590
596
|
(e.g. `ca_file`, `verify_mode`) — the list below covers the common ones.
|
|
591
597
|
additionalProperties: true
|
|
592
598
|
properties:
|
|
593
599
|
read_timeout:
|
|
594
|
-
|
|
595
|
-
|
|
600
|
+
oneOf:
|
|
601
|
+
- type: string
|
|
602
|
+
- type: number
|
|
603
|
+
minimum: 0
|
|
604
|
+
description: >-
|
|
605
|
+
Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
|
|
606
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
596
607
|
default: 60
|
|
597
608
|
write_timeout:
|
|
598
|
-
|
|
599
|
-
|
|
609
|
+
oneOf:
|
|
610
|
+
- type: string
|
|
611
|
+
- type: number
|
|
612
|
+
minimum: 0
|
|
613
|
+
description: >-
|
|
614
|
+
Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
|
|
615
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
600
616
|
default: 60
|
|
601
617
|
open_timeout:
|
|
602
|
-
|
|
603
|
-
|
|
618
|
+
oneOf:
|
|
619
|
+
- type: string
|
|
620
|
+
- type: number
|
|
621
|
+
minimum: 0
|
|
622
|
+
description: >-
|
|
623
|
+
Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
|
|
624
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
604
625
|
default: 60
|
|
605
626
|
keep_alive_timeout:
|
|
606
|
-
|
|
607
|
-
|
|
627
|
+
oneOf:
|
|
628
|
+
- type: string
|
|
629
|
+
- type: number
|
|
630
|
+
minimum: 0
|
|
631
|
+
description: >-
|
|
632
|
+
Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
|
|
633
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
608
634
|
default: 2
|
|
609
635
|
ssl_options:
|
|
610
636
|
type: array
|
|
@@ -635,17 +661,60 @@ components:
|
|
|
635
661
|
description: Maximum number of retry attempts. (Rest)
|
|
636
662
|
default: 1
|
|
637
663
|
retry_sleep:
|
|
638
|
-
|
|
639
|
-
|
|
664
|
+
oneOf:
|
|
665
|
+
- type: string
|
|
666
|
+
- type: number
|
|
667
|
+
minimum: 0
|
|
668
|
+
description: >-
|
|
669
|
+
Delay in seconds between retry attempts. (Rest)
|
|
670
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
640
671
|
default: 4
|
|
641
672
|
token_cache_max_age:
|
|
642
|
-
|
|
643
|
-
|
|
673
|
+
oneOf:
|
|
674
|
+
- type: string
|
|
675
|
+
- type: number
|
|
676
|
+
minimum: 0
|
|
677
|
+
description: >-
|
|
678
|
+
Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
|
|
679
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
644
680
|
default: 1800
|
|
645
681
|
token_refresh_threshold:
|
|
646
|
-
|
|
647
|
-
|
|
682
|
+
oneOf:
|
|
683
|
+
- type: string
|
|
684
|
+
- type: number
|
|
685
|
+
minimum: 0
|
|
686
|
+
description: >-
|
|
687
|
+
Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
|
|
688
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
648
689
|
default: 120
|
|
690
|
+
token_refresh_max_age:
|
|
691
|
+
oneOf:
|
|
692
|
+
- type: string
|
|
693
|
+
- type: number
|
|
694
|
+
minimum: 0
|
|
695
|
+
description: >-
|
|
696
|
+
Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit.
|
|
697
|
+
E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth)
|
|
698
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
699
|
+
default: 0
|
|
700
|
+
jwt_accepted_offset_sec:
|
|
701
|
+
oneOf:
|
|
702
|
+
- type: string
|
|
703
|
+
- type: number
|
|
704
|
+
minimum: 0
|
|
705
|
+
description: >-
|
|
706
|
+
Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth)
|
|
707
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
708
|
+
default: 300
|
|
709
|
+
jwt_expiry_offset_sec:
|
|
710
|
+
oneOf:
|
|
711
|
+
- type: string
|
|
712
|
+
- type: number
|
|
713
|
+
minimum: 0
|
|
714
|
+
description: >-
|
|
715
|
+
Validity of a generated JWT, used to request a token. (OAuth)
|
|
716
|
+
A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.
|
|
717
|
+
default: 3600
|
|
649
718
|
VaultHashicorpOptions:
|
|
650
719
|
type: object
|
|
651
720
|
description: >-
|
|
@@ -1265,10 +1334,10 @@ components:
|
|
|
1265
1334
|
examples:
|
|
1266
1335
|
- /opt/aspera/orchestrator/var/run/orchestrator/workflows/import/my_workflow.yml
|
|
1267
1336
|
add_as_revision:
|
|
1268
|
-
type: integer
|
|
1337
|
+
type: [integer, 'null']
|
|
1269
1338
|
description: >-
|
|
1270
1339
|
ID of an existing workflow: the file is imported as a new revision of this workflow (to be published).
|
|
1271
|
-
If not set, a new workflow is created.
|
|
1340
|
+
If not set, or `null`, a new workflow is created.
|
|
1272
1341
|
examples:
|
|
1273
1342
|
- 123
|
|
1274
1343
|
subwf_constraints:
|
|
@@ -1437,6 +1506,74 @@ components:
|
|
|
1437
1506
|
Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8, or on Windows, the terminal renders Unicode (e.g. Windows Terminal, VS Code).
|
|
1438
1507
|
img:
|
|
1439
1508
|
$ref: "#/components/schemas/ImageOptions"
|
|
1509
|
+
PollOptions:
|
|
1510
|
+
type: object
|
|
1511
|
+
description: >-
|
|
1512
|
+
Repeat a read-only command (e.g. `list`, `show`, `status`) and display its result,
|
|
1513
|
+
until a condition is met, or a number of runs or a time is reached.
|
|
1514
|
+
The command runs first immediately, then again `interval` seconds after the end of each run.
|
|
1515
|
+
Without `max`, `timeout` and `until`, it runs until interrupted (Ctrl-C).
|
|
1516
|
+
Refused on a command that changes state (e.g. `send`, `create`, `delete`, `start`), before anything is executed.
|
|
1517
|
+
Formatting options (`--format`, `--fields`, `--out.query`) apply to each result displayed.
|
|
1518
|
+
A short status line on `stderr` gives the run number and the time before each result displayed.
|
|
1519
|
+
By default, an error of a run (e.g. an API error) ends the command with that error (see `errors`).
|
|
1520
|
+
additionalProperties: false
|
|
1521
|
+
properties:
|
|
1522
|
+
interval:
|
|
1523
|
+
oneOf:
|
|
1524
|
+
- type: number
|
|
1525
|
+
minimum: 0
|
|
1526
|
+
- type: string
|
|
1527
|
+
description: >-
|
|
1528
|
+
Time to wait after a run, before the next one.
|
|
1529
|
+
A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).
|
|
1530
|
+
default: 5
|
|
1531
|
+
max:
|
|
1532
|
+
type: integer
|
|
1533
|
+
minimum: 1
|
|
1534
|
+
description: Maximum number of runs. No limit by default.
|
|
1535
|
+
timeout:
|
|
1536
|
+
oneOf:
|
|
1537
|
+
- type: number
|
|
1538
|
+
minimum: 0
|
|
1539
|
+
- type: string
|
|
1540
|
+
description: >-
|
|
1541
|
+
Maximum time since the start of the first run.
|
|
1542
|
+
A duration, as `interval`, e.g. `600`, `10m`, `1h`.
|
|
1543
|
+
A last run occurs at this time. No limit by default.
|
|
1544
|
+
With `max`, polling stops at the first limit reached.
|
|
1545
|
+
until:
|
|
1546
|
+
type: string
|
|
1547
|
+
description: >-
|
|
1548
|
+
JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data:
|
|
1549
|
+
after `--select` (for a list of objects), before `--fields` and `--out.query`.
|
|
1550
|
+
Polling stops at the first run where it is true: as in JMESPath, `false`, `null`, empty string, empty list and empty object are false, other values are true.
|
|
1551
|
+
So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item.
|
|
1552
|
+
The syntax is checked before the first run.
|
|
1553
|
+
If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1).
|
|
1554
|
+
show:
|
|
1555
|
+
type: string
|
|
1556
|
+
description: >-
|
|
1557
|
+
Which results are displayed.
|
|
1558
|
+
|
|
1559
|
+
- `change`: the first result, then each result whose display differs from the previous one.
|
|
1560
|
+
|
|
1561
|
+
- `each`: every result.
|
|
1562
|
+
|
|
1563
|
+
- `last`: only the last result, when polling stops (including when the condition is not met).
|
|
1564
|
+
enum: [change, each, last]
|
|
1565
|
+
default: change
|
|
1566
|
+
errors:
|
|
1567
|
+
type: string
|
|
1568
|
+
description: >-
|
|
1569
|
+
What an error of a run does (e.g. an API error, an entity not found yet).
|
|
1570
|
+
|
|
1571
|
+
- `fail`: the command ends with this error.
|
|
1572
|
+
|
|
1573
|
+
- `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false.
|
|
1574
|
+
If the last run fails, the command ends with its error.
|
|
1575
|
+
enum: [fail, retry]
|
|
1576
|
+
default: fail
|
|
1440
1577
|
WebServerOptions:
|
|
1441
1578
|
type: object
|
|
1442
1579
|
description: >-
|
data/lib/aspera/cli/parser.rb
CHANGED
|
@@ -243,13 +243,15 @@ module Aspera
|
|
|
243
243
|
#
|
|
244
244
|
# @param description [String] description of the identifier
|
|
245
245
|
# @param multiple [Boolean] `true`: read a list of IDs (bulk operation)
|
|
246
|
+
# @param mandatory [Boolean] `false`: the identifier may be absent, then `default` is returned
|
|
247
|
+
# @param default [Object] value when the identifier is absent and not mandatory
|
|
246
248
|
# @param block [Proc] block to search for identifier based on attribute value
|
|
247
249
|
# @return [String, Array<String>] identifier or list of IDs (if `multiple`)
|
|
248
250
|
# @yieldparam field [String] The field name from percent selector
|
|
249
251
|
# @yieldparam value [String] The value from percent selector
|
|
250
252
|
# @yieldreturn [String] Resolved identifier
|
|
251
|
-
def instance_identifier(description: 'identifier', multiple: false, &block)
|
|
252
|
-
res_id = get_next_argument(description, multiple: multiple)
|
|
253
|
+
def instance_identifier(description: 'identifier', multiple: false, mandatory: true, default: nil, &block)
|
|
254
|
+
res_id = get_next_argument(description, multiple: multiple, mandatory: mandatory, default: default)
|
|
253
255
|
# Can be an Array
|
|
254
256
|
if res_id.is_a?(String) && (m = Parser.percent_selector(res_id))
|
|
255
257
|
Aspera.assert(block_given?, type: Cli::BadArgument) { "Percent syntax for #{description} not supported in this context" }
|
|
@@ -403,7 +405,8 @@ module Aspera
|
|
|
403
405
|
result = {}
|
|
404
406
|
@command_line.each_long_option_with_value(after_command: after_command) do |tok|
|
|
405
407
|
path = [tok.name, *tok.dot_path]
|
|
406
|
-
|
|
408
|
+
declare_secrets(path.last, tok.value)
|
|
409
|
+
Log.log.debug { "option #{path.join(DotContainer::SEPARATOR)}=#{Secret::Hider.instance.hidden_copy(tok.value)}" }
|
|
407
410
|
DotContainer.dotted_to_container(path, Parser.smart_convert(tok.value), result)
|
|
408
411
|
end
|
|
409
412
|
result
|
|
@@ -692,6 +695,7 @@ module Aspera
|
|
|
692
695
|
# @param source [Symbol] `OptionSource`
|
|
693
696
|
# @param replace [Boolean] replace a pending value from same source
|
|
694
697
|
def add_pending_value(option_symbol, value, source, replace:)
|
|
698
|
+
declare_secrets(option_symbol, value)
|
|
695
699
|
entries = (@pending_values[option_symbol] ||= [])
|
|
696
700
|
index = entries.index { |e| e[:source].eql?(source) }
|
|
697
701
|
if index.nil?
|
|
@@ -701,6 +705,14 @@ module Aspera
|
|
|
701
705
|
end
|
|
702
706
|
end
|
|
703
707
|
|
|
708
|
+
# Declare secret values of an option not declared yet, by option name (as `OptionValue#store` does for a declared option),
|
|
709
|
+
# so that they are hidden wherever they appear (logs, results), also in a structure (e.g. `{value:, source:}` of a pending value)
|
|
710
|
+
# @param name [Symbol, String] option name
|
|
711
|
+
# @param value [Object] value
|
|
712
|
+
def declare_secrets(name, value)
|
|
713
|
+
Secret::Hider.instance.add_named_secrets(name, value)
|
|
714
|
+
end
|
|
715
|
+
|
|
704
716
|
# Apply pending values (presets, env) of declared options, lowest priority first
|
|
705
717
|
def apply_pending_values
|
|
706
718
|
ready = @pending_values.select { |k, _| @registry.declared?(k) }
|
|
@@ -746,7 +746,7 @@ module Aspera
|
|
|
746
746
|
Result::ObjectList.new(events)
|
|
747
747
|
end
|
|
748
748
|
)
|
|
749
|
-
command :transfers, description: 'List transfer events',
|
|
749
|
+
command :transfers, read_only: true, description: 'List transfer events',
|
|
750
750
|
arguments: [
|
|
751
751
|
EVENT_RESOURCE_TYPE_ARG,
|
|
752
752
|
EVENT_RESOURCE_ID_ARG.merge(mandatory: false, default: nil)
|
|
@@ -1080,6 +1080,8 @@ module Aspera
|
|
|
1080
1080
|
|
|
1081
1081
|
# packages > send
|
|
1082
1082
|
def action_packages_send(package:, **)
|
|
1083
|
+
# The package is created before the transfer
|
|
1084
|
+
transfer.assert_no_dry_run
|
|
1083
1085
|
package_data = package
|
|
1084
1086
|
new_user_option = options.get_option(:new_user_option)
|
|
1085
1087
|
option_validate = options.get_option(:validate_metadata)
|
|
@@ -1142,7 +1144,7 @@ module Aspera
|
|
|
1142
1144
|
dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
|
|
1143
1145
|
formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
|
|
1144
1146
|
statuses = transfer.start(transfer_spec, oauth_api: package_node_api)
|
|
1145
|
-
File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
|
|
1147
|
+
File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata && !statuses.is_a?(Transfer::Result::DryRun)
|
|
1146
1148
|
result_transfer.push({'package' => package_id, Runner::STATUS_FIELD => statuses})
|
|
1147
1149
|
if skip_ids_persistency && statuses.is_a?(Transfer::Result::Success)
|
|
1148
1150
|
skip_ids_persistency.data.push(package_id)
|
|
@@ -46,7 +46,7 @@ module Aspera
|
|
|
46
46
|
command :aws_trust_policy, description: 'Show AWS trust policy', action: ->(**) { Result::SingleObject.new(ats_api.read('aws/trustpolicy', {region: options.get_option(:region, mandatory: true)})) }
|
|
47
47
|
|
|
48
48
|
commands_under :cluster do
|
|
49
|
-
command :clouds, description: 'List cloud providers', action: ->(**) { Result::ObjectList.new(@ats_api_open.cloud_names.map { |k, v| CLOUD_TABLE.zip([k, v]).to_h }) }
|
|
49
|
+
command :clouds, read_only: true, description: 'List cloud providers', action: ->(**) { Result::ObjectList.new(@ats_api_open.cloud_names.map { |k, v| CLOUD_TABLE.zip([k, v]).to_h }) }
|
|
50
50
|
command :list, description: 'List ATS servers', action: ->(**) { Result::ObjectList.new(@ats_api_open.all_servers, fields: %w[id cloud region]) }
|
|
51
51
|
command :show, description: 'Show a specific server (or use options cloud and region)',
|
|
52
52
|
arguments: [{name: :server_id, mandatory: false, default: nil}]
|
|
@@ -7,6 +7,7 @@ require_relative '../extended_value'
|
|
|
7
7
|
require_relative '../parser'
|
|
8
8
|
require_relative '../../assert'
|
|
9
9
|
require_relative '../result'
|
|
10
|
+
require_relative '../poll'
|
|
10
11
|
require_relative '../command_registry'
|
|
11
12
|
require_relative '../option_declarator'
|
|
12
13
|
require_relative '../special_values'
|
|
@@ -289,6 +290,7 @@ module Aspera
|
|
|
289
290
|
option :query, description: 'Additional filter for for some commands (list/delete)', allowed: [Hash, Array, NilClass]
|
|
290
291
|
option :bulk, description: 'Bulk operation (only some)', allowed: Type::BOOLEAN, default: false
|
|
291
292
|
option :bfail, description: 'Bulk operation error handling', allowed: Type::BOOLEAN, default: true
|
|
293
|
+
option :poll, description: 'Repeat a read-only command (dot-notation: interval, max, timeout, until, show, errors)', schema: Schema::Registry::POLL_OPTIONS
|
|
292
294
|
|
|
293
295
|
def initialize(context:)
|
|
294
296
|
Aspera.assert_type(context, Context) { 'context' }
|
|
@@ -354,6 +356,8 @@ module Aspera
|
|
|
354
356
|
end
|
|
355
357
|
else
|
|
356
358
|
Security.instance.check_level(spec.security, "command #{current_path.join(' ')}") if spec
|
|
359
|
+
# Before anything is executed (setup, arguments, action)
|
|
360
|
+
poll = poll_result(current_path, spec) if is_leaf
|
|
357
361
|
# Phase A - for intermediate nodes only: resolve all ArgumentSpec declared on this node
|
|
358
362
|
# before dispatching to children (leaf nodes resolve their arguments inside execute_leaf).
|
|
359
363
|
ctx = resolve_arguments(spec.arguments, ctx) if !is_leaf && spec&.arguments
|
|
@@ -362,7 +366,7 @@ module Aspera
|
|
|
362
366
|
|
|
363
367
|
# Phase B - leaf fast-path or child dispatch
|
|
364
368
|
if is_leaf
|
|
365
|
-
dispatch_leaf(current_path, spec, ctx)
|
|
369
|
+
dispatch_leaf(current_path, spec, ctx, poll: poll)
|
|
366
370
|
else
|
|
367
371
|
dispatch_child(current_path, registry, ctx)
|
|
368
372
|
end
|
|
@@ -373,13 +377,32 @@ module Aspera
|
|
|
373
377
|
# @param current_path [Array<Symbol>]
|
|
374
378
|
# @param spec [CommandSpec]
|
|
375
379
|
# @param ctx [Hash]
|
|
380
|
+
# @param poll [Result::Poll, nil] With option `poll`: result that executes the action when displayed
|
|
376
381
|
# @return [Object]
|
|
377
|
-
def dispatch_leaf(current_path, spec, ctx)
|
|
382
|
+
def dispatch_leaf(current_path, spec, ctx, poll: nil)
|
|
378
383
|
if @context.help_requested
|
|
379
384
|
@help_path = current_path
|
|
380
385
|
raise Cli::HelpRequest, self
|
|
381
386
|
end
|
|
382
|
-
execute_leaf(spec, ctx)
|
|
387
|
+
execute_leaf(spec, ctx, poll: poll)
|
|
388
|
+
end
|
|
389
|
+
|
|
390
|
+
# With option `poll`, check that the command is read-only, and the parameters of `poll`
|
|
391
|
+
# @param current_path [Array<Symbol>] path of the leaf command
|
|
392
|
+
# @param spec [CommandSpec] leaf command
|
|
393
|
+
# @return [Result::Poll, nil] `nil` if option `poll` is not set
|
|
394
|
+
# @raise [Cli::BadArgument] if the command is not read-only, or a parameter is invalid
|
|
395
|
+
def poll_result(current_path, spec)
|
|
396
|
+
parameters = options.get_option(:poll)
|
|
397
|
+
return if parameters.nil? || parameters.empty?
|
|
398
|
+
command = [self.class.name.split('::').last.downcase, *current_path].join(' ')
|
|
399
|
+
Aspera.assert(spec.read_only?, type: Cli::BadArgument) do
|
|
400
|
+
"Option poll: refused on `#{command}`: only a read-only command can be repeated (e.g. list, show, status)"
|
|
401
|
+
end
|
|
402
|
+
# Options that make a read-only command change state at each run
|
|
403
|
+
Aspera.assert(!options.get_option(:once_only), type: Cli::BadArgument) { 'Option poll: refused with option once_only: it saves state at each run' }
|
|
404
|
+
Aspera.assert(options.get_option(:notify_to).nil?, type: Cli::BadArgument) { 'Option poll: refused with option notify_to: it sends emails at each run' }
|
|
405
|
+
Result::Poll.new(parameters, format: formatter&.format_type)
|
|
383
406
|
end
|
|
384
407
|
|
|
385
408
|
# Phase B, child branch: consume the next command argument, then either continue
|
|
@@ -486,13 +509,17 @@ module Aspera
|
|
|
486
509
|
# they are not read again from the command line.
|
|
487
510
|
# @param spec [CommandSpec] a leaf node (no children)
|
|
488
511
|
# @param ctx [Hash] accumulated context (pre-resolved keys are not re-consumed)
|
|
512
|
+
# @param poll [Result::Poll, nil] With option `poll`: the action is executed when this result is displayed
|
|
489
513
|
# @return [Object]
|
|
490
|
-
def execute_leaf(spec, ctx)
|
|
514
|
+
def execute_leaf(spec, ctx, poll: nil)
|
|
491
515
|
a = action_for(spec)
|
|
492
516
|
# Always resolve declared arguments (even when transfer_paths is set — those arguments
|
|
493
517
|
# are consumed first; ts_source_paths then reads whatever remains in the queue).
|
|
494
518
|
ctx = resolve_arguments(spec.arguments, ctx) if spec.arguments
|
|
495
|
-
invoke_action(a, [], ctx)
|
|
519
|
+
return invoke_action(a, [], ctx) if poll.nil?
|
|
520
|
+
# Arguments are resolved once, the action is executed at each run
|
|
521
|
+
poll.action = -> { invoke_action(a, [], ctx) }
|
|
522
|
+
poll
|
|
496
523
|
end
|
|
497
524
|
|
|
498
525
|
# Resolve positional arguments from the CLI argument stream, in order.
|
|
@@ -555,7 +582,7 @@ module Aspera
|
|
|
555
582
|
else
|
|
556
583
|
case arg_spec.type
|
|
557
584
|
when :identifier
|
|
558
|
-
options.instance_identifier(description: arg_spec.name.to_s, &block)
|
|
585
|
+
options.instance_identifier(description: arg_spec.name.to_s, mandatory: arg_spec.mandatory, default: arg_spec.default, &block)
|
|
559
586
|
else
|
|
560
587
|
# Class or Array<Class> -> pass as validation type
|
|
561
588
|
# When interactive: true, prompt for this argument only when no CLI argument is provided
|
|
@@ -158,6 +158,14 @@ module Aspera
|
|
|
158
158
|
{name: :location, type: Symbol, mandatory: false, default: :github, allowed: %i[github local toc]},
|
|
159
159
|
{name: :section, mandatory: false}
|
|
160
160
|
]
|
|
161
|
+
command(
|
|
162
|
+
:skill, description: 'Display the agent skill: how an AI drives IBM Aspera products with ascli (same as llms.txt)',
|
|
163
|
+
action: lambda do |**|
|
|
164
|
+
skill_file = File.join(self.class.gem_src_root, '..', 'skills', 'ascli', 'SKILL.md')
|
|
165
|
+
Aspera.assert(File.exist?(skill_file), type: Cli::Error) { "Agent skill not found: #{skill_file}" }
|
|
166
|
+
Result::Text.new(File.read(skill_file))
|
|
167
|
+
end
|
|
168
|
+
)
|
|
161
169
|
command(
|
|
162
170
|
:genkey, description: 'Generate a new RSA private key',
|
|
163
171
|
arguments: [
|
|
@@ -173,7 +181,7 @@ module Aspera
|
|
|
173
181
|
arguments: [{name: :private_key_pem}],
|
|
174
182
|
action: ->(private_key_pem:, **) { Result::Text.new(OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s) }
|
|
175
183
|
command :remote_certificate, description: 'Retrieve the certificate chain of a remote HTTPS server'
|
|
176
|
-
command :echo, description: 'Show the value of a given argument',
|
|
184
|
+
command :echo, read_only: true, description: 'Show the value of a given argument',
|
|
177
185
|
arguments: [{name: :value, type: nil}],
|
|
178
186
|
action: ->(value:, **) { Result.auto(value) }
|
|
179
187
|
command :download, description: 'Download a file from a URL',
|
|
@@ -375,6 +383,9 @@ module Aspera
|
|
|
375
383
|
command :errors, description: 'Show FASP error codes: of the management port (default), or of sessions (errcode in logs)',
|
|
376
384
|
arguments: [{name: :kind, allowed: %i[management session], mandatory: false, default: :management}]
|
|
377
385
|
ascp_logs_commands :logs
|
|
386
|
+
commands_under :logs do
|
|
387
|
+
command :find, description: 'Find the ascp log files of this system: of installed products, and default locations', action: :action_ascp_logs_find
|
|
388
|
+
end
|
|
378
389
|
command :products, description: 'Manage installed Aspera products'
|
|
379
390
|
commands_under :products do
|
|
380
391
|
command :list, description: 'List installed Aspera products',
|
|
@@ -299,6 +299,8 @@ module Aspera
|
|
|
299
299
|
end
|
|
300
300
|
|
|
301
301
|
def package_send(parameters)
|
|
302
|
+
# The package is created before the transfer
|
|
303
|
+
transfer.assert_no_dry_run
|
|
302
304
|
# autofill recipient for public url
|
|
303
305
|
if api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
|
|
304
306
|
parameters['recipients'] = [{
|
|
@@ -499,7 +501,7 @@ module Aspera
|
|
|
499
501
|
|
|
500
502
|
# :health and :postprocessing work without authentication: they do not use api_v5.
|
|
501
503
|
command :health, description: 'Check Faspex 5 health'
|
|
502
|
-
command :version, description: 'Show Faspex 5 version', action: ->(**) { Result::SingleObject.new(api_v5.read('version')) }
|
|
504
|
+
command :version, read_only: true, description: 'Show Faspex 5 version', action: ->(**) { Result::SingleObject.new(api_v5.read('version')) }
|
|
503
505
|
command :bearer_token, description: 'Show OAuth bearer token', action: ->(**) { Result::Text.new(api_v5.oauth.authorization) }
|
|
504
506
|
# Package id argument; with a public link to a package, setup_package_id provides it instead
|
|
505
507
|
PACKAGE_ID_ARG = [{name: :package_id, type: :identifier}].freeze
|
|
@@ -115,6 +115,20 @@ module Aspera
|
|
|
115
115
|
["orchestrator", "workflows", "development", "manual", "section", "<manual_anchor>"]
|
|
116
116
|
Before importing a workflow file, check it (graph, templates, inputs of steps) and fix all errors:
|
|
117
117
|
["orchestrator", "workflows", "check_import", "<file>"]
|
|
118
|
+
|
|
119
|
+
AOC AUTOMATION WORKFLOW DEVELOPMENT
|
|
120
|
+
Before writing or modifying an Aspera on Cloud Automation workflow, read the development guide
|
|
121
|
+
(large: read sections, not the whole document). Start with the section of each trigger and action
|
|
122
|
+
used (for example "Send a package" is action type package_transfer, section "package-transfer"),
|
|
123
|
+
then "payload-rules-enforced-by-the-api" and "finding-the-identifiers":
|
|
124
|
+
["aoc", "automation", "guide", "section", "package-transfer"]
|
|
125
|
+
Other sections: "triggers", "actions", "substitution-variables", "importing-a-workflow",
|
|
126
|
+
"design-recipes-and-patterns", "common-pitfalls-and-resolutions". List the anchors with:
|
|
127
|
+
["aoc", "automation", "guide", "toc"]
|
|
128
|
+
|
|
129
|
+
GENERAL GUIDANCE
|
|
130
|
+
For the general rules of use of ascli by an AI (written for a shell: each command line maps to args):
|
|
131
|
+
["config", "skill"]
|
|
118
132
|
INST
|
|
119
133
|
|
|
120
134
|
# Keys forwarded to MCP::Server constructor (symbolized)
|
|
@@ -129,7 +129,7 @@ module Aspera
|
|
|
129
129
|
spec: {description: 'Show transfer spec base'},
|
|
130
130
|
api_details: {description: 'Show API details'},
|
|
131
131
|
health: {description: 'Check node health'},
|
|
132
|
-
events: {description: 'List events'},
|
|
132
|
+
events: {description: 'List events', read_only: true},
|
|
133
133
|
info: {description: 'Show node info'},
|
|
134
134
|
slash: {description: 'Show root info'},
|
|
135
135
|
license: {description: 'Show license'},
|
|
@@ -156,7 +156,7 @@ module Aspera
|
|
|
156
156
|
modify: {description: 'Modify file', arguments: [{name: :path}, {name: :file, type: Hash, schema: 'node:components.schemas.files-id-put-request'}]},
|
|
157
157
|
cat: {description: 'Show file contents', arguments: SINGLE_PATH_ARG},
|
|
158
158
|
show: {description: 'Show file info', arguments: SINGLE_PATH_ARG},
|
|
159
|
-
thumbnail: {description: 'Show file thumbnail', arguments: SINGLE_PATH_ARG},
|
|
159
|
+
thumbnail: {description: 'Show file thumbnail', arguments: SINGLE_PATH_ARG, read_only: true},
|
|
160
160
|
bearer_token_node: {description: 'Show bearer token for file node', arguments: SINGLE_PATH_ARG},
|
|
161
161
|
node_info: {description: 'Show node info for file', arguments: SINGLE_PATH_ARG},
|
|
162
162
|
ls: {description: 'List files', arguments: SINGLE_PATH_ARG, aliases: [:browse]},
|
|
@@ -454,19 +454,19 @@ module Aspera
|
|
|
454
454
|
Result::Status.new('Done')
|
|
455
455
|
end
|
|
456
456
|
)
|
|
457
|
-
command :bandwidth, description: 'Show sync bandwidth',
|
|
457
|
+
command :bandwidth, read_only: true, description: 'Show sync bandwidth',
|
|
458
458
|
arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
|
|
459
459
|
action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/bandwidth", query_read_delete(default: {}))) }
|
|
460
|
-
command :counters, description: 'Show sync counters',
|
|
460
|
+
command :counters, read_only: true, description: 'Show sync counters',
|
|
461
461
|
arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
|
|
462
462
|
action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/counters", query_read_delete(default: {}))) }
|
|
463
|
-
command :files, description: 'List sync files',
|
|
463
|
+
command :files, read_only: true, description: 'List sync files',
|
|
464
464
|
arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
|
|
465
465
|
action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/files", query_read_delete(default: {}))) }
|
|
466
|
-
command :state, description: 'Show sync state',
|
|
466
|
+
command :state, read_only: true, description: 'Show sync state',
|
|
467
467
|
arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
|
|
468
468
|
action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/state")) }
|
|
469
|
-
command :summary, description: 'Show sync summary',
|
|
469
|
+
command :summary, read_only: true, description: 'Show sync summary',
|
|
470
470
|
arguments: [{name: :ssync_id, type: :identifier, lookup: :ssync_lookup}],
|
|
471
471
|
action: ->(ssync_id:, **) { Result::SingleObject.new(api_node.read("asyncs/#{ssync_id}/summary")) }
|
|
472
472
|
end
|
|
@@ -561,7 +561,7 @@ module Aspera
|
|
|
561
561
|
Result::Status.new("#{watch_folder_id} deleted")
|
|
562
562
|
end
|
|
563
563
|
)
|
|
564
|
-
command :state, description: 'Show watch folder state',
|
|
564
|
+
command :state, read_only: true, description: 'Show watch folder state',
|
|
565
565
|
arguments: [{name: :watch_folder_id, type: :identifier}],
|
|
566
566
|
action: ->(watch_folder_id:, **) { Result::SingleObject.new(api_node.read("v3/watchfolders/#{watch_folder_id}/state")) }
|
|
567
567
|
end
|
|
@@ -9,6 +9,22 @@ require_relative '../error'
|
|
|
9
9
|
module Aspera
|
|
10
10
|
module Cli
|
|
11
11
|
module Plugins
|
|
12
|
+
# Options of OAuth web authentication (authorization code): client and redirect URI.
|
|
13
|
+
# For a plugin that uses only this flow: `use_options OauthWebOptions` (without the options of `Oauth`)
|
|
14
|
+
module OauthWebOptions
|
|
15
|
+
extend OptionDeclarator
|
|
16
|
+
option :client_id, description: 'OAuth client identifier'
|
|
17
|
+
option :client_secret, description: 'OAuth client secret'
|
|
18
|
+
option :redirect_uri, description: 'OAuth (Web) redirect URI for web authentication'
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# Options of OAuth JWT authentication: private key
|
|
22
|
+
module OauthJwtOptions
|
|
23
|
+
extend OptionDeclarator
|
|
24
|
+
option :private_key, description: 'OAuth (JWT) RSA private key PEM value (prefix file path with @file:)'
|
|
25
|
+
option :passphrase, description: 'OAuth (JWT) RSA private key passphrase'
|
|
26
|
+
end
|
|
27
|
+
|
|
12
28
|
# base class for applications supporting OAuth 2.0 authentication
|
|
13
29
|
class Oauth < BasicAuth
|
|
14
30
|
class << self
|
|
@@ -33,11 +49,8 @@ module Aspera
|
|
|
33
49
|
# Options used for authentication (url, auth, client_id, etc...)
|
|
34
50
|
AUTH_OPTIONS = %i[url auth client_id client_secret redirect_uri private_key passphrase username password].freeze
|
|
35
51
|
option :auth, description: 'OAuth type of authentication', allowed: AUTH_TYPES, default: :jwt
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
option :redirect_uri, description: 'OAuth (Web) redirect URI for web authentication'
|
|
39
|
-
option :private_key, description: 'OAuth (JWT) RSA private key PEM value (prefix file path with @file:)'
|
|
40
|
-
option :passphrase, description: 'OAuth (JWT) RSA private key passphrase'
|
|
52
|
+
use_options OauthWebOptions
|
|
53
|
+
use_options OauthJwtOptions
|
|
41
54
|
end
|
|
42
55
|
end
|
|
43
56
|
end
|