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_metric_store_t;
 129
 130 /*
 131  * sdb_store_metric_t represents the meta-data of a stored metric object.
 132  */
 133 typedef struct {
 134         const char *hostname;
 135         const char *name;
 136         sdb_metric_store_t store;
 137
 138         sdb_time_t last_update;
 139         sdb_time_t interval;
 140         const char * const *backends;
 141         size_t backends_num;
 142 } sdb_store_metric_t;
 143 #define SDB_STORE_METRIC_INIT { NULL, NULL, { NULL, NULL }, 0, 0, NULL, 0 }
 144
 145 /*
 146  * sdb_store_attribute_t represents a stored attribute.
 147  */
 148 typedef struct {
 149         const char *hostname; /* optional */
 150         int parent_type;
 151         const char *parent;
 152         const char *key;
 153         sdb_data_t value;
 154
 155         sdb_time_t last_update;
 156         sdb_time_t interval;
 157         const char * const *backends;
 158         size_t backends_num;
 159 } sdb_store_attribute_t;
 160 #define SDB_STORE_ATTRIBUTE_INIT { NULL, 0, NULL, NULL, SDB_DATA_INIT, 0, 0, NULL, 0 }
 161
 162 /*
 163  * A JSON formatter converts stored objects into the JSON format.
 164  * See http://www.ietf.org/rfc/rfc4627.txt
 165  *
 166  * A JSON formatter object inherits from sdb_object_t and, thus, may safely be
 167  * cast to a generic object.
 168  */
 169 struct sdb_store_json_formatter;
 170 typedef struct sdb_store_json_formatter sdb_store_json_formatter_t;
 171
 172 /*
 173  * A store writer describes the interface for plugins implementing a store.
 174  *
 175  * Any of the call-back functions shall return:
 176  *  - 0 on success
 177  *  - a positive value if the new entry is older than the currently stored
 178  *    entry (in this case, no update will happen)
 179  *  - a negative value on error
 180  */
 181 typedef struct {
 182         /*
 183          * store_host:
 184          * Add/update a host in the store. If the host, identified by its
 185          * canonicalized name, already exists, it will be updated according to the
 186          * specified name and timestamp. Else, a new entry will be created in the
 187          * store.
 188          */
 189         int (*store_host)(sdb_store_host_t *host, sdb_object_t *user_data);
 190
 191         /*
 192          * store_service:
 193          * Add/update a service in the store. If the service, identified by its
 194          * name, already exists for the specified host, it will be updated
 195          * according to the specified name and timestamp. If the referenced host
 196          * does not exist, an error will be reported. Else, a new entry will be
 197          * created in the store.
 198          */
 199         int (*store_service)(sdb_store_service_t *service, sdb_object_t *user_data);
 200
 201         /*
 202          * store_metric:
 203          * Add/update a metric in the store. If the metric, identified by its
 204          * name, already exists for the specified host, it will be updated
 205          * according to the specified attributes. If the referenced host does not
 206          * exist, an error will be reported. Else, a new entry will be created in
 207          * the store.
 208          */
 209         int (*store_metric)(sdb_store_metric_t *metric, sdb_object_t *user_data);
 210
 211         /*
 212          * store_attribute:
 213          * Add/update a host's attribute in the store. If the attribute,
 214          * identified by its key, already exists for the specified host, it will
 215          * be updated to the specified values. If the referenced host does not
 216          * exist, an error will be reported. Else, a new entry will be created in
 217          * the store.
 218          */
 219         int (*store_attribute)(sdb_store_attribute_t *attr, sdb_object_t *user_data);
 220 } sdb_store_writer_t;
 221
 222 /*
 223  * A store reader describes the interface to query a store implementation.
 224  */
 225 typedef struct {
 226         /*
 227          * prepare_query:
 228          * Prepare the query described by 'ast' for execution.
 229          */
 230         sdb_object_t *(*prepare_query)(sdb_ast_node_t *ast,
 231                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 232
 233         /*
 234          * execute_query:
 235          * Execute a previously prepared query. The callback may expect that only
 236          * queries prepared by its respective prepare callback will be passed to
 237          * this function. The query result will be passed back via the specified
 238          * store writer.
 239          */
 240         int (*execute_query)(sdb_object_t *q,
 241                         sdb_store_writer_t *w, sdb_object_t *wd,
 242                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 243 } sdb_store_reader_t;
 244
 245 /*
 246  * Flags for JSON formatting.
 247  */
 248 enum {
 249         SDB_WANT_ARRAY = 1 << 0,
 250 };
 251
 252 /*
 253  * sdb_store_json_formatter:
 254  * Create a JSON formatter for the specified object types writing to the
 255  * specified buffer.
 256  */
 257 sdb_store_json_formatter_t *
 258 sdb_store_json_formatter(sdb_strbuf_t *buf, int type, int flags);
 259
 260 /*
 261  * sdb_store_json_finish:
 262  * Finish the JSON output. This function has to be called once after emiting
 263  * all objects.
 264  */
 265 int
 266 sdb_store_json_finish(sdb_store_json_formatter_t *f);
 267
 268 /*
 269  * sdb_store_json_writer:
 270  * A store writer implementation that generates JSON output. It expects a
 271  * store JSON formatter as its user-data argument.
 272  */
 273 extern sdb_store_writer_t sdb_store_json_writer;
 274
 275 #ifdef __cplusplus
 276 } /* extern "C" */
 277 #endif
 278
 279 #endif /* ! SDB_CORE_STORE_H */
 280
 281 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 282