aspera-cli 4.24.1 → 4.25.0.pre

data/lib/aspera/transfer/spec.schema.yaml

@@ -1,10 +1,18 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 $id: https://github.com/IBM/aspera-cli/tree/main/lib/aspera/transfer/spec.schema.yaml
-$comment: >-
-  The original file is the YAML file.
-  `x-` fields documented in command_line_builder.rb
 title: Aspera Transfer Specification
 description: Information defining an Aspera transfer.
+$comment: >-
+  The original file is the YAML file.
+  The following extensions are used for mapping to ascp arguments.
+  x-cli-envvar   [String]       Name of env var
+  x-cli-option   [String]       Command line option (starts with "-"), or `true`: same as ts, or `false`: not an option
+  x-cli-switch   [Bool]         `true` if option has no arg, else by default option has a value
+  x-cli-special  [Bool]         `true` if not anaged by command line generator (special handling: option or argument)
+  x-cli-convert  [String,Hash]  Method name for Convert object or Conversion Hash for enum: ts to arg
+  x-agents       [Array]        Supported agents (for doc only), if not specified: all
+  x-deprecation  [String]       Deprecation message for doc
+  `x-` fields are also documented in `command_line_builder.rb`
 type: object
 required:
   - destination_root
@@ -15,12 +23,14 @@ required:
 properties:
   apply_local_docroot:
     description: Apply local docroot to source paths.
+    type: boolean
     x-agents:
       - direct
       - transferd
     x-cli-switch: true
   cipher:
     description: In transit encryption algorithms.
+    type: string
     enum:
       - none
       - aes-128
@@ -36,15 +46,22 @@ properties:
     x-cli-option: -c
     x-cli-convert: remove_hyphen
   content_protection:
-    description: Enable client-side encryption at rest (CSEAR).
-      (content protection)
+    description: >-
+      Enable client-side content protection (CSEAR, encryption-at-rest).
+
+      For uploads, set to `encrypt` to transfer encrypted files and store them
+      on the server with the extension `.aspera-env`.
+      (`aspera.conf` parameter `transfer_encryption_content_protection_extension`).
+      To download and decrypt encrypted files, set to `decrypt`
+
+      `content_protection_password` must be specified if this option is set.
+    type: string
     enum:
       - encrypt
       - decrypt
     x-cli-option: --file-crypt
   content_protection_password:
-    description: Specifies CSEAR password.
-      (content protection)
+    description: Password for encryption/decryption of transferred assets.
     type: string
     x-cli-envvar: ASPERA_SCP_FILEPASS
   cookie:
@@ -52,7 +69,27 @@ properties:
     type: string
     x-cli-envvar: ASPERA_SCP_COOKIE
   create_dir:
-    description: Specifies whether to create new directories.
+    description: >-
+      Create target directory if it doesn't already exist.
+
+      If **all** the following conditions are met, then the `destination_root` specifies a filename instead of destination folder:
+
+      - `create_dir` is `false`
+
+      - A single source file is given on **command line**
+
+      - The target folder specified by `destination_root` does not exist
+
+      In all other cases, `destination_root` specifies a folder, and it is created if it does not already exist.
+      I.e. if **any** of those conditions is met:
+
+      - `create_dir` is `true`
+
+      - Multiple source files are provided
+
+      - List of source files are provided in a file (list or pair), default for Node API and `ascli`.
+
+      - The target folder exists
     type: boolean
     x-cli-option: -d
     x-cli-switch: true
@@ -64,20 +101,25 @@ properties:
 
       Objects on the destination that have the same name but different type or size as objects
       on the source are not deleted.
+    type: boolean
     x-cli-switch: true
   delete_source:
-    description: Remove transfered source files after transfer success.
-      TODO equivalent to `remove_after_transfer` + `remove_empty_directories` + `remove_empty_source_directory`
+    $comment: "TODO: implement"
+    description: >-
+      Remove transfered source files after transfer success.
+      Equivalent to `remove_after_transfer` + `remove_empty_directories` + `remove_empty_source_directory`.
+      Take precedence over those.
     type: boolean
     x-agents:
-      - node
       - direct
       - transferd
-    x-cli-option: --remove-after-transfer
-    x-cli-switch: true
+      - node
+    x-cli-special: true
   destination_root:
     description: Destination root directory.
+    type: string
     x-cli-special: true
+    $comment: Last argument on ascp command line.
   destination_root_id:
     description: >-
       The file ID of the destination root directory.
@@ -88,6 +130,7 @@ properties:
       - transferd
   direction:
     description: Direction of transfer (on client side).
+    type: string
     enum:
       - send
       - receive
@@ -102,6 +145,7 @@ properties:
 
       e.g. `-86400` for newer than a day back.
     type: string
