doc:
  short_help: Fetches a file from a remote (target) host.
  help: |
    This is still under development. For now, it won't create the local parent folder of the fetched file, and it'll
    always use the current (local) user as owner.
  references:
    "'fetch' Ansible module documentation": https://docs.ansible.com/ansible/latest/modules/fetch_module.html
  examples:
  - title: Transfer a file from the target machine to the controller.
    desc: |
      Transfer file '/tmp/service-backup.zip' from the target machine (which can be the same as the controller machine)
      to '/tmp/service-backup-from-target.zip' on the controller machine.
    vars:
      src: /tmp/service-backup.zip
      dest: /tmp/service-backup-from-target.zip

args:
  src:
    doc:
      short_help: The source file on the remote host.
    type: string
    required: true
  dest:
    doc:
      short_help: The destination file on this host.
    type: string
    required: true
    default: ~/Downloads/
  flat:
    doc:
      short_help: Whether to auto-rename the file after retrieval.
      help: |
        Allows you to override the default behavior of appending hostname/path/to/file to the destination. If dest ends with '/', it will use the basename of the source file, similar to the copy module. Obviously this is only handy if the filenames are unique.
    type: boolean
    default: true
    cli:
      param_decls:
      - --flat/--no-flat
  become:
    doc:
      short_help: Whether to use elevated privileges to read the remote file. Avoid if possible.
    type: boolean
    default: false
#  owner:
#    doc:
#      short_help: "The owner of the downloaded file."
#    type: string
#    required: false
#    cli:
#      metavar: USER
#  group:
#    doc:
#      short_help: "The group of the downloaded file."
#    type: string
#    required: false
#    cli:
#      metavar: GROUP
#  mode:
#    doc:
#      short_help: "The permissions of the downloaded file."
#    type: string
#    required: false
#    cli:
#      metavar: MODE
#  parent_dir_mode:
#    doc:
#      short_help: "The permissions of the downloaded file parent directory."
#    type: string
#    required: false
#    cli:
#      metavar: MODE

frecklets:
#  - user-exists:
#      frecklet::skip: "{{:: owner | true_if_empty_or('root') ::}}"
#      name: "{{:: owner ::}}"
#      group: "{{:: group ::}}"
##      system_user: "{{:: system_user ::}}"
#  - parent-folder-exists:
#      path: "{{:: dest ::}}"
#      owner: "{{:: owner  ::}}"
#      group: "{{:: group ::}}"
#      mode: "{{:: parent_dir_mode ::}}"
- frecklet:
    name: fetch
    type: ansible-module
    desc:
      msg: "fetch '{{:: src ::}}' -> '{{:: dest ::}}'"
    properties:
      idempotent: false
      internet: false
      elevated: '{{:: become ::}}'
  task:
    become: '{{:: become ::}}'
  vars:
    dest: '{{:: dest ::}}'
    src: '{{:: src ::}}'
    flat: '{{:: flat ::}}'

meta: {}