contrib/unbound/services/mesh.h

   1 /*
   2  * services/mesh.h - deal with mesh of query states and handle events for that.
   3  *
   4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
   5  *
   6  * This software is open source.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * Neither the name of the NLNET LABS nor the names of its contributors may
  20  * be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains functions to assist in dealing with a mesh of
  40  * query states. This mesh is supposed to be thread-specific.
  41  * It consists of query states (per qname, qtype, qclass) and connections
  42  * between query states and the super and subquery states, and replies to
  43  * send back to clients.
  44  */
  45
  46 #ifndef SERVICES_MESH_H
  47 #define SERVICES_MESH_H
  48
  49 #include "util/rbtree.h"
  50 #include "util/netevent.h"
  51 #include "util/data/msgparse.h"
  52 #include "util/module.h"
  53 #include "services/modstack.h"
  54 #include "services/rpz.h"
  55 #include "libunbound/unbound.h"
  56 struct sldns_buffer;
  57 struct mesh_state;
  58 struct mesh_reply;
  59 struct mesh_cb;
  60 struct query_info;
  61 struct reply_info;
  62 struct outbound_entry;
  63 struct timehist;
  64 struct respip_client_info;
  65
  66 /**
  67  * Maximum number of mesh state activations. Any more is likely an
  68  * infinite loop in the module. It is then terminated.
  69  */
  70 #define MESH_MAX_ACTIVATION 10000
  71
  72 /**
  73  * Max number of references-to-references-to-references.. search size.
  74  * Any more is treated like 'too large', and the creation of a new
  75  * dependency is failed (so that no loops can be created).
  76  */
  77 #define MESH_MAX_SUBSUB 1024
  78
  79 /**
  80  * Mesh of query states
  81  */
  82 struct mesh_area {
  83         /** active module stack */
  84         struct module_stack mods;
  85         /** environment for new states */
  86         struct module_env* env;
  87
  88         /** set of runnable queries (mesh_state.run_node) */
  89         rbtree_type run;
  90         /** rbtree of all current queries (mesh_state.node)*/
  91         rbtree_type all;
  92
  93         /** count of the total number of mesh_reply entries */
  94         size_t num_reply_addrs;
  95         /** count of the number of mesh_states that have mesh_replies
  96          * Because a state can send results to multiple reply addresses,
  97          * this number must be equal or lower than num_reply_addrs. */
  98         size_t num_reply_states;
  99         /** number of mesh_states that have no mesh_replies, and also
 100          * an empty set of super-states, thus are 'toplevel' or detached
 101          * internal opportunistic queries */
 102         size_t num_detached_states;
 103         /** number of reply states in the forever list */
 104         size_t num_forever_states;
 105
 106         /** max total number of reply states to have */
 107         size_t max_reply_states;
 108         /** max forever number of reply states to have */
 109         size_t max_forever_states;
 110
 111         /** stats, cumulative number of reply states jostled out */
 112         size_t stats_jostled;
 113         /** stats, cumulative number of incoming client msgs dropped */
 114         size_t stats_dropped;
 115         /** stats, number of expired replies sent */
 116         size_t ans_expired;
 117         /** stats, number of cached replies from cachedb */
 118         size_t ans_cachedb;
 119         /** number of replies sent */
 120         size_t replies_sent;
 121         /** sum of waiting times for the replies */
 122         struct timeval replies_sum_wait;
 123         /** histogram of time values */
 124         struct timehist* histogram;
 125         /** (extended stats) secure replies */
 126         size_t ans_secure;
 127         /** (extended stats) bogus replies */
 128         size_t ans_bogus;
 129         /** (extended stats) rcodes in replies */
 130         size_t ans_rcode[UB_STATS_RCODE_NUM];
 131         /** (extended stats) rcode nodata in replies */
 132         size_t ans_nodata;
 133         /** (extended stats) type of applied RPZ action */
 134         size_t rpz_action[UB_STATS_RPZ_ACTION_NUM];
 135
 136         /** backup of query if other operations recurse and need the
 137          * network buffers */
 138         struct sldns_buffer* qbuf_bak;
 139
 140         /** double linked list of the run-to-completion query states.
 141          * These are query states with a reply */
 142         struct mesh_state* forever_first;
 143         /** last entry in run forever list */
 144         struct mesh_state* forever_last;
 145
 146         /** double linked list of the query states that can be jostled out
 147          * by new queries if too old.  These are query states with a reply */
 148         struct mesh_state* jostle_first;
 149         /** last entry in jostle list - this is the entry that is newest */
 150         struct mesh_state* jostle_last;
 151         /** timeout for jostling. if age is lower, it does not get jostled. */
 152         struct timeval jostle_max;
 153
 154         /** If we need to use response ip (value passed from daemon)*/
 155         int use_response_ip;
 156         /** If we need to use RPZ (value passed from daemon) */
 157         int use_rpz;
 158 };
 159
 160 /**
 161  * A mesh query state
 162  * Unique per qname, qtype, qclass (from the qstate).
 163  * And RD / CD flag; in case a client turns it off.
 164  * And priming queries are different from ordinary queries (because of hints).
 165  *
 166  * The entire structure is allocated in a region, this region is the qstate
 167  * region. All parts (rbtree nodes etc) are also allocated in the region.
 168  */
 169 struct mesh_state {
 170         /** node in mesh_area all tree, key is this struct. Must be first. */
 171         rbnode_type node;
 172         /** node in mesh_area runnable tree, key is this struct */
 173         rbnode_type run_node;
 174         /** the query state. Note that the qinfo and query_flags
 175          * may not change. */
 176         struct module_qstate s;
 177         /** the list of replies to clients for the results */
 178         struct mesh_reply* reply_list;
 179         /** the list of callbacks for the results */
 180         struct mesh_cb* cb_list;
 181         /** set of superstates (that want this state's result)
 182          * contains struct mesh_state_ref* */
 183         rbtree_type super_set;
 184         /** set of substates (that this state needs to continue)
 185          * contains struct mesh_state_ref* */
 186         rbtree_type sub_set;
 187         /** number of activations for the mesh state */
 188         size_t num_activated;
 189
 190         /** previous in linked list for reply states */
 191         struct mesh_state* prev;
 192         /** next in linked list for reply states */
 193         struct mesh_state* next;
 194         /** if this state is in the forever list, jostle list, or neither */
 195         enum mesh_list_select { mesh_no_list, mesh_forever_list,
 196                 mesh_jostle_list } list_select;
 197         /** pointer to this state for uniqueness or NULL */
 198         struct mesh_state* unique;
 199
 200         /** true if replies have been sent out (at end for alignment) */
 201         uint8_t replies_sent;
 202 };
 203
 204 /**
 205  * Rbtree reference to a mesh_state.
 206  * Used in super_set and sub_set.
 207  */
 208 struct mesh_state_ref {
 209         /** node in rbtree for set, key is this structure */
 210         rbnode_type node;
 211         /** the mesh state */
 212         struct mesh_state* s;
 213 };
 214
 215 /**
 216  * Reply to a client
 217  */
 218 struct mesh_reply {
 219         /** next in reply list */
 220         struct mesh_reply* next;
 221         /** the query reply destination, packet buffer and where to send. */
 222         struct comm_reply query_reply;
 223         /** edns data from query */
 224         struct edns_data edns;
 225         /** the time when request was entered */
 226         struct timeval start_time;
 227         /** id of query, in network byteorder. */
 228         uint16_t qid;
 229         /** flags of query, for reply flags */
 230         uint16_t qflags;
 231         /** qname from this query. len same as mesh qinfo. */
 232         uint8_t* qname;
 233         /** same as that in query_info. */
 234         struct local_rrset* local_alias;
 235         /** send query to this http2 stream, if set */
 236         struct http2_stream* h2_stream;
 237 };
 238
 239 /**
 240  * Mesh result callback func.
 241  * called as func(cb_arg, rcode, buffer_with_reply, security, why_bogus,
 242  *              was_ratelimited);
 243  */
 244 typedef void (*mesh_cb_func_type)(void* cb_arg, int rcode, struct sldns_buffer*,
 245         enum sec_status, char* why_bogus, int was_ratelimited);
 246
 247 /**
 248  * Callback to result routine
 249  */
 250 struct mesh_cb {
 251         /** next in list */
 252         struct mesh_cb* next;
 253         /** edns data from query */
 254         struct edns_data edns;
 255         /** id of query, in network byteorder. */
 256         uint16_t qid;
 257         /** flags of query, for reply flags */
 258         uint16_t qflags;
 259         /** buffer for reply */
 260         struct sldns_buffer* buf;
 261         /** callback routine for results. if rcode != 0 buf has message.
 262          * called as cb(cb_arg, rcode, buf, sec_state, why_bogus, was_ratelimited);
 263          */
 264         mesh_cb_func_type cb;
 265         /** user arg for callback */
 266         void* cb_arg;
 267 };
 268
 269 /* ------------------- Functions for worker -------------------- */
 270
 271 /**
 272  * Allocate mesh, to empty.
 273  * @param stack: module stack to activate, copied (as readonly reference).
 274  * @param env: environment for new queries.
 275  * @return mesh: the new mesh or NULL on error.
 276  */
 277 struct mesh_area* mesh_create(struct module_stack* stack,
 278         struct module_env* env);
 279
 280 /**
 281  * Delete mesh, and all query states and replies in it.
 282  * @param mesh: the mesh to delete.
 283  */
 284 void mesh_delete(struct mesh_area* mesh);
 285
 286 /**
 287  * New query incoming from clients. Create new query state if needed, and
 288  * add mesh_reply to it. Returns error to client on malloc failures.
 289  * Will run the mesh area queries to process if a new query state is created.
 290  *
 291  * @param mesh: the mesh.
 292  * @param qinfo: query from client.
 293  * @param cinfo: additional information associated with the query client.
 294  *      'cinfo' itself is ephemeral but data pointed to by its members
 295  *      can be assumed to be valid and unchanged until the query processing is
 296  *      completed.
 297  * @param qflags: flags from client query.
 298  * @param edns: edns data from client query.
 299  * @param rep: where to reply to.
 300  * @param qid: query id to reply with.
 301  * @param rpz_passthru: if true, the rpz passthru was previously found and
 302  *      further rpz processing is stopped.
 303  */
 304 void mesh_new_client(struct mesh_area* mesh, struct query_info* qinfo,
 305         struct respip_client_info* cinfo, uint16_t qflags,
 306         struct edns_data* edns, struct comm_reply* rep, uint16_t qid,
 307         int rpz_passthru);
 308
 309 /**
 310  * New query with callback. Create new query state if needed, and
 311  * add mesh_cb to it.
 312  * Will run the mesh area queries to process if a new query state is created.
 313  *
 314  * @param mesh: the mesh.
 315  * @param qinfo: query from client.
 316  * @param qflags: flags from client query.
 317  * @param edns: edns data from client query.
 318  * @param buf: buffer for reply contents.
 319  * @param qid: query id to reply with.
 320  * @param cb: callback function.
 321  * @param cb_arg: callback user arg.
 322  * @param rpz_passthru: if true, the rpz passthru was previously found and
 323  *      further rpz processing is stopped.
 324  * @return 0 on error.
 325  */
 326 int mesh_new_callback(struct mesh_area* mesh, struct query_info* qinfo,
 327         uint16_t qflags, struct edns_data* edns, struct sldns_buffer* buf,
 328         uint16_t qid, mesh_cb_func_type cb, void* cb_arg, int rpz_passthru);
 329
 330 /**
 331  * New prefetch message. Create new query state if needed.
 332  * Will run the mesh area queries to process if a new query state is created.
 333  *
 334  * @param mesh: the mesh.
 335  * @param qinfo: query from client.
 336  * @param qflags: flags from client query.
 337  * @param leeway: TTL leeway what to expire earlier for this update.
 338  * @param rpz_passthru: if true, the rpz passthru was previously found and
 339  *      further rpz processing is stopped.
 340  * @param addr: sockaddr_storage for the client; to be used with subnet.
 341  * @param opt_list: edns opt_list from the client; to be used when subnet is
 342  *      enabled.
 343  */
 344 void mesh_new_prefetch(struct mesh_area* mesh, struct query_info* qinfo,
 345         uint16_t qflags, time_t leeway, int rpz_passthru,
 346         struct sockaddr_storage* addr, struct edns_option* opt_list);
 347
 348 /**
 349  * Handle new event from the wire. A serviced query has returned.
 350  * The query state will be made runnable, and the mesh_area will process
 351  * query states until processing is complete.
 352  *
 353  * @param mesh: the query mesh.
 354  * @param e: outbound entry, with query state to run and reply pointer.
 355  * @param reply: the comm point reply info.
 356  * @param what: NETEVENT_* error code (if not 0, what is wrong, TIMEOUT).
 357  */
 358 void mesh_report_reply(struct mesh_area* mesh, struct outbound_entry* e,
 359         struct comm_reply* reply, int what);
 360
 361 /* ------------------- Functions for module environment --------------- */
 362
 363 /**
 364  * Detach-subqueries.
 365  * Remove all sub-query references from this query state.
 366  * Keeps super-references of those sub-queries correct.
 367  * Updates stat items in mesh_area structure.
 368  * @param qstate: used to find mesh state.
 369  */
 370 void mesh_detach_subs(struct module_qstate* qstate);
 371
 372 /**
 373  * Attach subquery.
 374  * Creates it if it does not exist already.
 375  * Keeps sub and super references correct.
 376  * Performs a cycle detection - for double check - and fails if there is one.
 377  * Also fails if the sub-sub-references become too large.
 378  * Updates stat items in mesh_area structure.
 379  * Pass if it is priming query or not.
 380  * return:
 381  *      o if error (malloc) happened.
 382  *      o need to initialise the new state (module init; it is a new state).
 383  *        so that the next run of the query with this module is successful.
 384  *      o no init needed, attachment successful.
 385  *
 386  * @param qstate: the state to find mesh state, and that wants to receive
 387  *      the results from the new subquery.
 388  * @param qinfo: what to query for (copied).
 389  * @param qflags: what flags to use (RD / CD flag or not).
 390  * @param prime: if it is a (stub) priming query.
 391  * @param valrec: if it is a validation recursion query (lookup of key, DS).
 392  * @param newq: If the new subquery needs initialisation, it is returned,
 393  *      otherwise NULL is returned.
 394  * @return: false on error, true if success (and init may be needed).
 395  */
 396 int mesh_attach_sub(struct module_qstate* qstate, struct query_info* qinfo,
 397         uint16_t qflags, int prime, int valrec, struct module_qstate** newq);
 398
 399 /**
 400  * Add detached query.
 401  * Creates it if it does not exist already.
 402  * Does not make super/sub references.
 403  * Performs a cycle detection - for double check - and fails if there is one.
 404  * Updates stat items in mesh_area structure.
 405  * Pass if it is priming query or not.
 406  * return:
 407  *      o if error (malloc) happened.
 408  *      o need to initialise the new state (module init; it is a new state).
 409  *        so that the next run of the query with this module is successful.
 410  *      o no init needed, attachment successful.
 411  *      o added subquery, created if it did not exist already.
 412  *
 413  * @param qstate: the state to find mesh state, and that wants to receive
 414  *      the results from the new subquery.
 415  * @param qinfo: what to query for (copied).
 416  * @param qflags: what flags to use (RD / CD flag or not).
 417  * @param prime: if it is a (stub) priming query.
 418  * @param valrec: if it is a validation recursion query (lookup of key, DS).
 419  * @param newq: If the new subquery needs initialisation, it is returned,
 420  *      otherwise NULL is returned.
 421  * @param sub: The added mesh state, created if it did not exist already.
 422  * @return: false on error, true if success (and init may be needed).
 423  */
 424 int mesh_add_sub(struct module_qstate* qstate, struct query_info* qinfo,
 425         uint16_t qflags, int prime, int valrec, struct module_qstate** newq,
 426         struct mesh_state** sub);
 427
 428 /**
 429  * Query state is done, send messages to reply entries.
 430  * Encode messages using reply entry values and the querystate (with original
 431  * qinfo), using given reply_info.
 432  * Pass errcode != 0 if an error reply is needed.
 433  * If no reply entries, nothing is done.
 434  * Must be called before a module can module_finished or return module_error.
 435  * The module must handle the super query states itself as well.
 436  *
 437  * @param mstate: mesh state that is done. return_rcode and return_msg
 438  *      are used for replies.
 439  *      return_rcode: if not 0 (NOERROR) an error is sent back (and
 440  *              return_msg is ignored).
 441  *      return_msg: reply to encode and send back to clients.
 442  */
 443 void mesh_query_done(struct mesh_state* mstate);
 444
 445 /**
 446  * Call inform_super for the super query states that are interested in the
 447  * results from this query state. These can then be changed for error
 448  * or results.
 449  * Called when a module is module_finished or returns module_error.
 450  * The super query states become runnable with event module_event_pass,
 451  * it calls the current module for the super with the inform_super event.
 452  *
 453  * @param mesh: mesh area to add newly runnable modules to.
 454  * @param mstate: the state that has results, used to find mesh state.
 455  */
 456 void mesh_walk_supers(struct mesh_area* mesh, struct mesh_state* mstate);
 457
 458 /**
 459  * Delete mesh state, cleanup and also rbtrees and so on.
 460  * Will detach from all super/subnodes.
 461  * @param qstate: to remove.
 462  */
 463 void mesh_state_delete(struct module_qstate* qstate);
 464
 465 /* ------------------- Functions for mesh -------------------- */
 466
 467 /**
 468  * Create and initialize a new mesh state and its query state
 469  * Does not put the mesh state into rbtrees and so on.
 470  * @param env: module environment to set.
 471  * @param qinfo: query info that the mesh is for.
 472  * @param cinfo: control info for the query client (can be NULL).
 473  * @param qflags: flags for query (RD / CD flag).
 474  * @param prime: if true, it is a priming query, set is_priming on mesh state.
 475  * @param valrec: if true, it is a validation recursion query, and sets
 476  *      is_valrec on the mesh state.
 477  * @return: new mesh state or NULL on allocation error.
 478  */
 479 struct mesh_state* mesh_state_create(struct module_env* env,
 480         struct query_info* qinfo, struct respip_client_info* cinfo,
 481         uint16_t qflags, int prime, int valrec);
 482
 483 /**
 484  * Make a mesh state unique.
 485  * A unique mesh state uses it's unique member to point to itself.
 486  * @param mstate: mesh state to check.
 487  */
 488 void mesh_state_make_unique(struct mesh_state* mstate);
 489
 490 /**
 491  * Cleanup a mesh state and its query state. Does not do rbtree or
 492  * reference cleanup.
 493  * @param mstate: mesh state to cleanup. Its pointer may no longer be used
 494  *      afterwards. Cleanup rbtrees before calling this function.
 495  */
 496 void mesh_state_cleanup(struct mesh_state* mstate);
 497
 498 /**
 499  * Delete all mesh states from the mesh.
 500  * @param mesh: the mesh area to clear
 501  */
 502 void mesh_delete_all(struct mesh_area* mesh);
 503
 504 /**
 505  * Find a mesh state in the mesh area. Pass relevant flags.
 506  *
 507  * @param mesh: the mesh area to look in.
 508  * @param cinfo: if non-NULL client specific info that may affect IP-based
 509  *      actions that apply to the query result.
 510  * @param qinfo: what query
 511  * @param qflags: if RD / CD bit is set or not.
 512  * @param prime: if it is a priming query.
 513  * @param valrec: if it is a validation-recursion query.
 514  * @return: mesh state or NULL if not found.
 515  */
 516 struct mesh_state* mesh_area_find(struct mesh_area* mesh,
 517         struct respip_client_info* cinfo, struct query_info* qinfo,
 518         uint16_t qflags, int prime, int valrec);
 519
 520 /**
 521  * Setup attachment super/sub relation between super and sub mesh state.
 522  * The relation must not be present when calling the function.
 523  * Does not update stat items in mesh_area.
 524  * @param super: super state.
 525  * @param sub: sub state.
 526  * @return: 0 on alloc error.
 527  */
 528 int mesh_state_attachment(struct mesh_state* super, struct mesh_state* sub);
 529
 530 /**
 531  * Create new reply structure and attach it to a mesh state.
 532  * Does not update stat items in mesh area.
 533  * @param s: the mesh state.
 534  * @param edns: edns data for reply (bufsize).
 535  * @param rep: comm point reply info.
 536  * @param qid: ID of reply.
 537  * @param qflags: original query flags.
 538  * @param qinfo: original query info.
 539  * @return: 0 on alloc error.
 540  */
 541 int mesh_state_add_reply(struct mesh_state* s, struct edns_data* edns,
 542         struct comm_reply* rep, uint16_t qid, uint16_t qflags,
 543         const struct query_info* qinfo);
 544
 545 /**
 546  * Create new callback structure and attach it to a mesh state.
 547  * Does not update stat items in mesh area.
 548  * @param s: the mesh state.
 549  * @param edns: edns data for reply (bufsize).
 550  * @param buf: buffer for reply
 551  * @param cb: callback to call with results.
 552  * @param cb_arg: callback user arg.
 553  * @param qid: ID of reply.
 554  * @param qflags: original query flags.
 555  * @return: 0 on alloc error.
 556  */
 557 int mesh_state_add_cb(struct mesh_state* s, struct edns_data* edns,
 558         struct sldns_buffer* buf, mesh_cb_func_type cb, void* cb_arg,
 559         uint16_t qid, uint16_t qflags);
 560
 561 /**
 562  * Run the mesh. Run all runnable mesh states. Which can create new
 563  * runnable mesh states. Until completion. Automatically called by
 564  * mesh_report_reply and mesh_new_client as needed.
 565  * @param mesh: mesh area.
 566  * @param mstate: first mesh state to run.
 567  * @param ev: event the mstate. Others get event_pass.
 568  * @param e: if a reply, its outbound entry.
 569  */
 570 void mesh_run(struct mesh_area* mesh, struct mesh_state* mstate,
 571         enum module_ev ev, struct outbound_entry* e);
 572
 573 /**
 574  * Print some stats about the mesh to the log.
 575  * @param mesh: the mesh to print it for.
 576  * @param str: descriptive string to go with it.
 577  */
 578 void mesh_stats(struct mesh_area* mesh, const char* str);
 579
 580 /**
 581  * Clear the stats that the mesh keeps (number of queries serviced)
 582  * @param mesh: the mesh
 583  */
 584 void mesh_stats_clear(struct mesh_area* mesh);
 585
 586 /**
 587  * Print all the states in the mesh to the log.
 588  * @param mesh: the mesh to print all states of.
 589  */
 590 void mesh_log_list(struct mesh_area* mesh);
 591
 592 /**
 593  * Calculate memory size in use by mesh and all queries inside it.
 594  * @param mesh: the mesh to examine.
 595  * @return size in bytes.
 596  */
 597 size_t mesh_get_mem(struct mesh_area* mesh);
 598
 599 /**
 600  * Find cycle; see if the given mesh is in the targets sub, or sub-sub, ...
 601  * trees.
 602  * If the sub-sub structure is too large, it returns 'a cycle'=2.
 603  * @param qstate: given mesh querystate.
 604  * @param qinfo: query info for dependency.
 605  * @param flags: query flags of dependency.
 606  * @param prime: if dependency is a priming query or not.
 607  * @param valrec: if it is a validation recursion query (lookup of key, DS).
 608  * @return true if the name,type,class exists and the given qstate mesh exists
 609  *      as a dependency of that name. Thus if qstate becomes dependent on
 610  *      name,type,class then a cycle is created, this is return value 1.
 611  *      Too large to search is value 2 (also true).
 612  */
 613 int mesh_detect_cycle(struct module_qstate* qstate, struct query_info* qinfo,
 614         uint16_t flags, int prime, int valrec);
 615
 616 /** compare two mesh_states */
 617 int mesh_state_compare(const void* ap, const void* bp);
 618
 619 /** compare two mesh references */
 620 int mesh_state_ref_compare(const void* ap, const void* bp);
 621
 622 /**
 623  * Make space for another recursion state for a reply in the mesh
 624  * @param mesh: mesh area
 625  * @param qbuf: query buffer to save if recursion is invoked to make space.
 626  *    This buffer is necessary, because the following sequence in calls
 627  *    can result in an overwrite of the incoming query:
 628  *    delete_other_mesh_query - iter_clean - serviced_delete - waiting
 629  *    udp query is sent - on error callback - callback sends SERVFAIL reply
 630  *    over the same network channel, and shared UDP buffer is overwritten.
 631  *    You can pass NULL if there is no buffer that must be backed up.
 632  * @return false if no space is available.
 633  */
 634 int mesh_make_new_space(struct mesh_area* mesh, struct sldns_buffer* qbuf);
 635
 636 /**
 637  * Insert mesh state into a double linked list.  Inserted at end.
 638  * @param m: mesh state.
 639  * @param fp: pointer to the first-elem-pointer of the list.
 640  * @param lp: pointer to the last-elem-pointer of the list.
 641  */
 642 void mesh_list_insert(struct mesh_state* m, struct mesh_state** fp,
 643         struct mesh_state** lp);
 644
 645 /**
 646  * Remove mesh state from a double linked list.  Remove from any position.
 647  * @param m: mesh state.
 648  * @param fp: pointer to the first-elem-pointer of the list.
 649  * @param lp: pointer to the last-elem-pointer of the list.
 650  */
 651 void mesh_list_remove(struct mesh_state* m, struct mesh_state** fp,
 652         struct mesh_state** lp);
 653
 654 /**
 655  * Remove mesh reply entry from the reply entry list.  Searches for
 656  * the comm_point pointer.
 657  * @param mesh: to update the counters.
 658  * @param m: the mesh state.
 659  * @param cp: the comm_point to remove from the list.
 660  */
 661 void mesh_state_remove_reply(struct mesh_area* mesh, struct mesh_state* m,
 662         struct comm_point* cp);
 663
 664 /** Callback for when the serve expired client timer has run out.  Tries to
 665  * find an expired answer in the cache and reply that to the client.
 666  * @param arg: the argument passed to the callback.
 667  */
 668 void mesh_serve_expired_callback(void* arg);
 669
 670 /**
 671  * Try to get a (expired) cached answer.
 672  * This needs to behave like the worker's answer_from_cache() in order to have
 673  * the same behavior as when replying from cache.
 674  * @param qstate: the module qstate.
 675  * @param lookup_qinfo: the query info to look for in the cache.
 676  * @return dns_msg if a cached answer was found, otherwise NULL.
 677  */
 678 struct dns_msg*
 679 mesh_serve_expired_lookup(struct module_qstate* qstate,
 680         struct query_info* lookup_qinfo);
 681
 682 /**
 683  * See if the mesh has space for more queries. You can allocate queries
 684  * anyway, but this checks for the allocated space.
 685  * @param mesh: mesh area.
 686  * @return true if the query list is full.
 687  *      It checks the number of all queries, not just number of reply states,
 688  *      that have a client address. So that spawned queries count too,
 689  *      that were created by the iterator, or other modules.
 690  */
 691 int mesh_jostle_exceeded(struct mesh_area* mesh);
 692
 693 #endif /* SERVICES_MESH_H */