Add elapsed return value to select modules (#37969)

* Add elapsed return value to select modules

It can be quite useful to know exactly how much time has elapsed
downloading/waiting. This improves existing modules or updates
documentation.

* Ensure elapsed is always returned

* Added changelog fragment

lib/ansible/modules/windows/win_get_url.ps1

@@ -41,7 +41,7 @@ Function CheckModified-File($url, $dest, $headers, $credentials, $timeout, $use_
     $webLastMod = $null
 
     $webRequest = [System.Net.WebRequest]::Create($url)
-    
+
     foreach ($header in $headers.GetEnumerator()) {
         $webRequest.Headers.Add($header.Name, $header.Value)
     }
@@ -70,7 +70,7 @@ Function CheckModified-File($url, $dest, $headers, $credentials, $timeout, $use_
     } else {
         $webRequest.Method = [System.Net.WebRequestMethods+Http]::Head
     }
-    
+
     Try {
         $webResponse = $webRequest.GetResponse()
 
@@ -95,6 +95,8 @@ Function CheckModified-File($url, $dest, $headers, $credentials, $timeout, $use_
 
 Function Download-File($result, $url, $dest, $headers, $credentials, $timeout, $use_proxy, $proxy, $whatif) {
 
+    $module_start = Get-Date
+
     # Check $dest parent folder exists before attempting download, which avoids unhelpful generic error message.
     $dest_parent = Split-Path -LiteralPath $dest
     if (-not (Test-Path -LiteralPath $dest_parent -PathType Container)) {
@@ -132,8 +134,10 @@ Function Download-File($result, $url, $dest, $headers, $credentials, $timeout, $
             $extWebClient.DownloadFile($url, $dest)
         } Catch [System.Net.WebException] {
             $result.status_code = [int] $_.Exception.Response.StatusCode
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             Fail-Json -obj $result -message "Error downloading '$url' to '$dest': $($_.Exception.Message)"
         } Catch {
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             Fail-Json -obj $result -message "Unknown error downloading '$url' to '$dest': $($_.Exception.Message)"
         }
     }
@@ -142,6 +146,8 @@ Function Download-File($result, $url, $dest, $headers, $credentials, $timeout, $
     $result.changed = $true
     $result.msg = 'OK'
     $result.dest = $dest
+    $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
+
 }
 
 $url = Get-AnsibleParam -obj $params -name "url" -type "str" -failifempty $true
@@ -162,6 +168,7 @@ $force = Get-AnsibleParam -obj $params -name "force" -type "bool" -default $true
 $result = @{
     changed = $false
     dest = $dest
+    elapsed = 0
     url = $url
     # This is deprecated as of v2.4, remove in v2.8
     win_get_url = @{
@@ -190,7 +197,7 @@ if ($url_username) {
     } else {
         $credentials = New-Object System.Net.NetworkCredential($url_username, $url_password) 
     }
-    
+
 }
 
 # If skip_certificate_validation was specified, use validate_certs
@@ -221,14 +228,14 @@ $result.dest = $dest
 $result.win_get_url.dest = $dest
 
 # Enable TLS1.1/TLS1.2 if they're available but disabled (eg. .NET 4.5)
-$security_protcols = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::SystemDefault
+$security_protocols = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::SystemDefault
 if ([Net.SecurityProtocolType].GetMember("Tls11").Count -gt 0) {
-    $security_protcols = $security_protcols -bor [Net.SecurityProtocolType]::Tls11
+    $security_protocols = $security_protocols -bor [Net.SecurityProtocolType]::Tls11
 }
 if ([Net.SecurityProtocolType].GetMember("Tls12").Count -gt 0) {
-    $security_protcols = $security_protcols -bor [Net.SecurityProtocolType]::Tls12
+    $security_protocols = $security_protocols -bor [Net.SecurityProtocolType]::Tls12
 }
-[Net.ServicePointManager]::SecurityProtocol = $security_protcols
+[Net.ServicePointManager]::SecurityProtocol = $security_protocols
 
 if ($force -or -not (Test-Path -LiteralPath $dest)) {
 

lib/ansible/modules/windows/win_get_url.py

@@ -141,6 +141,11 @@ dest:
     returned: always
     type: string
     sample: C:\Users\RandomUser\earthrise.jpg
+elapsed:
+    description: The elapsed seconds between the start of poll and the end of the module.
+    returned: always
+    type: float
+    sample: 2.1406487
 url:
     description: requested url
     returned: always

lib/ansible/modules/windows/win_reboot.py

@@ -89,6 +89,6 @@ rebooted:
 elapsed:
   description: The number of seconds that elapsed waiting for the system to be rebooted.
   returned: always
-  type: int
-  sample: 23
+  type: float
+  sample: 23.2
 '''

lib/ansible/modules/windows/win_uri.ps1

@@ -40,6 +40,7 @@ $JSON_CANDIDATES = @('text', 'json', 'javascript')
 
 $result = @{
     changed = $false
+    elapsed = 0
     url = $url
 }
 
@@ -181,9 +182,12 @@ if ($null -ne $body) {
     }
 }
 
+$module_start = Get-Date
+
 try {
     $response = $client.GetResponse()
 } catch [System.Net.WebException] {
+    $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
     $response = $null
     if ($_.Exception.PSObject.Properties.Name -match "Response") {
         # was a non-successful response but we at least have a response and
@@ -194,13 +198,17 @@ try {
     # in the case a response (or empty response) was on the exception like in
     # a timeout scenario, we should still fail
     if ($null -eq $response) {
+        $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
         Fail-Json -obj $result -message "WebException occurred when sending web request: $($_.Exception.Message)"
     }
 } catch [System.Net.ProtocolViolationException] {
+    $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
     Fail-Json -obj $result -message "ProtocolViolationException when sending web request: $($_.Exception.Message)"
 } catch {
+    $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
     Fail-Json -obj $result -message "Unhandled exception occured when sending web request. Exception: $($_.Exception.Message)"
 }
+$result.elapsed = ((Get-Date) - $module_start).TotalSeconds
 
 ForEach ($prop in $response.psobject.properties) {
     $result_key = Convert-StringToSnakeCase -string $prop.Name

lib/ansible/modules/windows/win_uri.py

@@ -174,6 +174,11 @@ EXAMPLES = r'''
 '''
 
 RETURN = r'''
+elapsed:
+  description: The number of seconds that elapsed while performing the download
+  returned: always
+  type: float
+  sample: 23.2
 url:
   description: The Target URL
   returned: always

lib/ansible/modules/windows/win_wait_for.ps1

@@ -23,6 +23,7 @@ $timeout = Get-AnsibleParam -obj $params -name "timeout" -type "int" -default 30
 
 $result = @{
     changed = $false
+    elapsed = 0
 }
 
 # validate the input with the various options
@@ -126,9 +127,8 @@ if ($path -eq $null -and $port -eq $null -and $state -ne "drained") {
         }
 
         if ($complete -eq $false) {
-            $elapsed_seconds = ((Get-Date) - $module_start).TotalSeconds
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             $result.wait_attempts = $attempts
-            $result.elapsed = $elapsed_seconds
             if ($search_regex -eq $null) {
                 Fail-Json $result "timeout while waiting for file $path to be present"
             } else {
@@ -158,9 +158,8 @@ if ($path -eq $null -and $port -eq $null -and $state -ne "drained") {
         }
 
         if ($complete -eq $false) {
-            $elapsed_seconds = ((Get-Date) - $module_start).TotalSeconds
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             $result.wait_attempts = $attempts
-            $result.elapsed = $elapsed_seconds
             if ($search_regex -eq $null) {
                 Fail-Json $result "timeout while waiting for file $path to be absent"
             } else {
@@ -185,9 +184,8 @@ if ($path -eq $null -and $port -eq $null -and $state -ne "drained") {
         }
 
         if ($complete -eq $false) {
-            $elapsed_seconds = ((Get-Date) - $module_start).TotalSeconds
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             $result.wait_attempts = $attempts
-            $result.elapsed = $elapsed_seconds
             Fail-Json $result "timeout while waiting for $($hostname):$port to start listening"
         }
     } elseif ($state -in @("stopped","absent")) {
@@ -206,9 +204,8 @@ if ($path -eq $null -and $port -eq $null -and $state -ne "drained") {
         }
 
         if ($complete -eq $false) {
-            $elapsed_seconds = ((Get-Date) - $module_start).TotalSeconds
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             $result.wait_attempts = $attempts
-            $result.elapsed = $elapsed_seconds
             Fail-Json $result "timeout while waiting for $($hostname):$port to stop listening"
         }
     } elseif ($state -eq "drained") {
@@ -247,15 +244,14 @@ if ($path -eq $null -and $port -eq $null -and $state -ne "drained") {
         }
 
         if ($complete -eq $false) {
-            $elapsed_seconds = ((Get-Date) - $module_start).TotalSeconds
+            $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
             $result.wait_attempts = $attempts
-            $result.elapsed = $elapsed_seconds
             Fail-Json $result "timeout while waiting for $($hostname):$port to drain"
         }
     }
 }
 
-$result.wait_attempts = $attempts
 $result.elapsed = ((Get-Date) - $module_start).TotalSeconds
+$result.wait_attempts = $attempts
 
 Exit-Json $result