res_resolver_unbound: Fix config documentation.
[asterisk/asterisk.git] / res / res_sorcery_config.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012 - 2013, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  *
22  * \brief Sorcery Configuration File Object Wizard
23  *
24  * \author Joshua Colp <jcolp@digium.com>
25  */
26
27 /*** MODULEINFO
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 ASTERISK_REGISTER_FILE()
34
35 #include <regex.h>
36
37 #include "asterisk/module.h"
38 #include "asterisk/sorcery.h"
39 #include "asterisk/astobj2.h"
40 #include "asterisk/config.h"
41 #include "asterisk/uuid.h"
42 #include "asterisk/hashtab.h"
43
44 /*! \brief Structure for storing configuration file sourced objects */
45 struct sorcery_config {
46         /*! \brief UUID for identifying us when opening a configuration file */
47         char uuid[AST_UUID_STR_LEN];
48
49         /*! \brief Objects retrieved from the configuration file */
50         struct ao2_global_obj objects;
51
52         /*! \brief Any specific variable criteria for considering a defined category for this object */
53         struct ast_variable *criteria;
54
55         /*! \brief Number of buckets to use for objects */
56         unsigned int buckets;
57
58         /*! \brief Enable file level integrity instead of object level */
59         unsigned int file_integrity:1;
60
61         /*! \brief Filename of the configuration file */
62         char filename[];
63 };
64
65 /*! \brief Structure used for fields comparison */
66 struct sorcery_config_fields_cmp_params {
67         /*! \brief Pointer to the sorcery structure */
68         const struct ast_sorcery *sorcery;
69
70         /*! \brief Pointer to the fields to check */
71         const struct ast_variable *fields;
72
73         /*! \brief Regular expression for checking object id */
74         regex_t *regex;
75
76         /*! \brief Optional container to put object into */
77         struct ao2_container *container;
78 };
79
80 static void *sorcery_config_open(const char *data);
81 static void sorcery_config_load(void *data, const struct ast_sorcery *sorcery, const char *type);
82 static void sorcery_config_reload(void *data, const struct ast_sorcery *sorcery, const char *type);
83 static void *sorcery_config_retrieve_id(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id);
84 static void *sorcery_config_retrieve_fields(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields);
85 static void sorcery_config_retrieve_multiple(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects,
86                                              const struct ast_variable *fields);
87 static void sorcery_config_retrieve_regex(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex);
88 static void sorcery_config_close(void *data);
89
90 static struct ast_sorcery_wizard config_object_wizard = {
91         .name = "config",
92         .open = sorcery_config_open,
93         .load = sorcery_config_load,
94         .reload = sorcery_config_reload,
95         .retrieve_id = sorcery_config_retrieve_id,
96         .retrieve_fields = sorcery_config_retrieve_fields,
97         .retrieve_multiple = sorcery_config_retrieve_multiple,
98         .retrieve_regex = sorcery_config_retrieve_regex,
99         .close = sorcery_config_close,
100 };
101
102 /*! \brief Destructor function for sorcery config */
103 static void sorcery_config_destructor(void *obj)
104 {
105         struct sorcery_config *config = obj;
106
107         ao2_global_obj_release(config->objects);
108         ast_rwlock_destroy(&config->objects.lock);
109         ast_variables_destroy(config->criteria);
110 }
111
112 static int sorcery_config_fields_cmp(void *obj, void *arg, int flags)
113 {
114         const struct sorcery_config_fields_cmp_params *params = arg;
115         RAII_VAR(struct ast_variable *, objset, NULL, ast_variables_destroy);
116
117         if (params->regex) {
118                 /* If a regular expression has been provided see if it matches, otherwise move on */
119                 if (!regexec(params->regex, ast_sorcery_object_get_id(obj), 0, NULL, 0)) {
120                         ao2_link(params->container, obj);
121                 }
122                 return 0;
123         } else if (params->fields &&
124             (!(objset = ast_sorcery_objectset_create(params->sorcery, obj)) ||
125              (!ast_variable_lists_match(objset, params->fields, 0)))) {
126                 /* If we can't turn the object into an object set OR if differences exist between the fields
127                  * passed in and what are present on the object they are not a match.
128                  */
129                 return 0;
130         }
131
132         /* We want this object */
133         if (params->container) {
134                 /*
135                  * We are putting the found objects into the given container instead
136                  * of the normal container traversal return mechanism.
137                  */
138                 ao2_link(params->container, obj);
139                 return 0;
140         } else {
141                 return CMP_MATCH;
142         }
143 }
144
145 static void *sorcery_config_retrieve_fields(const struct ast_sorcery *sorcery, void *data, const char *type, const struct ast_variable *fields)
146 {
147         struct sorcery_config *config = data;
148         RAII_VAR(struct ao2_container *, objects, ao2_global_obj_ref(config->objects), ao2_cleanup);
149         struct sorcery_config_fields_cmp_params params = {
150                 .sorcery = sorcery,
151                 .fields = fields,
152                 .container = NULL,
153         };
154
155         /* If no fields are present return nothing, we require *something*, same goes if no objects exist yet */
156         if (!objects || !fields) {
157                 return NULL;
158         }
159
160         return ao2_callback(objects, 0, sorcery_config_fields_cmp, &params);
161 }
162
163 static void *sorcery_config_retrieve_id(const struct ast_sorcery *sorcery, void *data, const char *type, const char *id)
164 {
165         struct sorcery_config *config = data;
166         RAII_VAR(struct ao2_container *, objects, ao2_global_obj_ref(config->objects), ao2_cleanup);
167
168         return objects ? ao2_find(objects, id, OBJ_SEARCH_KEY) : NULL;
169 }
170
171 static void sorcery_config_retrieve_multiple(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const struct ast_variable *fields)
172 {
173         struct sorcery_config *config = data;
174         RAII_VAR(struct ao2_container *, config_objects, ao2_global_obj_ref(config->objects), ao2_cleanup);
175         struct sorcery_config_fields_cmp_params params = {
176                 .sorcery = sorcery,
177                 .fields = fields,
178                 .container = objects,
179         };
180
181         if (!config_objects) {
182                 return;
183         }
184
185         ao2_callback(config_objects, OBJ_NODATA | OBJ_MULTIPLE, sorcery_config_fields_cmp, &params);
186 }
187
188 static void sorcery_config_retrieve_regex(const struct ast_sorcery *sorcery, void *data, const char *type, struct ao2_container *objects, const char *regex)
189 {
190         struct sorcery_config *config = data;
191         RAII_VAR(struct ao2_container *, config_objects, ao2_global_obj_ref(config->objects), ao2_cleanup);
192         regex_t expression;
193         struct sorcery_config_fields_cmp_params params = {
194                 .sorcery = sorcery,
195                 .container = objects,
196                 .regex = &expression,
197         };
198
199         if (ast_strlen_zero(regex)) {
200                 regex = ".";
201         }
202
203         if (!config_objects || regcomp(&expression, regex, REG_EXTENDED | REG_NOSUB)) {
204                 return;
205         }
206
207         ao2_callback(config_objects, OBJ_NODATA | OBJ_MULTIPLE, sorcery_config_fields_cmp, &params);
208         regfree(&expression);
209 }
210
211 /*! \brief Internal function which determines if criteria has been met for considering an object set applicable */
212 static int sorcery_is_criteria_met(struct ast_variable *objset, struct ast_variable *criteria)
213 {
214         RAII_VAR(struct ast_variable *, diff, NULL, ast_variables_destroy);
215
216         return (!criteria || (!ast_sorcery_changeset_create(objset, criteria, &diff) && !diff)) ? 1 : 0;
217 }
218
219 static void sorcery_config_internal_load(void *data, const struct ast_sorcery *sorcery, const char *type, unsigned int reload)
220 {
221         struct sorcery_config *config = data;
222         struct ast_flags flags = { reload ? CONFIG_FLAG_FILEUNCHANGED : 0 };
223         struct ast_config *cfg = ast_config_load2(config->filename, config->uuid, flags);
224         struct ast_category *category = NULL;
225         RAII_VAR(struct ao2_container *, objects, NULL, ao2_cleanup);
226         const char *id = NULL;
227         unsigned int buckets = 0;
228
229         if (!cfg) {
230                 ast_log(LOG_ERROR, "Unable to load config file '%s'\n", config->filename);
231                 return;
232         } else if (cfg == CONFIG_STATUS_FILEUNCHANGED) {
233                 ast_debug(1, "Config file '%s' was unchanged\n", config->filename);
234                 return;
235         } else if (cfg == CONFIG_STATUS_FILEINVALID) {
236                 ast_log(LOG_ERROR, "Contents of config file '%s' are invalid and cannot be parsed\n", config->filename);
237                 return;
238         }
239
240         if (!config->buckets) {
241                 while ((category = ast_category_browse_filtered(cfg, NULL, category, NULL))) {
242
243                         /* If given criteria has not been met skip the category, it is not applicable */
244                         if (!sorcery_is_criteria_met(ast_category_first(category), config->criteria)) {
245                                 continue;
246                         }
247
248                         buckets++;
249                 }
250
251                 /* Determine the optimal number of buckets */
252                 while (buckets && !ast_is_prime(buckets)) {
253                         /* This purposely goes backwards to ensure that the container doesn't have a ton of
254                          * empty buckets for objects that will never get added.
255                          */
256                         buckets--;
257                 }
258
259                 if (!buckets) {
260                         buckets = 1;
261                 }
262         } else {
263                 buckets = config->buckets;
264         }
265
266         ast_debug(2, "Using bucket size of '%d' for objects of type '%s' from '%s'\n",
267                 buckets, type, config->filename);
268
269         objects = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, buckets,
270                 ast_sorcery_object_id_hash, NULL, ast_sorcery_object_id_compare);
271         if (!objects) {
272                 ast_log(LOG_ERROR, "Could not create bucket for new objects from '%s', keeping existing objects\n",
273                         config->filename);
274                 ast_config_destroy(cfg);
275                 return;
276         }
277
278         while ((category = ast_category_browse_filtered(cfg, NULL, category, NULL))) {
279                 RAII_VAR(void *, obj, NULL, ao2_cleanup);
280                 id = ast_category_get_name(category);
281
282                 /* If given criteria has not been met skip the category, it is not applicable */
283                 if (!sorcery_is_criteria_met(ast_category_first(category), config->criteria)) {
284                         continue;
285                 }
286
287                 /*  Confirm an object with this id does not already exist in the bucket.
288                  *  If it exists, however, the configuration is invalid so stop
289                  *  processing and destroy it. */
290                 obj = ao2_find(objects, id, OBJ_SEARCH_KEY);
291                 if (obj) {
292                         ast_log(LOG_ERROR, "Config file '%s' could not be loaded; configuration contains a duplicate object: '%s' of type '%s'\n",
293                                 config->filename, id, type);
294                         ast_config_destroy(cfg);
295                         return;
296                 }
297
298                 if (!(obj = ast_sorcery_alloc(sorcery, type, id)) ||
299                     ast_sorcery_objectset_apply(sorcery, obj, ast_category_first(category))) {
300
301                         if (config->file_integrity) {
302                                 ast_log(LOG_ERROR, "Config file '%s' could not be loaded due to error with object '%s' of type '%s'\n",
303                                         config->filename, id, type);
304                                 ast_config_destroy(cfg);
305                                 return;
306                         } else {
307                                 ast_log(LOG_ERROR, "Could not create an object of type '%s' with id '%s' from configuration file '%s'\n",
308                                         type, id, config->filename);
309                         }
310
311                         ao2_cleanup(obj);
312
313                         /* To ensure we don't lose the object that already exists we retrieve it from the old objects container and add it to the new one */
314                         if (!(obj = sorcery_config_retrieve_id(sorcery, data, type, id))) {
315                                 continue;
316                         }
317
318                         ast_log(LOG_NOTICE, "Retaining existing configuration for object of type '%s' with id '%s'\n", type, id);
319                 }
320
321                 ao2_link(objects, obj);
322         }
323
324         ao2_global_obj_replace_unref(config->objects, objects);
325         ast_config_destroy(cfg);
326 }
327
328 static void sorcery_config_load(void *data, const struct ast_sorcery *sorcery, const char *type)
329 {
330         sorcery_config_internal_load(data, sorcery, type, 0);
331 }
332
333 static void sorcery_config_reload(void *data, const struct ast_sorcery *sorcery, const char *type)
334 {
335         sorcery_config_internal_load(data, sorcery, type, 1);
336 }
337
338 static void *sorcery_config_open(const char *data)
339 {
340         char *tmp;
341         char *filename;
342         char *option;
343         struct sorcery_config *config;
344
345         if (ast_strlen_zero(data)) {
346                 return NULL;
347         }
348
349         tmp = ast_strdupa(data);
350         filename = strsep(&tmp, ",");
351
352         if (ast_strlen_zero(filename) || !(config = ao2_alloc_options(sizeof(*config) + strlen(filename) + 1, sorcery_config_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK))) {
353                 return NULL;
354         }
355
356         ast_uuid_generate_str(config->uuid, sizeof(config->uuid));
357
358         ast_rwlock_init(&config->objects.lock);
359         strcpy(config->filename, filename);
360
361         while ((option = strsep(&tmp, ","))) {
362                 char *name = strsep(&option, "="), *value = option;
363
364                 if (!strcasecmp(name, "buckets")) {
365                         if (sscanf(value, "%30u", &config->buckets) != 1) {
366                                 ast_log(LOG_ERROR, "Unsupported bucket size of '%s' used for configuration file '%s', defaulting to automatic determination\n",
367                                         value, filename);
368                         }
369                 } else if (!strcasecmp(name, "integrity")) {
370                         if (!strcasecmp(value, "file")) {
371                                 config->file_integrity = 1;
372                         } else if (!strcasecmp(value, "object")) {
373                                 config->file_integrity = 0;
374                         } else {
375                                 ast_log(LOG_ERROR, "Unsupported integrity value of '%s' used for configuration file '%s', defaulting to 'object'\n",
376                                         value, filename);
377                         }
378                 } else if (!strcasecmp(name, "criteria")) {
379                         char *field = strsep(&value, "=");
380                         struct ast_variable *criteria = ast_variable_new(field, value, "");
381
382                         if (criteria) {
383                                 criteria->next = config->criteria;
384                                 config->criteria = criteria;
385                         } else {
386                                 /* This is fatal since not following criteria would potentially yield invalid objects */
387                                 ast_log(LOG_ERROR, "Could not create criteria entry of field '%s' with value '%s' for configuration file '%s'\n",
388                                         field, value, filename);
389                                 ao2_ref(config, -1);
390                                 return NULL;
391                         }
392                 } else {
393                         ast_log(LOG_ERROR, "Unsupported option '%s' used for configuration file '%s'\n", name, filename);
394                 }
395         }
396
397         return config;
398 }
399
400 static void sorcery_config_close(void *data)
401 {
402         struct sorcery_config *config = data;
403
404         ao2_ref(config, -1);
405 }
406
407 static int load_module(void)
408 {
409         if (ast_sorcery_wizard_register(&config_object_wizard)) {
410                 return AST_MODULE_LOAD_DECLINE;
411         }
412
413         return AST_MODULE_LOAD_SUCCESS;
414 }
415
416 static int unload_module(void)
417 {
418         ast_sorcery_wizard_unregister(&config_object_wizard);
419         return 0;
420 }
421
422 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Sorcery Configuration File Object Wizard",
423         .support_level = AST_MODULE_SUPPORT_CORE,
424         .load = load_module,
425         .unload = unload_module,
426         .load_pri = AST_MODPRI_REALTIME_DRIVER,
427 );