+    x-cli-option: true
   exclude_older_than:
     description: >-
       Exclude files, but not directories, from the transfer if they are older
@@ -109,10 +153,12 @@ properties:
 
       e.g. `-86400` for older than a day back.
     type: string
+    x-cli-option: true
   fail_bad_filepass:
     description: Fail on bad file decryption passphrase.
     type: boolean
     x-cli-switch: true
+    x-cli-option: true
     x-agents:
       - direct
       - transferd
@@ -128,6 +174,7 @@ properties:
       - transferd
   file_checksum:
     description: Enable checksum reporting for transferred files by specifying the hash to use.
+    type: string
     enum:
       - sha-512
       - sha-384
@@ -137,8 +184,9 @@ properties:
       - none
     default: none
     x-agents:
-      - node
       - direct
+      - node
+    x-cli-option: true
   http_fallback:
     description: When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.
     type:
@@ -163,7 +211,8 @@ properties:
     x-agents:
       - transferd
   lock_min_rate:
-    description: "TODO: remove ?"
+    $comment: "TODO: Remove ?"
+    description: "n/a"
     type: boolean
     x-agents:
       - connect
@@ -183,15 +232,16 @@ properties:
       - transferd
       - connect
   lock_target_rate:
-    description: "TODO: remove ?"
+    $comment: "TODO: Remove ?"
+    description: "n/a"
     type: boolean
     x-agents:
       - connect
   lock_target_rate_kbps:
     description: >-
-      If `true`, lock the target transfer rate to the default value set for target_rate_kbps.
+      If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.
 
-      If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
+      If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.
     type: boolean
     x-agents:
       - transferd
@@ -212,7 +262,7 @@ properties:
       Move source files to the specified `archive-dir` directory after they are transferred correctly.
 
       Available as of 3.8.0.
-      Details in ascp manual.
+      Details in `ascp` manual.
 
       Requires write permissions on the source.
 
@@ -228,12 +278,14 @@ properties:
       Empty directories are not saved to `archive-dir`.
       To remove empty source directories after a successful move operation, also set `remove_empty_directories` to `true`.
       When using `remove_empty_directories`, empty directory removal examination starts at the `srcbase` and proceeds down any subdirectories.
-      If no `srcbase` is used and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is examined and removed if it is empty following the move of the source file.
+      If no `srcbase` is used and a file path (as opposed to a directory path) is specified,
+      then only the immediate parent directory is examined and removed if it is empty following the move of the source file.
     type: string
     x-agents:
       - direct
-      - node
       - transferd
+      - node
+    x-cli-option: true
   multi_session:
     description: >-
       Use multi-session transfer. max 128.
@@ -246,15 +298,16 @@ properties:
     x-cli-special: true
   multi_session_threshold:
     description: >-
-      Split files across multiple ascp sessions if their size in bytes is greater than
+      Split files across multiple `ascp` sessions if their size in bytes is greater than
       or equal to the specified value.
 
       (0=no file is split)
     type: integer
     x-agents:
       - direct
-      - node
       - transferd
+      - node
+    x-cli-option: true
   overwrite:
     description: >-
       Overwrite files at the destination with source files of the same name based 
@@ -297,12 +350,14 @@ properties:
 
       `full_checksum` : The source and destination files are compared based on full checksums
     default: diff
+    type: string
     enum:
       - never
       - always
       - diff
       - older
       - diff+older
+    x-cli-option: true
   password:
     description: >-
       Password for local Windows user when transfer user associated with node API user is not
@@ -328,9 +383,11 @@ properties:
 
       Because source access times are updated by the transfer operation,
       the timestamp that is preserved is the one just before to the transfer.
+    type: boolean
     x-cli-switch: true
   preserve_acls:
     description: Preserve access control lists.
+    type: string
     enum:
       - none
       - native
@@ -339,36 +396,40 @@ properties:
     x-agents:
       - direct
       - transferd
+    x-cli-option: true
   preserve_creation_time:
     description: >-
       Preserve source-file creation timestamps at the destination.
 
       Only Windows systems retain information about creation time.
       If the destination is not a Windows computer, this option is ignored.
+    type: boolean
     x-cli-switch: true
   preserve_extended_attrs:
     description: Preserve the extended attributes.
+    type: string
     enum:
       - none
       - native
       - metafile
     default: none
     x-agents:
+      - direct
       - transferd
     x-cli-option: --preserve-xattrs
   preserve_file_owner_gid:
     description: Preserve the group ID for a file owner.
     type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-switch: true
   preserve_file_owner_uid:
     description: Preserve the user ID for a file owner.
     type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-switch: true
   preserve_modification_time:
     description: >-
@@ -376,43 +437,46 @@ properties:
       of a transferred file to the modification of the source file or directory.
 
       Preserve source-file modification timestamps at the destination.
