Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
  • 2 commits
  • 1 file changed
  • 0 comments
  • 1 contributor

Showing 1 changed file with 64 additions and 18 deletions. Show diff stats Hide diff stats

  1. +64 18 doc/dns-design.rst
82 doc/dns-design.rst
Source Rendered
@@ -25,13 +25,14 @@ mechanism to establish socket connections in rough compliance to `Happy
25 25 Eyeballs (IPv6)`_ and `Happy Eyeballs (SCTP)`_. The API is intended to be
26 26 extensible to adapt to new technologies.
27 27
28   -This API consists of three major objects: policy context, low-level resolver,
29   -and socket connector. The policy context provides a common configuration
30   -point for lookup and connection policies, and provide the main point of
31   -extension for the API; the low-level resolver performs the basic lookup of
32   -addresses for names, automatically following aliases and service targets; the
33   -socket connector attempts to establish a socket for a service and/or domain
34   -name.
  28 +This API consists of four major objects: policy context, caching context,
  29 +low-level resolver, and socket connector. The policy context provides a common
  30 +configuration point for lookup and connection policies, and provide the main
  31 +point of extension for the API; the caching context stores results for a
  32 +lookup request, honoring each result's time-to-live; the low-level resolver
  33 +performs the basic lookup of addresses for names, automatically following
  34 +aliases and service targets; the socket connector attempts to establish a
  35 +socket for a service and/or domain name.
35 36
36 37 Policy Context
37 38 --------------
@@ -126,6 +127,51 @@ connector. Otherwise it returns false and error information.
126 127 bz_connector *conn,
127 128 bz_errcode *err)
128 129
  130 +Caching
  131 +-------
  132 +
  133 +Caching is managed by the cache context, bz_cache. It stores the results for
  134 +queries by type and name, and honors the record's TTL. There is a one-to-one
  135 +relation between a bz_ctx and a bz_cache, with the bz_ctx owning the bz_cache.
  136 +All bz_resolver and bz_connector instances created from a given bz_ctx make use
  137 +of this cache context.
  138 +
  139 +Properties
  140 +~~~~~~~~~~
  141 +
  142 +Each of the following properties has a getter, but no setter. The values are
  143 +determined when the bz_resolver is created, or as its state changes while
  144 +processing lookups:
  145 +
  146 +* context (``bz_ctx``) - The owning context.
  147 +
  148 +Operation
  149 +~~~~~~~~~
  150 +
  151 +The bz_cache provides the following functions:
  152 +
  153 +* retrieve() - Retrieves all results for a given type and name.
  154 +* append() - Appends a new result for a given type and name.
  155 +* clear() - Clears all results for a given type and name.
  156 +* purge() - Purges all cached information from the bz_cache.
  157 +
  158 +retrieve() takes a record type and a name (along with a callback and optional
  159 +callback data), and returns all of the relevant results for that key-pair via
  160 +the callback. If any results for the type/name key-pair have expired, they are
  161 +released and ignored.
  162 +
  163 +append() takes a record type, name, and result, appending the result to any
  164 +existing results stored for that type/name key-pair. If the type/name key-pair
  165 +does not already exist in the cache, it is created.
  166 +
  167 +clear() takes a record type and name, and removes all results for that
  168 +type/name key-pair.
  169 +
  170 +purge() removes all results for all known type/name key-pairs.
  171 +
  172 +Callback
  173 +~~~~~~~~
  174 +
129 175 Low-Level Resolver
130 176 ------------------
131 177
@@ -215,8 +261,8 @@ Callback
215 261 The lookup() callback is expected to match the following signature::
216 262
217 263 void (*bz_resolver_lookup_cb)(bz_lookup_handle handle,
218   - bz_err_code retcode,
219   - struct bz_lookup_result *result,
  264 + bz_errcode retcode,
  265 + bz_lookup_result *result,
220 266 void *arg);
221 267
222 268 This callback is executed for each found record, and when the lookup() is
@@ -290,7 +336,7 @@ convenience. The user owns the memory for name and MUST release it via free().
290 336 char **name,
291 337 size_t *namelen,
292 338 bz_errcode *err);
293   -
  339 +
294 340 parse_srv_port() returns the SRV target port from the lookup result.
295 341
296 342 ::
@@ -303,18 +349,18 @@ parse_srv_priority() returns the SRV priority from the lookup result.
303 349
304 350 ::
305 351
306   - bool bz_lookup_result_result_parse_srv_priority(bz_lookup_result *rst,
307   - uint16_t *priority,
308   - bz_errcode *err);
309   -
  352 + bool bz_lookup_result_parse_srv_priority(bz_lookup_result *rst,
  353 + uint16_t *priority,
  354 + bz_errcode *err);
  355 +
310 356 parse_srv_weight() returns the SRV weight from the lookup result.
311 357
312 358 ::
313 359
314   - bool bz_lookup_result_result_parse_srv_weight(bz_lookup_result *rst,
315   - uint16_t *weight,
316   - bz_errcode *err);
317   -
  360 + bool bz_lookup_result_parse_srv_weight(bz_lookup_result *rst,
  361 + uint16_t *weight,
  362 + bz_errcode *err);
  363 +
318 364 Socket Connector
319 365 ----------------
320 366

No commit comments for this range

Something went wrong with that request. Please try again.