Home | History | Annotate | Line # | Download | only in cachedb 
      1 /*
      2  * cachedb/cachedb.h - cache from a database external to the program module
      3  *
      4  * Copyright (c) 2016, 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 a module that uses an external database to cache
     40  * dns responses.
     41  */
     42 #include "util/module.h"
     43 struct cachedb_backend;
     44 struct module_stack;
     45 
     46 /**
     47  * The global variable environment contents for the cachedb
     48  * Shared between threads, this represents long term information.
     49  * Like database connections.
     50  */
     51 struct cachedb_env {
     52 	/** true is cachedb is enabled, the backend is turned on */
     53 	int enabled;
     54 
     55 	/** the backend routines */
     56 	struct cachedb_backend* backend;
     57 
     58 	/** backend specific data here */
     59 	void* backend_data;
     60 };
     61 
     62 /**
     63  * Per query state for the cachedb module.
     64  */
     65 struct cachedb_qstate {
     66 	int todo;
     67 };
     68 
     69 /**
     70  * Backend call routines
     71  */
     72 struct cachedb_backend {
     73 	/** backend name */
     74 	const char* name;
     75 
     76 	/** Init(env, cachedb_env): false on setup failure */
     77 	int (*init)(struct module_env*, struct cachedb_env*);
     78 
     79 	/** Deinit - close db for program exit */
     80 	void (*deinit)(struct module_env*, struct cachedb_env*);
     81 
     82 	/** Lookup (env, cachedb_env, key, result_buffer): true if found */
     83 	int (*lookup)(struct module_env*, struct cachedb_env*, char*,
     84 		struct sldns_buffer*);
     85 
     86 	/** Store (env, cachedb_env, key, data, data_len) */
     87 	void (*store)(struct module_env*, struct cachedb_env*, char*,
     88 		uint8_t*, size_t, time_t);
     89 };
     90 
     91 #define CACHEDB_HASHSIZE 256 /* bit hash */
     92 
     93 /** Init the cachedb module */
     94 int cachedb_init(struct module_env* env, int id);
     95 /** Deinit the cachedb module */
     96 void cachedb_deinit(struct module_env* env, int id);
     97 /** Operate on an event on a query (in qstate). */
     98 void cachedb_operate(struct module_qstate* qstate, enum module_ev event,
     99 	int id, struct outbound_entry* outbound);
    100 /** Subordinate query done, inform this super request of its conclusion */
    101 void cachedb_inform_super(struct module_qstate* qstate, int id,
    102 	struct module_qstate* super);
    103 /** clear the cachedb query-specific contents out of qstate */
    104 void cachedb_clear(struct module_qstate* qstate, int id);
    105 /** return memory estimate for cachedb module */
    106 size_t cachedb_get_mem(struct module_env* env, int id);
    107 
    108 /**
    109  * Get the function block with pointers to the cachedb functions
    110  * @return the function block for "cachedb".
    111  */
    112 struct module_func_block* cachedb_get_funcblock(void);
    113 
    114 /**
    115  * See if the cachedb is enabled.
    116  * @param mods: module stack. It finds the cachedb module environment.
    117  * @param env: module environment.
    118  * @return true if exists and enabled.
    119  */
    120 int cachedb_is_enabled(struct module_stack* mods, struct module_env* env);
    121 
    122 /**
    123  * Remove a message from the global cache. Because edns subnet has a more
    124  * specific entry, and if not removed when everything expires, the global
    125  * entry is used, instead of a fresh lookup of the edns subnet entry.
    126  * @param qstate: query state.
    127  */
    128 void cachedb_msg_remove(struct module_qstate* qstate);
    129 
    130 /**
    131  * Remove message from the cachedb cache, by query info.
    132  * @param env: module environment to look up cachedb state.
    133  * @param qinfo: the message to remove.
    134  */
    135 void cachedb_msg_remove_qinfo(struct module_env* env,
    136 	struct query_info* qinfo);
    137