1*c0b5d9fbSchristos /* $NetBSD: cache.h,v 1.6 2022/09/23 12:15:30 christos Exp $ */ 2e2b1b9c0Schristos 3e2b1b9c0Schristos /* 4e2b1b9c0Schristos * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5e2b1b9c0Schristos * 6*c0b5d9fbSchristos * SPDX-License-Identifier: MPL-2.0 7*c0b5d9fbSchristos * 8e2b1b9c0Schristos * This Source Code Form is subject to the terms of the Mozilla Public 9e2b1b9c0Schristos * License, v. 2.0. If a copy of the MPL was not distributed with this 1073584a28Schristos * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11e2b1b9c0Schristos * 12e2b1b9c0Schristos * See the COPYRIGHT file distributed with this work for additional 13e2b1b9c0Schristos * information regarding copyright ownership. 14e2b1b9c0Schristos */ 15e2b1b9c0Schristos 16e2b1b9c0Schristos #ifndef DNS_CACHE_H 17e2b1b9c0Schristos #define DNS_CACHE_H 1 18e2b1b9c0Schristos 19e2b1b9c0Schristos /***** 20e2b1b9c0Schristos ***** Module Info 21e2b1b9c0Schristos *****/ 22e2b1b9c0Schristos 23e2b1b9c0Schristos /*! \file dns/cache.h 24e2b1b9c0Schristos * \brief 25e2b1b9c0Schristos * Defines dns_cache_t, the cache object. 26e2b1b9c0Schristos * 27e2b1b9c0Schristos * Notes: 28e2b1b9c0Schristos *\li A cache object contains DNS data of a single class. 29e2b1b9c0Schristos * Multiple classes will be handled by creating multiple 30e2b1b9c0Schristos * views, each with a different class and its own cache. 31e2b1b9c0Schristos * 32e2b1b9c0Schristos * MP: 33e2b1b9c0Schristos *\li See notes at the individual functions. 34e2b1b9c0Schristos * 35e2b1b9c0Schristos * Reliability: 36e2b1b9c0Schristos * 37e2b1b9c0Schristos * Resources: 38e2b1b9c0Schristos * 39e2b1b9c0Schristos * Security: 40e2b1b9c0Schristos * 41e2b1b9c0Schristos * Standards: 42e2b1b9c0Schristos */ 43e2b1b9c0Schristos 44e2b1b9c0Schristos /*** 45e2b1b9c0Schristos *** Imports 46e2b1b9c0Schristos ***/ 47e2b1b9c0Schristos 48f2e20987Schristos #include <stdbool.h> 49f2e20987Schristos 50e2b1b9c0Schristos #include <isc/lang.h> 51e2b1b9c0Schristos #include <isc/stats.h> 52e2b1b9c0Schristos #include <isc/stdtime.h> 53e2b1b9c0Schristos 54e2b1b9c0Schristos #include <dns/types.h> 55e2b1b9c0Schristos 56e2b1b9c0Schristos ISC_LANG_BEGINDECLS 57e2b1b9c0Schristos 58e2b1b9c0Schristos /*** 59e2b1b9c0Schristos *** Functions 60e2b1b9c0Schristos ***/ 61e2b1b9c0Schristos isc_result_t 62f2e20987Schristos dns_cache_create(isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr, 63e2b1b9c0Schristos isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, 64e2b1b9c0Schristos const char *cachename, const char *db_type, 65e2b1b9c0Schristos unsigned int db_argc, char **db_argv, dns_cache_t **cachep); 66e2b1b9c0Schristos /*%< 67e2b1b9c0Schristos * Create a new DNS cache. 68e2b1b9c0Schristos * 69e2b1b9c0Schristos * dns_cache_create2() will create a named cache. 70e2b1b9c0Schristos * 71e2b1b9c0Schristos * dns_cache_create3() will create a named cache using two separate memory 72e2b1b9c0Schristos * contexts, one for cache data which can be cleaned and a separate one for 73e2b1b9c0Schristos * memory allocated for the heap (which can grow without an upper limit and 74e2b1b9c0Schristos * has no mechanism for shrinking). 75e2b1b9c0Schristos * 76e2b1b9c0Schristos * dns_cache_create() is a backward compatible version that internally 77e2b1b9c0Schristos * specifies an empty cache name and a single memory context. 78e2b1b9c0Schristos * 79e2b1b9c0Schristos * Requires: 80e2b1b9c0Schristos * 81e2b1b9c0Schristos *\li 'cmctx' (and 'hmctx' if applicable) is a valid memory context. 82e2b1b9c0Schristos * 83e2b1b9c0Schristos *\li 'taskmgr' is a valid task manager and 'timermgr' is a valid timer 84e2b1b9c0Schristos * manager, or both are NULL. If NULL, no periodic cleaning of the 85e2b1b9c0Schristos * cache will take place. 86e2b1b9c0Schristos * 87e2b1b9c0Schristos *\li 'cachename' is a valid string. This must not be NULL. 88e2b1b9c0Schristos * 89e2b1b9c0Schristos *\li 'cachep' is a valid pointer, and *cachep == NULL 90e2b1b9c0Schristos * 91e2b1b9c0Schristos * Ensures: 92e2b1b9c0Schristos * 93e2b1b9c0Schristos *\li '*cachep' is attached to the newly created cache 94e2b1b9c0Schristos * 95e2b1b9c0Schristos * Returns: 96e2b1b9c0Schristos * 97e2b1b9c0Schristos *\li #ISC_R_SUCCESS 98e2b1b9c0Schristos *\li #ISC_R_NOMEMORY 99e2b1b9c0Schristos */ 100e2b1b9c0Schristos 101e2b1b9c0Schristos void 102e2b1b9c0Schristos dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp); 103e2b1b9c0Schristos /*%< 104e2b1b9c0Schristos * Attach *targetp to cache. 105e2b1b9c0Schristos * 106e2b1b9c0Schristos * Requires: 107e2b1b9c0Schristos * 108e2b1b9c0Schristos *\li 'cache' is a valid cache. 109e2b1b9c0Schristos * 110e2b1b9c0Schristos *\li 'targetp' points to a NULL dns_cache_t *. 111e2b1b9c0Schristos * 112e2b1b9c0Schristos * Ensures: 113e2b1b9c0Schristos * 114e2b1b9c0Schristos *\li *targetp is attached to cache. 115e2b1b9c0Schristos */ 116e2b1b9c0Schristos 117e2b1b9c0Schristos void 118e2b1b9c0Schristos dns_cache_detach(dns_cache_t **cachep); 119e2b1b9c0Schristos /*%< 120e2b1b9c0Schristos * Detach *cachep from its cache. 121e2b1b9c0Schristos * 122e2b1b9c0Schristos * Requires: 123e2b1b9c0Schristos * 124e2b1b9c0Schristos *\li 'cachep' points to a valid cache. 125e2b1b9c0Schristos * 126e2b1b9c0Schristos * Ensures: 127e2b1b9c0Schristos * 128e2b1b9c0Schristos *\li *cachep is NULL. 129e2b1b9c0Schristos * 130e2b1b9c0Schristos *\li If '*cachep' is the last reference to the cache, 131e2b1b9c0Schristos * all resources used by the cache will be freed 132e2b1b9c0Schristos */ 133e2b1b9c0Schristos 134e2b1b9c0Schristos void 135e2b1b9c0Schristos dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp); 136e2b1b9c0Schristos /*%< 137e2b1b9c0Schristos * Attach *dbp to the cache's database. 138e2b1b9c0Schristos * 139e2b1b9c0Schristos * Notes: 140e2b1b9c0Schristos * 141e2b1b9c0Schristos *\li This may be used to get a reference to the database for 142e2b1b9c0Schristos * the purpose of cache lookups (XXX currently it is also 143e2b1b9c0Schristos * the way to add data to the cache, but having a 144e2b1b9c0Schristos * separate dns_cache_add() interface instead would allow 145e2b1b9c0Schristos * more control over memory usage). 146e2b1b9c0Schristos * The caller should call dns_db_detach() on the reference 147e2b1b9c0Schristos * when it is no longer needed. 148e2b1b9c0Schristos * 149e2b1b9c0Schristos * Requires: 150e2b1b9c0Schristos * 151e2b1b9c0Schristos *\li 'cache' is a valid cache. 152e2b1b9c0Schristos * 153e2b1b9c0Schristos *\li 'dbp' points to a NULL dns_db *. 154e2b1b9c0Schristos * 155e2b1b9c0Schristos * Ensures: 156e2b1b9c0Schristos * 157e2b1b9c0Schristos *\li *dbp is attached to the database. 158e2b1b9c0Schristos */ 159e2b1b9c0Schristos 160e2b1b9c0Schristos isc_result_t 161e2b1b9c0Schristos dns_cache_setfilename(dns_cache_t *cache, const char *filename); 162e2b1b9c0Schristos /*%< 163e2b1b9c0Schristos * If 'filename' is non-NULL, make the cache persistent. 164e2b1b9c0Schristos * The cache's data will be stored in the given file. 165e2b1b9c0Schristos * If 'filename' is NULL, make the cache non-persistent. 166e2b1b9c0Schristos * Files that are no longer used are not unlinked automatically. 167e2b1b9c0Schristos * 168e2b1b9c0Schristos * Returns: 169e2b1b9c0Schristos *\li #ISC_R_SUCCESS 170e2b1b9c0Schristos *\li #ISC_R_NOMEMORY 171e2b1b9c0Schristos *\li Various file-related failures 172e2b1b9c0Schristos */ 173e2b1b9c0Schristos 174e2b1b9c0Schristos isc_result_t 175e2b1b9c0Schristos dns_cache_load(dns_cache_t *cache); 176e2b1b9c0Schristos /*%< 177e2b1b9c0Schristos * If the cache has a file name, load the cache contents from the file. 178e2b1b9c0Schristos * Previous cache contents are not discarded. 179e2b1b9c0Schristos * If no file name has been set, do nothing and return success. 180e2b1b9c0Schristos * 181e2b1b9c0Schristos * MT: 182e2b1b9c0Schristos *\li Multiple simultaneous attempts to load or dump the cache 183e2b1b9c0Schristos * will be serialized with respect to one another, but 184e2b1b9c0Schristos * the cache may be read and updated while the dump is 185e2b1b9c0Schristos * in progress. Updates performed during loading 186e2b1b9c0Schristos * may or may not be preserved, and reads may return 187e2b1b9c0Schristos * either the old or the newly loaded data. 188e2b1b9c0Schristos * 189e2b1b9c0Schristos * Returns: 190e2b1b9c0Schristos * 191e2b1b9c0Schristos *\li #ISC_R_SUCCESS 192e2b1b9c0Schristos * \li Various failures depending on the database implementation type 193e2b1b9c0Schristos */ 194e2b1b9c0Schristos 195e2b1b9c0Schristos isc_result_t 196e2b1b9c0Schristos dns_cache_dump(dns_cache_t *cache); 197e2b1b9c0Schristos /*%< 198e2b1b9c0Schristos * If the cache has a file name, write the cache contents to disk, 199e2b1b9c0Schristos * overwriting any preexisting file. If no file name has been set, 200e2b1b9c0Schristos * do nothing and return success. 201e2b1b9c0Schristos * 202e2b1b9c0Schristos * MT: 203e2b1b9c0Schristos *\li Multiple simultaneous attempts to load or dump the cache 204e2b1b9c0Schristos * will be serialized with respect to one another, but 205e2b1b9c0Schristos * the cache may be read and updated while the dump is 206e2b1b9c0Schristos * in progress. Updates performed during the dump may 207e2b1b9c0Schristos * or may not be reflected in the dumped file. 208e2b1b9c0Schristos * 209e2b1b9c0Schristos * Returns: 210e2b1b9c0Schristos * 211e2b1b9c0Schristos *\li #ISC_R_SUCCESS 212e2b1b9c0Schristos * \li Various failures depending on the database implementation type 213e2b1b9c0Schristos */ 214e2b1b9c0Schristos 215e2b1b9c0Schristos isc_result_t 216e2b1b9c0Schristos dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now); 217e2b1b9c0Schristos /*%< 218e2b1b9c0Schristos * Force immediate cleaning of the cache, freeing all rdatasets 219e2b1b9c0Schristos * whose TTL has expired as of 'now' and that have no pending 220e2b1b9c0Schristos * references. 221e2b1b9c0Schristos */ 222e2b1b9c0Schristos 223e2b1b9c0Schristos const char * 224e2b1b9c0Schristos dns_cache_getname(dns_cache_t *cache); 225e2b1b9c0Schristos /*%< 226e2b1b9c0Schristos * Get the cache name. 227e2b1b9c0Schristos */ 228e2b1b9c0Schristos 229e2b1b9c0Schristos void 230e2b1b9c0Schristos dns_cache_setcachesize(dns_cache_t *cache, size_t size); 231e2b1b9c0Schristos /*%< 232e2b1b9c0Schristos * Set the maximum cache size. 0 means unlimited. 233e2b1b9c0Schristos */ 234e2b1b9c0Schristos 235e2b1b9c0Schristos size_t 236e2b1b9c0Schristos dns_cache_getcachesize(dns_cache_t *cache); 237e2b1b9c0Schristos /*%< 238e2b1b9c0Schristos * Get the maximum cache size. 239e2b1b9c0Schristos */ 240e2b1b9c0Schristos 241e2b1b9c0Schristos void 242e2b1b9c0Schristos dns_cache_setservestalettl(dns_cache_t *cache, dns_ttl_t ttl); 243e2b1b9c0Schristos /*%< 244e2b1b9c0Schristos * Sets the maximum length of time that cached answers may be retained 245e2b1b9c0Schristos * past their normal TTL. Default value for the library is 0, disabling 246e2b1b9c0Schristos * the use of stale data. 247e2b1b9c0Schristos * 248e2b1b9c0Schristos * Requires: 249e2b1b9c0Schristos *\li 'cache' to be valid. 250e2b1b9c0Schristos */ 251e2b1b9c0Schristos 252e2b1b9c0Schristos dns_ttl_t 253e2b1b9c0Schristos dns_cache_getservestalettl(dns_cache_t *cache); 254e2b1b9c0Schristos /*%< 255e2b1b9c0Schristos * Gets the maximum length of time that cached answers may be kept past 256e2b1b9c0Schristos * normal expiry. 257e2b1b9c0Schristos * 258e2b1b9c0Schristos * Requires: 259e2b1b9c0Schristos *\li 'cache' to be valid. 260e2b1b9c0Schristos */ 261e2b1b9c0Schristos 26273584a28Schristos void 26373584a28Schristos dns_cache_setservestalerefresh(dns_cache_t *cache, dns_ttl_t interval); 26473584a28Schristos /*%< 26573584a28Schristos * Sets the length of time to wait before attempting to refresh a rrset 26673584a28Schristos * if a previous attempt in doing so has failed. 26773584a28Schristos * During this time window if stale rrset are available in cache they 26873584a28Schristos * will be directly returned to client. 26973584a28Schristos * 27073584a28Schristos * Requires: 27173584a28Schristos *\li 'cache' to be valid. 27273584a28Schristos */ 27373584a28Schristos 27473584a28Schristos dns_ttl_t 27573584a28Schristos dns_cache_getservestalerefresh(dns_cache_t *cache); 27673584a28Schristos /*%< 27773584a28Schristos * Gets the 'stale-refresh-time' value, set by a previous call to 27873584a28Schristos * 'dns_cache_setservestalerefresh'. 27973584a28Schristos * 28073584a28Schristos * Requires: 28173584a28Schristos *\li 'cache' to be valid. 28273584a28Schristos */ 28373584a28Schristos 284e2b1b9c0Schristos isc_result_t 285e2b1b9c0Schristos dns_cache_flush(dns_cache_t *cache); 286e2b1b9c0Schristos /*%< 287e2b1b9c0Schristos * Flushes all data from the cache. 288e2b1b9c0Schristos * 289e2b1b9c0Schristos * Returns: 290e2b1b9c0Schristos *\li #ISC_R_SUCCESS 291e2b1b9c0Schristos *\li #ISC_R_NOMEMORY 292e2b1b9c0Schristos */ 293e2b1b9c0Schristos 294e2b1b9c0Schristos isc_result_t 2959742fdb4Schristos dns_cache_flushnode(dns_cache_t *cache, const dns_name_t *name, bool tree); 296e2b1b9c0Schristos /* 297e2b1b9c0Schristos * Flush a given name from the cache. If 'tree' is true, then 298e2b1b9c0Schristos * also flush all names under 'name'. 299e2b1b9c0Schristos * 300e2b1b9c0Schristos * Requires: 301e2b1b9c0Schristos *\li 'cache' to be valid. 302e2b1b9c0Schristos *\li 'name' to be valid. 303e2b1b9c0Schristos * 304e2b1b9c0Schristos * Returns: 305e2b1b9c0Schristos *\li #ISC_R_SUCCESS 306e2b1b9c0Schristos *\li #ISC_R_NOMEMORY 307e2b1b9c0Schristos *\li other error returns. 308e2b1b9c0Schristos */ 309e2b1b9c0Schristos 310e2b1b9c0Schristos isc_result_t 311e2b1b9c0Schristos dns_cache_flushname(dns_cache_t *cache, const dns_name_t *name); 312e2b1b9c0Schristos /* 313e2b1b9c0Schristos * Flush a given name from the cache. Equivalent to 314f2e20987Schristos * dns_cache_flushpartial(cache, name, false). 315e2b1b9c0Schristos * 316e2b1b9c0Schristos * Requires: 317e2b1b9c0Schristos *\li 'cache' to be valid. 318e2b1b9c0Schristos *\li 'name' to be valid. 319e2b1b9c0Schristos * 320e2b1b9c0Schristos * Returns: 321e2b1b9c0Schristos *\li #ISC_R_SUCCESS 322e2b1b9c0Schristos *\li #ISC_R_NOMEMORY 323e2b1b9c0Schristos *\li other error returns. 324e2b1b9c0Schristos */ 325e2b1b9c0Schristos 326e2b1b9c0Schristos isc_stats_t * 327e2b1b9c0Schristos dns_cache_getstats(dns_cache_t *cache); 328e2b1b9c0Schristos /* 329e2b1b9c0Schristos * Return a pointer to the stats collection object for 'cache' 330e2b1b9c0Schristos */ 331e2b1b9c0Schristos 332e2b1b9c0Schristos void 333e2b1b9c0Schristos dns_cache_dumpstats(dns_cache_t *cache, FILE *fp); 334e2b1b9c0Schristos /* 335e2b1b9c0Schristos * Dump cache statistics and status in text to 'fp' 336e2b1b9c0Schristos */ 337e2b1b9c0Schristos 338e2b1b9c0Schristos void 339e2b1b9c0Schristos dns_cache_updatestats(dns_cache_t *cache, isc_result_t result); 340e2b1b9c0Schristos /* 341e2b1b9c0Schristos * Update cache statistics based on result code in 'result' 342e2b1b9c0Schristos */ 343e2b1b9c0Schristos 344e2b1b9c0Schristos #ifdef HAVE_LIBXML2 345e2b1b9c0Schristos int 3469742fdb4Schristos dns_cache_renderxml(dns_cache_t *cache, void *writer0); 347e2b1b9c0Schristos /* 348e2b1b9c0Schristos * Render cache statistics and status in XML for 'writer'. 349e2b1b9c0Schristos */ 350e2b1b9c0Schristos #endif /* HAVE_LIBXML2 */ 351e2b1b9c0Schristos 3529742fdb4Schristos #ifdef HAVE_JSON_C 353e2b1b9c0Schristos isc_result_t 3549742fdb4Schristos dns_cache_renderjson(dns_cache_t *cache, void *cstats0); 355e2b1b9c0Schristos /* 356e2b1b9c0Schristos * Render cache statistics and status in JSON 357e2b1b9c0Schristos */ 3589742fdb4Schristos #endif /* HAVE_JSON_C */ 359e2b1b9c0Schristos 360e2b1b9c0Schristos ISC_LANG_ENDDECLS 361e2b1b9c0Schristos 362e2b1b9c0Schristos #endif /* DNS_CACHE_H */ 363