Allow specifying a Timeout value

[gdbarron]

closes #237

[Saadi6]

Without wrapping New-VenafiSession in try catch statement and using 1 sec timeout resulted in an incomplete VenafiSesison object. It was missing version and custom field definitions but token was present and useable.

VERBOSE: {"Body":"{\"ConfigClass\":\"Application Base\"}","ContentType":"application/json","Method":"Post","TimeoutSec":1,"Headers":{"Authorization":"***hidden***"},"Uri":"https://tls.bigsur.local/vedsdk/Metadata/GetItemsForClass","UseBasicParsing":true}
VERBOSE: Response status code 0
PS /Users/saad.humayun> $VenafiSession                       

Platform             : VDC
AuthType             : Token
Expires              : 12/23/2023 4:23:14 PM
TimeoutSec           : 1
SkipCertificateCheck : False
Version              : 
CustomField          : 
Server               : https://tls.bigsur.local
Key                  : 
Token                : @{Server=https://tls.bigsur.local; AccessToken=System.Management.Automation.PSCredential; RefreshToken=; Scope=System.Collections.Hashtable; 
                       Identity=AD+BigSur:efd2ab3ac8f73a40ba4865ea5da1c035; TokenType=Bearer; ClientId=xxxxx; Expires=12/23/2023 4:23:14 PM; RefreshExpires=}

Wrapping New-VenafiSession in try catch statement returns an error upon first timeout.

VERBOSE: {"ContentType":"application/json","Method":"Get","TimeoutSec":1,"Headers":{"Authorization":"***hidden***"},"Uri":"https://tls.bigsur.local/vedsdk/SystemStatus/Version","UseBasicParsing":true}
VERBOSE: Response status code 0
Exception: untitled:Untitled-1:8:5
Line |
   8 |      throw $_.Exception.Message
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Getting the version failed with the following error: The request was canceled due to the configured HttpClient.Timeout of 1 seconds elapsing..  This
     | feature was introduced in v18.3.

A new session with a reasonable timeout specified has everything as expected.

While this behaviour is as expected, it may confuse someone using a low timeout value without try catch, while using a function that happens to make several calls to Venafi API before a result is returned.

I suggest throwing an error when any call times out or adding a note in documentation that some errors due to low timeout value might be hidden if try and catch is not used.

[Saadi6]

comments submitted in review on GitHub

[gdbarron]

If someone uses a low timeout without error handling and an incomplete session is created, why doesn't the first call post New-VenafiSession fail? I would think it would just as the calls to get version and CF info did. Also, I would expect there to be errors for failure to retrieve version and CF, those are just not terminating errors so New-VenafiSession completes and does not stop the script.

Trying to understand the suggestion a bit deeper. Is it to update Invoke-VenafiRestMethod to throw a terminating error whenever an api call fails, or just fails on timeout, or not terminating? Or is the suggestion isolated to New-VenafiSession? Or something else?

[gdbarron]

@Saadi6?

[Saadi6]

Excuse the late response. Without error handling while calling New-VenafiSession with a very short timeout value a terminating error does not occur, even though some of the background HTTP calls made by VenafiPS (such as gathering custom fields) while creating the session object did timeout.

Wrapping New-VenafiSession in try catch statement - as one should - throws an error when any background HTTP request times out and an incomplete, yet semi-useable VenafiSession is not returned.

Yes, if possible, Invoke-VenafiRestMethod can be updated to throw a terminating error only incase of timeout error. There might other implications if terminating error is thrown for all types of error by Invoke-VenafiRestMethod.

However, given that you don't know someone might use VenafiPS in their own code, just a warning/suggestion to always use error handling - when a timeout value is specified - would also be sufficient IMHO.

[Saadi6]

Timeout feature works