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 "core/timeseries.h"
  36 #include "parser/ast.h"
  37 #include "utils/strbuf.h"
  38
  39 #include <stdio.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /*
  46  * Store object types.
  47  */
  48 enum {
  49         SDB_HOST = 1,
  50         SDB_SERVICE,
  51         SDB_METRIC,
  52
  53         SDB_ATTRIBUTE = 1 << 4,
  54
  55         /*
  56          * Queryable fields of a stored object.
  57          */
  58         SDB_FIELD_NAME = 1 << 8, /* type: string */
  59         SDB_FIELD_LAST_UPDATE,   /* type: datetime */
  60         SDB_FIELD_AGE,           /* type: datetime */
  61         SDB_FIELD_INTERVAL,      /* type: datetime */
  62         SDB_FIELD_BACKEND,       /* type: array of strings */
  63         SDB_FIELD_VALUE,         /* attributes only;  type: type of the value */
  64         SDB_FIELD_TIMESERIES,    /* metrics only;  type: boolean */
  65 };
  66 #define SDB_STORE_TYPE_TO_NAME(t) \
  67         (((t) == SDB_HOST) ? "host" \
  68                 : ((t) == SDB_SERVICE) ? "service" \
  69                 : ((t) == SDB_METRIC) ? "metric" \
  70                 : ((t) == SDB_ATTRIBUTE) ? "attribute" \
  71                 : ((t) == (SDB_ATTRIBUTE | SDB_HOST)) ? "host attribute" \
  72                 : ((t) == (SDB_ATTRIBUTE | SDB_SERVICE)) ? "service attribute" \
  73                 : ((t) == (SDB_ATTRIBUTE | SDB_METRIC)) ? "metric attribute" \
  74                 : "unknown")
  75
  76 #define SDB_FIELD_TO_NAME(f) \
  77         (((f) == SDB_FIELD_NAME) ? "name" \
  78                 : ((f) == SDB_FIELD_LAST_UPDATE) ? "last-update" \
  79                 : ((f) == SDB_FIELD_AGE) ? "age" \
  80                 : ((f) == SDB_FIELD_INTERVAL) ? "interval" \
  81                 : ((f) == SDB_FIELD_BACKEND) ? "backend" \
  82                 : ((f) == SDB_FIELD_VALUE) ? "value" \
  83                 : ((f) == SDB_FIELD_TIMESERIES) ? "timeseries" \
  84                 : "unknown")
  85
  86 #define SDB_FIELD_TYPE(f) \
  87         (((f) == SDB_FIELD_NAME) ? SDB_TYPE_STRING \
  88                 : ((f) == SDB_FIELD_LAST_UPDATE) ? SDB_TYPE_DATETIME \
  89                 : ((f) == SDB_FIELD_AGE) ? SDB_TYPE_DATETIME \
  90                 : ((f) == SDB_FIELD_INTERVAL) ? SDB_TYPE_DATETIME \
  91                 : ((f) == SDB_FIELD_BACKEND) ? (SDB_TYPE_ARRAY | SDB_TYPE_STRING) \
  92                 : ((f) == SDB_FIELD_VALUE) ? -1 /* unknown */ \
  93                 : ((f) == SDB_FIELD_TIMESERIES) ? SDB_TYPE_BOOLEAN \
  94                 : -1)
  95
  96 /*
  97  * sdb_store_host_t represents the meta-data of a stored host object.
  98  */
  99 typedef struct {
 100         const char *name;
 101
 102         sdb_time_t last_update;
 103         sdb_time_t interval;
 104         const char * const *backends;
 105         size_t backends_num;
 106 } sdb_store_host_t;
 107 #define SDB_STORE_HOST_INIT { NULL, 0, 0, NULL, 0 }
 108
 109 /*
 110  * sdb_store_service_t represents the meta-data of a stored service object.
 111  */
 112 typedef struct {
 113         const char *hostname;
 114         const char *name;
 115
 116         sdb_time_t last_update;
 117         sdb_time_t interval;
 118         const char * const *backends;
 119         size_t backends_num;
 120 } sdb_store_service_t;
 121 #define SDB_STORE_SERVICE_INIT { NULL, NULL, 0, 0, NULL, 0 }
 122
 123 /*
 124  * sdb_metric_store_t specifies how to access a metric's data.
 125  */
 126 typedef struct {
 127         const char *type;
 128         const char *id;
 129         const sdb_timeseries_info_t *info;
 130         sdb_time_t last_update;
 131 } sdb_metric_store_t;
 132
 133 /*
 134  * sdb_store_metric_t represents the meta-data of a stored metric object.
 135  */
 136 typedef struct {
 137         const char *hostname;
 138         const char *name;
 139
 140         /* All data stores providing this metric. */
 141         const sdb_metric_store_t *stores;
 142         size_t stores_num;
 143
 144         sdb_time_t last_update;
 145         sdb_time_t interval;
 146         const char * const *backends;
 147         size_t backends_num;
 148 } sdb_store_metric_t;
 149 #define SDB_STORE_METRIC_INIT { NULL, NULL, NULL, 0, 0, 0, NULL, 0 }
 150
 151 /*
 152  * sdb_store_attribute_t represents a stored attribute.
 153  */
 154 typedef struct {
 155         const char *hostname; /* optional */
 156         int parent_type;
 157         const char *parent;
 158         const char *key;
 159         sdb_data_t value;
 160
 161         sdb_time_t last_update;
 162         sdb_time_t interval;
 163         const char * const *backends;
 164         size_t backends_num;
 165 } sdb_store_attribute_t;
 166 #define SDB_STORE_ATTRIBUTE_INIT { NULL, 0, NULL, NULL, SDB_DATA_INIT, 0, 0, NULL, 0 }
 167
 168 /*
 169  * A JSON formatter converts stored objects into the JSON format.
 170  * See http://www.ietf.org/rfc/rfc4627.txt
 171  *
 172  * A JSON formatter object inherits from sdb_object_t and, thus, may safely be
 173  * cast to a generic object.
 174  */
 175 struct sdb_store_json_formatter;
 176 typedef struct sdb_store_json_formatter sdb_store_json_formatter_t;
 177
 178 /*
 179  * A store writer describes the interface for plugins implementing a store.
 180  *
 181  * Any of the call-back functions shall return:
 182  *  - 0 on success
 183  *  - a positive value if the new entry is older than the currently stored
 184  *    entry (in this case, no update will happen)
 185  *  - a negative value on error
 186  */
 187 typedef struct {
 188         /*
 189          * store_host:
 190          * Add/update a host in the store. If the host, identified by its
 191          * canonicalized name, already exists, it will be updated according to the
 192          * specified name and timestamp. Else, a new entry will be created in the
 193          * store.
 194          */
 195         int (*store_host)(sdb_store_host_t *host, sdb_object_t *user_data);
 196
 197         /*
 198          * store_service:
 199          * Add/update a service in the store. If the service, identified by its
 200          * name, already exists for the specified host, it will be updated
 201          * according to the specified name and timestamp. If the referenced host
 202          * does not exist, an error will be reported. Else, a new entry will be
 203          * created in the store.
 204          */
 205         int (*store_service)(sdb_store_service_t *service, sdb_object_t *user_data);
 206
 207         /*
 208          * store_metric:
 209          * Add/update a metric in the store. If the metric, identified by its
 210          * name, already exists for the specified host, it will be updated
 211          * according to the specified attributes. If the referenced host does not
 212          * exist, an error will be reported. Else, a new entry will be created in
 213          * the store.
 214          */
 215         int (*store_metric)(sdb_store_metric_t *metric, sdb_object_t *user_data);
 216
 217         /*
 218          * store_attribute:
 219          * Add/update a host's attribute in the store. If the attribute,
 220          * identified by its key, already exists for the specified host, it will
 221          * be updated to the specified values. If the referenced host does not
 222          * exist, an error will be reported. Else, a new entry will be created in
 223          * the store.
 224          */
 225         int (*store_attribute)(sdb_store_attribute_t *attr, sdb_object_t *user_data);
 226 } sdb_store_writer_t;
 227
 228 /*
 229  * A store reader describes the interface to query a store implementation.
 230  */
 231 typedef struct {
 232         /*
 233          * prepare_query:
 234          * Prepare the query described by 'ast' for execution.
 235          */
 236         sdb_object_t *(*prepare_query)(sdb_ast_node_t *ast,
 237                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 238
 239         /*
 240          * execute_query:
 241          * Execute a previously prepared query. The callback may expect that only
 242          * queries prepared by its respective prepare callback will be passed to
 243          * this function. The query result will be passed back via the specified
 244          * store writer.
 245          */
 246         int (*execute_query)(sdb_object_t *q,
 247                         sdb_store_writer_t *w, sdb_object_t *wd,
 248                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 249 } sdb_store_reader_t;
 250
 251 /*
 252  * Flags for JSON formatting.
 253  */
 254 enum {
 255         SDB_WANT_ARRAY = 1 << 0,
 256 };
 257
 258 /*
 259  * sdb_store_json_formatter:
 260  * Create a JSON formatter for the specified object types writing to the
 261  * specified buffer.
 262  */
 263 sdb_store_json_formatter_t *
 264 sdb_store_json_formatter(sdb_strbuf_t *buf, int type, int flags);
 265
 266 /*
 267  * sdb_store_json_finish:
 268  * Finish the JSON output. This function has to be called once after emiting
 269  * all objects.
 270  */
 271 int
 272 sdb_store_json_finish(sdb_store_json_formatter_t *f);
 273
 274 /*
 275  * sdb_store_json_writer:
 276  * A store writer implementation that generates JSON output. It expects a
 277  * store JSON formatter as its user-data argument.
 278  */
 279 extern sdb_store_writer_t sdb_store_json_writer;
 280
 281 #ifdef __cplusplus
 282 } /* extern "C" */
 283 #endif
 284
 285 #endif /* ! SDB_CORE_STORE_H */
 286
 287 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 288