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 private data magic numbers
  54 #define PCMK__XML_DOC_PRIVATE_MAGIC     0x81726354UL
  55 #define PCMK__XML_NODE_PRIVATE_MAGIC    0x54637281UL
  56 
  57 // XML entity references
  58 #define PCMK__XML_ENTITY_AMP    "&amp;"
  59 #define PCMK__XML_ENTITY_GT     "&gt;"
  60 #define PCMK__XML_ENTITY_LT     "&lt;"
  61 #define PCMK__XML_ENTITY_QUOT   "&quot;"
  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 void pcmk__xml_set_parent_flags(xmlNode *xml, uint64_t flags);
  77 
  78 G_GNUC_INTERNAL
  79 void pcmk__xml_new_private_data(xmlNode *xml);
  80 
  81 G_GNUC_INTERNAL
  82 void pcmk__xml_free_private_data(xmlNode *xml);
  83 
  84 G_GNUC_INTERNAL
  85 xmlDoc *pcmk__xml_new_doc(void);
  86 
  87 G_GNUC_INTERNAL
  88 bool pcmk__tracking_xml_changes(xmlNode *xml, bool lazy);
  89 
  90 G_GNUC_INTERNAL
  91 int pcmk__xml_position(const xmlNode *xml,
  92                        enum xml_private_flags ignore_if_set);
  93 
  94 G_GNUC_INTERNAL
  95 xmlNode *pcmk__xml_match(const xmlNode *haystack, const xmlNode *needle,
  96                          bool exact);
  97 
  98 G_GNUC_INTERNAL
  99 void pcmk__xml_update(xmlNode *parent, xmlNode *target, xmlNode *update,
 100                       uint32_t flags, bool as_diff);
 101 
 102 G_GNUC_INTERNAL
 103 xmlNode *pcmk__xc_match(const xmlNode *root, const xmlNode *search_comment,
 104                         bool exact);
 105 
 106 G_GNUC_INTERNAL
 107 void pcmk__xc_update(xmlNode *parent, xmlNode *target, xmlNode *update);
 108 
 109 G_GNUC_INTERNAL
 110 void pcmk__free_acls(GList *acls);
 111 
 112 G_GNUC_INTERNAL
 113 void pcmk__unpack_acl(xmlNode *source, xmlNode *target, const char *user);
 114 
 115 G_GNUC_INTERNAL
 116 bool pcmk__is_user_in_group(const char *user, const char *group);
 117 
 118 G_GNUC_INTERNAL
 119 void pcmk__apply_acl(xmlNode *xml);
 120 
 121 G_GNUC_INTERNAL
 122 void pcmk__apply_creation_acl(xmlNode *xml, bool check_top);
 123 
 124 G_GNUC_INTERNAL
 125 xmlAttr *pcmk__xe_set_attr_force(xmlNode *node, const char *name,
 126                                  const char *value);
 127 
 128 G_GNUC_INTERNAL
 129 int pcmk__xa_remove(xmlAttr *attr, bool force);
 130 
 131 G_GNUC_INTERNAL
 132 void pcmk__mark_xml_attr_dirty(xmlAttr *a);
 133 
 134 G_GNUC_INTERNAL
 135 bool pcmk__xa_filterable(const char *name);
 136 
 137 G_GNUC_INTERNAL
 138 void pcmk__log_xmllib_err(void *ctx, const char *fmt, ...)
     /*  */
 139 G_GNUC_PRINTF(2, 3);
 140 
 141 G_GNUC_INTERNAL
 142 void pcmk__mark_xml_node_dirty(xmlNode *xml);
 143 
 144 G_GNUC_INTERNAL
 145 bool pcmk__marked_as_deleted(xmlAttrPtr a, void *user_data);
 146 
 147 G_GNUC_INTERNAL
 148 void pcmk__dump_xml_attr(const xmlAttr *attr, GString *buffer);
 149 
 150 G_GNUC_INTERNAL
 151 int pcmk__xe_set_score(xmlNode *target, const char *name, const char *value);
 152 
 153 /*
 154  * Date/times
 155  */
 156 
 157 // For use with pcmk__add_time_from_xml()
 158 enum pcmk__time_component {
 159     pcmk__time_unknown,
 160     pcmk__time_years,
 161     pcmk__time_months,
 162     pcmk__time_weeks,
 163     pcmk__time_days,
 164     pcmk__time_hours,
 165     pcmk__time_minutes,
 166     pcmk__time_seconds,
 167 };
 168 
 169 G_GNUC_INTERNAL
 170 const char *pcmk__time_component_attr(enum pcmk__time_component component);
 171 
 172 G_GNUC_INTERNAL
 173 int pcmk__add_time_from_xml(crm_time_t *t, enum pcmk__time_component component,
 174                             const xmlNode *xml);
 175 
 176 G_GNUC_INTERNAL
 177 void pcmk__set_time_if_earlier(crm_time_t *target, const crm_time_t *source);
 178 
 179 
 180 /*
 181  * IPC
 182  */
 183 
 184 #define PCMK__IPC_VERSION 1
 185 
 186 #define PCMK__CONTROLD_API_MAJOR "1"
 187 #define PCMK__CONTROLD_API_MINOR "0"
 188 
 189 // IPC behavior that varies by daemon
 190 typedef struct pcmk__ipc_methods_s {
 191     /*!
 192      * \internal
 193      * \brief Allocate any private data needed by daemon IPC
 194      *
 195      * \param[in,out] api  IPC API connection
 196      *
 197      * \return Standard Pacemaker return code
 198      */
 199     int (*new_data)(pcmk_ipc_api_t *api);
 200 
 201     /*!
 202      * \internal
 203      * \brief Free any private data used by daemon IPC
 204      *
 205      * \param[in,out] api_data  Data allocated by new_data() method
 206      */
 207     void (*free_data)(void *api_data);
 208 
 209     /*!
 210      * \internal
 211      * \brief Perform daemon-specific handling after successful connection
 212      *
 213      * Some daemons require clients to register before sending any other
 214      * commands. The controller requires a CRM_OP_HELLO (with no reply), and
 215      * the CIB manager, executor, and fencer require a CRM_OP_REGISTER (with a
 216      * reply). Ideally this would be consistent across all daemons, but for now
 217      * this allows each to do its own authorization.
 218      *
 219      * \param[in,out] api  IPC API connection
 220      *
 221      * \return Standard Pacemaker return code
 222      */
 223     int (*post_connect)(pcmk_ipc_api_t *api);
 224 
 225     /*!
 226      * \internal
 227      * \brief Check whether an IPC request results in a reply
 228      *
 229      * \param[in,out] api      IPC API connection
 230      * \param[in]     request  IPC request XML
 231      *
 232      * \return true if request would result in an IPC reply, false otherwise
 233      */
 234     bool (*reply_expected)(pcmk_ipc_api_t *api, const xmlNode *request);
 235 
 236     /*!
 237      * \internal
 238      * \brief Perform daemon-specific handling of an IPC message
 239      *
 240      * \param[in,out] api  IPC API connection
 241      * \param[in,out] msg  Message read from IPC connection
 242      *
 243      * \return true if more IPC reply messages should be expected
 244      */
 245     bool (*dispatch)(pcmk_ipc_api_t *api, xmlNode *msg);
 246 
 247     /*!
 248      * \internal
 249      * \brief Perform daemon-specific handling of an IPC disconnect
 250      *
 251      * \param[in,out] api  IPC API connection
 252      */
 253     void (*post_disconnect)(pcmk_ipc_api_t *api);
 254 } pcmk__ipc_methods_t;
 255 
 256 // Implementation of pcmk_ipc_api_t
 257 struct pcmk_ipc_api_s {
 258     enum pcmk_ipc_server server;          // Daemon this IPC API instance is for
 259     enum pcmk_ipc_dispatch dispatch_type; // How replies should be dispatched
 260     size_t ipc_size_max;                  // maximum IPC buffer size
 261     crm_ipc_t *ipc;                       // IPC connection
 262     mainloop_io_t *mainloop_io;     // If using mainloop, I/O source for IPC
 263     bool free_on_disconnect;        // Whether disconnect should free object
 264     pcmk_ipc_callback_t cb;         // Caller-registered callback (if any)
 265     void *user_data;                // Caller-registered data (if any)
 266     void *api_data;                 // For daemon-specific use
 267     pcmk__ipc_methods_t *cmds;      // Behavior that varies by daemon
 268 };
 269 
 270 typedef struct pcmk__ipc_header_s {
 271     struct qb_ipc_response_header qb;
 272     uint32_t size_uncompressed;
 273     uint32_t size_compressed;
 274     uint32_t flags;
 275     uint8_t version;
 276 } pcmk__ipc_header_t;
 277 
 278 G_GNUC_INTERNAL
 279 int pcmk__send_ipc_request(pcmk_ipc_api_t *api, const xmlNode *request);
 280 
 281 G_GNUC_INTERNAL
 282 void pcmk__call_ipc_callback(pcmk_ipc_api_t *api,
 283                              enum pcmk_ipc_event event_type,
 284                              crm_exit_t status, void *event_data);
 285 
 286 G_GNUC_INTERNAL
 287 unsigned int pcmk__ipc_buffer_size(unsigned int max);
 288 
 289 G_GNUC_INTERNAL
 290 bool pcmk__valid_ipc_header(const pcmk__ipc_header_t *header);
 291 
 292 G_GNUC_INTERNAL
 293 pcmk__ipc_methods_t *pcmk__attrd_api_methods(void);
 294 
 295 G_GNUC_INTERNAL
 296 pcmk__ipc_methods_t *pcmk__controld_api_methods(void);
 297 
 298 G_GNUC_INTERNAL
 299 pcmk__ipc_methods_t *pcmk__pacemakerd_api_methods(void);
 300 
 301 G_GNUC_INTERNAL
 302 pcmk__ipc_methods_t *pcmk__schedulerd_api_methods(void);
 303 
 304 
 305 /*
 306  * Logging
 307  */
 308 
 309 //! XML is newly created
 310 #define PCMK__XML_PREFIX_CREATED "++"
 311 
 312 //! XML has been deleted
 313 #define PCMK__XML_PREFIX_DELETED "--"
 314 
 315 //! XML has been modified
 316 #define PCMK__XML_PREFIX_MODIFIED "+ "
 317 
 318 //! XML has been moved
 319 #define PCMK__XML_PREFIX_MOVED "+~"
 320 
 321 /*
 322  * Output
 323  */
 324 G_GNUC_INTERNAL
 325 int pcmk__bare_output_new(pcmk__output_t **out, const char *fmt_name,
 326                           const char *filename, char **argv);
 327 
 328 G_GNUC_INTERNAL
 329 void pcmk__register_option_messages(pcmk__output_t *out);
 330 
 331 G_GNUC_INTERNAL
 332 void pcmk__register_patchset_messages(pcmk__output_t *out);
 333 
 334 G_GNUC_INTERNAL
 335 bool pcmk__output_text_get_fancy(pcmk__output_t *out);
 336 
 337 /*
 338  * Rules
 339  */
 340 
 341 // How node attribute values may be compared in rules
 342 enum pcmk__comparison {
 343     pcmk__comparison_unknown,
 344     pcmk__comparison_defined,
 345     pcmk__comparison_undefined,
 346     pcmk__comparison_eq,
 347     pcmk__comparison_ne,
 348     pcmk__comparison_lt,
 349     pcmk__comparison_lte,
 350     pcmk__comparison_gt,
 351     pcmk__comparison_gte,
 352 };
 353 
 354 // How node attribute values may be parsed in rules
 355 enum pcmk__type {
 356     pcmk__type_unknown,
 357     pcmk__type_string,
 358     pcmk__type_integer,
 359     pcmk__type_number,
 360     pcmk__type_version,
 361 };
 362 
 363 // Where to obtain reference value for a node attribute comparison
 364 enum pcmk__reference_source {
 365     pcmk__source_unknown,
 366     pcmk__source_literal,
 367     pcmk__source_instance_attrs,
 368     pcmk__source_meta_attrs,
 369 };
 370 
 371 G_GNUC_INTERNAL
 372 enum pcmk__comparison pcmk__parse_comparison(const char *op);
 373 
 374 G_GNUC_INTERNAL
 375 enum pcmk__type pcmk__parse_type(const char *type, enum pcmk__comparison op,
 376                                  const char *value1, const char *value2);
 377 
 378 G_GNUC_INTERNAL
 379 enum pcmk__reference_source pcmk__parse_source(const char *source);
 380 
 381 G_GNUC_INTERNAL
 382 int pcmk__cmp_by_type(const char *value1, const char *value2,
 383                       enum pcmk__type type);
 384 
 385 G_GNUC_INTERNAL
 386 int pcmk__unpack_duration(const xmlNode *duration, const crm_time_t *start,
 387                           crm_time_t **end);
 388 
 389 G_GNUC_INTERNAL
 390 int pcmk__evaluate_date_spec(const xmlNode *date_spec, const crm_time_t *now);
 391 
 392 G_GNUC_INTERNAL
 393 int pcmk__evaluate_attr_expression(const xmlNode *expression,
 394                                    const pcmk_rule_input_t *rule_input);
 395 
 396 G_GNUC_INTERNAL
 397 int pcmk__evaluate_rsc_expression(const xmlNode *expr,
 398                                   const pcmk_rule_input_t *rule_input);
 399 
 400 G_GNUC_INTERNAL
 401 int pcmk__evaluate_op_expression(const xmlNode *expr,
 402                                  const pcmk_rule_input_t *rule_input);
 403 
 404 
 405 /*
 406  * Utils
 407  */
 408 #define PCMK__PW_BUFFER_LEN 500
 409 
 410 
 411 /*
 412  * Schemas
 413  */
 414 typedef struct {
 415     unsigned char v[2];
 416 } pcmk__schema_version_t;
 417 
 418 enum pcmk__schema_validator {
 419     pcmk__schema_validator_none,
 420     pcmk__schema_validator_rng
 421 };
 422 
 423 typedef struct {
 424     int schema_index;
 425     char *name;
 426     char *transform;
 427     void *cache;
 428     enum pcmk__schema_validator validator;
 429     pcmk__schema_version_t version;
 430     char *transform_enter;
 431     bool transform_onleave;
 432 } pcmk__schema_t;
 433 
 434 G_GNUC_INTERNAL
 435 GList *pcmk__find_x_0_schema(void);
 436 
 437 
 438 #endif  // CRMCOMMON_PRIVATE__H

/* */