<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><font color="#000000" class="">Hi All,</font></div><div class=""><br class=""></div><div class="">Willem and I have been discussing the error handling in getdns and would like to propose some changes based on our implementation experience. </div><div class=""><br class=""></div><div class="">1) Asynchronous error handling</div><div class=""><br class=""></div><div class="">At the moment the async callbacks are specified as below:<br class=""><div class=""><br class=""></div><div class=""><div style="box-sizing: border-box; margin: 0px 0px 0px 2em; font-family: monospace; font-weight: bold; color: rgb(51, 51, 51); font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">GETDNS_CALLBACK_COMPLETE</div><div style="box-sizing: border-box; margin: 0px 0px 0px 4em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">The response has the requested data in it</div><div style="box-sizing: border-box; margin: 0px 0px 0px 2em; font-family: monospace; font-weight: bold; color: rgb(51, 51, 51); font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">GETDNS_CALLBACK_CANCEL</div><div style="box-sizing: border-box; margin: 0px 0px 0px 4em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">The calling program cancelled the callback; response is NULL</div><div style="box-sizing: border-box; margin: 0px 0px 0px 2em; font-family: monospace; font-weight: bold; color: rgb(51, 51, 51); font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">GETDNS_CALLBACK_TIMEOUT</div><div style="box-sizing: border-box; margin: 0px 0px 0px 4em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">The requested action timed out; response is filled in with empty structures</div></div><div class=""><div style="box-sizing: border-box; margin: 0px 0px 0px 2em; font-family: monospace; font-weight: bold; color: rgb(51, 51, 51); font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">GETDNS_CALLBACK_ERROR</div><div style="box-sizing: border-box; margin: 0px 0px 0px 4em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);" class="">The requested action had an error; response is NULL</div></div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">With this approach there is no mechanism to provide any more fine grained information to the user when an ERROR is return because the response in the callback is NULL. </div><div class="">When considering a mainly UDP based approach this is probably sufficient, but to cater for TCP and TLS (with authentication) we would like to change the above so that a variety of errors that can occur that are not timeouts can be communicated to the caller. </div><div class=""><br class=""></div><div class="">We would like to propose that the ERROR case is changed to have the same response as the TIMEOUT case i.e:</div><div class=""><br class=""></div><div class=""><div class="" style="box-sizing: border-box; margin: 0px 0px 0px 2em; font-family: monospace; font-weight: bold; color: rgb(51, 51, 51); font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);">GETDNS_CALLBACK_ERROR</div><div class="" style="box-sizing: border-box; margin: 0px 0px 0px 4em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; line-height: 20px; widows: 1; background-color: rgb(255, 255, 255);">The requested action had an error; response is filled in with empty structures</div></div><div class=""><br class=""></div><div class="">And so the response structure would look similar to this example for a TIMEOUT:</div><div class=""><br class=""></div><div class=""><div class="">{</div><div class=""> "answer_type": GETDNS_NAMETYPE_DNS,</div><div class=""> "replies_full": [],</div><div class=""> "replies_tree": [],</div><div class=""> "status": GETDNS_RESPSTATUS_ALL_TIMEOUT</div><div class="">}</div><div class=""><br class=""></div></div><div class="">2) New GETDNS_RESPSTATUS codes</div><div class=""><br class=""></div><div class="">The new GETDNS_RESPSTATUS_ error cases we would like to add at this time are:</div><div class=""><br class=""></div><div class=""><div class="">TRANSPORT_SETUP_FAILED - for the case where no connection could be made over any specified transport to any upstream (for example, only TLS is specified but none of the available upstreams support it).</div><div class=""><br class=""></div></div><div class="">TLS_FEATURE_NOT_SUPPORTED - for the cases where getdns can’t support the configured transport/authentication options at runtime because the available TLS library doesn’t have the required functionality (for example support for TLS 1.2 or hostname verification methods)).</div><div class=""><br class=""></div><div class="">TLS_AUTH_FAILED - for the case when using TLS only and authentication is required but fails. This is strictly a sub-case of TRANSPORT_SETUP_FAILED but seems worthy of a separate status code.</div><div class=""><br class=""></div><div class="">3) Synchronous timeouts</div><div class=""><br class=""></div><div class="">When calling the API synchronously, the return type of the functions is getdns_return_t. There is currently no value for GETDNS_RETURN_TIMEOUT and the behaviour for the sync calls is not clearly specified for a timeout in the spec. So our implementation currently uses GETDNS_RETURN_GOOD (and returns the response dict as in 1 above), the best alternative error code would be GETDNS_RETURN_GENERIC_ERROR. So we would like to propose adding the value GETDNS_RETURN_TIMEOUT to the getdns_return_t type. </div><div class=""><br class=""></div><div class="">As a future activity we note that the above mechanisms can only relay a single error code. Since completing an API call can involve</div><div class="">- performing multiple DNS queries</div><div class="">- using multiple upstreams</div><div class="">- using multiple transports</div><div class="">- TLS authentication that can fail for various reasons</div><div class="">- DNSSEC validations</div><div class="">- TSIG validation</div><div class="">we are considering adding an ‘error log trail’ utility that would be recorded during execution and could be returned in the response dict. Feedback on this is welcomed. </div><div class=""><br class=""></div><div class="">Sara. </div><div class=""><br class=""></div></div></div></div><br class=""></body></html>