+    type: boolean
     x-cli-switch: true
   preserve_remote_acls:
     description: Preserve remote access control lists.
+    type: string
     enum:
       - none
       - native
       - metafile
     default: none
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-option: --remote-preserve-acls
   preserve_remote_extended_attrs:
     description: Preserve remote extended attributes.
+    type: string
     enum:
       - none
       - native
       - metafile
     default: none
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-option: --remote-preserve-xattrs
   preserve_source_access_time:
     description: Preserve the time logged for when the source file was accessed.
     type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-switch: true
   preserve_times:
     description: Preserve file timestamps.
     type: boolean
     x-agents:
+      - direct
       - transferd
       - node
-      - direct
     x-cli-option: -p
   rate_policy:
     description: >-
@@ -429,6 +493,7 @@ properties:
       Do not share bandwidth.
       Aspera recommends that you do not use this setting except under special circumstances, 
       otherwise the destination storage can be damaged.
+    type: string
     enum:
       - low
       - fair
@@ -442,28 +507,31 @@ properties:
       - transferd
   remote_host:
     description: IP or fully qualified domain name (FQDN) of the remote server.
+    type: string
     x-cli-option: --host
   remote_password:
     description: SSH session password.
+    type: string
     x-cli-envvar: ASPERA_SCP_PASS
   remote_user:
     description: Remote user. Default value is `xfer` on node or connect.
+    type: string
     x-cli-option: --user
   remove_after_transfer:
     description: Remove SRC files after transfer success.
     type: boolean
     x-agents:
       - direct
-      - node
       - transferd
+      - node
     x-cli-switch: true
   remove_empty_directories:
     description: Specifies whether to remove empty directories.
     type: boolean
     x-agents:
       - direct
-      - node
       - transferd
+      - node
     x-cli-switch: true
   remove_empty_source_dir:
     description: Remove empty source subdirectories and remove the source directory itself, if empty.
@@ -483,8 +551,8 @@ properties:
     type: boolean
     x-agents:
       - direct
-      - connect
       - node
+      - connect
     x-cli-switch: true
   proxy:
     description: >-
@@ -495,9 +563,11 @@ properties:
       Default ports for DNAT and DNATS protocols are 9091 and 9092.
 
       Password, if specified here, overrides the value of environment variable `ASPERA_PROXY_PASS`.
+    type: string
     x-agents:
       - direct
       - noded
+    x-cli-option: true
   resume_policy:
     description: >-
       If a transfer is interrupted or fails to finish,
@@ -514,6 +584,7 @@ properties:
 
       Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.
     default: faspmgr:none;other:sparse_csum
+    type: string
     enum:
       - none
       - attrs
@@ -526,8 +597,8 @@ properties:
       sparse_csum: 2
       full_csum: 3
   retry_duration:
-    description: Specifies how long to wait before retrying transfer (e.g. `5min`).
     $comment: "TODO: check this."
+    description: Specifies how long to wait before retrying transfer (e.g. `5min`).
     type:
       - integer
       - string
@@ -542,17 +613,18 @@ properties:
       before writing the new file.
 
       File attributes are maintained in the renamed file.
+    type: boolean
     x-cli-switch: true
     x-agents:
       - direct
-      - node
       - transferd
+      - node
   skip_duplicate_check:
     description: Don't check for duplicate files at the destination.
     type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-option: --skip-dir-traversal-dupes
     x-cli-switch: true
   skip_special_files:
@@ -562,14 +634,15 @@ properties:
       If `true`, `ascp` skips special assets and proceeds with the transfer of all other assets.
     type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-switch: true
   source_root:
     description: >-
       Path to be prepended to each source path.
 
       This is either a conventional path or it can be a URI but only if there is no root defined.
+    type: string
     x-cli-option: --source-prefix64
     x-cli-convert: base64
   source_root_id:
@@ -587,18 +660,19 @@ properties:
       The remaining portion of the source path is kept intact at the destination.
 
       Special care must be taken when used with cloud storage.
+    type: string
     x-agents:
       - direct
-      - node
       - transferd
+      - node
     x-cli-option: --src-base64
     x-cli-convert: base64
   src_base64:
     description: The folder name below which the directory structure is preserved (base64 encoded).
     type: string
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-option: --src-base64
   ssh_port:
     description: Specifies SSH (TCP) port.
@@ -612,6 +686,7 @@ properties:
       Shall look like: -----BEGIN RSA PRIV4TE KEY-----\nMII...
 
       Note the JSON encoding: \n for newlines.
+    type: string
     x-agents:
       - direct
       - transferd
@@ -620,24 +695,19 @@ properties:
     description: The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.
     type: string
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-envvar: ASPERA_SCP_PASS
   ssh_private_key_path:
     description: Path to private key for SSH.
     type: string
     x-agents:
