src/include/core/store.h

   1 /*
   2  * SysDB - src/include/core/store.h
   3  * Copyright (C) 2012-2015 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_CORE_STORE_H
  29 #define SDB_CORE_STORE_H 1
  30
  31 #include "sysdb.h"
  32 #include "core/object.h"
  33 #include "core/data.h"
  34 #include "core/time.h"
  35 #include "parser/ast.h"
  36 #include "utils/strbuf.h"
  37
  38 #include <stdio.h>
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /*
  45  * Store object types.
  46  */
  47 enum {
  48         SDB_HOST = 1,
  49         SDB_SERVICE,
  50         SDB_METRIC,
  51
  52         SDB_ATTRIBUTE = 1 << 4,
  53
  54         /*
  55          * Queryable fields of a stored object.
  56          */
  57         SDB_FIELD_NAME = 1 << 8, /* type: string */
  58         SDB_FIELD_LAST_UPDATE,   /* type: datetime */
  59         SDB_FIELD_AGE,           /* type: datetime */
  60         SDB_FIELD_INTERVAL,      /* type: datetime */
  61         SDB_FIELD_BACKEND,       /* type: array of strings */
  62         SDB_FIELD_VALUE,         /* attributes only;  type: type of the value */
  63         SDB_FIELD_TIMESERIES,    /* metrics only;  type: boolean */
  64 };
  65 #define SDB_STORE_TYPE_TO_NAME(t) \
  66         (((t) == SDB_HOST) ? "host" \
  67                 : ((t) == SDB_SERVICE) ? "service" \
  68                 : ((t) == SDB_METRIC) ? "metric" \
  69                 : ((t) == SDB_ATTRIBUTE) ? "attribute" \
  70                 : ((t) == (SDB_ATTRIBUTE | SDB_HOST)) ? "host attribute" \
  71                 : ((t) == (SDB_ATTRIBUTE | SDB_SERVICE)) ? "service attribute" \
  72                 : ((t) == (SDB_ATTRIBUTE | SDB_METRIC)) ? "metric attribute" \
  73                 : "unknown")
  74
  75 #define SDB_FIELD_TO_NAME(f) \
  76         (((f) == SDB_FIELD_NAME) ? "name" \
  77                 : ((f) == SDB_FIELD_LAST_UPDATE) ? "last-update" \
  78                 : ((f) == SDB_FIELD_AGE) ? "age" \
  79                 : ((f) == SDB_FIELD_INTERVAL) ? "interval" \
  80                 : ((f) == SDB_FIELD_BACKEND) ? "backend" \
  81                 : ((f) == SDB_FIELD_VALUE) ? "value" \
  82                 : ((f) == SDB_FIELD_TIMESERIES) ? "timeseries" \
  83                 : "unknown")
  84
  85 #define SDB_FIELD_TYPE(f) \
  86         (((f) == SDB_FIELD_NAME) ? SDB_TYPE_STRING \
  87                 : ((f) == SDB_FIELD_LAST_UPDATE) ? SDB_TYPE_DATETIME \
  88                 : ((f) == SDB_FIELD_AGE) ? SDB_TYPE_DATETIME \
  89                 : ((f) == SDB_FIELD_INTERVAL) ? SDB_TYPE_DATETIME \
  90                 : ((f) == SDB_FIELD_BACKEND) ? (SDB_TYPE_ARRAY | SDB_TYPE_STRING) \
  91                 : ((f) == SDB_FIELD_VALUE) ? -1 /* unknown */ \
  92                 : ((f) == SDB_FIELD_TIMESERIES) ? SDB_TYPE_BOOLEAN \
  93                 : -1)
  94
  95 /*
  96  * sdb_store_host_t represents the meta-data of a stored host object.
  97  */
  98 typedef struct {
  99         const char *name;
 100
 101         sdb_time_t last_update;
 102         sdb_time_t interval;
 103         const char * const *backends;
 104         size_t backends_num;
 105 } sdb_store_host_t;
 106 #define SDB_STORE_HOST_INIT { NULL, 0, 0, NULL, 0 }
 107
 108 /*
 109  * sdb_store_service_t represents the meta-data of a stored service object.
 110  */
 111 typedef struct {
 112         const char *hostname;
 113         const char *name;
 114
 115         sdb_time_t last_update;
 116         sdb_time_t interval;
 117         const char * const *backends;
 118         size_t backends_num;
 119 } sdb_store_service_t;
 120 #define SDB_STORE_SERVICE_INIT { NULL, NULL, 0, 0, NULL, 0 }
 121
 122 /*
 123  * sdb_metric_store_t specifies how to access a metric's data.
 124  */
 125 typedef struct {
 126         const char *type;
 127         const char *id;
 128         sdb_time_t last_update;
 129 } sdb_metric_store_t;
 130
 131 /*
 132  * sdb_store_metric_t represents the meta-data of a stored metric object.
 133  */
 134 typedef struct {
 135         const char *hostname;
 136         const char *name;
 137         sdb_metric_store_t store;
 138
 139         sdb_time_t last_update;
 140         sdb_time_t interval;
 141         const char * const *backends;
 142         size_t backends_num;
 143 } sdb_store_metric_t;
 144 #define SDB_STORE_METRIC_INIT { NULL, NULL, { NULL, NULL, 0 }, 0, 0, NULL, 0 }
 145
 146 /*
 147  * sdb_store_attribute_t represents a stored attribute.
 148  */
 149 typedef struct {
 150         const char *hostname; /* optional */
 151         int parent_type;
 152         const char *parent;
 153         const char *key;
 154         sdb_data_t value;
 155
 156         sdb_time_t last_update;
 157         sdb_time_t interval;
 158         const char * const *backends;
 159         size_t backends_num;
 160 } sdb_store_attribute_t;
 161 #define SDB_STORE_ATTRIBUTE_INIT { NULL, 0, NULL, NULL, SDB_DATA_INIT, 0, 0, NULL, 0 }
 162
 163 /*
 164  * A JSON formatter converts stored objects into the JSON format.
 165  * See http://www.ietf.org/rfc/rfc4627.txt
 166  *
 167  * A JSON formatter object inherits from sdb_object_t and, thus, may safely be
 168  * cast to a generic object.
 169  */
 170 struct sdb_store_json_formatter;
 171 typedef struct sdb_store_json_formatter sdb_store_json_formatter_t;
 172
 173 /*
 174  * A store writer describes the interface for plugins implementing a store.
 175  *
 176  * Any of the call-back functions shall return:
 177  *  - 0 on success
 178  *  - a positive value if the new entry is older than the currently stored
 179  *    entry (in this case, no update will happen)
 180  *  - a negative value on error
 181  */
 182 typedef struct {
 183         /*
 184          * store_host:
 185          * Add/update a host in the store. If the host, identified by its
 186          * canonicalized name, already exists, it will be updated according to the
 187          * specified name and timestamp. Else, a new entry will be created in the
 188          * store.
 189          */
 190         int (*store_host)(sdb_store_host_t *host, sdb_object_t *user_data);
 191
 192         /*
 193          * store_service:
 194          * Add/update a service in the store. If the service, identified by its
 195          * name, already exists for the specified host, it will be updated
 196          * according to the specified name and timestamp. If the referenced host
 197          * does not exist, an error will be reported. Else, a new entry will be
 198          * created in the store.
 199          */
 200         int (*store_service)(sdb_store_service_t *service, sdb_object_t *user_data);
 201
 202         /*
 203          * store_metric:
 204          * Add/update a metric in the store. If the metric, identified by its
 205          * name, already exists for the specified host, it will be updated
 206          * according to the specified attributes. If the referenced host does not
 207          * exist, an error will be reported. Else, a new entry will be created in
 208          * the store.
 209          */
 210         int (*store_metric)(sdb_store_metric_t *metric, sdb_object_t *user_data);
 211
 212         /*
 213          * store_attribute:
 214          * Add/update a host's attribute in the store. If the attribute,
 215          * identified by its key, already exists for the specified host, it will
 216          * be updated to the specified values. If the referenced host does not
 217          * exist, an error will be reported. Else, a new entry will be created in
 218          * the store.
 219          */
 220         int (*store_attribute)(sdb_store_attribute_t *attr, sdb_object_t *user_data);
 221 } sdb_store_writer_t;
 222
 223 /*
 224  * A store reader describes the interface to query a store implementation.
 225  */
 226 typedef struct {
 227         /*
 228          * prepare_query:
 229          * Prepare the query described by 'ast' for execution.
 230          */
 231         sdb_object_t *(*prepare_query)(sdb_ast_node_t *ast,
 232                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 233
 234         /*
 235          * execute_query:
 236          * Execute a previously prepared query. The callback may expect that only
 237          * queries prepared by its respective prepare callback will be passed to
 238          * this function. The query result will be passed back via the specified
 239          * store writer.
 240          */
 241         int (*execute_query)(sdb_object_t *q,
 242                         sdb_store_writer_t *w, sdb_object_t *wd,
 243                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 244 } sdb_store_reader_t;
 245
 246 /*
 247  * Flags for JSON formatting.
 248  */
 249 enum {
 250         SDB_WANT_ARRAY = 1 << 0,
 251 };
 252
 253 /*
 254  * sdb_store_json_formatter:
 255  * Create a JSON formatter for the specified object types writing to the
 256  * specified buffer.
 257  */
 258 sdb_store_json_formatter_t *
 259 sdb_store_json_formatter(sdb_strbuf_t *buf, int type, int flags);
 260
 261 /*
 262  * sdb_store_json_finish:
 263  * Finish the JSON output. This function has to be called once after emiting
 264  * all objects.
 265  */
 266 int
 267 sdb_store_json_finish(sdb_store_json_formatter_t *f);
 268
 269 /*
 270  * sdb_store_json_writer:
 271  * A store writer implementation that generates JSON output. It expects a
 272  * store JSON formatter as its user-data argument.
 273  */
 274 extern sdb_store_writer_t sdb_store_json_writer;
 275
 276 #ifdef __cplusplus
 277 } /* extern "C" */
 278 #endif
 279
 280 #endif /* ! SDB_CORE_STORE_H */
 281
 282 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 283