.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../common.defs

Host Resolution Proposal
************************

Introduction
------------

The current mechanism for resolving host names to IP addresses for Traffic Server is contained the HostDB and DNS
libraries. These take hostnames and provide IP addresses for them.

The current implementation is generally considered inadequate, both from a functionality point of view and difficulty in
working with it in other parts of Traffic Server. As Traffic Server is used in more complex situtations this inadequacy
presents increasing problems.

Goals
-----

Updating the host name resolution (currently referred to as "HostDB") has several functions goals

*  Enable additional processing layers to be easily added.
*  Enable plugins to directly access the name resolution logic
*  Enable plugins to provide name resolution
*  Asynchronous (immediate resolve or callback on block)
*  Minimize allocations -- in particular no allocations for cached resolutions
*  Simplify interactions with the resolution, particularly with regard to nameservers, origin server failover, and
   address family handling.

It is also necessary to support a number of specific features that are either currently available or strongly desired.

*  SplitDNS or its equivalent
*  Use of a hosts file (e.g. ``/etc/hosts``)
*  Simultaneous IPv4 and IPv6 queries
*  IP family control
*  Negative caching
   *  Server connection failures
   *  Query failures
   *  Nameserver failures.
*  Address validity time out control
*  Address round robin support
*  SRV record support (weighted records)
*  Nameserver round robin
*  Plugin access to nameserver data (add, remove, enumerate)
*  Plugin provision of resolvers.
*  Hooks for plugin detection / recovery from resolution events.

One issue is persistence of the cached resolutions. This creates problems for the current implementation (because of
size limits it imposes on the cached data) but also allows for quicker restarts in a busy environment.

Basics
------

The basic design is to separate the functionality into chainable layers so that a resolver with the desired attributes
can be assembled from those layers. The core interface is that of a lazy iterator. This object returns one of four
results when asked for an address

* An IP address
* Done(no more addresses are available)
* Wait(an address may be available in the future)
* Fail (no address is available and none will be so in the future)

Each layer (except the bottom) uses this API and also provides it. This enables higher level logic such as the state
machine to simply use the resolver as a list without having to backtrack states in the case of failures, or have special
cases for different resolution sources.

To perform a resolution, a client creates a query object (potentially on the stack), initializes it with the required
data (at least the hostname) and then starts the resolution. Methods on the query object allow its state and IP address
data to be accessed.

Required Resolvers
------------------

Nameserver
   A bottom level resolver that directly queries a nameserver for DNS data. This contains much of the functionality
   currently in the ``iocore/dns`` directory.

SplitDNS
   A resolver that directs requests to one of several resolvers. To emulate current behavior these would be Nameserver
   instances.

NameserverGroup
   A grouping mechanism for Nameserver instances that provides failover, round robin, and ordering capabilities. It may be
   reasonable to merge this with the SplitDNS resolver.

HostFile
   A resolver that uses a local file to resolve names.

AddressCache
   A resolver that also has a cache for resolution results. It requires another resolver instance to perform the actual
   resolution.

Preloaded
   A resolver that can contain one or more explicitly set IP addresses which are returned. When those are exhausted it
   falls back to another resolver.

Configuration
-------------

To configuration the resolution, each resolver would be assigned a tag. It is not, however, sufficient to simply provide
the list of resolver tags because some resolvers require additional configuration. Unfortunately this will likely
require a separate configuration file outside of :file:`records.config`, although we would be able to remove
:file:`splitdns.config`. In this case we would need chain start / end markers around a list of resolver tags. Each tag
would the be able to take additional resolver configuration data. For instance, for a SplitDNS resolver the nameservers.

Examples
--------

Transparent operations would benefit from the *Preloaded* resolver. This would be loaded with the origin host address
provided by the client connection. This could be done early in processing and then no more logic would be required to
skip DNS processing as it would happen without additional action by the state machine. It would handle the problem of de
facto denial of service if an origin server becomes unavailable in that configuration, as *Preloaded* would switch to
alternate addresses automatically.

Adding host file access would be easier as well, as it could be done in a much more modular fashion and then added to
the stack at configuration time. Whether such addresses were cached would be controlled by chain arrangement rather yet
more configuration knobs.

The default configuration would be *Preloaded* : *AddressCache* : *Nameserver*.

In all cases the state machine makes requests against the request object to get IP addresses as needed.

Issues
------

Request object allocation
=========================

The biggest hurdle is being able to unwind a resolver chain when a block is encountered. There are some ways to deal with this.

1) Set a maximum resolver chain length and declare the request instance so that there is storage for state for that many
resolvers. If needed and additional value of maximum storage per chain could be set as well. The expected number of
elements in a chain is expected to be limited, 10 would likely be a reaosnable limit. If settable at source
configuration time this should be sufficient.

2) Embed class allocators in resolver chains and mark the top / outermost / first resolver. The maximum state size for a
resolution can be calculated when the chain is created and then the top level resolver can use an allocation pool to
efficiently allocate request objects. This has an advantage that with a wrapper class the request object can be passed
along cheaply. Whether that's an advantage in practice is unclear.

Plugin resolvers
================

If plugins can provide resolvers, how can these can integrated in to existing resolver chains for use by the HTTP SM for
instance?

Feedback
========

It should be possible for a client to provide feedback about addresses (e.g., the origin server at this address is not
available). Not all resolvers will handle feedback but some will and that must be possible.

Related to this is that caching resolvers (such as *AddressCache*) must be able to iterator over all resolved addresses
even if their client does not ask for them. In effect they must background fill the address data.