-      - transferd
       - direct
-    x-cli-option: -i
-  ssh_args:
-    description: Array of arguments to pass to SSH. Use with caution.
-    type: array
-    x-agents:
       - transferd
-    x-cli-option: --ssh-args
+    x-cli-option: -i
   symlink_policy:
     description: Handle source side symbolic links.
+    type: string
     enum:
       - follow
       - copy
@@ -660,16 +730,17 @@ properties:
       Key `aspera.xfer_retry` specifies a retry timeout for node API initiated transfers.
     type: string
     x-agents:
-      - transferd
       - direct
+      - transferd
+    x-cli-option: true
   target_rate_cap_kbps:
     description: >-
       Maximum target rate for incoming transfers, in kilobits per second.
       Returned by upload/download_setup node API.
     type: integer
     x-agents:
-      - connect
       - transferd
+      - connect
   target_rate_kbps:
     description: Specifies desired speed for the transfer.
     type: integer
@@ -683,28 +754,47 @@ properties:
       - transferd
   token:
     description: "Authorization token. Type: Bearer, Basic or ATM. (Also arg -W)"
+    type: string
     x-cli-envvar: ASPERA_SCP_TOKEN
   use_ascp4:
-    description: Specify version of protocol. Do not use ascp4.
+    description: Specify version of protocol. Do not use `ascp4`.
     type: boolean
     default: false
     x-agents:
       - direct
-      - node
       - transferd
+      - node
     x-cli-special: true
   use_system_ssh:
-    description: TODO, comment...
-    type: string
+    description: >-
+      Use an external `ssh` program instead of the built-in `libssh2` implementation to establish
+      the connection to the remote host.
+      The desired `ssh` program must be in the environment's `PATH`.
+
+      To enable debugging of the `ssh` process, supply `-DD` and `--ssh-arg=-vv` arguments to `ascp`.
+    type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-option: -SSH
+    x-cli-switch: true
+  ssh_args:
+    $comment: "TODO: Generate multiple options and place as in comment (after -i , before user/host)"
+    description: >-
+      Add arguments to the command-line arguments passed to the external ssh program (implies -SSH).
+      The arguments are inserted before any key file(s) supplied to `ascp` and before the user/host arguments.
+    type: array
+    x-agents:
+      - direct
+      - transferd
+    x-cli-option: --ssh-arg
+    x-cli-special: true
   keepalive:
     description: The session is running in persistent session mode.
+    type: boolean
     x-agents:
-      - transferd
       - direct
+      - transferd
     x-cli-switch: true
   dgram_size:
     description: UDP datagram size in bytes.
@@ -717,13 +807,17 @@ properties:
     x-cli-option: -m
   sshfp:
     description: Check it against server SSH host key fingerprint.
+    type: string
     x-cli-option: --check-sshfp
   target_rate_percentage:
-    description: "TODO: remove ?"
+    $comment: "TODO: Remove ?"
+    description: "n/a"
+    type: string
     x-agents: []
   rate_policy_allowed:
     description: Specifies most aggressive rate policy that is allowed.
       Returned by node API.
+    type: string
     enum:
       - low
       - fair
@@ -733,13 +827,27 @@ properties:
       - connect
   fasp_url:
     description: Only used in Faspex.
+    type: string
     x-agents: []
   authentication:
     description: Set to `token` for SSH bypass keys, else password asked if not provided.
+    type: string
     x-agents:
       - connect
   cipher_allowed:
     description: Returned by node API. Valid literals include `aes-128` and `none`.
+    type: string
+    enum:
+      - none
+      - aes-128
+      - aes-192
+      - aes-256
+      - aes-128-cfb
+      - aes-192-cfb
+      - aes-256-cfb
+      - aes-128-gcm
+      - aes-192-gcm
+      - aes-256-gcm
     x-agents:
       - connect
   obfuscate_file_names:
@@ -750,21 +858,24 @@ properties:
   wss_enabled:
     description: Server has Web Socket service enabled.
     type: boolean
+    x-cli-option: --ws-connect
+    x-cli-switch: true
     x-cli-special: true
   wss_port:
-    description: TCP port used for websocket service feed.
+    description: TCP port used for Web Socket service feed.
     type: integer
     x-cli-special: true
   compression:
-    description: ascp4 only, 0 / 1?
+    description: ascp4 only.
+    $comment: "0 / 1?"
     type: integer
     x-agents: []
   read_threads:
-    description: ascp4 only
+    description: ascp4 only.
     type: integer
     x-agents: []
   write_threads:
-    description: ascp4 only
+    description: ascp4 only.
     type: integer
     x-agents: []
   xfer_max_retries: