New Feature: Configuration Settings

[MichaCo]

All this is subject to change/work in progress

• [x] Options/Settings API rework
  • [x] First version of the changes (https://github.com/MichaCo/DnsClient.NET/commit/6f2d9482c242f5c1f598d1ae2d1d3be44531713c)
  • [x] Finalize
• [x] Rework "by server" query to configured/custom query
  • [x] ~~Replace "by server" queries with optional DnsQueryOptions~~
    • [x] Revert that change, maybe simplify some overloads, but that API might still be useful => Configure the client once, use it with different servers. (The initial configuration doesn't require servers)
  • [x] Decide on fallback of name servers (e.g. if nothing is specified in query options, use the client's name servers)
• [x] Breaking changes marked as obsolete instead
• [ ] More unit tests to validate the different ways of configuring a query
• [x] Remove obsolete parts in the future (v1.x/2.0)
• [ ] Documentation changes in all examples and on the website

The Problem

The LookupClient class has many properties which define the behavior of that class, like number of retries for a query, timeouts, caching etc... All properties can be set at any point in time because LookupClient is not immutable. Also, LookupClient is not a cheap object and it is advisable to reuse it as much as possible.

The problem with this is, that the state of LookupClient can be altered by different parts of an application and can cause unpredictable behavior.

For example, 2 different threads run a query with LookupClient at the same time. One sets UseCaching to true and one to false, before running the query. There is no way to ensure thread safety at this point for the UseCaching property to be set correctly.

Solution

I will remove all properties from the LookupClient itself and move them to a options class which can be used to initialize LookupClient.

previous version

var client = new LookupClient(NameServer.GooglePublicDns)
{
    UseCache = true,
    EnableAuditTrail = false,
    Retries = 3,
    Timeout = TimeSpan.FromSeconds(10),
    ThrowDnsErrors = true
};

new version

var client = new LookupClient(
    new LookupClientOptions(NameServer.GooglePublicDns)
    {
        UseCache = true,
        EnableAuditTrail = false,
        Retries = 3,
        Timeout = TimeSpan.FromSeconds(10),
        ThrowDnsErrors = true                   
    });

LookupClientOptions can be changed as much as needed before it gets passed to the client's ctor (which also give a little bit more flexibility to consumers).

After the LookupClient gets initialized, the options are stored as read-only copy and cannot be changed anymore.

The settings can be accessed via client.Settings.

This is a Breaking Change

Yes, this will be a bigger breaking change, because all the properties on the class are getting removed and the way to configure LookupClient changes.

Instead of removing the existing functionality right away, I will mark everything obsolete which will be removed some versions later (probably in 2.0).

Additional changes:

The list of name servers was a collection of IPEndPoints. IPEndPoint itself is mutable though, so it would be possible to change e.g. the IP address of an endpoint. That will be changed, too. Instead, the NameServer class becomes an immutable type and will be used across the board.

Custom Queries

~~In version 1.1.0, I added "by server" query overloads which allows to query a different endpoint than configured initially. Those endpoints will be removed alltogether in the next version (yes its breaking but I hope that feature wasn't really used much yet). Instead, there will be new Query... methods taking a subset of LookupClientOptions as an additional/optional parameter.~~ There will be new overloads to Query, QueryAsync and QueryReverse which take DnsQueryOptions, which is a subset of LookupClientOptions.

With that, one can fully configure individual queries while still using the same client instance. This feature can be used to query a dedicated endpoint or just use a different configuration for a particular query.

Example A, disabling cache for one query.

client.Query("google.com", QueryType.A, queryOptions: new DnsQueryOptions(NameServer.GooglePublicDns)
{
    UseCache = false
});

The query options will replace any settings previously configured on the client. There is no fallback to what was configured previously ~~(including name servers)!~~, except for name servers. In case the passed in query options do not provide one or more name servers, the query will try to use the name servers of the LookupClient instance.

If anyone did read all of this ;) and has comments/ideas, let me know; happy to get feedback on this.

[MichaCo]

:update: Development here is mostly complete. It will be a non-breaking change in 1.3.0! see #57