root/lib/common/crmcommon_private.h

/* */

INCLUDED FROM

DEFINITIONS

1. pcmk__log_xmllib_err

   1 /*
   2  * Copyright 2018-2024 the Pacemaker project contributors
   3  *
   4  * The version control history for this file may have further details.
   5  *
   6  * This source code is licensed under the GNU Lesser General Public License
   7  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
   8  */
   9 
  10 #ifndef CRMCOMMON_PRIVATE__H
  11 #  define CRMCOMMON_PRIVATE__H
  12 
  13 /* This header is for the sole use of libcrmcommon, so that functions can be
  14  * declared with G_GNUC_INTERNAL for efficiency.
  15  */
  16 
  17 #include <stdint.h>         // uint8_t, uint32_t
  18 #include <stdbool.h>        // bool
  19 #include <sys/types.h>      // size_t
  20 #include <glib.h>           // gchar, GList
  21 #include <libxml/tree.h>    // xmlNode, xmlAttr
  22 #include <qb/qbipcc.h>      // struct qb_ipc_response_header
  23 
  24 // Decent chunk size for processing large amounts of data
  25 #define PCMK__BUFFER_SIZE 4096
  26 
  27 #if defined(PCMK__UNIT_TESTING)
  28 #undef G_GNUC_INTERNAL
  29 #define G_GNUC_INTERNAL
  30 #endif
  31 
  32 /* When deleting portions of an XML tree, we keep a record so we can know later
  33  * (e.g. when checking differences) that something was deleted.
  34  */
  35 typedef struct pcmk__deleted_xml_s {
  36     gchar *path;
  37     int position;
  38 } pcmk__deleted_xml_t;
  39 
  40 typedef struct xml_node_private_s {
  41         uint32_t check;
  42         uint32_t flags;
  43 } xml_node_private_t;
  44 
  45 typedef struct xml_doc_private_s {
  46         uint32_t check;
  47         uint32_t flags;
  48         char *user;
  49         GList *acls;
  50         GList *deleted_objs; // List of pcmk__deleted_xml_t
  51 } xml_doc_private_t;
  52 
  53 // XML entity references
  54 
  55 #define PCMK__XML_ENTITY_AMP    "&amp;"
  56 #define PCMK__XML_ENTITY_GT     "&gt;"
  57 #define PCMK__XML_ENTITY_LT     "&lt;"
  58 #define PCMK__XML_ENTITY_QUOT   "&quot;"
  59 
  60 //! libxml2 supports only XML version 1.0, at least as of libxml2-2.12.5
  61 #define PCMK__XML_VERSION ((pcmkXmlStr) "1.0")
  62 
  63 #define pcmk__set_xml_flags(xml_priv, flags_to_set) do {                    \
  64         (xml_priv)->flags = pcmk__set_flags_as(__func__, __LINE__,          \
  65             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  66             (flags_to_set), #flags_to_set);                                 \
  67     } while (0)
  68 
  69 #define pcmk__clear_xml_flags(xml_priv, flags_to_clear) do {                \
  70         (xml_priv)->flags = pcmk__clear_flags_as(__func__, __LINE__,        \
  71             LOG_NEVER, "XML", "XML node", (xml_priv)->flags,                \
  72             (flags_to_clear), #flags_to_clear);                             \
  73     } while (0)
  74 
  75 G_GNUC_INTERNAL
  76 bool pcmk__tracking_xml_changes(xmlNode *xml, bool lazy);
  77 
  78 G_GNUC_INTERNAL
  79 void pcmk__xml_mark_created(xmlNode *xml);
  80 
  81 G_GNUC_INTERNAL
  82 int pcmk__xml_position(const xmlNode *xml,
  83                        enum xml_private_flags ignore_if_set);
  84 
  85 G_GNUC_INTERNAL
  86 xmlNode *pcmk__xml_match(const xmlNode *haystack, const xmlNode *needle,
  87                          bool exact);
  88 
  89 G_GNUC_INTERNAL
  90 void pcmk__xml_update(xmlNode *parent, xmlNode *target, xmlNode *update,
  91                       uint32_t flags, bool as_diff);
  92 
  93 G_GNUC_INTERNAL
  94 xmlNode *pcmk__xc_match(const xmlNode *root, const xmlNode *search_comment,
  95                         bool exact);
  96 
  97 G_GNUC_INTERNAL
  98 void pcmk__xc_update(xmlNode *parent, xmlNode *target, xmlNode *update);
  99 
 100 G_GNUC_INTERNAL
 101 void pcmk__free_acls(GList *acls);
 102 
 103 G_GNUC_INTERNAL
 104 void pcmk__unpack_acl(xmlNode *source, xmlNode *target, const char *user);
 105 
 106 G_GNUC_INTERNAL
 107 bool pcmk__is_user_in_group(const char *user, const char *group);
 108 
 109 G_GNUC_INTERNAL
 110 void pcmk__apply_acl(xmlNode *xml);
 111 
 112 G_GNUC_INTERNAL
 113 void pcmk__apply_creation_acl(xmlNode *xml, bool check_top);
 114 
 115 G_GNUC_INTERNAL
 116 void pcmk__mark_xml_attr_dirty(xmlAttr *a);
 117 
 118 G_GNUC_INTERNAL
 119 bool pcmk__xa_filterable(const char *name);
 120 
 121 G_GNUC_INTERNAL
 122 void pcmk__log_xmllib_err(void *ctx, const char *fmt, ...)
     /*  */
 123 G_GNUC_PRINTF(2, 3);
 124 
 125 G_GNUC_INTERNAL
 126 void pcmk__mark_xml_node_dirty(xmlNode *xml);
 127 
 128 G_GNUC_INTERNAL
 129 bool pcmk__marked_as_deleted(xmlAttrPtr a, void *user_data);
 130 
 131 G_GNUC_INTERNAL
 132 void pcmk__dump_xml_attr(const xmlAttr *attr, GString *buffer);
 133 
 134 G_GNUC_INTERNAL
 135 int pcmk__xe_set_score(xmlNode *target, const char *name, const char *value);
 136 
 137 /*
 138  * Date/times
 139  */
 140 
 141 // For use with pcmk__add_time_from_xml()
 142 enum pcmk__time_component {
 143     pcmk__time_unknown,
 144     pcmk__time_years,
 145     pcmk__time_months,
 146     pcmk__time_weeks,
 147     pcmk__time_days,
 148     pcmk__time_hours,
 149     pcmk__time_minutes,
 150     pcmk__time_seconds,
 151 };
 152 
 153 G_GNUC_INTERNAL
 154 const char *pcmk__time_component_attr(enum pcmk__time_component component);
 155 
 156 G_GNUC_INTERNAL
 157 int pcmk__add_time_from_xml(crm_time_t *t, enum pcmk__time_component component,
 158                             const xmlNode *xml);
 159 
 160 G_GNUC_INTERNAL
 161 void pcmk__set_time_if_earlier(crm_time_t *target, const crm_time_t *source);
 162 
 163 
 164 /*
 165  * IPC
 166  */
 167 
 168 #define PCMK__IPC_VERSION 1
 169 
 170 #define PCMK__CONTROLD_API_MAJOR "1"
 171 #define PCMK__CONTROLD_API_MINOR "0"
 172 
 173 // IPC behavior that varies by daemon
 174 typedef struct pcmk__ipc_methods_s {
 175     /*!
 176      * \internal
 177      * \brief Allocate any private data needed by daemon IPC
 178      *
 179      * \param[in,out] api  IPC API connection
 180      *
 181      * \return Standard Pacemaker return code
 182      */
 183     int (*new_data)(pcmk_ipc_api_t *api);
 184 
 185     /*!
 186      * \internal
 187      * \brief Free any private data used by daemon IPC
 188      *
 189      * \param[in,out] api_data  Data allocated by new_data() method
 190      */
 191     void (*free_data)(void *api_data);
 192 
 193     /*!
 194      * \internal
 195      * \brief Perform daemon-specific handling after successful connection
 196      *
 197      * Some daemons require clients to register before sending any other
 198      * commands. The controller requires a CRM_OP_HELLO (with no reply), and
 199      * the CIB manager, executor, and fencer require a CRM_OP_REGISTER (with a
 200      * reply). Ideally this would be consistent across all daemons, but for now
 201      * this allows each to do its own authorization.
 202      *
 203      * \param[in,out] api  IPC API connection
 204      *
 205      * \return Standard Pacemaker return code
 206      */
 207     int (*post_connect)(pcmk_ipc_api_t *api);
 208 
 209     /*!
 210      * \internal
 211      * \brief Check whether an IPC request results in a reply
 212      *
 213      * \param[in,out] api      IPC API connection
 214      * \param[in]     request  IPC request XML
 215      *
 216      * \return true if request would result in an IPC reply, false otherwise
 217      */
 218     bool (*reply_expected)(pcmk_ipc_api_t *api, const xmlNode *request);
 219 
 220     /*!
 221      * \internal
 222      * \brief Perform daemon-specific handling of an IPC message
 223      *
 224      * \param[in,out] api  IPC API connection
 225      * \param[in,out] msg  Message read from IPC connection
 226      *
 227      * \return true if more IPC reply messages should be expected
 228      */
 229     bool (*dispatch)(pcmk_ipc_api_t *api, xmlNode *msg);
 230 
 231     /*!
 232      * \internal
 233      * \brief Perform daemon-specific handling of an IPC disconnect
 234      *
 235      * \param[in,out] api  IPC API connection
 236      */
 237     void (*post_disconnect)(pcmk_ipc_api_t *api);
 238 } pcmk__ipc_methods_t;
 239 
 240 // Implementation of pcmk_ipc_api_t
 241 struct pcmk_ipc_api_s {
 242     enum pcmk_ipc_server server;          // Daemon this IPC API instance is for
 243     enum pcmk_ipc_dispatch dispatch_type; // How replies should be dispatched
 244     size_t ipc_size_max;                  // maximum IPC buffer size
 245     crm_ipc_t *ipc;                       // IPC connection
 246     mainloop_io_t *mainloop_io;     // If using mainloop, I/O source for IPC
 247     bool free_on_disconnect;        // Whether disconnect should free object
 248     pcmk_ipc_callback_t cb;         // Caller-registered callback (if any)
 249     void *user_data;                // Caller-registered data (if any)
 250     void *api_data;                 // For daemon-specific use
 251     pcmk__ipc_methods_t *cmds;      // Behavior that varies by daemon
 252 };
 253 
 254 typedef struct pcmk__ipc_header_s {
 255     struct qb_ipc_response_header qb;
 256     uint32_t size_uncompressed;
 257     uint32_t size_compressed;
 258     uint32_t flags;
 259     uint8_t version;
 260 } pcmk__ipc_header_t;
 261 
 262 G_GNUC_INTERNAL
 263 int pcmk__send_ipc_request(pcmk_ipc_api_t *api, const xmlNode *request);
 264 
 265 G_GNUC_INTERNAL
 266 void pcmk__call_ipc_callback(pcmk_ipc_api_t *api,
 267                              enum pcmk_ipc_event event_type,
 268                              crm_exit_t status, void *event_data);
 269 
 270 G_GNUC_INTERNAL
 271 unsigned int pcmk__ipc_buffer_size(unsigned int max);
 272 
 273 G_GNUC_INTERNAL
 274 bool pcmk__valid_ipc_header(const pcmk__ipc_header_t *header);
 275 
 276 G_GNUC_INTERNAL
 277 pcmk__ipc_methods_t *pcmk__attrd_api_methods(void);
 278 
 279 G_GNUC_INTERNAL
 280 pcmk__ipc_methods_t *pcmk__controld_api_methods(void);
 281 
 282 G_GNUC_INTERNAL
 283 pcmk__ipc_methods_t *pcmk__pacemakerd_api_methods(void);
 284 
 285 G_GNUC_INTERNAL
 286 pcmk__ipc_methods_t *pcmk__schedulerd_api_methods(void);
 287 
 288 
 289 /*
 290  * Logging
 291  */
 292 
 293 //! XML is newly created
 294 #define PCMK__XML_PREFIX_CREATED "++"
 295 
 296 //! XML has been deleted
 297 #define PCMK__XML_PREFIX_DELETED "--"
 298 
 299 //! XML has been modified
 300 #define PCMK__XML_PREFIX_MODIFIED "+ "
 301 
 302 //! XML has been moved
 303 #define PCMK__XML_PREFIX_MOVED "+~"
 304 
 305 /*
 306  * Output
 307  */
 308 G_GNUC_INTERNAL
 309 int pcmk__bare_output_new(pcmk__output_t **out, const char *fmt_name,
 310                           const char *filename, char **argv);
 311 
 312 G_GNUC_INTERNAL
 313 void pcmk__register_option_messages(pcmk__output_t *out);
 314 
 315 G_GNUC_INTERNAL
 316 void pcmk__register_patchset_messages(pcmk__output_t *out);
 317 
 318 G_GNUC_INTERNAL
 319 bool pcmk__output_text_get_fancy(pcmk__output_t *out);
 320 
 321 /*
 322  * Rules
 323  */
 324 
 325 // How node attribute values may be compared in rules
 326 enum pcmk__comparison {
 327     pcmk__comparison_unknown,
 328     pcmk__comparison_defined,
 329     pcmk__comparison_undefined,
 330     pcmk__comparison_eq,
 331     pcmk__comparison_ne,
 332     pcmk__comparison_lt,
 333     pcmk__comparison_lte,
 334     pcmk__comparison_gt,
 335     pcmk__comparison_gte,
 336 };
 337 
 338 // How node attribute values may be parsed in rules
 339 enum pcmk__type {
 340     pcmk__type_unknown,
 341     pcmk__type_string,
 342     pcmk__type_integer,
 343     pcmk__type_number,
 344     pcmk__type_version,
 345 };
 346 
 347 // Where to obtain reference value for a node attribute comparison
 348 enum pcmk__reference_source {
 349     pcmk__source_unknown,
 350     pcmk__source_literal,
 351     pcmk__source_instance_attrs,
 352     pcmk__source_meta_attrs,
 353 };
 354 
 355 G_GNUC_INTERNAL
 356 enum pcmk__comparison pcmk__parse_comparison(const char *op);
 357 
 358 G_GNUC_INTERNAL
 359 enum pcmk__type pcmk__parse_type(const char *type, enum pcmk__comparison op,
 360                                  const char *value1, const char *value2);
 361 
 362 G_GNUC_INTERNAL
 363 enum pcmk__reference_source pcmk__parse_source(const char *source);
 364 
 365 G_GNUC_INTERNAL
 366 int pcmk__cmp_by_type(const char *value1, const char *value2,
 367                       enum pcmk__type type);
 368 
 369 G_GNUC_INTERNAL
 370 int pcmk__unpack_duration(const xmlNode *duration, const crm_time_t *start,
 371                           crm_time_t **end);
 372 
 373 G_GNUC_INTERNAL
 374 int pcmk__evaluate_date_spec(const xmlNode *date_spec, const crm_time_t *now);
 375 
 376 G_GNUC_INTERNAL
 377 int pcmk__evaluate_attr_expression(const xmlNode *expression,
 378                                    const pcmk_rule_input_t *rule_input);
 379 
 380 G_GNUC_INTERNAL
 381 int pcmk__evaluate_rsc_expression(const xmlNode *expr,
 382                                   const pcmk_rule_input_t *rule_input);
 383 
 384 G_GNUC_INTERNAL
 385 int pcmk__evaluate_op_expression(const xmlNode *expr,
 386                                  const pcmk_rule_input_t *rule_input);
 387 
 388 
 389 /*
 390  * Utils
 391  */
 392 #define PCMK__PW_BUFFER_LEN 500
 393 
 394 
 395 /*
 396  * Schemas
 397  */
 398 typedef struct {
 399     unsigned char v[2];
 400 } pcmk__schema_version_t;
 401 
 402 enum pcmk__schema_validator {
 403     pcmk__schema_validator_none,
 404     pcmk__schema_validator_rng
 405 };
 406 
 407 typedef struct {
 408     int schema_index;
 409     char *name;
 410     char *transform;
 411     void *cache;
 412     enum pcmk__schema_validator validator;
 413     pcmk__schema_version_t version;
 414     char *transform_enter;
 415     bool transform_onleave;
 416 } pcmk__schema_t;
 417 
 418 G_GNUC_INTERNAL
 419 GList *pcmk__find_x_0_schema(void);
 420 
 421 
 422 #endif  // CRMCOMMON_PRIVATE__H

/* */