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