[getdns-api] getdns API version published

[Paul Hoffman]

On Aug 19, 2013, at 11:05 PM, Murray S. Kucherawy <superuser at gmail.com> wrote:

> 1.1 getdns_general()
> 
> The "name" argument can be an IP address.  That's passed as a string (e.g., "127.0.0.1\0"), correct?  I assume so since it's a (const char *) and not a (void *) and there's no address family argument, but I ask because you name PTR, which one might take to mean the caller should in fact pass "1.0.0.127.in-addr.arpa\0" or similar.

The text says "This can also be an IPv4 or IPv6 address for request types that take addresses instead of domain names, such as PTR." I thought that was clear but, if not, wording proposals are appreciated.

> 1.3 getdns_hostname()
> 
> In the dictionary through which the address family is defined, the family is apparently presented as a string, either "IPv4\0" or "IPv6\0". 

Nope, these are bindata, not strings. At the top of section 2, it says "bindata is a struct to hold binary data. It is defined as { size_t size; uint8_t *binary_stuff; }."

> Are these case-sensitive? 

Yes.

> Why not just refer to a char that contains '4' or '6', or the values for AF_INET or AF_INET6?

That could have worked as well, but is not what was chosen.

> I think both of these might benefit from having a PTR lookup example in Section 8.

Sure, I can add an example like that.

> 1.7 Canceling a callback
> 
> In fact this really means the caller is canceling a previously initiated request, correct? 

Not necessarily.

> The callback may or may not already have been executed; this call guarantees that if it hasn't been hit, it will be hit now, which satisfies the post-condition that it's always called once.  But the other main effect here is that the DNS request, if it has not already completed, is canceled.  I guess the reason this tripped me up is that I would expect this to be expressed as a cancellation of the DNS query, not of the callback.

The application using the API shouldn't care whether or not the DNS request went out or not, just that the callback is cancelled. For example, assume that the DNS request returned but the cancellation comes in while doing DNSSEC validation: the application still wants the callback cancelled.

> 3. Extensions
> 
> What's supposed to be in the empty bullet before 3.1?

Nothing. HTML typo.

> 4.1 Structure of DNS replies_tree
> 
> The API will convert an A record (for example) into an "ipv4_address" (as a 32-bit quantity) but also leave the raw form there.  However, for names (e.g., the name in the question section), only the raw form is there.  That seems like it would be a common conversion nearly all callers will need to do.  Why force them to call the conversion, rather than just provide a decoded form in the replies_tree?

It didn't seem likely that people would be wanting the DNS names in human-readable form or, if they did, which they would want.

> 6.4 example
> 
> I haven't gone through all the example code yet, but I did find this:
> 
> this_ret = getdns_list_get_length(just_the_addresses_ptr, num_addresses_ptr);  // Ignore any error
> 
> 
> It looks like the second argument there should be prefixed by "&".  I think I saw at least one other place where this needed to be done as well.  I will make a full pass through the code examples, and I'll do my best not to put it off until I'm sitting in a WG in Vancouver to do it.

Noted. Also note that the line above is preceded by:
size_t * num_addresses_ptr = NULL;
Also note that all the examples compile under the most pedantry possible.

> 8.3 Contexts for Basic Resolution
> 
> I think getdns_context_set_dns_transport() is missing another value, which is something to start with UDP, but on fallback to TCP, bolt the connection up.  It's there for the TCP-only case, but not for the upgrade case. 

I think that was just overlooked.

> It might be better to use a bitmask here, e.g., UDP | TCP | PERSISTENT_CONNECTIONS.

Might have been, yes.

> In terms of timeouts, does that mean the way to have different timeouts for different queries is to establish different contexts, each with its own timeout?

Yes, exactly.

> If you limit the count of outstanding queries, what blocks, exactly?  I have a couple of ideas about how this could work and I can't tell what's meant here:  (a) A new request will get queued, and actually sent when some other stuff has resolved; (b) The API call that enqueues a new request will itself block until something else resolves.

The former, definitely. Async is async.

--Paul Hoffman