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