[win_get_url] feature: Add support checksum to module win_get_url (#51986)

* set valid_until equal to current time + spot_wait_timeout

* Add checksum check for downloaded file.

* refactoring

* fix typo

* add fixes

* mart try,catch handling

* revert lib/ansible/modules/cloud/amazon/ec2.py from upstream

* refactoring

* remove empty lines

* add checksum verification for existing file

* fix current file check

* refactoring destination file check

* add handling exceptions

* refactoring

* Added download file hash data from url

* fix string aligning

* fix bug with uri

* Added get hash from multy-string file

* Added URI support for checksum file location

* refactoing

* Remove any non-alphanumeric characters for hash from url

* fix discussions; add support for PS3

* refactoring

* add size return value

* checkout from upstream for lib/ansible/modules/cloud/amazon/ec2.py

* add Ansible.ModuleUtils.Legacy support; refactoring

* Copyright added

* Checking files size before and after downloading added.

* remove unused code

* Corrected regexp for dotted slashed file name prefix in hash-file

* hotfix typo error; add int tests

* remove legacy module support; split checksum to checksum, checksum_algorithm, checksum_url

* changed default hash algorithm

* Fixed case for ContentLength = -1

* Old comment removed

* fix typo

* Remove file size check before downloading

* add alias to ; fix tests

* adjust tests; fix lint warnings from PSScritpAnalyzer

* workaround for bug in win_chocolatey module on win2008

* remove win_get_url.ps1 from /test/sanity/pslint/ignore.txt

* add checksum_algorithm as retuen value

* first normalise before return Result

* resolve discussions

Signed-off-by: Viktor Utkin <viktor.utkin7@yandex.ru>

* fix discussions
fix http tests as discussed

* fix last discussions

* Reduce code duplication and add idempotency check

* fix sanity issue and remove testing code

* move back to using tmp file for checksum comparison

lib/ansible/modules/windows/win_get_url.py

@@ -34,7 +34,7 @@ options:
     required: yes
   force:
     description:
-    - If C(yes), will always download the file. If C(no), will only
+    - If C(yes), will download the file every time and replace the file if the contents change. If C(no), will only
       download the file if it does not exist or the remote file has been
       modified more recently than the local file.
     - This works by sending an http HEAD request to retrieve last modified
@@ -73,6 +73,36 @@ options:
     type: bool
     default: yes
     version_added: '2.4'
+  checksum:
+    description:
+      - If a I(checksum) is passed to this parameter, the digest of the
+        destination file will be calculated after it is downloaded to ensure
+        its integrity and verify that the transfer completed successfully.
+      - This option cannot be set with I(checksum_url).
+    type: str
+    version_added: "2.8"
+  checksum_algorithm:
+    description:
+      - Specifies the hashing algorithm used when calculating the checksum of
+        the remote and destination file.
+    type: str
+    choices:
+      - md5
+      - sha1
+      - sha256
+      - sha385
+      - sha512
+    default: sha1
+    version_added: "2.8"
+  checksum_url:
+    description:
+      - Specifies a URL that contains the checksum values for the resource at
+        I(url).
+      - Like C(checksum), this is used to verify the integrity of the remote
+        transfer.
+      - This option cannot be set with I(checksum).
+    type: str
+    version_added: "2.8"
   proxy_url:
     description:
     - The full URL of the proxy server to download through.
@@ -105,6 +135,9 @@ notes:
 - If your URL includes an escaped slash character (%2F) this module will convert it to a real slash.
   This is a result of the behaviour of the System.Uri class as described in
   L(the documentation,https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/network/schemesettings-element-uri-settings#remarks).
+- Since Ansible 2.8, the module will skip reporting a change if the remote
+  checksum is the same as the local local even when C(force=yes). This is to
+  better align with M(get_url).
 seealso:
 - module: get_url
 - module: uri
@@ -140,6 +173,22 @@ EXAMPLES = r'''
     dest: '%TEMP%\ftp-file.txt'
     url_username: ftp-user
     url_password: ftp-password
+
+- name: Download src with sha256 checksum url
+  win_get_url:
+    url: http://www.example.com/earthrise.jpg
+    dest: C:\temp\earthrise.jpg
+    checksum_url: http://www.example.com/sha256sum.txt
+    checksum_algorithm: sha256
+    force: True
+
+- name: Download src with sha256 checksum url
+  win_get_url:
+    url: http://www.example.com/earthrise.jpg
+    dest: C:\temp\earthrise.jpg
+    checksum: a97e6837f60cec6da4491bab387296bbcd72bdba
+    checksum_algorithm: sha1
+    force: True
 '''
 
 RETURN = r'''
@@ -148,11 +197,26 @@ dest:
     returned: always
     type: str
     sample: C:\Users\RandomUser\earthrise.jpg
+checksum_dest:
+    description: <algorithm> checksum of the file after the download
+    returned: success and dest has been downloaded
+    type: str
+    sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827
+checksum_src:
+    description: <algorithm> checksum of the remote resource
+    returned: force=yes or dest did not exist
+    type: str
+    sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827
 elapsed:
     description: The elapsed seconds between the start of poll and the end of the module.
     returned: always
     type: float
     sample: 2.1406487
+size:
+    description: size of the dest file
+    returned: success
+    type: int
+    sample: 1220
 url:
     description: requested url
     returned: always