rob05c commented on a change in pull request #7874: URL: https://github.com/apache/trafficserver/pull/7874#discussion_r669094146
########## File path: doc/developer-guide/core-architecture/hostdb.en.rst ########## @@ -0,0 +1,191 @@ +.. 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 + +.. highlight:: cpp +.. default-domain:: cpp + +.. _developer-doc-hostdb: + +HostDB +****** + +HostDB is a cache of DNS results. It is used to increase performance by aggregating address +resolution across transactions. HostDB also stores state information for specific IP addresses. + +Operation +========= + +The primary operation for HostDB is to resolve a fully qualified domain name ("FQDN"). As noted each +FQDN is associated with a single record. Each record has an array of items. When a resolution +request is made the database is checked to see if the record is already present. If so, it is +served. Otherwise a DNS request is made. When the nameserver replies a record is created, added +to the database, and then returned to the requestor. + +Each info tracks several status values for its corresponding upstream. These are + +* HTTP version +* Last failure time + +The HTTP version is tracked from responses and provides a mechanism to make intelligent guesses +about the protocol to use to the upstream. + +The last failure time tracks when the last connection failure to the info occurred and doubles as +a flag, where a value of ``TS_TIME_ZERO`` indicates a live target and any other value indicates a +dead info. + +If an info is marked dead (has a non-zero last failure time) there is a "fail window" during which +no connections are permitted. After this time the info is considered to be a "zombie". If all infos +for a record are dead then a specific error message is generated (body factory tag +"connect#all_dead"). Otherwise if the selected info is a zombie, a request is permitted but the +zombie is immediately marked dead again, preventing any additional requests until either the fail +window has passed or the single connection succeeds. A successful connection clears the last file +time and the info becomes alive. + +Runtime Structure +================= + +DNS results are stored in a global hash table as instances of ``HostDBRecord``. Each record stores +the results of a single query. These records are not updated with new DNS results - instead a new +record instance is created and replaces the previous instance in the table. The records are +reference counted so such a replacement doesn't invalidate the old record if the latter is still +being accessed. Some specific dynamic data is migrated from the old record to the new one, such as +the failure status of the upstreams in the record. + +In each record is a variable length array of items, instances of ``HostDBInfo``, one for each +IP address in the record. This is called the "round robin" data for historical reasons. For SRV +records there is an additional storage area in the record that is used to store the SRV names. + +.. figure:: HostDB-Data-Layout.svg + +The round robin data is accessed by using an offset and count in the base record. For SRV records +each record has an offset, relative to that ``HostDBInfo`` instance, for its own name in the name +storage area. + +State information for the outbound connection has been moved to a refurbished ``DNSInfo`` class +named ``ResolveInfo``. As much as possible relevant state information has been moved from the +``HttpSM`` to this structure. This is intended for future work where the state machine deals only +with upstream transactions and not sessions. + +``ResolveInfo`` may contain a reference to a HostDB record, which preserves the record even if it is +replaced due to DNS queries in other transactions. The record is not required as the resolution +information can be supplied directly without DNS or HostDB, e.g. a plugin sets the upstream address +explicitly. The ``resolved_p`` flag indicates if the current information is valid and ready to be Review comment: I don't fully understand what it means for `resolved_p` to be `false`, i.e. what it means for it to be "ready to be used," or why a plugin or core would set that. Docs explaining that might be helpful -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
